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

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, например оболочку, модуль launchd/systemd, секрет контейнера или секрет CI.
• Глобальный runtime-файл dotenv в ~/.openclaw/.env или $OPENCLAW_STATE_DIR/.env.
• Блок env конфигурации в ~/.openclaw/openclaw.json.
• Необязательный импорт из login-shell, когда включен env.shellEnv.enabled или OPENCLAW_LOAD_SHELL_ENV=1.

Если раньше вы хранили ключи провайдеров только в .env рабочей области, перенесите их в один из доверенных источников выше. .env рабочей области по-прежнему может предоставлять обычные переменные проекта, которые не являются учетными данными, перенаправлениями конечных точек, переопределениями хоста или runtime-элементами управления 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 из оболочки

env.shellEnv запускает вашу login shell и импортирует только отсутствующие ожидаемые ключи:

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

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

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Снимки exec shell

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

Переменные окружения, внедряемые во время выполнения

OpenClaw также внедряет маркеры контекста в запускаемые дочерние процессы:

• OPENCLAW_SHELL=exec: задается для команд, выполняемых через инструмент exec.
• OPENCLAW_SHELL=acp: задается для запусков процессов backend ACP runtime (например, acpx).
• OPENCLAW_SHELL=acp-client: задается для openclaw acp client, когда он запускает процесс моста ACP.
• OPENCLAW_SHELL=tui-local: задается для локальных shell-команд TUI !.
• OPENCLAW_CLI=1: задается для дочерних процессов, запускаемых точкой входа CLI.

Это runtime-маркеры (не обязательная пользовательская конфигурация). Их можно использовать в логике 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 по умолчанию. Сюда входят каталог состояния по умолчанию, путь конфигурации, каталоги агентов, учетные данные, рабочая область установочного подключения и dev checkout по умолчанию, используемый 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 хранилище CA, в котором могут отсутствовать современные корневые 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
• Обзор моделей