docs/docs/uk/gateway/configuration-reference.md

read_when	summary	title	x-i18n
Вам потрібні точні семантики полів конфігурації або значення за замовчуванням Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента	Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем	Довідник з конфігурації	generated_at model provider source_hash source_path workflow 2026-04-26T01:42:39Z gpt-5.4 openai 6197fab3f114cf237de46ea7c06c355be179e7b78ae39920b45bb094a04127b9 gateway/configuration-reference.md 15

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

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

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

• openclaw config schema виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із вбудованими метаданими bundled/plugin/channel, об’єднаними за наявності
• config.schema.lookup повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду
• pnpm config:docs:check / pnpm config:docs:gen перевіряють хеш базового стану документації конфігурації щодо поточної поверхні схеми

Окремі поглиблені довідники:

• Memory configuration reference для agents.defaults.memorySearch.*, memory.qmd.*, memory.citations і конфігурації dreaming у plugins.entries.memory-core.config.dreaming
• Slash commands для поточного вбудованого + bundled каталогу команд
• сторінки каналу/Plugin-власника для специфічних для каналу поверхонь команд

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

---

Канали

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

Типові значення агента, multi-agent, сесії та повідомлення

Перенесено на окрему сторінку — див. Configuration — agents для:

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

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

Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / base-URL перенесені на окрему сторінку — див. Configuration — tools and custom providers.

MCP

Визначення MCP-серверів, керованих OpenClaw, знаходяться в mcp.servers і використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди 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-серверів для середовищ виконання, які надають налаштовані MCP-інструменти.
• mcp.sessionIdleTtlMs: idle TTL для MCP-середовищ виконання в межах сесії. Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для довготривалих сесій і майбутніх викликів.
• Зміни в mcp.* застосовуються гаряче через вивільнення кешованих MCP-середовищ виконання сесії. Наступне виявлення/використання інструменту створює їх заново з нової конфігурації, тому видалені записи mcp.servers прибираються негайно, а не очікують завершення idle TTL.

Див. MCP і CLI backends для поведінки середовища виконання.

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

• Завантажуються з ~/.openclaw/extensions, <workspace>/.openclaw/extensions і plugins.load.paths.
• Виявлення підтримує нативні OpenClaw Plugins, а також сумісні пакети Codex і Claude, включно з пакетами Claude без manifest із типовою структурою каталогів.
• Зміни конфігурації потребують перезапуску gateway.
• allow: необов’язковий список дозволу (завантажуються лише перелічені Plugins). deny має пріоритет.
• plugins.entries.<id>.apiKey: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує).
• plugins.entries.<id>.env: карта змінних середовища в межах Plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: коли false, ядро блокує before_prompt_build та ігнорує поля, що змінюють prompt, із застарілого before_agent_start, водночас зберігаючи застарілі modelOverride і providerOverride. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих пакетами.
• plugins.entries.<id>.hooks.allowConversationAccess: коли true, довірені небудовані Plugins можуть читати необроблений вміст розмови з типізованих hooks, таких як llm_input, llm_output, before_agent_finalize і agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: явно довіряти цьому Plugin запитувати перевизначення provider і model для окремого запуску фонових підзапусків subagent.
• plugins.entries.<id>.subagent.allowedModels: необов’язковий список дозволу канонічних цілей provider/model для довірених перевизначень subagent. Використовуйте "*" лише тоді, коли навмисно хочете дозволити будь-яку модель.
• plugins.entries.<id>.config: об’єкт конфігурації, визначений Plugin (валідується схемою нативного OpenClaw Plugin, якщо вона доступна).
• Налаштування облікового запису/середовища виконання для канальних Plugins знаходяться в channels.<id> і мають бути описані метаданими channelConfigs у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw.
• plugins.entries.firecrawl.config.webFetch: налаштування провайдера Firecrawl web-fetch.
  • apiKey: API-ключ Firecrawl (приймає SecretRef). Використовує plugins.entries.firecrawl.config.webSearch.apiKey, застарілий tools.web.fetch.firecrawl.apiKey або змінну середовища FIRECRAWL_API_KEY, якщо не задано.
  • baseUrl: базовий URL API Firecrawl (типово: https://api.firecrawl.dev).
  • onlyMainContent: витягувати лише основний вміст зі сторінок (типово: true).
  • maxAgeMs: максимальний вік кешу в мілісекундах (типово: 172800000 / 2 дні).
  • timeoutSeconds: тайм-аут запиту зчитування в секундах (типово: 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-розклад для кожного повного циклу dreaming (типово "0 3 * * *").
  • політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації).
• Повна конфігурація пам’яті наведена в Memory configuration reference:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Увімкнені Plugins-пакети Claude також можуть додавати вбудовані типові значення Pi із settings.json; OpenClaw застосовує їх як санітизовані налаштування агента, а не як необроблені патчі конфігурації OpenClaw.
• plugins.slots.memory: вибрати ідентифікатор активного Plugin пам’яті або "none", щоб вимкнути Plugins пам’яті.
• plugins.slots.contextEngine: вибрати ідентифікатор активного Plugin рушія контексту; типово "legacy", якщо ви не встановите й не виберете інший рушій.

Див. Plugins.

---

Браузер

{
  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 для явних винятків.
• Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнені).
• 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 зберігають поточні обмеження маршруту Chrome MCP: дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks для завантаження одного файла, без перевизначення тайм-аутів діалогів, без 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

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

• seamColor: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо).
• 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
      // 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,
        },
      },
    },
  },
}

