🔧 故障排除

使用 sudo npm install -g openclaw@latest（macOS/Linux），或以管理员身份运行 PowerShell（Windows）。推荐配置 npm 永久权限：查看教程。

1. 重新打开终端窗口；2. 检查 npm 全局路径是否在 PATH 中；3. 运行 npm root -g 确认安装路径，然后将该路径添加到 PATH。

检查网络连接，尝试使用国内镜像：curl -fsSL https://openclaw.ai/install.sh | bash 如持续失败，可手动下载安装包。

OpenClaw 需要 Node.js 18+，推荐使用 Node.js 22 LTS。运行 node --version 检查版本。如版本过低，使用 nvm 升级：nvm install 22 && nvm use 22。

以管理员身份运行 PowerShell，执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 允许本地脚本运行。

运行 npm install -g npm@latest 升级 npm 到最新版本，然后重新安装 OpenClaw。

这是 npm 权限问题。解决方案：1. 使用 nvm 管理 Node.js；2. 或修改 npm 全局目录权限；3. 或使用 sudo 临时提权。

脚本支持 macOS/Linux/Windows。如遇到问题，手动指定安装方式：macOS/Linux 使用 curl 脚本，Windows 使用 PowerShell 脚本。

首次运行 openclaw onboard 或 openclaw gateway 时会自动生成配置文件。手动创建：mkdir -p ~/.openclaw && touch ~/.openclaw/openclaw.json。

先完全卸载：npm uninstall -g openclaw，然后清理残留：rm -rf ~/.openclaw，最后重新安装。

端口 18789 被其他程序占用。解决方法：1. 查找占用进程：lsof -i :18789（macOS/Linux）或 netstat -ano | findstr :18789（Windows）；2. 关闭占用程序；3. 或使用其他端口：openclaw gateway --port 18888。

检查日志输出：openclaw gateway（前台运行）查看具体错误。常见原因：配置文件语法错误、端口被占、权限不足。

使用 openclaw onboard --install-daemon 时确保以管理员权限运行。macOS 可能需要关闭 SIP：csrutil disable（谨慎操作）。

守护进程未正确安装。重新安装：openclaw daemon install，或使用前台模式测试：openclaw gateway --port 18789。

1. 确认服务正在运行：openclaw gateway status；2. 检查防火墙是否阻止连接；3. 确认访问地址正确：http://127.0.0.1:18789

1. 检查系统启动项配置；2. 手动添加开机启动：macOS launchctl、Linux systemctl、Windows 计划任务。

打开 ~/.openclaw/openclaw.json，检查是否有语法错误（如多余的逗号，引号不匹配）。可使用 JSON 校验工具验证。

首次启动需要初始化，可能需要几分钟。检查网络连接（需要下载 AI 模型），或使用本地模型配置跳过下载。

检查服务文件权限：chmod 644 /etc/systemd/system/openclaw.service，然后重载：systemctl daemon-reload。

服务未成功启动或端口配置错误。检查 openclaw gateway status 确认服务状态，查看配置文件中的端口设置。

1. 确保手机和电脑在同一网络；2. 检查防火墙；3. 重新扫码：先在手机端退出 Web WhatsApp，然后重新运行 openclaw channels login whatsapp。

这是 WhatsApp Web 限制导致的。建议：1. 保持手机在线；2. 减少同时会话数；3. 或考虑使用 WhatsApp Business API。

1. 确认扫码成功且保持连接；2. 检查配置文件的 channels.whatsapp.allowFrom 是否包含你的号码；3. 查看日志排查。

1. 从 @BotFather 获取正确的 Bot Token；2. 确保 Token 没有过期；3. 检查配置文件中的 token 拼写是否正确。

1. 检查 Bot 是否有发送消息权限；2. 确认已正确配置 webhook 或轮询模式；3. 查看日志中的具体错误信息。

1. 检查 Bot 是否已添加到群组；2. 确认 Bot 有群组消息权限；3. 检查配置中是否启用了群组监听。

1. 检查 Discord Developer Portal 创建的 Bot 是否正确；2. 确认已勾选 Server Members Intent 权限；3. 使用正确的邀请链接格式。

