2026 OpenClaw 通道接入实操
Slack / Discord / Telegram 权限、OAuth 与「能连但不回」分症状排查清单

先把「像连上却没反应」拆成六类通道症状

通道问题常被误报为「模型坏了」或「compose 网络又炸了」。在改镜像或调 network_mode 之前，先用下列标签描述现象，并与《Docker 网络分诊》中的症状表对照，避免两条线同时改动无法复盘。

1. 入站事件缺失：应用后台显示在线，但频道里新消息不会触发任何 Gateway 日志行；多见于 Slack 事件订阅未开、Discord Gateway intent 不足、或 Telegram 隐私模式阻挡群聊。
2. 只收私聊不收频道：OAuth scope 或 Bot 加入策略只覆盖 DM，频道消息被 silently drop；需要在各平台检查 channel 列表与 bot 成员身份。
3. 能解析命令但不回贴：入站日志有，回复路径被 groupPolicy、thread 策略或「仅同步已提及」类规则挡住；日志里常出现路由到空 agent 或权限拒绝。
4. 间歇性 OAuth / token 过期：控制台全绿，几小时后突然全红；多见于 refresh token 轮换未写回密钥仓、或容器重启后未挂载同一 .env。
5. 多工作区 / 多 guild 串线：同一进程绑了多个 Slack workspace 或 Discord server，配置合并错误导致消息路由到错误回调 URL。
6. 模型层误伤：通道层其实正常，但上游 429/5xx 让用户以为「机器人死了」；必须看 Gateway 与 provider 日志占比，并回到《provider 降级篇》。

把这六类与「最近是否改过 allowedOrigins、是否滚动过镜像」写在同一变更单上，值班同学才能在五分钟内选对分诊分支。

表 1：三层分诊——Gateway、通道、模型谁先背锅

下列表格是「先看哪一层」的决策矩阵，不是排他结论；每一格都应对应一条可执行的下一步命令或日志关键字。实务上建议先在纸上画三条竖线：左侧写「用户侧可见现象」，中间写「Gateway 日志里最先出现的异常类型」，右侧写「是否出现上游模型 HTTP 状态码」。只要中间列长期空白，就不要急着改 provider；若右侧先出现大量 429，则通道 OAuth 再授权十次也救不了账单。

与《Docker 网络分诊》配合阅读时，可把「容器内 channels 探针失败」视作第 0 层：先确认同一 compose 网络里 CLI 能打到 Gateway，再进入下表；否则你会在 Slack 后台看到永远健康的 webhook 记录，却在宿主机上面对 endless timeout。

三条应写进监控面板的通道 KPI

下列指标把「感觉机器人卡了」拆成可告警的数值；口径应与 Gateway 现有日志字段对齐。建议以小时桶聚合，而不是秒级抖动，否则夜班会被无意义告警淹没。

1. 入站事件率（IER）：单位时间内通道层确认收到的事件数除以业务侧发送次数；长期低于 0.9 优先查 OAuth 与订阅，而不是 GPU。
2. 路由命中率（RHR）：成功绑定到目标 agent 的入站占比；若下降而 IER 正常，说明策略或频道映射腐烂。
3. 回复完成率（RCR）：从入站到模型返回 200 的端到端比例；若 IER、RHR 均高而 RCR 低，模型层优先。

社区文档在 2026 年仍强调 openclaw channels status --probe 一类探针；把探针结果与上述三率放在同一面板，可避免「重连一下就好」的不可复现操作。若你们已在《Gateway 健康检查与滚动更新》里配置了 HTTP 探针，请确认探针 URL 与通道回调实际经过的反向代理路径一致：探针只打 loopback 而公网回调走另一证书链时，会出现「监控全绿、用户全红」的经典错位。

补充一条人工对照口径：每周随机抽十条用户消息，核对「平台侧消息 ID → Gateway request ID → 模型 trace ID」是否能在三处日志里闭环；若任一环缺失，说明结构化日志字段未对齐，优先修字段再谈扩容。

六步 Runbook：从探针到可回滚的授权变更