• mode: local (запустити gateway) або remote (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не local.
• port: єдиний мультиплексований порт для WS + HTTP. Пріоритет: --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789.
• bind: auto, loopback (типово), lan (0.0.0.0), tailnet (лише IP Tailscale) або custom.
• Застарілі псевдоніми bind: використовуйте значення режиму bind у gateway.bind (auto, loopback, lan, tailnet, custom), а не псевдоніми хоста (0.0.0.0, 127.0.0.1, localhost, ::, ::1).
• Примітка щодо Docker: типовий bind loopback слухає 127.0.0.1 усередині контейнера. Із bridge-мережею Docker (-p 18789:18789) трафік надходить через eth0, тому gateway недоступний. Використовуйте --network host або встановіть bind: "lan" (або bind: "custom" з customBindHost: "0.0.0.0"), щоб слухати на всіх інтерфейсах.
• Auth: типово обов’язкова. Для bind не на loopback потрібна auth gateway. На практиці це означає спільний token/password або reverse proxy з підтримкою ідентичності з gateway.auth.mode: "trusted-proxy". Майстер початкового налаштування типово генерує token.
• Якщо налаштовано і gateway.auth.token, і gateway.auth.password (включно з SecretRef), явно задайте gateway.auth.mode як token або password. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва, а mode не задано.
• gateway.auth.mode: "none": явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в підказках початкового налаштування.
• gateway.auth.mode: "trusted-proxy": делегувати auth reverse proxy з підтримкою ідентичності та довіряти заголовкам ідентичності з gateway.trustedProxies (див. Trusted Proxy Auth). Цей режим очікує джерело proxy не на loopback; reverse proxy loopback на тому самому хості не задовольняють auth trusted-proxy.
• gateway.auth.allowTailscale: коли true, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через tailscale whois). Кінцеві точки HTTP API не використовують цю auth через заголовки Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей потік без token передбачає, що хост gateway є довіреним. Типово true, коли tailscale.mode = "serve".
• gateway.auth.rateLimit: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта та для кожної області auth (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають 429 + Retry-After.
  • На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого {scope, clientIp} серіалізуються перед записом невдачі. Тому одночасні невдалі спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли паралельно як звичайні невідповідності.
  • gateway.auth.rateLimit.exemptLoopback типово має значення true; установіть false, якщо навмисно хочете, щоб трафік localhost теж підпадав під обмеження швидкості (для тестових налаштувань або суворих розгортань через proxy).
• Спроби WS auth із джерелом browser завжди обмежуються без звільнення для loopback (додатковий захист від brute force localhost через browser).
• На loopback ці блокування для джерел browser ізолюються за нормалізованим значенням Origin, тому повторні невдачі з одного localhost origin не призводять автоматично до блокування іншого origin.
• tailscale.mode: serve (лише tailnet, bind на loopback) або funnel (публічно, потребує auth).
• controlUi.allowedOrigins: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти з origin не на loopback.
• controlUi.dangerouslyAllowHostHeaderOriginFallback: небезпечний режим, який вмикає fallback origin через заголовок Host для розгортань, що навмисно покладаються на політику origin через заголовок Host.
• remote.transport: ssh (типово) або direct (ws/wss). Для direct remote.url має бути ws:// або wss://.
• OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: аварійне перевизначення через змінну середовища процесу на стороні клієнта, яке дозволяє незашифрований ws:// до довірених IP приватної мережі; типово незашифрований трафік і далі дозволено лише для loopback. Еквівалента в openclaw.json немає, а конфігурація приватної мережі browser, така як browser.ssrfPolicy.dangerouslyAllowPrivateNetwork, не впливає на клієнти Gateway WebSocket.
• gateway.remote.token / .password — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway.
• gateway.push.apns.relay.baseUrl: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed до gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS.
• gateway.push.apns.relay.timeoutMs: тайм-аут надсилання від gateway до relay у мілісекундах. Типово 10000.
• Реєстрації relay-backed делегуються конкретній ідентичності gateway. Пов’язаний застосунок iOS отримує gateway.identity.get, включає цю ідентичність у реєстрацію relay і передає до gateway право надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
• OPENCLAW_APNS_RELAY_BASE_URL / OPENCLAW_APNS_RELAY_TIMEOUT_MS: тимчасові перевизначення через env для наведеної вище конфігурації relay.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true: лише для розробки, аварійний дозвіл для URL relay HTTP на loopback. У production URL relay мають лишатися на HTTPS.
• gateway.channelHealthCheckMinutes: інтервал моніторингу стану каналів у хвилинах. Установіть 0, щоб глобально вимкнути перезапуски health-monitor. Типово: 5.
• gateway.channelStaleEventThresholdMinutes: поріг застарілого сокета в хвилинах. Зберігайте це значення більшим або рівним gateway.channelHealthCheckMinutes. Типово: 30.
• gateway.channelMaxRestartsPerHour: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типово: 10.
• channels.<provider>.healthMonitor.enabled: відмова на рівні каналу від перезапусків health-monitor зі збереженням глобального монітора увімкненим.
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу.
• Локальні шляхи виклику gateway можуть використовувати gateway.remote.* як fallback лише тоді, коли gateway.auth.* не задано.
• Якщо gateway.auth.token / gateway.auth.password явно налаштовано через SecretRef і не вдається розв’язати, розв’язання завершується fail closed (без маскування через fallback до remote).
• trustedProxies: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Перелічуйте лише proxy, які ви контролюєте. Записи loopback усе ще допустимі для налаштувань proxy на тому самому хості/визначення локального джерела (наприклад, Tailscale Serve або локальний reverse proxy), але вони не роблять запити loopback придатними для gateway.auth.mode: "trusted-proxy".
• allowRealIpFallback: коли true, gateway приймає X-Real-IP, якщо X-Forwarded-For відсутній. Типово false для поведінки fail closed.
• gateway.nodes.pairing.autoApproveCidrs: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого pairing вузла пристрою без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat і не схвалює автоматично підвищення ролі, областей доступу, метаданих або відкритого ключа.
• gateway.nodes.allowCommands / gateway.nodes.denyCommands: глобальне налаштування allow/deny для оголошених команд вузла після pairing і оцінювання списку дозволу.
• gateway.tools.deny: додаткові назви інструментів, заблоковані для HTTP POST /tools/invoke (розширює типовий список deny).
• gateway.tools.allow: прибрати назви інструментів із типового списку deny HTTP.

Кінцеві точки, сумісні з 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, які ви контролюєте; див. Trusted Proxy Auth)

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

Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану:

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

