Справочник по конфигурации

Справочник по основной конфигурации для ~/.openclaw/openclaw.json. Обзор, ориентированный на задачи, см. в разделе Конфигурация.

Охватывает основные поверхности конфигурации OpenClaw и дает ссылки на более подробные справочники, когда у подсистемы есть собственный углубленный материал. Каталоги команд, принадлежащие каналам и Plugin, а также глубокие настройки памяти/QMD находятся на отдельных страницах, а не здесь.

Источник истины в коде:

• openclaw config schema выводит актуальную JSON Schema, используемую для валидации и Control UI, с объединенными метаданными встроенных компонентов/Plugin/каналов, когда они доступны
• config.schema.lookup возвращает один узел схемы, ограниченный путем, для инструментов детализации
• pnpm config:docs:check / pnpm config:docs:gen проверяют базовый хэш документации конфигурации относительно текущей поверхности схемы

Путь поиска для агента: используйте действие инструмента gateway config.schema.lookup для точной документации и ограничений на уровне полей перед правками. Используйте Конфигурация для руководства, ориентированного на задачи, а эту страницу — для более широкой карты полей, значений по умолчанию и ссылок на справочники подсистем.

Отдельные углубленные справочники:

• Справочник по конфигурации памяти для agents.defaults.memorySearch.*, memory.qmd.*, memory.citations и конфигурации dreaming в plugins.entries.memory-core.config.dreaming
• Slash-команды для текущего каталога встроенных + поставляемых команд
• страницы владельцев каналов/Plugin для поверхностей команд, специфичных для каналов

Формат конфигурации — JSON5 (разрешены комментарии и завершающие запятые). Все поля необязательны — OpenClaw использует безопасные значения по умолчанию, когда они опущены.

Каналы

Ключи конфигурации для отдельных каналов перенесены на отдельную страницу — см. Конфигурация — каналы для channels.*, включая Slack, Discord, Telegram, WhatsApp, Matrix, iMessage и другие встроенные каналы (аутентификация, контроль доступа, несколько учетных записей, ограничение по упоминаниям).

Значения по умолчанию для агентов, мультиагентность, сессии и сообщения

Перенесено на отдельную страницу — см. Конфигурация — агенты для:

• agents.defaults.* (рабочая область, модель, мышление, heartbeat, память, медиа, skills, sandbox)
• multiAgent.* (мультиагентная маршрутизация и привязки)
• session.* (жизненный цикл сессии, compaction, очистка)
• messages.* (доставка сообщений, TTS, рендеринг markdown)
• talk.* (режим Talk)
  • talk.consultThinkingLevel: переопределение уровня мышления для полного запуска агента OpenClaw за realtime-консультациями Control UI Talk
  • talk.consultFastMode: одноразовое переопределение fast-mode для realtime-консультаций Control UI Talk
  • talk.speechLocale: необязательный идентификатор локали BCP 47 для распознавания речи Talk на iOS/macOS
  • talk.silenceTimeoutMs: когда не задано, Talk сохраняет стандартное для платформы окно паузы перед отправкой транскрипта (700 ms on macOS and Android, 900 ms on iOS)
  • talk.realtime.consultRouting: резервная маршрутизация через Gateway relay для финализированных realtime-транскриптов Talk, которые пропускают openclaw_agent_consult

Инструменты и пользовательские провайдеры

Политика инструментов, экспериментальные переключатели, конфигурация инструментов на базе провайдеров и настройка пользовательского провайдера / базового URL перенесены на отдельную страницу — см. Конфигурация — инструменты и пользовательские провайдеры.

Модели

Определения провайдеров, allowlist моделей и настройка пользовательских провайдеров находятся в Конфигурация — инструменты и пользовательские провайдеры. Корень models также отвечает за глобальное поведение каталога моделей.

