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

Кожен канал має власний розділ конфігурації в 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 визначає каталог моделей і діє як allowlist для /model.
• Використовуйте openclaw config set agents.defaults.models '<json>' --strict-json --merge, щоб додавати записи allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте --replace.
• Посилання на моделі використовують формат provider/model (наприклад, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx керує зменшенням зображень транскрипту/інструментів (типово 1200); нижчі значення зазвичай зменшують використання vision-токенів під час запусків із великою кількістю скриншотів.
• Дивіться Models CLI для перемикання моделей у чаті та Model Failover для ротації автентифікації й поведінки резервного переходу.
• Для користувацьких/self-hosted провайдерів дивіться Custom providers у довіднику.

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

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

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

Перегляньте повний довідник для деталей за каналами.

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

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  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 перевизначає це для груп/каналів.
• Перегляньте повний довідник щодо режимів видимих відповідей, перевизначень для окремих каналів і режиму чату із собою.

Використовуйте 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, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
• Перегляньте перевірки справності для операційного налагодження та повний довідник для всіх полів.

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

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Типове значення — 15000 мілісекунд.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS усе ще має пріоритет для одноразових перевизначень сервісу або оболонки.
• Спершу бажано виправити зависання запуску або 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).
• Дивіться керування сесіями щодо областей дії, зв’язків ідентичностей і політики надсилання.
• Дивіться повний довідник для всіх полів.

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

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

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

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

Push через relay налаштовується в openclaw.json.

Задайте це в конфігурації 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, wake nudges і пробудження для повторного підключення через зовнішній relay.
• Використовує дозвіл на надсилання з областю реєстрації, переданий спареним застосунком iOS. Gateway не потребує relay-токена для всього розгортання.
• Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою спарено застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію.
• Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовуються лише до офіційних розповсюджених збірок, які зареєструвалися через relay.
• Має збігатися з базовою URL-адресою relay, вбудованою в офіційну/TestFlight збірку iOS, щоб реєстраційний трафік і трафік надсилання потрапляли до того самого розгортання relay.

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

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL і OPENCLAW_APNS_RELAY_TIMEOUT_MS досі працюють як тимчасові перевизначення env.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true залишається development escape hatch лише для loopback; не зберігайте HTTP URL-адреси 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: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: видаляє завершені ізольовані сеанси запуску з sessions.json (типово 24h; задайте false, щоб вимкнути).
• runLog: обрізає cron/runs/<jobId>.jsonl за розміром і кількістю збережених рядків.
• Дивіться Завдання Cron для огляду можливості та прикладів CLI.

Увімкніть HTTP webhook endpoint-и на 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,
      },
    ],
  },
}

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

• Вважайте весь вміст payload hook/webhook недовіреним введенням.
• Використовуйте окремий hooks.token; не використовуйте повторно спільний токен Gateway.
• Автентифікація hook працює лише через заголовки (Authorization: Bearer ... або x-openclaw-token); токени в query string відхиляються.
• hooks.path не може бути /; тримайте webhook ingress на окремому підшляху, наприклад /hooks.
• Тримайте прапорці обходу небезпечного вмісту вимкненими (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), якщо не виконуєте вузько обмежене налагодження.
• Якщо ви вмикаєте hooks.allowRequestSessionKey, також задайте hooks.allowedSessionKeyPrefixes, щоб обмежити session keys, вибрані викликачем.
• Для агентів, керованих 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" } },
  ],
}

Дивіться Multi-Agent і повний довідник для правил прив’язування та профілів доступу окремих агентів.

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

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

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