Справочник по интерфейсу командной строки и конфигурационным файлам OpenClaw: полное руководство

Настройка OpenClaw осуществляется исключительно через один JSON5-файл ~/.openclaw/openclaw.json и интерфейс командной строки, содержащий более 100 подкоманд. Ни один из них не документирован полностью в одном месте. В официальном справочнике по CLI приводится дерево команд; в справочнике по конфигурации объясняются отдельные поля; но практические закономерности, связывающие их воедино, — нюансы строгости схемы, поведение ^[1] горячей перезагрузки и иерархия конфигурации — описаны в issues на GitHub, руководствах от сообщества и разборах ошибок в продакшене.

Это руководство всесторонне охватывает оба аспекта. Оно начинается с конфигурационного файла: формат, структура, каждый основной раздел с рабочими примерами. Затем рассматривается CLI: он организован по принципу рабочих процессов, а не в алфавитном порядке, чтобы вы могли легко найти всё необходимое для управления шлюзом, настройки каналов, диагностики и автоматизации. Завершается руководство описанием переменных окружения, порядка их разрешения и способов безопасного управления конфигурацией в рамках системы контроля версий.

Конфигурационный файл openclaw.json

Формат файла, расположение и правила валидации

Конфигурационный файл имеет формат JSON5, а не обычный JSON. Это означает, что комментарии (// like this), завершающие запятые и ключи без кавычек допустимы. По умолчанию файл находится по адресу ~/.openclaw/openclaw.json. Вы можете изменить его расположение с помощью переменной окружения OPENCLAW_CONFIG_PATH или флага CLI --profile <name>, что изолирует всё состояние в отдельном каталоге — удобно для тестирования или запуска нескольких изолированных экземпляров.

Валидация схемы выполняется через Zod при запуске. Неизвестные ключи приводят к тому, что шлюз отказывается запускаться. Нет режима предупреждений, нет мягкой обработки ошибок: если вы добавите ключ, которого нет в схеме, шлюз не запустится, и сообщение об ошибке ^[2] укажет на некорректный ключ. Это самое важное, что нужно знать перед ручным редактированием файла. Безопасный процесс редактирования:

# 1. Сначала сделайте резервную копию — всегда
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 2. Отредактируйте файл

# 3. Проверьте синтаксис JSON5
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 4. Проверьте схему и исправьте ошибки
openclaw doctor --fix

Шлюз отслеживает изменения в файле и выполняет горячую перезагрузку большинства настроек без перезапуска.

Структура конфигурации верхнего уровня

Полный обзор всех разделов верхнего уровня:

{
  // Записывается мастером настройки — не редактируйте вручную
  meta: { lastTouchedVersion: "...", lastTouchedAt: "..." },

  gateway: { ... },       // Порт, адрес привязки, токен аутентификации
  update: { channel: "stable" },  // stable | beta | dev
  env: { shellEnv: { enabled: true }, vars: { KEY: "value" } },

  agents: { defaults: { ... }, list: [ ... ] },  // Конфигурация агентов + переопределения
  models: { mode: "merge", providers: { ... } }, // Провайдеры LLM
  auth: { profiles: { ... }, order: { ... } },   // Переключение провайдеров при сбое

  channels: { telegram: { ... }, discord: { ... } }, // Каналы обмена сообщениями
  session: { dmScope: "per-channel-peer", reset: { ... } },
  bindings: [ { agentId: "...", match: { ... } } ],  // Мультиагентная маршрутизация

  cron: { enabled: true, maxConcurrentRuns: 2 },
  tools: { web: { search: { provider: "brave", apiKey: "..." } } },
  sandbox: { mode: "non-main", docker: { ... } },
  logging: { level: "info", consoleLevel: "warn" },
  skills: { install: { nodeManager: "pnpm" } },
}
Раздел gat

Раздел gateway (шлюз)

Управляет процессом привязки, аутентификации и перезагрузки шлюза:

gateway: {
  port: 18789,
  mode: "local",       // local | cloud
  bind: "loopback",    // loopback = только 127.0.0.1 (рекомендуется)
                       // all = 0.0.0.0 (требуется токен аутентификации)
  auth: {
    mode: "token",
    token: "your-generated-token",
    allowTailscale: true,   // IP-адреса Tailscale обходят проверку токена
  },
  controlUi: {
    enabled: true,
    dangerouslyDisableDeviceAuth: false,  // никогда true на общих хостах
  },
  reload: "hybrid",    // hot | hybrid | restart
}

Всегда используйте настройку bind: "loopback" на VPS-серверах. Настройка bind: "all" без надёжного токена аутентификации делает шлюз доступным из интернета. У открытых шлюзов OpenClaw, обнаруженных на публичных IP-адресах, происходит утечка ключей API, токенов OAuth и истории сессий. Шлюз откажется привязываться к не-loopback адресам без токена аутентификации. См. руководство по безопасности VPS для настройки обратного прокси.

Поле reload управляет поведением ^[3] горячей перезагрузки. Значение "hybrid" применяет изменения в реальном времени, где это возможно, и перезапускает систему только при необходимости. gateway.reload и gateway.remote — это два поля, изменение которых не вызывает перезагрузку: если вы измените любое из них, перезапустите шлюз вручную.

Раздел agents: настройки по умолчанию и переопределения для каждого агента

В разделе agents используется шаблон «знач��ния по умолчанию + переопределения». agents.defaults задаёт базовые параметры для каждого агента. Каждая запись в agents.list может переопределять отдельные поля. Шлюз объединяет их во время выполнения: конфигурация конкретного агента имеет приоритет там, где она задана, а значения по умолчанию заполняют всё остальное.

agents: {
  defaults: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: [
        "openai/gpt-5-mini",
        "openrouter/google/gemini-3-flash-preview",
      ],
    },
    // Сокращения-алиасы для slash-команды :model
    models: {
      "anthropic/claude-haiku-4-5": { alias: "haiku" },
      "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
      "anthropic/claude-opus-4-6": { alias: "opus" },
    },
    maxConcurrent: 4,

    // Обрезка контекста: удаляет устаревшие результаты инструментов перед каждым вызовом LLM
    contextPruning: {
      mode: "cache-ttl",        // off | cache-ttl
      ttl: "45m",
      keepLastAssistants: 2,
      minPrunableToolChars: 12000,
      softTrim: { maxChars: 2500, headChars: 900, tailChars: 900 },
      hardClear: { enabled: true, placeholder: "[Old tool result cleared]" },
      tools: { deny: ["browser", "canvas"] },
    },

    // Сжатие: суммаризирует полную историю, когда контекстное окно заполняется
    compaction: {
      mode: "safeguard",   // default | safeguard
      reserveTokensFloor: 12000,
      identifierPolicy: "strict",
      memoryFlush: {
        enabled: true,
        softThresholdTokens: 6000,
        prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        systemPrompt: "Session nearing compaction.",
      },
    },

    // Heartbeat
    heartbeat: {
      every: "30m",
      mode: "next-heartbeat",
    },
  },

  list: [
    { id: "main", default: true },
    {
      id: "work",
      workspace: "~/work-agent",
      model: { primary: "anthropic/claude-opus-4-6" },
      lane: "work-lane",
      laneConcurrency: 4,
    },
  ],
}

