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

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

Приоритет (от высшего к низшему)

Окружение процесса (то, что процесс Gateway уже получил от родительской оболочки или демона).
.env в текущем рабочем каталоге (значение dotenv по умолчанию; не переопределяет существующие значения; учётные данные провайдеров и защищённые параметры управления средой выполнения игнорируются).
Глобальный .env по пути ~/.openclaw/.env (также известен как $OPENCLAW_STATE_DIR/.env; рекомендуется для API-ключей провайдеров; не переопределяет существующие значения).
Блок конфигурации env в ~/.openclaw/openclaw.json (применяется только при отсутствии значения).
Необязательный импорт из 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 по умолчанию (`~/.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):

<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.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); старые имена не действуют.

Start here

FAQ

Testing

Diagnostics

Community and meta

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

Приоритет (от высшего к низшему)

Учётные данные провайдеров и `.env` рабочей области

Блок конфигурации `env`

Импорт окружения оболочки

Снимки окружения команд оболочки Exec

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

Переменные окружения интерфейса

Подстановка переменных окружения в конфигурации

Ссылки на секреты и строки `${ENV}`

Переменные окружения, связанные с путями

Журналирование

`OPENCLAW_HOME`

Пользователи nvm: ошибки TLS в web_fetch

Устаревшие переменные окружения

Связанные материалы

​Приоритет (от высшего к низшему)

​Учётные данные провайдеров и .env рабочей области

​Блок конфигурации env

​Импорт окружения оболочки

​Снимки окружения команд оболочки Exec

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

​Переменные окружения интерфейса

​Подстановка переменных окружения в конфигурации

​Ссылки на секреты и строки ${ENV}

​Переменные окружения, связанные с путями

​Журналирование

​OPENCLAW_HOME

​Пользователи nvm: ошибки TLS в web_fetch

​Устаревшие переменные окружения

​Связанные материалы

Приоритет (от высшего к низшему)

Учётные данные провайдеров и `.env` рабочей области

Блок конфигурации `env`

Импорт окружения оболочки

Снимки окружения команд оболочки Exec

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

Переменные окружения интерфейса

Подстановка переменных окружения в конфигурации

Ссылки на секреты и строки `${ENV}`

Переменные окружения, связанные с путями

Журналирование

`OPENCLAW_HOME`

Пользователи nvm: ошибки TLS в web_fetch

Устаревшие переменные окружения

Связанные материалы