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

月谈AI
0 阅读8分钟

我们每天都在和 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 的源码，试图回答一个问题：它到底是怎么做到的？

openclaw-architecture.png

六大核心模块详解

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/baileysQR 码登录gateway
TelegramgrammyBot Token + Webhookdirect
Slack@slack/boltBot/User Tokendirect
Discorddiscord.jsBot Tokendirect
SignalSignal CLI本地协议gateway
iMessageBlueBubblesHTTP APIgateway
飞书@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 ModeElevenLabs 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, bashgateway / sandbox
插件工具voice_call, canvas, memory_searchgateway
浏览器工具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…

avatar
文章
阅读
粉丝