故障排查 🔧

当 OpenClaw 出现异常时,以下是修复方法。

如果您只想要快速分类方法,请从 FAQ 的 前 60 秒 开始。本页面将深入介绍运行时故障和诊断。

特定提供商的快捷方式:/channels/troubleshooting

状态与诊断

快速分类命令(按顺序):

命令告诉你什么何时使用
openclaw status本地摘要:OS + 更新、gateway 可达性/模式、服务、agents/sessions、provider 配置状态首次检查,快速概览
openclaw status --all完整本地诊断(只读、可粘贴、相对安全)包括日志尾部需要分享调试报告时
openclaw status --deep运行 gateway health checks(健康检查)(包括 provider 探测;需要可达的 gateway)当"已配置"不意味着"正常工作"时
openclaw gateway probeGateway 发现 + 可达性(本地 + 远程目标)当你怀疑正在探测错误的 gateway 时
openclaw channels status --probe向运行中的 gateway 请求 channel(频道)状态(可选探测)当 gateway 可达但 channels 异常时
openclaw gateway statusSupervisor(监管器)状态(launchd/systemd/schtasks)、运行时 PID/退出、最后的 gateway 错误当服务"看起来已加载"但没有运行时
openclaw logs --follow实时日志(运行时问题的最佳信号)需要实际的故障原因时

分享输出: 优先使用 openclaw status --all(它会编辑 token(令牌))。如果粘贴 openclaw status,考虑先设置 OPENCLAW_SHOW_SECRETS=0(token 预览)。

另见:Health checksLogging

常见问题

No API key found for provider "anthropic"

这意味着 agent 的 auth store(身份验证存储)为空 或缺少 Anthropic 凭据。 Auth(身份验证)是 每个 agent,因此新 agent 不会继承主 agent 的密钥。

修复选项:

  • 重新运行 onboarding(入门引导)并为该 agent 选择 Anthropic
  • 或在 gateway host(主机) 上粘贴 setup-token(设置令牌):
    openclaw models auth setup-token --provider anthropic
    
  • 或将 auth-profiles.json 从主 agent 目录复制到新 agent 目录。

验证:

openclaw models status

OAuth token refresh failed (Anthropic Claude subscription)

这意味着存储的 Anthropic OAuth token(令牌)已过期且刷新失败。 如果您使用 Claude 订阅(没有 API 密钥),最可靠的修复方法是切换到 Claude Code setup-token 并在 gateway host 上粘贴。

推荐(setup-token):

# 在 gateway host 上运行(粘贴 setup-token)
openclaw models auth setup-token --provider anthropic
openclaw models status

如果您在其他地方生成了 token:

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

更多详情:AnthropicOAuth

Control UI fails on HTTP ("device identity required" / "connect failed")

