配置 — 渠道

channels.* 下的每个渠道配置键。涵盖私信和群组访问、多账号设置、提及门控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他内置渠道插件的每个渠道键。对于智能体、工具、Gateway 网关运行时以及其他顶层键，请参阅配置参考。

渠道

当某个渠道的配置节存在时，该渠道会自动启动（除非设置了 enabled: false）。

私信和群组访问

所有渠道都支持私信策略和群组策略：

私信策略	行为
`pairing`（默认）	未知发送者会收到一次性配对码；所有者必须批准
`allowlist`	仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
`open`	允许所有入站私信（需要 `allowFrom: ["*"]`）
`disabled`	忽略所有入站私信

群组策略	行为
`allowlist`（默认）	仅允许匹配已配置允许列表的群组
`open`	绕过群组允许列表（提及门控仍然适用）
`disabled`	阻止所有群组/房间消息

channels.defaults.groupPolicy 在提供商的 groupPolicy 未设置时设为默认值。配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多为 3 个。如果提供商配置块完全缺失（即不存在 channels.<provider>），运行时群组策略会回退为 allowlist（默认拒绝），并在启动时发出警告。

渠道模型覆盖

使用 channels.modelByChannel 将特定渠道 ID 固定到某个模型。值接受 provider/model 或已配置的模型别名。当会话尚未有模型覆盖时（例如通过 /model 设置），就会应用渠道映射。

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

渠道默认值和心跳

使用 channels.defaults 为各提供商共享群组策略和心跳行为：

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

channels.defaults.groupPolicy：当提供商级别的 groupPolicy 未设置时使用的回退群组策略。
channels.defaults.contextVisibility：所有渠道的默认补充上下文可见性模式。可选值：all（默认，包含所有引用/线程/历史上下文）、allowlist（仅包含允许列表发送者的上下文）、allowlist_quote（与 allowlist 相同，但保留显式引用/回复上下文）。每个渠道的覆盖项：channels.<channel>.contextVisibility。
channels.defaults.heartbeat.showOk：在心跳输出中包含健康渠道状态。
channels.defaults.heartbeat.showAlerts：在心跳输出中包含降级/错误状态。
channels.defaults.heartbeat.useIndicator：将心跳输出渲染为紧凑的指示器样式。

WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联的会话时，它会自动启动。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 蓝色对勾（在 self-chat 模式下为 false）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

多账号 WhatsApp

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

出站命令默认使用账号 default（如果存在）；否则使用第一个已配置的账号 id（排序后）。
可选的 channels.whatsapp.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖上述默认账号选择。
旧版单账号 Baileys 认证目录会由 openclaw doctor 迁移到 whatsapp/default。
每个账号的覆盖项：channels.whatsapp.accounts.<id>.sendReadReceipts、channels.whatsapp.accounts.<id>.dmPolicy、channels.whatsapp.accounts.<id>.allowFrom。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress（默认：off；请显式启用，以避免预览编辑速率限制）
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

Bot token：channels.telegram.botToken 或 channels.telegram.tokenFile（仅允许常规文件；拒绝符号链接），默认账号可回退到 TELEGRAM_BOT_TOKEN。
可选的 channels.telegram.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。
在多账号设置中（2 个或更多账号 id），请设置显式默认值（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免回退路由；如果缺失或无效，openclaw doctor 会发出警告。
configWrites: false 会阻止由 Telegram 发起的配置写入（supergroup ID 迁移、/config set|unset）。
顶层 bindings[] 中 type: "acp" 的条目可为论坛话题配置持久化 ACP 绑定（在 match.peer.id 中使用规范格式 chatId:topic:topicId）。字段语义与 ACP Agents 共享。
Telegram 流式预览使用 sendMessage + editMessageText（在私聊和群聊中都可用）。
重试策略：参见重试策略。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial）
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

