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

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_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.crtopenclaw 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); старі назви не мають жодного ефекту.

Пов’язане

• Конфігурація Gateway
• Поширені запитання: змінні середовища та завантаження .env
• Огляд моделей