​

故障排除 🔧

​

状态与诊断

​

常见问题

​

No API key found for provider “anthropic”

• 重新运行新手引导，为该智能体选择 Anthropic。
• 或者在 Gateway网关主机上粘贴 setup-token：
  复制

  openclaw models auth setup-token --provider anthropic
  
• 或将主智能体目录中的 auth-profiles.json 复制到新智能体目录。

openclaw models status

​

OAuth token refresh failed (Anthropic Claude subscription)

# 在 Gateway网关主机上运行（粘贴 setup-token）
openclaw models auth setup-token --provider anthropic
openclaw models status

openclaw models auth paste-token --provider anthropic
openclaw models status

​

控制面板在 HTTP 下失败（“device identity required” / “connect failed”）

• 优先通过 Tailscale Serve 使用 HTTPS。
• 或在 Gateway网关主机上本地打开：http://127.0.0.1:18789/。
• 如果必须使用 HTTP，启用 gateway.controlUi.allowInsecureAuth: true 并 使用 Gateway网关令牌（仅令牌；无设备身份/配对）。参见 控制面板。

​

CI 密钥扫描失败

​

服务已安装但未运行

openclaw gateway status
openclaw doctor

• 推荐：openclaw logs --follow
• 文件日志（始终可用）：/tmp/openclaw/openclaw-YYYY-MM-DD.log（或你配置的 logging.file）
• macOS LaunchAgent（如已安装）：$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log
• Linux systemd（如已安装）：journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows：schtasks /Query /TN "OpenClaw Gateway网关 (<profile>)" /V /FO LIST

• 提高文件日志详细级别（持久化 JSONL）：
  复制

  { "logging": { "level": "debug" } }
  
• 提高控制台日志详细级别（仅 TTY 输出）：
  复制

  { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
  
• 小提示：--verbose 仅影响控制台输出。文件日志仍由 logging.level 控制。

​

“Gateway网关 start blocked: set gateway.mode=local”

• 运行向导并将 Gateway网关运行模式设置为 Local：
  复制

  openclaw configure
  
• 或直接设置：
  复制

  openclaw config set gateway.mode local
  

• 设置远程 URL 并保持 gateway.mode=remote：
  复制

  openclaw config set gateway.mode remote
  openclaw config set gateway.remote.url "wss://gateway.example.com"
  

​

服务环境（PATH + 运行时）

• macOS：/opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
• Linux：/usr/local/bin、/usr/bin、/bin

​

Skills 在沙箱中缺少 API 密钥

• 设置 agents.defaults.sandbox.docker.env（或按智能体设置 agents.list[].sandbox.docker.env）
• 或将密钥内置到自定义沙箱镜像中
• 然后运行 openclaw sandbox recreate --agent <id>（或 --all）

​

服务在运行但端口未监听

• Runtime: running 表示你的管理器（launchd/systemd/schtasks）认为进程是活跃的。
• RPC probe 表示 CLI 实际上能够连接到 Gateway网关 WebSocket 并调用 status。
• 始终以 Probe target: + Config (service): 作为”我们实际尝试了什么？“的依据。

• gateway.mode 对于 openclaw gateway 和服务必须为 local。
• 如果你设置了 gateway.mode=remote，CLI 默认使用远程 URL。服务可能仍在本地运行，但你的 CLI 可能在探测错误的位置。使用 openclaw gateway status 查看服务解析的端口 + 探测目标（或传递 --url）。
• openclaw gateway status 和 openclaw doctor 会在服务看起来正在运行但端口未打开时显示最后一次 Gateway网关错误日志。
• 非 local loopback 绑定（lan/tailnet/custom，或 local loopback 不可用时的 auto）需要认证： gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• gateway.remote.token 仅用于远程 CLI 调用；它不会启用本地认证。
• gateway.token 会被忽略；请使用 gateway.auth.token。

• Config (cli): ... 和 Config (service): ... 通常应该一致。
• 如果不一致，几乎可以确定你在编辑一个配置而服务在运行另一个配置。
• 修复：从你希望服务使用的相同 --profile / OPENCLAW_STATE_DIR 重新运行 openclaw gateway install --force。

• 管理器配置（launchd/systemd/schtasks）缺少当前默认值。
• 修复：运行 openclaw doctor 更新配置（或 openclaw gateway install --force 完整重写）。

• 你将 gateway.bind 设置为非 local loopback 模式（lan/tailnet/custom，或 local loopback 不可用时的 auto）但未配置认证。
• 修复：设置 gateway.auth.mode + gateway.auth.token（或导出 OPENCLAW_GATEWAY_TOKEN）并重启服务。

• Gateway网关尝试绑定到 Tailscale IP（100.64.0.0/10）但主机上未检测到。
• 修复：在该机器上启动 Tailscale（或将 gateway.bind 改为 loopback/lan）。

• 对于 bind=lan 这是预期行为：Gateway网关监听 0.0.0.0（所有接口），local loopback 在本地仍可连接。
• 对于远程客户端，请使用真实的 LAN IP（不是 0.0.0.0）加端口，并确保已配置认证。

​

地址已被占用（端口 18789）

openclaw gateway status

​

检测到多余的工作区文件夹

​

主聊天在沙箱工作区中运行

• 如果你想让某个智能体使用主机工作区：设置 agents.list[].sandbox.mode: "off"。
• 如果你想在沙箱内访问主机工作区：为该智能体设置 workspaceAccess: "rw"。

​

“Agent was aborted”

• 用户发送了 stop、abort、esc、wait 或 exit
• 超时
• 进程崩溃

​

“Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5”

• 为该提供商选择一个最新模型，并更新你的配置或模型别名。
• 如果不确定有哪些可用模型，运行 openclaw models list 或 openclaw models scan 并选择一个受支持的模型。
• 检查 Gateway网关日志了解详细的失败原因。

​

消息未触发

openclaw status

# 消息必须匹配 mentionPatterns 或显式提及；默认值在渠道 groups/guilds 中。
# 多智能体：`agents.list[].groupChat.mentionPatterns` 覆盖全局模式。
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

openclaw logs --follow
# 或者快速过滤：
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

​

配对码未送达

openclaw pairing list <channel>

openclaw logs --follow | grep "pairing request"

​

图片 + 提及无法正常工作

• ❌ @openclaw + 图片
• ✅ @openclaw check this + 图片

​

会话未恢复

ls -la ~/.openclaw/agents/<agentId>/sessions/

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080 // 7 天
    }
  }
}

