OpenClaw 安装报错排查指南

原因：npm 版本过低或网络问题。
解决：

node -v   # 确保 >= 22
npm cache clean --force
npm install -g openclaw@latest --registry=https://registry.npmmirror.com

如果仍然失败，尝试使用 pnpm：pnpm add -g openclaw@latest

原因：npm 全局安装目录权限不足，或 Docker 中用户权限问题。
解决：

# 方案1：修复 npm 全局目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 方案2：Docker 中显式指定用户
docker run --user $(id -u):$(id -g) ...

原因：在非交互式终端（如 CI/CD、某些 SSH 会话）中运行安装脚本。
解决：确保使用交互式终端（如完整的 SSH 连接、本地终端），或在安装后手动运行 openclaw onboard。

原因：Windows 原生 cmd/PowerShell 与 Node.js spawn 的兼容问题。
解决：使用 WSL2 运行 OpenClaw（官方推荐），或者安装 Git Bash 并在其中执行：

# 安装 WSL2
wsl --install
# 在 WSL 中安装
npm install -g openclaw@latest

原因：Windows 上 OpenClaw 官方推荐 WSL2 环境，原生 Windows 支持有限。
解决：①确保 Node.js >= 22；②使用 WSL2；③如果用原生 Windows，以管理员权限运行 PowerShell 安装。

原因：npm 全局 bin 目录未在 PATH 中，或安装了旧版命令名。
解决：

# 确认 npm 全局 bin 位置
npm bin -g
# 添加到 PATH
echo 'export PATH=$(npm bin -g):$PATH' >> ~/.zshrc
source ~/.zshrc
# 使用新命令名
openclaw --version

原因：npm 全局安装时未正确安装 UI 静态资源。
解决：

# 完全卸载后重装
npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

# 或使用 pnpm（更可靠的全局安装）
pnpm add -g openclaw@latest

原因：用户级 systemd 在某些 Linux 发行版上未启用。
解决：

# 启用用户级 systemd（lingering）
sudo loginctl enable-linger $USER
# 手动创建 service
openclaw gateway install

原因：EC2 等云服务器默认未启用 user-level systemd。
解决：

sudo loginctl enable-linger $USER
systemctl --user daemon-reload
openclaw gateway install
openclaw gateway start

原因：Render 平台的构建环境与 OpenClaw 需求不完全匹配。
解决：使用 Docker 部署到 Render，确保 Dockerfile 中指定 Node.js >= 22，并正确设置持久化存储路径。

原因：ARM 设备性能有限，Node.js 启动和依赖加载较慢。
解决：①使用 64 位 OS；②使用 bun 替代 npm 运行以提升启动速度；③降低工作区文件注入量。

原因：版本回退，2026.2.26 发布时缺少 x64 构建。
解决：①升级到最新版（已修复）；②Intel Mac 用户回退到 v2026.2.25；③或使用 npm 全局安装方式。

原因：macOS launchd 服务未正确注册，或端口被占用。
解决：

# 检查端口占用
lsof -i :3007
# 手动重启 Gateway
openclaw gateway stop
openclaw gateway start
# 检查 launchd 日志
cat ~/.openclaw/logs/gateway.log

原因：文件描述符泄漏或系统 ulimit 过低。
解决：

# 提高文件描述符限制
ulimit -n 4096
# 重启 Gateway
openclaw gateway restart

