Appearance
第一部分:认识 OpenClaw
本部分将带你全面了解 OpenClaw 的核心定位、能力边界和支持的运行环境,为后续实战操作打下理论基础。
第 1 章:OpenClaw 是什么
1.1 项目定位:多渠道 AI 智能体网关平台
OpenClaw 是一个开源的多渠道 AI 智能体网关平台(Multi-Channel AI Agent Gateway),它的核心使命是:
将强大的 AI 智能体能力,无缝接入到你日常使用的各种消息平台中。
想象一下这样的场景:
- 在 WhatsApp 上问 AI 助手帮你查询天气、预订航班
- 在 Discord 服务器里让机器人自动整理会议纪要
- 在 Telegram 群组中让 AI 定时推送新闻摘要
- 在 Slack 工作区里让智能体执行代码、操作浏览器
传统上,这些需求要么依赖各平台零散的 Bot 服务,要么需要为每个平台单独开发集成。OpenClaw 的创新之处在于:
- 统一网关架构:一个 OpenClaw Gateway 实例可以同时管理 20+ 个消息平台的接入
- 智能体优先设计:内置完整的 AI Agent 运行时,支持工具调用、记忆系统、会话管理
- 多智能体并行:可以为不同场景配置独立的智能体(如个人助手、工作团队机器人、公开服务号)
- 开放生态:兼容 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、iMessage | QR 码 / Bot Token / BlueBubbles |
| 企业协作 | Slack、Microsoft Teams、Google Chat、Mattermost | OAuth / Bot Token |
| 社区社交 | Discord、Matrix、IRC | Bot Token / 账号登录 |
| 国际化平台 | LINE、Zalo、Feishu(飞书) | 平台 API |
| 开放协议 | Email(IMAP/SMTP)、SMS | 凭据配置 |
重点特性:
- 多账号支持:同一平台可以登录多个账号(如两个 WhatsApp 号、三个 Telegram Bot)
- 群组与私聊分离策略:细粒度控制机器人在群聊中的行为(如仅在被 @ 时响应)
- 白名单与配对机制:默认安全策略,防止未授权用户滥用
内置 AI 智能体运行时(基于 pi-mono)
OpenClaw 的智能体引擎基于 pi-mono(Anthropic 内部的 AI Agent 框架),提供:
- 工具调用(Tool Use):智能体可以执行 Shell 命令、操作文件、调用 API
- 浏览器自动化:托管隔离的 Chromium 实例,智能体可以像人类一样浏览网页、点击按钮、填写表单
- 记忆系统:双层记忆架构(日志层 + 长期记忆),支持向量语义搜索
- 会话管理:灵活的会话作用域(按发送者、按群组、按渠道隔离),自动压缩与重置
- 多模态支持:处理文本、图片、文件,输出格式化消息(Markdown、代码块)
与传统 Chatbot 框架的区别:
| 特性 | 传统框架(如 BotPress) | OpenClaw |
|---|---|---|
| 智能体能力 | 需要外接 AI 模型 | 内置完整 Agent 运行时 |
| 工具执行 | 需要手动编写插件 | 原生支持 50+ 工具,动态注册 |
| 记忆系统 | 通常基于数据库 | 文件系统 + 向量检索 |
| 浏览器自动化 | 需要集成 Puppeteer 等 | 内置托管浏览器 |
| 沙箱安全 | 不提供 | Docker 容器隔离 |
多智能体并行与路由
OpenClaw 支持在同一 Gateway 内运行多个完全隔离的智能体,每个智能体拥有:
- 独立的工作区(Workspace)
- 独立的认证配置(API Keys)
- 独立的会话存储
- 独立的工具策略和沙箱配置
路由规则(优先级从高到低):
- Peer 匹配:特定联系人或群组 ID 绑定到特定智能体
- Guild/Team 匹配:Discord 服务器、Slack 工作区级别绑定
- Account 匹配:消息账号级别绑定
- Channel 匹配:渠道类型级别绑定(如所有 WhatsApp 消息走智能体 A)
- 默认智能体:兜底规则
实战场景举例:
- 个人 WhatsApp 号码 → 智能体 A(全权限,可执行命令)
- 家庭群组 WhatsApp → 智能体 B(只读沙箱,仅提供信息服务)
- 公司 Slack 工作区 → 智能体 C(专用工作助手,访问内部工具)
- 开放 Telegram 频道 → 智能体 D(最小权限,禁用敏感工具)
工具执行、浏览器自动化、定时任务
工具系统(Tools):
OpenClaw 内置 50+ 工具,分为以下类别:
| 类别 | 代表工具 | 用途 |
|---|---|---|
| 执行类 | exec、apply_patch | 执行 Shell 命令、修改文件 |
| 信息类 | web_search、web_fetch | 搜索网页、抓取内容 |
| 浏览器类 | browser、canvas | 自动化浏览器操作 |
| 会话类 | sessions_spawn、sessions_send | 子会话管理、智能体间通信 |
| 消息类 | message | 跨渠道发送消息 |
| 自动化类 | cron、gateway | 定时任务、网关控制 |
| 记忆类 | memory_search、memory_get | 语义搜索记忆 |
工具策略:可以通过白名单/黑名单精细控制智能体可用的工具:
json
{
"tools": {
"allow": ["group:fs", "group:messaging"], // 允许文件系统和消息工具
"deny": ["exec"] // 禁止执行命令
}
}浏览器自动化(Browser Automation):
OpenClaw 提供两种浏览器控制模式:
- 托管浏览器(推荐):OpenClaw 启动隔离的 Chromium 实例,完全由智能体控制
- 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):
内置调度器支持三种模式:
一次性任务(
at):bashopenclaw cron add --at "2026-02-15T14:30:00Z" --instruction "提醒我开会"固定间隔(
every):bashopenclaw cron add --every 3600000 --instruction "检查网站状态" # 每小时Cron 表达式(
cron):bashopenclaw 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 作为主要通信协议,支持三种客户端类型:
- Control-plane 客户端:CLI 工具(
openclaw命令行) - Nodes 客户端:iOS/Android 移动应用
- 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 采用配对优先的安全策略:
默认私聊策略:
pairing- 新用户首次发送消息时,机器人会要求验证身份
- 只有通过配对的用户才能与智能体交互
- 配对数据存储在
~/.openclaw/gateway/pairings.json
三级信任等级:
- Pairing(配对模式):需要验证码或管理员批准
- Allowlist(白名单模式):只有预定义的用户 ID 可以交互
- Open(开放模式):任何人都可以发送消息(高风险,不推荐用于私人部署)
群组门控:
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
- 从 GitHub Releases 下载
.dmg文件 - 拖拽到
Applications文件夹
原生特性
菜单栏集成(Menu Bar):
- 常驻菜单栏图标,快速访问 Gateway 状态
- 右键菜单:启动/停止网关、打开 Control UI、查看日志
XPC 进程间通信:
- macOS App 与 Gateway 进程通过 XPC 通信
- 即使 App 关闭,Gateway 仍可在后台运行
语音覆盖层 UI(Voice Overlay):
- 全局快捷键唤醒语音输入
- 悬浮窗口显示转写结果和 AI 回复
Peekaboo 桥接:
- 与 macOS 系统服务深度集成
- 支持访问联系人、日历、提醒事项
权限管理:
- 首次运行时会请求以下权限:
- 麦克风(语音输入)
- 辅助功能(浏览器自动化)
- 完全磁盘访问(仅在需要访问特定文件夹时)
- 首次运行时会请求以下权限:
系统要求
- 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 提供以下访问方式:
- CLI 命令行:
openclaw工具管理所有功能 - Control UI Web 界面:通过 SSH 隧道访问
http://127.0.0.1:18789/ - TUI 终端界面:
openclaw tui(实验性)
2.3 Windows(通过 WSL2)
Windows 用户需要通过 WSL2(Windows Subsystem for Linux 2) 运行 OpenClaw。
前置条件
启用 WSL2:
powershell# 以管理员身份运行 PowerShell wsl --install wsl --set-default-version 2安装 Ubuntu 发行版:
powershellwsl --install -d Ubuntu-22.04安装 Node.js 22+(在 WSL 内):
bashcurl -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,扩展网关的能力到手机设备。
功能特性
Canvas 画布:
- 多模态输入界面(文本、语音、图片、位置)
- 支持手写笔记、涂鸦标注
摄像头捕获:
- 拍照上传到智能体
- 实时视频流分析(实验性)
语音笔记(Audio Notes):
- 录音后自动转写为文本
- 支持多语言识别(基于 Whisper)
位置查询:
- 分享当前 GPS 位置给智能体
- 智能体可以根据位置提供本地化服务
Talk 模式(实时语音交互):
- 类似电话通话的实时对话
- 支持中断、打断、自然对话流
语音唤醒(VoiceWake):
- 自定义唤醒词(如 "Hey OpenClaw")
- 后台监听,免提操作
安装方式
iOS(TestFlight 公测):
- 加入 TestFlight Beta 计划:链接
- 需要 iOS 16 或更高版本
Android(APK 直接安装):
- 从 GitHub Releases 下载
.apk - 需要 Android 12 或更高版本
配对流程
- 在手机上打开 OpenClaw App
- 选择 "Connect to Gateway"
- 扫描桌面端 Gateway 生成的配对二维码
- 确认设备信任
配对后,手机会作为 节点(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这会自动完成:
- 生成
docker-compose.yml配置 - 创建持久化数据卷
- 启动 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 logsRailway(最简单的部署体验)
一键部署:
- 访问 Railway.app
- 点击 "New Project" → "Deploy from GitHub repo"
- 选择
openclaw/openclaw仓库 - 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
部署步骤:
- 在 Render.com 创建新的 Web Service
- 连接 GitHub 仓库:
openclaw/openclaw - 配置构建命令:bash
npm install && npm run build - 配置启动命令:bash
openclaw gateway start
持久化存储:
- Render 不提供免费持久化卷,需要升级到付费计划
- 或使用外部存储(如 S3)存储智能体数据
Hetzner(性价比最高的欧洲云服务)
手动部署:
- 创建 Ubuntu 22.04 虚拟机(最小配置:2 vCPU + 4GB RAM)
- 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 | 自动扩展,负载均衡 |
小结
通过本章学习,你应该已经了解:
- OpenClaw 的核心定位:多渠道 AI 智能体网关平台,将强大的 Agent 能力接入到日常消息平台
- 四大核心能力:
- 统一接入 20+ 消息平台
- 内置完整的 AI 智能体运行时
- 多智能体并行与细粒度路由
- 工具执行、浏览器自动化、定时任务
- 架构设计:
- 单一长驻 Gateway 设计
- WebSocket 实时通信
- 统一的请求-响应帧格式
- 配对优先的信任模型
- 支持的平台:
- 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— 快速入门