设计多渠道统一入站与出站接口协议

[Altergom]

背景

微信、飞书、QQ Bot 的消息结构、身份字段和发送方式都不一致。如果没有统一协议，后续每接一个渠道都需要在业务层重复做一遍解析、路由和发送逻辑，最终会导致网关与具体渠道强耦合。

因此需要先定义多渠道统一的入站与出站接口协议，确保不同渠道都通过同一套事件模型与网关交互。

实现思路

• 设计统一的入站事件模型，用于承接所有下游渠道消息
• 入站协议至少覆盖以下信息：
  • channel
  • account_id
  • peer_id
  • peer_type
  • message_id / event_id
  • payload
  • raw / metadata
• 设计统一的出站消息模型，用于把网关动作发送回下游渠道
• 平台特有字段不进入主协议，只放入 raw 或 metadata
• 统一协议必须支持至少以下消息类型：
  • text
  • image
  • audio
• 统一协议必须能支撑后续会话路由、状态机推进和 Agent 对接
• 明确接口边界：
  • 渠道适配层负责平台协议转换
  • 网关只消费统一协议

相关链接

• OpenClaw Chat Channels
  https://docs.openclaw.ai/channels

• OpenClaw WeChat Channel
  https://docs.openclaw.ai/channels/wechat

• OpenClaw Feishu Channel
  https://docs.openclaw.ai/channels/feishu

• OpenClaw QQ Bot Channel
  https://docs.openclaw.ai/channels/qqbot

验证标准

• 形成一版明确的统一入站协议定义
• 形成一版明确的统一出站协议定义
• 明确所有下游渠道字段如何映射到统一协议
• 明确哪些字段是主协议字段，哪些字段只能进入扩展字段
• 明确后续任何渠道接入都不得绕过统一协议直接进入业务逻辑