Перейти к основному содержанию
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 по умолчанию (~/.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): 
<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.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); старые имена не имеют эффекта.

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