在 Discord Developer Portal 检查 Bot 权限：需要 Send Messages、Send Messages in Threads、Embed Links、Attach Files 等权限。

1. 确认机器人已添加到服务器；2. 检查配置文件中 channel 或 guild ID 是否正确；3. 确认消息前缀配置。

iMessage 渠道只能在 macOS 上运行。确保 Gateway 部署在 macOS 机器上，且已登录 Apple ID。

1. 检查终端是否支持 QR 码显示；2. 使用 openclaw channels login --headless 获取链接后在手机扫描；3. 检查终端编码设置。

确保各渠道使用独立的配置文件段，或运行多个 Gateway 实例（不同端口）。避免同一账号同时在多处登录。

需要从 Meta for Developers 申请 Business API，创建应用后获取 API Key 和 Phone Number ID，在配置文件中填入相应参数。

Signal 支持需要额外的注册步骤。使用 openclaw channels login signal 按照指引完成手机号绑定。

默认路径：~/.openclaw/openclaw.json（Linux/macOS）或 %USERPROFILE%\.openclaw\openclaw.json（Windows）。可通过 OPENCLAW_CONFIG_PATH 环境变量自定义。

在配置文件中添加 "token": "your-secure-token"。生成强令牌：openclaw token generate。

使用 allowFrom 白名单："whatsapp": { "allowFrom": ["+15551234567"] }。支持正则匹配。

在 messages.groupChat 中配置："mentionPatterns": ["@openclaw"] 或 "requireMention": true 只在@时响应。

配置文件中添加 "port": 18789，或启动时指定：openclaw gateway --port 18888。

在配置中设置 "language": "zh-CN"。OpenClaw 支持多种语言，会根据配置自动选择。

在配置文件中添加 "proxy": { "http": "http://proxy:port", "https": "http://proxy:port" }。

使用 OPENCLAW_TOKEN、OPENCLAW_PORT 等环境变量可覆盖对应配置项。

在 providers 段配置：支持 OpenAI、Anthropic、Claude、Google、Ollama 等。配置相应的 API Key。

设置环境变量 DEBUG=openclaw:* 查看详细日志，或在配置中添加 "debug": true。

1. 设置强访问令牌；2. 配置 IP 白名单 allowedIPs；3. 启用 HTTPS（使用 Nginx/Caddy 反向代理）；4. 定期更换令牌。

在配置文件中重置：删除旧令牌行，重新生成：openclaw token generate 并填入配置。

1. 启用令牌验证；2. 配置 auth.required: true；3. 设置 IP 白名单；4. 使用 HTTPS 加密传输。

立即在对应平台（OpenAI、Anthropic 等）撤销泄露的 API Key，重新生成并更新配置文件中的密钥。

使用环境变量而非明文配置文件存储敏感信息，或集成 HashiCorp Vault、AWS Secrets Manager 等密钥管理服务。

1. 检查防火墙：ufw allow 18789（Linux）或 Windows 防火墙规则；2. 确认服务绑定地址是否为 0.0.0.0 而非 127.0.0.1。

1. 确认 Tailscale 客户端已登录并在两台设备上运行；2. 检查 Tailscale IP 是否在白名单；3. 确认网络可达。

推荐使用：1. Tailscale（最安全）；2. Cloudflare Tunnel；3. frp；4. ngrok。根据场景选择。

如果需要代理，在配置中设置 proxy 参数。确保代理支持 WebSocket 连接。

1. 使用 Let's Encrypt 自动续期证书；2. 手动导入证书到系统信任存储；3. 开发环境可禁用证书验证（谨慎使用）。

1. 确保手机和 Gateway 在同一网络；2. 检查节点应用版本与 Gateway 兼容；3. 重新生成配对码：openclaw nodes pair。

1. 确认节点已成功配对；2. 检查移动端应用是否支持 Canvas；3. 查看节点状态：openclaw nodes list。

1. 检查网络稳定性；2. 调整节点配置中的心跳间隔；3. 确认手机未开启省电模式限制后台运行。

1. 确认 iOS 版本支持（iOS 15+）；2. 检查本地网络设置；3. 在 iOS 设置中允许本地网络访问。

