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

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_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.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
• FAQ: змінні середовища та завантаження .env
• Огляд моделей