2026/3/12 基于openclaw整理

https://github.com/openclaw/openclaw

OpenClaw 技术 Track 分析

底层能力、工具、技能、架构增强

一、项目概览

OpenClaw 是一个 TypeScript ESM 编写的 AI 助手平台，核心理念是"能真正做事的 AI"——在用户设备上运行，接入各种消息频道，遵循用户设定的规则。

二、核心架构

三、底层能力详解

3.1 Agent 引擎 (Pi SDK 嵌入式集成)

OpenClaw 的 AI 核心基于 Pi SDK 的嵌入式集成，而非 CLI/RPC 方式调用。

关键架构决策：

• 嵌入式实例化：直接 import { createAgentSession } 创建 Agent Session
• 完全接管工具集：不使用 Pi 内置工具，全部替换为 OpenClaw 自定义工具
• 自定义系统 Prompt：根据频道/上下文动态生成
• JSONL 会话持久化：树状结构（id/parentId 链接），支持分支和压缩

核心文件：

模型支持： Anthropic, OpenAI, Google Gemini, Ollama, HuggingFace, MiniMax, Moonshot, Venice, Bedrock, BytePlus/火山引擎, 通义千问, Chutes, vLLM, GitHub Copilot, Cloudflare AI Gateway, Vercel AI Gateway 等。

3.2 工具系统

工具管线流程：

Pi 基础工具 → OpenClaw 替换(exec/read/write) → OpenClaw 扩展工具 → 频道专属工具 → 策略过滤 → Schema 标准化 → AbortSignal 包装

内置工具分类：

3.3 Gateway 服务器

[server.impl.ts]是核心，职责包括：

• HTTP + WebSocket 双协议：RESTful API + 实时 WS 通信
• 多层认证：Token、OAuth、设备认证、浏览器硬化、CORS/CSP
• 频道生命周期管理：启动/停止/健康监控
• 配置热重载：运行时修改配置无需重启
• Control UI：内嵌 Web 管理界面
• OpenAI 兼容 API：[openai-http.ts] + [openresponses-http.ts]

3.4 插件系统

src/plugins/├── loader.ts       # 插件加载器（~26KB）- jiti 动态加载├── registry.ts     # 插件注册表（~18KB）- 生命周期管理├── hooks.ts        # 插件 Hooks（~23KB）- 全生命周期钩子├── discovery.ts    # 插件发现（~21KB）- npm/本地/workspace├── types.ts        # 类型定义（~26KB）- 完整的插件 API 类型└── manifest.ts     # 清单解析 - 声明式能力

插件能力： 提供 Provider、频道、工具、Hooks、内存引擎等扩展点。插件通过 npm install --omit=dev 安装，运行时通过 jiti 动态加载。

3.5 Hooks 系统

生命周期钩子机制，支持：

• before-agent-start / after-agent-end
• before-tool-call / after-tool-call
• before-message / after-message
• compaction 钩子
• session / subagent / gateway / llm 钩子

配置方式：YAML frontmatter 的 Hook 文件 + 内置钩子 + 插件钩子。

3.6 浏览器自动化

[src/browser/] 含 133+ 文件：

• Playwright 集成：[pw-session.ts]管理浏览器会话
• CDP 直连：[cdp.ts]支持 Chrome DevTools Protocol
• Chrome 扩展中继：[extension-relay.ts]通过扩展桥接
• AI 集成：[pw-ai.ts] Playwright AI 模块
• 多 Profile 支持：[profiles-service.ts] 管理多个浏览器配置

四、技能（Skills）系统

52 个内置技能，覆盖分类：

技能通过 SKILL.md 声明，支持 clawhub.ai 社区发布。

五、扩展生态 (Extensions)

40 个扩展插件，按类别：

六、核心架构增强能力

6.1 ACP 协议 (Agent Communication Protocol)

[src/acp/]实现了 Agent 间通信协议：

• [translator.ts]：消息协议翻译
• [session.ts]：ACP 会话管理
• persistent-bindings：持久化的 Agent 绑定

6.2 子 Agent 体系

完备的子 Agent 生命周期管理：

• 注册表：[subagent-registry.ts]
• 生成：[subagent-spawn.ts]
• 控制：[subagent-control.ts]
• 通告：[subagent-announce.ts]
• 深度限制：嵌套深度管控
• 生命周期重试：优雅的错误恢复

6.3 沙箱化执行

• Docker 容器隔离执行
• 工作区路径限制
• 工具级策略过滤
• 浏览器桥接 URL

6.4 上下文窗口管理

• 自动压缩：上下文溢出时自动触发
• Cache-TTL 上下文裁剪：基于缓存时间戳的智能裁剪
• 压缩安全守卫：自适应 Token 预算 + 失败操作摘要
• 历史限制：按频道类型（DM vs 群组）差异化

6.5 认证与故障转移

• 多 Profile 轮转：同一 Provider 多 API Key，自动轮换
• 冷却追踪：失败后 Profile 进入冷却期
• 模型故障转移：主模型失败自动切换备用
• Provider 兼容层：Anthropic/Gemini/OpenAI 各自的 quirks 处理

6.6 MCP 支持

通过 mcporter 桥接 MCP 协议，解耦方式集成：

• 无需重启 Gateway 即可增删 MCP Server
• 保持核心工具/上下文精简

七、数据流总结

八、关键技术指标