Критическое ограничение: некоторые поля работают только на уровне agents.defaults и молча игнорируются при установке для отдельного агента. К этой категории относятся настройки сжатия, значения по умолчанию для профиля браузера и переопределения уровня обработки. Шлюз не предупреждает вас — горячая перезагрузка просто не выполняется. Команда openclaw doctor --fix находит и удаляет эти недействительные ключи. Всегда запускайте её после редактирования конфигурации конкретного агента.

Обрезка контекста и сжатие (compaction): в чём разница

Обрезка контекста (context pruning) запускается перед каждым вызовом LLM. Она проверяет контекст в памяти ^[4] и удаляет устаревшие результаты инструментов, превышающие пороговое значение TTL или размера. Она не затрагивает файл сессии на диске — только то, что отправляется в модель. Без этого сессии с множеством вызовов инструментов накапливают огромные объёмы данных в контексте. Это основная причина проблемы из GitHub issue #2254: 35 сообщений создали файл сессии размером 2,9 МБ и контекст из 208 467 токенов, который молча перестал отвечать при превышении лимита модели в 200 000 токенов. Включение contextPruning с mode: "cache-ttl" предотвращает это.

Сжатие (compaction) запускается, когда контекстное окно приближается к своему пределу. Шлюз суммаризирует историю разговора, при необходимости сначала записывает заметки в ежедневный файл памяти через memoryFlush, а затем заменяет полную историю сводкой. В режиме "safeguard" выполняется пошаговая суммаризация для очень длинных историй, вместо попытки суммировать всё за один вызов LLM. Оба механизма должны быть включены в продакшене — в старых конфигурациях contextPruning может быть отключён, поскольку стал включаться по умолчанию позже.