原因：版本升级后会话文件路径校验变严格。
解决：升级到最新版本，或删除旧的会话缓存：rm -rf ~/.openclaw/workspace/sessions/*

原因：长对话积累导致会话文件膨胀到数百 MB。
解决：定期清理会话：openclaw sessions prune，或设置会话自动过期。

原因：从源码构建时 Node.js 版本不匹配或依赖冲突。
解决：确保使用 Node.js 22+，清除 node_modules 后重装：

rm -rf node_modules package-lock.json
npm install
npm run build

原因：Ubuntu 22.04 上 onboard 向导的交互式选择被跳过。
解决：手动配置 Provider：openclaw models add，或直接编辑 ~/.openclaw/openclaw.json 中的 models 部分。

原因：Gateway 与客户端之间的配对关系丢失或 token 过期。
解决：

# 重新配对
openclaw gateway pair
# 如果仍失败，重启 Gateway
openclaw gateway restart

原因：版本升级改变了配对 token 格式。
解决：

openclaw gateway stop
openclaw gateway pair --force
openclaw gateway start

原因：Gateway 进程未运行，或端口被占用。
解决：

openclaw gateway status
# 如果未运行
openclaw gateway start
# 检查端口 3007 是否被占用
lsof -i :3007  # macOS/Linux
netstat -ano | findstr 3007  # Windows

原因：网络变更（如切换 Wi-Fi）后 Gateway 地址改变。
解决：使用 openclaw gateway pair 重新配对，或将 Gateway 绑定到 0.0.0.0。

原因：WebSocket 连接异常断开，通常是网络不稳定或代理干扰。
解决：①检查防火墙/代理是否拦截 WebSocket；②设置 --keep-alive；③查看 Gateway 日志排查具体断开原因。

原因：macOS launchctl 重启超时，Gateway 进入降级状态。
解决：

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
openclaw gateway install
openclaw gateway start

原因：升级后出现重复的飞书插件条目。
解决：编辑 ~/.openclaw/openclaw.json，移除 plugins.entries 中重复的 feishu 条目，然后 openclaw gateway restart。

原因：全新安装后插件未正确注册。
解决：

openclaw plugins install --all
openclaw gateway restart

原因：v2026.3.1 回归缺陷，Vertex 嵌入式运行在 Telegram + cron 场景下崩溃。
解决：升级到 v2026.3.2+，该问题已修复。

原因：Web UI 使用的 token 缺少必要的权限范围。
解决：重新生成 token：openclaw gateway pair --scopes=operator.read,operator.write

原因：Web UI 版本与 Gateway 版本不一致。
解决：确保 OpenClaw 更新到最新版本：npm update -g openclaw@latest

原因：Control UI WebSocket 连接失败或权限不足。
解决：①确保 Gateway 运行中；②检查浏览器是否允许 WebSocket；③清除浏览器缓存重新打开 Control UI。

原因：SSH 隧道下 companion app 无法自动读取远程配置中的 auth token。
解决：手动复制远程 Gateway 的 auth token，在本地 companion app 设置中填入。

原因：升级后 token 格式变化，浏览器扩展期望派生 token。
解决：更新 Browser Relay 扩展到最新版，或重新运行 openclaw gateway pair 获取新格式 token。

原因：WhatsApp 会话状态损坏，无法完成重新配对。
解决：

# 清除 WhatsApp 会话缓存
rm -rf ~/.openclaw/workspace/channels/whatsapp/
# 重新配对
openclaw channels add whatsapp

原因：Windows 路径分隔符与 WhatsApp 插件不兼容。
解决：使用 WSL2 运行 OpenClaw（官方推荐 Windows 用户使用 WSL）。

原因：auto-enable 逻辑错误地将配置写入了 plugins.entries 而非 channels。
解决：手动编辑 ~/.openclaw/openclaw.json，将 Telegram 配置移到正确的 channels 字段下。

原因：Telegram 插件未安装或加载失败。
解决：

openclaw plugins install @openclaw/telegram
openclaw gateway restart

原因：Telegram 渠道使用了不同的 API 认证路径，触发计费检查。
解决：确保 Telegram 渠道使用的 API Key 与 Web UI 相同；检查 models 配置中 Telegram 是否绑定了正确的 provider。

原因：MiniMax 模型的流式输出格式与 Telegram 渠道不完全兼容。
解决：在模型配置中设置 "streaming": false，使用非流式模式。

原因：Node.js 内置 HTTPS 模块超时，但 curl 正常。通常是 DNS 或代理配置差异。
解决：设置 NODE_EXTRA_CA_CERTS 环境变量，或配置 HTTPS_PROXY 环境变量让 Node 也走代理。

原因：Discord Bot Token 无效或 Application ID 配置错误。
解决：①在 Discord Developer Portal 确认 Bot Token 有效；②确保配置中 applicationId 正确；③中国大陆用户需配置代理。

原因：中国大陆网络无法直接访问 Discord API。
解决：为 OpenClaw 配置 HTTP 代理：

export HTTPS_PROXY=http://your-proxy:port
openclaw gateway restart

原因：Discord WebSocket 频繁断开且重连退避时间无限增长。
解决：升级到最新版本（已优化重连逻辑）；检查网络是否稳定；查看是否有代理中断 WebSocket 长连接。

原因：模型的 thinking 输出未被过滤，直接发送到 Discord。
解决：升级到最新版；或在模型配置中设置 "reasoning": false 关闭推理输出。

原因：飞书插件依赖安装失败或版本不兼容。
解决：

# 使用社区维护的飞书插件
openclaw plugins install @m1heng/clawdbot-feishu
openclaw gateway restart

原因：内置飞书插件存在兼容性问题。
解决：社区推荐使用第三方插件 @m1heng/clawdbot-feishu，参见 #8650。

原因：iMessage 渠道中 AI 回复被识别为新消息再次触发回复。
解决：升级到最新版（已优化消息去重逻辑）；或在配置中排除自己的 Apple ID。

原因：Matrix SDK 中缺少自身用户验证方法。
解决：目前 Matrix E2EE 支持有限，建议暂时在未加密的房间中使用，或关注 Issue 更新。

原因：Matrix 插件依赖问题导致无法正常工作。
解决：确保安装最新版本的 Matrix 插件，并检查 Matrix homeserver 地址和 access token 是否正确。

原因：Mattermost WebSocket 事件监听失败。
解决：检查 Mattermost 服务器版本和 WebSocket 配置；确保 bot 账号有正确的频道权限。

原因：cron announce 在 Telegram topic 中默认发送摘要。
解决：在 cron 配置中设置 outputMode: "full"，或升级到已修复此行为的版本。

原因：LMStudio 的 API 兼容性问题。
解决：确保 LMStudio 启用了 OpenAI 兼容 API 模式；在 OpenClaw 中使用 openai-completions API 类型配置。

原因：浏览器 CDP 连接配置错误或 Chrome 未以调试端口启动。
解决：确保 Chrome 以远程调试模式启动：

google-chrome --remote-debugging-port=18800

并在配置中设置正确的 cdpPort。

原因：CDP 连接间歇性超时。
解决：增加超时时间：在配置中设置 "remoteCdpTimeoutMs": 5000；确保 Chrome 进程稳定运行。

原因：TUI 模式下 chat 事件未正确发送到终端。
解决：检查终端是否支持 ANSI；尝试使用 --no-tui 模式运行：openclaw chat --no-tui

原因：模型 API 调用失败但错误被静默吞没。
解决：①检查 API Key 是否有效；②查看 Gateway 日志：cat ~/.openclaw/logs/gateway.log | tail -50；③开启调试模式：openclaw --verbose

原因：Ollama 模型名称配置错误或 Ollama 服务未运行。
解决：①确认 Ollama 在运行：ollama list；②模型名需与 ollama list 输出一致（如 llama3.2 而非 llama-3.2）。

原因：配置中未明确指定 Ollama API 地址，默认调用本地 CLI。
解决：在模型 provider 配置中明确设置 "baseUrl": "http://remote-host:11434/v1"。

原因：模型切换逻辑未正确处理 Ollama 模型标签格式。
解决：在配置中手动添加模型条目，使用完整模型名（含 tag）："id": "deepseek-r1:latest"

原因：Antigravity（Google AI 集成）API 版本过旧。
解决：npm update -g openclaw@latest，升级后 Antigravity 集成会自动更新。

原因：自动发现的模型列表中缺少某些模型。
解决：在配置中手动添加模型条目，指定完整的模型 ID。

原因：gemini-cli 未安装或不在 PATH 中。
解决：

npm install -g @anthropic-ai/gemini-cli
# 或配置 Gemini 使用 API 模式而非 CLI

原因：OpenAI Responses API 要求 reasoning 后必须跟随 output item。
解决：升级到最新版本（已修复 reasoning 消息拼接逻辑）；或临时在模型配置中设置 "reasoning": false。

原因：gpt-5.2 的 reasoning 输出格式与 OpenClaw 解析逻辑不匹配，导致无限重试。
解决：升级 OpenClaw；或暂时切换到 gpt-4o 等非 reasoning 模型。

原因：Anthropic 限制了 Claude Code 的 OAuth token 在第三方应用中的使用。
解决：使用独立的 Anthropic API Key 而非 Claude Code 的 OAuth token。

原因：OAuth 配置的 mode 和 type 在不同配置文件之间不一致。
解决：重新运行 openclaw models add anthropic，使用 API Key 模式而非 OAuth。

原因：Bearer token 过期或格式不正确。
解决：重新认证：openclaw auth login anthropic；或直接使用 API Key 模式。

原因：自定义 API provider 的默认 context window 太小。
解决：在模型配置中明确设置："contextWindow": 32768 和 "maxTokens": 8192。

原因：模型不支持原生 tool calling，将工具调用作为文本输出。
解决：①使用支持 tool calling 的模型；②在模型配置中添加 "toolCalling": true；③或关闭工具调用。

原因：Gemini 模型以文本形式输出工具调用而非结构化格式。
解决：确保使用 Gemini 的 function calling API 模式；升级 OpenClaw 到最新版。

原因：v2026.3.7 回归问题，kimi-coding 模型的 tool call 解析失败。
解决：升级到 v2026.3.8+；或在模型配置中添加 "compat" 字段适配。

原因：OpenRouter 的模型 ID 需要双重前缀。
解决：使用完整格式："id": "openrouter/openrouter/auto"

原因：OpenRouter 代理的 Grok 模型不接受重复的工具定义。
解决：减少注册的工具数量；或在模型配置中设置 "tools": [] 禁用工具。

原因：配置文件中存在当前版本不识别的字段。
解决：删除不识别的字段，或升级 OpenClaw 到支持该字段的版本。

原因：OpenClaw 在运行时意外修改配置文件。
解决：备份配置文件：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak；升级到已修复的版本。

原因：openclaw configure 命令将脱敏后的 "sk-***" 写回了配置文件。
解决：从备份恢复：cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json；升级到已修复版本。

原因：工具参数名在版本之间有变更。
解决：升级到最新版本，参数名已统一。

原因：版本更新后工具注册逻辑变化，导致内置工具消失。
解决：

openclaw gateway restart
# 如果仍不工作
npm update -g openclaw@latest
openclaw gateway restart

原因：频繁版本更新导致工具稳定性问题。
解决：锁定到稳定版本：npm install -g openclaw@2026.3.5；避免频繁升级。

原因：AI 模型回复文本但不触发 tool call，通常是模型不支持或配置错误。
解决：①确保使用支持 tool calling 的模型（如 Claude、GPT-4o）；②检查工具是否正确注册：openclaw tools list；③重启 Gateway。

原因：特定版本打包时遗漏了内置 hooks。
解决：升级到 2026.2.3+，该问题已修复。

原因：内置的 soul-evil hook 存在安全隐患。
解决：升级到已移除该 hook 的版本；或手动禁用：在配置中移除 soul-evil 相关条目。

原因：Venice AI 的 API 格式与 OpenClaw 预期不匹配。
解决：检查 Venice AI 的 baseUrl 和 API 格式是否正确配置；确认 API Key 有效。

原因：OAuth token 过期后未自动刷新。
解决：重新认证：openclaw auth login；或切换为使用 API Key 模式。

原因：OAuth token 刷新导致每次工具调用阻塞 60 秒。
解决：使用 API Key 替代 OAuth 认证；或使用 API Proxy 中间层。

原因：NIM API 响应超时导致整个 Gateway 冻结。
解决：设置请求超时；升级到已添加超时保护的版本。

原因：早期 openai-completions 模式不支持 tool calling。
解决：升级到最新版本（已支持）；或切换到 "api": "openai-chat" 模式。

原因：Agent 可通过 exec 工具读取配置文件中的 API Key。
解决：①使用环境变量存储敏感信息而非配置文件；②限制 exec 工具的文件访问范围；③关注官方安全加固路线图。

原因：prompt 缓存未生效，每次请求都发送完整上下文。
解决：①检查 provider 是否支持 prompt caching；②在模型配置中启用 "caching": true；③减少系统提示变化频率。

原因：OpenTelemetry 依赖版本不兼容。
解决：重装插件：openclaw plugins install diagnostics-otel --force；或在配置中禁用 OTel 诊断。

原因：npm 全局安装下扩展解析路径错误。
解决：

# 使用 pnpm 安装
pnpm add -g openclaw@latest
# 或手动指定扩展路径
openclaw plugins install --registry=https://registry.npmmirror.com <plugin-name>

原因：对话上下文超过模型最大 token 限制。
解决：①在模型配置中增加 "contextWindow" 值；②使用 /clear 清除历史；③减少工作区文件注入量。

原因：会话自动携带了大量历史上下文，消耗大量 token。
解决：①定期新建会话；②在配置中设置 "maxHistoryMessages" 限制携带的历史条数。

原因：工作区注入了大量无关文件到系统提示中。
解决：在工作区配置中使用 .clawignore 排除不需要的文件；减小工作区范围。

原因：每次请求都重新发现所有工具，拖慢响应。
解决：升级到支持工具缓存的版本；或手动精简已注册的工具列表。

原因：系统提示中注入的日期不含星期信息，AI 无法正确回答 "今天星期几"。
解决：升级到已修复的版本；或在自定义系统提示中手动加入日期格式。

原因：通过 Open WebUI 路由 Ollama 时，工具调用后流被截断。
解决：直接连接 Ollama API 而非通过 WebUI 中转；或升级 Open WebUI 到最新版。

原因：版本升级引入多个回归问题。
解决：

# 回退到已知稳定版本
npm install -g openclaw@2026.3.3
# 或完全重装
npm uninstall -g openclaw
npm cache clean --force
npm install -g openclaw@latest

原因：Gateway 降级状态下内存索引无法构建。
解决：强制重启 Gateway 并重建索引：

openclaw gateway stop
rm -rf ~/.openclaw/workspace/indexes/
openclaw gateway start

原因：OpenClaw 存在多个安全加固需求。
解决：①始终更新到最新版本；②不在公网暴露 Gateway 端口；③使用环境变量管理 API Key；④限制 exec 工具权限范围。

原因：中文界面翻译不完整或有误。
解决：可在 GitHub 上提交翻译改进 PR；OpenClaw 支持国际化，可参与 i18n 贡献。