OpenClaw 深度剖析：架構、代理迴圈與運作原理

深入剖析 OpenClaw 的技術架構——從 Pi 的四工具極簡設計，到 Gateway WebSocket 協定、工作階段管理、瀏覽器自動化及技能系統。本文以我們對 v2026.1.30 程式碼庫的原始碼分析為基礎。

CHATTERgo Team
AI 代理開源架構技術深度剖析OpenClaw
返回文章列表

在上一篇文章中，我們介紹了 OpenClaw——這個前稱 Clawdbot、在一週內突破 145,000 顆 GitHub 星標的爆紅開源 AI 代理。那篇文章談的是它「是甚麼」以及「為甚麼重要」。這篇文章會再深入一步：我們分析了實際原始碼（版本 2026.1.30），了解它「如何」運作——尤其是 OpenClaw 如何建立在 Pi 之上。

我們發現，這是一套工程設計相當出色的系統，其理念挑戰了業界大部分人對建立 AI 代理的既有思維。

OpenClaw AI 代理架構

Pi 基礎：四個套件，一套理念

OpenClaw 的核心是 Pi——由 Mario Zechner 建立的極簡編程代理。正如 Armin Ronacher 在分析文章中所寫，Pi 有趣之處在於兩點：

  1. 它的核心非常精簡。 Pi 擁有所有代理中最短的系統提示詞，而且只有四個工具：Read、Write、Edit、Bash。
  2. 它透過擴充系統彌補精簡核心的不足，讓擴充功能能將狀態持久儲存至工作階段。

這是刻意作出的架構決定，而不是限制。Pi 的理念是：如果你想讓代理做新的事情，就請代理自行擴充能力。不需要 MCP 協定，也不用從技能市集下載——代理會自行編寫程式碼。

正如 Ronacher 所說：

「這不是偷懶而省略功能，而是源於 Pi 的運作理念。Pi 的整個想法是，如果你想讓代理做它尚未能做的事情，你不會去下載擴充功能、技能或其他類似東西，而是請代理自行擴充能力。它推崇的是編寫程式碼和執行程式碼的理念。」

OpenClaw 如何使用 Pi

查看實際的 package.json，可見 OpenClaw 依賴四個 Pi 套件（全部為 v0.51.0）：

套件 用途
@mariozechner/pi-agent-core 核心型別：AgentMessage、AgentTool、AgentEvent、StreamFn
@mariozechner/pi-ai LLM 抽象層：Model<Api>、complete()、streamSimple()、OAuthCredentials
@mariozechner/pi-coding-agent 工作階段管理：SessionManager、createAgentSession()、Skill、ExtensionContext、工具工廠（createReadTool、createWriteTool、createEditTool、codingTools）
@mariozechner/pi-tui 終端機介面：TUI、Component、SlashCommand、互動式元件

OpenClaw 並沒有建立 Pi 的分支版本，而是在外層封裝它。Pi 的代理核心提供基本的代理迴圈、工具系統及工作階段管理。OpenClaw 則在其上加入其餘功能：閘道、通訊渠道、額外工具、記憶、瀏覽器自動化及子代理系統。

flowchart TB
    subgraph PI["Pi Packages (v0.51.0)"]
        direction TB
        PAC["pi-agent-core<br/>AgentMessage, AgentTool, AgentEvent"]
        PAI["pi-ai<br/>Model, complete(), stream(), OAuth"]
        PCA["pi-coding-agent<br/>SessionManager, AgentSession,<br/>Read/Write/Edit/Bash tools,<br/>Skills, Extensions"]
        PTU["pi-tui<br/>TUI, Components, SlashCommands"]
    end
    
    subgraph OC["OpenClaw Layer"]
        direction TB
        EMB["Pi Embedded Runner<br/>(wraps Pi's agent loop)"]
        TW["Tool Wrappers<br/>(extends Pi's 4 tools)"]
        OT["20+ Additional Tools<br/>browser, message, exec,<br/>web_search, image, cron,<br/>sessions_spawn, memory..."]
        TP["8-Layer Tool Policy<br/>profile → provider → global →<br/>agent → group → sandbox →<br/>subagent"]
        EXT["Pi Extensions<br/>Context Pruning,<br/>Compaction Safeguard"]
    end
    
    subgraph INFRA["OpenClaw Infrastructure"]
        GW["Gateway + Channels"]
        MEM["Memory + Vector Search"]
        SUB["Subagent Registry"]
        SEC["Security + Sandbox"]
        ACP["Agent Communication<br/>Protocol (ACP)"]
    end
    
    PI --> OC
    OC --> INFRA

