OpenClaw 架构文档

关注

原创最新推荐文章于 2026-08-14 15:32:24 发布 1.3k 阅读 AI 写同款· GEO 优化 ›

OpenClaw 完整命令文档（2026.3.13 最新版）本文档为OpenClaw 2026.3.13通用版使用指南，包含核心命令大全。主要内容包括：1）基础安装/升级/卸载命令；2）ClawHub扩展安装命令（支持飞书/钉钉/企微等平台连接）；3）Skills技能安装命令（实现聊天/搜索/记忆等功能）；4）飞书机器人授权与配对命令；5）启动运行与配置检查命令；6）工作区与记忆管理命令；7）插件安全设置命令；8）调试日志命令；9）飞书机器人一键部署简化流程。文档特别强调飞书机器人部署需feishu扩展+对应技能+用户授权的完整配置，所有命令均需在终端执行，安装后需阅读详情

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 加载顺序

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

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 代理与各种消息渠道，实现智能自动化和交互。

收录于

人工智能

标签

#架构 #人工智能

OpenClaw配置教程文档 OpenClaw是一款开源的本地优先AI代理与自动化平台，允许用户在自有设备上部署个人AI助手，支持多渠道通信与大语言模型深度集成[1†]。本教程针对Linux系统环境，提供完整的安装配置指南，涵盖系统要求、安装步骤、配置流程及常见问题解决方案，特别适合AI应用场景部署。核心特点：本地优先设计：数据存储在本地，确保隐私可控[5†]多渠道支持：集成WhatsApp、Telegram、Slack、Discord、Google Chat等多种通讯平台[14†]持久记忆与主动执行。阅读详情

OpenClaw 架构文档

OpenClaw 架构文档

1. 概述

1.1 核心功能

1.2 架构概览

2. 核心组件

2.1 Gateway（网关）

2.1.1 网络模型

2.1.2 协议规范

2.2 通道（Channels）

2.2.1 WhatsApp 集成

2.2.2 Telegram 机器人

2.2.3 Discord 机器人

2.2.4 iMessage 集成

2.2.5 Mattermost 机器人

2.3 AI 代理系统

2.3.1 Pi 代理集成

2.3.2 多代理路由

2.3.3 会话管理

2.4 节点（Nodes）

2.4.1 功能

2.4.2 节点主机

2.5 工具系统

2.5.1 核心工具集

2.5.2 工具策略

2.6 技能系统（Skills）

2.6.1 加载顺序

2.6.2 技能格式

2.7 沙箱系统

2.7.1 沙箱模式

2.7.2 作用域

2.7.3 工作区访问

3. 配置管理

3.1 配置文件

3.2 主要配置部分

3.2.1 代理配置

3.2.2 通道配置

3.2.3 绑定规则

4. 安全特性

4.1 访问控制

4.2 认证机制

4.3 执行批准

4.4 安全审计

5. 部署和运维

5.1 安装要求

5.2 启动向导

5.3 服务管理

5.4 监控和健康检查

6. 扩展性

6.1 插件系统

6.2 自定义技能

7. 最佳实践

7.1 安全最佳实践

7.2 性能最佳实践

7.3 运维最佳实践

8. 故障排除

8.1 常见问题

8.2 诊断命令

9. 总结

相关推荐