6.24 故障排除

网关与运维网关与运维

🔧 当 OpenClaw 出现异常时，这里提供了系统的诊断和修复指南。

状态与诊断

快速诊断 Gateway/Agent 健康状态的命令：

openclaw status
openclaw status --all
openclaw status --deep
openclaw gateway probe
openclaw channels status --probe
openclaw gateway status
openclaw logs --follow
提示
status --all 命令会自动隐藏敏感信息，可以安全地粘贴到 issue 中。如需手动控制，可设置 OPENCLAW_SHOW_SECRETS=0。

常见问题

找不到 API 密钥 ("anthropic")

认证配置是按 agent 设置的。修复方法：

  • 运行入门向导重新配置认证
  • 使用 openclaw models auth setup-token --provider anthropic
  • 从其他设备复制 auth-profiles.json

验证认证状态：

openclaw models status

OAuth 令牌刷新失败

在网关主机上切换到 Claude Code 令牌设置：

openclaw models auth setup-token --provider anthropic

Control UI 在 HTTP 下失败

浏览器在非安全上下文中会阻止 WebCrypto。解决方案：

  • 使用 Tailscale Serve（提供 HTTPS）
  • 访问本地回环地址：http://127.0.0.1:18789/
  • 或在配置中启用：gateway.controlUi.allowInsecureAuth: true

CI 密钥扫描失败

参考 网关安全 文档中的 detect-secrets 基准指南。

服务已安装但未运行

检查网关状态和诊断：

openclaw gateway status
openclaw doctor

日志位置：

  • 通用：/tmp/openclaw/openclaw-YYYY-MM-DD.log
  • macOS：LaunchAgent 日志在 $OPENCLAW_STATE_DIR/logs/
  • Linux：journalctl --user -u openclaw-gateway
  • Windows：schtasks /Query 查看任务

启用调试日志：在配置中设置 logging.level: "debug"

网关启动被阻止：需要设置 gateway.mode=local

运行配置向导或手动设置：

openclaw configure
# 或
openclaw config set gateway.mode local

远程模式配置：

openclaw config set gateway.mode remote
openclaw config set gateway.remote.url https://your-gateway-url

临时跳过检查（不推荐）：

openclaw --allow-unconfigured

服务环境问题（PATH 和运行时）

服务环境的 PATH 是最小化的，不包含 nvm/fnm/volta/asdf。WhatsApp/Telegram 需要 Node.js（不支持 Bun）。使用 openclaw doctor 迁移到系统 Node。

沙箱中的 Skill 缺少 API 密钥

沙箱不继承 process.env。修复方法：

# 在配置中设置环境变量
agents.defaults.sandbox.docker.env:
  MY_API_KEY: "your-key-here"

# 然后重建沙箱
openclaw sandbox recreate --agent <name>

或使用包含密钥的自定义镜像。

服务运行中但端口未监听

"运行中"不等于"已绑定"。检查项：

  • 确认 gateway.mode 配置正确
  • 检查 CLI 配置与服务配置是否不一致
  • 非回环地址绑定需要认证（gateway.auth.token）
  • 确认 Tailscale 接口可用
  • 查看探测日志中的 Probe note:

地址已被占用（端口 18789）

识别并停止占用端口的进程：

openclaw gateway status
# 查看是哪个进程在监听
lsof -iTCP:18789

# 停止服务或更改端口
openclaw gateway stop
# 或
openclaw config set gateway.port 18790

检测到多个工作区目录

多个 ~/openclaw 目录会导致状态不一致。保持仅一个活跃工作区。

主聊天在沙箱工作区运行

由于为群组会话设置了 sandbox.mode: "non-main" 导致。修复：

# 禁用沙箱或允许读写访问
sandbox.mode: "off"
# 或
workspaceAccess: "rw"

代理被中止

由用户中止、超时或崩溃引起。会话会继续保留，重新发送消息即可。

未知模型：anthropic/claude-haiku-3-5

模型因安全原因被拒绝。修复：

openclaw models list
openclaw models scan
# 选择支持的最新模型

消息未触发响应

检查以下项：

  • 白名单配置：openclaw status
  • 提及要求：grep mentionPatterns
  • 日志中的阻止信息：grep "blocked|skip|unauthorized"

配对码未收到

每个渠道的待处理请求上限为 3 个。检查：

openclaw pairing list
# 查看日志中的配对请求
openclaw logs | grep "pairing request"
# 确认 dmPolicy 不是 open 或 allowlist

WhatsApp 图片+提及不工作

WhatsApp 在发送仅包含 @mention 的图片时会省略提及元数据。解决方案：添加文本，例如：@openclaw 检查这个

会话未恢复

检查项：

  • 会话文件是否存在
  • session.reset 配置（如 idleMinutes: 10080）
  • 重置触发器（如 /new 命令）

代理超时

