OpenClaw 架构深度解析：如何把 AI 助手搬到你的个人设备上

我们每天都在和 AI 对话------在 ChatGPT 的网页里，在 Copilot 的编辑器里，在各种套壳应用里。但如果你仔细想想，会发现一个尴尬的现实：AI 很聪明，但它什么也做不了。

它不能帮你发一条 WhatsApp 消息，不能替你在 Slack 里回复同事，不能打开你的摄像头拍张照片，不能在你的电脑上跑一个脚本。所有的"智能"都被锁在一个浏览器标签页里。

OpenClaw 试图改变这一点。

它是一个开源项目，由 PSPDFKit 创始人 Peter Steinberger 发起，MIT 协议，截至 2026 年 2 月已有 14,700+ 次提交和 20+ 位活跃贡献者。它的愿景很简单：

"OpenClaw is the AI that actually does things. It runs on your devices, in your channels, with your rules."

不是又一个 ChatGPT 套壳，而是一个运行在你自己设备上的 AI 助手------它能接管你的 WhatsApp、Telegram、Slack、Discord，能调用你手机的摄像头和 GPS，能在 Docker 沙箱里跑脚本，能通过 52 个内置技能操作 GitHub、Notion、1Password......

这篇文章不聊产品体验，只聊架构。我花了一些时间阅读 OpenClaw 的源码，试图回答一个问题：它到底是怎么做到的？

---

---

六大核心模块详解

1. Gateway 网关层 ------ 系统心脏

Gateway 是一个 Node.js 服务，默认监听 ws://127.0.0.1:18789，同时暴露 WebSocket 和 HTTP 两种协议。

启动流程：

startGatewayServer(port, opts)
  ├── 加载配置、迁移旧配置
  ├── 确保认证（Token / 密码 / 设备身份）
  ├── 加载插件 → loadGatewayPlugins()
  ├── 创建通道管理器 → createChannelManager()
  ├── 创建 HTTP/WebSocket 服务
  ├── 绑定 WebSocket 事件处理
  ├── 启动侧车服务（通道、Gmail 监听、钩子等）
  └── 启动 mDNS/Bonjour 局域网发现

Gateway 的核心职责：

• 消息路由：将来自不同通道的消息分发到正确的 Session
• Agent 调度：触发 AI 推理并将结果路由回去
• 插件管理：统一注册和管理通道、工具、钩子
• 安全管控：认证、设备配对、沙箱隔离

2. 通道集成层 ------ 打通 15+ 聊天平台

每个聊天平台作为独立的 Extension 插件，通过 Plugin SDK 注册到 Gateway。

通道插件统一接口：

ChannelPlugin {
  id: string
  gateway.startAccount()    // 启动连接到外部平台
  gateway.stopAccount()     // 停止连接
  outbound.sendText()       // 发送文本
  outbound.sendMedia()      // 发送媒体
  config.isEnabled()        // 是否启用
  capabilities              // 支持的能力（群组、反应、投票等）
}

各平台的底层实现：

平台	底层库	连接方式	投递模式
WhatsApp	@whiskeysockets/baileys	QR 码登录	gateway
Telegram	grammy	Bot Token + Webhook	direct
Slack	@slack/bolt	Bot/User Token	direct
Discord	discord.js	Bot Token	direct
Signal	Signal CLI	本地协议	gateway
iMessage	BlueBubbles	HTTP API	gateway
飞书	@larksuiteoapi/node-sdk	应用凭证	direct

消息流转路径：

用户在 WhatsApp 发消息
  → WhatsApp 插件收到消息
  → dispatchInboundMessage() 分发到网关
  → 路由到对应 Session
  → Agent Runtime 执行推理
  → Agent 生成回复
  → deliverAgentCommandResult()
  → 通过 WhatsApp outbound adapter 发回用户

这里有两种投递模式的设计值得关注：

• gateway 模式：消息经 Gateway 转发，适合没有官方 Bot API 的平台（如 WhatsApp、iMessage）
• direct 模式：插件直接投递到平台 API，减少延迟，适合有完善 Bot API 的平台

