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

· 3 мин чтения · admin

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

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

  • Process environment — то, что уже есть в shell/daemon
  • .env в текущей директории (dotenv, не перезаписывает)
  • Глобальный .env в ~/.openclaw/.env (не перезаписывает)
  • Config env block в ~/.openclaw/openclaw.json (только если отсутствует)
  • Shell env import (env.shellEnv.enabled), только для missing keys

    • На Ubuntu при дефолтном state dir OpenClaw также читает ~/.config/openclaw/gateway.env как fallback после глобального .env. Если оба существуют и расходятся — берёт ~/.openclaw/.env и пишет предупреждение.

    API-ключи

    Самый простой способ — через .env файл:

    
# ~/.openclaw/.env
OPENROUTER_API_KEY=sk-or-...
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk-...

    Или через config env block в openclaw.json:

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

    Оба варианта не перезаписывают уже существующие значения.

    Env var substitution в конфиге

    Можно ссылаться на переменные прямо в конфиге через ${VAR_NAME}:

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

    Переменные подставляются из process env при активации.

    Пути

    Переменная Назначение
    OPENCLAW_HOME Переопределить домашнюю директорию для всех внутренних путей. Полезно для service-аккаунтов
    OPENCLAW_STATE_DIR Переопределить state dir (по умолчанию ~/.openclaw)
    OPENCLAW_CONFIG_PATH Переопределить путь к конфигу (по умолчанию ~/.openclaw/openclaw.json)

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

    OPENCLAW_HOME можно указать с тильдой (~/svc) — раскрывается через $HOME.

    Логирование

    Переменная Назначение
    OPENCLAW_LOG_LEVEL Уровень логов (debug, trace). Приоритет над logging.level в конфиге

    Shell env import

    OpenClaw может импортировать переменные из login shell (только missing keys):

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

    Или через переменную: OPENCLAW_LOAD_SHELL_ENV=1

    UI переменные

    Переменная Назначение
    OPENCLAW_THEME=light Светлая тема TUI
    OPENCLAW_THEME=dark Тёмная тема TUI
    COLORFGBG Автоопределение темы терминала

    Runtime markers

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

    Значение `OPENCLAW_SHELL` Контекст
    exec Команды через exec tool
    acp ACP runtime spawns
    acp-client openclaw acp client
    tui-local Локальные ! команды в TUI

    Можно использовать в shell/profile логике для контекстных правил.

    nvm и TLS ошибки

    Если Node.js установлен через nvm (не системный пакетный менеджер), встроенный fetch() использует nvm CA store, в котором могут отсутствовать современные корневые сертификаты. Это ломает web_fetch на большинстве HTTPS сайтов.

    Автоматически (Linux): OpenClaw определяет nvm и применяет фикс:

  • openclaw gateway install пишет NODE_EXTRA_CA_CERTS в systemd environment
  • CLI entrypoint делает re-exec с NODE_EXTRA_CA_CERTS

    • Вручную (старые версии или прямой node запуск):

    
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run

    ⚠️ Не полагайтесь только на ~/.openclaw/.env для этой переменной — Node читает NODE_EXTRA_CA_CERTS при старте процесса.

    SecretRef vs `${ENV}`

    Два паттерна для env-зависимых значений:

  • ${VAR} — строковая подстановка в конфиге
  • SecretRef — { "source": "env", "provider": "default", "id": "VAR" } для полей, которые поддерживают secrets references

    • Оба разрешаются из process env. SecretRef подробно: Управление секретами.

    Что дальше

  • Конфигурация Gateway — настройки сервера
  • FAQ и решение проблем — диагностика
  • Установка OpenClaw — инструкции