Конфігурація

Кожен канал має власний розділ конфігурації в channels.<provider>. Кроки налаштування див. на спеціальній сторінці відповідного каналу:

• Discord — channels.discord
• Feishu — channels.feishu
• Google Chat — channels.googlechat
• iMessage — channels.imessage
• Mattermost — channels.mattermost
• Microsoft Teams — channels.msteams
• Signal — channels.signal
• Slack — channels.slack
• Telegram — channels.telegram
• WhatsApp — channels.whatsapp

Усі канали використовують однаковий шаблон політики особистих повідомлень:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // лише для allowlist/open    },  },}

Задайте основну модель і необов’язкові резервні моделі:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models визначає каталог моделей і слугує списком дозволених значень для /model; записи provider/* фільтрують /model, /models та засоби вибору моделей до вибраних постачальників, водночас і надалі використовуючи динамічне виявлення моделей.
• Використовуйте openclaw config set agents.defaults.models '<json>' --strict-json --merge, щоб додавати записи до списку дозволених, не видаляючи наявні моделі. Звичайні заміни, які видалили б записи, відхиляються, якщо не передати --replace.
• Посилання на моделі використовують формат provider/model (наприклад, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx керує зменшенням розміру зображень у транскриптах та інструментах (стандартне значення — 1200); менші значення зазвичай скорочують використання токенів комп’ютерного зору під час запусків із великою кількістю знімків екрана.
• Відомості про перемикання моделей у чаті див. у CLI моделей, а про ротацію автентифікації та поведінку резервних моделей — у Перемиканні моделей у разі відмови.
• Відомості про власних або самостійно розміщених постачальників див. у розділі Власні постачальники довідника.

Доступ до особистих повідомлень контролюється окремо для кожного каналу через dmPolicy (стандартне значення — "pairing"):

• "pairing": невідомі відправники отримують одноразовий код сполучення для схвалення
• "allowlist": дозволено лише відправникам із allowFrom (або зі сховища дозволених сполучених відправників)
• "open": дозволити всі вхідні особисті повідомлення (потребує allowFrom: ["*"])
• "disabled": ігнорувати всі особисті повідомлення

Для груп використовуйте groupPolicy ("allowlist" | "open" | "disabled") разом із groupAllowFrom або списками дозволених значень для конкретних каналів.

Докладні відомості для кожного каналу див. у повному довіднику.

За замовчуванням групові повідомлення потребують згадки. Налаштуйте шаблони активації для кожного агента. Звичайні відповіді в групах і каналах надсилаються автоматично; увімкніть шлях через інструмент повідомлень для спільних кімнат, де агент має вирішувати, коли відповідати:

{  messages: {    visibleReplies: "automatic", // встановіть "message_tool", щоб усюди вимагати надсилання через інструмент повідомлень    groupChat: {      visibleReplies: "message_tool", // за явною згодою; видимий результат потребує message(action=send)      unmentionedInbound: "room_event", // групове спілкування без згадок, яке завжди надходить, є тихим контекстом    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Згадки в метаданих: нативні @-згадки (торкніться для згадки у WhatsApp, @bot у Telegram тощо)
• Текстові шаблони: безпечні шаблони регулярних виразів у mentionPatterns
• Видимі відповіді: messages.visibleReplies може глобально вимагати надсилання через інструмент повідомлень; messages.groupChat.visibleReplies перевизначає це для груп і каналів.
• Режими видимих відповідей, перевизначення для окремих каналів і режим чату із собою див. у повному довіднику.

Використовуйте agents.defaults.skills як спільну основу, а потім перевизначайте її для окремих агентів за допомогою agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // успадковує github, weather      { id: "docs", skills: ["docs-search"] }, // замінює стандартні значення      { id: "locked-down", skills: [] }, // без Skills    ],  },}

• Не вказуйте agents.defaults.skills, щоб Skills за замовчуванням не мали обмежень.
• Не вказуйте agents.list[].skills, щоб успадкувати стандартні значення.
• Установіть agents.list[].skills: [], щоб не використовувати Skills.
• Див. Skills, Конфігурація Skills і Довідник із конфігурації.

Визначте, наскільки активно Gateway перезапускатиме канали, що здаються неактивними:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Показані значення є стандартними. Установіть gateway.channelHealthCheckMinutes: 0, щоб глобально вимкнути перезапуски моніторингом стану.
• channelStaleEventThresholdMinutes має бути більшим або дорівнювати інтервалу перевірки.
• Використовуйте channels.<provider>.healthMonitor.enabled або channels.<provider>.accounts.<id>.healthMonitor.enabled, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису, не вимикаючи глобальний моніторинг.
• Відомості про діагностику роботи див. у розділі Перевірки стану, а опис усіх полів — у повному довіднику.

Надайте локальним клієнтам більше часу для завершення рукостискання WebSocket перед автентифікацією на навантажених або малопотужних хостах:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• За замовчуванням — 15000 мілісекунд.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS усе ще має пріоритет для одноразових перевизначень служби або оболонки.
• Спочатку бажано усунути зависання під час запуску або в циклі подій; цей параметр призначений для справних хостів, які повільно прогріваються.

Сеанси керують безперервністю та ізоляцією розмов:

{  session: {    dmScope: "per-channel-peer",  // рекомендовано для кількох користувачів    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (спільний) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: глобальні типові параметри маршрутизації сеансів, прив’язаних до гілок. /focus, /unfocus, /agents, /session idle і /session max-age відповідно прив’язують, відв’язують, показують список і налаштовують це для кожного сеансу (Discord прив’язує гілки, Telegram — теми/розмови).
• Відомості про області дії, зв’язки ідентичностей і політику надсилання див. у розділі Керування сеансами.
• Опис усіх полів див. у повному довіднику.

Запускайте сеанси агентів в ізольованих середовищах виконання пісочниці:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Спочатку зберіть образ: із робочої копії вихідного коду виконайте scripts/sandbox-setup.sh, а для встановлення з npm див. вбудовану команду docker build у розділі Пісочниця § Образи та налаштування.

Повний посібник див. у розділі Пісочниця, а всі параметри — у повному довіднику.

Для push-сповіщень у загальнодоступних збірках з App Store використовується розміщений ретранслятор OpenClaw: https://ios-push-relay.openclaw.ai.

Власні розгортання ретранслятора потребують навмисно відокремленого процесу збирання та розгортання iOS, у якому URL-адреса ретранслятора збігається з URL-адресою ретранслятора Gateway. Якщо використовується власна збірка з ретранслятором, задайте це в конфігурації Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Необов’язково. За замовчуванням: 10000          timeoutMs: 10000,        },      },    },  },}

Еквівалент у CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Результат:

• Дає Gateway змогу надсилати push.test, сигнали пробудження та пробудження для повторного підключення через зовнішній ретранслятор.
• Використовує дозвіл на надсилання, обмежений реєстрацією, який передає спарений застосунок iOS. Gateway не потребує токена ретранслятора для всього розгортання.
• Прив’язує кожну реєстрацію через ретранслятор до ідентичності Gateway, з якою спарено застосунок iOS, щоб інший Gateway не міг повторно використати збережену реєстрацію.
• Зберігає пряме використання APNs для локальних або ручних збірок iOS. Надсилання через ретранслятор застосовується лише до офіційно розповсюджуваних збірок, зареєстрованих через ретранслятор.
• Має збігатися з базовою URL-адресою ретранслятора, вбудованою у збірку iOS, щоб трафік реєстрації та надсилання надходив до одного розгортання ретранслятора.

Наскрізний процес:

1. Установіть офіційний застосунок iOS.
2. Необов’язково: налаштуйте gateway.push.apns.relay.baseUrl у Gateway лише в разі використання навмисно відокремленої власної збірки з ретранслятором.
3. Спарте застосунок iOS із Gateway і дозвольте підключитися сеансам Node та оператора.
4. Застосунок iOS отримує ідентичність Gateway, реєструється в ретрансляторі за допомогою App Attest і квитанції застосунку, а потім публікує корисне навантаження push.apns.register через ретранслятор у спареному Gateway.
5. Gateway зберігає дескриптор ретранслятора й дозвіл на надсилання, а потім використовує їх для push.test, сигналів пробудження та пробуджень для повторного підключення.

Примітки щодо експлуатації:

• Якщо застосунок iOS перемкнено на інший Gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію ретранслятора, прив’язану до цього Gateway.
• Якщо випущено нову збірку iOS, яка використовує інше розгортання ретранслятора, застосунок оновить кешовану реєстрацію ретранслятора замість повторного використання старого джерела ретранслятора.

Примітка щодо сумісності:

• OPENCLAW_APNS_RELAY_BASE_URL і OPENCLAW_APNS_RELAY_TIMEOUT_MS усе ще працюють як тимчасові перевизначення через змінні середовища.
• Власні URL-адреси ретранслятора Gateway мають збігатися з базовою URL-адресою ретранслятора, вбудованою у збірку iOS; загальнодоступний канал випуску App Store відхиляє перевизначення URL-адреси ретранслятора iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true залишається аварійним механізмом лише для розробки через зворотний інтерфейс; не зберігайте URL-адреси HTTP-ретранслятора в конфігурації.

Наскрізний процес див. у розділі Застосунок iOS, а модель безпеки ретранслятора — у розділі Процес автентифікації та встановлення довіри.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: рядок тривалості (30m, 2h). Щоб вимкнути, задайте 0m. За замовчуванням: 30m.
• target: last | none | <channel-id> (наприклад, discord, matrix, telegram або whatsapp)
• directPolicy: allow (за замовчуванням) або block для цілей Heartbeat у стилі особистих повідомлень
• Повний посібник див. у розділі Heartbeat.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // за замовчуванням; диспетчеризація Cron + ізольоване виконання ходу агента Cron    sessionRetention: "24h",  },}

• sessionRetention: видаляє завершені ізольовані сеанси запуску з рядків сеансів SQLite (за замовчуванням 24h; щоб вимкнути, задайте false).
• У журналі запусків автоматично зберігаються 2000 найновіших кінцевих рядків для кожного завдання; для втрачених рядків зберігається 24-годинне вікно очищення.
• Огляд функції та приклади CLI див. у розділі Завдання Cron.

Увімкніть кінцеві точки HTTP Webhook у Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

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

• Вважайте весь вміст корисного навантаження обробників/Webhook недовіреними вхідними даними.
• Використовуйте окремий hooks.token; не використовуйте повторно активні секрети автентифікації Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN або gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Автентифікація обробників виконується лише через заголовки (Authorization: Bearer ... або x-openclaw-token); токени в рядку запиту відхиляються.
• hooks.path не може бути /; розміщуйте вхідний трафік Webhook в окремому підшляху, наприклад /hooks.
• Не вмикайте прапорці обходу перевірки небезпечного вмісту (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), крім випадків суворо обмеженого налагодження.
• Якщо ввімкнено hooks.allowRequestSessionKey, також задайте hooks.allowedSessionKeyPrefixes, щоб обмежити ключі сеансів, які може вибирати викликач.
• Для агентів, керованих обробниками, віддавайте перевагу потужним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями та, де можливо, пісочниця).

Усі параметри зіставлення та інтеграцію з Gmail див. у повному довіднику.

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

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

Правила прив’язування та профілі доступу для кожного агента див. у розділах Кілька агентів і повний довідник.

Використовуйте $include для впорядкування великих конфігурацій:

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

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