Зручні прапорці: --dev (використовує ~/.openclaw-dev + порт 19001), --profile <name> (використовує ~/.openclaw-<name>).

Див. Multiple Gateways.

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

gateway.reload

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

• mode: керує тим, як зміни конфігурації застосовуються під час виконання.
  • "off": ігнорувати зміни в реальному часі; зміни потребують явного перезапуску.
  • "restart": завжди перезапускати процес gateway при зміні конфігурації.
  • "hot": застосовувати зміни в процесі без перезапуску.
  • "hybrid" (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску.
• debounceMs: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
• deferralTimeoutMs: необов’язковий максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском. Пропустіть його або встановіть 0, щоб чекати безстроково й періодично журналювати попередження про те, що ще є незавершені операції.

---

Hooks

{
  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",
      },
    ],
  },
}

Auth: Authorization: Bearer <token> або x-openclaw-token: <token>. Hook-token у рядку запиту відхиляються.

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

• hooks.enabled=true потребує непорожнього hooks.token.
• hooks.token має відрізнятися від gateway.auth.token; повторне використання token Gateway відхиляється.
• hooks.path не може бути /; використовуйте окремий підшлях, наприклад /hooks.
• Якщо hooks.allowRequestSessionKey=true, обмежте hooks.allowedSessionKeyPrefixes (наприклад ["hook:"]).
• Якщо mapping або preset використовує шаблонізований sessionKey, задайте hooks.allowedSessionKeyPrefixes і hooks.allowRequestSessionKey=true. Статичні ключі mapping не потребують цього явного дозволу.

