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

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

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

Окружение процесса (что процесс Gateway уже имеет от родительской оболочки/демона).
.env в текущем рабочем каталоге (поведение dotenv по умолчанию; не перезаписывает).
Глобальный .env в ~/.openclaw/.env (он же $OPENCLAW_STATE_DIR/.env; не перезаписывает).
Блок env в конфигурации в ~/.openclaw/openclaw.json (применяется только при отсутствии).
Необязательный импорт login-оболочки (env.shellEnv.enabled или OPENCLAW_LOAD_SHELL_ENV=1), применяется только для недостающих ожидаемых ключей.

Если файл конфигурации полностью отсутствует, шаг 4 пропускается; импорт оболочки всё равно выполняется, если включён.

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

Два эквивалентных способа задать переменные окружения inline (оба не перезаписывают):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Импорт env из оболочки

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

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

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

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

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

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

OPENCLAW_SHELL=exec: устанавливается для команд, выполняемых через инструмент exec.
OPENCLAW_SHELL=acp: устанавливается для порождения процессов ACP-бэкенда (например, acpx).
OPENCLAW_SHELL=acp-client: устанавливается для openclaw acp client при порождении процесса ACP-моста.
OPENCLAW_SHELL=tui-local: устанавливается для локальных команд оболочки ! TUI.

Это маркеры времени выполнения (не обязательная пользовательская конфигурация). Их можно использовать в логике оболочки/профиля для применения контекстно-зависимых правил.

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

OPENCLAW_THEME=light: принудительно использовать светлую палитру TUI, когда ваш терминал имеет светлый фон.
OPENCLAW_THEME=dark: принудительно использовать тёмную палитру TUI.
COLORFGBG: если ваш терминал экспортирует это значение, OpenClaw использует подсказку о цвете фона для автоматического выбора палитры TUI.

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

Вы можете ссылаться на переменные окружения непосредственно в строковых значениях конфигурации, используя синтаксис ${VAR_NAME}:

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

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

SecretRef vs строки `${ENV}`

OpenClaw поддерживает два паттерна, основанных на переменных окружения:

Подстановка строк ${VAR} в значениях конфигурации.
Объекты SecretRef ({ source: "env", provider: "default", id: "VAR" }) для полей, поддерживающих ссылки на секреты.

Оба разрешаются из окружения процесса в момент активации. Подробности SecretRef описаны в Управление секретами.

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

Переменная	Назначение
`OPENCLAW_HOME`	Переопределить домашний каталог, используемый для всего внутреннего разрешения путей (`~/.openclaw/`, каталоги агентов, сессии, учётные данные). Полезно при запуске OpenClaw от имени выделенного сервисного пользователя.
`OPENCLAW_STATE_DIR`	Переопределить каталог состояния (по умолчанию `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Переопределить путь к файлу конфигурации (по умолчанию `~/.openclaw/openclaw.json`).

Логирование

Переменная	Назначение
`OPENCLAW_LOG_LEVEL`	Переопределить уровень логирования для файла и консоли (например, `debug`, `trace`). Имеет приоритет над `logging.level` и `logging.consoleLevel` в конфигурации. Недопустимые значения игнорируются с предупреждением.

`OPENCLAW_HOME`

При установке OPENCLAW_HOME заменяет системный домашний каталог ($HOME / os.homedir()) для всего внутреннего разрешения путей. Это обеспечивает полную изоляцию файловой системы для headless сервисных учётных записей.

Приоритет: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Пример (macOS LaunchDaemon):

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

OPENCLAW_HOME также может быть задан как путь с тильдой (например, ~/svc), который расширяется с помощью $HOME перед использованием.