OpenClaw 如何封裝 Pi 的工具

OpenClaw 並非直接照用 Pi 的四個核心工具，而是為每個工具加入適合正式環境的強化層；這些實作可在 src/agents/pi-tools.ts 中看到：

Read → createOpenClawReadTool：封裝 Pi 的 createReadTool()，加入 MIME 偵測（透過檔案魔術位元組驗證圖片類型）、圖片清理（在傳送至供應商前移除過大的圖片），以及 Claude Code 相容處理（將 file_path 作為 path 的別名）。

Write → 沙箱封裝：封裝 Pi 的 createWriteTool()，在啟用沙箱模式時加入路徑防護，防止檔案寫入沙箱根目錄以外的位置。

Edit → 沙箱封裝：封裝 Pi 的 createEditTool()，加入參數標準化（為相容 Claude，將 old_string/new_string 轉為 oldText/newText）及沙箱路徑防護。

Bash → 完全取代：Pi 的 bash 工具由 OpenClaw 的 exec 工具取代。這是一個明顯更完善的執行引擎，支援 Docker 沙箱執行、背景程序管理（透過獨立的 process 工具）、安全政策（逐項指令詢問／拒絕／允許）、提權模式、逾時處理、長時間執行程序的審批流程，以及按作用範圍追蹤程序。

除了四個核心工具，OpenClaw 還加入 20+ 個額外工具：

類別 工具
訊息通訊 message、sessions_send、sessions_spawn、sessions_list、sessions_history
瀏覽器 browser（13 項子操作：navigate、snapshot、act、tabs、console、pdf...）
網頁 web_search、web_fetch
媒體 image（視覺分析）、tts（文字轉語音）
基礎設施 gateway、nodes、cron、canvas、memory
特定渠道 discord_actions、slack_actions、telegram_actions、whatsapp_actions
程式碼 apply_patch（OpenAI Codex 專用）、process（背景工作）

嵌入式執行器：OpenClaw 的代理迴圈封裝層

最重要的整合點是 Pi Embedded Runner（src/agents/pi-embedded-runner/）。OpenClaw 透過它封裝 Pi 的代理迴圈，以支援多渠道使用：

flowchart TB
    ENTRY["Entry Points<br/>Gateway RPC / CLI / Cron / Webhook"]
    
    subgraph P1["Phase 1: Setup"]
        WS["Resolve Workspace + Sandbox"]
        TOOLS["Build OpenClaw Tools<br/>(Pi's 4 + 20+ extras)"]
        SM["Open SessionManager<br/>(Pi JSONL store)"]
        SETTINGS["Load SettingsManager<br/>(Pi workspace config)"]
        AGENT["createAgentSession()<br/>(Pi factory)"]
    end
    
    subgraph P2["Phase 2: Context Assembly"]
        SYS["Build System Prompt<br/>Base + Tools + Skills +<br/>SOUL.md + USER.md +<br/>AGENTS.md + HEARTBEAT.md"]
        MODEL["Resolve Model + Auth<br/>(Pi ModelRegistry +<br/>OpenClaw AuthStorage)"]
        HIST["Load Full History<br/>(Pi SessionManager)"]
        SAN["Sanitize History<br/>(Anthropic/Gemini turn ordering)"]
        IMG["Auto-inject Images<br/>(vision model detection)"]
        PRUNE["Context Pruning Extension<br/>(soft trim / hard clear)"]
    end
    
    subgraph P3["Phase 3: Execution"]
        PROMPT["session.prompt()<br/>(Pi agent loop)"]
        STREAM["subscribeEmbeddedPiSession()<br/>(OpenClaw stream wrapper)"]
        POLICY["8-Layer Tool Policy<br/>Check before each tool call"]
    end
    
    subgraph P4["Phase 4: Completion"]
        COMP["Compaction if Triggered<br/>(Pi + Safeguard Extension)"]
        PERSIST["Persist to JSONL"]
        REPLY["Shape + Send Reply<br/>to Channel"]
        CLEANUP["Dispose Session +<br/>Release Locks"]
    end
    
    ENTRY --> P1
    P1 --> P2
    P2 --> P3
    P3 -->|"Tool calls loop<br/>back through Pi"| P3
    P3 --> P4

