OpenClaw 各渠道配置键参考：本页列出所有内置渠道的 channels.* 配置项，包括 DM 配对策略（配对/白名单/开放/禁用）、群组白名单（默认 allowlist）、提及门控、多账户、模型覆盖、心跳设置及每个渠道的专属参数（如 Telegram botToken、Discord token、iMessage cliPath）。配置热重载后无需重启网关。注意：配对码有效期 1 小时，每个渠道最多 3 个待处理配对请求；群组策略未设置时默认 fail-closed（allowlist）。

OpenClaw 渠道配置：DM策略、群组权限与多账户设置

智能体、工具、网关运行时及其他顶层配置键请参见配置参考。

渠道配置

每个渠道在配置段存在时自动启动（除非设置 enabled: false）。

DM 与群组访问策略

所有渠道均支持以下 DM 和群组策略：

DM 策略	行为
`pairing`（默认）	未知发送者收到一次性配对码，需所有者审批
`allowlist`	仅允许 `allowFrom`（或已配对的允许存储）中的发送者
`open`	允许所有入站 DM（需设置 `allowFrom: ["*"]`）
`disabled`	忽略所有入站 DM

群组策略	行为
`allowlist`（默认）	仅匹配配置的白名单群组
`open`	绕过群组白名单（提及门控仍生效）
`disabled`	屏蔽所有群组/房间消息

TIP

channels.defaults.groupPolicy 在提供端的 groupPolicy 未设置时作为默认值。
配对码有效期 1 小时。每个渠道最多保留 3 个待处理的 DM 配对请求。
如果某个提供端块完全缺失（channels.<provider> 不存在），运行时群组策略会回退为 allowlist（fail-closed）并启动时打印警告。

渠道模型覆盖

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

json5

