OpenClaw 架构分析文档

作者：CSDN博客

---

关键技术点

1. WebSocket 协议

Gateway 使用单一 WebSocket 连接处理所有通信：

请求/响应模式: {type:"req", id, method, params}事件推送: {type:"event", event, payload}认证: 通过 OPENCLAW_GATEWAY_TOKEN 或 --token幂等性: 使用 idempotency keys 防止重复处理

2. 插件架构

OpenClaw 采用模块化插件架构：

Manifest: extension.json 定义插件元数据Slots: 插槽机制用于功能扩展Hooks: 生命周期钩子 (install, load, unload)Services: 插件服务接口

3. 工具系统

基于 Pi Agent 的工具调用框架：

Bash Tools: 命令执行 (沙箱化)File Tools: 文件读写Browser Tools: 浏览器控制Canvas Tools: 可视化界面Node Tools: 设备节点控制

4. 模型选择与认证

多模型支持: Anthropic, OpenAI, Bedrock, Ollama 等Auth Profiles: 认证配置轮换Failover: 模型故障转移Cost Tracking: 使用量跟踪

5. 安全机制

Sandboxing: Docker 容器隔离非主会话DM Policy: 陌生人消息配对机制工具策略: 白名单/黑名单控制TCC 权限: macOS 权限管理

---

扩展系统

扩展目录结构

1. extensions/
2. ├── whatsapp/         # WhatsApp 扩展
3. ├── telegram/         # Telegram 扩展
4. ├── discord/          # Discord 扩展
5. ├── slack/            # Slack 扩展
6. ├── msteams/          # MS Teams 扩展
7. ├── bluebubbles/      # BlueBubbles (iMessage) 扩展
8. ├── matrix/           # Matrix 扩展
9. ├── zalo/             # Zalo 扩展
10. ├── signal/           # Signal 扩展
11. └── ...

复制代码

插件开发

1. // 插件清单示例 (extension.json){"id":"my-plugin","name":"My Plugin","version":"1.0.0","slots":["channel","tool"],"hooks":["onMessage","onSend"]}

复制代码

技能 (Skills)

1. skills/
2. ├── coding-agent/    # 编码技能
3. ├── canvas/          # Canvas 技能
4. ├── github/          # GitHub 技能
5. ├── discord/         # Discord 技能
6. └── ...

复制代码

---

安全模型

默认安全策略

主会话: 完全信任，主机执行所有工具群组/通道会话: 默认沙箱隔离DM 策略: 陌生人需配对码验证工具白名单: 默认只允许安全工具

配置示例

1. {
2.   agents: {
3.     defaults: {
4.       sandbox: {
5.         mode: "non-main",  // 非主会话使用沙箱
6.         allowlist: ["bash", "read", "write", "sessions_*"],
7.         denylist: ["browser", "canvas", "nodes"]
8.       }
9.     }
10.   }
11. }

复制代码

远程访问安全

Tailscale Serve/Funnel: 安全的远程暴露SSH Tunnel: 备选方案Token Auth: 必需的认证令牌Password Auth: Funnel 模式必需

---

文件结构概览

1. openclaw/
2. ├── src/
3. │   ├── gateway/          # Gateway 服务器核心
4. │   ├── agents/           # Agent 运行时
5. │   ├── channels/         # 消息通道
6. │   ├── cli/              # CLI 实现
7. │   ├── config/           # 配置管理
8. │   ├── plugins/          # 插件系统
9. │   ├── infra/           # 基础设施
10. │   └── ...
11. ├── extensions/          # 扩展模块
12. ├── skills/              # 技能包
13. ├── docs/                # 文档
14. ├── apps/                # 应用程序 (macOS/iOS/Android)
15. └── openclaw.mjs         # CLI 入口

复制代码

---

关键文件说明

文件路径	功能描述
src/entry.ts	Node.js 入口，处理警告过滤和进程重载
src/index.ts	CLI 主入口，配置加载和程序初始化
src/gateway/server.impl.ts	Gateway 服务器核心实现 (~1500+ 行)
src/gateway/client.ts	WebSocket 客户端管理
src/gateway/server-chat.ts	聊天会话处理
src/channels/dock.ts	通道注册表
src/agents/pi-embedded-runner/	Pi Agent 嵌入运行时
src/plugins/loader.ts	插件加载器
src/plugins/registry.ts	插件注册表
openclaw.mjs	npm 包入口脚本

---

建议关注点

1. Gateway 性能

单点瓶颈：所有通道连接都经过 GatewayWebSocket 连接管理会话状态内存占用

2. 插件兼容性

插件版本与 Gateway 版本匹配TypeBox Schema 变更影响插槽机制使用

3. 安全边界

沙箱配置的正确性陌生人 DM 策略远程访问暴露面

4. 扩展开发

遵循 extension.json 规范正确实现生命周期钩子资源清理和错误处理

5. 调试技巧

使用 OPENCLAW_LOG=debug 启用详细日志openclaw doctor 健康检查Gateway WS 调试工具

原文地址：https://blog.csdn.net/caicongyang/article/details/158073760