配置 — 个人消息频道

channels.* 配置键用于个人消息渠道：WhatsApp、Telegram、Signal、iMessage 和 LINE。

WhatsApp¶

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

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      streaming: { chunkMode: "length" }, // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

• 顶层 bindings[] 条目中的 type: "acp" 用于配置 WhatsApp 私聊和群组的持久 ACP 绑定。在 match.peer.id 中使用 E.164 直拨号码或 WhatsApp 群组 JID。字段语义与 ACP 代理 中的定义一致。

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

Telegram¶

{
  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: { mode: "partial" }, // off | partial | block | progress (default: partial)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      trustedLocalFileRoots: ["/srv/telegram-bot-api-data"],
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot 令牌：channels.telegram.botToken 或 channels.telegram.tokenFile（仅限普通文件；拒绝符号链接），默认账户可回退到 TELEGRAM_BOT_TOKEN。
• channels.telegram.joinIntro 默认为 true。当机器人加入一个被允许的群组或超级群组时，它会发布一条介绍，使用群组标题、描述和可用的置顶消息。Telegram Bot API 无法读取加入前的群组历史。将此项设为 false 可禁用介绍，或使用 channels.telegram.accounts.<accountId>.joinIntro 进行按账户覆盖。介绍每个群组只发生一次；参见 群组加入介绍。介绍绝不会在私聊中运行。
• apiRoot 仅是 Telegram Bot API 根地址。请使用 https://api.telegram.org 或你自托管/代理的根地址，而不是 https://api.telegram.org/bot<TOKEN>；openclaw doctor --fix 会移除误加的尾部 /bot<TOKEN> 后缀。
• 对于 --local 模式下自托管的 Bot API 服务器，trustedLocalFileRoots 列出了 OpenClaw 可以读取的主机路径。将服务器数据卷挂载到 OpenClaw 主机上，并配置其数据根目录或按令牌的目录；/var/lib/telegram-bot-api 下的容器路径会被映射到这些根目录中。其他绝对路径仍会被拒绝。
• 可选的 channels.telegram.defaultAccount 在匹配已配置的账户 ID 时，会覆盖默认账户选择。
• 在多账户设置（2 个及以上账户 ID）中，请设置显式的默认账户（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免回退路由；当此设置缺失或无效时，openclaw doctor 会发出警告。
• configWrites: false 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、/config set|unset）。
• actions.reactions 控制消息反应和 emoji-list，后者用于列出当前聊天中允许的标准和自定义反应。
• 顶层 bindings[] 条目中的 type: "acp" 用于为论坛主题配置持久 ACP 绑定（在 match.peer.id 中使用规范形式 chatId:topic:topicId）。字段语义与 ACP 代理 中的定义一致。
• Telegram 流式预览使用 sendMessage + editMessageText（适用于私聊和群聊）。
• network.dnsResultOrder 默认为 "ipv4first"，以避免常见的 IPv6 请求失败。
• 重试策略：参见 重试策略。

Signal¶

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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 数据库和自动化（Automation）权限时，这是新的 OpenClaw iMessage 设置的首选路径。

BlueBubbles 支持已被移除。channels.bluebubbles 不再是当前 OpenClaw 上受支持的运行时配置面。请将旧配置迁移到 channels.imessage；简短版本请参阅 BlueBubbles 移除与 imsg iMessage 路径，完整对照表请参阅 从 BlueBubbles 迁移。

如果 Gateway 未运行在已登录的 Messages Mac 上，请保持 channels.imessage.enabled=true，并将 channels.imessage.cliPath 设置为 Gateway 本地的 SSH 包装器的绝对路径，该包装器在该 Mac 上运行 imsg "$@"。将 remoteHost 设置为 Messages Mac，而不是 Gateway 主机。OpenClaw 会自动检测简单的透明 SSH 包装器以实现兼容，但复杂的包装器需要显式指定 remoteHost。默认的本地 imsg 路径仅适用于 macOS。

在依赖 SSH 包装器进行生产环境发送之前，请通过该确切包装器验证一次外发 imsg send。某些 macOS TCC 状态会将 Messages 自动化分配给 /usr/libexec/sshd-keygen-wrapper，这可能导致读取和探测正常，而发送失败并返回 AppleEvents -1743；请参阅 iMessage 中的 SSH 包装器故障排查部分。

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/home/openclaw/.openclaw/scripts/imsg-ssh",
      dbPath: "/Users/user/Library/Messages/chat.db",
      remoteHost: "user@messages-mac",
      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",
      sendTransport: "auto",
      region: "US",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
    },
  },
}