​

智能体超时

{
  "reply": {
    "timeoutSeconds": 3600 // 1 小时
  }
}

​

WhatsApp 断开连接

# 检查本地状态（凭据、会话、排队事件）
openclaw status
# 探测运行中的 Gateway网关 + 渠道（WA 连接 + Telegram + Discord API）
openclaw status --deep

# 查看最近的连接事件
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"

openclaw gateway --verbose

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果 logout 无法完全清除
openclaw channels login --verbose       # 重新扫描二维码

​

媒体发送失败

ls -la /path/to/your/image.jpg

• 图片：最大 6MB
• 音频/视频：最大 16MB
• 文档：最大 100MB

grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

​

内存使用过高

{
  "session": {
    "historyLimit": 100 // 保留的最大消息数
  }
}

​

常见故障排除

​

”Gateway网关 won’t start — configuration invalid”

openclaw doctor
openclaw doctor --fix

• openclaw doctor 会报告每个无效条目。
• openclaw doctor --fix 会应用迁移/修复并重写配置。
• 诊断命令如 openclaw logs、openclaw health、openclaw status、openclaw gateway status 和 openclaw gateway probe 即使配置无效也能运行。

​

“All models failed” — 我应该先检查什么？

• 正在使用的提供商是否存在凭据（认证配置文件 + 环境变量）。
• 模型路由：确认 agents.defaults.model.primary 和回退模型是你能访问的模型。
• /tmp/openclaw/… 中的 Gateway网关日志查看具体的提供商错误。
• 模型状态：使用 /model status（聊天中）或 openclaw models status（CLI）。

​

我用个人 WhatsApp 号码运行 — 为什么自聊行为异常？

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"],
    },
  },
}

​

WhatsApp 将我登出了。如何重新认证？

openclaw channels login

​

main 分支构建错误 — 标准修复路径是什么？

