OpenClaw完整说明文档(中英对照版)

🦞 OpenClaw”Any OS + Chat Gateway for AI Agents”

1. Overview概述

OpenClaw is an open-source gateway that bridges WhatsApp (via WhatsApp Web/Baileys), Telegram (Bot API/grammY), Discord (Bot API), and iMessage (macOS imsg CLI) to AI coding agents, primarily Pi. Plugins extend support to Mattermost and more.

OpenClaw 是一个开源网关，将 WhatsApp（通过 WhatsApp Web/Baileys）、Telegram（Bot API/grammY）、Discord 和 iMessage（macOS imsg CLI）连接到 AI 编码代理（主要是 Pi）。插件可扩展对 Mattermost 等更多平台的支持。

Send a message from WhatsApp or Telegram → the Gateway receives it → routes it to the Pi agent → Pi responds with tool-streaming → response is sent back to the chat.

从 WhatsApp 或 Telegram 发送消息 → 网关接收 → 路由至 Pi 代理 → Pi 使用工具流式响应 → 回复发送回聊天界面。

💡Creator:   Peter Steinberger (@steipete). Pi author: Mario Zechner (@badlogicgames).   License: MIT — Free as a lobster in the ocean 🦞 创作者：Peter Steinberger；Pi 作者：Mario Zechner；协议：MIT 开源

2. Features功能特性

English	中文 Chinese
WhatsApp integration via   WhatsApp Web (Baileys)	通过 Baileys  实现 WhatsApp Web 集成
Telegram bot support   (grammY)	Telegram 机器人支持（grammY）
Discord bot support   (channels.discord.js)	Discord 机器人支持
Mattermost bot (plugin)	Mattermost 机器人（插件）
iMessage via local imsg CLI   (macOS)	iMessage 集成（macOS 本地 imsg CLI）
Pi agent bridge with tool   streaming	Pi 代理桥接，支持工具流式传输
Streaming and chunking for   long responses	长响应流式分块传输
Multi-agent routing with   isolated sessions	多代理路由，支持会话隔离
OAuth auth for Anthropic   and OpenAI	Anthropic 和 OpenAI 的 OAuth 认证
Group chat with   mention-based activation	群聊支持，基于 @提及   激活
Media support: images,   audio, documents	媒体支持：图片、音频、文档
Voice note transcription   hook	语音消息转录钩子
WebChat + macOS menu bar   app	WebChat + macOS 菜单栏应用
iOS and Android nodes with   Canvas/Camera	iOS/Android 节点，支持 Canvas 和摄像头
Browser-based Control UI   (dashboard)	基于浏览器的控制面板（Dashboard）
Brave Search built-in web   search tool	内置 Brave   Search 网页搜索工具
Cron jobs & webhooks   automation	定时任务与   Webhook 自动化
Sandboxing with Docker	Docker 沙箱隔离
ClawHub skill marketplace	ClawHub 技能市场
Plugin system (4-layer   architecture)	插件系统（4层架构）

3. Quick Start快速开始

Prerequisites前置要求

•Node.js >= 22 (required)

Node.js >= 22（必须）

•pnpm (optional, recommended for source builds)

pnpm（可选，从源码构建推荐安装）

•Brave Search API key (recommended for web search)

Brave Search API 密钥（网页搜索推荐）

•Windows: use WSL2 (Ubuntu recommended); native Windows is untested

Windows：使用 WSL2（推荐 Ubuntu）；原生 Windows 未经测试

Installation安装

Option 1: Official installer (recommended)

方式一：官方安装脚本（推荐）

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

Option 2: npm global install

方式二：npm 全局安装

npm install -g openclaw@latest

Option 3: pnpm global install

方式三：pnpm 全局安装

pnpm add -g openclaw@latest

Option 4: Build from source

方式四：从源码构建

git clone https://github.com/openclaw/openclaw.git cd openclaw && pnpm install && pnpm ui:build && pnpm build

Windows (PowerShell):

Windows（PowerShell）：

iwr -useb https://openclaw.ai/install.ps1 | iex

Onboarding Wizard初始化向导

Run the interactive onboarding wizard to configure everything:

运行交互式初始化向导完成所有配置：

openclaw onboard –install-daemon

The wizard sets up: model/auth, gateway settings, channels (WhatsApp/Telegram/Discord), pairing defaults, workspace bootstrap, skills, and optional background service.

向导将配置：模型/认证、网关设置、聊天频道、配对规则、工作空间、技能，以及可选的后台服务（守护进程）。

Start Gateway启动网关

openclaw gateway –port 18789 –verbose

Dashboard URL (local): http://127.0.0.1:18789/

控制面板地址（本地）：http://127.0.0.1:18789/

