OpenClaw 架构文档

1. 概述

OpenClaw 是一个跨平台的消息网关，用于连接 AI 代理与各种消息服务，如 WhatsApp、Telegram、Discord、iMessage 等。它提供了一个统一的接口来处理来自不同渠道的消息，并将其路由到 AI 代理进行处理。

1.1 核心功能

• 多渠道支持: 支持 WhatsApp、Telegram、Discord、iMessage、Mattermost 等
• AI 代理桥接: 集成了 Pi 编码代理（RPC 模式）与工具流
• 会话管理: 支持直接聊天和群组聊天，可配置提及模式
• 媒体支持: 支持图像、音频、文档的发送和接收
• 节点支持: 支持 iOS 和 Android 节点，提供 Canvas 表面、摄像头等功能
• 安全控制: 提供订阅认证、授权和访问控制

1.2 架构概览

WhatsApp / Telegram / Discord / iMessage (+ plugins)
 │
 ▼
 ┌───────────────────────────┐
 │ Gateway                   │ ws://127.0.0.1:18789 (loopback-only)
 │ (single source)           │
 │                           │ http://<gateway-host>:18793
 │                           │ /__openclaw__/canvas/ (Canvas host)
 └───────────┬───────────────┘
             │
             ├─ Pi agent (RPC)
             ├─ CLI (openclaw …)
             ├─ Chat UI (SwiftUI)
             ├─ macOS app (OpenClaw.app)
             ├─ iOS node via Gateway WS + pairing
             └─ Android node via Gateway WS + pairing

2. 核心组件

2.1 Gateway（网关）

Gateway 是 OpenClaw 的核心组件，是一个长期运行的进程，负责：

• 拥有单一的 WhatsApp Web 会话和其他渠道连接
• WebSocket 控制平面（默认端口 18789）
• HTTP 接口（控制 UI、钩子、A2UI）
• 事件和请求/响应协议处理
• 与 AI 代理的通信

2.1.1 网络模型

• 单主机推荐: 每台主机建议只运行一个网关
• 循环回路优先: Gateway WS 默认为 ws://127.0.0.1:18789
• 节点连接: 通过 WebSocket 连接到网关（LAN/tailnet/SSH 需要）
• Canvas 主机: HTTP 文件服务器，端口 18793，服务于 /openclaw/canvas/

2.1.2 协议规范

• 客户端首次请求必须包含连接帧：

  {
    "type": "req",
    "id": "...",
    "method": "connect",
    "params": {
      "minProtocol": "...",
      "maxProtocol": "...",
      "client": {
        "id": "...",
        "displayName": "...",
        "version": "...",
        "platform": "...",
        "caps": {},
        "auth": "..."
      }
    }
  }
  

• 网关响应：

  {
    "type": "res",
    "id": "...",
    "ok": true,
    "payload": {
      "type": "hello-ok",
      "snapshot": { ... }
    }
  }
  

2.2 通道（Channels）

OpenClaw 支持多种消息通道：

2.2.1 WhatsApp 集成

• 使用 Baileys 实现 WhatsApp Web 协议
• 支持直接消息和群组消息
• 支持媒体文件传输

2.2.2 Telegram 机器人

• 通过 grammY 支持 DM 和群组
• 支持原生命令注册

2.2.3 Discord 机器人

• 通过 channels.discord.js 支持 DM 和公会频道
• 支持原生命令和权限管理

2.2.4 iMessage 集成

• 本地 imsg CLI 集成（macOS）
• 支持附件和多媒体

2.2.5 Mattermost 机器人

• 插件形式提供
• 支持机器人令牌和 WebSocket 事件

2.3 AI 代理系统

2.3.1 Pi 代理集成

• RPC 模式运行
• 支持工具流
• 内置编码助手

2.3.2 多代理路由

• 可以运行多个隔离的代理
• 每个代理可以有不同的工作区、沙箱配置
• 基于绑定规则路由消息

2.3.3 会话管理

• 直接聊天：默认折叠为共享主会话
• 群组聊天：隔离处理
• 支持每会话、每代理或共享沙箱范围

2.4 节点（Nodes）

节点是连接到网关的配套设备（macOS/iOS/Android/无头模式）：

2.4.1 功能

• 通过 WebSocket 连接到网关
• 暴露命令表面（canvas.、camera.、system.*）
• 支持 Canvas 快照和控制
• 支持摄像头拍摄和视频录制
• 支持屏幕录制和位置获取

2.4.2 节点主机

• 允许远程执行系统命令
• 支持远程节点主机设置
• 执行批准机制

2.5 工具系统

2.5.1 核心工具集

• exec: 在工作区内运行 shell 命令
• process: 管理后台 exec 会话
• web_search: 使用 Brave Search API 搜索网络
• web_fetch: 从 URL 获取可读内容
• browser: 控制专用浏览器
• canvas: 驱动节点 Canvas
• nodes: 发现和目标配对节点
• image: 分析图像
• message: 发送消息和频道操作
• cron: 管理定时任务
• gateway: 重启或应用更新到网关
• sessions_*: 会话管理工具
• agents_list: 列出可用代理

2.5.2 工具策略

