【阅读笔记】OpenClaw入门

深度拆解 Clawdbot（OpenClaw）架构与实现

原帖作者：ℏεsam（X：@Hesamation） OpenClaw：https://deepwiki.com/openclaw/openclaw 相关实现解读：
https://x.com/Hesamation/article/2017038553058857413

是什么

OpenClaw（曾用名 Clawdbot、Moltbot）是一款开源、自托管、可执行真实任务的本地 AI 助手 / 自主代理。基于Pi Agent框架，打造了一个能自主决策、能持久记忆、能跨平台交互的AI助手

它怎么把这类系统做得更稳、更可控

最近半年写/用 Agent 的人，大概率都踩过同一类坑：模型未必是瓶颈，系统一"动手"，工程侧立刻露馅。并发乱、状态飘、日志不可读、工具权限没边界、失败不可回放……最后你会发现，提示词再华丽，也兜不住这些问题。这篇我想把 OpenClaw（Clawdbot）的架构拆开讲清楚。我更关心的是：它怎么把这类系统做得更稳、更可控。起因是我在 X 上刷到一条关于 Clawdbot 架构的拆解帖。它不是"神话能力"，而是用一套很工程的语言，把组件边界、执行链路、可靠性取舍讲得很清楚。原帖作者 @Hesamation 的出发点很实在：他想搞清楚 Clawdbot 的记忆系统到底怎么工作、可靠性如何。最后他发现，真正值得学的不是"它能做什么"，而是"它怎么把这些事做得更稳"。

• OpenClaw 的本体是 TypeScript CLI 进程，外加一个负责多渠道接入的 Gateway Server；它不是 Web App。
• 它把可靠性放在第一位：默认串行，显式并行（lane queue）。并发不是"性能技巧"，先是"可靠性问题"。
• Agent Runner 更像一条装配线：模型选择与 Key 冷却、Prompt 组装、历史加载、上下文窗口守护，然后驱动工具循环。
• 记忆不神秘：JSONL 转录（可回放）+ Markdown 记忆文件（可编辑）；检索用 向量 + 关键词 混合，落在 SQLite（FTS5）。
• 工具调用的安全边界必须系统化：allowlist + 结构化拦截（重定向/命令替换/子 Shell/链式执行等直接拒绝），别把"自觉"当机制。
• 浏览器不主要靠截图：用语义快照（Accessibility Tree/ARIA）把"看网页"降维成"读结构"，成本更低、成功率更稳。

架构解析

一条主链路讲清楚：消息进来之后发生了什么

把 OpenClaw 翻译成工程视角，就是一条清晰的流水线：

1. Channel Adapter：把不同渠道的输入统一成标准消息，并提取附件。
2. Gateway Server：会话协调器，决定这条消息应该进入哪个会话、排到哪个队列。
3. Lane Queue：每个会话默认串行；确实低风险的任务才允许并行。
4. Agent Runner：拼上下文、选模型、发起调用，驱动工具循环。
5. Agentic Loop：模型提出 tool call → 执行 → 结果回填 → 下一轮，直到输出或触达上限。
6. Response Path：把最终内容流式回写到渠道，同时把全过程写入可回放的转录（JSONL）。

这类架构的价值不在"酷"，在于边界清楚：你一眼能看懂"问题卡在哪一步"，也更容易把问题隔离。再补一个很实用但经常被忽略的点：❓响应链路本身也应该被当成系统的一部分。

原帖里提到 LLM 调用是流式输出，最终响应通过渠道回到用户；同时会话会被持久化成 JSONL（每行一个 JSON，对应用户消息、工具调用、执行结果、模型响应等）。这意味着"看到的输出"只是表层，下面还有一条可回放的证据链。

默认串行，显式并行：lane queue 为什么这么关键

OpenClaw 的克制在于：它把并发的选择权，从"开发者随手写的异步"收回到一个显式的系统约束里。

这个思路也和 Cognition 的 “Don’t Build Multi-Agents” 博文不谋而合：简单的 async 设置会让你陷入日志交织、状态竞争的泥潭。

工程上我建议你把并发决策做成三个层级：

• 默认串行：先保证任何链路都能稳定复现。
• 显式并行：只开放少数"无共享状态/幂等/可重试"的任务。
• 隔离失败域：并行任务失败，不影响主会话；失败能在日志里单独定位。你会发现，这套约束比"并发技巧"更值钱，因为它减少了你未来的 debug 成本。
  

Agent Runner：把"提示词工程"变成"上下文装配线"

真正能跑起来的系统，往往把提示词当成装配线上的一环，而不是宗教。在 OpenClaw 的描述里，Runner 做的事很具体：

• Model Resolver：决定用哪个模型；Key 失效标记冷却并切换；主模型失败自动换备用。
• System Prompt Builder：动态拼装系统提示词，把工具、技能、记忆整合进去。
• Session History Loader：加载会话历史（来自 .jsonl 转录）。
• Context Window Guard：上下文快满时压缩（总结）或降级/停止，避免"撑爆以后才知道"。

这套拆分带来两个立刻可感知的收益：

• 你能把"模型质量"和"系统质量"拆开看：模型波动时，系统依然可控。
• 你能做复盘：因为历史、工具调用、工具结果都是结构化记录，能回放、能对账。

顺着这条线，原帖还强调了 LLM 调用层的两个点：

• 流式输出：让"生成过程"可观察，也更利于把中间态回传给上层。
• 多厂商抽象：同一层对接不同模型提供方；如果模型支持，还可以请求"扩展思考"能力。

工程上这意味着：你不该把"换模型/换 Key/失败兜底"写散在业务逻辑里，而是收敛在 Runner 的职责边界里。