Token：channels.discord.token，默认账号可回退到 DISCORD_BOT_TOKEN。
直接出站调用如果提供了显式的 Discord token，该次调用会使用该 token；账号重试/策略设置仍然来自活动运行时快照中选定的账号。
可选的 channels.discord.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。
使用 user:<id>（私信）或 channel:<id>（服务器渠道）作为投递目标；不接受裸数字 ID。
服务器 slug 为小写，空格替换为 -；渠道键使用 slug 化名称（不带 #）。优先使用服务器 ID。
默认会忽略由机器人编写的消息。allowBots: true 会启用它们；使用 allowBots: "mentions" 则仅接受提及机器人的机器人消息（机器人自己的消息仍会被过滤）。
channels.discord.guilds.<id>.ignoreOtherMentions（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。
maxLinesPerMessage（默认 17）会拆分过高的消息，即使其长度未超过 2000 个字符。
channels.discord.threadBindings 控制 Discord 线程绑定路由：
- enabled：Discord 对线程绑定会话功能的覆盖（/focus、/unfocus、/agents、/session idle、/session max-age，以及绑定投递/路由）
- idleHours：Discord 对不活跃时自动取消聚焦的小时数覆盖（0 表示禁用）
- maxAgeHours：Discord 对硬性最大存续时长（小时）的覆盖（0 表示禁用）
- spawnSubagentSessions：为 sessions_spawn({ thread: true }) 自动创建/绑定线程的显式启用开关
顶层 bindings[] 中 type: "acp" 的条目可为渠道和线程配置持久化 ACP 绑定（在 match.peer.id 中使用渠道/线程 id）。字段语义与 ACP Agents 共享。
channels.discord.ui.components.accentColor 为 Discord components v2 容器设置强调色。
channels.discord.voice 启用 Discord 语音渠道对话，以及可选的自动加入 + LLM + TTS 覆盖。
channels.discord.voice.model 可选地覆盖用于 Discord 语音渠道响应的 LLM 模型。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 会透传给 @discordjs/voice 的 DAVE 选项（默认分别为 true 和 24）。
OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试恢复语音接收。
channels.discord.streaming 是规范的流式模式键。旧版 streamMode 和布尔值 streaming 会自动迁移。
channels.discord.autoPresence 将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。
channels.discord.dangerouslyAllowNameMatching 会重新启用可变名称/tag 匹配（破窗兼容模式）。
channels.discord.execApprovals：Discord 原生 exec 审批投递和审批人授权。
- enabled：true、false 或 "auto"（默认）。在自动模式下，当可以从 approvers 或 commands.ownerAllowFrom 解析出审批人时，exec 审批会激活。
- approvers：允许审批 exec 请求的 Discord 用户 ID。省略时回退到 commands.ownerAllowFrom。
- agentFilter：可选的智能体 ID 允许列表。省略则会为所有智能体转发审批。
- sessionFilter：可选的会话键模式（子串或正则表达式）。
- target：发送审批提示的位置。"dm"（默认）发送到审批人的私信，"channel" 发送到原始渠道，"both" 同时发送到两者。当目标包含 "channel" 时，按钮仅可由已解析的审批人使用。
- cleanupAfterResolve：为 true 时，在审批、拒绝或超时后删除审批私信。

反应通知模式： off（无）、own（机器人的消息，默认）、all（所有消息）、allowlist（来自 guilds.<id>.users 的所有消息）。

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

服务账号 JSON：可内联（serviceAccount）或基于文件（serviceAccountFile）。
也支持服务账号 SecretRef（serviceAccountRef）。
环境变量回退：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
使用 spaces/<spaceId> 或 users/<userId> 作为投递目标。
channels.googlechat.dangerouslyAllowNameMatching 会重新启用可变电子邮件主体匹配（破窗兼容模式）。

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式 API
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

Socket mode 需要同时提供 botToken 和 appToken（默认账号的环境变量回退为 SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
HTTP mode 需要 botToken 加上 signingSecret（位于根级或每个账号级）。
botToken、appToken、signingSecret 和 userToken 接受纯文本字符串或 SecretRef 对象。
Slack 账号快照会暴露每个凭证的来源/状态字段，例如 botTokenSource、botTokenStatus、appTokenStatus，以及在 HTTP mode 下的 signingSecretStatus。configured_unavailable 表示该账号通过 SecretRef 进行配置，但当前命令/运行时路径无法解析该 secret 值。
configWrites: false 会阻止由 Slack 发起的配置写入。
可选的 channels.slack.defaultAccount 会在其匹配某个已配置账号 id 时覆盖默认账号选择。
channels.slack.streaming.mode 是规范的 Slack 流式模式键。channels.slack.streaming.nativeTransport 控制 Slack 的原生流式传输。旧版 streamMode、布尔值 streaming 和 nativeStreaming 会自动迁移。
使用 user:<id>（私信）或 channel:<id> 作为投递目标。

