夜雨聆风
OpenClaw 深度解析:个人 AI 助理的架构设计之道
99% 的人只会在微信里聊 AI，但有人已经让 AI 住进了自己的手机、手表和电脑
引子
想象一下这个场景：
你在开车时收到一条 WhatsApp 消息，Apple Watch 震动了一下，你瞥了一眼，说”让 AI 回复”。手表把语音传给手机，手机转发给家里的 Gateway，Gateway 调用 AI 生成回复，再通过 WhatsApp 发回去。整个过程不到 3 秒。
这不是科幻电影，这是 OpenClaw 的日常操作。
今天，我们来深度拆解这个开源个人 AI 助理系统的架构设计，看看它是如何让 AI 真正”住进”你的设备的。
一、什么是 OpenClaw？
用一句话概括：OpenClaw 是一个让你在自己设备上运行的个人 AI 助理系统。
它不像 ChatGPT 那样需要打开网页，也不像 Siri 那样功能有限。OpenClaw 可以：
-
• 📱 通过 WhatsApp/Telegram/微信 等聊天软件与你对话 -
• ⌚️ 在 Apple Watch 上显示通知和快速回复 -
• 💻 作为 macOS 原生应用 常驻菜单栏 -
• 🏠 在家里服务器上 24 小时运行，随时待命 -
• 🔌 连接各种 AI 模型（OpenAI/Claude/Gemini/本地模型）
核心特点：私有化部署 + 全渠道接入 + 设备能力集成
二、核心架构：Gateway 中心模式
2.1 一张图看懂架构
┌─────────────────────────────────────────────────────────────┐│ 外部消息渠道 ││ WhatsApp │ Telegram │ Slack │ Discord │ Signal │ iMessage │└────────────────────┬────────────────────────────────────────┘ │ 每个渠道只有 1 个连接 ▼┌─────────────────────────────────────────────────────────────┐│ Gateway (控制平面核心) ││ • 维护所有渠道的持久连接 ││ • 管理会话状态 (认证、重连、去重) ││ • 消息路由 (渠道 ↔ 客户端 ↔ AI) ││ • 监听端口：ws://127.0.0.1:18789 │└────────────────────┬────────────────────────────────────────┘ │ WebSocket (内部协议) ┌────────────┼────────────┬────────────┐ ▼ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ CLI │ │macOS │ │iOS/ │ │WebChat │ │ │ │App │ │Android │ │ │ └────────┘ └────────┘ └────────┘ └────────┘ ▲ │ ┌────────┐ │Pi Agent│ (AI 处理引擎) └────────┘2.2 为什么这样设计？
关键问题：为什么所有组件都要通过 Gateway，而不是直接连 WhatsApp/Telegram？
答案有三个：
1️⃣ 会话唯一性
WhatsApp 一个账号只能有一个活跃 WebSocket 会话。如果 CLI、macOS App、iOS App 都直接连 WhatsApp，会互相踢下线。
Gateway 作为单一连接所有者，避免会话冲突。
2. 资源复用
❌ 错误设计： CLI-1 → 独立连 WhatsApp → 3 个 WebSocket CLI-2 → 独立连 WhatsApp → 3 个 WebSocket 结果：会话冲突、内存浪费✅ 正确设计： CLI-1 ─┐ CLI-2 ─┼→ Gateway → 1 个 WhatsApp WebSocket 结果：单一连接、所有客户端共享3. 状态一致性
Gateway 维护：
-
• 消息序列号（去重） -
• 已读状态同步 -
• 联系人/群组缓存 -
• 媒体下载缓存
所有客户端通过订阅 Gateway 事件获得一致视图。
三、客户端角色解析
3.1 Pi Agent：AI 大脑
Pi Agent 是 OpenClaw 的 AI 处理引擎，基于 @mariozechner/pi-ai npm 包实现。
核心职责：
-
• 接收消息 → 调用 LLM → 生成回复 -
• 管理会话上下文 -
• 调用工具（文件读写、代码执行、网络搜索等） -
• 写入长期记忆（Memory）
工作流程：
1. 订阅 Gateway 的 chat 事件2. 收到消息 → 读取会话历史3. 调用 LLM (OpenAI/Claude/Gemini)4. 流式返回回复5. 通过 Gateway 发送到渠道3.2 CLI：命令行遥控器
openclaw 命令行工具，用于：
# 发送消息openclaw message send --to +1234567890 --message "Hello"# 查看渠道状态openclaw channels status# 配置管理openclaw config set gateway.port 18790# 与 AI 对话openclaw agent --message "今天天气怎么样" --thinking high设计亮点：
-
• 无状态设计，启动快（~100ms） -
• 复用 Gateway 已有会话（无需重新认证） -
• 支持 RPC 模式（与脚本集成）
3.3 macOS App：原生控制中心
230+ 个 Swift 文件打造的完整原生应用：
-
• 菜单栏应用：状态显示、快速操作 -
• 设置窗口：渠道配置、模型管理、技能管理 -
• Gateway 管理：本地运行、远程连接、自动发现 -
• 设备能力：摄像头、麦克风、屏幕录制 -
• 系统集成：通知中心、语音唤醒、快捷键
技术栈：SwiftUI + WebSocket + Combine
3.4 iOS/Android：移动节点
移动端作为 Gateway 的Node 客户端，提供：
-
• 消息通知和快速回复 -
• 设备能力（摄像头、GPS、麦克风） -
• Apple Watch 中继（iPhone → Watch） -
• Canvas 渲染（AI 生成的网页 UI）
关键设计：移动端按需连接，Gateway 24 小时在线，不错过消息。
3.5 WebChat：浏览器里的控制台
基于 React 的 Web UI，通过 WebSocket 连接 Gateway：
-
• 聊天历史查看 -
• 消息发送 -
• Canvas 渲染 -
• 配置管理
优势：无需安装，打开浏览器就能用。
四、Telegram 集成深度解析
4.1 多 Bot 支持
一个 Telegram 账号可以创建最多 20 个 Bot，每个 Bot 可以对应不同的 AI Agent：
{ "channels": { "telegram": { "accounts": { "personal": { "botToken": "111111:AAA..." }, "work": { "botToken": "222222:BBB..." }, "support": { "botToken": "333333:CCC..." } } } }, "bindings": [ { "agentId": "main", "match": { "channel": "telegram", "accountId": "personal" } }, { "agentId": "coder", "match": { "channel": "telegram", "accountId": "work" } }, { "agentId": "support", "match": { "channel": "telegram", "accountId": "support" } } ]}使用场景：
-
• @PersonalBot → 日常聊天（轻量模型） -
• @CoderBot → 编程助手（强大模型） -
• @SupportBot → 客服助手（专用模型）
4.2 群聊支持
Telegram Bot 可以被拉入群聊，OpenClaw 支持：
{ "channels": { "telegram": { "groups": { "-1001234567890": { "requireMention": true, // 需要 @Bot 才响应 "groupPolicy": "open", // 群内所有人都可使用 "allowFrom": [] // 或指定用户白名单 } } } }}消息流程：
1. 群成员发送消息2. Bot 接收（需管理员或关闭隐私模式）3. 检查配置（mention/allowlist）4. 转发给 Gateway → Pi Agent5. AI 回复发送到群聊4.3 消息流向详解
Telegram 用户 │ │ 1. 发送消息 ▼Telegram Server │ │ 2. Webhook 推送 │ POST /webhook/telegram ▼Gateway (Telegram Adapter) │ │ 3. 规范化消息 │ 存储到数据库 ▼Gateway 核心 │ │ 4. 广播事件 │ event: chat ▼Pi Agent (WebSocket 订阅) │ │ 5. 调用 LLM ▼Pi Agent │ │ 6. 发送回复请求 │ req: send ▼Gateway │ │ 7. 路由到 Telegram ▼Telegram API │ │ 8. 推送给用户 ▼Telegram 用户 (收到回复)五、Apple Watch 集成
5.1 架构设计
Gateway ──► iPhone (WatchConnectivity) ──► Apple WatchiPhone 作为中继，通过 WatchConnectivity 框架与 Apple Watch 通信。
5.2 核心功能
通知推送
struct OpenClawWatchNotifyParams { var title: String // 标题 var body: String // 正文 var priority: Priority // 优先级 var actions: [WatchAction] // 操作按钮}快速回复
struct WatchReplyDraft { var promptId: String var actionId: String // 用户点击的按钮 var actionLabel: String // 按钮文本}状态查询
struct WatchMessagingStatus { var supported: Bool // 设备是否支持 var paired: Bool // 是否已配对 var appInstalled: Bool // Watch App 是否安装 var reachable: Bool // 是否可达}5.3 使用场景
审批场景：
1. AI 需要用户批准执行命令2. Gateway → iPhone → Apple Watch 推送通知3. Watch 显示："是否允许执行：rm -rf /tmp/*" 按钮：[批准] [拒绝]4. 用户点击"批准"5. Watch → iPhone → Gateway → Pi Agent6. AI 继续执行六、多 Agent 机制
6.1 什么是多 Agent？
OpenClaw 支持创建多个完全隔离的 AI Agent，每个 Agent 有：
-
• 独立的工作区（AGENTS.md/SOUL.md/USER.md） -
• 独立的会话历史 -
• 独立的认证信息（API Keys） -
• 独立的模型配置 -
• 独立的工具权限
6.2 配置示例
{ "agents": { "list": [ { "id": "main", "name": "个人助手", "workspace": "~/.openclaw/workspace-main", "model": "anthropic/claude-sonnet-4-5" }, { "id": "coder", "name": "编程助手", "workspace": "~/.openclaw/workspace-coder", "model": "anthropic/claude-opus-4-6", "tools": { "allow": ["exec", "read", "write"] } }, { "id": "family", "name": "家庭助手", "workspace": "~/.openclaw/workspace-family", "tools": { "deny": ["exec", "write"] } } ] }, "bindings": [ { "agentId": "main", "match": { "channel": "telegram", "accountId": "personal" } }, { "agentId": "coder", "match": { "channel": "telegram", "accountId": "work" } }, { "agentId": "family", "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "家庭群" } } } ]}6.3 路由规则
消息路由遵循最具体优先原则：
-
1. 精确匹配（peer ID） -
2. 群组匹配 -
3. 账号匹配 -
4. 渠道匹配 -
5. 默认 Agent
七、Memory 机制：AI 的长期记忆
7.1 Memory 是什么？
OpenClaw 的 Memory 是基于 Markdown 文件的长期记忆系统。
~/.openclaw/workspace/├── MEMORY.md # 长期记忆└── memory/ ├── 2026-03-13.md ├── 2026-03-14.md # 今天 └── 2026-03-15.md # 明天7.2 两层记忆结构
MEMORY.md（长期记忆）
# 用户偏好- 喜欢简洁的回答- 使用 TypeScript 开发- 工作时间：9:00-18:00# 项目信息- 项目名：OpenClaw- 技术栈：Node.js + TypeScriptmemory/YYYY-MM-DD.md（日常记忆）
# 2026-03-14## 上午- 09:00 用户询问了 Memory 机制- 10:30 帮助调试了 Telegram 配置## 下午- 14:00 讨论了 Apple Watch 集成7.3 记忆工具
AI 可用两个工具访问 Memory：
memory_search（语义搜索）
{ "tool": "memory_search", "params": { "query": "用户喜欢什么开发语言？" }}// 返回{ "snippets": [ { "text": "用户偏好：喜欢 TypeScript 开发", "path": "MEMORY.md", "lineRange": [5, 6], "score": 0.92 } ]}memory_get（精确读取）
{ "tool": "memory_get", "params": { "path": "MEMORY.md", "from": 1, "lines": 20 }}7.4 向量搜索
OpenClaw 支持为 Memory 建立向量索引：
{ "agents": { "defaults": { "memorySearch": { "provider": "openai", "model": "text-embedding-3-small", "hybrid": { "enabled": true }, // BM25 + 向量 "sync": { "watch": true } // 文件监听 } } }}支持的 Embedding 提供商：
-
• OpenAI -
• Gemini（支持多模态：图片/音频） -
• Voyage -
• Mistral -
• Ollama（本地） -
• Local（node-llama-cpp，完全离线）
7.5 实现位置
Memory 机制在 src/memory/ 模块实现：
src/memory/├── manager.ts # MemoryIndexManager (核心)├── manager-sync-ops.ts # 同步操作├── manager-search.ts # 搜索操作├── embeddings.ts # Embedding 提供商├── sqlite.ts # SQLite 存储└── qmd-manager.ts # QMD 后端（实验性）重要：Memory 是 Gateway 的核心功能，Pi Agent 只是使用者（通过工具调用）。
八、桌面端开发建议
8.1 为什么选择 OpenClaw？
如果你要开发桌面端 AI 应用，OpenClaw 提供了完整的 macOS 原生应用：
-
• 230+ Swift 文件 -
• 菜单栏应用 -
• 设置窗口 -
• Gateway 管理 -
• 通知系统集成 -
• 语音唤醒集成 -
• 摄像头/屏幕录制
开发工作量对比：
|
|
|
|---|---|
|
|
|
|
|
|
|
|
|
8.2 快速开始
# 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw# 安装依赖pnpm install# 运行 macOS 应用scripts/restart-mac.sh# 打包应用scripts/package-mac-app.sh九、架构设计亮点总结
9.1 Gateway 中心模式
-
• 单一连接所有者：避免渠道会话冲突 -
• 消息路由枢纽：所有流量经过 Gateway -
• 状态一致性：统一维护会话状态
9.2 客户端 – 服务器分离
-
• Gateway：服务端，24 小时在线 -
• 客户端：CLI/macOS/iOS/WebChat，按需连接 -
• Pi Agent：AI 引擎，作为特殊客户端
9.3 多 Agent 隔离
-
• 独立工作区 -
• 独立会话 -
• 独立认证 -
• 独立配置
9.4 Memory 设计
-
• Markdown 文件（人类可读） -
• 向量索引（语义搜索） -
• 混合搜索（BM25 + 向量） -
• 多后端支持（SQLite/QMD/PostgreSQL）
9.5 设备能力集成
-
• Apple Watch 通知 -
• macOS 原生 UI -
• iOS 设备能力（摄像头/GPS） -
• Canvas 渲染
十、写在最后
OpenClaw 代表了一种新的 AI 助理范式：
-
1. 私有化：数据在自己手里，不依赖大厂 -
2. 全渠道：WhatsApp/Telegram/微信/Slack 统一接入 -
3. 设备集成：手机/手表/电脑无缝协作 -
4. 可扩展：多 Agent、多模型、多工具
它不是另一个 ChatGPT 包装器，而是一个完整的 AI 操作系统。
如果你也想拥有一个真正属于自己的 AI 助理，OpenClaw 值得一试。
参考资料
-
• 项目地址：https://github.com/openclaw/openclaw -
• 文档：https://docs.openclaw.ai -
• 架构文档：https://docs.openclaw.ai/concepts/architecture -
• Memory 机制：https://docs.openclaw.ai/concepts/memory -
• 多 Agent：https://docs.openclaw.ai/concepts/multi-agent
作者：图灵同学 编辑：蔡清华 日期：2026 年 3 月 17 日
如果你觉得这篇文章有帮助，欢迎转发给更多对 AI 自媒体 Agent感兴趣的朋友。