Agentic Loop：奇迹发生的地方，也是事故高发区

工具循环大家都懂：tool call → 执行 → 回填 → 下一轮，直到输出或触达轮次上限（例如 20 轮）。

但工程上真正需要盯住的是三件事：

• 终止条件：什么时候该停？停得是否可解释？
• 工具输出的格式：工具返回是"日志"，还是"可被模型消费的证据"？
• 回填策略：回填太多撑爆上下文，回填太少模型又失明。

Context Window Guard 的价值也在这里：把"上下文爆炸"做成显式组件，而不是靠经验拍脑袋。你可以不追求每次都成功，但你不能接受失败时无从定位。

记忆：别神化，文件也能打

我很喜欢它对"记忆"的去神秘化处理：简单、可解释、可迁移。它主要靠两条线：

1. JSONL 会话转录：每一行一个 JSON 对象，包含用户消息、工具调用、执行结果、模型响应。
2. Markdown 记忆文件：放在 MEMORY.md 或 memory/ 目录下。

⚠️这相当于把记忆拆成两类：

• “发生过什么”（转录，偏事实、偏审计）
• “应该记住什么”（摘要与沉淀，偏经验、偏复用）

检索：向量 + 关键词的混合

很多系统只做向量检索，最后会踩一个坑：你以为找的是"精确概念"，结果召回一堆"语义相近但不对"的东西。OpenClaw 的思路更稳一点：向量检索负责语义召回，关键词匹配负责精确命中。

同步：Smart Syncing + 文件监控

记忆文件更新也不需要一套"专用记忆 API"。更朴素的方式就够了：Agent 用"写文件工具"写入 memory/*.md，文件监控器检测到变化后触发同步与索引更新。

它还提到一个细节：**新对话开始时，会有一个钩子把上一轮对话抓出来，写一份 Markdown 总结。**你可以把它理解成"把经验沉淀变成默认动作"，而不是全靠用户手动整理。

这点我很认可：工具越底层，越不容易被你自己未来的"架构升级"搞死。

原帖作者也提到，这套记忆系统和 @CamelAIOrg 实现的工作流记忆非常相似：没有复杂的记忆合并，没有按周/月的记忆压缩。简单可解释，胜过复杂的意大利面。

代价：没有遗忘曲线

它的记忆会长期保存，旧记忆与新记忆权重接近，也就意味着"它不太会自然遗忘"。

这既是优势也是风险：

• 优势：可追溯、可解释，复盘方便。
• 风险：过期经验可能持续被召回；你需要显式的版本化、有效期或冲突解决策略。

如果你打算照抄这一套，我建议至少补两个机制：

• 给记忆加 updated_at 与 confidence 的元信息（哪怕只是写在 Markdown 里）。
• 定期把"已过期/已被推翻"的结论写成一条新记忆，覆盖旧结论，而不是悄悄删掉。

附录

TypeScript CLI是什么

TypeScript CLI（命令行界面）进程，核心是用 TypeScript 开发可执行的命令行工具，并完成编译、运行、打包的全流程。相比纯 JavaScript CLI，TypeScript 提供类型安全、代码提示，能大幅降低大型 CLI 工具的维护成本。

TypeScript 和 Node.js 的关系：从核心定位到实际应用
TypeScript（简称 TS）和 Node.js 是互补而非替代的关系 ——Node.js 是运行 JavaScript 的服务器端运行时，TypeScript 是 JavaScript 的超集（带类型的 JS），最终需编译为 JS 才能在 Node.js 中运行。
用一句话概括：Node.js 是 “运行环境”，TypeScript 是 “开发语言 / 工具”，TS 为 Node.js 开发提供类型安全，Node.js 为 TS 代码提供执行载体。

语义快照（Accessibility Tree/ARIA）

浏览器从 DOM 树中剥离样式、脚本、装饰节点，只保留可交互、有语义的元素，生成的精简树结构。

每个节点包含四大核心属性：

• role：元素语义类型（button、heading、checkbox、link 等）
• name：可访问名称（按钮文字、输入框标签、aria-label）
• state：交互状态（checked、expanded、disabled、invalid 等）
• description：补充描述（aria-description、aria-describedby）

语义快照的核心价值：

• 不是视觉截图，而是语义结构的文本化表达
• 体积比 DOM 小 90%+，比截图小更多，适合 LLM 理解
• 是 AI 智能体（如 OpenClaw、Playwright MCP）操作网页的 “眼睛”

语义快照 = Accessibility Tree 的文本化快照 + ARIA 语义增强，是让辅助技术与 AI 智能体看懂、操作网页的核心技术，兼顾隐私、效率、精准度。

它带来的优势非常现实：

• 体积：截图可能到 5MB 级别；语义快照往往不到 50KB。
• 成本：Token 开销通常只是图像方案的一小部分。
• 精度：从"点坐标"变成"选节点引用"，成功率更稳定。
• 速度：纯文本解析比 CV 处理快得多。

你可以把它当成一种工程化取舍：只要任务不是强视觉依赖（比如识别图表细节、读验证码、找颜色差异），语义快照往往更可靠。

竞态关系（race condition）

竞态条件是多线程 / 多进程程序中，因多个执行流 “竞争” 共享资源且执行顺序不可控，导致程序结果不符合预期的错误。

竞态条件发生的三个必要条件：

• 共享资源：多个执行流（线程 / 进程）访问同一个可变资源（变量、文件、数据库、内存等）；
• 非原子操作：对共享资源的操作不是 “一步完成”（如 “读取→计算→写入” 是三步操作）；
• 执行顺序不可控：操作系统调度线程 / 进程的顺序随机，无法保证操作的原子性。