03 · Agent 的大脑是怎么工作的 · AI 编程官方教程中文版

——翔宇

要点速览

Agent 的核心不是「一问一答」，而是「推理-行动-观察」的循环——可能跑好几轮才给你回复
工具（Tools，底层能力）是手脚，技能（Skills，技能插件）是说明书——两层架构，缺一不可
工具有权限分组，exec 是万能的但也最危险
Hooks（钩子，内部事件回调）让你在 Agent 执行的关键节点插入自定义逻辑——八个钩子覆盖全生命周期
嵌入式架构让 Agent 跑在 Gateway（网关，系统核心进程）内部——快但有代价

1. 一个好问题

你跟 Agent 说：「帮我找一篇关于 AI 安全的论文，总结要点。」

停下来想一想——如果你是 Agent，你需要几步才能完成这件事？

试着列出来：

上网搜索「AI 安全论文」
看搜索结果列表
判断哪篇论文最相关
点进去读论文内容
提取关键要点
组织语言，写成总结
把总结回复给用户七步。而且这还是顺利的情况。如果第一次搜出来的论文不够好呢？你还得回到第 1 步换个关键词重新搜。如果论文太长读不完呢？你还得判断哪些章节最重要、只读那几段。

现在问题来了：如果 Agent 只是一个「收到问题→调 API→返回结果」的管道，它怎么完成这种需要多步骤、多判断的任务？

答案是——它不能。除非它有一个循环。

更进一步：这七步中有些步骤之间是有条件跳转的。第 3 步「判断哪篇最相关」——如果没有一篇相关呢？你得回到第 1 步换关键词。第 4 步「读论文内容」——如果论文被付费墙挡住了呢？你得跳过这篇、去读下一篇。

这不是一条直线，而是一张网。一个有分支、有回退、有判断的网。

🧠 底层逻辑

大多数人以为 Agent 是这样的：输入 → 处理 → 输出。一条直线。但 OpenClaw 的 Agent 是一个循环：输入 → 思考 → 行动 → 观察结果 → 再思考 → 再行动 → ……直到它认为任务完成了，才输出最终结果。

这个循环，就是 Agent 的「大脑」。

让我们一步步拆开它。

2. 大多数人的直觉——为什么是错的

错误直觉

「Agent 就是一个 API 包装器吧？我发消息，它调 Claude/GPT，把结果发回来。」

如果这个直觉是对的，那 Agent 和 ChatGPT 有什么区别？

这是一个值得认真回答的问题。

区别在于：ChatGPT 确实是一问一答的。你问它一个问题，它思考一次，回你一个答案。如果答案不对，你得自己追问。如果你想让它查个东西，你得自己去查了之后告诉它。它很聪明，但它只有脑子没有手脚，也没有自驱动的循环。

但 OpenClaw 的 Agent 会自己追问自己。

🎯 打个比方

ChatGPT 像一个只会接球的人——你扔一个球，他接住扔回来。OpenClaw 的 Agent 像一个会打全场的网球选手——你发一个球，他可能先跑位、调整站姿、观察风向，然后才挥拍。甚至打完一拍发现角度不好，他会自己调整下一拍的策略。

这个「自己调整」的能力，来自一个叫 ReAct 的范式——Reasoning（推理）+ Acting（行动）的组合。

我们来拆开看看它到底是怎么回事。

3. 从第一性原理拆解：ReAct 循环

ReAct 不是 OpenClaw 发明的——它是学术界提出的一种让 AI 自主完成复杂任务的框架。ReAct = Reasoning（推理）+ Acting（行动）。

它的核心思想很反直觉：AI 不应该先想好所有步骤再执行，而应该想一步、做一步、看结果、再想下一步。

你可能会问：为什么不先想好整个计划？

因为在真实世界里，你不可能在行动之前预见所有情况。搜索结果可能不是你预期的，网页可能打不开，论文内容可能跟标题不符。如果你先想好一个五步计划，第二步就失败了，整个计划就作废了。

🔑 关键点

ReAct 的哲学是：用行动验证推理，用观察修正下一步。 不是「计划→执行」，而是「推理→行动→观察→推理→行动→观察→……」的螺旋上升。

3.1 一个完整循环长什么样

回到刚才的例子——「帮我找一篇关于 AI 安全的论文，总结要点」。Agent 的大脑里发生了这些事：


第 1 轮
  推理：用户想要 AI 安全论文的总结。我先搜索一下。
  行动：调用 web_search 工具，搜索 "AI safety research paper 2025"
  观察：得到 10 条搜索结果

第 2 轮
  推理：第 3 条看起来最相关——一篇关于 LLM（大语言模型）对齐的论文。让我读一下。
  行动：调用 web_fetch 工具，抓取论文页面
  观察：拿到了论文全文，约 8000 字

第 3 轮
  推理：内容太长了，我需要提取要点并总结。论文主要讲了三个方面……
  行动：生成总结回复
  观察：（无——这是最后一步）

→ 最终回复发送给用户

三轮。每一轮都有推理、行动、观察。这就是 Agent Loop。

注意第 2 轮——Agent 做了一个判断：「第 3 条看起来最相关」。如果它判断错了呢？没关系。它会在第 3 轮发现内容不对，然后回到第 2 轮的逻辑——再去读另一篇。这就是循环的力量：错了可以修正。