1. 确认应用通知权限已开启；2. 检查电池优化设置，将 OpenClaw 节点应用加入白名单；3. 允许后台运行。

1. 确认 Gateway 正在运行；2. 检查端口是否正确（默认 18789）；3. 尝试清除浏览器缓存；4. 使用 http://127.0.0.1:18789 访问。

1. 检查配置文件中 token 是否正确；2. 令牌有大小写区分；3. 尝试重新生成令牌。

1. 检查网络到 Gateway 的延迟；2. 清理浏览器缓存和 Cookie；3. 尝试使用 Chrome/Firefox 最新版本。

1. 确认渠道已正确配置；2. 检查对方是否在白名单中；3. 查看控制台错误信息排查。

1. 检查文件大小限制（默认 10MB）；2. 确认文件类型是否支持；3. 检查 Gateway 所在服务器磁盘空间。

1. 检查 AI 提供商 API 响应时间；2. 确认网络到 AI 服务器的延迟；3. 考虑切换到响应更快的模型。

1. 减少同时连接的渠道数量；2. 清理历史消息缓存；3. 监控并增加系统内存；4. 检查是否有内存泄漏。

1. 检查是否有大量消息处理；2. 查看是否有频繁的 API 调用；3. 考虑升级服务器配置或优化配置。

前台运行 openclaw gateway 查看实时日志，或使用 openclaw logs 查看历史日志。日志默认保存在 ~/.openclaw/logs/。

运行 openclaw doctor 进行系统健康检查，它会检测 Node.js 版本、依赖、配置文件等。

运行 npm install -g openclaw@latest 升级到最新版本。升级前建议备份配置文件 ~/.openclaw/openclaw.json。

1. 停止服务：openclaw gateway stop；2. 卸载包：npm uninstall -g openclaw；3. 删除数据：rm -rf ~/.openclaw。

备份：复制 ~/.openclaw/openclaw.json 到安全位置。恢复：将备份文件复制回原位置即可。

拉取最新镜像：docker pull openclaw/openclaw:latest，然后重新启动容器。数据卷中的配置会自动保留。

每个实例使用不同端口和配置文件。确保数据库或消息队列共享，以实现多实例协同工作。

默认在 ~/.openclaw/ 目录。包括配置文件、日志、缓存等。可通过 OPENCLAW_STATE_DIR 自定义。

运行 openclaw cache clear 清理缓存，或手动删除 ~/.openclaw/cache/ 目录。

将技能文件放入 ~/.openclaw/skills/ 目录，然后在配置文件的 skills 段启用。

1. 确认 Webhook URL 可公开访问；2. 检查 SSL 证书是否有效；3. 验证签名密钥配置正确；4. 查看日志排查具体错误。

默认消息长度限制 4096 字符。可在配置文件中通过 messages.maxLength 调整。

1. 确认浏览器支持该音频格式；2. 检查音频文件是否完整；3. 查看 Gateway 日志中的转码错误。

1. 检查图片 URL 是否可访问；2. 确认图片格式支持（PNG/JPG/GIF/WebP）；3. 检查文件大小是否超限。

在配置文件中设置 messages.rateLimit，如 "rateLimit": {"max": 10, "window": "1m"} 每分钟最多 10 条。

1. 检查是否陷入对话循环；2. 配置消息过滤规则；3. 启用 cooldown 冷却时间。

1. 检查终端编码设置是否为 UTF-8；2. 确认配置文件使用 UTF-8 编码保存；3. 查看日志编码设置。

在配置文件中设置 "timezone": "Asia/Shanghai"，或通过环境变量 TZ 指定。

部分渠道对 emoji 支持有限。确保使用标准 Unicode emoji 字符，或在配置中启用 emoji 转换。

1. 确认该渠道支持 Markdown；2. 检查配置中 format.markdown 是否启用；3. 某些渠道需要使用特定语法。

1. 检查自动回复规则是否正确配置；2. 确认触发关键词设置；3. 查看消息是否被其他规则拦截。

1. 检查 cron 表达式语法；2. 确认 Gateway 运行时间覆盖定时任务时段；3. 查看定时任务日志排查。