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

​
Пріоритет (найвищий → найнижчий)

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

​
Облікові дані провайдерів і .env робочої області

Не зберігайте API-ключі провайдерів лише в .env робочої області. OpenClaw ігнорує змінні середовища облікових даних провайдерів із файлів .env робочої області, зокрема поширені ключі, як-от GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY і FIRECRAWL_API_KEY. Використовуйте одне з цих довірених джерел для облікових даних провайдерів:
  • Середовище процесу Gateway, наприклад оболонку, unit launchd/systemd, секрет контейнера або секрет CI.
  • Глобальний файл dotenv середовища виконання у ~/.openclaw/.env або $OPENCLAW_STATE_DIR/.env.
  • Блок env конфігурації у ~/.openclaw/openclaw.json.
  • Необов’язковий імпорт із login shell, коли ввімкнено env.shellEnv.enabled або OPENCLAW_LOAD_SHELL_ENV=1.
Якщо раніше ви зберігали ключі провайдерів лише в .env робочої області, перемістіть їх до одного з довірених джерел вище. .env робочої області все ще може надавати звичайні змінні проєкту, які не є обліковими даними, перенаправленнями endpoint, перевизначеннями host або елементами керування середовищем виконання OPENCLAW_*. Див. Файли .env робочої області для пояснення міркувань безпеки.

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

Два рівноцінні способи встановити inline-змінні середовища (обидва не перевизначають): 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}
Блок env конфігурації приймає лише буквальні рядкові значення. Він не розгортає значення file:...; наприклад, XAI_API_KEY: "file:secrets/xai-api-key.txt" передається провайдерам саме як цей рядок. Для ключів провайдерів, що зберігаються у файлах, використовуйте SecretRef у полі облікових даних, яке це підтримує: 
{
  secrets: {
    providers: {
      xai_key_file: {
        source: "file",
        path: "~/.openclaw/secrets/xai-api-key.txt",
        mode: "singleValue",
      },
    },
  },
  models: {
    providers: {
      xai: {
        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
      },
    },
  },
}
Див. Керування секретами і Поверхня облікових даних SecretRef щодо підтримуваних полів.

​
Імпорт середовища оболонки

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

​
Знімки exec-оболонки

На хостах Gateway не Windows команди bash і zsh exec типово використовують стартовий знімок. Установіть OPENCLAW_EXEC_SHELL_SNAPSHOT=0 у середовищі процесу Gateway, щоб вимкнути цей шлях. Значення false, no і off також його вимикають. Значення exec.env для окремого виклику не можуть перемикати знімки або перенаправляти кеш знімків.

​
Змінні середовища, ін’єктовані середовищем виконання

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

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

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

​
Підстановка змінних середовища в конфігурації

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

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

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

​
Змінні середовища, пов’язані зі шляхами

ЗміннаПризначення
OPENCLAW_HOMEПеревизначає домашній каталог, який використовується для внутрішніх типових шляхів OpenClaw (~/.openclaw/, каталоги агентів, сесії, облікові дані, installer onboarding і типовий dev checkout). Корисно під час запуску OpenClaw як окремого service user.
OPENCLAW_STATE_DIRПеревизначає каталог стану (типово ~/.openclaw).
OPENCLAW_CONFIG_PATHПеревизначає шлях до конфігураційного файлу (типово ~/.openclaw/openclaw.json).
OPENCLAW_INCLUDE_ROOTSСписок шляхів до каталогів, у яких директиви $include можуть розв’язувати файли поза каталогом конфігурації (типово: немає — $include обмежено каталогом конфігурації). З розгортанням тильди.

​
Журналювання

ЗміннаПризначення
OPENCLAW_LOG_LEVELПеревизначає рівень журналювання і для файлу, і для консолі (наприклад debug, trace). Має пріоритет над logging.level і logging.consoleLevel у конфігурації. Недійсні значення ігноруються з попередженням.
OPENCLAW_DEBUG_MODEL_TRANSPORTВиводить цільову діагностику таймінгів запиту/відповіді моделі на рівні info без увімкнення глобальних debug-логів.
OPENCLAW_DEBUG_MODEL_PAYLOADДіагностика payload моделі: summary, tools або full-redacted. full-redacted обмежується за розміром і редагується, але може містити текст prompt/повідомлення.
OPENCLAW_DEBUG_SSEДіагностика streaming: events для таймінгу first/done, peek для включення перших п’яти відредагованих подій SSE.
OPENCLAW_DEBUG_CODE_MODEДіагностика model-surface для code-mode, зокрема приховування provider-tool і забезпечення режиму лише exec/wait.

​
OPENCLAW_HOME

Коли встановлено, OPENCLAW_HOME замінює системний домашній каталог ($HOME / os.homedir()) для внутрішніх типових шляхів OpenClaw. Це охоплює типовий каталог стану, шлях конфігурації, каталоги агентів, облікові дані, робочу область installer onboarding і типовий dev checkout, який використовується openclaw update --channel dev. Пріоритет: OPENCLAW_HOME > $HOME > USERPROFILE > резервний home Termux PREFIX на Android > os.homedir() Приклад (macOS LaunchDaemon): 
<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>
OPENCLAW_HOME також можна встановити як шлях із тильдою (наприклад ~/svc), який перед використанням розгортається за тим самим ланцюжком резервного home ОС. Явні змінні шляхів, як-от OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH і OPENCLAW_GIT_DIR, все ще мають пріоритет. Завдання облікового запису ОС, як-от виявлення стартового файлу оболонки, налаштування package-manager і розгортання ~ на хості, все ще можуть використовувати справжній системний home.

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

Якщо Node.js було встановлено через nvm (а не системний package manager), вбудований fetch() використовує пакетне сховище CA від nvm, у якому можуть бути відсутні сучасні root 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 під час старту процесу.

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

OpenClaw читає лише змінні середовища OPENCLAW_*. Застарілі префікси CLAWDBOT_* і MOLTBOT_* із попередніх релізів мовчки ігноруються. Якщо якісь із них усе ще встановлено в процесі Gateway під час старту, OpenClaw виводить одне попередження про застарілість Node (OPENCLAW_LEGACY_ENV_VARS) зі списком виявлених префіксів і загальною кількістю. Перейменуйте кожне значення, замінивши застарілий префікс на OPENCLAW_ (наприклад CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); старі назви не мають жодного ефекту.

​
Пов’язане