3. AI Agent 运行时 ------ 本地推理引擎

OpenClaw 基于 pi-agent（嵌入式 Agent SDK）来运行 AI 推理。

模型发现与选择：

• 通过 pi-model-discovery 自动发现可用模型
• 支持 OpenAI、Anthropic Claude、Google Gemini、AWS Bedrock、本地 LLM（llama.cpp）
• resolveConfiguredModelRef() 解析用户配置
• runWithModelFallback() 支持模型自动降级

Agent 执行流程：

消息进入
  → agentCommand()
  → runEmbeddedPiAgent()
      ├── 加载会话上下文（历史消息）
      ├── 注入 System Prompt + 匹配的 Skills
      ├── 注入可用 Tools
      ├── 调用模型推理
      ├── 模型返回 Tool Call → 执行工具 → 结果回填 → 继续推理
      └── 最终回复 → 广播到 WebSocket / 通道

Session 管理：

• 每个对话有独立的 Session Key：agent:{agentId}:{mainKey}
• Session 持久化到文件系统
• 支持上下文压缩（compaction），避免长对话的 token 溢出

4. 原生应用层 ------ 设备硬件能力的桥梁

原生应用（macOS/iOS/Android）不直接运行 AI，而是作为 Gateway 的远程节点（Node）。

设备配对流程：

1. 用户在 Telegram 输入 /pair
2. device-pair 扩展生成配对码（base64 JSON: url + token）
3. 用户在 iOS App 中粘贴配对码或扫描 QR
4. App 用设备身份通过 WebSocket 连接 Gateway
5. Gateway 广播 device.pair.requested
6. 用户确认 /pair approve
7. Gateway 发放设备 Token，完成持久配对

节点能力调用：

Gateway 可以通过 node.invoke 远程调用原生 App 的硬件能力：

能力	实现方式
摄像头拍照	node.invoke → Camera Handler
屏幕录制	node.invoke → Screen Record
GPS 定位	node.invoke → Location
语音唤醒	Android SpeechRecognizer / iOS Voice Wake
Talk Mode	ElevenLabs TTS + 按键对讲
推送通知	node.event → 本地通知系统
SMS 短信	Android SMS Handler

语音交互实现：

• Voice Wake （Android）：用 SpeechRecognizer 持续监听触发词，检测后提取命令发送到 Gateway
• Talk Mode：Gateway 将 AI 回复通过 ElevenLabs 转为语音流，推送到 App 播放
• PTT 对讲 ：iOS/macOS 通过 talk.ptt.start/stop 命令实现按键对讲

5. Skills & Tools 系统 ------ 让 AI 能"做事"

Skills（技能） 是 OpenClaw 最有特色的设计之一。每个 Skill 是一个包含 SKILL.md 的目录，用自然语言描述用途和工具用法：

# SKILL.md 结构示例
---
name: github
description: Use when user mentions GitHub issues, PRs, or repositories
metadata:
  openclaw:
    requires:
      bins: [gh]
---
## Instructions
Use the `gh` CLI tool to interact with GitHub...

AI 在推理时根据用户意图自动匹配 Skill，读取对应的 SKILL.md 获取工具使用方法。这是一种优雅的声明式能力注入机制。

Tools（工具）类型：

类型	示例	执行位置
内置工具	read, write, edit, bash	gateway / sandbox
插件工具	voice_call, canvas, memory_search	gateway
浏览器工具	Playwright 自动化	sandbox 容器
节点工具	camera, location, sms	远程设备节点

工具策略管控：

通过 Profile（minimal / coding / messaging / full）和 allow/deny 列表精细控制工具权限：

{
  "tools.profile": "coding",
  "tools.deny": ["voice_call"],
  "agents.sandbox.tools.allow": ["read", "write", "bash"]
}

6. Docker 沙箱 ------ 安全执行环境

对于不信任的操作，OpenClaw 用 Docker 容器隔离执行：

