Переменные окружения

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), а также все ключи, оканчивающиеся на _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.
• Необязательный импорт из login shell, когда включён 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 запускает вашу login shell и импортирует только отсутствующие ожидаемые ключи:

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

Эквивалентные переменные окружения:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (по умолчанию 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-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()

Пример (LaunchDaemon в macOS):

<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
• Обзор моделей