03 · Agent 的大腦是怎麼工作的

前兩篇已經講清楚兩件事：OpenClaw 不是單純聊天視窗，一條訊息也不是直接丟給模型就結束。本篇繼續往裡看一層：真正讓 Agent 能做事的不是某個模型 API，而是一套執行時迴圈。

一句話先記住：

模型負責判斷下一步，OpenClaw 負責把工作空間、會話、工具、技能、許可權、事件流和最終回覆串起來。

1. 先把 Agent 看成執行中的工作單元

OpenClaw 官方把 Agent runtime 描述成一個嵌入式執行時：每個 Gateway 裡執行一個 Agent 程序，它擁有自己的 workspace、bootstrap files 和 session store。

這和“呼叫一次大模型介面”不是同一個層級。

flowchart LR
  Gateway[Gateway]
  Runtime[Embedded Agent Runtime]
  Workspace[Workspace]
  Session[Session Store]
  Tools[Built-in Tools]
  Skills[Skills Snapshot]

  Gateway --> Runtime
  Runtime --> Workspace
  Runtime --> Session
  Runtime --> Tools
  Runtime --> Skills

幾個關鍵點：

• Workspace：agents.defaults.workspace 是工具和上下文的工作目錄，可以理解成 Agent 的辦公桌。
• Bootstrap files：AGENTS.md、SOUL.md、TOOLS.md 等會被注入上下文，是 Agent 的長期工作說明。
• Session store：會話轉錄存為 JSONL，是 Agent 的本輪工作記錄。
• Built-in tools：read、exec、edit、write 等受 tool policy 控制，是 Agent 的手腳。
• Skills：SKILL.md 資料夾會進入提示詞和技能快照，是 Agent 的操作手冊。

這裡最容易誤解的是 TOOLS.md：它不是授權開關。官方說得很明確，核心工具是否存在由 tool policy 決定，TOOLS.md 只是“希望工具怎麼用”的指導。

2. Agent loop 是一次真實執行

官方對 Agent loop 的定義很直接：

intake → context assembly → model inference → tool execution → streaming replies → persistence

翻譯成中文，就是：

sequenceDiagram
  participant U as User
  participant G as Gateway
  participant R as Agent runtime
  participant M as Model
  participant T as Tools
  participant S as Session

  U->>G: message
  G->>R: agent run
  R->>S: load session and context
  R->>M: model inference
  M-->>R: assistant text or tool call
  R->>T: execute tool if needed
  T-->>R: tool result
  R->>M: continue with observation
  R-->>G: assistant/tool/lifecycle stream
  G-->>U: final or streamed reply
  R->>S: persist transcript

這就是 Agent 的大腦迴圈。

它不是“先規劃所有步驟，再線性執行”，而是：

1. 先把當前訊息、會話、workspace 說明和技能裝進上下文。
2. 讓模型判斷下一步是回答、呼叫工具，還是繼續思考。
3. 如果呼叫工具，OpenClaw 執行工具並把結果作為 observation 交回模型。
4. 模型基於觀察結果繼續生成下一步。
5. 直到迴圈結束，再產出可見回覆並寫入會話。

如果你讓 Agent “檢查專案測試為什麼失敗”，一次真實 loop 可能長這樣：

flowchart TD
  A[使用者: 檢查測試失敗] --> B[組裝上下文]
  B --> C[模型判斷需要讀檔案]
  C --> D[read package config]
  D --> E[模型判斷需要執行測試]
  E --> F[exec test command]
  F --> G[讀取失敗日誌]
  G --> H[模型定位失敗原因]
  H --> I[edit or apply_patch]
  I --> J[再次執行測試]
  J --> K[最終回覆]

Agent 看起來像在“自主工作”，本質上是模型決策和 OpenClaw 執行層反覆交替。

3. OpenClaw 在 loop 裡做了哪些系統工作

官方 agent RPC 會先驗證引數、解析 session、持久化 session metadata，然後立刻返回 { runId, acceptedAt }。真正的 Agent 工作隨後進入 agentCommand 和嵌入式 runtime。

從學習角度，不需要先記函式名，但要理解這幾層職責：

OpenClaw 的關鍵價值在這裡：它不是隻把訊息轉發給模型，而是在模型外面維護會話一致性、工具執行、許可權控制、流式事件和最終回覆。

4. 序列化保證同一個會話不打架

官方文件強調：OpenClaw 的 loop 是 single, serialized run per session。同一個 session key 下的執行會排隊，必要時還會經過全域性佇列。