嵌入式執行器的工作

  1. 工作區設定：解析代理的工作區目錄、沙箱設定及技能快照
  2. 建立工具：呼叫 createOpenClawCodingTools()——取得 Pi 的 codingTools 陣列，逐一取代或封裝工具，再加入 20+ 個 OpenClaw 專用工具
  3. 初始化工作階段：開啟 Pi 的 SessionManager（JSONL 對話紀錄）、建立 SettingsManager，然後呼叫 Pi 的 createAgentSession() 工廠函式
  4. 覆寫系統提示詞：將基礎提示詞、工具摘要、技能、啟動檔案（SOUL.md、USER.md 等）及執行環境資訊組合成完整系統提示詞
  5. 清理歷史紀錄：驗證並修正供應商特定的對話輪次順序（Anthropic 要求用戶與助理輪次交替；Gemini 要求以用戶輪次開始）
  6. 執行提示詞：呼叫 session.prompt()——此時實際執行的是 Pi 的代理迴圈
  7. 訂閱串流：subscribeEmbeddedPiSession() 封裝 Pi 的串流，加入 OpenClaw 特定處理，包括區塊式回覆、推理內容擷取，以及向閘道回呼部分回覆
  8. 壓縮：若觸發條件成立，執行 Pi 的 session.compact()，並由 Compaction Safeguard 擴充功能確保過程不會消耗過多上下文

八層工具政策系統

OpenClaw 架構中最精密的部分之一，是它的工具政策系統。任何工具執行前，都必須通過八層允許／拒絕篩選：

  1. 設定檔政策（tools.profile）——具名政策預設組合
  2. 供應商設定檔（tools.byProvider.profile）——按 LLM 供應商覆寫設定
  3. 全域允許清單（tools.allow）——整個執行個體的限制
  4. 供應商允許清單（tools.byProvider.allow）——按供應商設定的全域限制
  5. 代理專屬政策（agents.{id}.tools.allow）——逐個代理的限制
  6. 群組政策——渠道層級限制（例如在 Discord 伺服器中停用 exec）
  7. 沙箱政策——Docker 沙箱限制
  8. 子代理政策——針對新建立子代理的限制

這表示，在你的私人 WhatsApp 工作階段中獲准使用的瀏覽器工具，可以在 Discord 群組聊天中被拒絕；而沙箱內的子代理又可能採用完全不同的一組限制。每一層都會縮窄可用工具範圍——最嚴格的組合優先。

Pi 擴充功能：上下文修剪與壓縮防護

OpenClaw 內置兩個自訂 Pi 擴充功能，會掛接 Pi 的生命週期事件：

上下文修剪擴充功能

這個擴充功能位於 src/agents/pi-extensions/context-pruning/，會攔截 LLM 呼叫前的階段，在上下文視窗空間不足時修剪舊工具結果：

  • 軟性裁剪：截短大型工具結果，保留開頭及結尾
  • 硬性清除：以佔位內容取代非常舊的工具結果
  • 保護機制：絕不修剪第一則用戶訊息之前的內容（保護啟動時讀取的資料），並遵守 keepLastAssistants 設定
  • 觸發條件：只在 Anthropic 快取 TTL 到期時啟動（預設為 5 分鐘），減少不必要的快取寫入成本

壓縮防護擴充功能

這個擴充功能位於 src/agents/pi-extensions/compaction-safeguard.ts，會攔截 Pi 的 session_before_compact 事件：

  • 防止壓縮過程消耗過多上下文
  • 為移除的訊息另行製作摘要
  • 追蹤檔案操作（已讀取／修改的檔案），並將其納入摘要
  • 納入工具失敗摘要

這些擴充功能展示了 Pi 架構的實際運作方式：它們以檔案路徑形式載入，由 Pi 在執行時發現，並透過 Pi 的 SessionManager 持久儲存狀態。

子代理系統

OpenClaw 在 Pi 之上加入子代理協調層（src/agents/subagent-registry.ts）：

  • 建立子代理：sessions_spawn 工具會建立擁有獨立工作區及工具集的子代理工作階段
  • 登錄表：在記憶體及磁碟上追蹤子代理執行
  • 生命週期：監聽 Pi 代理的開始／完成／錯誤事件
  • 清理：可設定政策，以 delete 或 keep 刪除或保留已完成的子代理資料
  • 通知：子代理完成時通知父代理
  • 跨程序：透過閘道 RPC 跨程序等待子代理

