Skip to content

第一部分:认识 OpenClaw

本部分将带你全面了解 OpenClaw 的核心定位、能力边界和支持的运行环境,为后续实战操作打下理论基础。


第 1 章:OpenClaw 是什么

1.1 项目定位:多渠道 AI 智能体网关平台

OpenClaw 是一个开源的多渠道 AI 智能体网关平台(Multi-Channel AI Agent Gateway),它的核心使命是:

将强大的 AI 智能体能力,无缝接入到你日常使用的各种消息平台中。

想象一下这样的场景:

  • 在 WhatsApp 上问 AI 助手帮你查询天气、预订航班
  • 在 Discord 服务器里让机器人自动整理会议纪要
  • 在 Telegram 群组中让 AI 定时推送新闻摘要
  • 在 Slack 工作区里让智能体执行代码、操作浏览器

传统上,这些需求要么依赖各平台零散的 Bot 服务,要么需要为每个平台单独开发集成。OpenClaw 的创新之处在于:

  1. 统一网关架构:一个 OpenClaw Gateway 实例可以同时管理 20+ 个消息平台的接入
  2. 智能体优先设计:内置完整的 AI Agent 运行时,支持工具调用、记忆系统、会话管理
  3. 多智能体并行:可以为不同场景配置独立的智能体(如个人助手、工作团队机器人、公开服务号)
  4. 开放生态:兼容 AgentSkills 技能系统、支持自定义工具、提供 RPC/HTTP API

官方定义(来自 concepts/architecture 文档):

"OpenClaw is designed around a single long-lived Gateway that owns all messaging surfaces and maintains persistent connections to your channels."

OpenClaw 不仅仅是一个"聊天机器人框架",更是一个可编程的 AI 操作系统前端,让你的 AI 智能体能够在真实世界的消息平台上自主工作。


1.2 核心能力概览

统一接入 20+ 消息平台

OpenClaw 支持市面上几乎所有主流消息平台,包括但不限于:

平台类别支持的平台配对方式
即时通讯WhatsApp、Telegram、Signal、iMessageQR 码 / Bot Token / BlueBubbles
企业协作Slack、Microsoft Teams、Google Chat、MattermostOAuth / Bot Token
社区社交Discord、Matrix、IRCBot Token / 账号登录
国际化平台LINE、Zalo、Feishu(飞书)平台 API
开放协议Email(IMAP/SMTP)、SMS凭据配置

重点特性

  • 多账号支持:同一平台可以登录多个账号(如两个 WhatsApp 号、三个 Telegram Bot)
  • 群组与私聊分离策略:细粒度控制机器人在群聊中的行为(如仅在被 @ 时响应)
  • 白名单与配对机制:默认安全策略,防止未授权用户滥用

内置 AI 智能体运行时(基于 pi-mono)

OpenClaw 的智能体引擎基于 pi-mono(Anthropic 内部的 AI Agent 框架),提供:

  1. 工具调用(Tool Use):智能体可以执行 Shell 命令、操作文件、调用 API
  2. 浏览器自动化:托管隔离的 Chromium 实例,智能体可以像人类一样浏览网页、点击按钮、填写表单
  3. 记忆系统:双层记忆架构(日志层 + 长期记忆),支持向量语义搜索
  4. 会话管理:灵活的会话作用域(按发送者、按群组、按渠道隔离),自动压缩与重置
  5. 多模态支持:处理文本、图片、文件,输出格式化消息(Markdown、代码块)

与传统 Chatbot 框架的区别

特性传统框架(如 BotPress)OpenClaw
智能体能力需要外接 AI 模型内置完整 Agent 运行时
工具执行需要手动编写插件原生支持 50+ 工具,动态注册
记忆系统通常基于数据库文件系统 + 向量检索
浏览器自动化需要集成 Puppeteer 等内置托管浏览器
沙箱安全不提供Docker 容器隔离

多智能体并行与路由

OpenClaw 支持在同一 Gateway 内运行多个完全隔离的智能体,每个智能体拥有:

  • 独立的工作区(Workspace)
  • 独立的认证配置(API Keys)
  • 独立的会话存储
  • 独立的工具策略和沙箱配置

路由规则(优先级从高到低):

  1. Peer 匹配:特定联系人或群组 ID 绑定到特定智能体
  2. Guild/Team 匹配:Discord 服务器、Slack 工作区级别绑定
  3. Account 匹配:消息账号级别绑定
  4. Channel 匹配:渠道类型级别绑定(如所有 WhatsApp 消息走智能体 A)
  5. 默认智能体:兜底规则

