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

聚焦业务需要的演示。

探索购物顾问、电商运营流程，或两者兼备。告诉我们您的优先事项。

正在确认表单状态…