{
  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 设置跨提供端的共享群组策略和心跳行为：

json5

{
  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 通过网关的 web 渠道（Baileys Web）运行。当存在关联会话时自动启动。

json5

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 蓝色已读标记（自聊天模式为 false）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

多账户 WhatsApp

json5

{
  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。

json5

{
  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",
      },
      apiRoot: "https://api.telegram.org",
      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 环境变量。
apiRoot 仅指 Telegram Bot API 根地址。使用 https://api.telegram.org 或自宿主/代理根地址，不要加 /bot<TOKEN>；openclaw doctor --fix 会移除意外附加的 /bot<TOKEN> 后缀。
可选的 channels.telegram.defaultAccount 在匹配已配置账户 ID 时覆盖默认账户选择。
多账户（2 个以上账户 ID）时，需设置显式默认账户（channels.telegram.defaultAccount 或 channels.telegram.accounts.default），否则回退路由可能不稳定；openclaw doctor 会在缺失或无效时发出警告。
configWrites: false 阻止 Telegram 发起的配置写入（超级组 ID 迁移、/config set|unset）。
顶层 bindings[] 中 type: "acp" 的条目可为论坛话题配置持久 ACP 绑定（在 match.peer.id 中使用规范格式 chatId:topic:topicId）。字段语义参见 ACP Agents。
Telegram 流预览使用 sendMessage + editMessageText（适用于私聊和群组）。
重试策略：参见 Retry policy。

Discord

json5

{
  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,
      suppressEmbeds: true,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress（Discord 默认：progress）
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        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>（DM）或 channel:<id>（服务器频道）；纯数字 ID 会被拒绝。
服务器 slug 为小写，空格替换为 -；频道键使用 slug 化名称（不带 #）。推荐使用服务器 ID。
Bot 发送的消息默认被忽略。allowBots: true 启用；allowBots: "mentions" 仅接受提及 bot 的消息（自身消息仍被过滤）。
支持 bot 入站消息的频道可使用共享的 bot 循环保护。设置 channels.defaults.botLoopProtection 作为基线对预算，然后仅在某个表面需要不同限制时覆盖该频道或账户。
channels.discord.guilds.<id>.ignoreOtherMentions（及频道覆盖）会丢弃提及另一个用户/角色但未提及 bot 的消息（排除 @everyone/@here）。
channels.discord.mentionAliases 在发送前将稳定的出站 @handle 文本映射到 Discord 用户 ID，以便在临时目录缓存为空时仍能确定性提及已知队友。按账户覆盖位于 channels.discord.accounts.<accountId>.mentionAliases。
maxLinesPerMessage（默认 17）在超过 2000 字符前也会分割超长消息。
channels.discord.suppressEmbeds 默认 true，因此出站 URL 不会展开为 Discord 链接预览。显式的 embeds 载荷仍正常发送；每次工具调用可覆盖 suppressEmbeds。
channels.discord.threadBindings 控制 Discord 线程绑定路由：
- enabled：线程绑定会话功能的 Discord 覆盖（/focus、/unfocus、/agents、/session idle、/session max-age 及绑定投递/路由）
- idleHours：不活跃自动取消聚焦的小时数（0 禁用）
- maxAgeHours：硬性最大存在小时数（0 禁用）
- spawnSessions：sessions_spawn({ thread: true }) 和 ACP 线程生成自动创建/绑定的开关（默认 true）
- defaultSpawnContext：线程绑定生成的本地子智能体上下文（默认 "fork"）
顶层 bindings[] 中 type: "acp" 的条目可为频道和线程配置持久 ACP 绑定（在 match.peer.id 中使用频道/线程 ID）。字段语义参见 ACP Agents。
channels.discord.ui.components.accentColor 设置 Discord components v2 容器的强调色。
channels.discord.agentComponents.ttlMs 控制已发送 Discord 组件回调的注册时长。默认 1800000（30 分钟），最大 86400000（24 小时）。按账户覆盖位于 channels.discord.accounts.<accountId>.agentComponents.ttlMs。更长的值使旧按钮/选择/表单可用更久，建议使用适合工作流的最短 TTL。
channels.discord.voice 启用 Discord 语音频道对话及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音；设置 channels.discord.voice.enabled=true 启用。
channels.discord.voice.model 可选地覆盖 Discord 语音频道回复使用的 LLM 模型。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 直接传递给 @discordjs/voice DAVE 选项（默认 true 和 24）。
channels.discord.voice.connectTimeoutMs 控制初始 @discordjs/voice Ready 等待时间（/vc join 和自动加入尝试，默认 30000）。
channels.discord.voice.reconnectGraceMs 控制断连的语音会话在 OpenClaw 销毁前可以进入重连信令的时长（默认 15000）。
Discord 语音播放不会被其他用户的语音开始事件中断。为避免反馈循环，OpenClaw 在 TTS 播放期间忽略新的语音捕获。
OpenClaw 还会在重复解密失败后尝试退出/重新加入语音会话以恢复语音接收。
channels.discord.streaming 是规范的流模式键。Discord 默认 streaming.mode: "progress"，因此工具/工作进度会出现在一条编辑过的预览消息中；设置 streaming.mode: "off" 关闭。旧版 streamMode 和布尔 streaming 值仍作为运行时别名；运行 openclaw doctor --fix 重写持久配置。
channels.discord.autoPresence 将运行时可用性映射到 bot 状态（健康→在线，降级→空闲，资源耗尽→勿扰），并允许可选的状态文本覆盖。
channels.discord.dangerouslyAllowNameMatching 重新启用可变名称/标签匹配（break-glass 兼容模式）。
channels.discord.execApprovals：Discord 原生的执行审批投递和审批者授权。
- enabled：true、false 或 "auto"（默认）。自动模式下，当能从 approvers 或 commands.ownerAllowFrom 解析审批者时激活。
- approvers：允许审批执行请求的 Discord 用户 ID。省略时回退到 commands.ownerAllowFrom。
- agentFilter：可选的智能体 ID 白名单。省略则转发所有智能体的审批。
- sessionFilter：可选的会话键模式（子字符串或正则）。
- target：发送审批提示的位置。"dm"（默认）发送到审批者 DM，"channel" 发送到原始频道，"both" 同时发送。当目标包含 "channel" 时，按钮仅可由已解析的审批者使用。
- cleanupAfterResolve：true 时，在审批、拒绝或超时后删除审批 DM。

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

Google Chat

json5

{
  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 重新启用可变邮箱主体匹配（break-glass 兼容模式）。

Slack

json5

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      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",
      unfurlLinks: false,
      unfurlMedia: false,
      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 模式需要同时提供 botToken 和 appToken（默认账户环境变量回退：SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
HTTP 模式需要 botToken 加上 signingSecret（顶层或按账户）。
socketMode 将 Slack SDK Socket Mode 传输调优传递给公共 Bolt 接收器 API。仅在调查 ping/pong 超时或 WebSocket 异常时使用。clientPingTimeout 默认 15000；serverPingTimeout 和 pingPongLoggingEnabled 仅在配置时传递。
botToken、appToken、signingSecret 和 userToken 接受纯文本字符串或 SecretRef 对象。
Slack 账户快照会暴露每个凭据的来源/状态字段，如 botTokenSource、botTokenStatus、appTokenStatus，HTTP 模式下还有 signingSecretStatus。configured_unavailable 表示账户通过 SecretRef 配置但当前命令/运行时路径无法解析密钥值。
configWrites: false 阻止 Slack 发起的配置写入。
可选的 channels.slack.defaultAccount 在匹配已配置账户 ID 时覆盖默认账户选择。
channels.slack.streaming.mode 是规范的 Slack 流模式键。channels.slack.streaming.nativeTransport 控制 Slack 原生流传输。旧版 streamMode、布尔 streaming 和 nativeStreaming 值仍作为运行时别名；运行 openclaw doctor --fix 重写持久配置。
unfurlLinks 和 unfurlMedia 传递 Slack 的 chat.postMessage 链接和媒体展开布尔值，用于 bot 回复。unfurlLinks 默认 false，因此出站 bot 链接默认不展开；unfurlMedia 仅在配置时省略。可在 channels.slack.accounts.<accountId> 中设置任一值以覆盖某账户的顶层值。
交付目标使用 user:<id>（DM）或 channel:<id>。

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

线程会话隔离： thread.historyScope 为每线程（默认）或在频道中共享。thread.inheritParent 将父频道对话复制到新线程。

Slack 原生流及 Slack 助手风格的“正在输入...”线程状态需要回复线程目标。顶层 DM 默认在线程外，因此它们仍可通过 Slack 草稿发布和编辑预览进行流式输出，而不显示线程风格的原生流/状态预览。
typingReaction 在回复运行时向入站 Slack 消息添加临时反应，完成后移除。使用 Slack 表情符号简码，如 "hourglass_flowing_sand"。
channels.slack.execApprovals：Slack 原生的执行审批客户端投递和审批者授权。模式与 Discord 相同：enabled（true/false/"auto"）、approvers（Slack 用户 ID）、agentFilter、sessionFilter、target（"dm"、"channel" 或 "both"）。插件审批在使用 Slack 来源请求且 Slack 插件审批者可解析时也可使用此原生客户端路径；Slack 原生的插件审批投递也可通过 approvals.plugin 为 Slack 来源会话或 Slack 目标启用。插件审批使用来自 allowFrom 的 Slack 插件审批者和默认路由，而非 exec 审批者。

动作组	默认	备注
reactions	启用	添加反应 + 列出反应
messages	启用	读取/发送/编辑/删除
pins	启用	固定/取消固定/列出
memberInfo	启用	成员信息
emojiList	启用	自定义表情列表

Mattermost

Mattermost 作为当前 OpenClaw 版本的内置插件发布。旧版或自定义构建可使用 openclaw plugins install @openclaw/mattermost 安装最新 npm 包。在固定版本前请访问 npmjs.com/package/@openclaw/mattermost 查看当前 dist-tags。

json5

{
  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, // opt-in
        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 网关端点，并且 Mattermost 服务器可以访问。
原生斜杠回调使用在斜杠命令注册时 Mattermost 返回的每命令令牌进行身份验证。如果注册失败或没有命令激活，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

json5

{
  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 时覆盖默认账户选择。

iMessage

OpenClaw 会启动 imsg rpc（基于 stdio 的 JSON-RPC）。不需要守护进程或端口。当主机可以授予 Messages 数据库和自动化权限时，这是新 OpenClaw iMessage 设置的首选路径。

BlueBubbles 支持已被移除。channels.bluebubbles 在当前 OpenClaw 中不是受支持的运行时配置表面。将旧配置迁移到 channels.imessage；简版说明参见 BlueBubbles removal and the imsg iMessage path，完整对照表参见 Coming from BlueBubbles。

如果网关不在已登录 Messages 的 Mac 上运行，请保持 channels.imessage.enabled=true 并设置 channels.imessage.cliPath 为一个在该 Mac 上运行 imsg "$@" 的 SSH 包装器。默认本地 imsg 路径仅限 macOS。

json5

{
  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",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
      catchup: {
        enabled: false,
      },
    },
  },
}

可选的 channels.imessage.defaultAccount 在匹配已配置账户 ID 时覆盖默认账户选择。
需要对 Messages 数据库具有完全磁盘访问权限。
目标优选使用 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 发起的配置写入。
channels.imessage.actions.*：启用受 imsg status / openclaw channels status --probe 门控的私有 API 动作。
channels.imessage.includeAttachments 默认关闭；在期望入站媒体出现在智能体对话前请设置为 true。
channels.imessage.catchup.enabled：选择重放网关离线期间到达的入站消息。
channels.imessage.groups：群组注册和每群组设置。当 groupPolicy: "allowlist" 时，配置显式 chat_id 键或 "*" 通配符条目，使群组消息可通过注册门控。
顶层 bindings[] 中 type: "acp" 的条目可将 iMessage 对话绑定到持久 ACP 会话。在 match.peer.id 中使用标准化句柄或显式聊天目标（chat_id:*、chat_guid:*、chat_identifier:*）。字段语义共享请参见 ACP Agents。

iMessage SSH 包装器示例

bash

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

Matrix

Matrix 基于插件，在 channels.matrix 下配置。

json5

{
  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 将 Matrix HTTP 流量路由通过显式 HTTP(S) 代理。命名账户可通过 channels.matrix.accounts.<id>.proxy 覆盖。
channels.matrix.network.dangerouslyAllowPrivateNetwork 允许私有/内部家服务器。proxy 和此网络选择是独立控制。
channels.matrix.defaultAccount 在多账户设置中选择首选账户。
channels.matrix.autoJoin 默认为 off，因此被邀请的房间和新 DM 式邀请会被忽略，直到设置 autoJoin: "allowlist" 配合 autoJoinAllowlist 或 autoJoin: "always"。
channels.matrix.execApprovals：Matrix 原生的执行审批投递和审批者授权。
- enabled：true、false 或 "auto"（默认）。自动模式下，当能从 approvers 或 commands.ownerAllowFrom 解析审批者时激活。
- approvers：允许审批执行请求的 Matrix 用户 ID（例如 @owner:example.org）。
- agentFilter：可选的智能体 ID 白名单。省略则转发所有智能体的审批。
- sessionFilter：可选的会话键模式（子字符串或正则）。
- target：发送审批提示的位置。"dm"（默认）、"channel"（原始房间）或 "both"。
- 按账户覆盖：channels.matrix.accounts.<id>.execApprovals。
channels.matrix.dm.sessionScope 控制 Matrix DM 如何分组到会话：per-user（默认）按路由对等体共享，而 per-room 隔离每个 DM 房间。
Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
完整的 Matrix 配置、定位规则和设置示例参见 Matrix。

Microsoft Teams

Microsoft Teams 基于插件，在 channels.msteams 下配置。

json5

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

核心键路径在此说明：channels.msteams、channels.msteams.configWrites。
完整的 Teams 配置（凭据、webhook、DM/群组策略、每团队/每频道覆盖）参见 Microsoft Teams。

IRC

IRC 基于插件，在 channels.irc 下配置。

json5

{
  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 频道配置（主机/端口/TLS/频道/白名单/提及门控）参见 IRC。

多账户（所有渠道）

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

json5

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

default 在 accountId 省略时使用（CLI + 路由）。
环境变量令牌仅适用于 default 账户。
基础渠道设置适用于所有账户，除非被按账户覆盖。
使用 bindings[].match.accountId 将每个账户路由到不同智能体。
如果在单账户顶层渠道配置下通过 openclaw channels add（或渠道入门）添加非默认账户，OpenClaw 会先将账户范围的顶层单账户值提升到渠道账户映射中，以使原始账户继续工作。大多数渠道会将它们移动到 channels.<channel>.accounts.default；Matrix 可以保留现有的匹配命名/默认目标。
现有的纯渠道绑定（无 accountId）继续匹配默认账户；账户范围的绑定保持可选。
openclaw doctor --fix 也会通过将账户范围的顶层单账户值移动到为该渠道提升的账户中修复混合形状。大多数渠道使用 accounts.default；Matrix 可以保留现有的匹配命名/默认目标。

其他插件渠道

许多插件渠道配置为 channels.<id>，并在其专用渠道页面中说明（例如飞书、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
完整渠道索引参见 Channels。

群聊提及门控

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

可见回复分别控制。正常群组和频道请求默认使用自动最终交付：最终助手文本通过传统可见回复路径发布。某些 harness（包括 Codex）默认将直接/来源聊天设置为消息工具交付，因此可见输出仅在智能体调用 message(action=send) 后发布。如果模型返回最终文本而未调用消息工具，则该最终文本保持私有，网关详细日志会记录被抑制的有效载荷元数据。

仅工具可见回复需要能可靠调用工具的模型/运行时，推荐在最新一代模型（如 GPT 5.5）的共享环境房间中使用。如果会话日志显示助手文本带有 didSendViaMessagingTool: false，说明模型产生了私有最终文本而不是调用消息工具。可为该频道切换到更强的工具调用模型，检查网关详细日志以查看被抑制的有效载荷摘要，或设置 messages.groupChat.visibleReplies: "automatic" 以对每个群组/频道请求使用可见最终回复。

如果在当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。openclaw doctor 会对此不匹配发出警告。

故障排除：群组 @mention 触发输入提示后静默（无错误）

症状：群组/频道 @mention 显示输入指示器，网关日志报告 dispatch complete (queuedFinal=false, replies=0)，但消息未出现在房间中。相同智能体的 DM 回复正常。

原因：群组/频道可见回复模式解析为 "message_tool"，因此 OpenClaw 运行该轮次但抑制最终助手文本，除非智能体调用 message(action=send)。由于抑制是配置行为，没有错误。正常群组和频道轮次默认使用 "automatic"，因此此症状仅在 messages.groupChat.visibleReplies（或全局 messages.visibleReplies）显式设置为 "message_tool" 时出现。Harness defaultVisibleReplies 在此不适用——群组/频道解析器忽略它；它仅影响直接/来源聊天（Codex harness 以这种方式抑制直接聊天最终文本）。

修复：要么选择更强的工具调用模型，移除显式的 "message_tool" 覆盖以回退到 "automatic" 默认值，要么设置 messages.groupChat.visibleReplies: "automatic" 以强制每个群组/频道请求使用可见回复。网关在文件保存后热重载 messages 配置；仅当部署中禁用了文件监视或配置重载时才需重启网关。

提及类型：

元数据提及：平台原生 @提及。WhatsApp 自聊天模式下忽略。
文本模式：agents.list[].groupChat.mentionPatterns 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
仅当检测可能时（原生提及或至少一个模式）才执行提及门控。

json5

{
  messages: {
    visibleReplies: "automatic", // 强制直接/来源聊天使用旧的自动最终回复
    groupChat: {
      historyLimit: 50,
      unmentionedInbound: "room_event", // 始终开启的未提及房间闲聊变为静默上下文
      visibleReplies: "message_tool", // 选择加入；需要 message(action=send) 才能有可见房间回复
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

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

messages.groupChat.unmentionedInbound: "room_event" 在支持的渠道上将未提及的始终开启群组/频道消息作为静默房间上下文提交。提及的消息、命令和直接消息仍为用户请求。有关完整的 Discord、Slack 和 Telegram 示例，请参见 Ambient room events。

messages.visibleReplies 是全局来源事件默认值；messages.groupChat.visibleReplies 为群组/频道来源事件覆盖它。当 messages.visibleReplies 未设置时，直接/来源聊天使用选中的运行时或 harness 默认值。Codex harness 默认直接/来源聊天使用消息工具交付；设置 messages.visibleReplies: "automatic" 使用自动最终交付。渠道白名单和提及门控仍决定是否处理事件。

DM 历史限制

json5

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

解析顺序：每 DM 覆盖 → 提供端默认 → 无限制（全部保留）。

支持：telegram、whatsapp、discord、slack、signal、imessage、msteams。

自聊天模式

在 allowFrom 中包含你自己的号码以启用自聊天模式（忽略原生 @提及，仅响应文本模式）：

json5

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

命令（聊天命令处理）

json5

{
  commands: {
    native: "auto", // 在支持时注册原生命令
    nativeSkills: "auto", // 在支持时注册原生技能命令
    text: true, // 解析聊天消息中的 /commands
    bash: false, // 允许 !（别名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允许 /config
    mcp: false, // 允许 /mcp
    plugins: false, // 允许 /plugins
    debug: false, // 允许 /debug
    restart: true, // 允许 /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 开启原生技能命令，Slack 保持关闭。
每渠道覆盖：channels.discord.commands.native（布尔或 "auto"）。对于 Discord，false 在启动时跳过原生命令注册和清理。
每渠道覆盖原生技能注册：channels.<provider>.commands.nativeSkills。
channels.telegram.customCommands 添加额外的 Telegram 机器人菜单条目。
bash: true 启用 ! <cmd> 用于主机 shell。需要 tools.elevated.enabled 且发送者在 tools.elevated.allowFrom.<channel> 中。
config: true 启用 /config（读取/写入 openclaw.json）。对于网关 chat.send 客户端，持久的 /config set|unset 写入还需要 operator.admin；只读的 /config show 对普通写作用域操作员客户端保持可用。
mcp: true 启用 /mcp 用于 OpenClaw 管理的 MCP 服务器配置（mcp.servers 下）。
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 和网关重启工具动作。默认：true。
ownerAllowFrom 是所有者专属命令和所有者门控渠道动作的显式所有者白名单。与 allowFrom 分离。
ownerDisplay: "hash" 在系统提示中哈希显示所有者 ID。设置 ownerDisplaySecret 控制哈希。
allowFrom 是每提供端设置。设置后，它将是唯一授权来源（渠道白名单/配对和 useAccessGroups 被忽略）。
useAccessGroups: false 允许命令在未设置 allowFrom 时绕过访问组策略。
命令文档映射：
- 内置 + 捆绑目录：Slash Commands
- 渠道特定命令表面：Channels
- QQ Bot 命令：QQ Bot
- 配对命令：Pairing
- LINE 卡片命令：LINE
- 记忆做梦：Dreaming

常见问题

如何设置 Telegram 群组只回复 @提及？

在 channels.telegram.groups["*"] 中设置 requireMention: true（默认即如此）。如果需要特定群组例外，在 groups 下添加该群组 ID 并设置 requireMention: false。

Discord 配对码不生效，可能是什么原因？

确保 channels.discord.dmPolicy 设置为 "pairing"（默认）。检查 allowFrom 是否为空，配对码有效期 1 小时，且每个渠道最多 3 个待处理请求。如果 bot 没有读取消息权限，配对 DM 可能不会被接收。

iMessage 渠道无法接收消息，需要哪些权限？

OpenClaw 需要完全磁盘访问权限才能读取 Messages 数据库（~/Library/Messages/chat.db）。在 macOS 系统设置中为网关终端/应用授予完全磁盘访问权限。如果网关不在登录 Messages 的 Mac 上，需配置 channels.imessage.cliPath 为 SSH 包装器，并设置 remoteHost。另外 includeAttachments 默认为 false，如需接收媒体需设置为 true。

OpenClaw 渠道配置：DM策略、群组权限与多账户设置 ​

渠道配置 ​

DM 与群组访问策略 ​

渠道模型覆盖 ​

渠道默认值与心跳 ​

WhatsApp ​

Telegram ​

Discord ​

Google Chat ​

Slack ​

Mattermost ​

Signal ​

iMessage ​

Matrix ​

Microsoft Teams ​

IRC ​

多账户（所有渠道） ​

其他插件渠道 ​

群聊提及门控 ​

DM 历史限制 ​

自聊天模式 ​

命令（聊天命令处理） ​

相关链接 ​

常见问题 ​

如何设置 Telegram 群组只回复 @提及？ ​

Discord 配对码不生效，可能是什么原因？ ​

iMessage 渠道无法接收消息，需要哪些权限？ ​

OpenClaw 渠道配置：DM策略、群组权限与多账户设置

渠道配置

DM 与群组访问策略

渠道模型覆盖

渠道默认值与心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

iMessage

Matrix

Microsoft Teams

IRC

多账户（所有渠道）

其他插件渠道

群聊提及门控

DM 历史限制

自聊天模式

命令（聊天命令处理）

相关链接

常见问题

如何设置 Telegram 群组只回复 @提及？

Discord 配对码不生效，可能是什么原因？

iMessage 渠道无法接收消息，需要哪些权限？