配置 — 个人消息频道
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 代理 中共享。
多账号 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。
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 token:
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 主机上挂载服务器数据卷,并配置其数据根目录或按 token 划分的目录;/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 数据库和自动化权限时,这是新的 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 数据库拥有完全磁盘访问权限。
- 优先使用
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:普通出站回复的首选imsgRPC 发送传输方式。auto(默认)在 IMCore 桥接运行时用于现有聊天,然后回退到 AppleScript;bridge要求私有 API 投递;applescript强制使用公开的 Messages 自动化路径。channels.imessage.actions.*:启用私有 API 操作,这些操作还受imsg status/openclaw channels status --probe控制。channels.imessage.includeAttachments默认关闭;在期望代理轮次中出现入站媒体之前,请将其设置为true。- 桥接/网关重启后的入站恢复是自动的(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 Agents。
iMessage SSH 包装器示例
对于远程 imsg v0.13.4,投票必须使用 pollOptionId;其 poll.vote RPC 方法不会解析索引或文本选择器。对非零部分索引的附件回复在远程也不可用。这些限制不会改变本地 imsg 行为。
LINE¶
LINE 由插件支持,并在 channels.line 下配置。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw