最近半年写/用 Agent 的人,大概率都踩过同一类坑:模型未必是瓶颈,系统一"动手",工程侧立刻露馅。
并发乱、状态飘、日志不可读、工具权限没边界、失败不可回放……最后你会发现,提示词再华丽,也兜不住这些问题。
这篇我想把 OpenClaw(Clawdbot)的架构拆开讲清楚。我更关心的是:它怎么把这类系统做得更稳、更可控。
起因是我在 X 上刷到一条关于 Clawdbot 架构的拆解帖。它不是"神话能力",而是用一套很工程的语言,把组件边界、执行链路、可靠性取舍讲得很清楚。
原帖作者 @Hesamation 的出发点很实在:他想搞清楚 Clawdbot 的记忆系统到底怎么工作、可靠性如何。最后他发现,真正值得学的不是"它能做什么",而是"它怎么把这些事做得更稳"。
太长不看版(6 条)
- • OpenClaw 的本体是 TypeScript CLI 进程,外加一个负责多渠道接入的 Gateway Server;它不是 Web App。
- • 它把可靠性放在第一位:默认串行,显式并行(lane queue)。并发不是"性能技巧",先是"可靠性问题"。
- • Agent Runner 更像一条装配线:模型选择与 Key 冷却、Prompt 组装、历史加载、上下文窗口守护,然后驱动工具循环。
- • 记忆不神秘:JSONL 转录(可回放)+ Markdown 记忆文件(可编辑);检索用 向量 + 关键词 混合,落在 SQLite(FTS5)。
- • 工具调用的安全边界必须系统化:allowlist + 结构化拦截(重定向/命令替换/子 Shell/链式执行等直接拒绝),别把"自觉"当机制。
- • 浏览器不主要靠截图:用 语义快照(Accessibility Tree/ARIA) 把"看网页"降维成"读结构",成本更低、成功率更稳。
图 1:原始架构图(原图)
图 2:OpenClaw 核心链路
先把它放回正确的分类:它到底是什么
很多人聊 Agent,一开口就是"自治""多智能体""进化"。
但落地时,你更需要先回答一句话:你做的是聊天机器人,还是"能在你的机器上执行工具的系统"?
OpenClaw 的定位很明确:它是一个 运行在你机器上的进程,负责三件事:
- • 接收来自不同渠道的消息(Telegram、Discord、Slack 等)。
- • 调用 LLM API(OpenAI、Anthropic、本地模型等)。
- • 在本地或受控环境里执行工具(Shell、文件、浏览器、进程),再把结果回写给你。
这句话看起来朴素,但它把架构重心直接钉死了:执行的可控性、状态的可追溯性、失败的可解释性。
一条主链路讲清楚:消息进来之后发生了什么
把 OpenClaw 翻译成工程视角,就是一条清晰的流水线:
-
- Channel Adapter:把不同渠道的输入统一成标准消息,并提取附件。
-
- Gateway Server:会话协调器,决定这条消息应该进入哪个会话、排到哪个队列。
-
- Lane Queue:每个会话默认串行;确实低风险的任务才允许并行。
-
- Agent Runner:拼上下文、选模型、发起调用,驱动工具循环。
-
- Agentic Loop:模型提出 tool call → 执行 → 结果回填 → 下一轮,直到输出或触达上限。
-
- Response Path:把最终内容流式回写到渠道,同时把全过程写入可回放的转录(JSONL)。
这类架构的价值不在"酷",在于边界清楚:你一眼能看懂"问题卡在哪一步",也更容易把问题隔离。
再补一个很实用但经常被忽略的点:响应链路本身也应该被当成系统的一部分。
原帖里提到 LLM 调用是流式输出,最终响应通过渠道回到用户;同时会话会被持久化成 JSONL(每行一个 JSON,对应用户消息、工具调用、执行结果、模型响应等)。这意味着"看到的输出"只是表层,下面还有一条可回放的证据链。
默认串行,显式并行:lane queue 为什么这么关键
我见过太多 Agent 项目,最开始只是想"多开几个 async/await",结果半年后变成三件事:
- • 日志像毛线团,交织在一起看不懂。
- • 共享状态一多,竞态条件(race condition)开始像幽灵一样出现。
- • "偶现"占据你绝大多数调试时间。
OpenClaw 的克制在于:它把并发的选择权,从"开发者随手写的异步"收回到一个显式的系统约束里。
这个思路也和 Cognition 的 "Don't Build Multi-Agents" 博文不谋而合:简单的 async 设置会让你陷入日志交织、状态竞争的泥潭。
lane queue 的直觉
- • 每个会话有自己的"泳道"(lane)。
- • 泳道里默认 串行执行。
- • 只有你明确标注"低风险、可并行"的任务,才会进入并行泳道(例如某些定时任务)。
这会强迫你换一个心理模型:从"我该锁哪里"转到"哪些任务真的能安全并行"。
Lane 是对队列的一层抽象,把"串行"作为默认架构,而不是事后补丁。作为开发者,你正常写代码,队列帮你处理竞态条件。
让并发"站到台前"
工程上我建议你把并发决策做成三个层级:
- • 默认串行:先保证任何链路都能稳定复现。
- • 显式并行:只开放少数"无共享状态/幂等/可重试"的任务。
- • 隔离失败域:并行任务失败,不影响主会话;失败能在日志里单独定位。
你会发现,这套约束比"并发技巧"更值钱,因为它减少了你未来的 debug 成本。
图 3:lane queue 的并发策略
Agent Runner:把"提示词工程"变成"上下文装配线"
真正能跑起来的系统,往往把提示词当成装配线上的一环,而不是宗教。
在 OpenClaw 的描述里,Runner 做的事很具体:
- • Model Resolver:决定用哪个模型;Key 失效标记冷却并切换;主模型失败自动换备用。
- • System Prompt Builder:动态拼装系统提示词,把工具、技能、记忆整合进去。
- • Session History Loader:加载会话历史(来自
.jsonl转录)。 - • Context Window Guard:上下文快满时压缩(总结)或降级/停止,避免"撑爆以后才知道"。
这套拆分带来两个立刻可感知的收益:
- • 你能把"模型质量"和"系统质量…