实战场景举例

  • 个人 WhatsApp 号码 → 智能体 A(全权限,可执行命令)
  • 家庭群组 WhatsApp → 智能体 B(只读沙箱,仅提供信息服务)
  • 公司 Slack 工作区 → 智能体 C(专用工作助手,访问内部工具)
  • 开放 Telegram 频道 → 智能体 D(最小权限,禁用敏感工具)

工具执行、浏览器自动化、定时任务

工具系统(Tools)

OpenClaw 内置 50+ 工具,分为以下类别:

类别代表工具用途
执行类execapply_patch执行 Shell 命令、修改文件
信息类web_searchweb_fetch搜索网页、抓取内容
浏览器类browsercanvas自动化浏览器操作
会话类sessions_spawnsessions_send子会话管理、智能体间通信
消息类message跨渠道发送消息
自动化类crongateway定时任务、网关控制
记忆类memory_searchmemory_get语义搜索记忆

工具策略:可以通过白名单/黑名单精细控制智能体可用的工具:

json
{
  "tools": {
    "allow": ["group:fs", "group:messaging"],  // 允许文件系统和消息工具
    "deny": ["exec"]  // 禁止执行命令
  }
}

浏览器自动化(Browser Automation)

OpenClaw 提供两种浏览器控制模式:

  1. 托管浏览器(推荐):OpenClaw 启动隔离的 Chromium 实例,完全由智能体控制
  2. Chrome 扩展中继:复用你已有的浏览器,通过扩展桥接

快速示例

bash
# 启动托管浏览器
openclaw browser --browser-profile openclaw start

# 打开网页
openclaw browser open https://news.ycombinator.com

# 获取页面快照(AI 可见)
openclaw browser snapshot

# 点击页面元素(通过 AI 标注的数字 Ref)
openclaw browser click 42

定时任务(Cron Jobs)

内置调度器支持三种模式:

  1. 一次性任务at):

    bash
    openclaw cron add --at "2026-02-15T14:30:00Z" --instruction "提醒我开会"
  2. 固定间隔every):

    bash
    openclaw cron add --every 3600000 --instruction "检查网站状态"  # 每小时
  3. Cron 表达式cron):

    bash
    openclaw cron add --cron "0 9 * * MON-FRI" --timezone "Asia/Shanghai" \
      --instruction "发送每日简报到工作群"

1.3 架构总览

单一长驻 Gateway 设计

OpenClaw 采用中心化网关架构,与传统的"每个渠道一个进程"的设计不同:

传统架构(分散式):
WhatsApp Bot 进程 A  ──┐
Telegram Bot 进程 B  ──┤
Discord Bot 进程 C   ──┤─→ 各自独立,难以协调
Slack Bot 进程 D     ──┘

OpenClaw 架构(网关式):
                    ┌─ WhatsApp (Baileys)
                    ├─ Telegram (Bot API)
OpenClaw Gateway ───├─ Discord (Gateway API)
                    ├─ Slack (Events API)
                    └─ Control UI / WebChat

核心优势

  • 统一状态管理:所有渠道的会话、记忆、配置在同一进程中
  • 智能体共享:同一智能体实例可以同时服务多个渠道
  • 跨渠道消息:智能体可以在 WhatsApp 接收消息,然后向 Slack 发送通知
  • 资源高效:只需一个 Node.js 进程,内存占用通常 < 500MB

WebSocket 协议通信

OpenClaw 使用 WebSocket 作为主要通信协议,支持三种客户端类型:

  1. Control-plane 客户端:CLI 工具(openclaw 命令行)
  2. Nodes 客户端:iOS/Android 移动应用
  3. WebChat 客户端:浏览器聊天界面

连接模型(来自 concepts/architecture 文档):

┌─────────────────────────────────────────┐
│       OpenClaw Gateway (WS Server)      │
│                                         │
│  - HTTP Server (REST API)               │
│  - WebSocket Server (RPC + Streaming)  │
│  - Channel Adapters (WhatsApp/Telegram)│
│  - Agent Runtime (pi-mono)              │
└─────────────────────────────────────────┘
         ▲          ▲          ▲
         │          │          │
    CLI 客户端   iOS App   Web UI
   (Control)    (Node)   (WebChat)

优势

  • 实时双向通信:支持流式响应(打字效果)、实时状态更新
  • 长连接复用:减少握手开销,降低延迟
  • 跨设备同步:多个客户端可以同时连接,实时看到智能体的状态

请求-响应帧格式

OpenClaw 定义了统一的 RPC 消息格式:

请求帧

json
{
  "type": "req",
  "id": "unique-request-id",
  "method": "message.send",
  "params": {
    "text": "Hello, world!",
    "channelId": "whatsapp:123456"
  }
}

