Довідник із конфігурації

Довідник основної конфігурації для ~/.openclaw/openclaw.json. Огляд, орієнтований на завдання, див. у Конфігурація.

Охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний глибший довідник. Каталоги команд, якими володіють канали й plugins, а також поглиблені параметри пам’яті/QMD розміщені на власних сторінках, а не тут.

Джерело істини в коді:

• openclaw config schema виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні
• 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-команди для поточного вбудованого + bundled каталогу команд
• сторінки відповідних каналів/plugins для поверхонь команд, специфічних для каналу

Формат конфігурації — JSON5 (дозволені коментарі та завершальні коми). Усі поля необов’язкові - OpenClaw використовує безпечні типові значення, коли їх пропущено.

# Канали

Ключі конфігурації для окремих каналів перенесено на окрему сторінку - див. Конфігурація - канали для channels.*, зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадками).

# Типові параметри агента, багато агентів, сеанси та повідомлення

Перенесено на окрему сторінку - див. Конфігурація - агенти для:

• agents.defaults.* (робоча область, модель, мислення, Heartbeat, пам’ять, медіа, Skills, пісочниця)
• multiAgent.* (маршрутизація та прив’язки для багатьох агентів)
• session.* (життєвий цикл сеансу, Compaction, обрізання)
• messages.* (доставка повідомлень, TTS, рендеринг markdown)
• talk.* (режим Talk)
  • talk.speechLocale: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS
  • talk.silenceTimeoutMs: коли не задано, Talk зберігає типове для платформи вікно паузи перед надсиланням транскрипта (700 ms on macOS and Android, 900 ms on iOS)

# Інструменти та кастомні провайдери

Політика інструментів, експериментальні перемикачі, конфігурація інструментів на базі провайдерів і налаштування кастомного провайдера / базової URL-адреси перенесені на окрему сторінку - див. Конфігурація - інструменти та кастомні провайдери.

# Моделі

Визначення провайдерів, списки дозволених моделей і налаштування кастомних провайдерів розміщено в Конфігурація - інструменти та кастомні провайдери. Корінь models також відповідає за глобальну поведінку каталогу моделей.

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

• models.mode: поведінка каталогу провайдерів (merge або replace).
• models.providers: мапа кастомних провайдерів, ключована ідентифікатором провайдера.
• models.pricing.enabled: керує фоновим початковим завантаженням pricing, яке стартує після того, як sidecars і канали досягнуть готового шляху Gateway. Коли false, Gateway пропускає отримання pricing-каталогів OpenRouter і LiteLLM; налаштовані значення models.providers.*.models[].cost досі працюють для локальних оцінок вартості.

# MCP

Визначення MCP-серверів, керованих OpenClaw, розміщені в mcp.servers і використовуються вбудованим Pi та іншими 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
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: іменовані визначення stdio або віддалених MCP-серверів для runtime, які надають налаштовані MCP-інструменти. Віддалені записи використовують transport: "streamable-http" або transport: "sse"; type: "http" — CLI-нативний псевдонім, який openclaw mcp set і openclaw doctor --fix нормалізують у канонічне поле transport.
• mcp.sessionIdleTtlMs: TTL бездіяльності для bundled MCP runtime, обмежених сеансом. Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є резервним механізмом для довгоживучих сеансів і майбутніх викликачів.
• Зміни в mcp.* застосовуються гаряче через звільнення кешованих MCP runtime сеансів. Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тож видалені записи mcp.servers прибираються негайно, а не чекають idle TTL.

Див. MCP і CLI бекенди щодо поведінки runtime.

# Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    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: необов’язковий список дозволених лише для bundled skills (не впливає на керовані/робочі skills).
• load.extraDirs: додаткові спільні корені skill (найнижчий пріоритет).
• install.preferBrew: коли true, віддає перевагу інсталяторам Homebrew, якщо brew доступний, перш ніж переходити до інших типів інсталяторів.
• install.nodeManager: перевага Node-інсталятора для специфікацій metadata.openclaw.install (npm | pnpm | yarn | bun).
• entries.<skillKey>.enabled: false вимикає skill, навіть якщо він bundled/встановлений.
• entries.<skillKey>.apiKey: зручність для skills, які оголошують основну змінну середовища (plaintext-рядок або об’єкт SecretRef).

