OpenClaw 架构深度解析：打造属于你的个人 AI 助手

目录

“EXFOLIATE! EXFOLIATE!” —— 一只太空龙虾（可能）

引言

在 AI 助手遍地开花的今天，大多数产品都将用户数据托管在云端，通过 API 提供服务。但如果你想要一个真正属于自己的 AI 助手——它运行在你自己的设备上，连接你常用的通讯工具，执行你编写的自动化任务——那么 OpenClaw 可能是你一直在寻找的答案。

经过几天的深入研究和源码阅读，我将在这篇文章中带你全面了解 OpenClaw 的架构设计、核心组件以及它如何实现”本地优先、隐私至上”的 AI 助手体验。

OpenClaw 是什么？

OpenClaw 是一个自托管的个人 AI 助手网关，由 Pi 背后的团队开发。它的核心理念可以用一句话概括：

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

主要特性

• 多平台通讯集成：WhatsApp、Telegram、Slack、Discord、Signal、iMessage、飞书、LINE 等 20+ 个渠道
• 本地优先架构：Gateway 运行在你的设备上（macOS、Linux、Windows WSL2）
• 多代理支持：可同时运行多个独立的 AI 代理
• 丰富的工具生态：浏览器控制、定时任务、文件系统操作、Canvas 可视化
• 移动端配套：iOS/Android 节点应用，支持语音唤醒和连续对话
• Skill 系统：可扩展的技能系统，通过 SKILL.md 定义新的能力

架构概览

OpenClaw 采用分层架构设计，核心是 Gateway（网关），所有组件都围绕它构建：

┌─────────────────────────────────────────────────────────────┐
│                    Messaging Channels                        │
│  WhatsApp  Telegram  Slack  Discord  Signal  iMessage      │
│  Feishu    LINE     Matrix  WebChat   ...                   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     Gateway (控制平面)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Session    │  │   Agent     │  │    Tools    │         │
│  │  Manager    │  │   Runtime   │  │   (exec/    │         │
│  │             │  │  (pi-mono)  │  │  browser/   │         │
│  └─────────────┘  └─────────────┘  │  cron/...)  │         │
│                                    └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Skills    │  │    Cron     │  │   Canvas    │         │
│  │   Registry  │  │   Jobs      │  │    Host     │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │   CLI    │   │  Web UI  │   │   Node   │
    │ (终端)   │   │(控制面板)│   │ (移动端) │
    └──────────┘   └──────────┘   └──────────┘

核心设计原则

1. Single Gateway：一个 Gateway 实例控制所有通讯渠道，避免 Baileys/WhatsApp 等库的多实例冲突
2. WebSocket 长连接：所有客户端通过 WebSocket 与 Gateway 通信，支持实时事件推送
3. 本地优先：默认绑定 127.0.0.1:18789，保持数据本地
4. 显式安全：所有高风险操作（如执行命令）需要显式配置，而非默认开放

核心组件详解

1. Gateway（网关）

Gateway 是整个系统的控制平面，负责：

• 渠道管理：维护与 WhatsApp、Telegram 等平台的连接
• 消息路由：根据配置将消息路由到不同的 Agent
• 会话管理：维护会话状态、历史记录、上下文
• 工具执行：管理工具的执行和安全策略

Gateway 使用 TypeBox 定义协议 Schema，确保类型安全：

// WebSocket 协议结构
{type: "req", id, method, params} → {type: "res", id, ok, payload|error}
{type: "event", event, payload, seq?, stateVersion?}

2. Agent Runtime（代理运行时）

OpenClaw 使用 pi-mono 的嵌入式运行时，但会话管理和工具调用完全由 OpenClaw 自己控制。

Workspace（工作区） 是 Agent 的核心概念：

~/.openclaw/workspace/
├── AGENTS.md      # 操作指令和"记忆"
├── SOUL.md        # 人设、边界、语气
├── TOOLS.md       # 用户维护的工具说明
├── BOOTSTRAP.md   # 首次运行仪式（完成后删除）
├── IDENTITY.md    # Agent 名称/表情符号
└── USER.md        # 用户画像

