实战 04：简易 OpenClaw——单渠道网关

#1、本篇交付物

实现一个 Telegram 或 Slack 单渠道 Gateway：验证身份、接收并去重事件、路由到内部 Session、异步运行 Agent、可靠发送回复、处理批准按钮、保存死信和运行记录。Agent Core 可以复用 LangChain/LangGraph，也可以接前面的 OpenCode Server。

第一版只接一个账号、一个渠道。多渠道、Memory、Skills、Cron 和多 Agent 放在后续专题。

#2、Gateway 与普通聊天机器人的区别

普通机器人常在 webhook 内直接调用模型并回复；Gateway 是长期运行的控制面：

复制Channel Adapter
  ↕ inbound/outbound
Gateway
  ├─ Identity / Pairing / Allowlist
  ├─ Conversation → Session Router
  ├─ Inbox / Outbox / Queue / Dead Letter
  ├─ Agent Runtime / Tool Policy / Approval
  ├─ Event Protocol / Control API
  └─ Config / Health / Audit

Gateway 进程管理连接、身份、Session 和调度；Agent 处理语义任务；工具服务执行动作。三层责任不可混在一个 webhook 函数里。

#3、统一渠道事件

各平台字段不同，Adapter 先转换成内部合同：

复制type InboundEvent = {
  id: string;
  channel: "telegram" | "slack";
  accountId: string;
  conversation: { externalId: string; kind: "dm" | "group" | "thread" };
  sender: { externalId: string; displayName?: string };
  message: { externalId: string; text?: string; replyTo?: string; attachments: Attachment[] };
  timestamp: string;
  rawHash: string;
};

内部 Agent 不读取平台 raw payload。发送侧也使用统一 OutboundMessage，由 Adapter 处理 Markdown、长度、线程回复、按钮和媒体差异。

#4、原始 Body 验签

验签必须在 JSON 解析和任何 body 修改之前完成，并验证时间戳窗口防重放。Express 示例：

复制app.post("/webhook", express.raw({ type: "application/json", limit: "1mb" }), async (req, res) => {
  verifyOfficialSignature({ headers: req.headers, rawBody: req.body, now: Date.now() });
  const raw = JSON.parse(req.body.toString("utf8"));
  const event = adapter.parse(raw, hash(req.body));
  await inbox.accept(event);
  res.status(200).json({ ok: true });
});

验签算法、challenge 和 ACK 时限按渠道官方文档实现。不要用 body 里的 token 自证身份；错误签名不入队，并以限速方式记录安全事件。

#5、Inbox、Outbox 与数据库

复制channel_accounts(id, channel, status, encrypted_credentials)
identities(channel, account_id, external_user_id, internal_user_id, status)
conversations(channel, account_id, external_conversation_id, kind, session_id)
inbox_events(channel, account_id, external_event_id, raw_hash, status, attempt, request_id)
outbox_messages(id, conversation_id, idempotency_key, payload, status, external_message_id)
pending_actions(id, session_id, internal_user_id, payload_hash, status, expires_at)
dead_letters(id, source_type, source_id, reason, attempts, last_error)

channel + account + external_event_id 唯一。数据库事务同时插入 inbox 与 outbox job；ACK 后 worker 异步消费。发送回复也通过 outbox，避免 worker 调渠道成功后崩溃而重复发送。

#6、身份、Pairing 和访问策略

陌生 DM 默认不直接进入 Agent，可采用 pairing code 或 allowlist。Identity 记录 external user 到 internal user 的已验证映射。群组采用两层门禁：群/频道 allowlist；mention/reply gate。被回复不应绕过成员 allowlist。

单人私人助手可以让自己的多个设备共享 main Session；一旦允许多人 DM，必须按 channel + account + peer 隔离 Session。Session 路由是消息上下文隔离，不是宿主机安全隔离；互不信任的用户应使用独立 Gateway/OS/容器边界。

#7、Session Router

复制function sessionKey(event: InboundEvent, policy: SessionPolicy): string {
  if (event.conversation.kind === "group")
    return `${event.channel}:${event.accountId}:group:${event.conversation.externalId}`;
  if (policy.dmScope === "main") return "main";
  if (policy.dmScope === "per-channel-peer")
    return `${event.channel}:${event.accountId}:dm:${event.sender.externalId}`;
  throw new Error("unsupported scope");
}

Router 查找或创建内部 Session，并把 channel event ID、identity、conversation address、tool profile 注入 runtime。用户文本不能指定 Session ID 或角色。

同一 Session 消息默认串行。运行中又到新消息时可排队、合并为 steering input，或要求显式取消；第一版选择排队最容易证明正确。

#8、Worker 执行协议

复制claim inbox event（租约 + attempt）
  → 加载 identity/conversation/session
  → 检查访问、速率、mention gate
  → 规范化文本/附件
  → agent.run(session, message, runtimeContext)
  → 将流式内部事件更新为 typing/progress（节流）
  → 事务创建 outbound message + outbox job
  → inbox processed

Worker 崩溃后租约过期可重取；Agent run 使用 inbox event ID 作为幂等 key，不能创建第二个 turn。达到重试上限进入 dead letter，并向允许的运维渠道告警。

#9、可靠发送

Sender 领取 outbox 租约，调用渠道 API，保存 external message ID。尽量使用渠道支持的 idempotency key；不支持时保存稳定 client message ID，并在不确定结果时查询或采用业务去重策略。

处理渠道限流：读取 retry-after；区分可重试 429/5xx 与永久 4xx；指数退避加随机抖动；单 conversation 保序；大消息按语义边界切分并防止重试时部分重复。

#10、工具与聊天审批

第一版只开放 search_docs/get_status/create_draft。发信、建日程、改文件等副作用创建 pending action，向用户发送摘要按钮：动作、目标、关键参数、影响和过期时间。

Callback 仍要验签和 inbox 去重；根据 verified identity 锁定 action；检查 user、Session、tenant、状态、过期和 payload hash；事务记录决定，再用同一 thread 恢复图。转发按钮或猜 action ID 无法批准他人的动作。

#11、命令、附件和群聊

命令解析在 Agent 前完成：/help、/status、/cancel、/new 是确定性控制命令，不必浪费模型调用。未知命令再作为普通文本或拒绝。

附件先检查平台元数据、大小、MIME 和下载域名，再存隔离 artifact；恶意文档只作为不可信内容。群聊只发送必要内容，禁止加载私有 DM memory；默认 mention gate，控制回复频率避免刷屏。

#12、配置和密钥

配置 schema 区分基础设施与 Agent 默认值：gateway bind/auth、channel account、session scope、tool profile、sandbox、rate limit。候选配置先校验，再原子替换并保留 last-known-good；渠道凭证进入密钥存储，不写明文日志。

默认 loopback 管理接口；远程 Control API 必须认证和 TLS/可信网络。健康检查区分 Gateway、Channel socket、queue、database、model/tool dependencies。

#13、端到端验收

同一 webhook 重投十次只有一个 turn；签名错误和旧时间戳不入队；陌生 DM 需要 pairing；多人 DM 的 Session 不串；群内未 allow/mention 不触发；Worker/Sender 在调用前后崩溃仍不丢不重；429 按 retry-after；审批被转发后拒绝；附件 prompt injection 不扩大权限；dead letter 可检查和安全重放。

完成本篇得到“可靠单渠道 Gateway”。后续三篇分别补足 OpenCode 上下文/扩展体系，以及 OpenClaw 的多渠道架构、Memory/Skills/Cron 和生产安全。

官方参考：OpenClaw Architecture、Session Management、Security。