OpenClaw 代理正是這樣委派任務：「研究這個主題」會建立研究子代理，「草擬回覆」會建立寫作子代理——全部由父代理協調。

代理通訊協定（ACP）

OpenClaw 實作了代理通訊協定（Agent Communication Protocol）（src/acp/）——一項新興的代理間通訊標準：

  • 伺服器：實作 @agentclientprotocol/sdk 的 AgentSideConnection
  • 轉換層：連接 ACP 與 OpenClaw 的閘道協定
  • 工作階段對映：將 ACP 工作階段對映至 OpenClaw 工作階段金鑰
  • 事件對映：將閘道生命週期事件轉換為 ACP 事件

這讓外部相容 ACP 的客戶端能透過 stdio（NDJSON）控制 OpenClaw 代理，為與其他代理框架互通打開大門。

記憶：向量搜尋與語意檔案

OpenClaw 的記憶系統（src/memory/）不止於簡單的檔案儲存：

  • 向量嵌入：支援 OpenAI、Gemini 及本機 node-llama-cpp 嵌入供應商
  • SQLite-vec：使用帶有向量擴充功能的 SQLite 作本機向量儲存
  • 混合搜尋：結合向量相似度搜尋與關鍵字比對
  • 自動建立索引：自動為工作階段對話紀錄、MEMORY.md 及每日筆記建立索引
  • 去重：在重新建立索引時避免重複項目

記憶 tool 讓代理能以語意方式搜尋自己的歷史紀錄——例如「我上週二討論了 API 項目的甚麼內容？」——而不必將完整歷史紀錄放入上下文。

安全存取範圍仍然至關重要：

  • 主要工作階段（與擁有者直接聊天）：可以讀寫 MEMORY.md，並使用向量搜尋
  • 群組工作階段：不能存取 MEMORY.md 或個人記憶，防止資料外洩

瀏覽器自動化：Playwright 與 AI 快照

OpenClaw 實作了一套精密的瀏覽器控制系統（browser-tool.ts 共 725 行），以 Playwright 為基礎，並整合 Chrome DevTools Protocol（CDP）。

flowchart LR
    subgraph PROFILES["Browser Profiles"]
        OC["openclaw<br/>Managed Playwright"]
        CE["chrome extension<br/>Extension Relay"]
        SB["sandbox<br/>Docker Container"]
        RM["remote<br/>Browserless.io"]
    end
    
    subgraph TOOLS["13 Browser Actions"]
        NAV["navigate"]
        SNAP["snapshot"]
        SCRN["screenshot"]
        ACT["act (click/type/drag)"]
        TABS["tabs / open / focus / close"]
        CON["console"]
        PDF["pdf"]
    end
    
    REQ["Agent Tool Call"] --> PROF["Profile Selection"]
    PROF --> PROFILES
    PROFILES --> PW["Playwright Connection"]
    PW --> TOOLS
    TOOLS --> RES["Role References<br/>e1, e2, e3..."]
    RES -->|"Used in future actions"| REQ

視覺系統：不使用外部程式庫

OpenClaw 不會使用外部視覺程式庫（tesseract、pixelmatch 等）來理解網頁，而是利用 Playwright 內部的 _snapshotForAI 方法——這是一個無障礙樹 API，能產生穩定、以角色為基礎的元素參照。

代理透過穩定參照來指定元素：click e7、type e4 "user@example.com"。這比以像素為基礎的方法更可靠，因為角色參照不會因頁面佈局改變、動畫或響應式斷點而失效。

多設定檔架構

  • openclaw——由 Playwright 管理的瀏覽器，擁有獨立的用戶資料目錄，與你的個人瀏覽器完全隔離。
  • chrome extension——透過本機擴充功能中繼連接至你實際使用的 Chrome 瀏覽器，適合需要存取已登入工作階段的情況。
  • sandbox——以 Docker 容器執行的瀏覽器，為不可信網站提供完全隔離。
  • remote——Browserless.io 或類似的遠端 CDP 端點，供伺服器端自動化使用。

技能：有安全保障的自我擴充

技能是帶有 YAML 前置資料的 Markdown 檔案（SKILL.md），會按優先次序從多個來源載入：

  1. 工作區技能（./skills/）——最高優先次序
  2. 受管理技能（~/.openclaw/skills/）
  3. 內置技能（npm 套件）
  4. 額外目錄（設定）
  5. 外掛技能目錄
  6. ClawHub（clawhub.com）——公開登錄庫