Раздел models

models: {
  mode: "merge",  // merge = объединить списки провайдеров; replace = заменить умолчания

  providers: {
    anthropic: {
      apiKey: "${ANTHROPIC_API_KEY}",
    },
    openai: {
      apiKey: "${OPENAI_API_KEY}",
    },

    // LM Studio (локальный сервер, совместимый с OpenAI)
    "lmstudio": {
      baseUrl: "http://127.0.0.1:1234/v1",
      apiKey: "lmstudio",
      api: "openai-responses",
      models: [
        {
          id: "lmstudio/qwen2.5-coder-7b",
          name: "Qwen 2.5 Coder 7B",
          reasoning: false,
          input: ["text"],
          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
          contextWindow: 32768,
          maxTokens: 8000,
        },
      ],
    },

    // Ollama
    ollama: {
      baseUrl: "http://localhost:11434",
      apiKey: "ollama-local",
      api: "openai-completions",
      models: [ ... ],
    },
  },
}

Поле api определяет формат запросов. "openai-responses" работает для большинства локальных серверов, совместимых с OpenAI; "openai-completions" — для Ollama; "anthropic" — для Anthropic API. Если модель не поддерживает вызов инструментов, установите параметр reasoning: false и не используйте её в качестве основной модели агента — система инструментов OpenClaw требует поддержки вызова функций.

Раздел auth: переключение между профилями провайдеров при сбое

Использование нескольких профилей аутентификации для одного провайдера обеспечивает автоматическое переключение при превышении лимитов запросов. Сессии остаются привязанными к одному профилю (для поддержания кэша) и сбрасываются при выполнении /new или при сжатии данных:

auth: {
  profiles: {
    "anthropic:subscription": { mode: "oauth", email: "you@example.com" },
    "anthropic:api": { mode: "api_key", apiKey: "${ANTHROPIC_API_KEY}" },
    "openai:default": { mode: "api_key", apiKey: "${OPENAI_API_KEY}" },
  },
  order: {
    anthropic: ["anthropic:subscription", "anthropic:api"],
    openai: ["openai:default"],
  },
}

Когда профиль достигает лимита запросов или происходит сбой аутентификации, OpenClaw пытается использовать следующий профиль в списке для этого провайдера. Если все профили провайдера не проходят проверку, происходит переход к следующей модели в списке agents.defaults.model.fallbacks. Настройте резервные модели у разных провайдеров (Anthropic → OpenAI, а не Anthropic → Anthropic), чтобы избежать известной проблемы, когда достижение лимита одной моделью помечает весь провайдер как находящийся в режиме ожидания.

Раздел session

session: {
  dmScope: "per-channel-peer",
  // Варианты:
  // "main" — все личные сообщения используют одну сессию (по умолчанию для одного пользователя)
  // "per-peer" — изоляция по ID отправителя во всех каналах
  // "per-channel-peer" — изоляция по отправителю + канал (рекомендуется для нескольких пользователей)
  // "per-account-channel-peer" — максимальная гранулярность

  threadBindings: {
    enabled: true,
    idleHours: 24,      // автоматически отвязать тред после указанного числа часов простоя
    maxAgeHours: 0,     // 0 = без ограничения по возрасту
  },
  reset: {
    mode: "daily",      // none | daily | idle
    atHour: 4,          // час по UTC для ежедневного сброса
    idleMinutes: 120,   // для режима idle
  },
  identityLinks: {
    // Связывание учётных записей одного пользователя в разных каналах
    alice: ["telegram:123456", "discord:987654"],
  },
}

Настройка dmScope: "per-channel-peer" подходит для любой конфигурации, где несколько человек могут отправлять личные сообщения вашему агенту. Значение по умолчанию "main" означает, что все пользователи разделяют одну сессию, — а значит, контекст личной переписки Алисы виден Бобу. Это утечка данных, а не просто проблема настроек. См. руководство по конфиденциальности и соответствию требованиям.

Раздел sandbox

sandbox: {
  mode: "non-main",    // off | all | non-main
  scope: "session",
  docker: {
    image: "openclaw-sandbox:bookworm-slim",
    network: "none",          // без исходящей сети из песочницы
    readOnlyRoot: true,
    cpus: "1",
    memoryMb: 512,
  },
}

Режим "non-main" запускает подагентов и cron-задания внутри изолированных контейнеров Docker, сохраняя при этом основную DM-сессию на хосте. Режим "all" изолирует все процессы. Требуется Docker CLI внутри образа шлюза (OPENCLAW_INSTALL_DOCKER_CLI=1) и доступ к сокетам Docker.

Горячая перезагрузка: что применяется в реальном времени, а что требует перезапуска

Настройки, требующие перезагрузки шлюза:

• gateway.port и gateway.bind (невозможно повторно привязать активный сокет)

• gateway.reload и gateway.remote (не вызывают перезагрузку по замыслу)

• Образ Docker для песочницы или конфигурация сети

• Установка или удаление плагина

Настройки, которые применяются без перезапуска: изменения модели и резервного режима, изменения конфигурации агента, политики каналов (dmPolicy, allowFrom), cron-задания, интервалы heartbeat, конфигурация инструментов и большинство настроек сессий.

Справочник CLI

Настройка и первый запуск

# Интерактивный мастер настройки
openclaw onboard

# Настройка + установка демона одной командой (самый частый вариант первого запуска)
openclaw onboard --install-daemon

# Повторный запуск определённых шагов настройки
openclaw configure

# Неинтерактивный режим (Docker, CI)
openclaw onboard --non-interactive

# Сброс только конфигурации (сессии и учётные данные сохраняются)
openclaw reset --scope config

# Сброс конфигурации + учётных данных + сессий (рабочая область сохраняется)
openclaw reset --scope config+creds+sessions

# Полный сброс (включая рабочую область)
openclaw reset --scope full

Команда doctor и диагностика

openclaw doctor — самая полезная команда во всём CLI. Запускайте её после любых изменений конфигурации, после любого обновления и всякий раз, когда шлюз ведёт себя непредсказуемо.

# Базовая проверка (только чтение, безопасна в любое время)
openclaw doctor

# Проверка + автоисправление
openclaw doctor --fix

# Глубокое сканирование (более тщательное, медленнее)
openclaw doctor --deep --yes

# Неинтерактивный режим (для скриптов)
openclaw doctor --non-interactive

# Полный дамп статуса
openclaw status --all --deep

# Статус в формате JSON
openclaw status --json

# Прямая проверка шлюза (работает, даже если демон не запущен)
openclaw health --json --verbose

# Аудит безопасности
openclaw security audit
openclaw security audit --fix

# Проверка на утечку учётных данных
openclaw secrets audit --check

Управление шлюзом

# Запуск на переднем плане (для отладки)
openclaw gateway run