1. git pull origin main && pnpm install
2. openclaw doctor
3. 查看 GitHub issues 或 Discord
4. 临时解决方案：回退到较旧的提交

​

npm install 失败（allow-build-scripts / 缺少 tar 或 yargs）。怎么办？

git status   # 确保你在仓库根目录
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

​

如何在 git 安装和 npm 安装之间切换？

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

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

• git 流程仅在仓库干净时才会 rebase。请先提交或暂存更改。
• 切换后运行：
  复制

  openclaw doctor
  openclaw gateway restart
  

​

Telegram 块式流不在工具调用之间拆分文本。为什么？

• agents.defaults.blockStreamingDefault 仍为 "off"。
• channels.telegram.blockStreaming 设置为 false。
• channels.telegram.streamMode 为 partial 或 block 且草稿流处于活跃状态 （私聊 + 话题）。草稿流在此情况下会禁用块式流。
• 你的 minChars / coalesce 设置过高，导致块被合并。
• 模型输出了一个大型文本块（没有中途刷新点）。

1. 将块式流设置放在 agents.defaults 下，而不是根级别。
2. 如果你想要真正的多消息块式回复，设置 channels.telegram.streamMode: "off"。
3. 调试时使用较小的 chunk/coalesce 阈值。

​

Discord 在我的服务器中不回复，即使设置了 requireMention: false。为什么？

1. 设置 channels.discord.groupPolicy: "open" 或添加服务器白名单条目（可选添加频道白名单）。
2. 在 channels.discord.guilds.<guildId>.channels 中使用数字频道 ID。
3. 将 requireMention: false 放在 channels.discord.guilds 下方（全局或按频道）。 顶层 channels.discord.requireMention 不是受支持的键。
4. 确保机器人拥有 Message Content Intent 和频道权限。
5. 运行 openclaw channels status --probe 获取审计提示。

​

Cloud Code Assist API 错误：invalid tool schema (400)。怎么办？

1. 更新 OpenClaw：
   • 如果你能从源码运行，拉取 main 并重启 Gateway网关。
   • 否则，等待包含 schema 清洗器的下一个版本。
2. 避免不受支持的关键字，如 anyOf/oneOf/allOf、patternProperties、 additionalProperties、minLength、maxLength、format 等。
3. 如果你定义自定义工具，保持顶层 schema 为 type: "object"，带 properties 和简单枚举。

​

macOS 特定问题

​

授予权限时应用崩溃（语音/麦克风）

tccutil reset All bot.molt.mac.debug

​

Gateway网关卡在”Starting…”

openclaw gateway status
openclaw gateway stop
# 或：launchctl bootout gui/$UID/bot.molt.gateway（替换为 bot.molt.<profile>；旧版 com.openclaw.* 仍可用）

lsof -nP -iTCP:18789 -sTCP:LISTEN

kill -TERM <PID>
sleep 1
kill -9 <PID> # 最后手段

openclaw --version
npm install -g openclaw@<version>

​

调试模式

# 在配置中开启 trace 日志：
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# 然后运行 verbose 命令将调试输出镜像到标准输出：
openclaw gateway --verbose
openclaw channels login --verbose

​

日志位置

​

健康检查

# 管理器 + 探测目标 + 配置路径
openclaw gateway status
# 包含系统级扫描（旧版/多余服务、端口监听者）
openclaw gateway status --deep

# Gateway网关是否可达？
openclaw health --json
# 如果失败，附带连接详情重新运行：
openclaw health --verbose

# 默认端口上是否有监听？
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 最近活动（RPC 日志尾部）
openclaw logs --follow
# RPC 不可用时的备选方案
tail -20 /tmp/openclaw/openclaw-*.log

​

重置一切

openclaw gateway stop
# 如果你安装了服务并想全新安装：
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # 重新配对 WhatsApp
openclaw gateway restart           # 或：openclaw gateway

​

获取帮助

1. 先查看日志：/tmp/openclaw/（默认：openclaw-YYYY-MM-DD.log，或你配置的 logging.file）
2. 在 GitHub 上搜索现有 issues
3. 提交新 issue 并附上：
   • OpenClaw 版本
   • 相关日志片段
   • 复现步骤
   • 你的配置（脱敏！）

​

浏览器无法启动（Linux）

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}