💡Bun warning:   Bun has known issues with WhatsApp and Telegram channels. Always use Node for   the Gateway. ⚠️ Bun 警告：Bun 在 WhatsApp 和 Telegram 频道下存在已知问题，网关请始终使用 Node 运行。

Connect WhatsApp连接 WhatsApp

openclaw channels login

Scan the QR code via WhatsApp → Settings → Linked Devices.

通过 WhatsApp → 设置 → 已关联设备 扫描二维码。

Verify Installation验证安装

openclaw status openclaw health openclaw security audit –deep

Send a Test Message发送测试消息

openclaw message send –target +15555550123 –message “Hello from OpenClaw”

4. Architecture架构说明

OpenClaw follows a Gateway-centric architecture. The Gateway is a single long-running process that owns all channel connections and the WebSocket control plane.

OpenClaw 采用网关中心化架构。网关是一个长期运行的单进程，负责拥有所有频道连接和 WebSocket 控制平面。

English	中文 Chinese
Gateway (openclaw gateway)	网关进程，管理所有连接
Pi agent (RPC mode)	Pi 代理，通过 RPC 接收任务
CLI (openclaw …)	命令行工具
WebChat / macOS app	浏览器控制面板 /   macOS 应用
iOS / Android node	iOS / Android 节点，通过 WebSocket 配对
Canvas host (port 18793)	Canvas 文件服务器（节点 WebView 用）

Network model: one Gateway per host (recommended). Gateway WebSocket defaults to loopback ws://127.0.0.1:18789. For Tailnet access, use –bind tailnet –token … Remote use is via SSH tunnel or Tailscale.

网络模型：每台主机建议只运行一个网关。WebSocket 默认绑定到本地回环地址。Tailnet 远程访问需指定 –bind tailnet –token。也可通过 SSH 隧道或 Tailscale 远程使用。

5. Configuration配置说明

Config file location: ~/.openclaw/openclaw.json (JSON5 format, supports comments and trailing commas). Missing file = safe defaults. Gateway watches the file and applies changes automatically (hot reload).

配置文件路径：~/.openclaw/openclaw.json（JSON5 格式，支持注释和末尾逗号）。文件不存在时使用安全默认值。网关会监听文件变化并自动热重载。

Editing methods:

编辑方式：

•openclaw onboard / openclaw configure — interactive wizard

交互式向导

•openclaw config get/set/unset— one-liner CLI

CLI 单行命令

•Control UI at http://127.0.0.1:18789 — Config tab with form + raw JSON

浏览器控制面板 →Config 标签页

•Direct edit of ~/.openclaw/openclaw.json

直接编辑配置文件

Minimal Config Example最简配置示例

{agents: { defaults: { workspace: “~/.openclaw/workspace” } },channels: { whatsapp: { allowFrom: [“+15555550123”] } }, }

Key Config Sections主要配置项说明

English	中文 Chinese
agents.defaults.workspace	代理工作目录路径
agents.defaults.model.primary	主模型（如   anthropic/claude-sonnet-4-5）
agents.defaults.model.fallbacks	备用模型列表
agents.defaults.sandbox.mode	沙箱模式：off /   non-main / all
channels.whatsapp.allowFrom	WhatsApp 白名单号码
channels.telegram.botToken	Telegram 机器人令牌
channels.discord.*	Discord 频道配置
session.dmScope	DM 会话范围：main / per-peer / per-channel-peer
session.reset.mode	会话重置模式：daily   / idle / never
cron.enabled	是否启用定时任务
hooks.enabled	是否启用   Webhook
tools.web.search.apiKey	Brave Search API 密钥
gateway.auth.token	网关访问令牌

💡Strict   validation: OpenClaw rejects configs with unknown keys, malformed types, or   invalid values — the Gateway refuses to start. Run openclaw   doctor to see exact issues, or openclaw doctor –fix to auto-repair. 严格验证：配置中有未知键、类型错误或无效值时，网关拒绝启动。运行 openclaw doctor 查看问题，或 openclaw doctor   –fix 自动修复。

6. Channels聊天频道

DM access is controlled per channel via dmPolicy:

每个频道的 DM 访问权限通过 dmPolicy 控制：

English	中文 Chinese
“pairing”   (default)	配对模式（默认）：陌生发送者需完成配对验证
“allowlist”	白名单模式：只允许   allowFrom 列表中的用户
“open” (+   allowFrom: [“*”])	开放模式：允许所有   DM
“disabled”	禁用模式：忽略所有   DM

WhatsAppWhatsApp

•Login: openclaw channels login (shows QR)

登录：openclaw channels login（显示二维码）

•Scan via WhatsApp → Settings → Linked Devices

扫描路径：WhatsApp→ 设置 → 已关联设备