• 可选的 channels.imessage.defaultAccount 在匹配已配置账户 ID 时覆盖默认账户选择。
• 需要 Messages 数据库的完全磁盘访问权限（Full Disk Access）。
• 优先使用 chat_id:<id> 目标。使用 imsg chats --limit 20 列出聊天。
• 对于 SSH 设置，cliPath 是 Gateway 主机上的绝对路径。remoteHost（host 或 user@host）是 Messages Mac，dbPath 在该 Mac 上解析。请使用远程数据库的绝对路径，而不是从 Gateway 用户的主目录展开。
• 已配置或自动检测到的 remoteHost 可通过现有的严格 SSH/SCP 传输实现入站附件获取和出站文件暂存。出站文件使用仅所有者可访问的远程临时路径，并在成功、失败或超时后尽力清理；清理失败会发出警告，并可能留下仅所有者可访问的残留文件。
• attachmentRoots 和 remoteAttachmentRoots 限制入站附件路径（默认：/Users/*/Library/Messages/Attachments）。
• SCP 使用严格的主机密钥检查，因此请确保 Messages Mac 的主机密钥已存在于 ~/.ssh/known_hosts 中。
• channels.imessage.configWrites：允许或拒绝 iMessage 发起的配置写入。
• channels.imessage.sendTransport：常规外发回复的首选 imsg RPC 发送传输方式。auto（默认）在 IMCore 桥接运行时对现有聊天使用该桥接，然后回退到 AppleScript；bridge 需要私有 API 投递；applescript 强制使用公共 Messages 自动化路径。
• channels.imessage.actions.*：启用同样受 imsg status / openclaw channels status --probe 门控的私有 API 操作。
• channels.imessage.includeAttachments 默认关闭；在期望智能体对话轮次中出现入站媒体之前，请将其设置为 true。
• 桥接/Gateway 重启后的入站恢复是自动的（GUID 去重加上陈旧积压消息的时限围栏）。现有的 channels.imessage.catchup.enabled: true 配置仍作为已弃用的兼容配置文件被支持；catchup 默认禁用。
• channels.imessage.groups：群组注册表和各群组设置。使用 groupPolicy: "allowlist" 时，配置显式的 chat_id 键或 "*" 通配符条目，以便群组消息可以通过注册表门控。
• 顶层 bindings[] 中 type: "acp" 的条目可以将 iMessage 对话绑定到持久化 ACP 会话。在 match.peer.id 中使用规范化句柄或显式聊天目标（chat_id:*、chat_guid:*、chat_identifier:*）。共享字段语义：ACP 智能体。

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

LINE¶

LINE 由插件支持，并在 channels.line 下配置。

• channels.line.joinIntro 默认为 true。当机器人加入被允许的群组或多人群聊房间时，它会发布一条介绍，并在可用时使用群组名称。LINE 不暴露多人群聊的房间名称或主题，其 Messaging API 也无法读取历史消息。将此选项设置为 false 可禁用介绍，或使用 channels.line.accounts.<accountId>.joinIntro 进行特定账户的覆盖。介绍每个房间只发生一次，且绝不会在一对一用户聊天中触发；请参阅 群组加入介绍。
• 完整的 LINE 配置、webhook 设置和访问策略记录在 LINE 中。