1. 冻结变更面：记录当前镜像标签、环境变量哈希与最近三次 compose 变更；通道问题常与滚动发布同日出现。若同日还改过 allowedOrigins 或 TLS 证书，请在变更单上显式写出「回滚到上一证书指纹」的步骤，避免 OAuth 回调与 CORS 同时坏。
2. 跑 Gateway 基线：确认本机或容器内 gateway status 与《doctor 篇》中的健康检查一致。若使用 systemd 或 launchd，请核对重启策略：频繁重启会把通道 WebSocket 打到平台侧频控。
3. 按平台逐项授权：Slack 重走 OAuth，核对 scope；Discord 勾选必要 intent 并重新邀请 bot；Telegram 用 BotFather 关闭隐私模式或确保群聊 @bot。授权完成后等待平台侧缓存失效窗口（常见 5–15 分钟），不要连续点十次重授权制造限流。
4. 验证最小对话：各平台用单频道、单 agent、无额外策略复现一次 ping-pong，再恢复 groupPolicy。建议把测试消息打上固定前缀，便于在日志里 grep，而不是在千人群里刷屏。
5. 对照模型层：若 ping-pong 仍失败，抓取 30 秒日志统计 429 占比，再决定是否切 provider。若 429 集中在某一 key，请检查是否误把消费级套餐密钥当成按量计费 key 混用。
6. 写回运维笔记：把 token 轮换策略与密钥存放路径写进与《Docker 网络篇》同一仓库，避免「只有某人电脑能发版」。对外部协作方只给最小 scope 的只读 token，主密钥仍走内部 KMS 或 sealed secret。

Slack / Discord / Telegram 快速检查表（平台差异一页收）

下列检查项应与各平台官方控制台对照执行；不要依赖截图过期的「权限列表」。若团队同时维护 staging 与 production 两个 workspace，请把回调 URL 主机名写成表格里的独立一列，避免 staging 证书被误绑到 prod DNS。

• Slack：App 级 token 与 bot token 是否同时有效；事件订阅 URL 是否指向当前可公网访问的 Gateway；Socket Mode 与 HTTP 模式是否混用导致双订阅。若使用 Enterprise Grid，请确认每个 workspace 的安装记录是否都指向同一 OAuth client，否则会出现「有的区能收、有的区收不到」。
• Discord：Message Content Intent、Server Members 等是否与真实读消息需求一致；bot 是否在目标频道可见；频道级权限是否拒绝发送。大服务器上常见「频道覆盖权限」与「类别继承」互相打架，建议用 Discord 自带的权限诊断视图逐条对照，而不是只看 bot 角色名。
• Telegram：Webhook 与长轮询是否二选一；证书与回调 URL 是否随滚动发布漂移；群聊是否在隐私模式下要求显式 mention。若走自签证书，请确认 Telegram 要求的端口与 TLS 版本仍被当前 Gateway 监听；证书轮换日建议单独发变更窗口而不是与功能发布叠在同一天。

三平台都与出站 IP 稳定强相关：若 Gateway 跑在会随机切换出口的家用宽带或频繁重拨的 VPN 上，平台侧可能把 webhook 当作异常流量；这与《多地区云 Mac》里强调的固定区域与可审计出口一致——当你准备把机器人交给团队长期依赖时，应优先把控制面搬到可达性可证明的环境，而不是在客户端网络里打游击。

为什么「只在个人笔记本上挂通道」难撑团队级 OpenClaw

个人设备睡眠、VPN 与本地代理会改变出站 IP 与 TLS 指纹，导致 OAuth 回调与平台侧白名单随机失败；多人共用时也无法把 token 轮换与审计字段写进统一密钥仓。把 Gateway 与通道进程放在可值班、网络出口稳定、可按区域部署的执行平面，才能与团队级 agent 策略一致。

对需要长期在线、固定回调域名与可预测出口的 OpenClaw 拓扑而言，MACCOME 在新加坡、日韩、香港与美东美西提供的 Mac Mini M4 / M4 Pro 云主机适合作为 Gateway 与 Apple 工具链共存的常驻节点；通道分诊完成后，可在《SSH 与 VNC 指南》与帮助中心核对接入，再按公开价格与区域页扩展租期。

试点建议：先在独占测试机上用单频道跑满 24 小时 IER 与 RCR，再接入生产 workspace，避免「大群一放开就全红」的不可逆事故。