這解決的是一個現實問題：Agent 會讀寫 session transcript，也可能呼叫 exec、write、edit 等工具。如果同一個會話裡兩個 run 同時改狀態，很容易出現：

• 兩次回覆順序錯亂。
• 工具結果寫進錯誤的輪次。
• session history 被併發覆蓋。
• 使用者後來發的訊息被過早或過晚注入。

所以 OpenClaw 把 Agent loop 當成“一個會話的一次事務性執行”來處理。

flowchart LR
  M1[message A] --> L[session lane]
  M2[message B] --> L
  M3[message C] --> L
  L --> R1[run A]
  R1 --> R2[run B]
  R2 --> R3[run C]

這也是為什麼第二篇講訊息佇列時會提到 collect、steer、followup：這些模式最終都要喂進 session lane，不能繞過會話一致性。

5. Context 決定大腦看見什麼

模型不是憑空推理。它每一步能做什麼，取決於本輪 prompt 裡有什麼。

OpenClaw 在 prompt assembly 階段會組合：

• OpenClaw base prompt。
• skills prompt。
• bootstrap context。
• per-run overrides。
• session messages。
• 模型限制與 compaction reserve tokens。

這解釋了一個常見現象：同樣一個模型，在不同 OpenClaw workspace 裡表現會完全不同。因為它看到的 AGENTS.md、SOUL.md、TOOLS.md、skills 和歷史上下文不同。

可以把大腦分成兩層：模型能力負責語言理解、推理、工具呼叫判斷，主要透過換 model 或 provider 改；上下文工程負責角色、規則、工具習慣、專案知識，主要透過 workspace 檔案、skills、hooks、memory 改。

下一篇會專門講記憶系統，這裡先記住：OpenClaw Agent 的“聰明”不是隻來自模型，也來自上下文裝配。

6. Tools 是 Agent 的可執行能力

工具讓 Agent 從“會說”變成“會做”。

以 exec 為例，官方定義是：在 workspace 中執行 shell commands，支援前臺和後臺執行；如果 process 可用，還可以管理後臺程序。exec 有幾個關鍵引數：

OpenClaw 還會把工具事件作為 tool stream 發出。也就是說，使用者或 UI 不只看到最終答案，還可以看到工具開始、更新、結束。

這對遠端 Agent 很重要：如果 Agent 在微信、Discord、Telegram 或 Control UI 裡執行，你需要知道它正在查檔案、跑命令還是等待審批。

7. Skills 是 Agent 的操作手冊

Tools 解決“能不能做”，Skills 解決“應該怎麼做”。

OpenClaw 使用 AgentSkills-compatible skill folders。每個 skill 是一個目錄，裡面至少有 SKILL.md，透過 YAML frontmatter 描述名稱和用途，再寫具體操作說明。

官方當前的載入優先順序是：

同名 skill 衝突時，高優先順序覆蓋低優先順序。這裡有兩個實踐結論：

1. 專案專用流程放 <workspace>/skills，不要汙染全域性。
2. 通用個人習慣放 ~/.agents/skills 或 ~/.openclaw/skills，但要知道它會影響很多 Agent。

Skill 還有 allowlist。agents.defaults.skills 可以設預設可見技能，agents.list[].skills 可以替換某個 Agent 的技能集合。非空列表是最終集合，不會和 defaults 合併。

8. 許可權邊界要拆成三層

舊式理解經常把許可權說成“允許 Agent 用工具”一句話。OpenClaw 當前文件把它拆得更清楚：

三個層次不能混為一談。

flowchart TD
  A[Agent wants to run exec] --> B{Tool policy allows exec?}
  B -- No --> X[blocked]
  B -- Yes --> C{Session sandboxed?}
  C -- No --> D[host exec policy applies]
  C -- Yes --> E{Elevated requested and allowed?}
  E -- No --> F[run inside sandbox]
  E -- Yes --> G[run on gateway or node with approvals]

幾個硬規則：

• deny 總是贏。
• 如果 allow 非空，其他工具預設視為 blocked。
• Tool policy 是硬停止點，/exec 不能覆蓋被 deny 的 exec。
• /exec 只改當前 session 的 exec 預設引數，不授予工具訪問權。
• Elevated 隻影響 exec，不授予額外工具，也不覆蓋 tool allow/deny。
• /elevated full 會跳過 exec approvals，但前提仍然是 elevated 可用且 allowlist 透過。

這部分很關鍵。把許可權層次講清楚，才不會把“工具不可用”“sandbox 裡跑不到宿主路徑”“審批沒過”“skill 沒載入”混成同一個問題。

9. Hooks 不是一個東西