# Запуск на нестандартном порту
openclaw gateway run --port 19000 --bind loopback

# Принудительно завершить процесс на порту и запустить заново
openclaw gateway run --force

# Управление демоном (требуется установленный демон)
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

# Установка и управление демоном
openclaw daemon install
openclaw daemon install --user        # systemd-сервис на уровне пользователя
openclaw daemon start | stop | restart | status | logs | uninstall

# Открыть панель управления в браузере
openclaw dashboard

# Удалённый терминальный интерфейс (подключение к удалённому шлюзу)
openclaw tui --url https://example.com --token YOUR_TOKEN

Управление конфигурацией

Пр��дпочтительнее использовать openclaw config, а не редактировать файл напрямую. Запись через CLI использует тот же парсер JSON5 и валидацию схемы, поэтому невозможно ввести неизвестные ключи.

# Получить конкретное значение
openclaw config get agents.defaults.model.primary
openclaw config get gateway.port

# Получить всё (с форматированием)
openclaw config get

# Установить значение
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.defaults.maxConcurrent 8
openclaw config set gateway.bind "loopback"

# Удалить ключ
openclaw config unset tools.web.search.apiKey
openclaw config unset agents.defaults.heartbeat

Управление каналами

# Список каналов
openclaw channels list

# Проверка статуса (состояние подключений)
openclaw channels status
openclaw channels status --probe --all   # дополнительные проверки подключения

# Логи конкретного канала
openclaw channels logs --channel telegram
openclaw channels logs --channel discord --limit 100

# Добавить канал (интерактивный мастер)
openclaw channels add --channel telegram
openclaw channels add --channel discord

# Добавить неинтерактивно
openclaw channels add --channel telegram 
  --account main 
  --name "My Bot" 
  --token "$TELEGRAM_BOT_TOKEN"

# WhatsApp и OAuth-авторизация (сканирование QR / браузерный поток)
openclaw channels login
openclaw channels login whatsapp

# Одобрить код сопряжения от нового отправителя в личных сообщениях
openclaw pairing approve telegram CODE123

# Удалить канал (по умолчанию — отключает)
openclaw channels remove --channel telegram
openclaw channels remove --channel discord --delete   # также удаляет запись из конфигурации

Логи

# Просмотр логов в реальном времени (с цветовой разметкой в TTY)
openclaw logs --follow

# Вывод в JSON (одно событие на строку, для конвейерной обработки)
openclaw logs --json

# Ограничить количество строк
openclaw logs --limit 200

# Фильтр по уровню логирования
openclaw logs --level warn

# Логи конкретного канала
openclaw channels logs --channel whatsapp

Управление моделями

# Список настроенных моделей
openclaw models list
openclaw models list --all    # включая полный каталог

# Проверка статуса модели и аутентификации
openclaw models status
openclaw models status --probe   # тест подключения для каждого провайдера

# Сменить основную модель
openclaw models set anthropic/claude-sonnet-4-5

# Задать модель для обработки изображений (для визуального ввода)
openclaw models set-image openai/gpt-4o

# Управление алиасами
openclaw models aliases list
openclaw models aliases add fast anthropic/claude-haiku-4-5

# Управление резервными моделями
openclaw models fallbacks list
openclaw models fallbacks add openai/gpt-5-mini
openclaw models fallbacks clear

# Управление аутентификацией
openclaw models auth add
openclaw models auth setup-token
openclaw models auth order get
openclaw models auth order set anthropic "anthropic:subscription,anthropic:api"

Управление агентами

# Список агентов
openclaw agents list

# Добавить агента (интерактивно)
openclaw agents add

# Добавить неинтерактивно
openclaw agents add --id "work" --workspace ~/work-agent --non-interactive

# Список привязок маршрутизации
openclaw agents acp list

# Добавить привязку (направить канал/группу к конкретному агенту)
openclaw agents acp add --agent work --channel telegram --group-id -1001234567

# Удалить привязку
openclaw agents acp remove --agent work --channel telegram

