夜雨聆风OpenClaw 完整部署与使用指南
版本：v1.0 | 更新日期：2026-03-08 | 适用对象：希望搭建个人 AI 助手的开发者和高级用户
目录
第一章 认识 OpenClaw 第二章 部署指南 第三章 连接聊天软件 第四章 配置 AI 模型 第五章 技能系统 第六章 多 Agent 协同 第七章 使用场景 第八章 常见问题排查 附录 命令速查表
第一章 认识 OpenClaw
1.1 产品概述
OpenClaw 是一个开源的、自托管的 AI 助手网关平台。它运行在用户自己的计算机或服务器上，通过统一的 Gateway 服务连接多种即时通讯软件（Telegram、WhatsApp、Discord、飞书等），并将消息路由到用户选择的 AI 模型（Claude、GPT、GLM 等）。
核心特点
- 自托管
：所有数据存储在本地，用户拥有完全控制权 - 多渠道接入
：单一 Gateway 可同时服务多个聊天平台 - 模型网关
：支持 20+ AI 模型提供商 - 可扩展
：通过 Skills 系统扩展能力 - 多 Agent
：支持创建多个独立角色的 AI 助手
与云端 AI 服务的对比
1.2 系统架构
OpenClaw 采用模块化架构设计，主要包含以下组件：
┌─────────────────────────────────────────────────────────────┐│ 即时通讯平台 ││ Telegram │ WhatsApp │ Discord │ 飞书 │ Signal │ iMessage │└──────────────────────────┬──────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ Gateway（网关） ││ ││ - 消息路由与分发 - 会话管理 - 权限控制 ││ - Web Control UI ( http://127.0.0.1:18789 ) ││ - 定时任务调度 │└──────────────────────────┬──────────────────────────────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼┌──────────────┐ ┌──────────────┐ ┌──────────────┐│ Provider │ │ Skills │ │ Nodes ││ 模型提供商 │ │ 技能库 │ │ 节点 ││ │ │ │ │ ││ Anthropic │ │ 网页抓取 │ │ iOS 设备 ││ OpenAI │ │ 数据分析 │ │ Android设备 ││ 智谱 GLM │ │ 文档处理 │ │ ││ 阿里千问 │ │ 投资分析 │ │ ││ 本地模型 │ │ ...80+ │ │ │└──────────────┘ └──────────────┘ └──────────────┘
1.3 核心组件说明
Gateway（网关）
Gateway 是 OpenClaw 的核心服务进程，负责：
监听来自各通道的消息 管理会话状态和上下文 路由消息到对应的 AI 模型 处理工具调用和技能执行 提供 Web 控制界面
运行要求：Gateway 必须保持持续运行状态，否则所有功能将不可用。
Channels（通道）
Channels 负责连接各种即时通讯平台：
Provider（模型配置）
OpenClaw 支持多种 AI 模型提供商：
Skills（技能）
Skills 是扩展 AI 能力的插件系统，采用 Markdown 格式定义。每个技能包含：
SKILL.md：技能说明和使用指南 scripts/：可选的执行脚本 references/：可选的参考文档 assets/：可选的资源文件
Nodes（节点）
Nodes 允许将移动设备、其他节点设备与主 Gateway 配对，实现：
远程相机控制 屏幕录制和查看 语音交互 位置获取
Sessions（会话）
OpenClaw 支持多会话隔离：
每个会话有独立的上下文和记忆 可创建不同角色的 Agent 支持主 Agent 和子 Agent 协同
1.4 身份系统
OpenClaw 通过 workspace 文件夹下面三个配置文件定义 AI 的身份和行为：
SOUL.md - 行为准则
定义 AI 的价值观、行为边界和对话风格。
# SOUL.md - 行为准则你不是聊天机器人，你正在成为一个有独立人格的助手。## 核心原则1. 真正有用，而不是表演有用2. 要有自己的观点3. 先尝试解决，再询问4. 用能力赢得信任5. 记住你是客人## 行为边界- 私人信息绝对保密- 对外操作前必须确认- 群聊中不代表用户发言- 不发送半成品回复
IDENTITY.md - 自我认知
定义 AI 的名字、形象和调性。
# IDENTITY.md - 自我认知- 名称：助手- 物种：AI 助手- 调性：专业、高效、务实- 签名：数据驱动
USER.md - 用户信息
记录用户的偏好、习惯和上下文。
# USER.md - 用户信息- 姓名：- 称呼：- 时区：Asia/Shanghai (GMT+8)## 背景信息（根据交互逐步补充用户的工作、项目、偏好等信息）
1.5 记忆系统
OpenClaw 的记忆系统基于文件存储，所有记忆都保存在本地磁盘上。
记忆文件结构
~/.openclaw/workspace/├── MEMORY.md # 长期记忆索引└── memory/ ├── projects.md # 项目状态 ├── infra.md # 基础设施配置 ├── lessons.md # 经验教训 └── 2026-03-08.md # 每日日志
记忆读取规则
记忆写入规则
用户说"记住这个"时，立即写入文件 重要的决策和偏好写入 MEMORY.md 日常交互记录写入当日日志文件 - 只有写入文件的内容才能跨会话保留
第二章 部署指南
2.1 环境要求
硬件要求
软件要求
node --version | ||
npm --version | ||
git --version |
2.2 macOS 部署
前置要求：安装 Xcode Command Line Tools
打开终端，执行：
# 安装 Xcode Command Line Toolsxcode-select --install
会弹出安装窗口，点击"安装"即可。
步骤 1：安装 Homebrew
# 安装 Homebrew（如果没有）/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 添加到 PATH（Apple Silicon Mac 需要执行）echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofileeval "$(/opt/homebrew/bin/brew shellenv)"# 验证brew --version
步骤 2：安装 Node.js
# 安装 Node.js 22brew install node@22# 如果提示已存在，可以链接brew link node@22# 验证 Node.js 版本node --version # 输出应该类似 v22.x.xnpm --version
方式一：一键安装脚本（推荐）
打开终端，执行以下命令：
# 下载并执行安装脚本curl -fsSL https://openclaw.ai/install.sh | bash
安装完成后，运行配置向导：
# 运行配置向导并安装系统服务openclaw onboard --install-daemon
验证安装：
# 检查版本openclaw --version# 检查 Gateway 状态openclaw gateway status# 打开控制面板openclaw dashboard
方式二：手动安装
如果一键脚本失败，可以手动安装：
# 全局安装 OpenClawnpm install -g openclaw@latest# 验证安装openclaw --version# 运行配置向导openclaw onboard# 启动 Gatewayopenclaw gateway --port 18789
配置系统服务
让 Gateway 在后台持续运行：
# 安装为系统服务openclaw onboard --install-daemon# 管理服务openclaw gateway start # 启动openclaw gateway stop # 停止openclaw gateway restart # 重启openclaw gateway status # 状态
2.3 macOS 常见问题
问题 1：npm 全局安装权限问题
报错示例：
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'解决方案：
# 方案1：修改 npm 全局目录到用户目录mkdir ~/.npm-globalnpm config set prefix '~/.npm-global'# 添加到 PATH（zsh）echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrcsource ~/.zshrc# 重新安装npm install -g openclaw@latest
或：
# 方案2：使用 sudo（不推荐）sudo npm install -g openclaw@latest
问题 2：Homebrew 安装失败
报错示例：
curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused解决方案：
# 方案1：使用国内镜像/bin/bash -c "$(curl -fsSL https://cdn.jsdelivr.net/gh/ineo6/homebrew-install/install.sh)"# 方案2：检查网络代理设置export ALL_PROXY=socks5://127.0.0.1:7890
问题 3：Node.js 版本过低
报错示例：
error openclaw@latest: The engine "node" is incompatible with this module.Expected version ">=18.0.0". Got "14.x.x"
解决方案：
# 查看当前版本node --version# 升级 Node.jsbrew upgrade node@22# 或使用 nvm 管理 Node 版本brew install nvmnvm install 22nvm use 22
问题 4：端口被占用
报错示例：
Error: listen EADDRINUSE: address already in use :::18789解决方案：
# 查找占用端口的进程lsof -i :18789# 终止进程（替换 PID）kill -9 <PID># 或使用其他端口openclaw gateway --port 18790
问题 5：系统服务启动失败
报错示例：
Failed to start openclaw-gateway.service: Unit file not found解决方案：
# 重新安装守护进程openclaw onboard --install-daemon# 检查服务状态launchctl list | grep openclaw# 手动启动（调试用）openclaw gateway --port 18789
问题 6：Apple Silicon (M1/M2/M3) 兼容性问题
报错示例：
Error: Cannot find module '@openclaw/native-darwin-arm64'解决方案：
# 确保使用 ARM64 版本的 Node.jsarch -arm64 brew install node@22# 重新安装 OpenClawnpm uninstall -g openclawnpm install -g openclaw@latest
问题 7：证书问题
报错示例：
Error: unable to verify the first certificate解决方案：
# 临时禁用 SSL 验证（不推荐长期使用）npm config set strict-ssl false# 或添加证书npm config set cafile /path/to/certificate.pem
卸载
# 停止服务openclaw gateway stop# 卸载 OpenClawnpm uninstall -g openclaw# 删除配置文件（可选）rm -rf ~/.openclaw
2.4 Windows 部署
注意：此方式可能遇到权限问题、路径问题等兼容性问题。建议使用 WSL2。
前置要求：设置 PowerShell 执行策略
以管理员身份打开 PowerShell：
# 查看当前策略Get-ExecutionPolicy -List# 设置执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser# 验证Get-ExecutionPolicy
步骤 1：安装 Git
访问官网：https://git-scm.com/download/win 下载 .exe 安装包 双击运行，一路 Next
验证：
git --version步骤 2：安装 Node.js
访问官网：https://nodejs.org/ 下载 LTS 版本的 .msi 安装包 双击运行，一路 Next
验证：
node --versionnpm --version
步骤 3：安装 OpenClaw
# 以管理员身份运行iwr -useb https://openclaw.ai/install.ps1 | iex# 运行配置向导openclaw onboard --install-daemon# 验证openclaw gateway status
2.5 Windows 常见问题
问题 1：执行策略报错
报错示例：
无法加载文件 C:\xxx\install.ps1，因为在此系统上禁止运行脚本。解决方案：
# 临时允许（仅当前会话）Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
问题 2：npm 全局安装权限问题
解决方案：
# 方案1：修改 npm 全局目录到用户目录npm config set prefix "$env:USERPROFILE\npm-global"# 添加到 PATH（永久）[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\npm-global", "User")# 重启 PowerShell 后生效
或：
# 方案2：以管理员身份运行 PowerShell，再执行安装npm install -g openclaw@latest
问题 3：路径含空格报错
报错示例：
'C:\Program' 不是内部或外部命令，也不是可运行的程序或批处理文件。解决方案：
安装时选择不含空格的路径，如 C:\nodejs\、C:\git\
2.6 配置文件详解
目录结构
~/.openclaw/├── openclaw.json # 主配置文件├── credentials/ # 凭证存储目录├── workspace/ # 工作区目录│ ├── SOUL.md # 行为准则│ ├── IDENTITY.md # 自我认知│ ├── USER.md # 用户信息│ ├── MEMORY.md # 长期记忆│ ├── SESSION-STATE.md # 会话状态│ ├── AGENTS.md # Agent 配置│ ├── TOOLS.md # 工具说明│ ├── HEARTBEAT.md # 心跳任务│ ├── BOOTSTRAP.md # 初始化脚本│ └── memory/ # 日记目录│ └── YYYY-MM-DD.md├── logs/ # 日志目录└── cron/ # 定时任务 └── jobs.json
完整配置示例
{ "meta": { "lastTouchedVersion": "2026.3.2", "lastTouchedAt": "2026-03-06T06:12:49.228Z" }, "env": { "BOCHA_API_KEY": "sk-xxx" }, "wizard": { "lastRunAt": "2026-03-04T02:31:16.405Z", "lastRunVersion": "2026.3.2", "lastRunCommand": "doctor", "lastRunMode": "local" }, "auth": { "profiles": { "zai:default": { "provider": "zai", "mode": "api_key" } } }, "models": { "mode": "merge", "providers": { "zai": { "baseUrl": "https://api.z.ai/api/coding/paas/v4", "api": "openai-completions", "models": [ { "id": "glm-5", "name": "GLM-5", "api": "openai-completions", "reasoning": true, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 640000, "maxTokens": 207272 } ] } } }, "agents": { "defaults": { "model": { "primary": "zai/glm-5", "fallbacks": ["zai/glm-4.6v"] }, "workspace": "/Users/xxx/.openclaw/workspace", "compaction": { "mode": "safeguard" }, "maxConcurrent": 4, "subagents": { "maxConcurrent": 8 } } }, "tools": { "profile": "full", "policy": { "exec": { "security": "deny", "ask": "on-miss" } } }, "messages": { "ackReactionScope": "group-mentions" }, "commands": { "native": "auto", "nativeSkills": "auto", "restart": true, "ownerDisplay": "raw" }, "session": { "dmScope": "per-channel-peer" }, "channels": { "feishu": { "enabled": true, "appId": "cli_xxx", "appSecret": "xxx", "domain": "feishu", "groupPolicy": "open", "dmPolicy": "open", "allowFrom": ["*"] } }, "gateway": { "port": 18789, "mode": "local", "bind": "lan", "auth": { "mode": "token", "token": "your-secure-token" }, "controlUi": { "allowedOrigins": ["*"], "allowInsecureAuth": true, "dangerouslyDisableDeviceAuth": true }, "tls": { "enabled": false, "cert": "", "key": "" }, "tailscale": { "mode": "off", "resetOnExit": false } }, "cron": { "enabled": true, "store": "~/.openclaw/cron/jobs.json", "maxConcurrentRuns": 1 }, "memorySearch": { "enabled": true, "extraPaths": [] }, "plugins": { "entries": { "feishu": { "enabled": true } }, "installs": { "feishu": { "source": "npm", "spec": "@openclaw/feishu", "version": "2026.3.1" } } }}
配置项详细说明
1. meta（元数据）
系统自动维护的元信息，不要手动修改。
"meta": { "lastTouchedVersion": "2026.3.2", "lastTouchedAt": "2026-03-06T06:12:49.228Z"}
2. env（环境变量）
存储 API Key 等敏感信息，会注入到运行环境。
"env": { "BOCHA_API_KEY": "sk-xxx", "OPENAI_API_KEY": "sk-xxx"}
3. auth（认证配置）
配置 AI 模型提供商的认证方式。
"auth": { "profiles": { "zai:default": { "provider": "zai", "mode": "api_key" }, "anthropic:default": { "provider": "anthropic", "mode": "api_key" } }}
4. models（模型配置）
定义可用的 AI 模型及其参数。
"models": { "mode": "merge", "providers": { "zai": { "baseUrl": "https://api.z.ai/api/coding/paas/v4", "api": "openai-completions", "models": [ { "id": "glm-5", "name": "GLM-5", "api": "openai-completions", "reasoning": true, "input": ["text"], "cost": { "input": 0, "output": 0 }, "contextWindow": 640000, "maxTokens": 207272 } ] } }}
支持的 API 协议：
openai-completions- OpenAI Chat Completions API anthropic-messages- Anthropic Messages API
5. agents（Agent 配置）
配置 Agent 的默认行为。
"agents": { "defaults": { "model": { "primary": "zai/glm-5", "fallbacks": ["zai/glm-4.6v"] }, "workspace": "/Users/xxx/.openclaw/workspace", "compaction": { "mode": "safeguard" }, "maxConcurrent": 4, "subagents": { "maxConcurrent": 8 } }}
compaction 模式说明：
safeguard- 安全模式，在接近上下文限制时压缩 aggressive- 激进模式，更频繁压缩 disabled- 禁用压缩
6. tools（工具配置）
配置工具访问权限和行为。
"tools": { "profile": "full", "policy": { "exec": { "security": "deny", "ask": "on-miss" } }}
profile 说明：
full- 启用所有工具 coding- 仅启用编码相关工具 minimal- 最小工具集
security 说明：
deny- 默认拒绝所有命令（最安全） allowlist- 仅允许白名单命令 full- 允许所有命令（危险）
7. gateway（Gateway 配置）
配置 Gateway 服务。
"gateway": { "port": 18789, "mode": "local", "bind": "lan", "auth": { "mode": "token", "token": "your-secure-token" }, "controlUi": { "allowedOrigins": ["*"], "allowInsecureAuth": true }, "tls": { "enabled": false, "cert": "", "key": "" }}
bind 说明：
localhost/ 127.0.0.1- 仅本机访问lan- 局域网可访问 0.0.0.0- 所有接口（危险）
8. channels（渠道配置）
配置消息渠道。
"channels": { "defaults": { "enabled": false, "groupPolicy": "allowlist" }, "feishu": { "enabled": true, "appId": "cli_xxx", "appSecret": "xxx", "domain": "feishu", "groupPolicy": "open", "dmPolicy": "open", "allowFrom": ["*"] }, "telegram": { "enabled": true, "botToken": "123456:ABCxxx", "dmPolicy": "pairing", "allowFrom": [], "groups": { "*": { "requireMention": true } } }}
groupPolicy/dmPolicy 选项：
open- 开放给所有人 allowlist- 仅白名单用户 denylist- 黑名单模式 pairing- 需要配对（仅 DM）
第三章 连接聊天软件
3.1 通道概览
OpenClaw 支持同时连接多个即时通讯平台，消息会自动路由到对应的通道。
3.2 Telegram 配置
Telegram 是配置最简单的通道，适合初次接触 OpenClaw 的用户。
步骤 1：创建 Bot
打开 Telegram 应用 搜索并打开 @BotFather（注意验证官方认证标识） 发送命令 /newbot按提示设置 Bot 名称（显示名称，可中文） 设置 Bot 用户名（必须以 bot 结尾，如 my_assistant_bot） - 保存返回的 Bot Token
（格式：123456789:ABCdefGHI...）
Bot Token 示例：
123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890步骤 2：配置 OpenClaw
编辑配置文件 ~/.openclaw/openclaw.json：
{ "channels": { "telegram": { "enabled": true, "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890", "dmPolicy": "pairing", "allowFrom": [], "groups": { "*": { "requireMention": true } }, "groupPolicy": "allowlist" } }}
或使用环境变量（不推荐，仅适用于默认账户）：
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz1234567890"步骤 3：启动 Gateway 并配对
# 启动 Gatewayopenclaw gateway# 在 Telegram 中给你的 Bot 发送任意消息# 查看配对请求openclaw pairing list telegram# 输出示例：# CODE USER_ID STATUS CREATED# ABC123XYZ 123456789 pending 2026-03-08 10:00:00# 批准配对openclaw pairing approve telegram ABC123XYZ
配对码有效期为 1 小时，过期需重新发送消息获取。
步骤 4：添加 Bot 到群组
在 Telegram 群组设置中添加 Bot 根据需要配置群组权限
群组配置示例：
{ "channels": { "telegram": { "groups": { "-1001234567890": { "groupPolicy": "open", "requireMention": false } } } }}
获取 Telegram User ID
方法一：通过日志（推荐）
# 启动日志跟踪openclaw logs --follow# 给 Bot 发送消息# 日志中查看 from.id 字段
方法二：通过 API
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates"返回的 JSON 中查找 message.from.id。
方法三：使用第三方 Bot
发送消息给 @userinfobot 或 @getidsbot，会返回你的 User ID。
DM Policy 说明
3.3 飞书配置
步骤 1：创建飞书企业自建应用
登录 飞书开放平台 点击 创建企业自建应用 填写：应用名称（如 "OpenClaw助手"）、应用描述、应用图标 点击 创建，进入应用管理页面
步骤 2：添加机器人
在应用管理页面左侧导航栏找到 添加应用能力 选择 机器人 点击 添加
💡 提示：添加机器人之后，可以暂不发布，待其他配置完成后一并发布。
步骤 3：查询 App ID 和 App Secret
在左侧导航栏找到 凭据与基础信息 找到 App ID 和 App Secret 点击右侧"复制"按钮保存（注意数据安全，勿泄露）
步骤 4：为 OpenClaw 配置通道
命令行输入 openclaw config 进行配置：
选择飞书连接方式 输入飞书机器人的 App Secret 和 App ID 确保飞书提示连接成功
💡 提示：OpenClaw 支持同一台服务器配置多个通道，例如同时接入 QQ 机器人和飞书机器人。
步骤 5：飞书机器人相关配置
事件配置
在飞书应用管理页左侧导航栏找到 事件与回调 在"事件配置"页签中选择 长连接接收事件 点击 保存
⚠️ 注意：如果报错"应用未建立长连接"，请检查 App ID 和 App Secret 是否已正确配置。如果配置正确但仍报错，可在轻量应用服务器应用管理页面点击"重启"按钮重启网关服务，再返回飞书开放平台保存事件配置。
添加事件
点击"事件配置"页面中的 添加事件 在弹出的列表中搜索并添加 接收消息 点击 确认添加，按指引确认开通权限（推荐）
群组相关权限：若需在群组中使用，可继续添加：
消息已读 机器人进群 机器人被移出群
回调配置
在"事件与回调 - 回调配置"页面 订阅方式选择 使用长连接接收回调 点击 保存，无需填写其他地址
权限配置
在飞书应用管理页左侧导航栏找到 权限管理 点击 批量导入权限 按钮 复制以下 JSON，替换弹窗中原有内容：
{ "scopes": { "tenant": [ "im:message", "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly", "im:message:send_as_bot", "im:resource", "contact:user.base:readonly", "im:message.group_msg", "im:message:readonly", "im:message:update", "im:message:recall", "im:message.reactions:read", "docx:document:readonly", "drive:drive:readonly", "wiki:wiki:readonly", "bitable:app:readonly", "task:task:read", "contact:contact.base:readonly", "docx:document", "docx:document.block:convert", "drive:drive", "wiki:wiki", "bitable:app", "task:task:write" ], "user": [] }
点击 下一步 → 确认新增权限 → 申请开通 等待权限导入完成
步骤 6：创建版本并发布
在飞书应用管理页左侧导航栏找到 版本管理与发布 点击右上角 创建版本 填写：应用版本号（如 1.0.0）、更新说明 点击 保存 并确认发布 等待飞书管理员通过发布审核
与飞书机器人进行交互
单独聊天
登录飞书（电脑版或手机版） 点击搜索框输入机器人的应用名称 点击搜索到的机器人进入私聊页面 开始对话
配对（Pairing）说明
首次对话可能提示配对请求：
复制机器人回复的最后一行命令 在打开部署 OpenClaw 终端中粘贴命令并执行 默认情况下，每增加一个同事，都需要将其用户 ID 添加到白名单中
这是因为 OpenClaw 为了保证安全，默认的配置是只允许特定的、经过授权的用户与机器人对话。如果你不手动添加，机器人会拒绝他们的请求，并可能提示"access not configured"或类似的错误。
不过，如果你是在一个私有的、受信任的内部环境中使用，希望所有飞书用户都能直接使用，也可以通过修改配置来实现"免审批"模式：
openclaw config set channels.feishu.dmPolicy openopenclaw config set channels.feishu.allowFrom '["*"]'
配置修改后，记得重启网关使其生效：
openclaw gateway restart提示"配对成功"后即可正常对话。
支持的消息类型
💡 提示：上述表格仅代表飞书机器人支持接收、回复的消息类型，实际能否完成任务还取决于 OpenClaw 接入的模型能力。
飞书工具能力
飞书常见问题
问题 1：应用未建立长连接
原因：App ID 和 App Secret 配置错误或未生效
解决方案：
检查 App ID 和 App Secret 是否正确 在轻量应用服务器应用管理页面点击"重启"按钮重启网关服务 返回飞书开放平台重新保存事件配置
问题 2：机器人不回复消息
可能原因：
模型 API Key 未配置或配置错误 机器人未发布或发布审核未通过 权限未正确配置
解决方案：
检查模型 API Key 配置 检查飞书开放平台"版本管理与发布"状态 检查权限列表是否完整
问题 3：无法添加到群聊
原因：机器人只能添加到同一企业下的群聊
解决方案：确保群组与企业机器人在同一企业下
3.4 WhatsApp 配置
步骤 1：扫码登录
# 启动登录流程openclaw channels login whatsapp
终端会显示二维码，使用手机 WhatsApp 扫描：
打开手机 WhatsApp 进入「设置」->「已关联的设备」 点击「关联设备」 扫描终端中的二维码
步骤 2：配置白名单
{ "channels": { "whatsapp": { "enabled": true, "allowFrom": [ "+8613800138000", "+8613900139000" ] } }}
步骤 3：重启 Gateway
openclaw gateway restartWhatsApp 常见问题
问题：登录失败
错误信息：Error: QR code expired
原因：二维码过期（约 20 秒）
解决方案：重新执行 openclaw channels login whatsapp
问题：频繁掉线
原因：WhatsApp 限制长时间连接
解决方案：
定期重新登录 保持 Gateway 持续运行
3.5 多通道配置
OpenClaw 支持同时启用多个通道：
{ "channels": { "telegram": { "enabled": true, "botToken": "xxx" }, "feishu": { "enabled": true, "appId": "xxx", "appSecret": "xxx" }, "discord": { "enabled": true, "token": "Bot xxx" } }}
消息路由规则：
在哪个通道收到的消息，回复到哪个通道 AI 不会主动选择通道 可通过 message 工具跨通道发送
第四章 配置 AI 模型
4.1 支持的模型提供商
OpenClaw 支持多种 AI 模型提供商，可以根据需求选择。
商业模型提供商
本地模型工具
4.2 获取 API Key
Anthropic (Claude)
访问：https://console.anthropic.com/ 注册/登录账户 进入「API Keys」页面 点击「Create Key」 复制生成的 Key（以 sk-ant- 开头）
注意：Key 只显示一次，请立即保存。
OpenAI (GPT)
访问：https://platform.openai.com/ 注册/登录账户 进入「API Keys」页面 点击「Create new secret key」 复制生成的 Key（以 sk- 开头）
智谱 AI (GLM)
访问：https://open.bigmodel.cn/ 注册/登录账户 进入「API Keys」页面 点击「创建 API Key」 复制生成的 Key
阿里云 (千问)
访问：https://dashscope.console.aliyun.com/ 登录阿里云账户 进入「API-KEY 管理」 点击「创建新的 API-KEY」 复制生成的 Key（以 sk- 开头）
4.3 配置 API Key
方式一：配置向导（推荐）
openclaw configure --section providers按提示选择提供商并输入 API Key。
方式二：编辑配置文件
编辑 ~/.openclaw/openclaw.json：
{ "providers": { "anthropic": { "apiKey": "sk-ant-xxxxx" }, "openai": { "apiKey": "sk-xxxxx" }, "zhipu": { "apiKey": "xxxxx.xxxxx" }, "alibaba": { "apiKey": "sk-xxxxx" }, "google": { "apiKey": "xxxxx" }, "deepseek": { "apiKey": "sk-xxxxx" } }}
方式三：环境变量
在 ~/.zshrc 或 ~/.bashrc 中添加：
# Anthropicexport ANTHROPIC_API_KEY="sk-ant-xxxxx"# OpenAIexport OPENAI_API_KEY="sk-xxxxx"# 智谱 AIexport ZHIPU_API_KEY="xxxxx.xxxxx"# 阿里云export ALIBABA_API_KEY="sk-xxxxx"# Googleexport GOOGLE_API_KEY="xxxxx"# DeepSeekexport DEEPSEEK_API_KEY="sk-xxxxx"
然后执行：
source ~/.zshrc4.4 多模型配置
OpenClaw 支持为不同场景配置不同的模型。
默认模型配置
{ "agents": { "defaults": { "model": "claude-3-5-sonnet-latest", "thinking": "medium", "maxTokens": 8192, "temperature": 0.7 } }}
参数说明：
多 Agent 配置
为不同用途的 Agent 配置不同模型：
{ "agents": { "list": [ { "name": "技术顾问", "model": "claude-3-5-sonnet-latest", "workspace": "~/.openclaw/workspace-tech", "bindings": { "telegram": ["+15555550123"] }, "skills": ["github", "playwright", "kubernetes-devops"] }, { "name": "运营专家", "model": "gpt-4o", "workspace": "~/.openclaw/workspace-ops", "bindings": { "feishu": ["ou_xxx"] }, "skills": ["data-analyst", "content-research-writer"] }, { "name": "日常助理", "model": "gpt-4o-mini", "workspace": "~/.openclaw/workspace-daily", "bindings": { "telegram": ["+15555550456"] } }, { "name": "投资顾问", "model": "claude-3-5-sonnet-latest", "workspace": "~/.openclaw/workspace-finance", "skills": ["stock-analysis", "financial-calculator"] } ] }}
子 Agent 模型配置
为子 Agent 配置更便宜的模型以节省成本：
{ "agents": { "defaults": { "model": "claude-3-5-sonnet-latest", "subagents": { "model": "gpt-4o-mini", "maxConcurrent": 8 } } }}
模型别名
OpenClaw 支持使用别名简化模型名称：
4.5 本地模型配置
Ollama 配置
安装 Ollama：
# macOSbrew install ollama# Linuxcurl -fsSL https://ollama.com/install.sh | sh
下载模型：
# 下载 Llama 3.2ollama pull llama3.2# 下载千问 2.5ollama pull qwen2.5# 下载其他模型ollama pull mistralollama pull codellama
启动 Ollama 服务：
ollama serve配置 OpenClaw：
{ "providers": { "ollama": { "baseUrl": "http://localhost:11434" } }, "agents": { "defaults": { "model": "ollama:llama3.2" } }}
LM Studio 配置
下载并安装 LM Studio：https://lmstudio.ai/ 在 LM Studio 中下载模型 启动本地服务器（默认端口 1234）
配置 OpenClaw：
{ "providers": { "lmstudio": { "baseUrl": "http://localhost:1234/v1" } }, "agents": { "defaults": { "model": "lmstudio:local-model" } }}
4.6 模型切换
会话内切换
在对话中使用斜杠命令切换模型：
/model claude-3-opus-latest/model gpt-4o/model glm-4/model ollama:llama3.2
查看当前模型：
/status4.7 成本优化
推荐配置组合
节省成本的技巧
- 使用 Flash/Mini 版本
：简单任务用轻量模型 - 子 Agent 用便宜模型
：并行任务用 GPT-4o-mini - 启用 Token 缓存
：减少重复计算 - 使用本地模型
：完全免费
4.8 模型配置常见问题
问题 1：API Key 无效
错误信息：Error: Authentication failed: invalid_api_key
排查步骤：
# 1. 检查 API Key 是否正确cat ~/.openclaw/openclaw.json | grep apiKey# 2. 检查是否有多余空格或换行# 3. 测试 API Key 是否有效curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-3-5-sonnet-latest", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'
解决方案：
重新生成 API Key 确认账户余额充足 检查 API Key 是否被撤销
问题 2：模型响应超时
错误信息：Error: Request timeout after 60000ms
原因：网络问题或模型负载过高
解决方案：
# 1. 检查网络连接ping api.anthropic.com# 2. 尝试使用代理export HTTP_PROXY=http://127.0.0.1:7890export HTTPS_PROXY=http://127.0.0.1:7890# 3. 切换到国内模型# 使用 GLM 或千问
问题 3：余额不足
错误信息：Error: insufficient_quota
解决方案：
登录提供商控制台充值 切换到其他提供商 使用本地模型
问题 4：速率限制
错误信息：Error: rate_limit_exceeded
解决方案：
等待一段时间后重试 升级 API 套餐 分散请求时间
第五章 技能系统
5.1 技能概述
Skills 是 OpenClaw 的能力扩展系统，通过 Markdown 格式的配置文件为 AI 提供专业知识和工作流程指导。
技能与 MCP 的区别
技能目录结构
my-skill/├── SKILL.md # 必需：技能说明和使用指南├── scripts/ # 可选：可执行脚本│ └── helper.sh├── references/ # 可选：参考文档│ └── api-docs.md└── assets/ # 可选：模板和资源 └── template.json
5.2 安装技能
从 ClawHub 搜索安装
ClawHub 是 OpenClaw 官方技能市场，地址：https://clawhub.com
# 搜索技能openclaw skills search <关键词># 示例openclaw skills search "数据分析"openclaw skills search "stock"openclaw skills search "web"# 安装技能openclaw skills install <技能名># 示例openclaw skills install data-analystopenclaw skills install github
强制安装（部分技能可能被安全工具标记，需要强制安装）：
openclaw skills install <技能名> --force查看已安装技能
# 列出所有已安装技能openclaw skills list# 查看技能详情openclaw skills info <技能名>
更新技能
# 更新单个技能openclaw skills update <技能名># 更新所有技能openclaw skills update --all
卸载技能
openclaw skills uninstall <技能名>5.3 技能清单
以下是当前已安装的技能分类列表。
数据分析类
研究搜索类
开发工具类
内容创作类
投资理财类
电商运营类
AI/ML 类
记忆系统类
自动化类
工具类
5.4 推荐技能组合
电商运营组合
openclaw skills install shopping-price-drop-coupon-scoutopenclaw skills install data-analystopenclaw skills install scrapeopenclaw skills install market-analysis-cn
技术开发组合
openclaw skills install githubopenclaw skills install playwrightopenclaw skills install kubernetes-devopsopenclaw skills install api-design
内容创作组合
openclaw skills install content-research-writeropenclaw skills install deep-researchopenclaw skills install bocha-web-searchopenclaw skills install document-pro
投资理财组合
openclaw skills install stock-analysisopenclaw skills install financial-calculatoropenclaw skills install a-stock-monitoropenclaw skills install investment-advisor
5.5 创建自定义技能
步骤 1：创建技能目录
mkdir -p ~/.openclaw/workspace/skills/my-skillcd ~/.openclaw/workspace/skills/my-skill
步骤 2：编写 SKILL.md
---name: my-skilldescription: 我的自定义技能---# My Skill这个技能用于执行特定任务。## 使用场景- 场景一：描述- 场景二：描述## 执行步骤1. 第一步：具体操作2. 第二步：具体操作3. 第三步：具体操作## 输出格式描述期望的输出格式。## 注意事项- 注意点一- 注意点二## 示例提供具体的使用示例。
步骤 3：测试技能
在对话中提及与技能相关的任务，AI 会自动读取 SKILL.md 并按照指导执行。
5.6 技能配置常见问题
问题 1：技能安装失败
错误信息：Error: Installation blocked by security policy 或 VirusTotal flagged this skill as suspicious
原因：安全工具标记
解决方案：
# 查看技能详情openclaw skills info <技能名># 强制安装openclaw skills install <技能名> --force
问题 2：技能不生效
错误信息：无错误，但 AI 没有按技能指导执行
排查步骤：
# 1. 检查技能文件是否存在ls ~/.openclaw/workspace/skills/<技能名>/SKILL.md# 2. 检查文件内容cat ~/.openclaw/workspace/skills/<技能名>/SKILL.md# 3. 检查日志openclaw logs --follow
可能原因：
SKILL.md 文件不存在或格式错误 技能描述与任务不匹配 AI 判断不需要使用该技能
问题 3：技能更新失败
错误信息：Error: Failed to fetch latest version
原因：网络问题或 ClawHub 服务不可用
解决方案：
# 检查网络连接ping clawhub.com# 使用代理export HTTP_PROXY=http://127.0.0.1:7890openclaw skills update <技能名>
第六章 多 Agent 协同
6.1 子 Agent 概述
子 Agent 是主 Agent 的独立执行单元，可以在后台并行处理任务，完成后自动回报结果。
应用场景
并行调研多个方向 同时处理多个数据集 分工协作完成复杂任务 节省成本（使用不同模型）
核心规则
6.2 启动子 Agent
方式一：自然语言描述
直接在对话中描述需求：
帮我同时调研以下三个方向：1. OpenAI 最新发布的模型及其特点2. Anthropic Claude 的定价策略3. 国产大模型（GLM、千问）的对比请并行执行，完成后汇总给我。
主 Agent 会自动判断并启动子 Agent。
方式二：斜杠命令
# 启动子 Agent/subagents spawn <agentId> <任务描述># 查看所有子 Agent/subagents list# 查看运行日志/subagents log <id># 向子 Agent 发送消息/subagents send <id> <消息># 引导子 Agent 方向/subagents steer <id> <消息># 终止子 Agent/subagents kill <id|all>
6.3 子 Agent 配置
模型配置
为子 Agent 配置更便宜的模型：
{ "agents": { "defaults": { "model": "claude-3-5-sonnet-latest", "subagents": { "model": "gpt-4o-mini", "maxConcurrent": 8 } } }}
工具权限
子 Agent 默认获得除会话工具外的所有工具。
被禁用的工具（防止套娃）：
sessions_list sessions_history sessions_send sessions_spawn
自定义权限配置：
{ "tools": { "subagents": { "tools": { "deny": ["gateway", "cron"], "allow": ["read", "exec", "process"] } } }}
注意：deny 优先级高于 allow。
6.4 通告机制
子 Agent 完成任务后会自动发布通告，包含以下信息：
跳过通告
如果子 Agent 回复 ANNOUNCE_SKIP，则不发布通告。
6.5 多 Agent 角色配置
配置不同职责的 Agent：
{ "agents": { "list": [ { "name": "技术顾问", "model": "claude-3-5-sonnet-latest", "workspace": "~/.openclaw/workspace-tech", "bindings": { "telegram": ["+15555550123"] }, "skills": ["github", "playwright", "kubernetes-devops"] }, { "name": "运营专家", "model": "gpt-4o", "workspace": "~/.openclaw/workspace-ops", "bindings": { "feishu": ["ou_xxx"] }, "skills": ["data-analyst", "content-research-writer"] }, { "name": "投资顾问", "model": "claude-3-5-sonnet-latest", "workspace": "~/.openclaw/workspace-finance", "skills": ["stock-analysis", "financial-calculator"] } ] }}
绑定规则
通过 bindings 配置将特定用户路由到特定 Agent：
{ "bindings": { "telegram": ["+15555550123", "+15555550456"], "feishu": ["ou_xxx", "ou_yyy"] }}
6.6 节点配置
什么是节点？
节点是配对的移动设备（iOS/Android），可以提供：
相机控制 屏幕操作 语音交互 位置获取
配对步骤
# 1. 获取配对码openclaw nodes pairing# 2. 在手机 App 中输入配对码# 3. 验证配对openclaw nodes list
节点操作
# 拍照openclaw nodes camera_snap --node <node_id> --facing back# 录屏openclaw nodes screen_record --node <node_id> --duration 60# 获取位置openclaw nodes location_get --node <node_id># 发送通知openclaw nodes notify --node <node_id> --title "提醒" --body "内容"
第七章 使用场景
7.1 日常场景
日程管理
帮我查一下明天的日程 提醒我下午3点开会 每周一早上9点提醒我写周报
天气查询
明天天气怎么样？ 这周会下雨吗？ 北京的空气质量如何？
邮件处理
帮我写一封请假邮件 总结一下今天收到的邮件 回复这封邮件，内容是...
文档处理
帮我总结这个文档的要点 把这篇英文翻译成中文 提取PDF中的表格数据
购物辅助
帮我查一下iPhone 15的最低价 这个商品有优惠券吗？ 对比京东和天猫的价格
7.2 工作场景
代码开发
帮我写一个Python爬虫，抓取豆瓣电影Top250 这段代码有什么问题？请指出并修复 帮我重构这个函数，提高可读性 为这个模块写单元测试
数据分析
分析这份销售数据，找出增长趋势 生成柱状图和折线图 预测下个月的销量
竞品调研
帮我调研竞品A和竞品B的功能对比 分析行业趋势和市场规模
报告撰写
帮我写一份项目周报 生成季度总结PPT大纲
7.3 自动化场景
定时任务
# 每天早上7点发送早报openclaw cron add \ --name "早报" \ --cron "0 7 * * *" \ --tz "Asia/Shanghai" \ --session isolated \ --message "汇总昨天的重要新闻和待办事项" \ --channel telegram \ --to "+15555550123"# 每周一早上9点提醒写周报openclaw cron add \ --name "周报提醒" \ --cron "0 9 * * 1" \ --tz "Asia/Shanghai" \ --session isolated \ --message "提醒：该写周报了" \ --channel telegram \ --to "+15555550123"
监控告警
# 每5分钟检查网站状态openclaw cron add \ --name "网站监控" \ --every 300000 \ --session isolated \ --message "检查 https://example.com 是否可访问，如果不可访问则通知我"
7.4 最佳实践
明确指令
❌ 不推荐：帮我弄一下那个东西 ✅ 推荐：帮我分析 data.csv 文件，按月份统计销售额，生成折线图
持续优化
定期更新 MEMORY.md 记录重要信息 调整 SOUL.md 让回复风格更符合预期 安装和更新有用的 Skills 根据使用情况调整模型选择
善用子 Agent
复杂任务拆分 并行执行不同类型任务 使用不同模型节省成本 定期检查子 Agent 日志 合理设置并发数量
第八章 常见问题排查
8.1 诊断工具
openclaw doctor
自动诊断配置问题：
# 运行诊断openclaw doctor# 自动修复openclaw doctor --fix
输出示例：
Checking OpenClaw configuration...[OK] Node.js version: v22.6.1[OK] OpenClaw version: 2026.2.28[OK] Gateway status: running[OK] Config file: valid[WARN] No channels configured[WARN] MEMORY.md not foundRun 'openclaw doctor --fix' to auto-fix issues.
openclaw status
查看系统状态：
openclaw status输出示例：
OpenClaw Status===============Version: 2026.2.28Runtime: agent=main | host=MacBook-Pro | os=Darwin 25.3.0Node: v22.6.1Model: claude-3-5-sonnet-latestGateway: running on port 18789Usage (this session): Time: 2m 34s | Input tokens: 12,345 | Output tokens: 8,901
日志查看
# 实时日志openclaw logs --follow# 最近100行日志openclaw logs --limit 100# 过滤错误日志openclaw logs --filter "error"
8.2 常见问题清单
安装问题
问题 1：npm install 失败 - 网络超时
错误信息：
npm ERR! network request to https://registry.npmjs.org/openclaw failednpm ERR! errno ETIMEDOUTnpm ERR! syscall connect
原因：网络连接问题，无法访问 npm 仓库
解决方案：
# 方案一：切换国内镜像源npm config set registry https://registry.npmmirror.comnpm install -g openclaw@latest# 方案二：使用代理npm config set proxy http://127.0.0.1:7890npm config set https-proxy http://127.0.0.1:7890npm install -g openclaw@latest# 方案三：使用 cnpmnpm install -g cnpm --registry=https://registry.npmmirror.comcnpm install -g openclaw@latest
问题 2：权限不足
错误信息：
npm ERR! Error: EACCES: permission deniednpm ERR! syscall: mkdirnpm ERR! path: /usr/local/lib/node_modules/openclawnpm ERR! errno: -13
原因：当前用户没有 npm 全局目录的写入权限
解决方案：
# 方案一：修改目录权限（macOS/Linux）sudo chown -R $(whoami) /usr/local/lib/node_modulessudo chown -R $(whoami) /usr/local/binnpm install -g openclaw@latest# 方案二：使用 nvm 管理 Node.jscurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bashsource ~/.zshrcnvm install 22nvm use 22npm install -g openclaw@latest# 方案三：使用 sudo（不推荐）sudo npm install -g openclaw@latest
问题 3：Node.js 版本过低
错误信息：
error openclaw@2026.x.x: The engine "node" is incompatible with this module.Expected version ">=22.0.0". Got "18.17.0"
原因：Node.js 版本低于要求的 22.0.0
解决方案：
# macOS - 使用 Homebrewbrew upgrade node@22# Ubuntu/Debiancurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs# 使用 nvmnvm install 22nvm use 22nvm alias default 22
Gateway 问题
问题 1：端口被占用
错误信息：
Error: listen EADDRINUSE: address already in use :::18789 at Server.setupListenHandle [as _listen2] (node:net:1872:16) at listenInCluster (node:net:1939:12)
原因：端口 18789 已被其他程序占用
解决方案：
# 查看占用端口的进程lsof -i :18789# 输出示例：# COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME# node 1234 user 22u IPv6 12345 0t0 TCP *:18789 (LISTEN)# 杀掉进程kill -9 1234# 或使用其他端口openclaw gateway --port 18790
问题 2：Gateway 无法启动
错误信息：Error: Cannot find module '/usr/local/lib/node_modules/openclaw/...'
原因：OpenClaw 安装不完整
解决方案：
# 重新安装npm uninstall -g openclawnpm install -g openclaw@latest# 清除缓存npm cache clean --forcenpm install -g openclaw@latest
问题 3：Gateway 频繁重启
错误信息：无明确错误，Gateway 状态频繁变化
排查步骤：
# 查看详细日志openclaw logs --follow# 检查配置文件openclaw doctor# 检查系统资源top
可能原因：
配置文件错误 内存不足 系统资源限制
通道问题
问题 1：Telegram Bot 不回复
错误信息：无错误，但 Bot 不响应消息
排查步骤：
# 1. 检查 Bot Token 是否正确cat ~/.openclaw/openclaw.json | grep botToken# 2. 检查是否已配对openclaw pairing list telegram# 3. 查看日志openclaw logs --follow# 4. 测试 Bot Tokencurl "https://api.telegram.org/bot<TOKEN>/getMe"
解决方案：
# 如果未配对openclaw pairing approve telegram <CODE># 如果 Token 错误，重新配置openclaw configure --section channels
问题 2：飞书收不到消息
错误信息：无错误，但收不到消息
排查步骤：
# 1. 检查事件订阅地址# 在飞书应用后台确认地址正确# 2. 测试地址可达性curl http://your-server:18789/webhook/feishu# 3. 查看日志openclaw logs --follow# 4. 检查应用权限# 确认已添加 im:message 等权限
可能原因：
事件订阅地址不可达 应用未发布 权限配置不完整 加密密钥配置错误
问题 3：WhatsApp 掉线
错误信息：Error: Session closed
原因：WhatsApp 连接超时或被限制
解决方案：
# 重新登录openclaw channels login whatsapp# 保持 Gateway 持续运行openclaw gateway start
模型问题
问题 1：API Key 无效
错误信息：
Error: Authentication failed: invalid_api_key{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid API Key" }}
排查步骤：
# 1. 检查 API Key 格式cat ~/.openclaw/openclaw.json | grep apiKey# 2. 测试 API Key# Anthropiccurl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-3-5-sonnet-latest", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'# OpenAIcurl https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}'
解决方案：
重新生成 API Key 确认没有多余空格或换行 检查账户是否被禁用
问题 2：余额不足
错误信息：
Error: insufficient_quota{ "type": "error", "error": { "type": "insufficient_quota", "message": "You have exceeded your current quota" }}
解决方案：
登录提供商控制台充值 切换到其他提供商 使用免费模型（GLM-4-Flash） 使用本地模型
问题 3：响应超时
错误信息：Error: Request timeout after 60000ms
原因：网络问题或模型负载过高
解决方案：
# 检查网络ping api.anthropic.comping api.openai.com# 使用代理export HTTP_PROXY=http://127.0.0.1:7890export HTTPS_PROXY=http://127.0.0.1:7890# 切换到国内模型# 使用 GLM 或千问
问题 4：速率限制
错误信息：
Error: rate_limit_exceeded{ "type": "error", "error": { "type": "rate_limit_error", "message": "Rate limit exceeded" }}
解决方案：
等待一段时间后重试 升级 API 套餐 分散请求时间 使用多个 API Key 轮换
8.3 重置配置
保留凭证重置
openclaw configure --reset完全重置
# 警告：这将删除所有配置、凭证和工作区openclaw configure --reset --reset-scope full# 或手动删除rm -rf ~/.openclaw
8.4 获取帮助
官方资源
提问技巧
在 GitHub Issues 提问时，请附上：
系统信息
openclaw --versionnode --versionuname -a
诊断输出
openclaw doctor状态信息
openclaw status相关日志
openclaw logs --limit 50问题描述和复现步骤
附录：命令速查表
安装和配置
npm install -g openclaw@latest # 安装openclaw onboard # 配置向导openclaw configure # 编辑配置openclaw doctor # 诊断
Gateway 管理
openclaw gateway start # 启动openclaw gateway stop # 停止openclaw gateway restart # 重启openclaw gateway status # 状态openclaw dashboard # 控制面板
通道管理
openclaw channels login <channel> # 登录通道openclaw pairing list <channel> # 查看配对openclaw pairing approve <channel> <CODE> # 批准配对
技能管理
openclaw skills search <keyword> # 搜索openclaw skills install <name> # 安装openclaw skills list # 列出openclaw skills update <name> # 更新openclaw skills uninstall <name> # 卸载
定时任务
openclaw cron add --name "任务名" --cron "0 7 * * *" # 添加openclaw cron list # 列出openclaw cron run <jobId> --force # 手动运行openclaw cron remove <jobId> # 删除
节点管理
openclaw nodes list # 列出openclaw nodes pairing # 配对openclaw nodes camera_snap --node <id> # 拍照openclaw nodes screen_record --node <id> # 录屏