OpenClaw 現在有兩套容易混淆的 hook：

• Internal hooks：執行在 Gateway 事件指令碼層，適合 /new、/reset、/stop、agent:bootstrap、gateway lifecycle、message events。
• Plugin hooks：執行在外掛內程序擴充套件點，適合改 prompt、攔截 tool call、控制訊息傳送、觀察 session lifecycle。

Internal hooks 的事件包括：

• command:new
• command:reset
• command:stop
• session:compact:before
• session:compact:after
• agent:bootstrap
• gateway:startup
• message:received
• message:preprocessed
• message:sent

Plugin hooks 才包含 before_tool_call、after_tool_call、before_prompt_build、before_agent_reply 等更深的 Agent loop 擴充套件點。

所以實踐上要這樣選：

• /new 時儲存一份會話摘要：Internal hook。
• Gateway 啟動時跑 BOOT.md：Internal hook。
• 在系統 prompt 構建前注入動態上下文：Plugin hook。
• 在工具呼叫前要求審批或改引數：Plugin hook。
• 出站訊息傳送前重寫或取消：Plugin hook。

不要把 internal hook 當成萬能攔截器。它適合事件自動化；真正要進入模型、工具、訊息派發鏈路，應該用 Plugin hooks。

10. Streaming、timeout 和靜默回覆

Agent loop 執行時會發三類主要事件流：lifecycle 負責 start、end、error；assistant 負責 assistant deltas；tool 負責 tool start/update/end。

這也是為什麼 OpenClaw 可以在聊天渠道里邊做邊回，或者在 Control UI 裡展示工具過程。

超時也分層：

• agent.wait 預設只是等待 30 秒，不代表 Agent 被停止。
• Agent runtime 有 agents.defaults.timeoutSeconds，官方預設值是 48 小時。
• Model idle timeout 會在模型長時間沒有輸出 chunk 時中止請求。
• exec 自己也有每個命令的 timeout。

最終回覆階段還有一個特殊規則：精確的 NO_REPLY / no_reply 會從出站 payload 裡過濾掉。這個能力適合 Agent 已經透過 messaging tool 傳送過可見回覆、或者某些自動化任務不需要再重複確認。

11. 常見誤解

常見誤解可以按這組邊界校正：

• Agent 不是 ChatGPT 套殼。Agent 是 runtime 驅動的迴圈，模型只是其中一層。
• Tool 寫在 TOOLS.md 裡不等於能用。工具可用性由 tool policy 決定，TOOLS.md 只是指導。
• Skill 不等於工具。Skill 是說明書，工具才是執行能力。
• Hook 不是都能攔截工具呼叫。before_tool_call 屬於 Plugin hooks，不是普通 internal hook。
• Elevated 不等於超級管理員。Elevated 隻影響 sandbox 中的 exec，不能覆蓋 tool policy。
• agent.wait 超時不等於 Agent 停了。agent.wait 只是等待超時，不等於執行被取消。

這些區別看起來細，但後面排障會頻繁用到。

12. 給 Agent 的實踐任務

把下面任務交給你的 OpenClaw Agent，觀察它的過程：

请解释你处理这条消息时会经历哪些阶段：
1. 哪些 workspace 文件会影响你的回答？
2. 你现在有哪些 tools 和 skills？
3. 如果要运行 shell 命令，sandbox、tool policy、elevated 分别会影响什么？
4. 什么时候应该用 internal hook，什么时候应该用 plugin hook？

你要看的不是答案是否漂亮，而是它能不能把 runtime、context、tools、skills、policy、hooks 分層說清楚。

如果它把 TOOLS.md 當成授權配置，或者把 before_tool_call 寫成普通 internal hook，就說明這章還沒吃透。

13. 本章自檢

讀完這一篇，你應該能回答：

1. 為什麼說 Agent loop 不是一次 API 呼叫？
2. OpenClaw 為什麼要按 session 序列化 Agent run？
3. Workspace、bootstrap files、session store 分別影響什麼？
4. Tools 和 Skills 的邊界是什麼？
5. Sandbox、tool policy、elevated 三層分別控制什麼？
6. Internal hooks 和 Plugin hooks 的區別是什麼？
7. NO_REPLY 為什麼不會作為普通回覆發出去？

能回答這些問題，再進入下一篇記憶系統，才不會把“Agent 記住了什麼”和“Agent 本輪看見了什麼”混在一起。

14. 接下來去哪

15. 官方資料

• Agent Runtime
• Agent Loop
• Exec Tool
• Skills
• Hooks
• Plugin Hooks
• Sandbox vs Tool Policy vs Elevated