响应帧(成功):

json
{
  "type": "res",
  "id": "unique-request-id",
  "ok": true,
  "payload": {
    "messageId": "msg-789"
  }
}

响应帧(失败):

json
{
  "type": "res",
  "id": "unique-request-id",
  "ok": false,
  "error": {
    "code": "CHANNEL_NOT_FOUND",
    "message": "Channel whatsapp:123456 is not connected"
  }
}

常用 RPC 方法

  • message.send:发送消息
  • sessions.list:列出会话
  • config.apply:更新配置
  • gateway.restart:重启网关
  • browser.navigate:浏览器导航

设备配对与信任模型

OpenClaw 采用配对优先的安全策略:

  1. 默认私聊策略pairing

    • 新用户首次发送消息时,机器人会要求验证身份
    • 只有通过配对的用户才能与智能体交互
    • 配对数据存储在 ~/.openclaw/gateway/pairings.json
  2. 三级信任等级

    • Pairing(配对模式):需要验证码或管理员批准
    • Allowlist(白名单模式):只有预定义的用户 ID 可以交互
    • Open(开放模式):任何人都可以发送消息(高风险,不推荐用于私人部署
  3. 群组门控

    • requireMention: true:只在被 @ 时响应
    • allowFrom:白名单机制,只响应特定用户

配对流程示例(WhatsApp):

用户: /start
机器人: 你好!请输入配对码以验证身份。

[管理员在 CLI 中运行: openclaw pairing create]
管理员: 配对码是 ABC123

用户: /pair ABC123
机器人: ✅ 配对成功!你现在可以使用所有功能了。

安全最佳实践

  • 永远不要使用 open 模式暴露到公网
  • 使用 Tailscale 或 SSH 隧道进行远程访问
  • 定期审计配对列表openclaw pairing list

第 2 章:支持的平台与运行环境

2.1 macOS(原生应用 + 菜单栏集成)

macOS 是 OpenClaw 的一级支持平台,提供最完整的原生体验。

安装方式

方式一:一键安装脚本(推荐)

bash
curl -fsSL https://openclaw.ai/install.sh | bash

方式二:Homebrew(社区维护)

bash
brew install openclaw

方式三:直接下载 macOS App

原生特性

  1. 菜单栏集成(Menu Bar)

    • 常驻菜单栏图标,快速访问 Gateway 状态
    • 右键菜单:启动/停止网关、打开 Control UI、查看日志
  2. XPC 进程间通信

    • macOS App 与 Gateway 进程通过 XPC 通信
    • 即使 App 关闭,Gateway 仍可在后台运行
  3. 语音覆盖层 UI(Voice Overlay)

    • 全局快捷键唤醒语音输入
    • 悬浮窗口显示转写结果和 AI 回复
  4. Peekaboo 桥接

    • 与 macOS 系统服务深度集成
    • 支持访问联系人、日历、提醒事项
  5. 权限管理

    • 首次运行时会请求以下权限:
      • 麦克风(语音输入)
      • 辅助功能(浏览器自动化)
      • 完全磁盘访问(仅在需要访问特定文件夹时)

系统要求

  • macOS 12 Monterey 或更高版本
  • Apple Silicon (M1/M2/M3) 或 Intel x86_64
  • 至少 4GB 可用 RAM
  • 2GB 可用磁盘空间(智能体工作区可能需要更多)

2.2 Linux(命令行部署)

Linux 是 生产环境部署的首选平台,适合服务器长期运行。

支持的发行版

  • Ubuntu 20.04 LTS 或更高版本(推荐)
  • Debian 11 或更高版本
  • Fedora 36+
  • Arch Linux(社区支持)
  • Rocky Linux / AlmaLinux(RHEL 兼容)

安装方式

方式一:一键脚本

bash
curl -fsSL https://openclaw.ai/install.sh | bash

方式二:从源码构建

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build
npm link  # 全局安装 openclaw 命令

方式三:Nix 包管理器

bash
nix profile install github:openclaw/openclaw

守护进程管理

OpenClaw 提供 systemd 服务集成:

bash
# 安装守护进程
openclaw onboard --install-daemon

# systemd 服务操作
sudo systemctl start openclaw    # 启动
sudo systemctl enable openclaw   # 开机自启
sudo systemctl status openclaw   # 查看状态
sudo journalctl -u openclaw -f   # 查看日志

服务文件位置/etc/systemd/system/openclaw.service

无头模式(Headless)

Linux 服务器通常没有图形界面,OpenClaw 提供以下访问方式:

  1. CLI 命令行openclaw 工具管理所有功能
  2. Control UI Web 界面:通过 SSH 隧道访问 http://127.0.0.1:18789/
  3. TUI 终端界面openclaw tui(实验性)

2.3 Windows(通过 WSL2)

Windows 用户需要通过 WSL2(Windows Subsystem for Linux 2) 运行 OpenClaw。

前置条件

  1. 启用 WSL2

    powershell
    # 以管理员身份运行 PowerShell
    wsl --install
    wsl --set-default-version 2
  2. 安装 Ubuntu 发行版

    powershell
    wsl --install -d Ubuntu-22.04
  3. 安装 Node.js 22+(在 WSL 内):

    bash
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
    sudo apt-get install -y nodejs

安装 OpenClaw

在 WSL2 终端中运行:

bash
curl -fsSL https://openclaw.ai/install.sh | bash

访问 Control UI

WSL2 支持端口转发,可以直接在 Windows 浏览器中访问:

http://localhost:18789/

注意事项

  • 文件系统性能:建议将 OpenClaw 数据存储在 WSL2 文件系统内(~/),而非 Windows 挂载路径(/mnt/c/
  • 网络限制:WSL2 使用虚拟网络,某些平台(如 WhatsApp)可能需要额外的网络配置
  • 资源分配:默认 WSL2 使用 50% 系统内存,可通过 .wslconfig 文件调整

2.4 iOS / Android 节点应用

OpenClaw 提供移动端 Node App,扩展网关的能力到手机设备。

功能特性

  1. Canvas 画布

    • 多模态输入界面(文本、语音、图片、位置)
    • 支持手写笔记、涂鸦标注
  2. 摄像头捕获

    • 拍照上传到智能体
    • 实时视频流分析(实验性)
  3. 语音笔记(Audio Notes)

    • 录音后自动转写为文本
    • 支持多语言识别(基于 Whisper)
  4. 位置查询

    • 分享当前 GPS 位置给智能体
    • 智能体可以根据位置提供本地化服务
  5. Talk 模式(实时语音交互)

    • 类似电话通话的实时对话
    • 支持中断、打断、自然对话流
  6. 语音唤醒(VoiceWake)

    • 自定义唤醒词(如 "Hey OpenClaw")
    • 后台监听,免提操作

安装方式

iOS(TestFlight 公测):

  • 加入 TestFlight Beta 计划:链接
  • 需要 iOS 16 或更高版本

Android(APK 直接安装):

配对流程

  1. 在手机上打开 OpenClaw App
  2. 选择 "Connect to Gateway"
  3. 扫描桌面端 Gateway 生成的配对二维码
  4. 确认设备信任

配对后,手机会作为 节点(Node) 接入网关,智能体可以调用节点能力:

bash
# 在智能体中调用节点工具
openclaw nodes list                      # 列出已配对节点
openclaw nodes capture --node-id abc123  # 请求节点拍照

2.5 Docker 容器化部署

Docker 是 生产环境的推荐部署方式,提供完整的隔离和可重现性。

快速启动

方式一:官方一键脚本

bash
curl -fsSL https://openclaw.ai/docker-setup.sh | bash

这会自动完成:

  1. 生成 docker-compose.yml 配置
  2. 创建持久化数据卷
  3. 启动 Gateway 容器

方式二:手动 Docker Compose

创建 docker-compose.yml

yaml
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "127.0.0.1:18789:18789"  # Control UI
      - "127.0.0.1:18790:18790"  # WebSocket
    volumes:
      - openclaw-data:/root/.openclaw
      - ./workspace:/workspace  # 智能体工作区
    environment:
      - OPENCLAW_HOME=/root/.openclaw
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    # 可选:沙箱支持
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  openclaw-data:

启动服务:

bash
docker-compose up -d

数据持久化

OpenClaw 需要持久化以下数据:

路径内容必须持久化
~/.openclaw/openclaw.json主配置文件✅ 是
~/.openclaw/agents/智能体会话和记忆✅ 是
~/.openclaw/gateway/网关状态(配对信息)✅ 是
~/.openclaw/skills/自定义技能建议
/workspace智能体工作区建议

备份策略

bash
# 导出数据卷
docker run --rm -v openclaw-data:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/openclaw-backup.tar.gz -C /data .

# 恢复数据卷
docker run --rm -v openclaw-data:/data -v $(pwd):/backup \
  ubuntu tar xzf /backup/openclaw-backup.tar.gz -C /data

环境变量配置

Docker 部署支持通过环境变量覆盖配置:

bash
# .env 文件
OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg vim htop"  # 额外安装的系统包
OPENCLAW_EXTRA_MOUNTS="/data:/data:ro"  # 额外挂载路径
OPENCLAW_HOME_VOLUME="custom-volume"  # 自定义数据卷名称

2.6 云平台部署

OpenClaw 支持主流云平台的一键部署,适合需要公网访问或高可用的场景。

Fly.io(推荐,免费套餐足够个人使用)

一键部署

bash
# 安装 flyctl
curl -L https://fly.io/install.sh | sh

# 登录
flyctl auth login

# 部署 OpenClaw
flyctl launch --image ghcr.io/openclaw/openclaw:latest

特性

  • 全球 Edge 网络,低延迟
  • 自动 HTTPS 证书
  • 持久化存储(Fly Volumes)
  • 免费配额:3 个共享 CPU 应用

访问方式

bash
# 获取公网 URL
flyctl apps list

# SSH 进入容器
flyctl ssh console

# 查看日志
flyctl logs

Railway(最简单的部署体验)

一键部署

  1. 访问 Railway.app
  2. 点击 "New Project" → "Deploy from GitHub repo"
  3. 选择 openclaw/openclaw 仓库
  4. Railway 自动检测 Dockerfile 并部署

环境变量配置(在 Railway 面板中设置):

ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
OPENCLAW_GATEWAY_BIND=0.0.0.0  # 允许外部访问

注意:Railway 会自动分配公网域名(如 openclaw-production.up.railway.app),需要配置网关 Token 防止未授权访问。

Render

部署步骤

  1. Render.com 创建新的 Web Service
  2. 连接 GitHub 仓库:openclaw/openclaw
  3. 配置构建命令:
    bash
    npm install && npm run build
  4. 配置启动命令:
    bash
    openclaw gateway start

持久化存储

  • Render 不提供免费持久化卷,需要升级到付费计划
  • 或使用外部存储(如 S3)存储智能体数据

Hetzner(性价比最高的欧洲云服务)

手动部署

  1. 创建 Ubuntu 22.04 虚拟机(最小配置:2 vCPU + 4GB RAM)
  2. SSH 登录后运行:
    bash
    curl -fsSL https://openclaw.ai/install.sh | bash
    openclaw onboard --install-daemon

优势

  • 价格便宜(€4.5/月起)
  • 数据中心位于德国,符合 GDPR
  • 提供私有网络(vSwitch)

GCP(Google Cloud Platform)

Cloud Run 部署(无服务器容器):

bash
gcloud run deploy openclaw \
  --image ghcr.io/openclaw/openclaw:latest \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY

注意:Cloud Run 是无状态的,需要配置持久化存储(Cloud Storage 或 Cloud SQL)。

Northflank

Northflank 是专为微服务设计的容器平台,支持:

  • 原生 Docker Compose 部署
  • 内置 Secret 管理
  • 免费套餐:2 个服务 + 2GB RAM

部署指南:参考 官方文档


平台选择建议

场景推荐平台理由
本地开发测试macOS / Linux 裸机最快速度,无网络延迟
个人长期使用macOS App + 菜单栏最佳用户体验,开机自启
家庭服务器Linux + systemd稳定可靠,资源可控
团队协作Docker Compose易于迁移和备份
公网服务Fly.io 或 Railway免费额度 + 自动 HTTPS
企业部署Hetzner VPS + Docker成本可控,数据自主
高可用生产GCP/AWS + Kubernetes自动扩展,负载均衡

小结

通过本章学习,你应该已经了解:

  1. OpenClaw 的核心定位:多渠道 AI 智能体网关平台,将强大的 Agent 能力接入到日常消息平台
  2. 四大核心能力
    • 统一接入 20+ 消息平台
    • 内置完整的 AI 智能体运行时
    • 多智能体并行与细粒度路由
    • 工具执行、浏览器自动化、定时任务
  3. 架构设计
    • 单一长驻 Gateway 设计
    • WebSocket 实时通信
    • 统一的请求-响应帧格式
    • 配对优先的信任模型
  4. 支持的平台
    • macOS:原生应用 + 菜单栏集成
    • Linux:命令行 + systemd 守护进程
    • Windows:通过 WSL2 运行
    • 移动端:iOS/Android Node App
    • 容器化:Docker / Docker Compose
    • 云平台:Fly.io、Railway、Render、Hetzner、GCP、Northflank

接下来,我们将在 第二部分:快速上手 中,带你完成 OpenClaw 的安装、配置和第一次对话体验。


参考文档

  • concepts/architecture — OpenClaw 架构总览
  • platforms/ — 各平台支持文档
  • install/ — 安装指南
  • start/getting-started — 快速入门