# Выполнить один шаг агента напрямую (минуя канал)
openclaw agent --message "What needs my attention today?"

# Удалить агента
openclaw agents delete --id work

Управление памятью

# Статус индекса памяти
openclaw memory status

# Переиндексировать все файлы памяти в рабочей области
openclaw memory index --all

# Поиск по памяти
openclaw memory search --query "deployment notes"

# Отправить сообщение в конкретную сессию
openclaw message agent --session "session-key" --message "Status update?"

Управление cron-заданиями

# Список всех cron-заданий
openclaw cron list --all

# Показать статус cron-заданий
openclaw cron status

# Добавить однократное задание на определённое время
openclaw cron add 
  --name "morning-brief" 
  --at "2026-04-01T09:00:00Z" 
  --message "Summarize emails and calendar for today"

# Добавить повторяющееся задание (интервал в миллисекундах)
openclaw cron add 
  --name "hourly-check" 
  --every 3600000 
  --message "Check for priority items"

# Добавить с cron-выражением
openclaw cron add 
  --name "weekly-report" 
  --cron "0 9 * * 1" 
  --message "Generate weekly summary"

# Запустить задание немедленно (игнорируя расписание)
openclaw cron run --id morning-brief

# Включить/отключить
openclaw cron enable --id morning-brief
openclaw cron disable --id morning-brief

# Просмотр истории запусков
openclaw cron runs --id morning-brief --limit 10

# Редактировать существующее задание
openclaw cron edit --id morning-brief

# Удалить задание
openclaw cron rm --id morning-brief

Skills и плагины

# Список установленных skills
openclaw skills list

# Подробности о skill
openclaw skills info web-search

# Проверка совместимости (выполнены ли требования)
openclaw skills check --eligible

# Управление плагинами
openclaw plugins list
openclaw plugins info my-plugin
openclaw plugins install my-plugin
openclaw plugins enable my-plugin
openclaw plugins disable my-plugin
openclaw plugins doctor   # отчёт об ошибках загрузки плагинов

Сессии и устройства

# Список сессий разговоров
openclaw sessions --json

# Очистка старых файлов сессий
openclaw sessions cleanup

# Управление устройствами
openclaw devices list
openclaw devices node run --id DEVICE_ID

# Подтверждения (для инструментов, требующих ручного подтверждения)
openclaw approvals get
openclaw approvals set --policy "auto"
openclaw approvals allowlist add "exec"

Управление обновлениями

# Обновить до последней стабильной версии
openclaw update

# Сменить канал обновлений
openclaw update --channel stable   # stable | beta | dev

# Мигрировать конфигурацию после обновления мажорной версии
openclaw migrate

Глобальные флаги

Эти флаги работают с любой командой:

--dev              # Использовать dev-окружение (отдельный каталог состояния)
--profile <name>   # Использовать именованный профиль (отдельный каталог состояния)
--json             # Вывод в формате JSON
--verbose          # Подробное логирование
--no-color         # Отключить цветной вывод ANSI
--log-level debug  # Установить уровень логирования (debug | info | warn | error)

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

Приоритет источников

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

1. Окружение процесса (переменные, уже имеющиеся в оболочке при запуске шлюза)

2. .env в текущем рабочем каталоге (если присутствует при запуске шлюза)

3. ~/.openclaw/.env (глобальный резервный вариант)

4. env.vars в файле openclaw.json (встроенные переменные конфигурации, не переопределяющие параметры)

Блок env.vars в конфигурационном файле предназначен для установки значений по умолчанию, которые не переопределяют уже имеющиеся в среде параметры. Используйте его для неконфиденциальных значений. Для учётных данных используйте ~/.openclaw/.env или переменные окружения процесса.

Основные переменные окружения

# Пути конфигурации
OPENCLAW_HOME=~/.openclaw          # Базовый каталог
OPENCLAW_CONFIG_PATH=/path/to/openclaw.json  # Переопределение расположения конфигурационного файла