再看一个更复杂的场景。如果第一次搜索结果全是新闻而不是论文呢？


第 1 轮
  推理：用户想要 AI 安全论文的总结。我先搜索一下。
  行动：调用 web_search，搜索 "AI safety research paper 2025"
  观察：得到 10 条结果，全是新闻报道，没有论文

第 2 轮
  推理：搜索结果不够学术。我换个关键词再搜。
  行动：调用 web_search，搜索 "AI alignment paper arxiv 2025"
  观察：这次有 3 篇 arXiv 论文

第 3 轮
  推理：第一篇 "Constitutional AI v2" 看起来最相关。我去读一下。
  行动：调用 web_fetch，抓取论文页面
  观察：拿到了论文摘要和关键章节

第 4 轮
  推理：内容足够了，我来总结……
  行动：生成总结回复

→ 最终回复发送给用户

四轮。Agent 自己发现了搜索结果不好，自己修正了搜索策略。这个修正不是你教它的——是它在循环中通过「观察」自己学会的。

📌 记住这点

不是所有请求都需要多轮。「你好」只需要一轮。「帮我写一段代码」通常也只需要一轮。但「帮我搜索一个问题、读几篇文章、综合总结」这种任务，可能需要五六轮甚至更多。Agent 自己决定需要几轮——不是你定义的，也不是预编程的。

3.2 六个阶段的全景图

每一轮循环，具体包含六个阶段：

🔑 关键点

阶段 3 和阶段 4 可能反复执行多次——模型推理后决定用工具，工具返回结果后，模型再推理、再用工具……直到模型认为「够了，可以回复了」。这就是为什么叫「循环」而不是「管道」。

3.3 最容易被忽略的阶段：上下文组装

六个阶段中，「组装上下文」看起来最不起眼，但它可能是最重要的。

因为 AI 模型只能基于它「看到」的信息来推理。如果上下文里没有包含某个 Skill 的指令，Agent 就不知道该怎么做某类任务。如果上下文里没有用户的偏好记忆，Agent 就不知道你喜欢什么格式。

上下文组装就是把所有相关信息拼在一起——系统提示词（SOUL.md、AGENTS.md）、对话历史、相关记忆、匹配的 Skill 指令——形成一个完整的「工作包」交给模型。

💬 说人话

上下文组装就像员工开始干活前先在桌上铺好所有材料——今天的任务单（用户消息）、操作手册（Skill）、之前的笔记（记忆）、公司规范（系统提示）。如果某份材料没铺上桌，员工就不知道有这回事。

上下文的深入理解会在第 5 篇《上下文——最贵的资源》中展开。这里你只需要知道：Agent 循环的质量上限，取决于上下文的质量。

3.4 谁来决定「够了」？

这是一个很微妙的问题。Agent 怎么知道该停下来了？

答案是：AI 模型自己决定。

当模型在推理阶段判断「我已经有足够的信息来回答用户的问题了」，它就不会再请求调用工具，而是直接生成最终回复。这个判断不是基于规则（比如「最多跑 5 轮」），而是基于模型自己的「感觉」——它觉得答案足够好了。

🧠 底层逻辑

这里有一个有趣的哲学问题：一个 AI 怎么知道自己「知道得够多了」？答案是——它不一定知道。有时候 Agent 会过早停下来（信息不够），有时候会过晚停下来（跑了太多轮）。这就是为什么超时机制和 Hooks 很重要——它们是人类给循环设的边界。

4. 验证理解：如果 Agent 只能做一轮

为了真正理解循环的必要性，我们做一个思想实验：如果 Agent 只能做一轮，会怎样？

退化成一轮的 Agent，本质上就是一个翻译器——把你的自然语言翻译成一次 API 调用，把结果翻译回自然语言。

你说「帮我找 AI 安全论文并总结」，它只能做一件事：搜索。然后把搜索结果原封不动扔给你。

你说「不对，我要的是论文内容的总结，不是搜索结果的列表」，它再做一件事：拿第一条搜索结果去总结。

一切需要你来驱动下一步。你变成了循环的一部分——你在替 Agent 做推理。

💬 说人话

一轮 Agent 就像一个只会执行但不会思考的实习生——你说「帮我搜论文」他就搜，你说「帮我总结」他就总结，但他永远不会自己把这两步连起来。你得一步一步告诉他。多轮 Agent 是一个会思考的老员工——你说「帮我搜论文并总结」，他自己就搞定了。

🧠 底层逻辑

循环不是一个「锦上添花」的功能——它是 Agent 和普通 Chatbot 的根本分界线。没有循环的 AI 是工具，有循环的 AI 是 Agent。

这个退化实验还揭示了一件事——为什么很多人用 ChatGPT 觉得「AI 不够聪明」。不是 AI 不够聪明，是它缺少循环。它一次性给你一个答案，如果答案不好，你得自己去驱动下一步。而有循环的 Agent 会自己去验证、修正、迭代——最终给你一个经过多轮打磨的结果。

4.1 用一个反问验证你的理解

在继续之前，先问你一个问题：

如果你想让一轮 Agent 也能完成「搜论文并总结」这个任务，有没有可能？

答案是——理论上可能，但需要你做大量前期工作。你可以自己先搜好论文、复制粘贴全文到对话里，然后让 Agent 总结。这样 Agent 只需要一轮就能完成。

但你注意到了吗？你做了循环本该做的事——搜索、筛选、获取内容。你把自己变成了循环的一部分。

这就是 Agent Loop 的本质价值：把你从循环中解放出来。 你只需要定义目标（「找论文并总结」），Agent 自己完成中间的所有步骤。

4.2 循环的三种退化模式

既然循环这么重要，我们不妨再深入一步——Agent 的循环可能退化成哪些不良模式？

📌 记住这点

如果你发现 Agent 的回复质量很低——不够深入、不够完整——先别怪模型笨。检查一下：它是不是只跑了一轮？如果是，问题可能出在 Skill 指令上——你没有告诉它「搜索之后要深入阅读」。循环的质量取决于 Agent 在每一轮的「推理」质量，而推理质量很大程度上取决于你给它的指令和上下文。

5. 工具系统：手脚和说明书

Agent 的大脑再聪明，如果没有手脚，也只能「想」不能「做」。

想象一个被锁在空房间里的天才——他能想出解决任何问题的方案，但他不能上网搜索，不能读文件，不能运行程序，不能发消息。他能做的只有「想」和「说」。

没有工具的 Agent 就是这个天才。

工具系统就是打开那扇门——让 Agent 从「能想」变成「能做」。但 OpenClaw 的工具系统不是一层，而是两层。这个两层设计非常重要，值得仔细理解。

5.1 第一层：Tools（工具）= 手脚

工具是最底层的能力单元。每个工具做一件具体的事。

💬 说人话

工具就是 Agent 能伸出的「手」。没有 exec 工具，Agent 不能跑命令；没有 web_search 工具，Agent 不能上网查东西。你给它什么工具，它就有什么能力。

5.2 第二层：Skills（技能）= 说明书

有了工具（手脚），Agent 知道自己「能做什么」。但它还不知道「怎么做」。

这就是 Skill 的作用——告诉 Agent 遇到某类任务时，应该怎么组合使用工具来完成。

🎯 打个比方

你有一把螺丝刀（工具）。但面对一台需要拆修的打印机，光有螺丝刀还不够——你需要一本维修手册（Skill），告诉你先拆哪个螺丝、后拆哪个螺丝、哪个零件要小心。Skill 就是 Agent 的维修手册。

5.3 Skill 的三个来源

Skill 可以从三个地方加载，优先级从低到高：

📌 记住这点

名称冲突时，工作区的赢。这意味着你可以写一个和内置 Skill 同名的工作区 Skill，用你自己的版本覆盖掉默认行为。这是有意设计的——给你最大的控制权。

5.4 Skill 的本质：一个目录 + 一个文件

Skill 听起来很高级，但它的实现非常朴素。

一个 Skill 就是一个文件夹，里面放一个 SKILL.md 文件。这个文件用自然语言告诉 Agent：「遇到这类任务，你应该怎么做。」

没有代码，没有编译，没有打包。写完即生效。

💬 说人话

你不需要会编程就能写 Skill。它本质上就是一份详细的工作指南——用中文或英文写给 Agent 看的。Agent 读了之后，自己判断什么时候该用，怎么用。

这也解释了为什么 Skill 和工具是分开的两层——工具是代码实现的确定性能力（搜索就是搜索，读文件就是读文件），而 Skill 是自然语言描述的灵活策略（可以随时修改、不用重启）。

5.5 两层架构为什么不可或缺

你可能会问：为什么不把工具和 Skill 合成一层？直接给 Agent 一堆「高级工具」不行吗？

不行。原因是灵活性和可定制性。

如果把 Skill 的逻辑硬编码到工具里，你就没法自定义了。比如「每日晨报」这个任务——它需要先搜索新闻、再总结、再格式化、再发送。如果这是一个工具，你没法改它的任何步骤。但如果它是一个 Skill，你可以改搜索源、改总结风格、改发送渠道——因为 Skill 只是一份说明书，底层用的还是通用工具。

我们用反事实推理来验证：

如果只有工具没有 Skill？

Agent 拥有所有底层能力，但不知道怎么组合。你说「帮我写一份晨报」，它可能搜索了但不知道该总结成什么格式。你得每次都告诉它「先搜新闻、再搜日历、然后用表格格式总结」。累不累？

如果只有 Skill 没有工具？

Agent 有一本详细的操作手册，但没有手脚。它知道应该先搜索再总结，但它搜不了——因为搜索能力不存在。

两层缺一不可——工具提供能力，Skill 提供策略。

5.6 Skill 在循环中的角色

你可能会好奇：Skill 在 Agent Loop 里具体在哪个环节发挥作用？

答案是「上下文组装」阶段。当 Agent 收到一条消息，OpenClaw 会匹配这条消息可能触发的 Skill，把相关 Skill 的指令加入上下文。这样模型在推理时就能看到这些指令，并据此决定下一步该做什么。

🎯 打个比方

你走进办公室准备开始工作（上下文组装阶段）。桌上放着一堆任务单，其中一张跟你今天要做的事相关（Skill 匹配）。你把那张任务单翻开放在手边（加入上下文），然后按照上面的步骤开始干活（模型推理+工具执行）。任务单不直接帮你干活——它告诉你怎么干。

所以 Skill 不是一个独立的执行引擎——它是上下文的一部分。它通过影响模型的推理过程来影响 Agent 的行为。这也解释了为什么有时候 Skill 指令写得不够清楚，Agent 就不会按你期望的方式执行——因为模型在推理时「没看懂」那份说明书。

⚡ 速记

工具 = 能力（能做什么），Skill = 策略（怎么做）。能力是固定的，策略是灵活的。一个给 Agent 手脚，一个给 Agent 方法论。

6. 工具权限：万能钥匙的安全悖论

你给 Agent 的工具越多，它越强大。但强大和安全往往是一对矛盾。

这引出一个尖锐的问题：

如果有人给你一把万能钥匙，你放心吗？

在 OpenClaw 的语境里，这个问题变成：你愿意让 Agent 在你的电脑上执行任何命令吗？读取任何文件？代你发送任何消息？

大多数人的直觉反应是「当然不」。但如果你因此限制了 Agent 的能力，它就做不了你期望它做的事。这就是安全悖论——限制太多不好用，限制太少不安全。

OpenClaw 用工具组（Group）来优雅地解决这个问题。

6.1 八大工具组

OpenClaw 把内置工具按功能分成八个组（Group），方便批量管理权限：

6.2 exec：最强也最危险

所有工具里，exec 是最特殊的。

它让 Agent 能在你的机器上执行任何命令行指令——安装软件、删除文件、修改系统配置、甚至连接远程服务器。它本质上就是一把万能钥匙。

🎯 打个比方

给 Agent 开放 exec 工具，就像给一个新员工配了办公室的所有钥匙——仓库、机房、保险箱都能进。如果这个员工靠谱，效率极高。如果不靠谱……你懂的。

🧠 底层逻辑

OpenClaw 不是不知道 exec 危险——它是刻意这样设计的。因为 Agent 跑在你自己的机器上（不是云端），本质上和你自己在终端里敲命令没区别。它选择信任你对自己机器的控制权，而不是替你做安全决策。

这里有一个容易被忽略的细节：exec 工具有一个 timeout 参数，默认 1800 秒（30 分钟）。如果命令执行超时，会被强制终止。还有一个 background: true 选项，让长时间任务在后台跑——Agent 不用傻等，可以先回复你，任务完成后再告诉你结果。

🔍 深入一步

你可能会想：「如果第三方 Skill 恶意调用 exec 删我文件怎么办？」这是一个真实的安全问题。OpenClaw 社区已经发现过恶意 Skill 利用 exec 工具搞破坏的案例。应对方式有两种：用 tools.deny 对特定 Agent 禁用 exec，或者用 before_tool_call Hook 审查每一条 exec 命令——后面第 9 节会详细讲。

6.3 权限控制的两种方式

如果你不想给 Agent 万能钥匙，有两种方式限制：

方式一：黑名单/白名单

用 tools.deny（黑名单）和 tools.allow（白名单）控制。deny 优先——如果一个工具同时在 deny 和 allow 里，它是被禁止的。

方式二：预设配置文件

OpenClaw 提供四种开箱即用的权限预设：

💡 划重点

如果你在本地自己用，full 没问题——反正是你自己的机器。如果你在服务器上跑、或者给别人用，建议从 minimal 开始，只开你确实需要的工具。安全原则：最小权限够用就行。

6.4 权限和循环的关系

权限配置直接影响 Agent 循环的行为。

一个被限制了 web_search 工具的 Agent，在收到「帮我搜一下最新的 AI 新闻」时，会怎么做？它在推理阶段会发现自己没有搜索能力，然后只能用自己已有的知识来回答——或者直接告诉你「我没有联网搜索的权限」。

🧠 底层逻辑

权限不只是安全机制——它也是能力边界的定义。你通过权限配置，本质上在告诉 Agent：「你的手能伸多远。」工具越多，Agent 的循环可以探索的路径越多；工具越少，循环的可能性就越有限。这是一个刻意的设计：你可以为不同场景的 Agent 配置不同的工具集，让每个 Agent 只做它应该做的事。

7. 超时机制：Agent 不能干到地老天荒

前面讲了 Agent 会自己决定「跑几轮」。但这带来一个问题——如果 Agent 判断失误，觉得自己「还没完成」，一直跑下去呢？

这不是假设。真实场景中，Agent 可能陷入这些死循环：

搜索结果不满意 → 换关键词 → 还是不满意 → 再换 → 无限循环
调用一个已经挂掉的 API → 超时 → 重试 → 又超时 → 无限重试
读一个文件、修改、发现改错了、撤回、重新改 → 改来改去所以 OpenClaw 必须有一个兜底机制——超时。它是循环的安全阀。

💬 说人话

给员工 10 分钟处理一个请求。10 分钟还没搞定，经理会过来说「行了，先停下来，告诉我进展到哪了」。大部分请求 10-30 秒就完成了——600 秒是防止极端情况的安全网。

你可能会问：10 分钟够吗？对于 99% 的任务绰绰有余。搜索通常 2-5 秒，文件读写几毫秒，模型推理 5-15 秒。需要更长时间的任务（比如批量处理 100 个文件），Agent 会用后台执行——exec 工具有 background: true 选项，任务在后台跑，不占 Agent 的运行时间。

🔑 关键点

超时不是「任务失败」——它是一个保护机制。超时后 Agent 会保存当前状态，你可以继续追问「刚才那个任务做到哪了」，Agent 可以从记忆中恢复进度。

7.1 为什么是 600 秒而不是 60 秒

你可能好奇：为什么默认给 10 分钟这么长？大部分请求不是 10-30 秒就完成了吗？

因为有些任务确实需要时间。比如：

Agent 调用 browser 工具打开一个网页，网页加载慢——30 秒
Agent 连续搜索 3 次、读 3 篇文章——每次搜索+阅读 30 秒，总共 90 秒
Agent 生成一篇长文——模型推理 20 秒
Agent 调用 exec 跑一个数据处理脚本——脚本跑 120 秒把这些加起来，一个复杂任务确实可能需要 3-5 分钟。600 秒给了足够的余量，同时又不会让一个失控的 Agent 跑几个小时。

💬 说人话

600 秒就像高速公路的限速 120——大部分人开 80-100，但限速不能设 80，否则偶尔需要超车的人就被限制了。10 分钟是一个「大部分时候用不满，但偶尔真的需要」的安全线。

8. NO_REPLY（静默标记，不发送回复）：Agent 有时候应该闭嘴

这是一个很少被提到但设计极其精妙的功能。

想想这个场景：你设了一个 Cron（定时任务），让 Agent 每小时检查一次服务器状态。90% 的时间，服务器都是正常的。

如果 Agent 每小时给你发一条「服务器正常」——你烦不烦？

🎯 打个比方

你让保安每小时巡逻一次。如果一切正常，你希望保安每小时跑来跟你说「报告老板，一切正常」吗？当然不。你只希望他在发现异常时才来找你。

这就是 NO_REPLY 的设计意图。

当 Agent 的输出内容是 NO_REPLY 这个特殊标记时，OpenClaw 不会发送任何消息给用户。Agent 完成了任务，但选择了「闭嘴」。

怎么触发 NO_REPLY？你不需要手动设置。通常在 Skill 或 AGENTS.md 里告诉 Agent：「如果巡检结果一切正常，输出 NO_REPLY 即可。」Agent 在推理阶段判断「没什么可报告的」，就会输出这个标记。

你可能会想：为什么不用一个布尔配置项（比如 silentOnSuccess: true）来控制是否发送回复？为什么要让 Agent 自己决定？

因为「是否有值得报告的事」本身就是一个需要判断力的问题。同样是定时巡检，如果 CPU 使用率从 30% 涨到了 80%——虽然没有超过报警线（90%），但趋势值得关注。这种情况下，Agent 应该报告还是沉默？

用布尔配置项做不到这种细粒度判断。但 Agent 可以——它在推理阶段分析巡检结果，自己决定是否有值得报告的异常。这就是让 Agent 自己输出 NO_REPLY 而不是用配置项控制的原因。

8.1 NO_REPLY 的典型场景

🧠 底层逻辑

NO_REPLY 体现了一个设计原则：Agent 应该像一个得体的助手——需要报告时报告，不需要时保持沉默。 沉默本身也是一种回复——它意味着「一切正常，不用担心」。

8.2 不只是 NO_REPLY：回复整形的全貌

NO_REPLY 是回复整形（Reply Shaping）机制的一部分。OpenClaw 在发送最终回复之前，还会做几件事：

💬 说人话

回复整形就是「发出去之前再整理一下」——去掉重复的、补上缺失的、该沉默时闭嘴。你不需要手动干预这些，OpenClaw 自动处理。

9. Hooks：在关键节点「推一下」

到现在为止，Agent 的循环看起来是一个全自动的系统——消息进来，循环跑，回复出去。你作为用户，只负责发消息和看结果。

但如果你想在这个自动化流程中插入一些「你的意志」呢？

比如：

每次 Agent 要调用 exec 工具之前，先记录一下要执行什么命令——用于安全审计
每次 Agent 发送回复之前，先检查有没有敏感信息——防止泄露你的 API Key
每次会话开始时，自动加载特定的配置文件——不同时间段用不同的人设
每次会话结束时，自动把重要信息存进记忆——防止遗忘这就是 Hooks（钩子）系统的用途。它让你在不修改 Agent 核心逻辑的情况下，在关键节点注入自定义行为。

9.1 八个钩子，覆盖全生命周期

🎯 打个比方

钩子就像生产线上的质检点。产品（消息/工具调用）从生产线上走过，每经过一个质检点，你可以拦下来检查一下、调整一下、甚至退回去。你可以在任何一个质检点放一个检查员，也可以一个都不放——生产线照样跑。

9.2 为什么直觉不够

错误直觉

「我直接在 AGENTS.md 里写规则就行了，比如『不要执行 rm -rf 命令』。为什么还需要 Hooks？」

因为 AGENTS.md 里的规则是「建议」——Agent 可能遵守，也可能忘记。但 Hook 是「强制」——它在代码层面拦截，Agent 没有选择权。

💬 说人话

在 AGENTS.md 里写「不要删重要文件」，就像跟员工口头说「注意安全」——他可能记住也可能忘记。用 before_tool_call Hook 拦截所有包含 rm -rf 的命令，就像在危险区域装了一扇只有经理能打开的门——不管员工记没记住，门都关着。

🔍 深入一步

Hooks 的执行是同步的——在 Hook 完成之前，Agent 的循环会暂停等待。这意味着你可以在 Hook 里做耗时操作（比如调用外部审批 API），但也要注意不要让 Hook 太慢——否则 Agent 的响应时间会被拖长。

9.3 一个真实场景：用 Hook 做安全审计

假设你让 Agent 管理你的服务器。你信任它的大部分操作，但你有一个底线：不允许 Agent 执行任何删除命令（rm、del、drop 等）。

你可以在 AGENTS.md 里写：「禁止执行删除命令。」但你不放心——万一 Agent 在某次推理中「忘记」了这条规则呢？

这时候 before_tool_call Hook 就派上用场了。你可以配置一个 Hook：每次 Agent 要调用 exec 工具时，先检查命令里有没有 rm、del、drop 这些关键词。有？直接拦截，不执行。同时把这次拦截记录到日志文件，方便你回顾。

📌 记住这点

AGENTS.md 里的规则是「软约束」——依赖 AI 的遵从性。Hook 是「硬约束」——在代码层面拦截，不可绕过。两者配合使用效果最好：AGENTS.md 告诉 Agent「不要这样做」（减少触发），Hook 在万一触发时兜底拦截。

9.4 Hook 和 Agent Loop 的关系

把 Hook 放回整个循环来看，它们是嵌入在循环的各个阶段之间的检查点：


消息到达
  ↓ [message_received Hook]
Agent 开始
  ↓ [before_agent_start Hook]
推理 → 决定用工具
  ↓ [before_tool_call Hook]
执行工具
  ↓ [after_tool_call Hook]
（可能再推理、再用工具……）
生成回复
  ↓ [message_sending Hook]
发送回复
Agent 结束
  ↓ [agent_end Hook]

每个箭头处都可以插入一个 Hook。你可以只用其中一两个，也可以全部用上。大部分用户只需要 before_tool_call（安全审查）和 session_end（保存记忆）两个就够了。

9.5 没有 Hook 会怎样

没有 Hook，Agent 照样跑得很好——Hook 是可选的增强，不是必需的组件。

但有了 Hook，你就从一个「只能看结果」的用户，变成了一个「能干预过程」的管理者。这个区别在简单场景下感受不到，但在你让 Agent 管理服务器、代你发消息、处理敏感数据时，就变得至关重要了。

💬 说人话

Hook 就像装了监控摄像头的工厂——不装也能生产，但装了之后出了问题能回看、能预防、能实时拦截。你的 Agent 越自动化、做的事越重要，Hook 的价值就越大。

10. 嵌入式架构：快的代价

到这里，我们已经理解了 Agent 大脑的工作原理——循环、工具、权限、超时、沉默、钩子。但有一个底层问题一直没回答：

Agent 的循环到底跑在哪里？它是一个独立的程序吗？

答案可能让你意外——OpenClaw 的 Agent 不是独立进程。它跑在 Gateway（网关）进程的内部。这个设计选择影响着你使用 OpenClaw 的方方面面。

10.1 什么意思

传统的做法是：Gateway 是一个程序，Agent 是另一个程序，两者通过网络通信。就像公司的前台和员工在不同的楼层，靠电话沟通。

OpenClaw 的做法是：Gateway 和 Agent 在同一个进程里。就像前台和员工坐在同一张桌子旁边，喊一声就能沟通。不需要序列化消息、不需要网络传输、不需要等待响应——一个函数调用就完成了。

10.2 好处：速度和简单

💬 说人话

嵌入式就是「全员坐在一间办公室里」。沟通成本极低，协作效率极高，部署只需要一台机器。

10.3 代价：所有鸡蛋在一个篮子里

🎯 打个比方

10 个员工在同一间办公室里，协作效率很高。但办公室停电了？所有人停工。一个人的电脑着火了？烟雾弥漫整个办公室。这就是嵌入式架构的代价。

10.4 这个取舍值得吗

对于大多数个人用户和小团队——值得。原因很简单：

你通常只跑 1-3 个 Agent——单点故障的影响有限
你的机器内存够用——一个 Agent 的内存占用通常在几十 MB
简单就是力量——一条命令启动，不用操心服务编排如果你是企业用户、需要高可用——可以跑多个 Gateway 实例做冗余。但那是另一个话题了。

🔑 关键点

架构选择没有绝对的对错。嵌入式用简单换取了速度和易用性，放弃了隔离性和可扩展性。OpenClaw 选择了适合个人用户和小团队的那一端。

10.5 对比：如果是微服务架构会怎样

为了加深理解，我们想象一下如果 OpenClaw 不用嵌入式、而是用微服务架构会怎样：

💬 说人话

微服务就像每个员工在独立办公室——隔音好、互不影响，但喊一声对方听不到，得发邮件。嵌入式就像开放工位——吵但快，效率高但停电全灭。对个人用户来说，开放工位的效率优势远大于隔音劣势。

📌 记住这点

理解嵌入式架构有一个实际意义：如果你的 Gateway 崩了，所有 Agent 都会断线。这时候不要慌——重启 Gateway 就行。你的记忆文件（memory/）和配置文件都在磁盘上，不会丢失。Agent 会在重启后自动加载记忆，恢复到之前的状态（虽然当前会话的上下文会丢失）。

11. Lobster 引擎：当 Agent 太「聪明」了

前面讲的 Agent Loop 有一个特点——每一轮推理，AI 模型自己决定下一步做什么。这在大多数场景下是好事，但在某些场景下是坏事。

