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

У каждого канала есть собственный раздел конфигурации в 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    ],  },}

• Чтобы по умолчанию не ограничивать Skills, не указывайте agents.defaults.skills.
• Чтобы наследовать значения по умолчанию, не указывайте agents.list[].skills.
• Чтобы отключить Skills, задайте agents.list[].skills: [].
• См. Skills, конфигурацию Skills и справочник по конфигурации.

Настройте интенсивность перезапуска каналов, которые выглядят неактивными:

{  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 не мог повторно использовать сохранённую регистрацию.
• Для локальных и вручную собранных версий iOS сохраняется прямая отправка через APNs. Отправка через ретранслятор применяется только к официально распространяемым сборкам, зарегистрированным через ретранслятор.
• Должен совпадать с базовым 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 остаётся предназначенным только для loopback аварийным вариантом для разработки; не сохраняйте 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-вебхуков на 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,      },    ],  },}

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

• Считайте всё содержимое полезной нагрузки хука или вебхука недоверенными входными данными.
• Используйте отдельный hooks.token; не используйте повторно активные секреты аутентификации Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN или gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Аутентификация хуков выполняется только через заголовок (Authorization: Bearer ... или x-openclaw-token); токены в строке запроса отклоняются.
• hooks.path не может быть /; размещайте входящие вебхуки в отдельном подпути, например /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) к дополнительным каталогам, на которые могут ссылаться включения. Символические ссылки разрешаются и проверяются повторно, поэтому путь, который лексически находится в каталоге конфигурации, но фактическая цель которого выходит за пределы всех разрешённых корней, всё равно отклоняется.
• Обработка ошибок: понятные ошибки для отсутствующих файлов, ошибок разбора, циклических включений, недопустимого формата пути и чрезмерной длины