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

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for 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 керує зменшенням масштабу зображень у transcript/tool (типово 1200); нижчі значення зазвичай зменшують використання vision-token у запусках із великою кількістю скриншотів.
• Дивіться Models CLI для перемикання моделей у чаті та Model Failover для ротації автентифікації й поведінки резервування.
• Для власних/self-hosted провайдерів дивіться Custom providers у довіднику.

Доступ до DM контролюється для кожного каналу через dmPolicy:

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

Для груп використовуйте groupPolicy + groupAllowFrom або списки дозволених, специфічні для каналу.

Дивіться повний довідник для подробиць щодо кожного каналу.

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

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

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

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no 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, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
• Дивіться Health Checks для операційного налагодження та повний довідник для всіх полів.

Дайте локальним клієнтам більше часу, щоб завершити pre-auth WebSocket-рукостискання на навантажених або малопотужних хостах:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Типове значення — 15000 мілісекунд.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS усе ще має пріоритет для одноразових перевизначень сервісу або shell.
• Спершу краще виправити зависання запуску/event-loop; цей параметр призначений для хостів, які справні, але повільні під час прогрівання.

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

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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: глобальні стандартні значення для маршрутизації сесій, прив’язаних до потоків (Discord підтримує /focus, /unfocus, /agents, /session idle і /session max-age).
• Див. Керування сесіями щодо областей дії, зв’язків ідентичностей і політики надсилання.
• Див. повний довідник для всіх полів.

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

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

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

Див. Пісочниця для повного посібника та повний довідник для всіх параметрів.

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

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

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

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

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

Що це робить:

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

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

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

Операційні примітки:

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

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

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

Див. Програма iOS для наскрізного потоку та Потік автентифікації й довіри для моделі безпеки relay.

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

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

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: видаляти завершені ізольовані сесії запусків із sessions.json (стандартно 24h; задайте false, щоб вимкнути).
• runLog: обрізати збережені рядки історії запусків Cron для кожного завдання. maxBytes залишається прийнятим для старіших файлових журналів запусків.
• Див. Завдання Cron для огляду функції та прикладів CLI.

Увімкніть 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,      },    ],  },}

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

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

Див. повний довідник для всіх параметрів зіставлення та інтеграції 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"],  },}

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