•Config section: channels.whatsapp

配置段：channels.whatsapp

TelegramTelegram

•Requires a bot token from @BotFather

需要从@BotFather 获取机器人令牌

•First DM returns a pairing code — approve it

首条 DM 会返回配对码，需手动审批

•Config section: channels.telegram

配置段：channels.telegram

DiscordDiscord

•Requires a Discord bot token and guild/channel setup

需要 Discord 机器人令牌和服务器配置

•Config section: channels.discord

配置段：channels.discord

Pairing / DM Approval配对 / DM 审批

openclaw pairing list whatsapp openclaw pairing approve whatsapp <code>

7. Tools & Skills工具与技能

Built-in Tools内置工具

English	中文 Chinese
Brave Search	网页搜索（内置，需   API 密钥）
Perplexity Search	Perplexity 搜索（可选）
apply_patch	应用补丁工具（代码修改）
Exec Tool	执行 Shell 命令工具
PDF Tool	PDF 处理工具
Browser (OpenClaw-managed)	浏览器自动化工具
LLM Task	子 LLM 任务工具
Firecrawl	网页抓取工具
Diffs	差异对比渲染工具
Elevated Mode	提升权限模式
Lobster	类型化工作流运行时（含审批门控）
BTW Side Questions	旁注问题工具
Thinking Levels	思维层级控制
Reactions	消息反应工具

Skills & ClawHub技能与 ClawHub

Skills are versioned bundles of files that teach OpenClaw how to perform specific tasks. ClawHub is the official skill marketplace. Skills can be loaded from workspace/skills, ~/.openclaw/skills, or bundled locations.

技能是版本化的文件包，教会 OpenClaw 执行特定任务。ClawHub 是官方技能市场。技能可从 workspace/skills、~/.openclaw/skills 或内置位置加载。

•Browse and install: clawhub search <query>

浏览安装：clawhub search <关键词>

•Workspace skills take precedence over bundled skills

工作空间技能优先于内置技能

Plugin System插件系统

OpenClaw plugin system has 4 layers:

OpenClaw 插件系统包含 4 层：

English	中文 Chinese
Manifest + discovery	清单定义 + 插件发现
Enablement + validation	启用控制 + 验证
Hook registration	钩子注册（before_agent_start   / before_model_resolve 等）
Exclusive slots (e.g.   memory)	排他性插槽（如   memory 插件只能有一个）

8. Automation自动化

Cron Jobs定时任务

Schedule agent tasks with cron expressions. Managed via CLI or config.

使用 Cron 表达式调度代理任务，通过 CLI 或配置文件管理。

openclaw cron list openclaw cron add –schedule “0 9 * * *” –task “Daily report”

English	中文 Chinese
cron.enabled	是否启用定时任务系统
cron.maxConcurrentRuns	最大并发任务数
cron.sessionRetention	运行会话保留时长（默认 24h）
cron.runLog.maxBytes	运行日志最大体积

Webhooks (Hooks)Webhook（钩子）

Enable HTTP webhook endpoints on the Gateway for external event ingestion.

在网关上启用 HTTP Webhook 端点，用于接收外部事件。

•Gmail Pub/Sub integration supported

支持 Gmail Pub/Sub 集成

•Token-secured endpoints

令牌保护的端点

•Configurable mappings: match path → route to agent

可配置路由映射：匹配路径 → 路由到代理

💡Security:   treat all webhook payload content as untrusted input. Keep unsafe-content   bypass flags disabled in production. 安全提示：所有 Webhook 内容均视为不可信输入。生产环境中请禁用   allowUnsafeExternalContent 标志。

Heartbeat心跳检测

Configure periodic agent check-ins to keep sessions alive and monitor status.

配置代理周期性心跳，保持会话活跃并监控状态。

agents.defaults.heartbeat:every: “30m”# 每 30 分钟target: “last” # 发送到最后一个活跃频道

9. Platforms & Deployment平台与部署

English	中文 Chinese
macOS (native app + menu   bar)	macOS（原生应用 + 菜单栏）
iOS (node app with pairing)	iOS（节点应用，支持配对）
Android (node app + Canvas)	Android（节点应用 + Canvas + 摄像头）
Linux (CLI + daemon)	Linux（CLI + 守护进程）
Windows via WSL2	Windows 通过 WSL2
Docker / Podman	Docker / Podman 容器部署
Kubernetes	Kubernetes 集群部署
Fly.io	Fly.io 云部署
Railway / Render	Railway / Render 云平台
Hetzner / DigitalOcean /   GCP / Oracle	主流 VPS 云服务器
Nix	Nix 包管理器安装
Raspberry Pi	树莓派部署
Ansible	Ansible 自动化部署