# Логирование
OPENCLAW_LOG_LEVEL=debug           # debug | info | warn | error
OPENCLAW_LOG_FORMAT=json           # для структурированного вывода логов

# API-ключи моделей (используются через ${VAR} в конфигурации)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...

# Шлюз
OPENCLAW_GATEWAY_TOKEN=your-token  # Переопределяет gateway.auth.token в конфигурации

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

Любое строковое значение в openclaw.json может ссылаться на переменные окружения через ${VAR_NAME}. Подстановка выполняется при запуске шлюза. Чтобы использовать литеральный символ доллара, экранируйте его: $${NOT_A_VAR}.

models: {
  providers: {
    anthropic: {
      apiKey: "${ANTHROPIC_API_KEY}",
    },
  },
}
channels: {
  telegram: {
    botToken: "${TELEGRAM_BOT_TOKEN}",
  },
}

Для наиболее безопасной работы с учётными данными используйте систему SecretRef, а не переменные окружения напрямую. Инструкции по использованию секретов Docker, HashiCorp Vault и 1Password из конфигурации см. в руководстве по управлению секретами.

Интеграция с командной оболочкой

Параметр env.shellEnv.enabled: true запускает вашу login-оболочку и импортирует из неё окружение. Это удобно, если у вас есть API-ключи, заданные в профиле оболочки (~/.bashrc, ~/.zshrc), которые вы хотите, чтобы OpenClaw подхватил без дублирования в ~/.openclaw/.env. Если запуск вашей оболочки медленный или ресурсоёмкий, задайте значение env.shellEnv.timeoutMs, чтобы ограничить время ожидания импорта.

Управление конфигурацией в системе контроля версий

Конфигурационный файл ~/.openclaw/openclaw.json содержит как инфраструктурную конфигурацию (безопасную для контроля версий), так и учётные данные (небезопасные для коммита). Самый простой подход: используйте в контроле версий очищенный шаблон, в котором все конфиденциальные значения заменены ссылками на переменные окружения, и храните фактические учётные данные только в ~/.openclaw/.env или в менеджере секретов.

Что включать в контроль версий, а что исключать

Минимальный набор параметров .gitignore для репозитория конфигурации OpenClaw:

# Учётные данные
.env
*.env
credentials/

# Сессии (большие, эфемерные, содержат приватный контекст переписки)
sessions/
*.jsonl

# Файлы памяти (персональный контент)
workspace/memory/
workspace/MEMORY.md

# Состояние cron-заданий (рантайм-данные, не конфигурация)
cron/runs/

# Рантайм-состояние
*.lock
tmp/

Что можно безопасно добавить в контроль версий: структуру openclaw.json с использованием ${VAR} вместо фактических ключей, файлы рабочей области AGENTS.md ^[5] и SOUL.md ^[6] (если не содержат персональной информации), а также определения cron-заданий в cron/jobs.json.

Предкоммитное сканирование учётных данных

Добавьте truffleHog или gitleaks в качестве pre-commit хука, чтобы перехватывать учётные данные, случайно добавленные в файлы конфигурации до коммита. Быстрая ручная проверка:

# Поиск утечек ключей перед коммитом
grep -rE "sk-ant-|sk-or-|sk-[A-Za-z0-9]{40}" ~/.openclaw/openclaw.json
# Не должно найти ничего; все ключи должны быть в формате ${VAR}

Изменения конфигурации после обновлений

В каждой версии OpenClaw могут добавляться или переименовываться ключи конфигурации, а схема может меняться между релизами. После обновления всегда запускайте openclaw doctor --fix для удаления устаревших ключей и добавления необходимых новых полей. Невыполнение этого — самая распространённая причина ситуации, когда настройки выглядят сконфигурированными, но не вступают в силу: старые ключи, тихо удалённые из схемы, игнорируются вместо того чтобы вызвать ошибку, — шлюз запускается, но настройка ничего не делает.

Благодарим за внимание ^[7]. Ваш Cloud4Y ^[8]. Читайте нас здесь или в Telegram-канале ^[9]!