# Plugins

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

• Завантажуються з ~/.openclaw/extensions, <workspace>/.openclaw/extensions, а також plugins.load.paths.
• Discovery приймає нативні OpenClaw plugins, а також сумісні Codex bundles і Claude bundles, включно з manifestless Claude default-layout bundles.
• Зміни конфігурації потребують перезапуску gateway.
• allow: необов’язковий список дозволених (завантажуються лише перелічені plugins). deny має пріоритет.
• bundledDiscovery: типове значення для нових конфігурацій — "allowlist", тому непорожній plugins.allow також обмежує bundled provider plugins, зокрема web-search runtime providers. Doctor записує "compat" для мігрованих legacy allowlist конфігурацій, щоб зберегти наявну поведінку bundled providers, доки ви не ввімкнете нову.
• plugins.entries.<id>.apiKey: зручне поле API-ключа на рівні plugin (коли підтримується plugin).
• plugins.entries.<id>.env: мапа змінних середовища, обмежена plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: коли false, core блокує before_prompt_build і ігнорує поля, що змінюють prompt, із legacy before_agent_start, зберігаючи legacy modelOverride і providerOverride. Застосовується до нативних plugin hooks і підтримуваних директорій hooks, наданих bundle.
• plugins.entries.<id>.hooks.allowConversationAccess: коли true, довірені небандловані plugins можуть читати сирий вміст розмови з типізованих hooks, як-от llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize і agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: явно довіряє цьому plugin запитувати per-run перевизначення provider і model для фонових запусків subagent.
• plugins.entries.<id>.subagent.allowedModels: необов’язковий список дозволених канонічних цілей provider/model для довірених перевизначень subagent. Використовуйте "*" лише тоді, коли навмисно хочете дозволити будь-яку модель.
• plugins.entries.<id>.config: об’єкт конфігурації, визначений plugin (валідується нативною схемою OpenClaw plugin, коли доступна).
• Налаштування облікового запису/runtime channel plugin розміщуються в channels.<id> і мають описуватися метаданими channelConfigs маніфесту відповідного plugin, а не центральним реєстром опцій OpenClaw.
• 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-адреса Firecrawl API (типово: https://api.firecrawl.dev; self-hosted перевизначення мають вказувати на private/internal endpoints).
  • onlyMainContent: витягувати зі сторінок лише основний вміст (типово: true).
  • maxAgeMs: максимальний вік кешу в мілісекундах (типово: 172800000 / 2 дні).
  • timeoutSeconds: тайм-аут scrape-запиту в секундах (типово: 60).
• plugins.entries.xai.config.xSearch: налаштування xAI X Search (Grok web search).
  • enabled: увімкнути провайдера X Search.
  • model: модель Grok для використання в пошуку (наприклад, "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: налаштування memory dreaming. Див. Dreaming щодо фаз і порогів.
  • enabled: головний перемикач dreaming (типово false).
  • frequency: Cron cadence для кожного повного sweep 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 також можуть додавати вбудовані типові значення Pi з settings.json; OpenClaw застосовує їх як sanitized налаштування агента, а не як сирі patches конфігурації OpenClaw.
• plugins.slots.memory: виберіть ідентифікатор активного plugin пам’яті або "none", щоб вимкнути plugins пам’яті.
• plugins.slots.contextEngine: виберіть ідентифікатор активного plugin context engine; типово "legacy", якщо ви не встановите й не виберете інший engine.

Див. Plugins.

# Зобов’язання

commitments керує виведеною пам’яттю подальших дій: OpenClaw може виявляти check-ins із ходів розмови та доставляти їх через 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 для явних винятків.
• Віддалені профілі працюють лише в режимі підключення (start/stop/reset вимкнено).
• profiles.*.cdpUrl приймає http://, https://, ws:// і wss://. Використовуйте HTTP(S), коли потрібно, щоб OpenClaw виявляв /json/version; використовуйте WS(S), коли ваш провайдер надає прямий URL DevTools WebSocket.
• remoteCdpTimeoutMs і remoteCdpHandshakeTimeoutMs застосовуються до перевірок доступності віддаленого CDP і attachOnly, а також до запитів відкриття вкладок. Керовані профілі loopback зберігають локальні стандартні значення CDP.
• Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього профілю attachOnly: true; інакше OpenClaw трактує порт loopback як локальний керований профіль браузера і може повідомляти про помилки володіння локальним портом.
• Профілі existing-session використовують Chrome MCP замість CDP і можуть підключатися на вибраному хості або через підключений браузерний вузол.
• Профілі existing-session можуть задавати userDataDir, щоб націлитися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge.
• Профілі existing-session зберігають поточні обмеження маршрутів Chrome MCP: дії на основі snapshot/ref замість націлювання CSS-селекторами, хуки завантаження одного файлу, без перевизначень тайм-аутів діалогів, без wait --load networkidle і без responsebody, експорту PDF, перехоплення завантажень або пакетних дій.
• Локальні керовані профілі openclaw автоматично призначають cdpPort і cdpUrl; задавайте cdpUrl явно лише для віддаленого CDP.
• Локальні керовані профілі можуть задавати 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: акцентний колір для chrome нативного інтерфейсу застосунку (відтінок бульбашки 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://gateway.tailnet: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
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

# OpenAI-сумісні кінцеві точки

• 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 Порожні списки дозволених трактуються як незадані; використовуйте gateway.http.endpoints.responses.files.allowUrl=false і/або gateway.http.endpoints.responses.images.allowUrl=false, щоб вимкнути отримання URL.
• Необов’язковий заголовок посилення захисту відповіді:
  • gateway.http.securityHeaders.strictTransportSecurity (задавайте лише для HTTPS origin, які ви контролюєте; див. Автентифікація через довірений проксі)

# Ізоляція кількох екземплярів

Запускайте кілька 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 на слухачі Gateway (HTTPS/WSS) (типово: false).
• autoGenerate: автоматично генерує локальну самопідписану пару сертифікат/ключ, коли явні файли не налаштовано; лише для локального використання/розробки.
• certPath: шлях файлової системи до файлу сертифіката TLS.
• keyPath: шлях файлової системи до файлу приватного ключа TLS; тримайте права доступу обмеженими.
• caPath: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюжків довіри.

# gateway.reload

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

• mode: керує тим, як зміни конфігурації застосовуються під час виконання.
  • "off": ігнорувати live-редагування; зміни потребують явного перезапуску.
  • "restart": завжди перезапускати процес Gateway після зміни конфігурації.
  • "hot": застосовувати зміни в процесі без перезапуску.
  • "hybrid" (типово): спочатку спробувати гаряче перезавантаження; якщо потрібно, повернутися до перезапуску.
• debounceMs: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
• 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>. Токени hook у рядку запиту відхиляються.

Примітки щодо перевірки та безпеки:

• hooks.enabled=true потребує непорожнього hooks.token.
• hooks.token має бути відмінним від gateway.auth.token; повторне використання токена Gateway відхиляється.
• 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: "[email protected]",
      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 WebViews зазвичай не надсилають заголовки автентифікації; після сполучення та підключення вузла Gateway оголошує URL можливостей з областю дії вузла для доступу до canvas/A2UI.
• URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний механізм на основі IP не використовується.
• Вставляє клієнт live-reload в обслуговуваний HTML.
• Автоматично створює початковий index.html, коли каталог порожній.
• Також обслуговує A2UI на /__openclaw__/a2ui/.
• Зміни потребують перезапуску gateway.
• Вимикайте live reload для великих каталогів або помилок EMFILE.

# Виявлення

# mDNS (Bonjour)

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

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

# Глобальна зона (DNS-SD)

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

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

Налаштування: openclaw dns setup --apply.

# Середовище

# env (вбудовані змінні середовища)

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

• Вбудовані змінні середовища застосовуються лише якщо в середовищі процесу немає відповідного ключа.
• Файли .env: .env у CWD + ~/.openclaw/.env (жоден не перевизначає наявні змінні).
• shellEnv: імпортує відсутні очікувані ключі з профілю вашої оболонки входу.
• Повний порядок пріоритетів див. у Середовище.

# Підстановка змінних середовища

Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою ${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}$
• id для source: "exec" не мають містити сегменти шляху, розділені скісними рисками, . або .. (наприклад, a/../b відхиляється)

# Підтримувана поверхня облікових даних

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

# Конфігурація постачальників секретів

{
  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 і використовує протокольні payload у stdin/stdout.
• За замовчуванням шляхи команд через символьні посилання відхиляються. Установіть allowSymlinkCommand: true, щоб дозволити шляхи із символьними посиланнями, водночас перевіряючи розв’язаний цільовий шлях.
• Якщо налаштовано trustedDirs, перевірка довіреного каталогу застосовується до розв’язаного цільового шляху.
• Дочірнє середовище exec за замовчуванням мінімальне; передавайте потрібні змінні явно через passEnv.
• Посилання на секрети розв’язуються під час активації у знімок у пам’яті, після чого шляхи запитів читають лише цей знімок.
• Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на ввімкнених поверхнях призводять до збою запуску або перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.

# Сховище автентифікації

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

• Профілі для кожного агента зберігаються в <agentDir>/auth-profiles.json.
• auth-profiles.json підтримує посилання на рівні значень (keyRef для api_key, tokenRef для token) для статичних режимів облікових даних.
• Застарілі пласкі мапи auth-profiles.json, як-от { "provider": { "apiKey": "..." } }, не є форматом часу виконання; openclaw doctor --fix переписує їх у канонічні профілі API-ключів provider:default із резервною копією .legacy-flat.*.bak.
• Профілі в режимі OAuth (auth.profiles.<id>.mode = "oauth") не підтримують облікові дані профілю автентифікації на основі SecretRef.
• Статичні облікові дані часу виконання надходять із розв’язаних знімків у пам’яті; застарілі статичні записи auth.json очищуються, коли їх виявлено.
• Застарілі імпорти OAuth беруться з ~/.openclaw/credentials/oauth.json.
• Див. OAuth.
• Поведінка секретів під час виконання та інструменти 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: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: 1). Форми зайнятості провайдера, як-от ModelNotReadyException, потрапляють сюди.
• overloadedBackoffMs: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: 0).
• rateLimitedProfileRotations: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок обмеження частоти перед переходом до резервної моделі (типово: 1). Ця група обмежень частоти включає тексти у форматі провайдера, як-от 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: 600000,

    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,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: 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 відступають, доки стан не змінюється.
• stuckSessionAbortMs: поріг віку без прогресу в мс, після якого придатну завислу активну роботу можна аварійно злити для відновлення. Якщо не задано, OpenClaw використовує безпечніше розширене вікно вбудованого запуску щонайменше 10 хвилин і 5x stuckSessionWarnMs.
• 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.sampleRate: частота вибірки трас 0-1.
• otel.flushIntervalMs: періодичний інтервал скидання телеметрії в мс.
• otel.captureContent: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве true захоплює несистемний вміст повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути inputMessages, outputMessages, toolInputs, toolOutputs і systemPrompt.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут gen_ai.system для сумісності; метрики GenAI використовують обмежені семантичні атрибути.
• OPENCLAW_OTEL_PRELOADED=1: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/зупинку SDK, що належить Plugin, зберігаючи активними діагностичні слухачі.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT і OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: змінні середовища кінцевих точок для окремих сигналів, що використовуються, коли відповідний ключ конфігурації не задано.
• cacheTrace.enabled: журналювати знімки трасування кешу для вбудованих запусків (типово: false).
• cacheTrace.filePath: шлях виводу для JSONL трасування кешу (типово: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: керують тим, що включається у вивід трасування кешу (усі типово: 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: мінімальна затримка в годинах перед авто-застосуванням стабільного каналу (типово: 6; максимум: 168).
• auto.stableJitterHours: додаткове вікно розподілу розгортання стабільного каналу в годинах (типово: 12; максимум: 168).
• auto.betaCheckIntervalHours: як часто виконуються перевірки бета-каналу в годинах (типово: 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: глобальний функціональний шлюз ACP (типово: true; встановіть false, щоб приховати dispatch ACP і можливості spawn).
• dispatch.enabled: незалежний шлюз для dispatch ходу сесії ACP (типово: true). Встановіть false, щоб залишити команди ACP доступними, блокуючи виконання.
• backend: типовий ідентифікатор бекенда середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). Спершу встановіть Plugin бекенда, а якщо задано plugins.allow, включіть ідентифікатор Plugin бекенда (наприклад acpx), інакше бекенд ACP не завантажиться.
• defaultAgent: резервний ідентифікатор цільового агента ACP, коли spawns не вказують явну ціль.
• allowedAgents: allowlist ідентифікаторів агентів, дозволених для сесій середовища виконання ACP; порожній список означає відсутність додаткових обмежень.
• maxConcurrentSessions: максимальна кількість одночасно активних сесій ACP.
• stream.coalesceIdleMs: вікно скидання під час простою в мс для потокового тексту.
• stream.maxChunkChars: максимальний розмір фрагмента перед розділенням проєкції потокового блоку.
• stream.repeatSuppression: пригнічувати повторювані рядки статусу/інструментів за хід (типово: true).
• stream.deliveryMode: "live" транслює поступово; "final_only" буферизує до завершальних подій ходу.
• stream.hiddenBoundarySeparator: розділювач перед видимим текстом після прихованих подій інструментів (типово: "paragraph").
• stream.maxOutputChars: максимальна кількість символів виводу асистента, проєктованих за хід ACP.
• stream.maxSessionUpdateChars: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP.
• stream.tagVisibility: запис назв тегів у булеві перевизначення видимості для потокових подій.
• runtime.ttlMinutes: TTL простою в хвилинах для воркерів сесії ACP перед придатним очищенням.
• runtime.installCommand: необов’язкова команда інсталяції, яку потрібно виконати під час початкового налаштування середовища виконання ACP.

# CLI

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

• cli.banner.taglineMode керує стилем слогана банера:
  • "random" (типово): ротаційні кумедні/сезонні слогани.
  • "default": фіксований нейтральний слоган (All your chats, one OpenClaw.).
  • "off": без тексту слогана (назва/версія банера все одно показуються).
• Щоб приховати весь банер (а не лише слогани), задайте env 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-міст. Вузли підключаються через WebSocket Gateway. Ключі bridge.* більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; openclaw doctor --fix може видалити невідомі ключі).

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

# Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // 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/runs/<jobId>.jsonl) перед обрізанням. За замовчуванням: 2_000_000 байтів.
• runLog.keepLines: найновіші рядки, що зберігаються під час обрізання журналу запуску. За замовчуванням: 2000.
• webhookToken: bearer-токен, який використовується для POST-доставки cron webhook (delivery.mode = "webhook"); якщо пропущено, заголовок автентифікації не надсилається.
• webhook: застаріла резервна URL-адреса webhook (http/https), що використовується лише для збережених завдань, які досі мають notify: true.

# cron.retry

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

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

Застосовується лише до одноразових завдань cron. Повторювані завдання використовують окрему обробку збоїв.

# 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" публікує в налаштований webhook.
• accountId: необов’язковий обліковий запис або ідентифікатор каналу для обмеження області доставки сповіщень.

# cron.failureDestination

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

• Типове місце призначення для сповіщень про збої cron в усіх завданнях.
• mode: "announce" або "webhook"; за замовчуванням "announce", коли є достатньо даних цілі.
• channel: перевизначення каналу для доставки announce. "last" повторно використовує останній відомий канал доставки.
• to: явна ціль announce або URL webhook. Обов’язково для режиму webhook.
• accountId: необов’язкове перевизначення облікового запису для доставки.
• delivery.failureDestination окремого завдання перевизначає це глобальне значення за замовчуванням.
• Коли не задано ні глобальне, ні окреме для завдання місце призначення збоїв, завдання, які вже доставляють через announce, у разі збою повертаються до основної цілі 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). Абсолютні форми/форми з ../ дозволені лише тоді, коли вони все одно розв’язуються всередині цієї межі.
• Записи, що належать OpenClaw і змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються наскрізно в цей включений файл. Наприклад, plugins install оновлює plugins: { $include: "./plugins.json5" } у plugins.json5 і залишає openclaw.json недоторканим.
• Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні лише для читання для записів, що належать OpenClaw; такі записи завершуються закритою помилкою замість сплющення конфігурації.
• Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних включень.

Пов’язане: Конфігурація · Приклади конфігурації · Doctor

# Пов’язане

• Конфігурація
• Приклади конфігурації