ensureSandboxContainer(session)
  → 为每个 session 创建独立容器
  → 同步 workspace 文件
  → 同步 Skills
  → 在容器内执行命令
  → 限制内存、CPU、网络

浏览器自动化也可以跑在隔离的浏览器容器中（Playwright + 可选 VNC），确保 AI 操作网页时不影响主机环境。

---

对开发者和团队的参考价值

1. Gateway-as-Hub 架构模式

OpenClaw 最核心的架构决策是本地 Gateway 作为统一中枢。这个模式适用于任何需要整合多个外部服务的场景：

• 企业内部工具集成：用 Gateway 统一对接钉钉、飞书、企业微信等多个 IM
• IoT 智能家居：本地 Hub 管理多个设备协议（Zigbee、BLE、WiFi）
• API 聚合网关：统一管理多个 AI Provider 的调用和降级

关键设计要点：

• WebSocket 作为主协议，HTTP 作为兼容层
• 插件化架构，核心精简，能力外置
• 统一的消息路由和 Session 管理

2. 插件化通道抽象

OpenClaw 对 15+ 聊天平台的统一抽象非常值得借鉴。ChannelPlugin 接口设计了清晰的生命周期：

注册 → 配置 → 启动 → 消息收发 → 停止

参考场景：

• 构建多渠道客服系统
• 统一通知推送服务
• 跨平台消息转发 Bot

3. SKILL.md ------ 声明式能力注入

用 Markdown 文件声明 AI 技能，而不是硬编码 Function Calling，这是一个非常聪明的设计：

优势：

• 非开发者也能编写和修改技能
• 热加载，无需重启服务
• 自然语言描述意图，AI 自行匹配
• 技能可以独立分发和共享（ClawHub 市场）

参考场景：

• 企业知识库 + AI 助手：将 SOP 写成 Skill，AI 自动匹配执行
• 运维自动化：将运维手册转为 Skill，AI 根据告警自动处理
• 教育领域：将教学场景写成 Skill，AI 辅助答疑

4. Node 远程调用模式

通过 WebSocket + node.invoke 远程调用设备硬件能力的设计，解决了一个核心问题：AI 在服务端运行，但硬件在客户端。

参考场景：

• 远程协助工具：AI 远程调用用户设备的摄像头、屏幕
• 工业 IoT：AI 远程调用传感器和执行器
• 分布式测试：远程调用多台设备执行测试

5. 安全分层设计

OpenClaw 的安全设计是"强默认 + 显式开放"：

DM 配对验证 → Token 认证 → 工具策略管控 → Docker 沙箱隔离 → 命令执行审批

参考场景：

• 任何需要让 AI 执行实际操作的系统都应参考这套分层安全模型
• 特别是 Agent 类产品，必须有明确的权限边界和审批机制

6. Monorepo + Extension 工程化

OpenClaw 用 pnpm workspace 管理 70+ 个包，包括核心、UI、38 个扩展、52 个技能、3 个原生应用。

工程化实践：

• tsdown（基于 esbuild）构建，速度极快
• oxlint + oxfmt 代替 ESLint + Prettier，性能更好
• 5 套 Vitest 配置（unit / e2e / live / gateway / extensions）
• 严格的 PR 规范：单 PR 单议题，不超过 5000 行

---

总结

OpenClaw 不是又一个 ChatGPT 套壳，而是一套完整的本地 AI 助手基础设施。它的核心创新在于：

1. 本地 Gateway 中枢：所有能力通过一个本地服务统一调度
2. 通道抽象层：一套接口打通 15+ 聊天平台
3. 声明式技能系统：用 Markdown 描述 AI 能力，而非硬编码
4. 设备节点模型：让 AI 能远程调用手机/电脑的硬件能力
5. 安全分层：从认证到沙箱的完整安全链路

这套设计为"如何在个人设备上运行一个真正有用的 AI 助手"提供了一个高质量的开源参考实现。无论你是想构建自己的 AI 助手，还是设计多通道集成系统，OpenClaw 的架构都值得深入研究。

---

项目地址：github.com/openclaw/op...