如果您通过纯 HTTP 打开 dashboard(控制面板)(例如 http://<lan-ip>:18789/http://<tailscale-ip>:18789/),浏览器在 非安全上下文 中运行并阻止 WebCrypto,因此无法生成设备身份。

修复:

  • 通过 Tailscale Serve 优先使用 HTTPS。
  • 或在 gateway host 上本地打开:http://127.0.0.1:18789/
  • 如果必须保持 HTTP,启用 gateway.controlUi.allowInsecureAuth: true 并使用 gateway token(仅 token;无设备身份/配对)。参见 Control UI

CI Secrets Scan Failed

这意味着 detect-secrets 发现了尚未在 baseline(基线)中的新候选项。 遵循 Secret scanning

Service Installed but Nothing is Running

如果 gateway service(服务)已安装但进程立即退出,服务可能显示"已加载"但没有运行。

检查:

openclaw gateway status
openclaw doctor

Doctor/service 将显示运行时状态(PID/最后退出)和日志提示。

日志:

  • 优先:openclaw logs --follow
  • 文件日志(始终):/tmp/openclaw/openclaw-YYYY-MM-DD.log(或您配置的 logging.file
  • macOS LaunchAgent(如果已安装):$OPENCLAW_STATE_DIR/logs/gateway.loggateway.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 控制。

有关格式、配置和访问的完整概述,请参阅 /logging

"Gateway start blocked: set gateway.mode=local"

这意味着配置存在但 gateway.mode 未设置(或不是 local),因此 Gateway 拒绝启动。

修复(推荐):

  • 运行向导并将 Gateway 运行模式设置为 Local(本地)
    openclaw configure
    
  • 或直接设置:
    openclaw config set gateway.mode local
    

如果您打算运行远程 Gateway:

  • 设置远程 URL 并保持 gateway.mode=remote
    openclaw config set gateway.mode remote
    openclaw config set gateway.remote.url "wss://gateway.example.com"
    

仅限临时/开发: 传递 --allow-unconfigured 以在没有 gateway.mode=local 的情况下启动 gateway。

还没有配置文件? 运行 openclaw setup 创建启动配置,然后重新运行 gateway。

Service Environment (PATH + runtime)

Gateway service(服务)使用 最小 PATH 运行以避免 shell/manager 混乱:

  • macOS:/opt/homebrew/bin/usr/local/bin/usr/bin/bin
  • Linux:/usr/local/bin/usr/bin/bin

这有意排除版本管理器(nvm/fnm/volta/asdf)和包管理器(pnpm/npm),因为服务不加载您的 shell init(初始化)。像 DISPLAY 这样的运行时变量应该存在于 ~/.openclaw/.env 中(由 gateway 早期加载)。 host=gateway 上的 Exec 运行会将您的 login-shell PATH 合并到 exec 环境中,因此缺少工具通常意味着您的 shell init 没有导出它们(或设置 tools.exec.pathPrepend)。参见 /tools/exec

WhatsApp + Telegram channels 需要 Node;不支持 Bun。如果您的服务是使用 Bun 或版本管理的 Node 路径安装的,运行 openclaw doctor 迁移到系统 Node 安装。

Skill missing API key in sandbox

症状: Skill(技能)在 host 上工作但在 sandbox(沙箱)中失败并缺少 API 密钥。

原因: sandbox exec 在 Docker 内运行, 继承 host process.env

修复:

  • 设置 agents.defaults.sandbox.docker.env(或每个 agent 的 agents.list[].sandbox.docker.env
  • 或将密钥烘焙到您的自定义 sandbox 镜像中
  • 然后运行 openclaw sandbox recreate --agent <id>(或 --all

Service Running but Port Not Listening

如果服务报告 running(运行中) 但 gateway 端口上没有监听,Gateway 可能拒绝绑定。

"running" 在这里的含义

  • Runtime: running 意味着您的 supervisor(launchd/systemd/schtasks)认为进程处于活动状态。
  • RPC probe 意味着 CLI 实际上可以连接到 gateway WebSocket 并调用 status
  • 始终相信 Probe target: + Config (service): 作为"我们实际尝试了什么?"行。

检查:

  • gateway.mode 对于 openclaw gateway 和服务必须是 local
  • 如果您设置了 gateway.mode=remoteCLI 默认 为远程 URL。服务仍可能在本地运行,但您的 CLI 可能正在探测错误的地方。使用 openclaw gateway status 查看服务的解析端口 + 探测目标(或传递 --url)。
  • 当服务看起来在运行但端口关闭时,openclaw gateway statusopenclaw doctor 会从日志中显示 最后的 gateway 错误
  • 非环回绑定(lan/tailnet/custom,或环回不可用时的 auto)需要 auth(身份验证):gateway.auth.token(或 OPENCLAW_GATEWAY_TOKEN)。
  • gateway.remote.token 仅用于远程 CLI 调用;它 启用本地 auth。
  • gateway.token 被忽略;使用 gateway.auth.token

如果 openclaw gateway status 显示配置不匹配

  • Config (cli): ...Config (service): ... 通常应该匹配。
  • 如果它们不匹配,您几乎肯定在编辑一个配置而服务正在运行另一个。
  • 修复:从您希望服务使用的相同 --profile / OPENCLAW_STATE_DIR 重新运行 openclaw gateway install --force

如果 openclaw gateway status 报告服务配置问题

  • Supervisor 配置(launchd/systemd/schtasks)缺少当前默认值。
  • 修复:运行 openclaw doctor 更新它(或 openclaw gateway install --force 进行完全重写)。

如果 Last gateway error: 提到 "refusing to bind … without auth"

  • 您将 gateway.bind 设置为非环回模式(lan/tailnet/custom,或环回不可用时的 auto)但没有配置 auth。
  • 修复:设置 gateway.auth.mode + gateway.auth.token(或导出 OPENCLAW_GATEWAY_TOKEN)并重新启动服务。

如果 openclaw gateway statusbind=tailnet 但未找到 tailnet 接口

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

如果 Probe note: 说探测使用环回

  • 对于 bind=lan,这是预期的:gateway 监听 0.0.0.0(所有接口),环回仍应在本地连接。
  • 对于远程客户端,使用真实的 LAN IP(不是 0.0.0.0)加端口,并确保配置了 auth。

Address Already in Use (Port 18789)

这意味着某些东西已经在 gateway 端口上监听。

检查:

openclaw gateway status

它将显示监听器和可能的原因(gateway 已在运行、SSH 隧道)。 如果需要,停止服务或选择不同的端口。

Extra Workspace Folders Detected

如果您从较旧的安装升级,磁盘上可能仍有 ~/openclaw。 多个 workspace(工作区)目录可能导致令人困惑的 auth 或状态漂移,因为只有一个 workspace 处于活动状态。

修复: 保留单个活动 workspace 并归档/删除其余。参见 Agent workspace

Main chat running in a sandbox workspace

症状:pwd 或文件工具显示 ~/.openclaw/sandboxes/...,尽管您期望 host workspace。

原因: agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey(默认 "main")。 Group/channel sessions(会话)使用它们自己的键,因此它们被视为 non-main 并获得 sandbox workspaces。

修复选项:

  • 如果您希望 agent 使用 host workspaces:设置 agents.list[].sandbox.mode: "off"
  • 如果您希望在 sandbox 内访问 host workspace:为该 agent 设置 workspaceAccess: "rw"

"Agent was aborted"

Agent 在响应中途被中断。

原因:

  • 用户发送 stopabortescwaitexit
  • 超时超出
  • 进程崩溃

修复: 只需发送另一条消息。会话继续。

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

OpenClaw 有意拒绝 较旧/不安全的模型(尤其是那些更容易受到 prompt injection(提示注入)的模型)。如果您看到此错误,则不再支持该模型名称。

修复:

  • 为 provider 选择 最新 模型并更新您的配置或 model alias(模型别名)。
  • 如果您不确定哪些模型可用,运行 openclaw models listopenclaw models scan 并选择受支持的模型。
  • 检查 gateway 日志以获取详细的失败原因。

另见:Models CLIModel providers

Messages Not Triggering

检查 1: 发送者是否在允许列表中?

openclaw status

在输出中查找 AllowFrom: ...

检查 2: 对于群聊,是否需要提及?

# 消息必须匹配 mentionPatterns 或明确提及;默认值存在于 channel groups/guilds 中。
# Multi-agent:`agents.list[].groupChat.mentionPatterns` 覆盖全局 patterns。
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

检查 3: 检查日志

openclaw logs --follow
# 或如果您想要快速过滤器:
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

Pairing Code Not Arriving

如果 dmPolicypairing,未知发送者应该收到代码,他们的消息在批准之前被忽略。

检查 1: 是否已有待处理请求在等待?

openclaw pairing list <channel>

待处理的 DM pairing(配对)请求默认限制为每个 channel 3 个。如果列表已满,新请求将不会生成代码,直到批准或过期。

检查 2: 请求是否已创建但未发送回复?

openclaw logs --follow | grep "pairing request"

检查 3: 确认该 channel 的 dmPolicy 不是 open/allowlist

Image + Mention Not Working

已知问题:当您发送图像时 包含提及(没有其他文本),WhatsApp 有时不包括提及 metadata(元数据)。

解决方法: 在提及中添加一些文本:

  • @openclaw + 图像
  • @openclaw check this + 图像

Session Not Resuming

检查 1: session 文件是否存在?

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

检查 2: 重置窗口是否太短?

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

检查 3: 是否有人发送了 /new/reset 或重置触发器?

Agent Timing Out

默认超时为 30 分钟。对于长任务:

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

或使用 process 工具将长命令后台运行。

WhatsApp Disconnected

# 检查本地状态(凭据、会话、排队事件)
openclaw status
# 探测运行中的 gateway + channels(WA 连接 + Telegram + Discord APIs)
openclaw status --deep

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

修复: 通常在 Gateway 运行时自动重新连接。如果您卡住了,重新启动 Gateway 进程(无论您如何监督它),或使用详细输出手动运行:

openclaw gateway --verbose

如果您已注销/取消链接:

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果 logout 无法完全删除所有内容
openclaw channels login --verbose       # 重新扫描 QR

Media Send Failing

检查 1: 文件路径是否有效?

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

检查 2: 是否太大?

  • 图像:最大 6MB
  • 音频/视频:最大 16MB
  • 文档:最大 100MB

检查 3: 检查 media 日志

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

High Memory Usage

OpenClaw 在内存中保留对话历史。

修复: 定期重启或设置 session 限制:

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

常见故障排查

"Gateway won't start — configuration invalid"

OpenClaw 现在在配置包含未知键、格式错误的值或无效类型时拒绝启动。 这是出于安全考虑的有意行为。

使用 Doctor 修复:

openclaw doctor
openclaw doctor --fix

注意:

  • openclaw doctor 报告每个无效条目。
  • openclaw doctor --fix 应用迁移/修复并重写配置。
  • 诊断命令如 openclaw logsopenclaw healthopenclaw statusopenclaw gateway statusopenclaw gateway probe 即使配置无效也仍然运行。

"All models failed" — what should I check first?

  • Credentials(凭据) 为正在尝试的 provider(s) 提供(auth profiles + env vars)。
  • Model routing(模型路由):确认 agents.defaults.model.primary 和 fallbacks(备用)是您可以访问的模型。
  • Gateway logs/tmp/openclaw/… 中查找确切的 provider 错误。
  • Model status:使用 /model status(聊天)或 openclaw models status(CLI)。

I'm running on my personal WhatsApp number — why is self-chat weird?

启用 self-chat mode(自聊模式)并将您自己的号码加入允许列表:

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

参见 WhatsApp setup

WhatsApp logged me out. How do I re‑auth?

再次运行 login 命令并扫描 QR 码:

openclaw channels login

Build errors on main — what's the standard fix path?

  1. git pull origin main && pnpm install
  2. openclaw doctor
  3. 检查 GitHub issues 或 Discord
  4. 临时解决方法:checkout 较旧的 commit

npm install fails (allow-build-scripts / missing tar or yargs). What now?

如果您从源代码运行,请使用 repo 的包管理器:pnpm(首选)。 Repo 声明 packageManager: "pnpm@…"

典型恢复:

git status   # 确保您在 repo 根目录
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

原因:pnpm 是此 repo 的配置包管理器。

How do I switch between git installs and npm installs?

使用 website installer(网站安装程序) 并使用 flag 选择安装方法。它就地升级并重写 gateway service 以指向新安装。

切换 到 git install

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

切换 到 npm global

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

注意:

  • Git flow 仅在 repo 干净时才 rebase。首先 commit 或 stash 更改。
  • 切换后,运行:
    openclaw doctor
    openclaw gateway restart
    

Telegram block streaming isn't splitting text between tool calls. Why?

Block streaming(块流式传输)仅发送 已完成的文本块。您看到单条消息的常见原因:

  • agents.defaults.blockStreamingDefault 仍然是 "off"
  • channels.telegram.blockStreaming 设置为 false
  • channels.telegram.streamModepartialblock 且 draft streaming 处于活动状态(私聊 + topics)。在这种情况下,Draft streaming 禁用 block streaming。
  • 您的 minChars / coalesce 设置太高,因此块被合并。
  • 模型发出一个大文本块(没有中途刷新点)。

修复清单:

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

参见 Streaming

Discord doesn't reply in my server even with requireMention: false. Why?

requireMention 仅在 channel 通过允许列表 之后 控制提及门控。 默认情况下 channels.discord.groupPolicyallowlist,因此必须明确启用 guilds。 如果您设置 channels.discord.guilds.<guildId>.channels,则仅允许列出的 channels;省略它以允许 guild 中的所有 channels。

修复清单:

  1. 设置 channels.discord.groupPolicy: "open" 添加 guild allowlist 条目(可选添加 channel allowlist)。
  2. channels.discord.guilds.<guildId>.channels 中使用 数字 channel IDs
  3. requireMention: false 放在 channels.discord.guilds (全局或每个 channel)。顶级 channels.discord.requireMention 不是受支持的键。
  4. 确保 bot 有 Message Content Intent 和 channel 权限。
  5. 运行 openclaw channels status --probe 获取审计提示。

文档:DiscordChannels troubleshooting

Cloud Code Assist API error: invalid tool schema (400). What now?

这几乎总是 tool schema(工具架构)兼容性 问题。Cloud Code Assist endpoint 接受严格的 JSON Schema 子集。OpenClaw 在当前 main 中清理/规范化工具架构,但修复尚未在最后一个版本中(截至 2026 年 1 月 13 日)。

修复清单:

  1. 更新 OpenClaw
    • 如果您可以从源代码运行,拉取 main 并重新启动 gateway。
    • 否则,等待包含 schema scrubber 的下一个版本。
  2. 避免不支持的关键字,如 anyOf/oneOf/allOfpatternPropertiesadditionalPropertiesminLengthmaxLengthformat 等。
  3. 如果您定义自定义工具,请将顶级 schema 保持为 type: "object",带有 properties 和简单枚举。

参见 ToolsTypeBox schemas

macOS 特定问题

App Crashes when Granting Permissions (Speech/Mic)

如果应用在您点击隐私提示上的"允许"时消失或显示"Abort trap 6":

修复 1:重置 TCC Cache(缓存)

tccutil reset All bot.molt.mac.debug

修复 2:强制使用新 Bundle ID 如果重置不起作用,在 scripts/package-mac-app.sh 中更改 BUNDLE_ID(例如,添加 .test 后缀)并重建。这迫使 macOS 将其视为新应用。

Gateway stuck on "Starting..."

应用连接到端口 18789 上的本地 gateway。如果它保持卡住:

修复 1:停止 supervisor(首选) 如果 gateway 由 launchd 监督,杀死 PID 只会重新生成它。首先停止 supervisor:

openclaw gateway status
openclaw gateway stop
# 或:launchctl bootout gui/$UID/bot.molt.gateway(替换为 bot.molt.<profile>;旧版 com.openclaw.* 仍然有效)

修复 2:端口繁忙(查找监听器)

lsof -nP -iTCP:18789 -sTCP:LISTEN

如果它是一个非监督进程,首先尝试优雅停止,然后升级:

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

修复 3:检查 CLI 安装 确保全局 openclaw CLI 已安装并与应用版本匹配:

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

调试模式

获取详细日志记录:

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

日志位置

日志位置
Gateway 文件日志(结构化)/tmp/openclaw/openclaw-YYYY-MM-DD.log(或 logging.file
Gateway service 日志(supervisor)macOS:$OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log(默认:~/.openclaw/logs/...;profiles 使用 ~/.openclaw-<profile>/logs/...
Linux:journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
Windows:schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
Session 文件$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
Media cache$OPENCLAW_STATE_DIR/media/
Credentials$OPENCLAW_STATE_DIR/credentials/

Health Check(健康检查)

# Supervisor + 探测目标 + 配置路径
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

⚠️ 这会丢失所有会话并需要重新配对 WhatsApp。

获取帮助

  1. 首先检查日志:/tmp/openclaw/(默认:openclaw-YYYY-MM-DD.log,或您配置的 logging.file
  2. 在 GitHub 上搜索现有问题
  3. 打开新问题并提供:
    • OpenClaw 版本
    • 相关日志片段
    • 重现步骤
    • 您的配置(编辑机密!)

"您试过关闭再打开吗?" — 每个 IT 人员

🦞🔧

Browser Not Starting (Linux)

如果您看到 "Failed to start Chrome CDP on port 18800"

最可能的原因: Ubuntu 上的 Snap 打包的 Chromium。

快速修复: 改为安装 Google Chrome:

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"
  }
}

完整指南: 参见 browser-linux-troubleshooting