什么时候是坏事？当你需要确定性的时候。

🎯 打个比方

你让一个聪明人去寄快递——「帮我把这个包裹寄到北京」。聪明人可能会：先对比几家快递公司价格、选一家最便宜的、然后发现那家今天不营业、再换一家……最终可能花了一个小时。但你其实只需要他走到楼下顺丰、扫码下单、放柜子里——三步搞定。

Agent Loop 就是那个「聪明人」——它会自己判断、自己决策。这在大多数场景下是优势，但在需要精确可重复的场景下反而是劣势。

因为 AI 的判断有不确定性——同样的输入，跑两次可能走不同的路径。大多数时候结果差不多，但偶尔会出差错。如果这个任务要求每次都一模一样，AI 的这种「创造性」就变成了 Bug。

这就是为什么你需要它严格按步骤执行。

这就是 Lobster 引擎存在的原因。

💡 划重点

大部分场景用 Agent Loop + Skill 就够了。只有当你发现 Agent 反复在某个步骤犯同样的错——比如每次翻译都跳过格式化步骤——才考虑把那个流程改成 Lobster 管道。让确定性替代判断力。

🧠 底层逻辑

Lobster 不是 Agent Loop 的替代品，而是补充。Agent 负责「需要创造力的事」，Lobster 负责「需要精确的事」。两者可以协作——Agent 在循环中调用 Lobster 管道来完成某个子任务，自己继续做需要判断力的部分。

11.1 什么时候该用 Lobster

一个简单的判断标准：

💬 说人话

如果你发现自己在 Skill 里写了「必须先做 A、再做 B、再做 C、不要跳过任何步骤」这样的指令，但 Agent 还是时不时跳过某一步——那就是 Lobster 出场的时候了。把「ABCABC永远不变」的流程交给 Lobster，把需要灵活判断的部分留给 Agent。

这一篇不会深入讲 Lobster 的具体用法——那是翔宇版第 7 篇的内容。这里你只需要知道它存在、它解决什么问题、什么时候该考虑它。

11.2 Lobster 和 Agent Loop 协作的例子

想象一个翻译工作流：

从 RSS 订阅源抓取最新的 5 篇英文文章 → 需要判断：哪些文章值得翻译？（Agent Loop）
翻译选中的文章 → 不需要判断：按固定流程翻译（Lobster 管道：原文→粗翻→校对→格式化）
把翻译好的文章发布到公众号 → 不需要判断：按固定步骤发布（Lobster 管道：上传→排版→发布） Agent 负责第 1 步——判断哪些文章值得翻译。这需要理解文章内容、评估相关性、做决策。这是 AI 擅长的。

Lobster 负责第 2、3 步——按固定流程执行。每次都一样，不需要发挥，需要的是精确和可重复。

⚡ 速记

Agent Loop 做决策，Lobster 做执行。一个负责「想」，一个负责「干」。两者协作，既灵活又精确。

12. 设计权衡：为什么这样设计

在结束之前，我们退后一步，看看 Agent 大脑的整体设计中有哪些关键的取舍。理解取舍，比理解具体实现更重要——因为取舍反映的是设计者的价值观。

🧠 底层逻辑

所有这些选择都指向同一个方向：为个人用户和小团队优化。 OpenClaw 不是为了服务百万用户的企业级平台，而是为了让一个人或一个小团队拥有一个真正强大、真正自主的 AI 助手。在这个定位下，简单 > 复杂，能力 > 安全限制，速度 > 隔离。

理解了设计权衡，你就能理解 OpenClaw 社区里很多争论的本质——「为什么不加一个权限确认弹窗？」「为什么不把 Agent 做成独立进程？」这些不是没想到，而是刻意选择不做。每个设计决策都是在两个合理的选项之间做取舍，没有完美方案。

📌 记住这点

当你对 OpenClaw 的某个设计感到困惑时——比如「为什么 exec 默认开放这么危险」——先问自己：如果不这样设计，会失去什么？通常答案是「方便性」或「能力」。理解了取舍，困惑就消失了。

13. 把所有东西串起来

我们从一个好问题开始——「Agent 是怎么思考的？」——到现在已经拆解了整个大脑的工作原理。

先用一个完整的流程图把所有模块串起来：


用户发消息
  ↓ [message_received Hook]
Gateway 接收 → 路由到 Agent
  ↓ [session_start Hook（新会话时）]
  ↓ [before_agent_start Hook]
Agent Loop 启动
  │
  ├→ 组装上下文（SOUL.md + 对话历史 + 记忆 + Skill 指令）
  ├→ 模型推理（Claude/GPT 决定下一步）
  │     │
  │     ├→ 决定用工具
  │     │     ↓ [before_tool_call Hook]
  │     │   执行工具（exec/read/write/web_search/...）
  │     │     ↓ [after_tool_call Hook]
  │     │   拿到结果 → 回到「模型推理」（循环）
  │     │
  │     └→ 决定直接回复
  │           ↓
  │         生成回复文本
  │           ↓ 回复整形（去重 / NO_REPLY / 错误回退）
  │           ↓ [message_sending Hook]
  │         发送给用户
  │
  ↓ [agent_end Hook]
持久化（对话记录 + 记忆写入）
  ↓ [session_end Hook（会话结束时）]

超时守卫：全程 ≤600 秒

