Перейти до основного вмісту

​
Змінні середовища

OpenClaw отримує змінні середовища з кількох джерел. Правило таке: ніколи не перевизначати наявні значення.

​
Пріоритет (від вищого до нижчого)

  1. Середовище процесу (те, що процес Gateway уже отримав від батьківської shell/daemon).
  2. .env у поточній робочій теці (типова поведінка dotenv; без перевизначення).
  3. Глобальний .env у ~/.openclaw/.env (або $OPENCLAW_STATE_DIR/.env; без перевизначення).
  4. Блок env у конфігурації в ~/.openclaw/openclaw.json (застосовується лише за відсутності значення).
  5. Необов’язковий імпорт login shell (env.shellEnv.enabled або OPENCLAW_LOAD_SHELL_ENV=1), застосовується лише для відсутніх очікуваних ключів.
На свіжих встановленнях Ubuntu, які використовують типову state dir, OpenClaw також розглядає ~/.config/openclaw/gateway.env як сумісний резервний варіант після глобального .env. Якщо обидва файли існують і відрізняються, OpenClaw зберігає значення з ~/.openclaw/.env і виводить попередження. Якщо файл конфігурації повністю відсутній, крок 4 пропускається; імпорт shell усе одно виконується, якщо його ввімкнено.

​
Блок env у конфігурації

Два рівнозначні способи задати вбудовані env vars (обидва не перевизначають наявні): 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​
Імпорт shell env

env.shellEnv запускає вашу login shell і імпортує лише відсутні очікувані ключі: 
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
Еквіваленти env vars:
  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

​
Env vars, інʼєктовані під час runtime

OpenClaw також інʼєктує маркери контексту в запущені дочірні процеси:
  • OPENCLAW_SHELL=exec: задається для команд, виконаних через інструмент exec.
  • OPENCLAW_SHELL=acp: задається для запусків процесів бекенда runtime ACP (наприклад acpx).
  • OPENCLAW_SHELL=acp-client: задається для openclaw acp client, коли він запускає bridge-процес ACP.
  • OPENCLAW_SHELL=tui-local: задається для локальних shell-команд ! у TUI.
Це маркери runtime (а не обов’язкова конфігурація користувача). Їх можна використовувати в логіці shell/profile для застосування правил, специфічних для контексту.

​
Env vars UI

  • OPENCLAW_THEME=light: примусово використовувати світлу палітру TUI, якщо ваш термінал має світле тло.
  • OPENCLAW_THEME=dark: примусово використовувати темну палітру TUI.
  • COLORFGBG: якщо ваш термінал експортує цю змінну, OpenClaw використовує підказку про колір тла, щоб автоматично вибрати палітру TUI.

​
Підстановка env vars у конфігурації

Ви можете посилатися на env vars безпосередньо в рядкових значеннях конфігурації за допомогою синтаксису ${VAR_NAME}: 
{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}
Повні деталі див. у Конфігурація: підстановка env vars.

​
Secret refs проти рядків ${ENV}

OpenClaw підтримує два підходи на основі env:
  • рядкову підстановку ${VAR} у значеннях конфігурації.
  • об’єкти SecretRef ({ source: "env", provider: "default", id: "VAR" }) для полів, які підтримують посилання на секрети.
Обидва варіанти визначаються з середовища процесу під час активації. Докладніше про SecretRef див. у Керування секретами.

​
Env vars, пов’язані зі шляхами

ЗміннаПризначення
OPENCLAW_HOMEПеревизначає домашній каталог, який використовується для всіх внутрішніх обчислень шляхів (~/.openclaw/, теки агентів, сесії, облікові дані). Корисно, коли OpenClaw працює від окремого сервісного користувача.
OPENCLAW_STATE_DIRПеревизначає state dir (типово ~/.openclaw).
OPENCLAW_CONFIG_PATHПеревизначає шлях до файлу конфігурації (типово ~/.openclaw/openclaw.json).

​
Логування

ЗміннаПризначення
OPENCLAW_LOG_LEVELПеревизначає рівень логування як для файлу, так і для консолі (наприклад debug, trace). Має пріоритет над logging.level і logging.consoleLevel у конфігурації. Недійсні значення ігноруються з попередженням.

​
OPENCLAW_HOME

Коли задано OPENCLAW_HOME, він замінює системний домашній каталог ($HOME / os.homedir()) для всіх внутрішніх обчислень шляхів. Це дає змогу повністю ізолювати файлову систему для headless сервісних облікових записів. Пріоритет: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir() Приклад (macOS LaunchDaemon): 
<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>
OPENCLAW_HOME також можна задати як шлях із тильдою (наприклад ~/svc), який перед використанням буде розгорнуто через $HOME.

​
Користувачі nvm: збої TLS у web_fetch

Якщо Node.js було встановлено через nvm (а не через системний менеджер пакетів), вбудований fetch() використовує сховище CA, яке постачається з nvm, і в ньому може бракувати сучасних кореневих CA (ISRG Root X1/X2 для Let’s Encrypt, DigiCert Global Root G2 тощо). Через це web_fetch завершується з "fetch failed" на більшості HTTPS-сайтів. У Linux OpenClaw автоматично виявляє nvm і застосовує виправлення в реальному середовищі запуску:
  • openclaw gateway install записує NODE_EXTRA_CA_CERTS у середовище сервісу systemd
  • точка входу CLI openclaw повторно запускає себе з NODE_EXTRA_CA_CERTS, заданою до старту Node
Ручне виправлення (для старіших версій або прямих запусків node ...): Експортуйте змінну перед запуском OpenClaw: 
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run
Не покладайтеся лише на запис цієї змінної в ~/.openclaw/.env; Node читає NODE_EXTRA_CA_CERTS під час старту процесу.

​
Пов’язане