Кінцеві точки:

• 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 у mapping, згенеровані через шаблон, вважаються наданими ззовні й також потребують hooks.allowRequestSessionKey=true.

• match.path відповідає підшляху після /hooks (наприклад, /hooks/gmail → gmail).
• match.source відповідає полю payload для узагальнених шляхів.
• Шаблони на кшталт {{messages[0].subject}} читають дані з payload.
• transform може вказувати на модуль JS/TS, який повертає дію hook.
  • transform.module має бути відносним шляхом і залишатися в межах hooks.transformsDir (абсолютні шляхи та traversal відхиляються).
• agentId маршрутизує до конкретного агента; невідомі ID повертаються до типового.
• allowedAgentIds: обмежує явну маршрутизацію (* або пропущено = дозволити всі, [] = заборонити всі).
• defaultSessionKey: необов’язковий фіксований ключ сесії для запусків hook-агента без явного sessionKey.
• allowRequestSessionKey: дозволяє викликачам /hooks/agent і ключам сесії mapping, керованим шаблонами, задавати sessionKey (типово: false).
• allowedSessionKeyPrefixes: необов’язковий список дозволених префіксів для явних значень sessionKey (запит + mapping), наприклад ["hook:"]. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований sessionKey.
• deliver: true надсилає фінальну відповідь у канал; channel типово має значення last.
• model перевизначає LLM для цього запуску hook (має бути дозволений, якщо налаштовано каталог моделей).

Інтеграція Gmail

• Вбудований preset Gmail використовує sessionKey: "hook:gmail:{{messages[0].id}}".
• Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть hooks.allowRequestSessionKey: true і обмежте hooks.allowedSessionKeyPrefixes, щоб вони відповідали простору імен Gmail, наприклад ["hook:", "hook:gmail:"].
• Якщо вам потрібен hooks.allowRequestSessionKey: false, перевизначте preset статичним 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.

---

Хост Canvas