反应通知模式： off、own（默认）、all、allowlist（来自 reactionAllowlist）。 线程会话隔离： thread.historyScope 为每线程（默认）或整个渠道共享。thread.inheritParent 会将父渠道的记录复制到新线程中。

Slack 原生流式传输加上 Slack 助手样式的“正在输入…”线程状态，需要以回复线程为目标。顶层私信默认不在线程中，因此会使用 typingReaction 或普通投递，而不是线程样式预览。
typingReaction 会在回复运行期间为入站 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 简码，例如 "hourglass_flowing_sand"。
channels.slack.execApprovals：Slack 原生 exec 审批投递和审批人授权。与 Discord 使用相同 schema：enabled（true/false/"auto"）、approvers（Slack 用户 ID）、agentFilter、sessionFilter 和 target（"dm"、"channel" 或 "both"）。

操作组	默认值	说明
reactions	已启用	添加反应 + 列出反应
messages	已启用	读取/发送/编辑/删除
pins	已启用	固定/取消固定/列出
memberInfo	已启用	成员信息
emojiList	已启用	自定义 emoji 列表

Mattermost

Mattermost 作为插件提供：openclaw plugins install @openclaw/mattermost。

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // 显式启用
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // 用于反向代理/公共部署的可选显式 URL
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

聊天模式：oncall（在 @ 提及时响应，默认）、onmessage（每条消息）、onchar（以触发前缀开头的消息）。当启用 Mattermost 原生命令时：

commands.callbackPath 必须是路径（例如 /api/channels/mattermost/command），不能是完整 URL。
commands.callbackUrl 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。
原生斜杠命令回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调，并返回 Unauthorized: invalid command token.。
对于私有/tailnet/内部回调主机，Mattermost 可能要求 ServiceSettings.AllowedUntrustedInternalConnections 包含回调主机/域名。请使用主机/域名值，而不是完整 URL。
channels.mattermost.configWrites：允许或拒绝由 Mattermost 发起的配置写入。
channels.mattermost.requireMention：在渠道中回复前要求 @mention。
channels.mattermost.groups.<channelId>.requireMention：每个渠道的提及门控覆盖（"*" 表示默认值）。
可选的 channels.mattermost.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // 可选账号绑定
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

反应通知模式： off、own（默认）、all、allowlist（来自 reactionAllowlist）。

channels.signal.account：将渠道启动固定到特定的 Signal 账号标识。
channels.signal.configWrites：允许或拒绝由 Signal 发起的配置写入。
可选的 channels.signal.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。

BlueBubbles

BlueBubbles 是推荐的 iMessage 路径（由插件支持，配置位于 channels.bluebubbles）。

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl、password、webhookPath、群组控制和高级操作：
      // 参见 /channels/bluebubbles
    },
  },
}

此处涵盖的核心键路径：channels.bluebubbles、channels.bluebubbles.dmPolicy。
可选的 channels.bluebubbles.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。
顶层 bindings[] 中 type: "acp" 的条目可以将 BlueBubbles 对话绑定到持久化 ACP 会话。在 match.peer.id 中使用 BlueBubbles handle 或目标字符串（chat_id:*、chat_guid:*、chat_identifier:*）。共享字段语义： ACP Agents。
完整的 BlueBubbles 渠道配置记录在 BlueBubbles 中。

iMessage

OpenClaw 会启动 imsg rpc（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

