English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Diagnostics

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

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

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

  1. Середовище процесу (те, що процес Gateway уже має від батьківської оболонки/демона).
  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, які використовують типовий каталог стану, OpenClaw також розглядає ~/.config/openclaw/gateway.env як резервний варіант сумісності після глобального .env. Якщо обидва файли існують і відрізняються, OpenClaw зберігає ~/.openclaw/.env і виводить попередження.

Якщо файл конфігурації повністю відсутній, крок 4 пропускається; імпорт із оболонки все одно виконується, якщо його ввімкнено.

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

Два еквівалентні способи задати вбудовані змінні середовища (обидва не перевизначають наявні значення):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

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

env.shellEnv запускає вашу login shell і імпортує лише відсутні очікувані ключі:

{
  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 runtime (наприклад acpx).
  • OPENCLAW_SHELL=acp-client: задається для openclaw acp client, коли він породжує процес моста ACP.
  • OPENCLAW_SHELL=tui-local: задається для локальних команд оболонки TUI !.

Це маркери часу виконання (не обов’язкова користувацька конфігурація). Їх можна використовувати в логіці 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}",
      },
    },
  },
}

Повні відомості див. у розділі Конфігурація: підстановка змінних середовища.

Посилання на секрети порівняно з рядками ${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_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 під час старту процесу.

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

OpenClaw читає лише змінні середовища OPENCLAW_*. Застарілі префікси CLAWDBOT_* і MOLTBOT_* з попередніх випусків мовчки ігноруються.

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

Пов’язане