Remote Access远程访问

•SSH tunnel (most secure)

SSH 隧道（最安全）

•Tailscale / Tailnet (recommended for persistent remote)

Tailscale / Tailnet（推荐用于长期远程）

•Bonjour discovery (LAN)

Bonjour 发现（局域网）

10. Model Providers模型提供商

English	中文 Chinese
Anthropic (Claude)	Anthropic — Claude 系列
OpenAI (GPT / Codex)	OpenAI — GPT / Codex 系列
Amazon Bedrock	AWS Bedrock 托管模型
Ollama (local models)	Ollama — 本地模型运行
OpenRouter	OpenRouter — 多模型路由
Mistral	Mistral AI
Qwen / MiniMax / GLM /   Moonshot	国产模型：通义千问   / MiniMax / 智谱 / 月之暗面
GitHub Copilot	GitHub Copilot 接入
Cloudflare AI Gateway	Cloudflare AI 网关
Vercel AI Gateway	Vercel AI 网关
Hugging Face (Inference)	Hugging Face 推理 API
vLLM / LiteLLM	自托管推理框架
Venice AI / Together /   NVIDIA	其他第三方提供商

Model ref format: provider/model (e.g. anthropic/claude-opus-4-6). Model failover: configure fallbacks for automatic rotation on auth/quota errors.

模型引用格式：provider/model（如 anthropic/claude-opus-4-6）。支持配置 fallbacks 在认证/配额失败时自动切换。

11. CLI ReferenceCLI 命令参考

English	中文 Chinese
openclaw onboard	运行初始化向导
openclaw gateway [–port N]	启动网关
openclaw gateway status	查看网关状态
openclaw channels login	配对/登录聊天频道
openclaw status [–all]   [–deep]	查看整体状态与诊断信息
openclaw health	执行健康探测
openclaw doctor [–fix]	诊断并修复配置问题
openclaw configure	运行配置向导
openclaw config   get/set/unset <key>	读写配置项
openclaw message send   –target … –message …	发送测试消息
openclaw pairing list   <channel>	列出待审批配对请求
openclaw pairing approve   <channel> <code>	批准配对请求
openclaw cron   list/add/remove	管理定时任务
openclaw sessions list	列出当前会话
openclaw models list	列出可用模型
openclaw logs [–follow]	查看网关日志
openclaw update	更新   OpenClaw
openclaw uninstall	卸载   OpenClaw
openclaw dashboard	在浏览器中打开控制面板
openclaw security audit   [–deep]	安全审计

12. Security安全

•Gateway token: generated by default (even on loopback) — stored in gateway.auth.token

网关令牌：默认生成（即使在回环地址也会生成）

•Sandboxing: run agent sessions in isolated Docker containers

沙箱：在隔离的Docker 容器中运行代理会话

•DM policy (pairing/allowlist/open/disabled) per channel

每个频道独立配置 DM 访问策略

•Loopback-first: Gateway WS defaults to 127.0.0.1

网关 WebSocket默认绑定本地回环地址

•Run openclaw security audit –deep to check your setup

运行 openclaw security audit –deep 检查安全配置

•Treat all webhook/hook payloads as untrusted input

所有 Webhook 内容视为不可信输入

13. Troubleshooting故障排查

English	中文 Chinese
openclaw status –all	最佳可粘贴的只读调试报告
openclaw health	请求网关健康快照
openclaw doctor	检查并诊断配置问题
openclaw doctor –fix	自动修复可修复的配置问题
openclaw logs –follow	实时跟踪网关日志
“no auth   configured” error	返回向导设置   OAuth/API 密钥
WhatsApp not connecting	确保用 Node 运行网关（非 Bun）
Config rejected at startup	运行 doctor 检查 JSON5 语法和字段名
Pairing code not approved	运行   openclaw pairing list 查看待审批条目

14. Resources & Links资源与链接

English	中文 Chinese
Official docs	https://docs.openclaw.ai
GitHub repository	https://github.com/openclaw/openclaw
ClawHub skill marketplace	https://clawhub.dev (via   CLI: clawhub)
Releases	https://github.com/openclaw/openclaw/releases
Local dashboard	http://127.0.0.1:18789/
Pi agent (by Mario Zechner)	https://github.com/badlogic/pi-mono
Brave Search API	https://api.search.brave.com
License	MIT — Free as a lobster in the ocean 🦞

💡“EXFOLIATE!   EXFOLIATE!” — A space lobster, probably. OpenClaw = CLAW   + TARDIS, because every space lobster needs a time-and-space machine. “脱壳！脱壳！“——   某只太空龙虾，大概。OpenClaw = CLAW + TARDIS，因为每只太空龙虾都需要一台时空机器。🦞