> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Переменные окружения 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` рабочей области](/ru/gateway/security#workspace-env-files), где описано обоснование безопасности. ## Блок `env` конфигурации Два эквивалентных способа задать встроенные переменные окружения (оба не переопределяют существующие значения): ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, }, } ``` Блок `env` конфигурации принимает только литеральные строковые значения. Он не раскрывает значения `file:...`; например, `XAI_API_KEY: "file:secrets/xai-api-key.txt"` передается провайдерам именно как эта строка. Для ключей провайдеров, хранящихся в файлах, используйте SecretRef в поле учетных данных, которое это поддерживает: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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" }, }, }, }, } ``` См. [Управление секретами](/ru/gateway/secrets) и [поверхность учетных данных SecretRef](/ru/reference/secretref-credential-surface), где перечислены поддерживаемые поля. ## Импорт env из оболочки `env.shellEnv` запускает вашу login shell и импортирует только **отсутствующие** ожидаемые ключи: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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}`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { models: { providers: { "vercel-gateway": { apiKey: "${VERCEL_GATEWAY_API_KEY}", }, }, }, } ``` Подробности см. в [Конфигурация: подстановка переменных окружения](/ru/gateway/configuration-reference#env-var-substitution). ## Secret refs и строки `${ENV}` OpenClaw поддерживает два шаблона на основе переменных окружения: * Строковая подстановка `${VAR}` в значениях конфигурации. * Объекты SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) для полей, поддерживающих ссылки на секреты. Оба разрешаются из окружения процесса во время активации. Подробности SecretRef документированы в [Управление секретами](/ru/gateway/secrets). Сам блок `env` конфигурации не разрешает SecretRefs или сокращенные значения `file:...`. ## Переменные окружения, связанные с путями | Переменная | Назначение | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_HOME` | Переопределяет домашний каталог, используемый для внутренних путей OpenClaw по умолчанию (`~/.openclaw/`, каталоги агентов, сеансы, учетные данные, установочное подключение и dev checkout по умолчанию). Полезно при запуске OpenClaw от имени выделенного сервисного пользователя. | | `OPENCLAW_STATE_DIR` | Переопределяет каталог состояния (по умолчанию `~/.openclaw`). | | `OPENCLAW_CONFIG_PATH` | Переопределяет путь к файлу конфигурации (по умолчанию `~/.openclaw/openclaw.json`). | | `OPENCLAW_INCLUDE_ROOTS` | Список путей к каталогам, где директивы `$include` могут разрешать файлы за пределами каталога конфигурации (по умолчанию: нет — `$include` ограничен каталогом конфигурации). С раскрытием тильды. | ## Журналирование | Переменная | Назначение | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OPENCLAW_LOG_LEVEL` | Переопределяет уровень логирования и для файла, и для консоли (например, `debug`, `trace`). Имеет приоритет над `logging.level` и `logging.consoleLevel` в конфигурации. Недопустимые значения игнорируются с предупреждением. | | `OPENCLAW_DEBUG_MODEL_TRANSPORT` | Выводит целевые диагностические данные времени запросов/ответов модели на уровне `info` без включения глобальных debug-логов. | | `OPENCLAW_DEBUG_MODEL_PAYLOAD` | Диагностика payload модели: `summary`, `tools` или `full-redacted`. `full-redacted` ограничивается по объему и редактируется, но может включать текст prompt/сообщений. | | `OPENCLAW_DEBUG_SSE` | Диагностика потоковой передачи: `events` для времени первого/завершающего события, `peek` для включения первых пяти отредактированных событий SSE. | | `OPENCLAW_DEBUG_CODE_MODE` | Диагностика model-surface для code mode, включая скрытие provider-tool и принудительное соблюдение только exec/wait. | ### `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): ```xml theme={"theme":{"light":"min-light","dark":"min-dark"}} EnvironmentVariables OPENCLAW_HOME /Users/user ``` `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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt openclaw 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](/ru/gateway/configuration) * [FAQ: переменные окружения и загрузка .env](/ru/help/faq#env-vars-and-env-loading) * [Обзор моделей](/ru/concepts/models)