Перейти к основному содержимому

Окружение и отладка

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

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

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

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

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

Блок env в конфиге​

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

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

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

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

{
  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.

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

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

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

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

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

Ссылки на секреты 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()) для всех внутренних операций с путями. Это позволяет обеспечить полную изоляцию файловой системы для учётных записей служб без графического интерфейса. Приоритет: 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 перед использованием.

Связанные разделы​

История OpenClawОтладка