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

У каждого канала есть собственный раздел конфигурации в 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; записи provider/* фильтруют /model, /models и средства выбора моделей до выбранных провайдеров, при этом по-прежнему используя динамическое обнаружение моделей.
• Используйте openclaw config set agents.defaults.models '<json>' --strict-json --merge, чтобы добавить записи allowlist без удаления существующих моделей. Обычные замены, которые удалили бы записи, отклоняются, если не передать --replace.
• Ссылки на модели используют формат provider/model (например, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx управляет уменьшением изображений стенограммы/инструментов (по умолчанию 1200); более низкие значения обычно уменьшают использование vision-токенов в запусках с большим количеством скриншотов.
• См. CLI моделей для переключения моделей в чате и аварийное переключение моделей для ротации auth и поведения резервных вариантов.
• Для пользовательских/самостоятельно размещенных провайдеров см. пользовательские провайдеры в справочнике.

Доступ к 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", // 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 переопределяет это для групп/каналов.
• См. полный справочник по режимам видимых ответов, переопределениям для каналов и режиму чата с самим собой.

Используйте 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, чтобы глобально отключить перезапуски health monitor.
• channelStaleEventThresholdMinutes должен быть больше интервала проверки или равен ему.
• Используйте channels.<provider>.healthMonitor.enabled или channels.<provider>.accounts.<id>.healthMonitor.enabled, чтобы отключить автоматические перезапуски для одного канала или аккаунта, не отключая глобальный монитор.
• См. проверки работоспособности для операционной отладки и полный справочник по всем полям.

Дайте локальным клиентам больше времени на завершение pre-auth WebSocket handshake на загруженных или маломощных хостах:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

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

Сессии управляют непрерывностью и изоляцией разговоров:

{  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 через ретранслятор для публичных сборок App Store/TestFlight использует размещенный ретранслятор OpenClaw: https://ios-push-relay.openclaw.ai.

Пользовательские развертывания ретранслятора требуют намеренно отдельного пути сборки/развертывания iOS, URL ретранслятора которого совпадает с URL ретранслятора Gateway. Если вы используете пользовательскую сборку с ретранслятором, задайте это в конфигурации 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, сигналы пробуждения и пробуждения для переподключения через внешний ретранслятор.
• Использует разрешение на отправку в области регистрации, пересланное сопряженным приложением iOS. Gateway не нужен токен ретранслятора на уровне всего развертывания.
• Привязывает каждую регистрацию через ретранслятор к идентичности Gateway, с которым было сопряжено приложение iOS, поэтому другой Gateway не сможет повторно использовать сохраненную регистрацию.
• Оставляет локальные/ручные сборки iOS на прямом APNs. Отправки через ретранслятор применяются только к официальным распространяемым сборкам, зарегистрированным через ретранслятор.
• Должно совпадать с базовым URL ретранслятора, встроенным в сборку iOS, чтобы трафик регистрации и отправки попадал в одно и то же развертывание ретранслятора.

Сквозной поток:

1. Установите официальную/TestFlight-сборку iOS.
2. Необязательно: настройте gateway.push.apns.relay.baseUrl на Gateway только при использовании намеренно отдельной пользовательской сборки с ретранслятором.
3. Сопрягите приложение iOS с Gateway и дайте подключиться как сеансам узла, так и сеансам оператора.
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 остается аварийным выходом для разработки только через local loopback; не сохраняйте HTTP URL ретранслятора в конфигурации.

См. Приложение iOS для сквозного потока и Поток аутентификации и доверия для модели безопасности ретранслятора.

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

• every: строка длительности (30m, 2h). Задайте 0m, чтобы отключить.
• target: last | none | <channel-id> (например, discord, matrix, telegram или whatsapp)
• directPolicy: allow (по умолчанию) или block для целей Heartbeat в стиле личных сообщений
• См. 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,      },    ],  },}

Примечание по безопасности:

• Считайте все содержимое полезных нагрузок хуков/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) к дополнительным каталогам, на которые могут ссылаться включения. Символические ссылки разрешаются и проверяются повторно, поэтому путь, который лексически находится в каталоге конфигурации, но чей реальный целевой путь выходит за пределы всех разрешенных корней, все равно отклоняется.
• Обработка ошибок: понятные ошибки для отсутствующих файлов, ошибок разбора, циклических включений, недопустимого формата пути и чрезмерной длины