这个流程图里有几个关键细节值得注意：

循环发生在模型推理和工具执行之间——这是整个系统最核心的部分。模型推理后如果决定用工具，就执行工具、拿回结果、再推理。如果决定不用工具，就直接生成回复。
Hook 散布在各个关键节点——它们不改变循环的逻辑，只是在关键时刻让你「看一眼」或「推一下」。
回复整形在发送前发生——这是你最后一道防线，可以在 message_sending Hook 里拦截不合适的回复。
超时守卫覆盖全程——不管循环跑到哪一步，600 秒一到就强制中断。再用一张表把所有模块对应起来：

⚡ 速记

Agent 的大脑 = ReAct 循环（推理+行动）+ 工具系统（手脚+说明书）+ 安全机制（权限+超时+钩子）+ 运行架构（嵌入式）。

一句话检验

如果你能用一句话回答以下问题，你就真正理解了 Agent 的大脑：

Agent 和 ChatGPT 的根本区别？ → Agent 有循环（自己推理→行动→观察→再推理），ChatGPT 只有一轮问答
ReAct 的核心思想？ → 想一步做一步，用行动验证推理，用观察修正下一步
Agent Loop 是什么？ → 推理-行动-观察的循环，可能跑多轮才回复，不是一问一答
Tools 和 Skills 的区别？ → Tools 是手脚（能做什么），Skills 是说明书（怎么做）
Skill 优先级？ → 工作区 > 托管 > 内置，同名时工作区赢
exec 为什么危险？ → 它能执行任何命令——等于给了 Agent 你电脑的最高权限
NO_REPLY 有什么用？ → 让 Agent 在没什么可报告时保持沉默，不打扰你
Hook 和 AGENTS.md 规则的区别？ → AGENTS.md 是软约束（Agent 可能忘记），Hook 是硬约束（代码层面拦截）
嵌入式架构的代价？ → Gateway 挂了所有 Agent 都挂——所有鸡蛋在一个篮子里
什么时候用 Lobster 而不是 Skill？ → 不需要判断力、只需要按步骤精确执行的确定性任务

CC 提示词

理解了 Agent 大脑的工作原理，现在用 Claude Code 来观察你的 Agent 是怎么「思考」的。

🚀 对 Claude Code 说 帮我分析 OpenClaw Agent 的工具和技能配置： - 检查 /你的路径/.openclaw/openclaw.json 中的 tools 配置，告诉我当前开放了哪些工具组、禁用了哪些

列出所有已加载的 Skills（分别检查内置、托管 ~/.openclaw/skills/、工作区 skills/ 三个位置）

检查是否有同名 Skill 冲突——如果有，告诉我哪个优先级更高的会覆盖低优先级的

检查 agents.defaults.timeoutSeconds 的值，评估是否需要调整

综合评估：当前的工具权限配置是否合理？有没有不必要的高危工具开放着？

🚀 对 Claude Code 说 帮我检查 OpenClaw 的 Hooks 配置： - 读取 /你的路径/.openclaw/openclaw.json 中的 hooks 配置部分

列出当前已配置的所有 Hooks，按生命周期阶段排列

如果没有配置任何 Hook，帮我创建一个 before_tool_call 的示例 Hook：当 Agent 要调用 exec 工具时，把要执行的命令记录到 /你的路径/.openclaw/workspace/memory/ 下的今日日志文件

验证 Hook 配置是否正确加载

🚀 对 Claude Code 说 帮我观察 OpenClaw Agent 的循环过程： - 找到最近一次 Agent 会话的日志文件（通常在 ~/.openclaw/agents/ 目录下的 sessions 文件夹里）

分析这次会话中 Agent 跑了几轮循环——每次模型推理和工具调用算一轮

列出每一轮的：推理内容摘要、调用了什么工具、工具返回了什么

判断 Agent 的循环效率：有没有不必要的重复操作？有没有可以优化的地方？

统计这次会话的总耗时，以及每一轮的耗时分布

回顾：这篇文章的思路

我们从一个简单的问题出发——「Agent 是怎么思考的」——然后用费曼的方法一层层拆解：

先暴露直觉（Agent 就是 API 包装器）→ 证明直觉是错的（一问一答做不了复杂任务）
引入第一性原理（ReAct 循环：推理+行动+观察）→ 展开六个阶段的全景图
用退化实验验证（去掉循环会怎样？——变成需要人驱动的翻译器）
拆解工具系统（手脚+说明书的两层架构）→ 权限安全悖论 → exec 的危险与必要
讲清安全机制（超时兜底 + NO_REPLY 静默设计 + Hooks 硬约束）
揭示运行架构（嵌入式的快与代价）→ Lobster 引擎对确定性的补充
总结设计权衡（为什么每个看似「不合理」的设计都有其合理性）每个细节都回答了「为什么」而不只是「是什么」。

如果你读完之后再看到「Agent」这个词，脑子里浮现的不再是一个黑盒，而是一个有循环、有手脚、有安全边界、有运行架构的完整系统——那这篇文章就达到目的了。

下一篇——《记忆——AI 怎么记住你》——会解答循环中一个至关重要的问题：Agent 跑完一轮又一轮，积累了那么多信息，这些信息是怎么被保存下来、在下次对话时被找回来的？

03 · Agent 的大脑是怎么工作的

On this page