可选的 channels.imessage.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。
需要对 Messages 数据库授予 Full Disk Access。
优先使用 chat_id:<id> 目标。使用 imsg chats --limit 20 列出聊天。
cliPath 可以指向 SSH 包装器；设置 remoteHost（host 或 user@host）以便通过 SCP 获取附件。
attachmentRoots 和 remoteAttachmentRoots 用于限制入站附件路径（默认：/Users/*/Library/Messages/Attachments）。
SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 ~/.ssh/known_hosts 中。
channels.imessage.configWrites：允许或拒绝由 iMessage 发起的配置写入。
顶层 bindings[] 中 type: "acp" 的条目可以将 iMessage 对话绑定到持久化 ACP 会话。在 match.peer.id 中使用规范化 handle 或显式聊天目标（chat_id:*、chat_guid:*、chat_identifier:*）。共享字段语义： ACP Agents。

iMessage SSH 包装器示例

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Matrix

Matrix 由插件支持，配置位于 channels.matrix。

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

Token 认证使用 accessToken；密码认证使用 userId + password。
channels.matrix.proxy 通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可以通过 channels.matrix.accounts.<id>.proxy 覆盖它。
channels.matrix.network.dangerouslyAllowPrivateNetwork 允许私有/内部 homeserver。proxy 和这个网络显式启用项是彼此独立的控制项。
channels.matrix.defaultAccount 在多账号设置中选择首选账号。
channels.matrix.autoJoin 默认为 off，因此受邀房间和新的私信式邀请会被忽略，直到你设置 autoJoin: "allowlist" 并配合 autoJoinAllowlist，或设置 autoJoin: "always"。
channels.matrix.execApprovals：Matrix 原生 exec 审批投递和审批人授权。
- enabled：true、false 或 "auto"（默认）。在自动模式下，当可以从 approvers 或 commands.ownerAllowFrom 解析出审批人时，exec 审批会激活。
- approvers：允许审批 exec 请求的 Matrix 用户 ID（例如 @owner:example.org）。
- agentFilter：可选的智能体 ID 允许列表。省略则会为所有智能体转发审批。
- sessionFilter：可选的会话键模式（子串或正则表达式）。
- target：发送审批提示的位置。"dm"（默认）、"channel"（来源房间）或 "both"。
- 每账号覆盖项：channels.matrix.accounts.<id>.execApprovals。
channels.matrix.dm.sessionScope 控制 Matrix 私信如何归并到会话中：per-user（默认）按路由对端共享，而 per-room 会隔离每个私信房间。
Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
完整的 Matrix 配置、目标规则和设置示例记录在 Matrix 中。

Microsoft Teams

Microsoft Teams 由插件支持，配置位于 channels.msteams。

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId、appPassword、tenantId、webhook、团队/渠道策略：
      // 参见 /channels/msteams
    },
  },
}

此处涵盖的核心键路径：channels.msteams、channels.msteams.configWrites。
完整的 Teams 配置（凭证、webhook、私信/群组策略、每团队/每渠道覆盖）记录在 Microsoft Teams 中。

IRC

IRC 由插件支持，配置位于 channels.irc。

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

此处涵盖的核心键路径：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
可选的 channels.irc.defaultAccount 会在其匹配某个已配置账号 id 时，覆盖默认账号选择。
完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 IRC 中。

多账号（所有渠道）

每个渠道可运行多个账号（每个账号都有自己的 accountId）：

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

当省略 accountId 时，使用 default（CLI + 路由）。
环境变量 token 仅适用于 default 账号。
基础渠道设置会应用到所有账号，除非在每账号级别被覆盖。
使用 bindings[].match.accountId 将每个账号路由到不同的智能体。
如果你通过 openclaw channels add（或渠道新手引导）添加非默认账号，而当前仍使用单账号顶层渠道配置，OpenClaw 会先将带账号作用域的顶层单账号值提升到该渠道的账号映射中，以便原始账号继续工作。大多数渠道会将其移到 channels.<channel>.accounts.default；Matrix 则可以保留现有匹配的命名/default 目标。
现有的仅渠道绑定（无 accountId）将继续匹配默认账号；带账号作用域的绑定仍然是可选的。
openclaw doctor --fix 也会通过将带账号作用域的顶层单账号值移动到该渠道所选的提升账号中来修复混合形状。大多数渠道使用 accounts.default；Matrix 则可以保留现有匹配的命名/default 目标。

其他插件渠道

许多插件渠道都配置为 channels.<id>，并在各自专属的渠道页面中有说明（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。参见完整渠道索引：Channels。

群聊提及门控

群组消息默认需要提及（元数据提及或安全正则表达式模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。 提及类型：

元数据提及：原生平台 @ 提及。在 WhatsApp self-chat 模式下会被忽略。
文本模式：agents.list[].groupChat.mentionPatterns 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。
仅在能够检测提及的情况下（原生提及或至少有一个模式）才会强制执行提及门控。

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit 设置全局默认值。渠道可通过 channels.<channel>.historyLimit（或每账号设置）覆盖。设置为 0 可禁用。

私信历史限制

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

解析顺序：每私信覆盖 → 提供商默认值 → 不限制（全部保留）。支持：telegram、whatsapp、discord、slack、signal、imessage、msteams。

self-chat 模式

将你自己的号码包含在 allowFrom 中即可启用 self-chat 模式（忽略原生 @ 提及，仅响应文本模式）：

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

Commands（聊天命令处理）

{
  commands: {
    native: "auto", // 在支持时注册原生命令
    nativeSkills: "auto", // 在支持时注册原生 Skills 命令
    text: true, // 解析聊天消息中的 /commands
    bash: false, // 允许 !（别名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允许 /config
    mcp: false, // 允许 /mcp
    plugins: false, // 允许 /plugins
    debug: false, // 允许 /debug
    restart: true, // 允许 /restart + gateway restart 工具
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

命令详情

此配置块用于配置命令入口。关于当前内置 + 内置捆绑的命令目录，请参见 Slash Commands。
本页是配置键参考，不是完整的命令目录。像 QQ Bot /bot-ping /bot-help /bot-logs、LINE /card、设备配对 /pair、内存 /dreaming、手机控制 /phone 和 Talk /voice 这类由渠道/插件拥有的命令，记录在其各自的渠道/插件页面以及 Slash Commands 中。
文本命令必须是带有前导 / 的独立消息。
native: "auto" 会为 Discord/Telegram 开启原生命令，对 Slack 保持关闭。
nativeSkills: "auto" 会为 Discord/Telegram 开启原生 Skills 命令，对 Slack 保持关闭。
每个渠道单独覆盖：channels.discord.commands.native（布尔值或 "auto"）。false 会清除之前已注册的命令。
使用 channels.<provider>.commands.nativeSkills 为每个渠道覆盖原生 Skills 注册。
channels.telegram.customCommands 会添加额外的 Telegram 机器人菜单项。
bash: true 为主机 shell 启用 ! <cmd>。需要 tools.elevated.enabled，并且发送者位于 tools.elevated.allowFrom.<channel> 中。
config: true 启用 /config（读取/写入 openclaw.json）。对于 Gateway 网关 chat.send 客户端，持久化 /config set|unset 写入还需要 operator.admin；只读的 /config show 对普通写作用域 operator 客户端仍然可用。
mcp: true 会为 mcp.servers 下由 OpenClaw 管理的 MCP 服务器配置启用 /mcp。
plugins: true 会为插件发现、安装和启用/禁用控制启用 /plugins。
channels.<provider>.configWrites 控制每个渠道的配置变更权限（默认：true）。
对于多账号渠道，channels.<provider>.accounts.<id>.configWrites 也会控制以该账号为目标的写入（例如 /allowlist --config --account <id> 或 /config set channels.<provider>.accounts.<id>...）。
restart: false 会禁用 /restart 和 Gateway 网关 restart 工具操作。默认值：true。
ownerAllowFrom 是 owner 专用命令/工具的显式 owner 允许列表。它与 allowFrom 分开。
ownerDisplay: "hash" 会在系统提示中对 owner id 做哈希。设置 ownerDisplaySecret 可控制哈希。
allowFrom 是按提供商区分的。设置后，它将成为唯一的授权来源（渠道允许列表/配对以及 useAccessGroups 都会被忽略）。
useAccessGroups: false 允许命令在未设置 allowFrom 时绕过访问组策略。
命令文档映射：
- 内置 + 内置捆绑目录：Slash Commands
- 渠道专属命令入口：Channels
- QQ Bot 命令：QQ Bot
- 配对命令：Pairing
- LINE card 命令：LINE
- 内存 dreaming：Dreaming

Overview

First steps

Guides

配置 — 渠道

渠道

私信和群组访问

渠道模型覆盖

渠道默认值和心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles

iMessage

Matrix

Microsoft Teams

IRC

多账号（所有渠道）

其他插件渠道

群聊提及门控

私信历史限制

self-chat 模式

Commands（聊天命令处理）

相关

Overview

First steps

Guides

​渠道

​私信和群组访问

​渠道模型覆盖

​渠道默认值和心跳

​WhatsApp

​Telegram

​Discord

​Google Chat

​Slack

​Mattermost

​Signal

​BlueBubbles

​iMessage

​Matrix

​Microsoft Teams

​IRC

​多账号（所有渠道）

​其他插件渠道

​群聊提及门控

​私信历史限制

​self-chat 模式

​Commands（聊天命令处理）

​相关

渠道

私信和群组访问

渠道模型覆盖

渠道默认值和心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles

iMessage

Matrix

Microsoft Teams

IRC

多账号（所有渠道）

其他插件渠道

群聊提及门控

私信历史限制

self-chat 模式

Commands（聊天命令处理）

相关