系统架构详解
这篇文章用于建立“全局工程脑图”：当你在日志、事件、配置里遇到问题时，能快速判断自己处在哪一层、该去哪个入口排查。
架构总览（从入口到出口）
OpenClaw 可以理解为一套“多入口 + 单内核”的运行时：
- 入口层：Channels（WhatsApp/Telegram/Discord…）与自动化入口（Webhooks/Cron…）
- 控制平面：Gateway（WebSocket/HTTP 服务、鉴权、路由与状态广播）
- 执行平面：Agent（run/attempt 生命周期、lane/queue 并发、流式输出）
- 能力层：Tools（Browser/Exec/Web…）与 Providers（模型与回退）
- 数据层：Sessions、Media、Config、日志与审计
如果你刚跑通安装与向导，建议先把这 3 个入口记住：
- 观测与交互：
Control UI - 诊断：
doctor - 排障：
troubleshooting
关键组件（你会反复遇到的名词）
Gateway（控制平面）
Gateway 是长期运行的核心进程，典型职责包括：
- 维护与各 Channel/Provider 的连接与生命周期
- 暴露 WebSocket/HTTP API，处理请求并广播事件
- 统一鉴权（token / pairing / remote 访问边界）
- 维护会话与并发（
sessionKey/ lane / queue）
相关入口：
Channels（消息入口）
Channels 是用户与系统交互的入口；不同平台的连接方式、消息格式与限制不同，但最终都应被收敛到统一的“入站消息 → 路由 → 会话”流程。
相关入口：
Routing + SessionKey（把消息“分桶”）
系统需要把不同来源（私聊/群聊/不同平台/不同账号）的消息稳定地映射到会话：这通常由 sessionKey 完成，它决定了：
- 哪些消息会串行（同一 sessionKey）
- 哪些消息可以并行（不同 sessionKey）
- 如何避免“串线”（群聊/多账号/多通道）
相关入口：
Agent（执行平面：run/attempt）
Agent 接收一次“需要回复/需要执行”的任务，常见链路是：
- 入站消息被路由到某个
sessionKey - 进入 lane/queue（同会话串行、跨会话并行）
- 触发一次 run，并可能拆成多个 attempt（例如回退/重试）
- 期间穿插工具调用（Browser/Exec/Web…）与流式输出
- 产出最终回复，再回到 Channel 出站发送
相关入口：
Tools（把“说”变成“做”）
Tools 负责执行有副作用的动作（系统命令、浏览器自动化、网络请求等）。关键不是“能做什么”，而是“如何可控地做”。
相关入口：
Providers（模型与回退）
Providers 负责把“提示词与上下文”变成“模型输出”，并在失败场景里提供可控的回退策略。
相关入口：
一次消息的完整旅程（建议你能在日志里复现）
把一次交互拆成“可观测”的步骤，有利于排障：
- 入口：某个 Channel 收到消息（或 Webhook/Cron 触发）
- 路由：根据账号/群组/线程等信息生成
sessionKey - 并发：进入 lane/queue（同 sessionKey 串行）
- 执行：Agent 运行，可能产生工具调用与流式事件
- 出站：回复回到 Channel，发送给用户
最实用的“硬验收”是：你能在 Control UI 或日志中用同一个 runId 追踪上述关键节点（详见 日志）。
安全边界（把风险分层）
建议把安全问题按层处理，而不是“全靠提示词约束”：
- 入口边界：remote 访问、trusted proxy、token、pairing（谁能连上 Gateway）
- 执行边界：Sandbox / tool policy / approvals（一次工具调用能做什么）
- 审计与追踪：日志、诊断与最小可复现链路（出了问题怎么追）
相关入口：