--- read_when: - Вам нужно знать, какие переменные окружения загружаются и в каком порядке - Вы отлаживаете отсутствие ключей API в Gateway - Вы документируете аутентификацию провайдера или среды развертывания summary: Откуда OpenClaw загружает переменные окружения и порядок их приоритета title: Переменные окружения x-i18n: generated_at: "2026-07-13T18:11:14Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: e0010465008969ea1ebf7bb79d01ee86b7be20f7b6d0d90da72d8b0a3b1ed273 source_path: help/environment.md workflow: 16 --- 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` рабочей области](/ru/gateway/security#workspace-env-files). ## Блок конфигурации `env` Есть два равноценных способа задать встроенные переменные окружения (ни один из них не переопределяет существующие значения): ```json5 { env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-...", }, }, } ``` Блок конфигурации `env` принимает только строковые литералы. Он не раскрывает значения `file:...`; например, `XAI_API_KEY: "file:secrets/xai-api-key.txt"` передаётся провайдерам именно как эта строка. Для ключей провайдеров, хранящихся в файлах, используйте SecretRef в поле учётных данных, которое его поддерживает: ```json5 { 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.shellEnv` запускает вашу login shell и импортирует только **отсутствующие** ожидаемые ключи: ```json5 { 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}`: ```json5 { models: { providers: { "vercel-gateway": { apiKey: "${VERCEL_GATEWAY_API_KEY}", }, }, }, } ``` Полные сведения см. в разделе [Конфигурация: подстановка переменных окружения](/ru/gateway/configuration-reference#env-var-substitution). ## Ссылки на секреты и строки `${ENV}` OpenClaw поддерживает два шаблона, использующих окружение: - Подстановка строк `${VAR}` в значениях конфигурации. - Объекты SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) для полей, поддерживающих ссылки на секреты. Оба варианта разрешаются из окружения процесса во время активации. Подробности о SecretRef приведены в разделе [Управление секретами](/ru/gateway/secrets). Сам блок конфигурации `env` не разрешает SecretRef или сокращённые значения `file:...`. ## Переменные окружения, связанные с путями | Переменная | Назначение | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPENCLAW_HOME` | Переопределяет домашний каталог, используемый для внутренних путей OpenClaw по умолчанию (`~/.openclaw/`, каталоги агентов, сеансы, учётные данные, рабочая область первоначальной настройки установщика и каталог разработки по умолчанию). Полезно при запуске 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` без включения глобальных отладочных журналов. | | `OPENCLAW_DEBUG_MODEL_PAYLOAD` | Диагностика полезной нагрузки модели: `summary`, `tools` или `full-redacted`. `full-redacted` ограничивается по объёму и редактируется, но может содержать текст подсказок или сообщений. | | `OPENCLAW_DEBUG_SSE` | Диагностика потоковой передачи: `events` для времени первого события и завершения, `peek` — для включения первых пяти отредактированных событий SSE. | | `OPENCLAW_DEBUG_CODE_MODE` | Диагностика поверхности модели в режиме кода, включая сокрытие инструментов провайдера и компактное прямое принудительное управление. | ### `OPENCLAW_HOME` Если задана переменная `OPENCLAW_HOME`, она заменяет системный домашний каталог (`$HOME` / `os.homedir()`) для внутренних путей OpenClaw по умолчанию. К ним относятся каталог состояния по умолчанию, путь к конфигурации, каталоги агентов, учётные данные, рабочая область первоначальной настройки установщика и каталог разработки по умолчанию, используемый `openclaw update --channel dev`. **Приоритет:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > резервный домашний каталог Termux `PREFIX` на Android > `os.homedir()` **Пример** (LaunchDaemon в macOS): ```xml 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, в котором могут отсутствовать современные корневые сертификаты (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 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) - [Часто задаваемые вопросы: переменные среды и загрузка .env](/ru/help/faq#env-vars-and-env-loading) - [Обзор моделей](/ru/concepts/models)