• 全局允许/拒绝: 通过 tools.allow / tools.deny 控制
• 工具配置文件: minimal、coding、messaging、full
• 按提供商限制: 为特定提供商进一步限制工具
• 工具组: 支持 group:* 条目的简写

2.6 技能系统（Skills）

OpenClaw 使用 AgentSkills 兼容的技能文件夹：

2.6.1 加载顺序

1. 工作区技能: <workspace>/skills（最高优先级）
2. 管理/本地技能: ~/.openclaw/skills
3. 捆绑技能: 随安装包分发（最低优先级）

2.6.2 技能格式

---
name: skill-name
description: Skill description
metadata:
 {
   "openclaw":
   {
     "requires": { "bins": ["binary"], "env": ["ENV_VAR"], "config": ["browser.enabled"] },
     "primaryEnv": "ENV_VAR",
     "os": ["darwin", "linux", "win32"]
   }
 }
---
# 技能说明和指令

2.7 沙箱系统

2.7.1 沙箱模式

• "off": 不使用沙箱
• "non-main": 仅非主会话使用沙箱
• "all": 所有会话使用沙箱

2.7.2 作用域

• "session": 每个会话一个容器（默认）
• "agent": 每个代理一个容器
• "shared": 所有沙箱会话共享一个容器

2.7.3 工作区访问

• "none": 工具看到沙箱工作区（默认）
• "ro": 以只读方式挂载代理工作区
• "rw": 以读写方式挂载代理工作区

3. 配置管理

3.1 配置文件

• 位置: ~/.openclaw/openclaw.json
• 格式: JSON5（支持注释和尾随逗号）
• 验证: 严格验证，无效配置会导致网关拒绝启动

3.2 主要配置部分

3.2.1 代理配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["openai/gpt-4o"]
      },
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace-main",
        "groupChat": {
          "mentionPatterns": ["@openclaw"]
        }
      }
    ]
  }
}

3.2.2 通道配置

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "telegram": {
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"]
    }
  }
}

3.2.3 绑定规则

{
  "bindings": [
    {
      "agentId": "home",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    },
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "biz"
      }
    }
  ]
}

4. 安全特性

4.1 访问控制

• 直接消息策略: pairing、allowlist、open、disabled
• 群组策略: allowlist、open、disabled
• 配对系统: 未知发件人获得配对代码，需批准后才能处理消息

4.2 认证机制

• 网关认证: 需要令牌或密码（默认启用）
• Tailscale 集成: 支持 Tailscale Serve 身份验证
• 受信任代理: 支持反向代理配置

4.3 执行批准

• 主机执行: 工具批准机制防止未授权命令执行
• 节点执行: macOS 节点支持执行批准设置
• 沙箱执行: 限制在隔离环境中运行

4.4 安全审计

• 安全审计命令: openclaw security audit
• 深度检查: openclaw security audit --deep
• 自动修复: openclaw security audit --fix

5. 部署和运维

5.1 安装要求

• 运行时要求: Node ≥ 22
• 推荐: pnpm（源码构建时）
• 可选: Brave Search API 密钥用于网络搜索

5.2 启动向导

# 安装 CLI
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon

# 启动网关
openclaw gateway --port 18789

5.3 服务管理

• 状态检查: openclaw gateway status
• 安装服务: openclaw gateway install
• 停止/重启: openclaw gateway stop/restart
• 日志查看: openclaw logs --follow

5.4 监控和健康检查

• 健康检查: openclaw health
• 状态报告: openclaw status --all
• 安全审计: openclaw security audit

6. 扩展性

6.1 插件系统

• 插件安装: openclaw plugins install
• 插件配置: 通过配置文件管理
• 工具注册: 插件可以注册额外的工具

6.2 自定义技能

• 技能注册: 通过 SKILL.md 文件
• 条件加载: 基于环境和依赖项
• 动态刷新: 支持运行时技能更新

7. 最佳实践

7.1 安全最佳实践

• 保持直接消息锁定（配对/允许列表）
• 优先使用提及门控群组；避免在公共房间中"始终开启"机器人
• 将敏感工具限制为可信代理或明确允许列表
• 运行现代、指令强化的模型用于任何具有工具的机器人

7.2 性能最佳实践

• 使用沙箱减少攻击面
• 合理配置会话历史限制
• 适当使用缓存和重试策略
• 监控资源使用情况

7.3 运维最佳实践

• 定期备份配置和会话数据
• 使用版本控制管理配置文件
• 设置适当的日志级别和保留策略
• 定期运行安全审计

8. 故障排除

8.1 常见问题

• 无法连接到网关: 检查端口和认证设置
• 通道连接失败: 验证凭据和网络连接
• 工具调用失败: 检查工具策略和批准设置

8.2 诊断命令

• openclaw status --all: 全面的状态报告
• openclaw health: 健康检查
• openclaw logs: 查看日志
• openclaw doctor: 诊断和修复

9. 总结

OpenClaw 是一个功能强大且灵活的 AI 代理消息网关，提供了对多种消息平台的支持、灵活的配置选项和强大的安全特性。其模块化架构允许扩展和定制，使其适合各种用例，从个人助理到企业级部署。

通过合理的配置和安全措施，OpenClaw 可以安全可靠地连接 AI 代理与各种消息渠道，实现智能自动化和交互。