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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

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

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

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

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

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

​
Змінні середовища 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 задокументовано в Керуванні секретами.

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

ЗміннаПризначення
OPENCLAW_HOMEПеревизначити домашній каталог, що використовується для всього внутрішнього розв’язання шляхів (~/.openclaw/, каталоги агентів, сесії, облікові дані). Корисно під час запуску OpenClaw як окремого службового користувача.
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Діагностика корисного навантаження моделі: summary, tools або full-redacted. full-redacted обмежується й редагується, але може містити текст підказки/повідомлення.
OPENCLAW_DEBUG_SSEДіагностика потокової передачі: events для часу першої/завершальної події, peek для включення перших п’яти відредагованих подій SSE.
OPENCLAW_DEBUG_CODE_MODEДіагностика поверхні моделі в режимі коду, включно з приховуванням інструментів провайдера та примусовим дотриманням лише exec/wait.

​
OPENCLAW_HOME

Якщо встановлено, OPENCLAW_HOME замінює системний домашній каталог ($HOME / os.homedir()) для всього внутрішнього розв’язання шляхів. Це забезпечує повну ізоляцію файлової системи для безголових службових облікових записів. Пріоритетність: 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 під час запуску процесу.

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

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

​
Пов’язане