技能包含載入檢查機制，會在載入前檢查作業系統相容性、所需執行檔、環境變數及設定值。它們亦可轉換為斜線指令（/skillname），並自動去重。

不過，Pi 的理念依然不變：雖然你可以下載技能，但它鼓勵的做法是讓代理自行編寫技能。正如 Ronacher 所描述：

「我的代理有不少技能，關鍵是，當我不再需要某個技能時，就會將它丟棄。我有一個技能，協助代理按照我的要求撰寫提交訊息、執行提交操作，以及更新變更紀錄。」

安全模型

OpenClaw 的安全防護分佈於輸入、執行及資料邊界：

  • 輸入：私訊配對（未知發送者會收到驗證碼）、明確的允許清單、群組提及觸發限制
  • 執行：非主要工作階段使用 Docker 沙箱、八層工具政策系統、逐個工作階段的提權模式開關
  • 資料：只在本機儲存、記憶存取範圍（主要與群組工作階段之別）、憑證儲存於 ~/.openclaw/credentials/
  • 網絡：Gateway WebSocket 只綁定迴路介面（127.0.0.1:18789）、以權杖進行身分驗證

共有三個權限層級：non-main（限制最多）、main（正常）、elevated（執行敏感操作時明確啟用）。

這對 AI 代理架構意味着甚麼

我們的原始碼分析揭示了幾個值得留意的架構模式：

1. 封裝，而非建立分支。 OpenClaw 以 npm 套件形式依賴 Pi，封裝其工具及工作階段管理，而不是建立程式碼庫的分支版本。這表示 Pi 的改進會自動傳遞至下游。

2. 從 4 個擴展至 24+ 個工具的模式。 Pi 由 4 個工具起步。OpenClaw 封裝這 4 個工具，再加入 20+ 個——但全部都遵循 Pi 統一的 AgentTool 介面。代理迴圈不在意有多少工具，只會執行 LLM 選擇的工具。

3. 多租戶代理必須具備多層政策系統。 當一個代理同時服務 WhatsApp 私訊、Discord 伺服器及沙箱子代理時，你需要的是可組合的安全政策，而不是單一的允許／拒絕清單。

4. 處理代理內部事務時，擴充功能優於外掛。 Pi 的擴充系統（生命週期掛接點及狀態持久儲存）比外掛系統更適合處理代理內部事務（上下文管理、壓縮），因為擴充功能可以攔截代理迴圈本身。

5. 保留完整歷史紀錄，配合智能淘汰。 OpenClaw 將完整對話歷史傳送至 LLM，透過壓縮（持久摘要）及修剪（暫時裁剪）管理成本，保留過度摘要會遺失的細節。

這與 CHATTERgo 的關係

CHATTERgo 與 OpenClaw 在理念上有共通之處——尤其是重視自主、能使用工具的代理，而非預先編寫的工作流程。我們的 AI 代理亦會：

  • 動態推理客戶問題，而不是依循流程圖
  • 使用執行時選取的工具（產品目錄搜尋、訂單查詢、知識庫）
  • 跨工作階段保留對話上下文
  • 透過自訂工具、API 及 MCP 擴充能力

關鍵差異在於我們專注的領域。OpenClaw 是在你自己的硬件上執行的通用個人代理。CHATTERgo 則是以託管服務形式運作、專為電子商務而設的代理，針對產品推薦、客戶支援及多語言商務營運作出最佳化。

兩種方法都指向同一個未來：AI 不只是談論事情，而是真正採取行動。

資料來源

  1. OpenClaw 原始碼（v2026.1.30）：github.com/openclaw/openclaw
  2. OpenClaw 文件：docs.openclaw.ai
  3. OpenClaw 網站：openclaw.ai
  4. ClawHub 技能登錄庫：clawhub.com
  5. Armin Ronacher，〈Pi：OpenClaw 之中的極簡代理〉，2026 年 1 月 31 日：lucumr.pocoo.org/2026/1/31/pi
  6. CHATTERgo 程式碼分析——OpenClaw 架構深度剖析（v2026.1.30）：app.chattergo.com/apps/public/doc/c2758da9
  7. CHATTERgo 程式碼分析——OpenClaw 瀏覽器控制系統：app.chattergo.com/apps/public/doc/5965a85b

聚焦業務需要的示範。

探索購物顧問、電商營運流程，或兩者兼備。告訴我們您的優先事項。

正在確認表格狀態…