最近半年写/用 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 翻译成工程视角，就是一条清晰的流水线：
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 为什么这么关键
我见过太多 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：上下文快满时压缩（总结）或降级/停止，避免"撑爆以后才知道"。
这套拆分带来两个立刻可感知的收益：
• 你能把"模型质量"和"系统质量"拆开看：模型波动时，系统依然可控。 • 你能做复盘：因为历史、工具调用、工具结果都是结构化记录，能回放、能对账。
顺着这条线，原帖还强调了 LLM 调用层的两个点：
• 流式输出：让"生成过程"可观察，也更利于把中间态回传给上层。 • 多厂商抽象：同一层对接不同模型提供方；如果模型支持，还可以请求"扩展思考"能力。
工程上这意味着：你不该把"换模型/换 Key/失败兜底"写散在业务逻辑里，而是收敛在 Runner 的职责边界里。
Agentic Loop：奇迹发生的地方，也是事故高发区
工具循环大家都懂：tool call → 执行 → 回填 → 下一轮，直到输出或触达轮次上限（例如 20 轮）。
但工程上真正需要盯住的是三件事：
• 终止条件：什么时候该停？停得是否可解释？ • 工具输出的格式：工具返回是"日志"，还是"可被模型消费的证据"？ • 回填策略：回填太多撑爆上下文，回填太少模型又失明。
Context Window Guard 的价值也在这里：把"上下文爆炸"做成显式组件，而不是靠经验拍脑袋。
你可以不追求每次都成功，但你不能接受失败时无从定位。
记忆：别神化，文件也能打
我很喜欢它对"记忆"的去神秘化处理：简单、可解释、可迁移。
它主要靠两条线：
1. JSONL 会话转录：每一行一个 JSON 对象，包含用户消息、工具调用、执行结果、模型响应。 2. Markdown 记忆文件：放在 MEMORY.md或memory/目录下。
这相当于把记忆拆成两类：
• "发生过什么"（转录，偏事实、偏审计） • "应该记住什么"（摘要与沉淀，偏经验、偏复用）
检索：向量 + 关键词的混合
很多系统只做向量检索，最后会踩一个坑：你以为找的是"精确概念"，结果召回一堆"语义相近但不对"的东西。
OpenClaw 的思路更稳一点：向量检索负责语义召回，关键词匹配负责精确命中。
原帖给了一个很直观的例子：你搜 "authentication bug"，系统既能命中写了 "auth issues" 这种同义表达（语义），也能命中精确短语（关键词）。这能明显降低"看起来相关但其实不对"的噪声。
实现上它用 SQLite：
• 向量搜索：SQLite（向量索引实现细节不展开，重点在"落地到同一个存储"）。 • 关键词搜索：SQLite FTS5。
嵌入模型（embedding provider）是可配置的。
同步：Smart Syncing + 文件监控
记忆文件更新也不需要一套"专用记忆 API"。更朴素的方式就够了：Agent 用"写文件工具"写入 memory/*.md，文件监控器检测到变化后触发同步与索引更新。
它还提到一个细节：新对话开始时，会有一个钩子把上一轮对话抓出来，写一份 Markdown 总结。你可以把它理解成"把经验沉淀变成默认动作"，而不是全靠用户手动整理。
这点我很认可：工具越底层，越不容易被你自己未来的"架构升级"搞死。
原帖作者也提到，这套记忆系统和 @CamelAIOrg 实现的工作流记忆非常相似：没有复杂的记忆合并，没有按周/月的记忆压缩。简单可解释，胜过复杂的意大利面。
代价：没有遗忘曲线
它的记忆会长期保存，旧记忆与新记忆权重接近，也就意味着"它不太会自然遗忘"。
这既是优势也是风险：
• 优势：可追溯、可解释，复盘方便。 • 风险：过期经验可能持续被召回；你需要显式的版本化、有效期或冲突解决策略。
如果你打算照抄这一套，我建议至少补两个机制：
• 给记忆加 updated_at与confidence的元信息（哪怕只是写在 Markdown 里）。• 定期把"已过期/已被推翻"的结论写成一条新记忆，覆盖旧结论，而不是悄悄删掉。
工具与"电脑操作"：强大，但别自欺欺人
OpenClaw 给 Agent 的能力很直白：你给它一台电脑，它就能用。
它的 exec 工具支持三种执行环境：
• 沙箱（Sandbox）：默认在容器里跑命令。 • 宿主机：直接在本机执行。 • 远程设备：在远程机器执行。
配套还有三类常见能力：
• 文件系统工具：读、写、编辑。 • 浏览器工具：基于 Playwright，并使用语义快照。 • 进程管理：启动后台任务、查看状态、终止进程。
这里我要强调一句很现实的话：只要你允许"宿主机执行"，你就等于把最终责任从系统转交给了用户本人。
所以后面那套安全护栏，才显得没那么"锦上添花"，而更像必需品。
安全：护栏不靠祈祷，靠 allowlist
很多人做工具调用安全，最后会变成一句话："请模型不要做危险操作"。
这在工程上等同于没有。
OpenClaw 的做法更像 Claude Code：维护一个 允许列表（allowlist），把"能跑什么命令"当成一个可审计的配置文件。
原帖里给了一个示例：配置会记录每个 agent 允许的命令模式，以及上次使用时间。大概长这样（示意）：
{
"agents": {
"main": {
"allowlist": [
{ "pattern": "/usr/bin/npm", "lastUsedAt": 1706644800 },
{ "pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900 }
]
}
}
}另外，一些"明显安全"的命令会被默认放行（比如 jq、grep、cut、sort、uniq、head、tail、tr、wc）。
同时，它还做了一个我很喜欢的判断：不仅拦命令本身，还拦 危险的 Shell 结构，比如：
• 重定向（ >）• 命令替换（ $(...)）• 子 Shell（ (...)）• 链式执行（ ||/&&）
原帖给了几个会被直接拒绝的例子：
# 这些在执行前就会被拒绝：
npm install $(cat /etc/passwd) # 命令替换
cat file > /etc/hosts # 重定向
rm -rf / || echo "failed" # 链式执行
(sudo rm -rf /) # 子 Shell为什么这很重要？
因为真正的攻击，往往会把危险行为藏在一段看起来无害的组合里，而不是明着写"直接跑 rm"。
你可以把这套机制理解成一句话：在用户允许的范围内，尽可能给 Agent 自主权。
你不需要在提示词里反复喊"别乱来"。
系统层面直接定义"你最多只能走到哪"，效果会更稳定。
浏览器：语义快照，比截图更像"工程选择"
OpenClaw 的浏览器工具不以截图为主，而是使用 语义快照（Semantic Snapshots）。
本质是把网页转成可访问性树（Accessibility Tree / ARIA）的结构化文本，让 Agent"读结构"而不是"看像素"。
Agent 看到的页面大概是这样：
- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
- heading "Welcome back"
- list
- listitem "Dashboard"
- listitem "Settings"它带来的优势非常现实：
• 体积：截图可能到 5MB 级别；语义快照往往不到 50KB。 • 成本：Token 开销通常只是图像方案的一小部分。 • 精度：从"点坐标"变成"选节点引用"，成功率更稳定。 • 速度：纯文本解析比 CV 处理快得多。
你可以把它当成一种工程化取舍：只要任务不是强视觉依赖（比如识别图表细节、读验证码、找颜色差异），语义快照往往更可靠。
浏览网页本质上不一定是视觉任务——这是语义快照能成立的前提。
我会怎么抄：10 个可以直接落地的改造点
如果你正在做 Agent 工程化，这里是我觉得"抄了就能立刻变稳"的 10 件事：
1. 默认串行先跑稳：先让一条链路稳定复现，再谈并行与性能。 2. 把并发变成系统决策：lane queue + 会话隔离；并行必须显式声明。 3. Runner 组件化：Model Resolver / Prompt Builder / History Loader / Context Guard 拆开，便于替换与观测。 4. 把工具调用当事件：每次 tool call 都写 JSONL（请求/参数/结果/耗时/错误码），能回放。 5. 工具输出做"证据化"：工具返回尽量结构化（表格/JSON 摘要），避免把噪声日志塞满上下文。 6. 记忆先文件化： MEMORY.md/memory/*.md配上updated_at、来源、置信度，比黑盒 DB 更可控。7. 检索别只押向量：向量召回 + 关键词精确命中；必要时加"必须命中词"的 hard filter。 8. 安全从 allowlist 开始：允许什么、拒绝什么，写成配置；危险 shell 结构直接拒绝。 9. 浏览器优先语义快照：能读结构就别看像素；把强视觉任务单独隔离（验证码/图表/颜色等）。 10. 失败要可解释：把"环境不满足/偶发失败/策略拦截"分开报错，别让用户只看到一句"失败了"。
收个尾：工程化 Agent 的"现实感"
我越来越觉得，Agent 真正的分水岭是：失败时你能不能解释清楚。
至于"能不能做"，反而没那么稀缺了。
提示词当然重要，模型当然重要。
但真正让系统可用的，是这些看似朴素的工程约束：队列、日志、文件、allowlist、可访问性树。
它们不性感，却很可靠。
