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

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

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

1. Середовище процесу (те, що процес Gateway уже отримав від батьківської оболонки або служби).
2. .env у поточному робочому каталозі (типова поведінка dotenv; не перевизначає; облікові дані провайдерів і захищені параметри керування середовищем виконання ігноруються).
3. Глобальний .env за шляхом ~/.openclaw/.env (також $OPENCLAW_STATE_DIR/.env; рекомендовано для ключів API провайдерів; не перевизначає).
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 робочого простору

Не зберігайте ключі 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), а також усі ключі із закінченням _API_HOST, _BASE_URL або _HOMESERVER і цілі простори імен OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* та OPENAI_API_KEY_*.

Натомість використовуйте для облікових даних провайдерів одне з таких довірених джерел:

• Середовище процесу Gateway, наприклад оболонку, модуль launchd/systemd, секрет контейнера або секрет CI.
• Глобальний файл dotenv середовища виконання за шляхом ~/.openclaw/.env або $OPENCLAW_STATE_DIR/.env.
• Блок env конфігурації у ~/.openclaw/openclaw.json.
• Необов’язковий імпорт з оболонки входу, коли ввімкнено env.shellEnv.enabled або OPENCLAW_LOAD_SHELL_ENV=1.

Якщо раніше ви зберігали ключі провайдерів лише у файлі .env робочого простору, перенесіть їх до одного з наведених вище довірених джерел. Файл .env робочого простору й надалі може надавати звичайні змінні проєкту, які не є обліковими даними, переспрямуваннями кінцевих точок, перевизначеннями хостів або параметрами керування середовищем виконання OPENCLAW_*.

Обґрунтування з погляду безпеки див. у розділі Файли .env робочого простору.

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

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

{  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 запускає вашу оболонку входу й імпортує лише відсутні очікувані ключі:

{  env: {    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

Еквівалентні змінні середовища:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (типове значення — 15000)

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

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

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

OpenClaw також додає маркери контексту до породжених дочірніх процесів:

• OPENCLAW_SHELL=exec: установлюється для команд, запущених через інструмент exec.
• OPENCLAW_SHELL=acp-client: установлюється для openclaw acp client, коли він породжує процес мосту ACP.
• OPENCLAW_SHELL=tui-local: установлюється для локальних команд оболонки TUI !.
• OPENCLAW_CLI=1: установлюється для дочірніх процесів, породжених точкою входу CLI.

Це маркери середовища виконання (вони не є обов’язковою конфігурацією користувача). Їх можна використовувати в логіці оболонки або профілю, щоб застосовувати правила для певного контексту.

Змінні середовища інтерфейсу користувача

• 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 наведено в розділі Керування секретами. Сам блок env конфігурації не розпізнає SecretRef або скорочені значення file:....

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

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

OPENCLAW_HOME

Якщо встановлено OPENCLAW_HOME, він замінює системний домашній каталог ($HOME / os.homedir()) для внутрішніх типових шляхів OpenClaw. Це охоплює типовий каталог стану, шлях конфігурації, каталоги агентів, облікові дані, робочий простір початкового налаштування інсталятора та типовий каталог розробницького клонування, який використовує openclaw update --channel dev.

Пріоритетність: OPENCLAW_HOME > $HOME > USERPROFILE > резервний домашній каталог Termux PREFIX на Android > os.homedir()

Приклад (macOS LaunchDaemon):

<key>EnvironmentVariables</key><dict>  <key>OPENCLAW_HOME</key>  <string>/Users/user</string></dict>

Для OPENCLAW_HOME також можна задати шлях із тильдою (наприклад, ~/svc), який перед використанням розгортається за допомогою того самого ланцюжка резервного визначення домашнього каталогу ОС.

Явні змінні шляхів, як-от OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH і OPENCLAW_GIT_DIR, усе одно мають пріоритет. Завдання, пов’язані з обліковим записом ОС, як-от виявлення файлу запуску оболонки, налаштування менеджера пакетів і розгортання ~ хоста, можуть і надалі використовувати справжній системний домашній каталог.

Користувачі nvm: помилки TLS у web_fetch

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