三、接入示例：Telegram Bot

1. 创建 Bot

在 Telegram 找 @BotFather，/newbot 按提示创建，拿到 Bot Token。同时可关闭隐私模式（Privacy Mode）让它在群组里能看到普通消息——是否需要取决于你想让它在群里如何响应。

2. 把 token 以 SecretRef 写入

# 先把 token 放进 Gateway 进程的环境变量（如 TELEGRAM_BOT_TOKEN）
# 再用引用方式配置，不出现明文
openclaw config set channels.telegram.botToken \
  --ref-provider default --ref-source env --ref-id TELEGRAM_BOT_TOKEN

# 启用
openclaw config patch --stdin <<'JSON'
{ channels: { telegram: { enabled: true } } }
JSON

Telegram 默认长轮询（long polling），无需公网回调地址，内网/NAT 后也能用；Webhook 模式需要公网 HTTPS 端点，适合有固定域名的部署。

3. 配对（Pairing）与访问控制

Telegram 的 DM 默认策略是 pairing：第一个给 Bot 发私信的人，需要经过配对批准，避免任何人都能调用你的助手。流程：

# 你给 Bot 发一条 DM 后，从日志或配对回复里读取你的 Telegram 数字 user id
openclaw logs --follow
# 看到 senderUserId（纯数字，不是用户名/手机号）后停止跟随

把该 user id 写入 allowFrom（JSON 数组，严格类型）：

openclaw config set channels.telegram.allowFrom '["123456789"]' --strict-json

群组场景用 groupPolicy + groupAllowFrom：默认群组是 allowlist 模式，只在白名单群里响应，防止把 Bot 拉进陌生群被滥用。

4. Prove 验证

# 先 dry-run 看载荷，再发真实测试消息
openclaw message send --channel telegram --target <chatId> \
  --message "OpenClaw channel test — please ignore" --dry-run
openclaw message send --channel telegram --target <chatId> \
  --message "OpenClaw channel test — please ignore"

命令返回确认投递成功才算接入完成；失败则记录确切的账户/权限/网络原因，而不是含糊地说"连不上"。

四、其他渠道的差异点

虽然平台细节不同，但"拿凭证 → SecretRef 配置 → 访问控制 → Prove"这条主线完全一致。

五、多渠道下的会话与路由

会话键（Session Key）

每个对话上下文由"渠道 + 账户 + 聊天/话题"唯一定位。同一个人从 Telegram 和 Discord 发来，默认是不同会话，上下文不互通——这是有意为之，避免跨平台上下文串扰。Telegram 的论坛话题（forum topic）还能做到每个话题一个独立会话。

多账户

一个渠道可以配多个 Bot 账户（accounts）。配两个及以上时应显式设置 defaultAccount，否则系统回退到第一个账户并在 doctor 中告警。每个账户都需要有明确的 Agent owner。

绑定 Agent（bindings）

通过顶层 bindings 把"某渠道 + 某账户"或"某群组/话题"路由给指定 Agent：

{ agentId: "main", match: { channel: "telegram", accountId: "default" } }

缺少 owner 的账户会被置为 blocked，并给出需要补的 binding。利用这个机制，可以让"工作群里的 Bot"走严谨的工作 Agent，"私聊 Bot"走主 Agent，互不干扰。

六、诊断与修复

# 总览所有渠道及连接状态
openclaw channels list --all
openclaw channels status
openclaw channels status --probe   # 主动探测连通性

# 配置体检
openclaw doctor --lint             # 只读检查，可能 exit 1，读报告即可

# 查看当前渠道配置路径（首次设置前 "not found" 是正常的）
openclaw config get channels --json

# 写配置前确认该渠道的确切字段名（各渠道不同）
openclaw config schema --json | jq '.properties.channels.properties.telegram'

典型故障：

• 群组里 Bot 不说话：多半是 groupPolicy/allowlist 没放行，或 Telegram 隐私模式开启导致它根本收不到非@消息
• 启动报 token 未授权：token 错或被吊销，回 BotFather 重新获取并更新 SecretRef
• 长轮询不稳定：网络抖动/代理问题，配置网络出口或代理；轮询本就支持断线重连
• 命令不生效：native commands 未启用或命令菜单未同步
• 多账户走错 Agent：defaultAccount 未设、binding 缺失，按 status 给出的 remediation 补

七、安全实践

• 最小权限：DM 用 pairing，群组用 allowlist，绝不默认对所有人开放
• 凭证只用 SecretRef / 掩码输入，定期在平台侧轮换 token
• 群聊里助手不是你的"传声筒"，对代发、外发动作保持确认，避免它在群里泄露你的私有信息
• 给不同可信度的渠道/群绑定不同工具策略（tools policy），低信任环境收紧敏感工具

总结

OpenClaw 渠道系统用统一的适配器抽象，把十几个差异巨大的消息平台收敛成同一套接入流程：平台侧建 Bot 拿凭证 → 用 SecretRef 安全配置 → pairing/allowlist 控制访问 → 发真实消息 Prove。多渠道时记住会话天然隔离、多账户要显式 defaultAccount、用 bindings 决定每个渠道/群归哪个 Agent。按"配置 → probe → 真实消息验证"走，并用 doctor/channels status 诊断，就能让助手稳定地活在你最常用的聊天工具里。