{
  canvasHost: {
    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" (типово).
• Для bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
• Node WebViews зазвичай не надсилають заголовки auth; після pairing і підключення вузла Gateway оголошує URL можливостей із областю вузла для доступу до canvas/A2UI.
• URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Fallback на основі IP не використовується.
• Впроваджує клієнт live-reload у HTML, що обслуговується.
• Автоматично створює стартовий index.html, якщо каталог порожній.
• Також обслуговує A2UI за адресою /__openclaw__/a2ui/.
• Зміни потребують перезапуску gateway.
• Вимикайте live reload для великих каталогів або при помилках EMFILE.

---

Виявлення

mDNS (Bonjour)

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

• minimal (типово): не включає cliPath + sshPort до записів TXT.
• full: включає cliPath + sshPort.
• Назва хоста типово openclaw. Перевизначайте через OPENCLAW_MDNS_HOSTNAME.

Wide-area (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 поточного робочого каталогу + ~/.openclaw/.env (жоден із них не перевизначає наявні змінні).
• shellEnv: імпортує відсутні очікувані ключі з профілю вашої оболонки входу.
• Див. Environment для повного пріоритету.

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

Посилайтеся на змінні середовища в будь-якому рядку конфігурації через ${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}$
• source: "file" id: абсолютний JSON pointer (наприклад "/providers/openai/apiKey")
• шаблон id для source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• source: "exec" id не повинні містити сегменти шляху . або .., розділені / (наприклад, a/../b відхиляється)

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

• Канонічна матриця: SecretRef Credential Surface
• 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" (у режимі singleValue id має бути "value").
• Шляхи провайдерів file і exec завершуються fail closed, коли перевірка Windows ACL недоступна. Установлюйте allowInsecurePath: true лише для довірених шляхів, які неможливо перевірити.
• Провайдер exec вимагає абсолютний шлях command і використовує payload протоколу через stdin/stdout.
• Типово шляхи команд-символічних посилань відхиляються. Установіть allowSymlinkCommand: true, щоб дозволити шляхи-символічні посилання з перевіркою шляху розв’язаного цільового файла.
• Якщо налаштовано trustedDirs, перевірка довірених каталогів застосовується до шляху розв’язаної цілі.
• Дочірнє середовище exec типово мінімальне; передавайте потрібні змінні явно через passEnv.
• Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок.
• Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.

---

Сховище auth

{
  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) для статичних режимів облікових даних.
• Профілі режиму OAuth (auth.profiles.<id>.mode = "oauth") не підтримують облікові дані профілів auth із підтримкою SecretRef.
• Статичні облікові дані під час виконання надходять зі знімків, розв’язаних у пам’яті; застарілі статичні записи auth.json очищуються при виявленні.
• Застарілі імпорти OAuth беруться з ~/.openclaw/credentials/oauth.json.
• Див. OAuth.
• Поведінка секретів під час виконання та інструменти audit/configure/apply: Secrets Management.

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: базовий backoff у годинах, коли профіль зазнає невдачі через справжні помилки білінгу/недостатнього кредиту (типово: 5). Явний текст про білінг усе ще може потрапити сюди навіть для відповідей 401/403, але провайдер-специфічні засоби зіставлення тексту залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter Key limit exceeded). Повторювані HTTP 402 повідомлення про вікно використання або ліміт витрат організації/робочого простору натомість залишаються в шляху rate_limit.
• billingBackoffHoursByProvider: необов’язкові перевизначення годин backoff для білінгу на рівні провайдера.
• billingMaxHours: обмеження в годинах для експоненційного зростання backoff білінгу (типово: 24).
• authPermanentBackoffMinutes: базовий backoff у хвилинах для збоїв auth_permanent із високою впевненістю (типово: 10).
• authPermanentMaxMinutes: обмеження в хвилинах для зростання backoff auth_permanent (типово: 60).
• failureWindowHours: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: 24).
• overloadedProfileRotations: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: 1). Сюди потрапляють форми на кшталт ModelNotReadyException, коли провайдер зайнятий.
• overloadedBackoffMs: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: 0).
• rateLimitedProfileRotations: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: 1). До цього кошика 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: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: 524288000 = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.

---

Діагностика

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,

    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: поріг віку в мс для виводу попереджень про завислі сесії, поки сесія залишається в стані обробки.
• otel.enabled: вмикає конвеєр експорту OpenTelemetry (типово: false). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у OpenTelemetry export.
• 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: увімкнути експорт trace, metrics або logs.
• otel.sampleRate: частота семплювання trace 0–1.
• otel.flushIntervalMs: інтервал періодичного скидання telemetry у мс.
• otel.captureContent: явний дозвіл на захоплення необробленого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення true захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно вмикати inputMessages, outputMessages, toolInputs, toolOutputs і systemPrompt.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово span зберігають застарілий атрибут gen_ai.system для сумісності; metrics 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: мінімальна затримка в годинах перед автозастосуванням на каналі stable (типово: 6; максимум: 168).
• auto.stableJitterHours: додаткове вікно розподілу розгортання для каналу 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 і spawn ACP).
• dispatch.enabled: незалежний gate для dispatch ходу сесії ACP (типово: true). Установіть false, щоб зберегти команди ACP доступними, але заблокувати виконання.
• backend: типовий ідентифікатор backend середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). Якщо задано plugins.allow, включіть ідентифікатор Plugin backend (наприклад acpx), інакше bundled Plugin за замовчуванням не завантажиться.
• defaultAgent: резервний ідентифікатор цільового агента ACP, коли spawn не задають явну ціль.
• allowedAgents: список дозволених ідентифікаторів агентів для сесій середовища виконання ACP; порожнє значення означає відсутність додаткового обмеження.
• maxConcurrentSessions: максимальна кількість одночасно активних сесій ACP.
• stream.coalesceIdleMs: вікно idle-flush у мс для потокового тексту.
• stream.maxChunkChars: максимальний розмір фрагмента перед розбиттям проєкції потокового блока.
• stream.repeatSuppression: пригнічувати повторювані рядки status/tool у межах одного ходу (типово: true).
• stream.deliveryMode: "live" транслює поступово; "final_only" буферизує до термінальних подій ходу.
• stream.hiddenBoundarySeparator: роздільник перед видимим текстом після прихованих подій tool (типово: "paragraph").
• stream.maxOutputChars: максимальна кількість символів виводу асистента, що проєктуються за один хід ACP.
• stream.maxSessionUpdateChars: максимальна кількість символів для проєктованих рядків status/update ACP.
• stream.tagVisibility: запис назв тегів до булевих перевизначень видимості для потокових подій.
• runtime.ttlMinutes: idle TTL у хвилинах для worker сесій ACP до можливого очищення.
• runtime.installCommand: необов’язкова команда встановлення для запуску під час bootstrap середовища виконання ACP.

---

CLI

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

• cli.banner.taglineMode керує стилем підзаголовка banner:
  • "random" (типово): ротаційні кумедні/сезонні підзаголовки.
  • "default": фіксований нейтральний підзаголовок (Усі ваші чати, один OpenClaw.).
  • "off": без тексту підзаголовка (назва/версія banner усе ще показуються).
• Щоб приховати весь banner (а не лише підзаголовки), установіть env OPENCLAW_HIDE_BANNER=1.

---

Wizard

Метадані, які записуються керованими потоками налаштування CLI (onboard, configure, doctor):

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

---

Ідентичність

Див. поля ідентичності agents.list у Agent defaults.

---

Bridge (застарілий, вилучений)

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

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

---

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    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 token, що використовується для доставки POST Webhook Cron (delivery.mode = "webhook"); якщо пропущено, заголовок auth не надсилається.
• 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,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled: увімкнути сповіщення про збої для завдань Cron (типово: false).
• after: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: 1).
• cooldownMs: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
• 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: перевизначення каналу для доставки announce. "last" повторно використовує останній відомий канал доставки.
• to: явна ціль announce або URL Webhook. Обов’язкове для режиму webhook.
• accountId: необов’язкове перевизначення облікового запису для доставки.
• delivery.failureDestination для конкретного завдання перевизначає це глобальне значення за замовчуванням.
• Коли не задано ні глобальне, ні індивідуальне місце призначення збою, завдання, які вже доставляють через announce, у разі збою повертаються до цієї основної цілі announce.
• delivery.failureDestination підтримується лише для завдань sessionTarget="isolated", якщо тільки основний delivery.mode завдання не дорівнює "webhook".

Див. Cron Jobs. Ізольовані виконання Cron відстежуються як background tasks.

---

Змінні шаблону медіамоделі

Заповнювачі шаблону, що розгортаються в tools.media.models[].args:

Змінна	Опис
{{Body}}	Повний текст вхідного повідомлення
{{RawBody}}	Необроблений текст (без обгорток історії/відправника)
{{BodyStripped}}	Текст без згадок у групі
{{From}}	Ідентифікатор відправника
{{To}}	Ідентифікатор призначення
{{MessageSid}}	Ідентифікатор повідомлення каналу
{{SessionId}}	UUID поточної сесії
{{IsNewSession}}	"true", коли створено нову сесію
{{MediaUrl}}	Псевдо-URL вхідного медіа
{{MediaPath}}	Локальний шлях до медіа
{{MediaType}}	Тип медіа (image/audio/document/…)
{{Transcript}}	Транскрипт аудіо
{{Prompt}}	Розв’язаний prompt медіа для записів CLI
{{MaxChars}}	Розв’язана максимальна кількість символів виводу для записів CLI
{{ChatType}}	"direct" або "group"
{{GroupSubject}}	Назва групи (best effort)
{{GroupMembers}}	Попередній перегляд учасників групи (best effort)
{{SenderName}}	Відображуване ім’я відправника (best effort)
{{SenderE164}}	Номер телефону відправника (best effort)
{{Provider}}	Підказка провайдера (whatsapp, telegram, discord тощо)

---

Include конфігурації ($include)

Розділяйте конфігурацію на кілька файлів:

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

Поведінка злиття:

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

---

Пов’язане: Configuration · Configuration Examples · Doctor

Пов’язане

• Configuration
• Configuration examples