默认超时 30 分钟。延长超时时间：

# 在配置中设置（单位：秒）
reply.timeoutSeconds: 3600

或使用 process 工具处理长时间任务。

WhatsApp 已断开连接

检查连接状态：

openclaw status
openclaw status --deep
openclaw logs | grep "connection|disconnect"

# 重启网关或重新登录
openclaw gateway restart
openclaw channels login --verbose

媒体发送失败

验证以下项：

  • 文件路径正确
  • 大小限制：图片 ≤6MB，音频/视频 ≤16MB，文档 ≤100MB
  • 查看媒体日志：openclaw logs | grep "media|fetch|download"

内存使用过高

历史记录保存在内存中。解决方案：

  • 定期重启服务
  • 设置历史记录限制：session.historyLimit: 100

常见故障排除

网关无法启动 — 配置无效

Doctor 可以修复未知键或格式错误的值：

openclaw doctor --fix

所有模型都失败

检查项：

  • 凭证配置
  • 模型路由配置（agents.defaults.model.primary）
  • 网关日志
  • openclaw models status

WhatsApp 自聊异常

启用自聊模式并在配置中将自己的号码加入白名单：

selfChatMode: true

WhatsApp 已登出

重新认证：

openclaw channels login

main 分支构建错误

更新并修复：

git pull
pnpm install
openclaw doctor

如果问题持续，查看 GitHub/Discord，或回滚到较早的提交。

npm install 失败

使用声明的包管理器 pnpm：

pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

在 git/npm 安装之间切换

使用安装脚本的标志：

# Git 安装
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

# npm 安装（默认）
curl -fsSL https://openclaw.ai/install.sh | bash

# 然后运行
openclaw doctor
openclaw gateway restart

Telegram 块流式传输未分割

确保配置正确：

agents.defaults.blockStreamingDefault: "on"
channels.telegram.streamMode: "off"

避免在话题中使用草稿流式传输。调整 minChars 或合并设置。

Discord 不回复（尽管 requireMention: false）

groupPolicy 默认为 allowlist。修复：

# 设置为 open 或添加白名单
groupPolicy: "open"
# 或添加服务器/频道 ID（使用数字 ID）

# requireMention 应放在 channels.discord.guilds 下
# 确认机器人权限 + 消息内容意图已启用

Cloud Code Assist 400 错误

架构不兼容。解决方案：

  • 更新到最新的 OpenClaw（main 分支包含清理器）
  • 避免使用 anyOf、patternProperties、format 等
  • 保持工具架构简单：type: "object" + properties

macOS 特定问题

App 在隐私提示时崩溃

重置 TCC 缓存或更改 Bundle ID：

tccutil reset All bot.molt.mac.debug
# 或更改 BUNDLE_ID 并重建

Gateway 卡在"启动中..."

先停止监督器：

openclaw gateway stop
# 或
launchctl bootout gui/$(id -u)/bot.molt.openclaw-gateway

# 检查端口占用
lsof -iTCP:18789

# 确认 CLI 版本与 app 匹配

调试模式

在配置中设置追踪日志级别：

logging.level: "trace"

使用 --verbose 标志将日志镜像到 stdout。

日志位置

  • 网关文件日志：/tmp/openclaw/openclaw-YYYY-MM-DD.log（或 logging.file 配置）
  • macOS 服务日志：$OPENCLAW_STATE_DIR/logs/
  • Linux 服务日志：journalctl --user -u openclaw-gateway
  • Windows 服务日志：schtasks /Query
  • 会话数据：$OPENCLAW_STATE_DIR/agents/<agent>/sessions/
  • 媒体缓存：$OPENCLAW_STATE_DIR/media/
  • 凭证：$OPENCLAW_STATE_DIR/credentials/

健康检查

完整的健康检查命令集：

openclaw gateway status
openclaw gateway status --deep
openclaw health --json
openclaw health --verbose
lsof -iTCP:18789
openclaw logs --follow
tail -20 /tmp/openclaw/openclaw-*.log

重置所有内容

警告
这是核心选项！将丢失所有会话历史和配置，WhatsApp 需要重新配对。
openclaw gateway stop
trash ~/.openclaw  # 或 rm -rf ~/.openclaw
openclaw channels login
openclaw gateway restart

Linux 浏览器无法启动

可能是 Snap Chromium 冲突。修复：

# 安装 Google Chrome
sudo apt install google-chrome-stable

# 在配置中设置路径
browser.executablePath: "/usr/bin/google-chrome-stable"

获取帮助

提交问题时，请提供：

  • OpenClaw 版本
  • 相关日志片段（/tmp/openclaw/...）
  • 重现步骤
  • 已隐藏敏感信息的配置

首先查看 /tmp/openclaw/ 日志，然后搜索 GitHub issues。

提示
"你试过关闭再打开吗？" —— 每个 IT 人员 🦞🔧