摘要本系列面向已具备大模型与 Agent 基础的读者从架构—运行时—源码三层读 OpenClaw。本篇作为导读除统一术语与读源码方法外专门对齐 Architecture Overview 中的官方组件总表、设计原则与 Data flow 六步建立可对照 D1/D2 的架构骨架并给出资料可信度分级S0/D1/D2/D3、固定 commit与rg/测试的阅读约定以及全系列15 篇目录与阅读顺序。后续各篇将沿「Gateway → Router → Brain/Hands → Memory → Channels → 多 Agent → RFC/Heartbeat/安全/生态」展开。关键词OpenClaw系统架构Gateway多 Agent源码阅读资料分级系列导读1 为什么要单独写一篇「导读」OpenClaw 不是「又一个调用 OpenAI API 的脚本集合」而是一个长期驻留、以 Gateway 为中心、把通道、推理、执行与持久化记忆缝在一起的个人智能体运行时。若直接进入某段 TypeScript 实现很容易在「这是 CLI 还是网关」「这是通道回调还是 Brain 循环」里迷路。本篇目标有三点统一术语后面 14 篇都会用到的 Gateway / Router / Brain / Hands 等词在本篇一次性对齐含义。统一读法全系列引用源码时如何选 commit、如何用rg/测试定位避免「对着 main 漂移吵架」。统一路线图15 篇各自回答什么问题、与已发表的第2、第8篇如何衔接读者可按表索骥。理解要点把本篇当成「系列里的README glossary contributing guide」——不追求覆盖 OpenClaw 全部功能而追求后续篇能站在同一套语言上说话。2 核心模型单进程 Gateway 与多 Agent官方架构叙述Architecture Overview把系统压成一张「控制面 推理 执行 记忆 通道」的图。可以把它想象成一家餐厅Gateway 是前台与排号系统谁先来、谁被服务Router 决定订单进后厨还是吧台快取Brain 是主厨的脑子想菜谱、拆步骤Hands 是灶台上的手真炒菜Memory 是写在便签墙与台账上的持久笔记Channels 是外卖平台与电话线Skills 则是可插拔的预制酱料包扩展能力边界。多 Agent 场景下Multi-Agent Workflows、仓库 docs/concepts/multi-agent.mdOpenClaw 的典型形态是多个 Agent 共享同一个 Gateway 进程与端口但每个 Agent 拥有自己的工作区、状态目录、会话存储并可绑定不同通道与模型。这就像同一栋大厦里有多套独立公寓——共享电梯与物业Gateway但室内陈设与门禁卡workspace / session彼此隔离。实际例子工作与个人各一个 Agent、不同 IM 账号绑定到不同agentId仍由同一 Gateway 接入需要更强隔离时再开第二进程例如不同OPENCLAW_HOME与端口这在官方文档里作为「Separate Instances」类模式出现。2.1 组件一览表全系列共用词汇组件角色一句话后续篇目规划Gateway长驻控制面连接管理、健康、WebSocket 等第3篇起深入Router入站事件分发决定本轮是否进 Brain、是否走快捷路径第4篇Brain多厂商 LLM 调用、消息拼装、工具调用循环第5篇HandsShell、文件、浏览器等执行面与沙箱边界第6篇Memory本地优先持久化含与「人格文件」分工第7篇与第8篇成稿互证Channels各类消息通道与 Gateway 的桥接第9篇Skills工作区技能扩展与 Built-in、MCP 插件并列第2篇2.2 数据流以下六步与 Architecture Overview 中的Data flow一致文中「通道」可对应各类 IM / 邮件等接入不限于某一具体产品输入到达经通道如新消息、Heartbeat定时唤醒或CLI命令进入系统。Router 分发判断本轮需要进入Brain、调用某个Skill还是允许不经大模型、直接回复。Brain 推理由 LLM 理解请求、形成计划并决定是否走工具链。Hands 执行在此完成 Shell、文件读写、浏览器操作等带副作用的动作。Memory 更新把需在多轮对话中延续的上下文写回持久化载体具体形态与策略见第7篇。响应返回沿本轮输入来源的同一通道或对应客户端界面把结果送回用户。理解要点插图与下文 §2.5 的 mermaid 表达同一套语义若与某版本源码或本地部署不一致以S0pin 的 commit与D1/D2为准。2.3 端到端示例从用户输入到完整回复为了把抽象的六步数据流落地让我们追踪一条真实的用户请求如何在 OpenClaw 中流动。场景设定用户在微信/WhatsApp 上发送消息“帮我查一下明天上海的天气如果下雨的话提醒我今晚10点关好窗户”系统配置已接入WhatsApp 渠道Channels已安装天气查询 Skillweather-query/SKILL.md已启用定时提醒功能通过 Hands 调用系统cron或日历 API完整数据流追踪┌─────────────────────────────────────────────────────────────────────────┐ │ Step 1: 输入到达Input Arrival │ ├─────────────────────────────────────────────────────────────────────────┤ │ 用户手机 ──▶ WhatsApp 服务器 ──▶ [Channels 渠道层] ──▶ [Gateway:18789] │ │ │ │ • Channels 插件维持与 WhatsApp 的长连接WebSocket │ │ • Gateway 收到原始消息{from: 用户A, content: 帮我查一下..., ts} │ │ • Gateway 识别出关联的 Agent ID 和 workspace │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Step 2: Router 分发Routing Decision │ ├─────────────────────────────────────────────────────────────────────────┤ │ [Gateway] ──▶ [Router] 决策 │ │ │ │ • 这不是简单的问候语需要 LLM 理解意图 │ │ • 需要调用外部工具天气 API 定时器 │ │ • 决策结果路由到 Brain携带 context{user, channel, history} │ │ │ │ ❌ 不走的分支若只是你好Router 可能走「快捷回复」直接返回 │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Step 3: Brain 推理LLM Planning │ ├─────────────────────────────────────────────────────────────────────────┤ │ [Router] ──▶ [Brain] 加载系统提示词 用户消息 │ │ │ │ Brain 拆解为两步计划 │ │ 1. 调用 weather-query Skill 获取明天上海天气 │ │ • read 工具加载 skills/weather-query/SKILL.md │ │ • 按 Skill 说明调用天气 API │ │ │ │ 2. 条件判断如果 rainfall 0 │ │ • 调用 Hands 设置定时提醒今晚10点 │ │ • 否则跳过提醒 │ │ │ │ Brain 生成工具调用序列 │ │ json │ │ [{tool: read, path: skills/weather-query/SKILL.md}, │ │ {tool: http_request, url: api.weather.com/shanghai/tomorrow}, │ │ {tool: schedule_reminder, when: 22:00, what: 关窗户}] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Step 4: Hands 执行Tool Execution │ ├─────────────────────────────────────────────────────────────────────────┤ │ [Brain] ──▶ [Skills] ──▶ [Hands] │ │ │ │ 执行层动作 │ │ • Skills 层读取天气 Skill 的 SKILL.md按说明格式化 API 请求 │ │ • Hands 层 │ │ - Shellcurl 调用天气 API或浏览器访问网页 │ │ - File缓存天气数据到 /tmp/weather-shanghai-20260115.json │ │ - Scheduler向系统 cron 或日历 API 注册 22:00 提醒关窗户 │ │ │ │ 执行结果收集 │ │ • 天气明天上海小雨15-18℃降雨概率 80% │ │ • 提醒已设置今晚 22:00 推送通知 │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Step 5: Memory 更新State Persistence │ ├─────────────────────────────────────────────────────────────────────────┤ │ [Brain] ──▶ [Memory] 存储 │ │ │ │ • 对话历史用户问过天气 设置提醒用于多轮上下文 │ │ • 提醒任务{id: rem-001, time: 22:00, content: 关窗户, status: pending} │ • 用户偏好可能记住该用户关注上海天气用于 future 个性化 │ │ │ │ 存储位置 │ │ • 短期Gateway 内存中的 session snapshot │ │ • 长期~/.openclaw/agents/agentId/sessions/sessions.json │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Step 6: 响应返回Response Delivery │ ├─────────────────────────────────────────────────────────────────────────┤ │ [Brain 生成回复] ──▶ [Gateway] ──▶ [Channels] ──▶ 用户手机 │ │ │ │ 回复内容 │ │ 明天上海有小雨️气温 15-18℃记得带伞。 │ │ 已帮你设置今晚 22:00 的提醒到时我会再通知你关好窗户。 │ │ │ │ 异步事件当晚 22:00 │ │ • Heartbeat / Timer 触发 Gateway 唤醒 │ │ • Gateway ──▶ Router ──▶ Brain生成提醒消息 │ │ • Brain ──▶ Gateway ──▶ Channels ──▶ 用户手机 ⏰ 提醒关好窗户 │ └─────────────────────────────────────────────────────────────────────────┘关键观察点观察项本例体现对应后续篇目Gateway 的入口角色所有流量初始请求定时提醒都经 18789 端口第3篇Router 的智能分发区分需要 Brain vs “快捷回复”第4篇Skills 的渐进披露按需读取SKILL.md不常驻内存第2篇Hands 的副作用真实的 API 调用 系统定时器设置第6篇Memory 的跨会话延续存储的提醒任务在几小时后触发第7篇Channels 的双向通信接收用户消息 推送提醒消息第9篇理解要点这六步不是一次性瀑布流而是循环往复的协作——当晚 22:00 的提醒会再次触发 Step 1→6 的完整循环只是此时输入来源是内部定时器而非外部用户。2.4 架构纵深官方「Deep dives」索引自学用2.3 架构纵深官方「Deep dives」索引自学用若要在导读之后立刻往下钻建议优先读 D1仓库docs/中与架构强相关的入口路径以main为例精读时请换为你的pin commit链接docs/gateway/index.md — Gateway 总索引docs/gateway/network-model.md — 网络与发现docs/gateway/authentication.md — 鉴权docs/concepts/context-engine.md — 上下文装配与 Brain 紧密相关本篇不展开各文件细节避免与第3篇及以后重复你若能读完上述 23 个入口就已经比「只看一张 mermaid」多走了一层架构。3 资料分级S0 / D1 / D2 / D3全系列引用约定读开源项目时最大的噪音来自「博客写完了但与仓库真实行为不一致」。本系列约定如下档级与系列规划文档一致档级含义使用方式S0你本地clone的某一固定 commit上的源码与测试最终裁判行为以代码为准D1仓库内docs/Markdown与 S0 对照版本与源码同步演进D2官方文档站如 clawdocs.org、docs.openclaw.ai快速建立概念若与 D1/S0 冲突以S0D1为准并在文中说明D3第三方博客、商业托管站点的「架构解读」类文章叙事与场景可参考数字、API、能力列表需回 D1/S0 复核理解要点D1/D2/D3 是「资料来源类型」「第2篇、第8篇」是本系列博客的列表序号二者不要混读成「D2 等于第2篇」之类。4 如何读 OpenClaw 源码4.1 固定 commit全系列同一 SHAmain分支会持续合并若每篇文章引用不同时间点的路径与符号读者复制链接会对不上。建议git clone https://github.com/openclaw/openclaw.git到本地任意目录。在本系列开写时执行一次git rev-parse HEAD记下40 位 SHA。全系列正文里引用该仓库时优先使用https://github.com/openclaw/openclaw/blob/SHA/路径或在篇首写明「以下路径均相对于仓库根目录commit SHA」。实际例子你在 2026-04-11 拉取得到abc1234...则全系列 15 篇都写「基于abc1234...」若第12篇写作时上游大改可**新开一段「自本篇起更新 pin」**而不是悄悄混用。4.2 CLI、Gateway 与src/一级目录仓库根目录的package.json、工作区配置如pnpm-workspace.yaml若存在帮助你理解包边界与 Gateway 强相关的 CLI 行为通常可从src/cli/与仓库内docs/cli/gateway.md对齐认知。规划文档中归纳的src/一级目录线索用于第一篇建立「地图感」具体文件仍以你 pin 的 commit 为准agents、bindings、channels、chat、cli、commands、bootstrap、auto-reply等。后续篇会各自把子图放大。4.3 先「搜」再「读」缩小范围OpenClaw 仓库体量大不适合从某个入口文件按顺序硬读到底。更省力的做法是先有一个具体问题或报错栈里的符号名用关键词在目录里搜一遍只看命中文件与行号再顺着import/ 调用关系往下追。终端安装 ripgrep 后在克隆下来的仓库根目录执行rg与grep类似常用在src/下搜。示例引号内|表示「或」rggateway|WebSocket|daemonsrc rgroute|dispatch|incomingsrc rgsandbox|shell|execsrc extensionsVS Code / CursorCtrl Shift FMac 上多为Cmd Shift F打开在文件中查找在「要包含的文件」里限制./src等即可需要跟调用链时用F12转到定义、Shift F12查看引用。更多用法见各自主文档与键盘快捷方式设置。理解要点只记一条主路径——搜 → 打开命中处 → 用定义/引用跟链其余自行扩展即可。4.4 用测试当文档若某行为在 D2 上描述含糊优先搜*.test.ts/*.spec.ts中与该行为相关的用例名——测试通常给出了最小可复现的输入输出假设比注释更不容易过期。5 全系列 15 篇目录与阅读顺序#主题说明与链接1系列导读即本文。术语与官方组件表对齐、S0/D1/D2/D3 资料分级、pin commit、rg与 VS Code 全局搜索、全系列路线图。2Skills 机制SKILL.md目录发现、available_skills提示拼装、会话快照与 watcher、ClawHub 与.clawhub/lock.json、Built-in / Skills / Plugins 分层与源码走读。3Gateway单进程控制面WebSocket、守护与健康、鉴权与设备发现与docs/gateway/*、src/cli/对照读源码。03_OpenClaw_Gateway.md4Router入站事件如何分发是否进入 Brain、是否走 Skill、是否允许直回与官方 Data flow 第2步对齐。5Brain多厂商 LLM、消息拼装、工具调用循环、上下文压缩compaction与docs/concepts/context-engine.md等。6HandsShell、文件、浏览器执行面沙箱与权限边界docs/tools/multi-agent-sandbox-tools.md与多 Agent 场景。7Memory 子系统持久化 I/O、flush、与内置 memory 文档与第8篇分工本篇偏实现与载体第8篇偏八类人格文件的语义与自修改。8Learning AdaptationSOUL / AGENTS / MEMORY 等八文件、软学习范式、与 LangGraph 示例对照。9ChannelsIM 等通道如何接入 Gatewaysrc/channels/与extensions/*分工为第10篇 bindings 路由做铺垫。10多 Agent 核心agents.list、每 Agent workspace / state / session、bindings匹配规则与默认 Agent。11子 Agentsessions_spawn父子关系、官方文档所述「隔离、主要向父汇报」边界与「对等协作」差异。12Agent Teams RFCRFC: Agent Teams 导读原生编排 vs 外部工作流引擎、上下文序列化与延迟取舍。13Heartbeat周期唤醒、与 Router/Brain 触发关系docs/gateway/heartbeat.md与 cron 对照。14安全与成本多 Agent 攻击面、OPENCLAW_HOME强隔离、沙箱与按 Agent 选模型Cost Management 等。15生态编排Mission Control、Antfarm 等社区编排与 Gateway API 的关系对照第12篇收束「内核保证什么、生态补什么」。6 参考文献与链接OpenClaw 主仓库https://github.com/openclaw/openclawArchitecture OverviewD2含 Component Summary / Design Principles / Data flowhttp://clawdocs.org/architecture/overviewMulti-Agent WorkflowsD2http://clawdocs.org/guides/multi-agent仓库内 Gateway 与概念文档D1docs/gateway/index.md、context.md、features.md、multi-agent.md第三方架构叙事D3需与 D1/S0 交叉验证OpenClaw Architecture: 3 Conceptsgetclaw.shHow OpenClaw Worksmanagemyclaw.com