故障排查 🔧
当 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 probe | Gateway 发现 + 可达性(本地 + 远程目标) | 当你怀疑正在探测错误的 gateway 时 |
| openclaw channels status --probe | 向运行中的 gateway 请求 channel(频道)状态(可选探测) | 当 gateway 可达但 channels 异常时 |
| openclaw gateway status | Supervisor(监管器)状态(launchd/systemd/schtasks)、运行时 PID/退出、最后的 gateway 错误 | 当服务"看起来已加载"但没有运行时 |
| openclaw logs --follow | 实时日志(运行时问题的最佳信号) | 需要实际的故障原因时 |
分享输出: 优先使用 openclaw status --all(它会编辑 token(令牌))。如果粘贴 openclaw status,考虑先设置 OPENCLAW_SHOW_SECRETS=0(token 预览)。
另见:Health checks 和 Logging。
常见问题
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
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.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 控制。
有关格式、配置和访问的完整概述,请参阅 /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=remote,CLI 默认 为远程 URL。服务仍可能在本地运行,但您的 CLI 可能正在探测错误的地方。使用 openclaw gateway status 查看服务的解析端口 + 探测目标(或传递 --url)。
- 当服务看起来在运行但端口关闭时,openclaw gateway status 和 openclaw 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 status 说 bind=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 在响应中途被中断。
原因:
- 用户发送 stop、abort、esc、wait 或 exit
- 超时超出
- 进程崩溃
修复: 只需发送另一条消息。会话继续。
"Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5"
OpenClaw 有意拒绝 较旧/不安全的模型(尤其是那些更容易受到 prompt injection(提示注入)的模型)。如果您看到此错误,则不再支持该模型名称。
修复:
- 为 provider 选择 最新 模型并更新您的配置或 model alias(模型别名)。
- 如果您不确定哪些模型可用,运行 openclaw models list 或 openclaw models scan 并选择受支持的模型。
- 检查 gateway 日志以获取详细的失败原因。
另见:Models CLI 和 Model 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
如果 dmPolicy 是 pairing,未知发送者应该收到代码,他们的消息在批准之前被忽略。
检查 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 logs、openclaw health、openclaw status、openclaw gateway status 和 openclaw 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?
- git pull origin main && pnpm install
- openclaw doctor
- 检查 GitHub issues 或 Discord
- 临时解决方法: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.streamMode 是 partial 或 block 且 draft streaming 处于活动状态(私聊 + topics)。在这种情况下,Draft streaming 禁用 block streaming。
- 您的 minChars / coalesce 设置太高,因此块被合并。
- 模型发出一个大文本块(没有中途刷新点)。
修复清单:
- 将 block streaming 设置放在 agents.defaults 下,而不是根目录。
- 如果您想要真正的多消息块回复,设置 channels.telegram.streamMode: "off"。
- 在调试时使用较小的 chunk/coalesce 阈值。
参见 Streaming。
Discord doesn't reply in my server even with requireMention: false. Why?
requireMention 仅在 channel 通过允许列表 之后 控制提及门控。 默认情况下 channels.discord.groupPolicy 是 allowlist,因此必须明确启用 guilds。 如果您设置 channels.discord.guilds.<guildId>.channels,则仅允许列出的 channels;省略它以允许 guild 中的所有 channels。
修复清单:
- 设置 channels.discord.groupPolicy: "open" 或 添加 guild allowlist 条目(可选添加 channel allowlist)。
- 在 channels.discord.guilds.<guildId>.channels 中使用 数字 channel IDs。
- 将 requireMention: false 放在 channels.discord.guilds 下(全局或每个 channel)。顶级 channels.discord.requireMention 不是受支持的键。
- 确保 bot 有 Message Content Intent 和 channel 权限。
- 运行 openclaw channels status --probe 获取审计提示。
文档:Discord、Channels 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 日)。
修复清单:
- 更新 OpenClaw:
- 如果您可以从源代码运行,拉取 main 并重新启动 gateway。
- 否则,等待包含 schema scrubber 的下一个版本。
- 避免不支持的关键字,如 anyOf/oneOf/allOf、patternProperties、additionalProperties、minLength、maxLength、format 等。
- 如果您定义自定义工具,请将顶级 schema 保持为 type: "object",带有 properties 和简单枚举。
参见 Tools 和 TypeBox 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。
获取帮助
- 首先检查日志:/tmp/openclaw/(默认:openclaw-YYYY-MM-DD.log,或您配置的 logging.file)
- 在 GitHub 上搜索现有问题
- 打开新问题并提供:
- 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