这很重要
OpenClaw 代码库架构总结
=====================
OpenClaw 是一个功能非常丰富的个人 AI 助手系统。以下是主要组件和架构的详细分析：
## 核心架构概览
### 1. Gateway 控制平面 (src/gateway/)
- WebSocket 控制服务器，统一管理会话、渠道、工具和事件
- 核心实现在 server.impl.ts，包含健康检查、维护、发现等
- 支持 HTTP 端点（OpenAI Completions、OpenResponses API）
- 内置 TailScale 暴露和远程访问支持
- 负责认证、授权、会话管理
### 2. Agent 运行时 (src/agents/)
- 基于 @mariozechner/pi-agent-core 的嵌入式 Pi agent
- 流式订阅系统 (pi-embedded-subscribe.ts)，处理 LLM 输出、工具调用、消息分块
- 工具系统 (pi-tools.ts) 包括 Bash、文件操作、编辑、浏览器、Canvas 等
- 沙箱支持 (sandbox/)，用于多租户和组隔离
- 子 Agent 协调 (subagent-registry.ts)
- 认证配置管理 (auth-profiles.ts)
- 技能系统 (skills/) - bundled、workspace、managed
### 3. 消息渠道系统 (src/channels/)
- 支持多种渠道：Telegram、WhatsApp、Discord、Slack、Signal、iMessage、Google Chat
- 插件系统支持扩展渠道（Microsoft Teams、Matrix、Zalo 等）
- 路由、许可列表、配对、命令门控
- 组消息处理和提及门控
- 渠道注册表 (registry.ts)
### 4. 浏览器控制 (src/browser/)
- 基于 Playwright 的浏览器控制
- 独立的控制服务器 (server.ts)，通过 CDP 协议通信
- 配置文件管理、截图、交互工具
- 支持 AI 模块（pw-ai.ts）
- 客户端操作核心 (client-actions-*.ts)
### 5. Canvas 主机 (src/canvas-host/)
- A2UI（Agent-to-UI）系统
- 可视化工作空间支持
- 文件解析器和服务端状态管理
- Canvas 主机服务器
### 6. 插件系统 (src/plugins/)
- 强大的插件架构，支持：
- 工具注册 (registerTool)
- 钩子系统 (registerHook)：agent_start、llm_input、llm_output、tool_call 等
- HTTP 处理器
- CLI 命令
- 渠道插件
- Provider 插件（OAuth/API Key）
- 插件来源：bundled、global、workspace、config
- 插件注册表 (registry.ts)
- 运行时管理 (runtime/)
### 7. 技能系统 (src/agents/skills/)
- Bundled 技能（内置）
- Workspace 技能（用户定义）
- Managed 技能（远程）
- 前置元数据处理、过滤、序列化
- 技能刷新和状态管理
### 8. CLI (src/cli/)
- Commander.js 构建的 CLI
- 支持 profile 系统
- 各种子命令：gateway、agent、channels、config、skills 等
- 进度显示和终端工具
- CLI deps 和路由系统
### 9. 媒体管道 (src/media/)
- 图像、音频、视频处理
- 转录钩子、大小限制、临时文件生命周期
- 媒体理解和处理
### 10. 配置系统 (src/config/)
- JSON5 配置文件
- 验证、迁移、运行时覆盖
- 环境变量支持
- Nix 模式支持
### 11. 基础设施 (src/infra/)
- 环境变量处理
- 文件系统和路径管理
- 心跳和活动监控
- 更新检查
- SSH 和 TailScale 隧道
- 诊断事件
- 执行审批
### 12. 安全特性
- DM 配对策略（默认需要配对）
- 执行审批管理器
- 路径安全检查
- 沙箱模式（Docker 隔离）
- 工具策略管道
- 原始来源检查
- CSRF 保护
### 13. 移动端应用 (apps/)
- macOS 应用：菜单栏控制、Voice Wake、Talk Mode、Canvas
- iOS 节点：Canvas、Voice Wake、相机、屏幕录制
- Android 节点：Canvas、Talk Mode、相机、屏幕录制
- 共享代码库 (apps/shared/)
## 关键技术栈
### 核心技术
- Node 22+ 运行时
- TypeScript (ESM)
- pnpm 包管理器
- Bun 支持（可选，用于开发）
### AI 和 Agent
- @mariozechner/pi-agent-core (Pi Agent 框架)
- @mariozechner/pi-ai (AI 模型接口)
- @mariozechner/pi-coding-agent (编码工具)
### 浏览器和媒体
- Playwright (浏览器控制)
- sharp (图像处理)
- pdfjs-dist (PDF 处理)
- node-edge-tts (文本转语音)
### 通信
- ws (WebSocket)
- express (HTTP 服务器)
- @whiskeysockets/baileys (WhatsApp)
- grammy (Telegram)
- discord.js (Discord)
- @slack/bolt (Slack)
### 开发工具
- Oxlint/Oxfmt (linting/formatting)
- Vitest (测试框架)
- tsdown (TypeScript 编译)
### 消息渠道库
- @grammyjs/* (Telegram)
- @slack/* (Slack)
- discord-api-types (Discord)
- @whiskeysockets/baileys (WhatsApp)
## 设计亮点
### 1. 本地优先
- Gateway 运行在用户设备上
- 数据不离开本地环境
- 完全控制和隐私保护
### 2. 多渠道统一
- 一个 agent 连接所有消息渠道
- 统一的会话管理和上下文
- 跨渠道消息发送
### 3. 模块化架构
- 插件系统支持高度扩展
- 清晰的模块边界
- 易于添加新功能和渠道
### 4. 流式处理
- 实时 LLM 输出和工具调用
- 增量响应更新
- 低延迟用户体验
### 5. 安全性
- 多层安全机制（配对、审批、沙箱）
- DM 访问控制
- 执行策略和路径保护
### 6. 跨平台
- macOS、Linux、Windows (WSL2)
- iOS、Android 移动节点
- 统一的体验
## 项目结构
```
src/
├── agents/ # Agent 运行时、工具、技能
├── browser/ # 浏览器控制
├── canvas-host/ # Canvas/A2UI 主机
├── channels/ # 消息渠道
├── cli/ # 命令行界面
├── config/ # 配置系统
├── gateway/ # Gateway 服务器
├── infra/ # 基础设施工具
├── logging/ # 日志系统
├── media/ # 媒体处理
├── plugins/ # 插件系统
├── routing/ # 消息路由
├── runtime/ # 运行时抽象
└── ...
apps/
├── android/ # Android 应用
├── ios/ # iOS 应用
├── macos/ # macOS 应用
└── shared/ # 共享代码
extensions/ # 渠道插件
scripts/ # 构建脚本
test/ # 测试文件
docs/ # 文档
skills/ # 内置技能
```
## 核心概念
### 会话 (Sessions)
- 每个对话/渠道有独立的会话
- 会话持久化到文件系统
- 支持会话压缩和总结
### 工具 (Tools)
- Agent 可调用的函数
- 内置工具：bash、read、write、browser、canvas 等
- 插件可注册自定义工具
### 技能 (Skills)
- 可重用的 agent 能力包
- 支持 Markdown 前置元数据
- Bundled、Workspace、Managed 三种类型
### 渠道 (Channels)
- 消息输入/输出接口
- 支持 DM 和群组
- 可配置的路由和权限
### 钩子 (Hooks)
- 事件驱动的扩展点
- 支持生命周期事件、工具调用、消息处理等
## 性能和可靠性
- 并发控制和车道限制
- 重试策略和错误恢复
- 心跳监控
- 健康检查
- 会话维护和清理
这个项目展现了现代 AI 系统设计的最佳实践，特别是在隐私、扩展性和用户体验方面。