这些文件在会话启动时自动注入到 Agent 上下文中，成为系统提示词的一部分。

3. Skills 系统

Skills 是 OpenClaw 的扩展机制，采用 AgentSkills 兼容格式：

---
name: weread
description: "微信读书 AI 总结助手"
metadata:
  { "openclaw": { "emoji": "📚", "requires": { "bins": ["python3"] } } }
---

# 微信读书助手

## When to Use

当用户询问微信读书相关问题时使用此 skill。

## Commands

```bash
python3 /path/to/weread_books.py --list

Skills 的加载优先级：

Workspace Skills (最高) → ~/.openclaw/skills → Bundled Skills (最低)

### 4. Tools（工具）

OpenClaw 提供丰富的内置工具：

| 工具 | 功能 | 安全级别 |
|------|------|----------|
| `read` / `write` / `edit` | 文件系统操作 | 受 workspace 限制 |
| `exec` | 执行 shell 命令 | 需要 safeBins 配置 |
| `browser` | 浏览器控制（CDP） | 独立 Chrome 实例 |
| `cron` | 定时任务 | 可能影响持久状态 |
| `canvas` | 可视化界面 | 沙盒内运行 |
| `sessions_spawn` | 派生子代理 | 可能创建后台任务 |

工具安全通过 **Profile** 系统控制：

- `minimal`：仅基本工具
- `messaging`：适合消息处理
- `coding`：开发相关工具
- `full`：全部工具（需谨慎使用）

### 5. Channels（通讯渠道）

OpenClaw 支持 20+ 个通讯渠道，每个渠道都有专门的适配器：

| 渠道 | 库/协议 | 特点 |
|------|---------|------|
| WhatsApp | Baileys | 最稳定的 WhatsApp 库 |
| Telegram | grammY | 功能丰富的 Bot API |
| Slack | Bolt | 企业级集成 |
| Discord | discord.js | 社区友好 |
| Signal | signal-cli | 隐私优先 |
| Feishu | 官方 API | 飞书生态 |

**安全机制**：
- DM 配对（`dmPolicy: pairing`）：未知用户需要配对码才能与 Bot 对话
- 群组提及（`requireMention`）：群组中需要 @Bot 才会响应
- 白名单（`allowFrom`）：限制允许的用户/群组

## 深入：消息流转机制

当一条消息从 WhatsApp 到达时，处理流程如下：

```mermaid
sequenceDiagram
    participant User
    participant WhatsApp
    participant Gateway
    participant Agent
    participant Tools

    User->>WhatsApp: 发送消息
    WhatsApp->>Gateway: Baileys 事件
    Gateway->>Gateway: 1. 验证配对状态
    Gateway->>Gateway: 2. 解析 sessionKey
    Gateway->>Gateway: 3. 应用群组策略
    Gateway->>Agent: 4. 创建/恢复会话
    Agent->>Agent: 5. 构建系统提示词
    Agent->>Gateway: 6. 请求工具调用
    Gateway->>Tools: 7. 执行工具（如 exec）
    Tools-->>Gateway: 返回结果
    Gateway-->>Agent: 传递工具输出
    Agent-->>Gateway: 生成回复
    Gateway-->>WhatsApp: 发送响应
    WhatsApp-->>User: 显示消息

Session Key 的奥秘

OpenClaw 使用 sessionKey 来路由消息到正确的会话：

agent:<agentId>:<channel>:<context>

例如：
- agent:main:main              # 主会话
- agent:main:whatsapp:direct   # WhatsApp 私信隔离
- agent:main:slack:channel     # Slack 频道隔离

通过 session.dmScope 可以配置 DM 的隔离级别：

• main：所有 DM 进入主会话（默认）
• per-channel-peer：每个渠道+用户独立会话
• per-account-channel-peer：多账号场景

安全架构：信任边界与执行控制

OpenClaw 采用个人助手信任模型，而非多租户隔离：

默认假设：Gateway 运行在一个受信任的操作员边界内。