{  models: {    // Optional. Default: true. Requires a Gateway restart when changed.    pricing: { enabled: false },  },}

• models.mode: поведение каталога провайдеров (merge или replace).
• models.providers: карта пользовательских провайдеров с ключами по id провайдера.
• models.providers.*.localService: необязательный диспетчер процессов по требованию для локальных серверов моделей. OpenClaw проверяет настроенный endpoint health, запускает абсолютную command при необходимости, ждет готовности, затем отправляет запрос модели. См. Локальные сервисы моделей.
• models.pricing.enabled: управляет фоновой начальной загрузкой цен, которая запускается после того, как sidecar-процессы и каналы достигают пути готовности Gateway. Когда false, Gateway пропускает получение ценовых каталогов OpenRouter и LiteLLM; настроенные значения models.providers.*.models[].cost по-прежнему работают для локальных оценок стоимости.

MCP

Определения MCP-серверов, управляемых OpenClaw, находятся в mcp.servers и используются встроенным OpenClaw и другими runtime-адаптерами. Команды openclaw mcp list, show, set и unset управляют этим блоком без подключения к целевому серверу во время правок конфигурации.

{  mcp: {    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.    sessionIdleTtlMs: 600000,    servers: {      docs: {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-fetch"],      },      remote: {        url: "https://example.com/mcp",        transport: "streamable-http", // streamable-http | sse        timeout: 20,        connectTimeout: 5,        supportsParallelToolCalls: true,        headers: {          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",        },        auth: "oauth",        oauth: {          scope: "docs.read",        },        sslVerify: true,        clientCert: "/path/to/client.crt",        clientKey: "/path/to/client.key",        toolFilter: {          include: ["search_*"],          exclude: ["admin_*"],        },        // Optional Codex app-server projection controls.        codex: {          agents: ["main"],          defaultToolsApprovalMode: "approve", // auto | prompt | approve        },      },    },  },}

• mcp.servers: именованные определения stdio или удаленных MCP-серверов для runtime, которые предоставляют настроенные MCP-инструменты. Удаленные записи используют transport: "streamable-http" или transport: "sse"; type: "http" — это CLI-нативный псевдоним, который openclaw mcp set и openclaw doctor --fix нормализуют в каноническое поле transport.
• mcp.servers.<name>.enabled: установите false, чтобы сохранить определение сервера, исключив его из обнаружения встроенного OpenClaw MCP и проекции инструментов.
• mcp.servers.<name>.timeout / requestTimeoutMs: таймаут MCP-запроса для отдельного сервера в секундах или миллисекундах.
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: таймаут подключения для отдельного сервера в секундах или миллисекундах.
• mcp.servers.<name>.supportsParallelToolCalls: необязательная подсказка о конкурентности для адаптеров, которые могут выбирать, выполнять ли параллельные вызовы MCP-инструментов.
• mcp.servers.<name>.auth: установите "oauth" для HTTP MCP-серверов, которым требуется OAuth. Выполните openclaw mcp login <name>, чтобы сохранить токены в состоянии OpenClaw.
• mcp.servers.<name>.oauth: необязательные переопределения scope OAuth, URL перенаправления и URL метаданных клиента.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: элементы управления HTTP TLS для приватных endpoint и mutual TLS.
• mcp.servers.<name>.toolFilter: необязательный выбор инструментов для отдельного сервера. include ограничивает обнаруженные MCP-инструменты совпадающими именами; exclude скрывает совпадающие имена. Записи — это точные имена MCP-инструментов или простые glob-шаблоны *. Серверы с ресурсами или prompt также генерируют имена служебных инструментов (resources_list, resources_read, prompts_list, prompts_get), и эти имена используют тот же фильтр.
• mcp.servers.<name>.codex: необязательные элементы управления проекцией Codex app-server. Этот блок является метаданными OpenClaw только для потоков Codex app-server; он не влияет на сессии ACP, универсальную конфигурацию Codex harness или другие runtime-адаптеры. Непустой codex.agents ограничивает сервер перечисленными id агентов OpenClaw. Пустые, blank или недействительные scoped-списки агентов отклоняются валидацией конфигурации и опускаются путем runtime-проекции, а не становятся глобальными. codex.defaultToolsApprovalMode выводит нативный для Codex default_tools_approval_mode для этого сервера. OpenClaw удаляет блок codex перед передачей нативной конфигурации mcp_servers в Codex. Опустите блок, чтобы сервер проецировался для каждого агента Codex app-server с поведением одобрения MCP по умолчанию Codex.
• mcp.sessionIdleTtlMs: idle TTL для runtime поставляемого MCP, ограниченных сессией. Одноразовые встроенные запуски запрашивают очистку в конце запуска; этот TTL является запасным механизмом для долгоживущих сессий и будущих вызывающих сторон.
• Изменения в mcp.* применяются горячо путем освобождения кэшированных session MCP runtime. Следующее обнаружение/использование инструмента пересоздает их из новой конфигурации, поэтому удаленные записи mcp.servers очищаются немедленно, а не ждут idle TTL.
• Runtime-обнаружение также учитывает уведомления об изменении списка MCP-инструментов, сбрасывая кэшированный каталог для этой сессии. Серверы, которые объявляют ресурсы или prompt, получают служебные инструменты для перечисления/чтения ресурсов и перечисления/получения prompt. Повторяющиеся сбои вызова инструмента ненадолго приостанавливают затронутый сервер перед следующей попыткой вызова.

См. MCP и CLI-бэкенды для поведения runtime.

Skills

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },    install: {      preferBrew: true,      nodeManager: "npm", // npm | pnpm | yarn | bun      allowUploadedArchives: false,    },    workshop: {      allowSymlinkTargetWrites: false,    },    entries: {      "image-lab": {        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}

• allowBundled: необязательный allowlist только для поставляемых skills (управляемые/workspace skills не затрагиваются).
• load.extraDirs: дополнительные общие корни skills (самый низкий приоритет).
• load.allowSymlinkTargets: доверенные реальные целевые корни, в которые могут разрешаться symlink skills, когда ссылка находится вне настроенного исходного корня.
• workshop.allowSymlinkTargetWrites: разрешает Skill Workshop apply записывать через уже доверенные цели symlink (по умолчанию: false).
• install.preferBrew: когда true, предпочитать установщики Homebrew, если brew доступен, перед fallback на другие типы установщиков.
• install.nodeManager: предпочтение установщика Node для спецификаций metadata.openclaw.install (npm | pnpm | yarn | bun).
• install.allowUploadedArchives: разрешить доверенным клиентам Gateway с operator.admin устанавливать приватные zip-архивы, подготовленные через skills.upload.* (по умолчанию: false). Это включает только путь загруженного архива; обычные установки ClawHub этого не требуют.
• entries.<skillKey>.enabled: false отключает skill, даже если он поставляемый/установленный.
• entries.<skillKey>.apiKey: удобство для skills, объявляющих основную переменную env (строка plaintext или объект SecretRef).

Plugins

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: [],    load: {      paths: ["~/Projects/oss/voice-call-plugin"],    },    entries: {      "voice-call": {        enabled: true,        hooks: {          allowPromptInjection: false,        },        config: { provider: "twilio" },      },    },  },}

• Загружается из каталогов пакетов или bundle-каталогов в ~/.openclaw/extensions и <workspace>/.openclaw/extensions, а также из файлов или каталогов, перечисленных в plugins.load.paths.
• Помещайте автономные файлы Plugin в plugins.load.paths; автоматически обнаруженные корни расширений игнорируют файлы .js, .mjs и .ts верхнего уровня, чтобы вспомогательные скрипты в этих корнях не блокировали запуск.
• Обнаружение принимает нативные Plugins OpenClaw, а также совместимые Codex-бандлы и Claude-бандлы, включая Claude-бандлы с layout по умолчанию без manifest.
• Изменения конфигурации требуют перезапуска Gateway.
• allow: необязательный allowlist (загружаются только перечисленные Plugins). deny имеет приоритет.
• plugins.entries.<id>.apiKey: удобное поле API-ключа на уровне Plugin (если поддерживается Plugin).
• plugins.entries.<id>.env: карта переменных окружения в области Plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: когда false, ядро блокирует before_prompt_build и игнорирует поля, изменяющие prompt, из legacy before_agent_start, сохраняя legacy modelOverride и providerOverride. Применяется к нативным хукам Plugin и поддерживаемым каталогам хуков, предоставленным бандлами.
• plugins.entries.<id>.hooks.allowConversationAccess: когда true, доверенные не встроенные Plugins могут читать сырой контент беседы из типизированных хуков, таких как llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize и agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: явно доверить этому Plugin запрашивать переопределения provider и model для каждого запуска фоновых subagent-запусков.
• plugins.entries.<id>.subagent.allowedModels: необязательный allowlist канонических целей provider/model для доверенных переопределений subagent. Используйте "*" только если вы намеренно хотите разрешить любую модель.
• plugins.entries.<id>.llm.allowModelOverride: явно доверить этому Plugin запрашивать переопределения модели для api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: необязательный allowlist канонических целей provider/model для доверенных переопределений завершения LLM Plugin. Используйте "*" только если вы намеренно хотите разрешить любую модель.
• plugins.entries.<id>.llm.allowAgentIdOverride: явно доверить этому Plugin запускать api.runtime.llm.complete для agent id, отличного от значения по умолчанию.
• plugins.entries.<id>.config: объект конфигурации, определенный Plugin (проверяется схемой нативного Plugin OpenClaw, когда доступно).
• Настройки аккаунта и runtime для channel Plugin находятся в channels.<id> и должны описываться метаданными channelConfigs manifest владеющего Plugin, а не центральным реестром опций OpenClaw.

Конфигурация Codex harness Plugin

Встроенный Plugin codex владеет нативными настройками Codex app-server harness в plugins.entries.codex.config. См. справочник Codex harness для полной поверхности конфигурации и Codex harness для runtime-модели.

codexPlugins применяется только к сессиям, которые выбирают нативный Codex harness. Он не включает Codex Plugins для запусков провайдера OpenClaw, привязок бесед ACP или любого не-Codex harness.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",                allow_destructive_actions: false,              },            },          },        },      },    },  },}

• plugins.entries.codex.config.codexPlugins.enabled: включает нативную поддержку Plugin/app для Codex harness. По умолчанию: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: политика по умолчанию для destructive-action для перенесенных elicitations приложения Plugin. Используйте true, чтобы принимать безопасные схемы одобрения Codex без запроса, false, чтобы отклонять их, "auto", чтобы маршрутизировать требуемые Codex одобрения через одобрения Plugin OpenClaw, или "always", чтобы запрашивать каждое записывающее/destructive действие Plugin без долговременного одобрения. Режим "always" очищает долговременные переопределения одобрения Codex для каждого tool в затронутом приложении перед запуском thread. По умолчанию: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: включает перенесенную запись Plugin, когда глобальный codexPlugins.enabled также равен true. По умолчанию: true для явных записей.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: стабильная идентичность marketplace. V1 поддерживает только "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: стабильная идентичность Codex Plugin из миграции, например "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: переопределение destructive-action для каждого Plugin. Если пропущено, используется глобальное значение allow_destructive_actions. Значение для каждого Plugin принимает те же политики true, false, "auto" или "always".

codexPlugins.enabled — глобальная директива включения. Явные записи Plugin, записанные миграцией, являются долговременным набором установки и пригодности для восстановления. plugins["*"] не поддерживается, переключателя install нет, а локальные значения marketplacePath намеренно не являются полями конфигурации, потому что они зависят от host.

Проверки готовности app/list кэшируются на один час и обновляются асинхронно, когда устаревают. Конфигурация приложения Codex thread вычисляется при установлении сессии Codex harness, а не на каждом turn; используйте /new, /reset или перезапуск Gateway после изменения нативной конфигурации Plugin.

• plugins.entries.firecrawl.config.webFetch: настройки провайдера Firecrawl web-fetch.
  • apiKey: необязательный API-ключ Firecrawl для более высоких лимитов (принимает SecretRef). Возвращается к plugins.entries.firecrawl.config.webSearch.apiKey, legacy tools.web.fetch.firecrawl.apiKey или переменной окружения FIRECRAWL_API_KEY.
  • baseUrl: базовый URL API Firecrawl (по умолчанию: https://api.firecrawl.dev; self-hosted переопределения должны указывать на private/internal endpoints).
  • onlyMainContent: извлекать из страниц только основной контент (по умолчанию: true).
  • maxAgeMs: максимальный возраст кэша в миллисекундах (по умолчанию: 172800000 / 2 дня).
  • timeoutSeconds: timeout scrape-запроса в секундах (по умолчанию: 60).
• plugins.entries.xai.config.xSearch: настройки xAI X Search (веб-поиск Grok).
  • enabled: включить провайдера X Search.
  • model: модель Grok, используемая для поиска (например, "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: настройки memory dreaming. См. Dreaming для фаз и порогов.
  • enabled: главный переключатель dreaming (по умолчанию false).
  • frequency: Cron-каденция для каждого полного прохода dreaming ("0 3 * * *" по умолчанию).
  • model: необязательное переопределение модели subagent Dream Diary. Требует plugins.entries.memory-core.subagent.allowModelOverride: true; используйте вместе с allowedModels, чтобы ограничить цели. Ошибки недоступности модели повторяются один раз с моделью сессии по умолчанию; ошибки доверия или allowlist не откатываются молча.
  • политика фаз и пороги являются деталями реализации (не пользовательскими ключами конфигурации).
• Полная конфигурация памяти находится в справочнике конфигурации памяти:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Включенные Claude bundle Plugins также могут вносить встроенные значения OpenClaw по умолчанию из settings.json; OpenClaw применяет их как очищенные настройки агента, а не как сырые патчи конфигурации OpenClaw.
• plugins.slots.memory: выберите id активного memory Plugin или "none", чтобы отключить memory Plugins.
• plugins.slots.contextEngine: выберите id активного context engine Plugin; по умолчанию используется "legacy", если вы не установите и не выберете другой engine.

См. Plugins.

Обязательства

commitments управляет выводимой последующей памятью: OpenClaw может обнаруживать check-ins из turns беседы и доставлять их через Heartbeat-запуски.

• commitments.enabled: включить скрытое извлечение LLM, хранение и доставку через Heartbeat для выведенных последующих обязательств. По умолчанию: false.
• commitments.maxPerDay: максимальное число выведенных последующих обязательств, доставляемых за сессию агента за скользящий день. По умолчанию: 3.

См. выведенные обязательства.

Браузер

{  browser: {    enabled: true,    evaluateEnabled: true,    defaultProfile: "user",    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access      // allowPrivateNetwork: true, // legacy alias      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    tabCleanup: {      enabled: true,      idleMinutes: 120,      maxTabsPerSession: 8,      sweepMinutes: 5,    },    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },    color: "#FF4500",    // headless: false,    // noSandbox: false,    // extraArgs: [],    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    // attachOnly: false,  },}

• evaluateEnabled: false отключает act:evaluate и wait --fn.
• tabCleanup освобождает отслеживаемые вкладки основного агента после простоя или когда сеанс превышает свой лимит. Задайте idleMinutes: 0 или maxTabsPerSession: 0, чтобы отключить эти отдельные режимы очистки.
• ssrfPolicy.dangerouslyAllowPrivateNetwork отключен, если не задан, поэтому навигация браузера по умолчанию остается строгой.
• Задавайте ssrfPolicy.dangerouslyAllowPrivateNetwork: true только когда вы намеренно доверяете браузерной навигации в частной сети.
• В строгом режиме удаленные конечные точки профилей CDP (profiles.*.cdpUrl) подпадают под такую же блокировку частных сетей во время проверок доступности/обнаружения.
• ssrfPolicy.allowPrivateNetwork остается поддерживаемым как устаревший псевдоним.
• В строгом режиме используйте ssrfPolicy.hostnameAllowlist и ssrfPolicy.allowedHostnames для явных исключений.
• Удаленные профили работают только в режиме подключения (запуск/остановка/сброс отключены).
• profiles.*.cdpUrl принимает http://, https://, ws:// и wss://. Используйте HTTP(S), когда хотите, чтобы OpenClaw обнаруживал /json/version; используйте WS(S), когда ваш провайдер предоставляет прямой URL DevTools WebSocket.
• remoteCdpTimeoutMs и remoteCdpHandshakeTimeoutMs применяются к удаленной и attachOnly доступности CDP, а также к запросам открытия вкладок. Управляемые профили loopback сохраняют локальные значения CDP по умолчанию.
• Если внешне управляемая служба CDP доступна через loopback, задайте для этого профиля attachOnly: true; иначе OpenClaw воспринимает порт loopback как локальный управляемый профиль браузера и может сообщать об ошибках владения локальным портом.
• Профили existing-session используют Chrome MCP вместо CDP и могут подключаться на выбранном хосте или через подключенный узел браузера.
• Профили existing-session могут задавать userDataDir, чтобы указать конкретный профиль браузера на базе Chromium, например Brave или Edge.
• Профили existing-session могут задавать cdpUrl, когда Chrome уже запущен за конечной точкой обнаружения DevTools HTTP(S) или прямой конечной точкой WS(S). В этом режиме OpenClaw передает конечную точку в Chrome MCP вместо авто-подключения; userDataDir игнорируется для аргументов запуска Chrome MCP.
• Профили existing-session сохраняют текущие ограничения маршрута Chrome MCP: действия на основе snapshot/ref вместо нацеливания CSS-селекторами, хуки загрузки одного файла, без переопределений тайм-аута диалогов, без wait --load networkidle и без responsebody, экспорта PDF, перехвата загрузок или пакетных действий.
• Локальные управляемые профили openclaw автоматически назначают cdpPort и cdpUrl; задавайте cdpUrl явно только для удаленных профилей CDP или подключения к конечной точке existing-session.
• Локальные управляемые профили могут задавать executablePath, чтобы переопределить глобальный browser.executablePath для этого профиля. Используйте это, чтобы запускать один профиль в Chrome, а другой в Brave.
• Локальные управляемые профили используют browser.localLaunchTimeoutMs для HTTP-обнаружения Chrome CDP после запуска процесса и browser.localCdpReadyTimeoutMs для готовности CDP websocket после запуска. Увеличивайте их на более медленных хостах, где Chrome успешно запускается, но проверки готовности опережают запуск. Оба значения должны быть положительными целыми числами до 120000 мс; недопустимые значения конфигурации отклоняются.
• Порядок автообнаружения: браузер по умолчанию, если он основан на Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath и browser.profiles.<name>.executablePath оба принимают ~ и ~/... для домашнего каталога вашей ОС перед запуском Chromium. Для userDataDir отдельного профиля в профилях existing-session тильда также раскрывается.
• Служба управления: только loopback (порт выводится из gateway.port, по умолчанию 18791).
• extraArgs добавляет дополнительные флаги запуска к локальному запуску Chromium (например --disable-gpu, размеры окна или флаги отладки).

Интерфейс

{  ui: {    seamColor: "#FF4500",    assistant: {      name: "OpenClaw",      avatar: "CB", // emoji, short text, image URL, or data URI    },  },}

• seamColor: акцентный цвет для оформления интерфейса нативного приложения (оттенок пузыря Talk Mode и т. д.).
• assistant: переопределение идентичности Control UI. Если не задано, используется идентичность активного агента.

Gateway

{  gateway: {    mode: "local", // local | remote    port: 18789,    bind: "loopback",    auth: {      mode: "token", // none | token | password | trusted-proxy      token: "your-token",      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth      allowTailscale: true,      rateLimit: {        maxAttempts: 10,        windowMs: 60000,        lockoutMs: 300000,        exemptLoopback: true,      },    },    tailscale: {      mode: "off", // off | serve | funnel      resetOnExit: false,    },    controlUi: {      enabled: true,      basePath: "/openclaw",      // root: "dist/control-ui",      // embedSandbox: "scripts", // strict | scripts | trusted      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode      // allowInsecureAuth: false,      // dangerouslyDisableDeviceAuth: false,    },    remote: {      url: "ws://127.0.0.1:18789",      transport: "ssh", // ssh | direct      token: "your-token",      // password: "your-password",    },    trustedProxies: ["10.0.0.1"],    // Optional. Default false.    allowRealIpFallback: false,    nodes: {      pairing: {        // Optional. Default unset/disabled.        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],      },      allowCommands: ["canvas.navigate"],      denyCommands: ["system.run"],    },    tools: {      // Additional /tools/invoke HTTP denies      deny: ["browser"],      // Remove tools from the default HTTP deny list for owner/admin callers      allow: ["gateway"],    },    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          timeoutMs: 10000,        },      },    },  },}

OpenAI-совместимые конечные точки

• Административный HTTP RPC: по умолчанию отключен как Plugin admin-http-rpc. Включите Plugin, чтобы зарегистрировать POST /api/v1/admin/rpc. См. Административный HTTP RPC.
• Chat Completions: отключено по умолчанию. Включите с gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Усиление URL-входов Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Пустые allowlist считаются незаданными; используйте gateway.http.endpoints.responses.files.allowUrl=false и/или gateway.http.endpoints.responses.images.allowUrl=false, чтобы отключить получение URL.
• Необязательный заголовок усиления ответа:
  • gateway.http.securityHeaders.strictTransportSecurity (задавайте только для HTTPS origins, которые вы контролируете; см. Аутентификация через доверенный прокси)

Изоляция нескольких экземпляров

Запускайте несколько Gateway на одном хосте с уникальными портами и каталогами состояния:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \OPENCLAW_STATE_DIR=~/.openclaw-a \openclaw gateway --port 19001

Удобные флаги: --dev (использует ~/.openclaw-dev + порт 19001), --profile <name> (использует ~/.openclaw-<name>).

См. Несколько Gateway.

gateway.tls

{  gateway: {    tls: {      enabled: false,      autoGenerate: false,      certPath: "/etc/openclaw/tls/server.crt",      keyPath: "/etc/openclaw/tls/server.key",      caPath: "/etc/openclaw/tls/ca-bundle.crt",    },  },}

• enabled: включает TLS termination на слушателе Gateway (HTTPS/WSS) (по умолчанию: false).
• autoGenerate: автоматически создает локальную самоподписанную пару сертификат/ключ, когда явные файлы не настроены; только для локального/dev использования.
• certPath: путь в файловой системе к файлу сертификата TLS.
• keyPath: путь в файловой системе к файлу приватного ключа TLS; держите права доступа ограниченными.
• caPath: необязательный путь к CA bundle для проверки клиента или пользовательских цепочек доверия.

gateway.reload

{  gateway: {    reload: {      mode: "hybrid", // off | restart | hot | hybrid      debounceMs: 500,      deferralTimeoutMs: 300000,    },  },}

• mode: управляет тем, как изменения конфигурации применяются во время выполнения.
  • "off": игнорировать живые изменения; изменения требуют явного перезапуска.
  • "restart": всегда перезапускать процесс Gateway при изменении конфигурации.
  • "hot": применять изменения внутри процесса без перезапуска.
  • "hybrid" (по умолчанию): сначала пытаться выполнить горячую перезагрузку; при необходимости откатываться к перезапуску.
• debounceMs: окно подавления дребезга в мс перед применением изменений конфигурации (неотрицательное целое число).
• deferralTimeoutMs: необязательное максимальное время ожидания в мс для текущих операций перед принудительным перезапуском или горячей перезагрузкой канала. Опустите, чтобы использовать ограниченное ожидание по умолчанию (300000); задайте 0, чтобы ждать бесконечно и периодически записывать предупреждения о все еще ожидающих операциях.

Хуки

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    maxBodyBytes: 262144,    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: true,    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],    allowedAgentIds: ["hooks", "main"],    presets: ["gmail"],    transformsDir: "~/.openclaw/hooks/transforms",    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "hooks",        wakeMode: "now",        name: "Gmail",        sessionKey: "hook:gmail:{{messages[0].id}}",        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",        deliver: true,        channel: "last",        model: "openai/gpt-5.4-mini",      },    ],  },}

Аутентификация: Authorization: Bearer <token> или x-openclaw-token: <token>. Токены хуков в строке запроса отклоняются.

Примечания по проверке и безопасности:

• hooks.enabled=true требует непустой hooks.token.
• hooks.token должен отличаться от активной аутентификации Gateway с общим секретом (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN или gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); при обнаружении повторного использования запуск записывает нефатальное предупреждение безопасности.
• openclaw security audit помечает повторное использование аутентификации хука/Gateway как критическую проблему, включая аутентификацию Gateway по паролю, предоставленную только во время аудита (--auth password --password <password>). Запустите openclaw doctor --fix, чтобы ротировать сохраненный повторно используемый hooks.token, затем обновите внешние отправители хуков, чтобы они использовали новый токен хука.
• hooks.path не может быть /; используйте выделенный подпуть, например /hooks.
• Если hooks.allowRequestSessionKey=true, ограничьте hooks.allowedSessionKeyPrefixes (например, ["hook:"]).
• Если сопоставление или предустановка использует шаблонный sessionKey, задайте hooks.allowedSessionKeyPrefixes и hooks.allowRequestSessionKey=true. Статические ключи сопоставления не требуют такого явного включения.

Конечные точки:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey из полезной нагрузки запроса принимается только когда hooks.allowRequestSessionKey=true (по умолчанию: false).
• POST /hooks/<name> → разрешается через hooks.mappings
  • Значения sessionKey сопоставления, отрендеренные из шаблона, считаются предоставленными извне и также требуют hooks.allowRequestSessionKey=true.

Интеграция Gmail

• Встроенная предустановка Gmail использует sessionKey: "hook:gmail:{{messages[0].id}}".
• Если вы сохраняете такую маршрутизацию по сообщениям, задайте hooks.allowRequestSessionKey: true и ограничьте hooks.allowedSessionKeyPrefixes так, чтобы они соответствовали пространству имен Gmail, например ["hook:", "hook:gmail:"].
• Если вам нужен hooks.allowRequestSessionKey: false, переопределите предустановку статическим sessionKey вместо шаблонного значения по умолчанию.

{  hooks: {    gmail: {      account: "openclaw@gmail.com",      topic: "projects/<project-id>/topics/gog-gmail-watch",      subscription: "gog-gmail-watch-push",      pushToken: "shared-push-token",      hookUrl: "http://127.0.0.1:18789/hooks/gmail",      includeBody: true,      maxBytes: 20000,      renewEveryMinutes: 720,      serve: { bind: "127.0.0.1", port: 8788, path: "/" },      tailscale: { mode: "funnel", path: "/gmail-pubsub" },      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

• Gateway автоматически запускает gog gmail watch serve при загрузке, когда он настроен. Задайте OPENCLAW_SKIP_GMAIL_WATCHER=1, чтобы отключить.
• Не запускайте отдельный gog gmail watch serve параллельно с Gateway.

Хост Plugin Canvas

{  plugins: {    entries: {      canvas: {        config: {          host: {            root: "~/.openclaw/workspace/canvas",            liveReload: true,            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1          },        },      },    },  },}

• Обслуживает редактируемые агентом HTML/CSS/JS и A2UI по HTTP через порт Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Только локально: сохраняйте gateway.bind: "loopback" (по умолчанию).
• Привязки не к loopback: маршруты canvas требуют аутентификации Gateway (токен/пароль/доверенный прокси), как и другие HTTP-поверхности Gateway.
• Веб-представления Node обычно не отправляют заголовки аутентификации; после сопряжения и подключения узла Gateway объявляет URL возможностей, ограниченные этим узлом, для доступа к canvas/A2UI.
• URL возможностей привязаны к активному WS-сеансу узла и быстро истекают. Резервный вариант на основе IP не используется.
• Внедряет клиент живой перезагрузки в обслуживаемый HTML.
• Автоматически создает начальный index.html, когда каталог пуст.
• Также обслуживает A2UI по адресу /__openclaw__/a2ui/.
• Изменения требуют перезапуска Gateway.
• Отключите живую перезагрузку для больших каталогов или ошибок EMFILE.

Обнаружение

mDNS (Bonjour)

{  discovery: {    mdns: {      mode: "minimal", // minimal | full | off    },  },}

• minimal (по умолчанию, когда включен встроенный Plugin bonjour): опускать cliPath + sshPort из TXT-записей.
• full: включать cliPath + sshPort; многоадресная реклама в LAN по-прежнему требует включенного встроенного Plugin bonjour.
• off: подавлять многоадресную рекламу в LAN без изменения включенности Plugin.
• Встроенный Plugin bonjour автоматически запускается на хостах macOS и включается вручную в развертываниях Gateway на Linux, Windows и в контейнерах.
• Имя хоста по умолчанию равно системному имени хоста, когда оно является допустимой DNS-меткой, с откатом к openclaw. Переопределите с помощью OPENCLAW_MDNS_HOSTNAME.

Глобальная область (DNS-SD)

{  discovery: {    wideArea: { enabled: true },  },}

Записывает зону unicast DNS-SD в ~/.openclaw/dns/. Для обнаружения между сетями используйте вместе с DNS-сервером (рекомендуется CoreDNS) + Tailscale split DNS.

Настройка: openclaw dns setup --apply.

Окружение

env (inline env vars)

{  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: {      GROQ_API_KEY: "gsk-...",    },    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

• Inline env vars применяются только если в окружении процесса отсутствует ключ.
• Файлы .env: .env в CWD + ~/.openclaw/.env (ни один не переопределяет существующие переменные).
• shellEnv: импортирует отсутствующие ожидаемые ключи из профиля вашей login shell.
• Полный порядок приоритета см. в разделе Окружение.

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

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

{  gateway: {    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },  },}

• Совпадают только имена в верхнем регистре: [A-Z_][A-Z0-9_]*.
• Отсутствующие/пустые переменные вызывают ошибку при загрузке конфигурации.
• Экранируйте как $${VAR} для литерала ${VAR}.
• Работает с $include.

Секреты

Ссылки на секреты аддитивны: открытые текстовые значения по-прежнему работают.

SecretRef

Используйте одну форму объекта:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Проверка:

• Шаблон provider: ^[a-z][a-z0-9_-]{0,63}$
• Шаблон id для source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• id для source: "file": абсолютный JSON pointer (например "/providers/openai/apiKey")
• Шаблон id для source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$ (поддерживает селекторы в стиле AWS secret#json_key)
• id для source: "exec" не должны содержать сегменты пути, разделенные слешами, . или .. (например, a/../b отклоняется)

Поддерживаемая поверхность учетных данных

• Каноническая матрица: Поверхность учетных данных SecretRef
• secrets apply нацелен на поддерживаемые пути учетных данных openclaw.json.
• Ссылки auth-profiles.json включены в runtime-разрешение и покрытие аудита.

Конфигурация поставщиков секретов

{  secrets: {    providers: {      default: { source: "env" }, // optional explicit env provider      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json",        timeoutMs: 5000,      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        passEnv: ["PATH", "VAULT_ADDR"],      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

Примечания:

• Поставщик file поддерживает mode: "json" и mode: "singleValue" (id должен быть "value" в режиме singleValue).
• Пути поставщиков file и exec завершаются отказом, когда проверка Windows ACL недоступна. Устанавливайте allowInsecurePath: true только для доверенных путей, которые нельзя проверить.
• Поставщику exec требуется абсолютный путь command, и он использует protocol payloads через stdin/stdout.
• По умолчанию пути команд через symlink отклоняются. Установите allowSymlinkCommand: true, чтобы разрешить пути symlink с проверкой разрешенного целевого пути.
• Если настроен trustedDirs, проверка доверенного каталога применяется к разрешенному целевому пути.
• Окружение дочернего процесса exec по умолчанию минимально; явно передавайте нужные переменные через passEnv.
• Ссылки на секреты разрешаются во время активации в in-memory snapshot, после чего пути запросов читают только snapshot.
• Фильтрация активной поверхности применяется во время активации: неразрешенные ссылки на включенных поверхностях приводят к сбою запуска/перезагрузки, а неактивные поверхности пропускаются с диагностикой.

Хранилище auth

{  auth: {    profiles: {      "anthropic:default": { provider: "anthropic", mode: "api_key" },      "anthropic:work": { provider: "anthropic", mode: "api_key" },      "openai:personal": { provider: "openai", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai:personal"],    },  },}

• Профили для каждого агента хранятся в <agentDir>/auth-profiles.json.
• auth-profiles.json поддерживает ссылки на уровне значений (keyRef для api_key, tokenRef для token) для статических режимов учетных данных.
• Устаревшие плоские карты auth-profiles.json, такие как { "provider": { "apiKey": "..." } }, не являются runtime-форматом; openclaw doctor --fix переписывает их в канонические API-key-профили provider:default с резервной копией .legacy-flat.*.bak.
• Профили в режиме OAuth (auth.profiles.<id>.mode = "oauth") не поддерживают учетные данные auth-профиля на базе SecretRef.
• Статические runtime-учетные данные берутся из разрешенных снимков в памяти; устаревшие статические записи auth.json очищаются при обнаружении.
• Устаревшие OAuth-импорты берутся из ~/.openclaw/credentials/oauth.json.
• См. OAuth.
• Runtime-поведение секретов и инструменты audit/configure/apply: Управление секретами.

auth.cooldowns

{  auth: {    cooldowns: {      billingBackoffHours: 5,      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },      billingMaxHours: 24,      authPermanentBackoffMinutes: 10,      authPermanentMaxMinutes: 60,      failureWindowHours: 24,      overloadedProfileRotations: 1,      overloadedBackoffMs: 0,      rateLimitedProfileRotations: 1,    },  },}

• billingBackoffHours: базовая задержка в часах, когда профиль дает сбой из-за настоящих ошибок оплаты/недостатка средств (по умолчанию: 5). Явный текст про оплату может все равно попасть сюда даже в ответах 401/403, но текстовые сопоставители, специфичные для провайдера, остаются ограничены провайдером, которому они принадлежат (например, OpenRouter Key limit exceeded). Повторяемые HTTP 402 с сообщениями об окне использования или лимите расходов организации/рабочей области остаются в пути rate_limit.
• billingBackoffHoursByProvider: необязательные переопределения часов задержки оплаты для каждого провайдера.
• billingMaxHours: верхний предел в часах для экспоненциального роста задержки оплаты (по умолчанию: 24).
• authPermanentBackoffMinutes: базовая задержка в минутах для высокодостоверных сбоев auth_permanent (по умолчанию: 10).
• authPermanentMaxMinutes: верхний предел в минутах для роста задержки auth_permanent (по умолчанию: 60).
• failureWindowHours: скользящее окно в часах, используемое для счетчиков задержки (по умолчанию: 24).
• overloadedProfileRotations: максимальное число ротаций auth-профилей того же провайдера при ошибках перегрузки перед переключением на резервную модель (по умолчанию: 1). Формы занятости провайдера, такие как ModelNotReadyException, попадают сюда.
• overloadedBackoffMs: фиксированная задержка перед повторной попыткой ротации перегруженного провайдера/профиля (по умолчанию: 0).
• rateLimitedProfileRotations: максимальное число ротаций auth-профилей того же провайдера при ошибках rate-limit перед переключением на резервную модель (по умолчанию: 1). Этот bucket rate-limit включает тексты, оформленные провайдером, такие как Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded и resource exhausted.

Журналирование

{  logging: {    level: "info",    file: "/tmp/openclaw/openclaw.log",    consoleLevel: "info",    consoleStyle: "pretty", // pretty | compact | json    redactSensitive: "tools", // off | tools    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],  },}

• Файл журнала по умолчанию: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Задайте logging.file для стабильного пути.
• consoleLevel повышается до debug при --verbose.
• maxFileBytes: максимальный размер активного файла журнала в байтах перед ротацией (положительное целое число; по умолчанию: 104857600 = 100 МБ). OpenClaw хранит до пяти нумерованных архивов рядом с активным файлом.
• redactSensitive / redactPatterns: маскирование по возможности для консольного вывода, файловых журналов, записей журнала OTLP и сохраненного текста транскрипта сессии. redactSensitive: "off" отключает только эту общую политику журналов/транскриптов; поверхности безопасности UI/инструментов/диагностики все равно редактируют секреты перед выводом.

Диагностика

{  diagnostics: {    enabled: true,    flags: ["telegram.*"],    stuckSessionWarnMs: 30000,    stuckSessionAbortMs: 300000,    memoryPressureSnapshot: false,     otel: {      enabled: false,      endpoint: "https://otel-collector.example.com:4318",      tracesEndpoint: "https://traces.example.com/v1/traces",      metricsEndpoint: "https://metrics.example.com/v1/metrics",      logsEndpoint: "https://logs.example.com/v1/logs",      protocol: "http/protobuf", // http/protobuf | grpc      headers: { "x-tenant-id": "my-org" },      serviceName: "openclaw-gateway",      traces: true,      metrics: true,      logs: false,      logsExporter: "otlp",      sampleRate: 1.0,      flushIntervalMs: 5000,      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: false,      },    },     cacheTrace: {      enabled: false,      filePath: "~/.openclaw/logs/cache-trace.jsonl",      includeMessages: true,      includePrompt: true,      includeSystem: true,    },  },}

• enabled: главный переключатель вывода инструментирования (по умолчанию: true).
• flags: массив строк флагов, включающих целевой вывод журнала (поддерживает подстановочные шаблоны вроде "telegram.*" или "*").
• stuckSessionWarnMs: порог возраста без прогресса в мс для классификации длительных сессий обработки как session.long_running, session.stalled или session.stuck. Ответ, инструмент, статус, блок и прогресс ACP сбрасывают таймер; повторяющаяся диагностика session.stuck применяет backoff, пока состояние не меняется.
• stuckSessionAbortMs: порог возраста без прогресса в мс, после которого подходящая зависшая активная работа может быть abort-drained для восстановления. Если не задано, OpenClaw использует более безопасное расширенное окно встроенного запуска минимум 5 минут и 3x stuckSessionWarnMs.
• memoryPressureSnapshot: захватывает отредактированный снимок стабильности перед OOM, когда давление памяти достигает critical (по умолчанию: false). Установите true, чтобы добавить сканирование/запись файла пакета стабильности, сохранив обычные события давления памяти.
• otel.enabled: включает конвейер экспорта OpenTelemetry (по умолчанию: false). Полную конфигурацию, каталог сигналов и модель приватности см. в экспорте OpenTelemetry.
• otel.endpoint: URL коллектора для экспорта OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: необязательные OTLP-эндпоинты для отдельных сигналов. Если заданы, они переопределяют otel.endpoint только для этого сигнала.
• otel.protocol: "http/protobuf" (по умолчанию) или "grpc".
• otel.headers: дополнительные заголовки метаданных HTTP/gRPC, отправляемые с запросами экспорта OTel.
• otel.serviceName: имя сервиса для атрибутов ресурса.
• otel.traces / otel.metrics / otel.logs: включают экспорт трассировок, метрик или журналов.
• otel.logsExporter: приемник экспорта журналов: "otlp" (по умолчанию), "stdout" для одного JSON-объекта на строку stdout или "both".
• otel.sampleRate: частота семплирования трассировки 0-1.
• otel.flushIntervalMs: периодический интервал сброса телеметрии в мс.
• otel.captureContent: явное включение захвата необработанного содержимого для атрибутов span OTEL. По умолчанию отключено. Boolean true захватывает несистемное содержимое сообщений/инструментов; объектная форма позволяет явно включить inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt и toolDefinitions.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: переключатель окружения для новейшей экспериментальной формы span GenAI inference, включая имена span {gen_ai.operation.name} {gen_ai.request.model}, тип span CLIENT и gen_ai.provider.name вместо устаревшего gen_ai.system. По умолчанию span сохраняют openclaw.model.call и gen_ai.system для совместимости; метрики GenAI используют ограниченные семантические атрибуты.
• OPENCLAW_OTEL_PRELOADED=1: переключатель окружения для хостов, которые уже зарегистрировали глобальный OpenTelemetry SDK. В этом случае OpenClaw пропускает запуск/останов SDK, принадлежащего Plugin, сохраняя диагностические слушатели активными.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT и OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: env-переменные эндпоинтов для отдельных сигналов, используемые, когда соответствующий ключ конфигурации не задан.
• cacheTrace.enabled: журналировать снимки трассировки кэша для встроенных запусков (по умолчанию: false).
• cacheTrace.filePath: путь вывода для cache trace JSONL (по умолчанию: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: управляют тем, что включается в вывод cache trace (все по умолчанию: true).

Обновление

{  update: {    channel: "stable", // stable | beta | dev    checkOnStart: true,     auto: {      enabled: false,      stableDelayHours: 6,      stableJitterHours: 12,      betaCheckIntervalHours: 1,    },  },}

• channel: канал релиза для установок npm/git - "stable", "beta" или "dev".
• checkOnStart: проверять обновления npm при запуске gateway (по умолчанию: true).
• auto.enabled: включить фоновое автообновление для установок пакетов (по умолчанию: false).
• auto.stableDelayHours: минимальная задержка в часах перед авто-применением stable-канала (по умолчанию: 6; максимум: 168).
• auto.stableJitterHours: дополнительное окно распределения rollout для stable-канала в часах (по умолчанию: 12; максимум: 168).
• auto.betaCheckIntervalHours: как часто выполняются проверки beta-канала, в часах (по умолчанию: 1; максимум: 24).

ACP

{  acp: {    enabled: true,    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "main",    allowedAgents: ["main", "ops"],    maxConcurrentSessions: 10,     stream: {      coalesceIdleMs: 50,      maxChunkChars: 1000,      repeatSuppression: true,      deliveryMode: "live", // live | final_only      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph      maxOutputChars: 50000,      maxSessionUpdateChars: 500,    },     runtime: {      ttlMinutes: 30,    },  },}

• enabled: глобальный feature gate ACP (по умолчанию: true; установите false, чтобы скрыть dispatch ACP и возможности spawn).
• dispatch.enabled: независимый gate для dispatch хода сессии ACP (по умолчанию: true). Установите false, чтобы команды ACP оставались доступными, но выполнение блокировалось.
• backend: идентификатор runtime backend ACP по умолчанию (должен соответствовать зарегистрированному runtime Plugin ACP). Сначала установите backend Plugin, и если задан plugins.allow, включите идентификатор backend Plugin (например, acpx), иначе backend ACP не загрузится.
• defaultAgent: резервный идентификатор целевого агента ACP, когда spawn не указывает явную цель.
• allowedAgents: allowlist идентификаторов агентов, разрешенных для runtime-сессий ACP; пустое значение означает отсутствие дополнительных ограничений.
• maxConcurrentSessions: максимальное число одновременно активных сессий ACP.
• stream.coalesceIdleMs: окно idle flush в мс для потокового текста.
• stream.maxChunkChars: максимальный размер фрагмента перед разделением проекции потокового блока.
• stream.repeatSuppression: подавлять повторяющиеся строки статуса/инструментов в рамках хода (по умолчанию: true).
• stream.deliveryMode: "live" передает поток инкрементально; "final_only" буферизует до терминальных событий хода.
• stream.hiddenBoundarySeparator: разделитель перед видимым текстом после скрытых событий инструмента (по умолчанию: "paragraph").
• stream.maxOutputChars: максимальное число символов вывода ассистента, проецируемых на ход ACP.
• stream.maxSessionUpdateChars: максимальное число символов для проецируемых строк статуса/обновления ACP.
• stream.tagVisibility: запись имен тегов в boolean-переопределения видимости для потоковых событий.
• runtime.ttlMinutes: idle TTL в минутах для worker сессий ACP до возможности очистки.
• runtime.installCommand: необязательная команда установки, выполняемая при bootstrap runtime-окружения ACP.

CLI

{  cli: {    banner: {      taglineMode: "off", // random | default | off    },  },}

• cli.banner.taglineMode управляет стилем слогана баннера:
  • "random" (по умолчанию): чередующиеся забавные/сезонные слоганы.
  • "default": фиксированный нейтральный слоган (All your chats, one OpenClaw.).
  • "off": без текста слогана (заголовок/версия баннера всё равно отображаются).
• Чтобы скрыть весь баннер (а не только слоганы), задайте переменную окружения OPENCLAW_HIDE_BANNER=1.

Мастер

Метаданные, записываемые интерактивными потоками настройки CLI (onboard, configure, doctor):

{  wizard: {    lastRunAt: "2026-01-01T00:00:00.000Z",    lastRunVersion: "2026.1.4",    lastRunCommit: "abc1234",    lastRunCommand: "configure",    lastRunMode: "local",  },}

Идентификация

См. поля идентификации agents.list в разделе значения по умолчанию агента.

Мост (устаревший, удалён)

Текущие сборки больше не включают TCP-мост. Узлы подключаются через Gateway WebSocket. Ключи bridge.* больше не входят в схему конфигурации (валидация завершается ошибкой, пока они не удалены; openclaw doctor --fix может удалить неизвестные ключи).

{"bridge": {  "enabled": true,  "port": 18790,  "bind": "tailnet",  "tls": {    "enabled": true,    "autoGenerate": true  }}}

Cron

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth    sessionRetention: "24h", // duration string or false    runLog: {      maxBytes: "2mb", // default 2_000_000 bytes      keepLines: 2000, // default 2000    },  },}

• sessionRetention: как долго хранить завершённые изолированные сессии запусков cron перед удалением из sessions.json. Также управляет очисткой архивированных удалённых расшифровок cron. По умолчанию: 24h; задайте false, чтобы отключить.
• runLog.maxBytes: принимается для совместимости со старыми файловыми журналами запусков cron. По умолчанию: 2_000_000 байт.
• runLog.keepLines: новейшие строки истории запусков SQLite, сохраняемые для каждого задания. По умолчанию: 2000.
• webhookToken: bearer-токен, используемый для доставки cron Webhook через POST (delivery.mode = "webhook"); если он не указан, заголовок авторизации не отправляется.
• webhook: устаревший резервный URL Webhook (http/https), используемый openclaw doctor --fix для миграции сохранённых заданий, в которых всё ещё есть notify: true; доставка во время выполнения использует для каждого задания delivery.mode="webhook" вместе с delivery.to или delivery.completionDestination при сохранении доставки объявлений.

cron.retry

{  cron: {    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },  },}

• maxAttempts: максимальное количество повторных попыток для cron-заданий при временных ошибках (по умолчанию: 3; диапазон: 0-10).
• backoffMs: массив задержек backoff в мс для каждой повторной попытки (по умолчанию: [30000, 60000, 300000]; 1-10 элементов).
• retryOn: типы ошибок, запускающие повторные попытки: "rate_limit", "overloaded", "network", "timeout", "server_error". Не указывайте, чтобы повторять все временные типы.

Одноразовые задания остаются включёнными, пока не будут исчерпаны повторные попытки, затем отключаются с сохранением итогового состояния ошибки. Повторяющиеся задания используют ту же политику повторов при временных ошибках, чтобы запуститься снова после backoff перед следующим запланированным интервалом; постоянные ошибки или исчерпанные повторные попытки при временных ошибках возвращаются к обычному повторяющемуся расписанию с backoff по ошибке.

cron.failureAlert

{  cron: {    failureAlert: {      enabled: false,      after: 3,      cooldownMs: 3600000,      includeSkipped: false,      mode: "announce",      accountId: "main",    },  },}

• enabled: включает оповещения о сбоях для cron-заданий (по умолчанию: false).
• after: количество последовательных сбоев перед отправкой оповещения (положительное целое число, минимум: 1).
• cooldownMs: минимальное количество миллисекунд между повторными оповещениями для одного и того же задания (неотрицательное целое число).
• includeSkipped: учитывать последовательные пропущенные запуски в пороге оповещения (по умолчанию: false). Пропущенные запуски отслеживаются отдельно и не влияют на backoff ошибок выполнения.
• mode: режим доставки: "announce" отправляет сообщение через канал; "webhook" отправляет POST на настроенный Webhook.
• accountId: необязательный идентификатор аккаунта или канала для ограничения области доставки оповещений.

cron.failureDestination

{  cron: {    failureDestination: {      mode: "announce",      channel: "last",      to: "channel:C1234567890",      accountId: "main",    },  },}

• Назначение по умолчанию для уведомлений о сбоях cron по всем заданиям.
• mode: "announce" или "webhook"; по умолчанию используется "announce", когда доступно достаточно данных о цели.
• channel: переопределение канала для доставки объявлений. "last" повторно использует последний известный канал доставки.
• to: явная цель объявления или URL Webhook. Обязательно для режима Webhook.
• accountId: необязательное переопределение аккаунта для доставки.
• delivery.failureDestination конкретного задания переопределяет это глобальное значение по умолчанию.
• Когда ни глобальное назначение сбоя, ни назначение сбоя конкретного задания не задано, задания, которые уже доставляются через announce, при сбое возвращаются к этой основной цели объявления.
• delivery.failureDestination поддерживается только для заданий sessionTarget="isolated", если основной delivery.mode задания не равен "webhook".

См. Cron-задания. Изолированные выполнения cron отслеживаются как фоновые задачи.

Переменные шаблона модели медиа

Заполнители шаблона, разворачиваемые в tools.media.models[].args:

Включения конфигурации ($include)

Разделение конфигурации на несколько файлов:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],  },}

Поведение слияния:

• Один файл: заменяет содержащий объект.
• Массив файлов: глубоко сливается по порядку (более поздние переопределяют более ранние).
• Соседние ключи: сливаются после включений (переопределяют включённые значения).
• Вложенные включения: до 10 уровней в глубину.
• Пути: разрешаются относительно включающего файла, но должны оставаться внутри каталога конфигурации верхнего уровня (dirname от openclaw.json). Абсолютные формы и формы с ../ разрешены только тогда, когда они всё равно разрешаются внутри этой границы. Пути не должны содержать null-байты и должны быть строго короче 4096 символов до и после разрешения.
• Записи, принадлежащие OpenClaw, которые изменяют только один раздел верхнего уровня, подкреплённый однофайловым включением, записываются в этот включённый файл. Например, plugins install обновляет plugins: { $include: "./plugins.json5" } в plugins.json5 и оставляет openclaw.json без изменений.
• Корневые включения, массивы включений и включения с соседними переопределениями доступны только для чтения для записей, принадлежащих OpenClaw; такие записи завершаются закрытой ошибкой вместо разворачивания конфигурации.
• Ошибки: понятные сообщения для отсутствующих файлов, ошибок разбора, циклических включений, недопустимого формата пути и чрезмерной длины.

Связано: Конфигурация · Примеры конфигурации · Doctor

Связано

• Конфигурация
• Примеры конфигурации