OpenClaw 项目架构学习指南

信息已经足够全面了，现在来整理一份系统的架构学习指南：

OpenClaw 项目架构学习指南

一、项目定位

OpenClaw 是一个个人 AI 助手网关（Personal AI Assistant Gateway）。核心思路：

你在手机上用 WhatsApp/Telegram/Signal 等聊天，消息发到 Gateway，Gateway 驱动 AI 模型处理，回复给你。

一句话：多渠道消息接入 → 统一 AI Agent 处理 → 多渠道消息发出。

二、整体架构分层

┌──────────────────────────────────────────────────────────┐
│                      用户侧 / 接入层                       │
│  WhatsApp / Telegram / Signal / Discord / Slack / ...    │
│  WebChat / macOS App / iOS App / Android App / CLI       │
└────────────────────────┬─────────────────────────────────┘
                         │ WebSocket (18789)
┌────────────────────────▼─────────────────────────────────┐
│                      Gateway（核心）                        │
│  WebSocket Server │ HTTP Server │ Auth │ Pairing          │
│  Channel Manager  │ Session Manager │ Cron │ Hooks        │
└────────┬───────────────────────┬─────────────────────────┘
         │                       │
┌────────▼────────┐    ┌─────────▼────────────────────────┐
│   Agent Runtime │    │      Extensions（插件层）           │
│  (pi-mono 衍生) │    │  discord / telegram / whatsapp /  │
│  Tools / Skills │    │  feishu / slack / memory / ...    │
│  Sessions/JSONL │    └──────────────────────────────────┘
└─────────────────┘

三、目录结构速查

四、五个核心概念（按优先级学习）

1. Gateway（网关）

文件：src/gateway/server.impl.ts，文档：docs/concepts/architecture.md

• 默认端口 18789，同时承载 WebSocket API + HTTP（Canvas）
• 所有客户端（App/WebChat/CLI）通过 WebSocket 连接，第一帧必须发 connect
• 帧格式：{type:"req"idmethodparams} ↔ {type:"res"idokpayload}
• 事件推送：{type:"event"eventpayload}

2. Agent Loop（Agent 执行循环）

文件：src/agents/pi-embedded-runner/，文档：docs/concepts/agent-loop.md

收到消息 → 组装上下文/System Prompt → 调用模型 → 工具调用（循环）→ 流式输出 → 存 JSONL

• 每个 Session 串行执行（有队列），不并发
• 支持超时中断（默认 600s）
• 支持 Compaction（上下文压缩，防 token 溢出）

3. Channel Plugin（渠道插件）

文件：src/channels/plugins/，extensions/<渠道名>/，文档：docs/channels/

• 每个渠道（WhatsApp、Telegram 等）是一个独立插件
• 统一接口：消息接收 → auto-reply 调度层 → Agent → 消息发出
• 渠道配置在 openclaw.on 的 channels 节点下

4. Session（会话）

文件：src/sessions/，文档：docs/concepts/session.md

• Key 格式：agent:<agentId>:<sessionKey>
• 默认所有私信共享 main session（单用户友好）
• 多用户场景建议设 dmScope: "per-channel-peer" 隔离
• Transcript 存 ~/.openclaw/agents/<id>/sessions/<SessionId>.onl

5. Plugin Hook 系统

文件：src/plugins/，文档：docs/concepts/agent-loop.md（Hook Points 章节）

关键 Hook 点：

• before_prompt_build → 注入自定义 context
• before_tool_call / after_tool_call → 拦截工具调用
• message_received / message_sending → 拦截消息
• gateway_start / gateway_stop → 生命周期

五、推荐学习路径

第1步：读架构文档
  docs/concepts/architecture.md       ← 整体架构（已读✓）
  docs/concepts/agent.md              ← Agent 运行时
  docs/concepts/agent-loop.md         ← 执行循环（已读✓）
  docs/concepts/session.md            ← 会话管理（已读✓）

第2步：看 Gateway 启动流程
  src/gateway/server.impl.ts          ← startGatewayServer()
  src/config/paths.ts                 ← 配置路径解析（已读✓）
  src/config/zod-schema.ts            ← 配置结构

第3步：理解消息流转
  src/auto-reply/                     ← 收到消息如何触发 Agent
  src/channels/plugins/index.ts       ← 渠道插件注册
  src/agents/pi-embedded-runner/      ← Agent 实际执行

第4步：研究扩展机制
  extensions/discord/                 ← 看一个具体渠道实现
  src/plugins/                        ← 插件运行时
  docs/tools/plugin.md                ← 插件开发文档

第5步：了解 ACP 协议（高级）
  src/acp/                            ← Agent Client Protocol
  docs/cli/acp.md
  docs/tools/acp-agents.md

六、想深入哪个方向？

• 🔌 添加新渠道：看 extensions/ 下任意一个渠道实现
• 🔧 开发插件/Hook：看 docs/tools/plugin.md
• 🤖 修改 Agent 行为：看 src/agents/ + docs/concepts/agent-loop.md
• 🌐 WebSocket 协议：看 docs/gateway/protocol.md
• 💾 会话存储/记忆：看 src/sessions/ + src/memory/
• 📦 Skills 开发：看 docs/tools/creating-skills.md

你最想先深入了解哪块？我可以帮你精读对应代码。