三层安全防线

1. 网络层：

   • 默认绑定 127.0.0.1（仅本地）
   • 支持 Token/Password 认证
   • 设备配对（本地自动批准，远程需显式批准）

2. 渠道层：

   • DM 配对策略（pairing/allowlist/open/disabled）
   • 群组提及要求
   • 白名单控制

3. 工具层：

   • tools.profile 控制可用工具集
   • tools.exec.safeBins 限制可执行的二进制文件
   • tools.exec.ask 配置执行前确认（off/on-miss/always）
   • 沙盒模式（Docker 隔离）

为什么 exec 工具需要特殊配置？

在 OpenClaw 2026.3.8 中，exec 工具默认不会将 bash/python 等解释器列入 safeBins，因为：

interpreter/runtime binaries in safeBins are unsafe without explicit hardened profiles

这是有意为之的安全设计——执行任意代码的能力需要显式启用。

扩展：Plugin 系统与 MCP

OpenClaw 的架构鼓励通过 Plugin 扩展功能：

• Extensions：位于 extensions/ 目录，如 Feishu、Matrix、Mattermost
• NPM 包：可独立发布和安装的插件
• MCP 支持：通过 mcporter 桥接 MCP 服务器

MCP（Model Context Protocol）的设计理念与 OpenClaw 的 Skill 系统类似，都旨在标准化 AI 工具的接入方式。

实际部署模式

模式一：本地开发工作站

# 安装
npm install -g openclaw@latest

# 初始化
openclaw onboard --install-daemon

# 启动 Gateway
openclaw gateway --port 18789

适合：开发者、隐私敏感用户

模式二：VPS + Tailscale

# VPS 上运行 Gateway，绑定 loopback
openclaw gateway --bind loopback --port 18789

# 本地通过 Tailscale 访问
# macOS/iOS/Android 节点自动发现

适合：需要随时随地访问的用户

模式三：Docker 部署

docker run -d \
  -v ~/.openclaw:/root/.openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

适合：服务器环境、需要隔离的场景

与微信读书 Skill 的实战经验

在我尝试为微信读书创建 Skill 的过程中，深入理解了 OpenClaw 的工作机制：

遇到的挑战

1. 工具未注入：默认配置下 exec 工具虽然启用，但解释器（python3/bash）需要显式配置 safeBins
2. System Prompt 结构：Skills 只是给 LLM 的”说明书”，真正的工具定义由 Gateway 控制
3. 超时问题：本地模型调用可能超时，需要合理设置 timeoutSeconds

最终方案

对于需要执行本地脚本的场景，目前最稳定的方式是：

1. Shell Wrapper：通过 ~/.bashrc 定义函数，绕过 OpenClaw 的工具系统
2. Feishu Bot：使用 Webhook 触发，由 Bot 直接执行命令
3. 等待修复：关注 GitHub Issues 等待工具配置的改进

总结：OpenClaw 的独特价值

在这个 AI 服务日益集中化的时代，OpenClaw 提供了一种去中心化的替代方案：

特性	云端 AI 服务	OpenClaw
数据隐私	数据上传至服务商	数据本地保留
定制化	受限于平台能力	完全可扩展（Skills/Plugins）
集成能力	封闭生态	开放渠道（20+ 个通讯平台）
成本	API 调用费用	自托管成本
可靠性	依赖服务商	完全自主控制

OpenClaw 最适合：

• 隐私优先：不愿将敏感对话上传至云端的用户
• 重度定制：需要深度集成特定工具和流程的用户
• 多平台：横跨多个通讯渠道管理消息的用户
• 技术爱好者：愿意投入时间自托管和定制的开发者

参考资源

• OpenClaw 官网
• 官方文档
• GitHub 仓库
• Discord 社区
• AgentSkills 规范

---

本文基于 OpenClaw 2026.3.8 版本源码分析撰写。项目迭代迅速，部分细节可能随版本更新而变化。

文章作者：阿文

文章链接： https://www.awen.me/post/83c46c68.html

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 阿文的博客！