故障排除 🔧

当 OpenClaw 表现异常时，这里是如何修复它的方法。

如果您只是想要一个快速分类方案，请从 FAQ 的前 60 秒开始。本页面深入探讨运行时故障和诊断。

状态和诊断

快速分类命令（按顺序）：

命令	告诉你什么	何时使用
`openclaw status`	本地摘要：操作系统 + 更新，网关可达性/模式，服务，代理/会话，提供者配置状态	首次检查，快速概览
`openclaw status --all`	完整本地诊断（只读，可粘贴，相对安全）包括日志尾部	当您需要分享调试报告时
`openclaw status --deep`	运行网关健康检查（包括提供者探测；需要可访问的网关）	当"已配置"不等于"正在工作"时
`openclaw gateway probe`	网关发现 + 可达性（本地 + 远程目标）	当您怀疑您正在探测错误的网关时
`openclaw channels status --probe`	向运行的网关询问通道状态（并可选地进行探测）	当网关可访问但通道表现异常时
`openclaw gateway status`	监督者状态（launchd/systemd/schtasks），运行时 PID/退出，最后的网关错误	当服务"看起来已加载"但没有运行任何东西时
`openclaw logs --follow`	实时日志（运行时问题的最佳信号）	当您需要实际失败原因时

分享输出： 优先使用 openclaw status --all（它会编辑令牌）。如果您粘贴 openclaw status，请考虑先设置 OPENCLAW_SHOW_SECRETS=0（令牌预览）。

另请参阅：健康检查和日志。

常见问题

未找到提供者 "anthropic" 的 API 密钥

这意味着 代理的身份验证存储为空 或缺少 Anthropic 凭据。身份验证是 按代理 的，所以新代理不会继承主代理的密钥。

修复选项：

重新运行入门设置并为该代理选择 Anthropic。

或在 网关主机 上粘贴一个设置令牌：

bash

openclaw models auth setup-token --provider anthropic

或从主代理目录复制 auth-profiles.json 到新代理目录。

验证：

bash

openclaw models status

OAuth 令牌刷新失败（Anthropic Claude 订阅）

这意味着存储的 Anthropic OAuth 令牌已过期且刷新失败。如果您使用的是 Claude 订阅（没有 API 密钥），最可靠的修复方法是切换到 Claude Code 设置令牌 或在 网关主机 上重新同步 Claude Code CLI OAuth。

推荐（设置令牌）：

bash

# 在网关主机上运行（运行 Claude Code CLI）
openclaw models auth setup-token --provider anthropic
openclaw models status

如果您在其他地方生成了令牌：

bash

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

如果您希望保持 OAuth 重用： 在网关主机上使用 Claude Code CLI 登录，然后运行 openclaw models status 将刷新的令牌同步到 OpenClaw 的身份验证存储中。

更多详细信息：Anthropic 和 OAuth。

控制 UI 在 HTTP 上失败（"需要设备身份" / "连接失败"）

如果您通过普通 HTTP 打开仪表板（例如 http://<lan-ip>:18789/ 或 http://<tailscale-ip>:18789/），浏览器在 非安全上下文 中运行并阻止 WebCrypto，因此无法生成设备身份。

修复：

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

Web UI 显示 "disconnected (1008): pairing required" 错误

当您访问 Web UI 时，可能会遇到以下错误：

disconnected (1008): pairing required

这个错误通常出现在 容器化部署（Docker、Kubernetes）中。

详细说明和解决方案： 见配对要求故障排除

快速修复（Docker）：

bash

docker compose run --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true
docker compose restart openclaw-gateway

快速修复（本地）：

bash

openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

Web UI 显示 "disconnected (1006): no reason" 错误

当您更新 Openclaw 后打开 Web 网关管理页面，可能会遇到以下错误：

disconnected (1006): no reason

问题原因：

WebSocket 错误码 1006 表示“异常关闭”，连接在没有收到正常关闭帧的情况下断开。

根因是 浏览器本地存储（localStorage）中缓存了旧版本的设备认证数据：

旧版本 Web UI 在浏览器中保存了设备身份密钥对和认证 token
更新到新版本后，Gateway 服务器重启
刷新页面时，新版前端复用了旧的 token
旧 token 与新版 Gateway 的验证逻辑不兼容，导致 WebSocket 握手失败

解决方案：

方法 1：清除浏览器本地存储（推荐）

方法 2：使用无痕/隐私模式

在新的无痕浏览窗口打开 Web UI，这样会使用全新的本地存储。

Chrome：Ctrl+Shift+N（Windows/Linux）或 Cmd+Shift+N（macOS）
Firefox：Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS）
Safari：文件 → 新建私密窗口

方法 3：清除站点数据（快捷方式）

Ctrl+Shift+Delete（Windows/Linux）或 Cmd+Shift+Delete（macOS），然后：

时间范围选择“全部时间”
仅勾选“Cookie 和站点数据”
点击清除

预防建议：

每次大版本更新后，如果遇到连接问题，优先尝试清除浏览器本地存储。

CI Secrets Scan 失败

这意味着 detect-secrets 找到了基准线中尚未包含的新候选项目。请遵循秘密扫描。

服务已安装但没有运行

如果网关服务已安装但进程立即退出，服务可能显示为"已加载"但实际上没有运行任何东西。

检查：

bash

openclaw gateway status
openclaw doctor

Doctor/服务将显示运行时状态（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）：
json
```
{ "logging": { "level": "debug" } }
```

提高控制台详细程度（仅 TTY 输出）：

json

{ "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }

快速提示：--verbose 仅影响 控制台 输出。文件日志仍由 logging.level 控制。

有关格式、配置和访问的完整概述，请参见 /logging。

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

这意味着配置存在但 gateway.mode 未设置（或不是 local），所以网关拒绝启动。

修复（推荐）：

运行向导并将网关运行模式设置为本地：
bash
```
openclaw configure
```
或直接设置：
bash
```
openclaw config set gateway.mode local
```

如果您打算运行远程网关：

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

bash

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

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

还没有配置文件？ 运行 openclaw setup 创建起始配置，然后重新运行网关。

服务环境（PATH + 运行时）

网关服务使用 最小 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 初始化。运行时变量如 DISPLAY 应该位于 ~/.openclaw/.env 中（由网关早期加载）。在 host=gateway 上运行的 Exec 将您的登录 shell PATH 合并到 exec 环境中，所以缺少工具通常意味着您的 shell 初始化没有导出它们（或设置 tools.exec.pathPrepend）。参见 /tools/exec。

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

技能在沙盒中缺少 API 密钥

症状： 技能在主机上工作但在沙盒中因缺少 API 密钥而失败。

原因： 沙盒化的 exec 在 Docker 内部运行，不继承主机的 process.env。

修复：

设置 agents.defaults.sandbox.docker.env（或按代理 agents.list[].sandbox.docker.env）
或将密钥嵌入到您的自定义沙盒镜像中
然后运行 openclaw sandbox recreate --agent <id>（或 --all）

服务运行但端口未监听

如果服务报告 运行中 但在网关端口上没有任何监听，网关可能拒绝绑定。

"运行中"在此处的含义

运行时：运行中 意味着您的监督程序（launchd/systemd/schtasks）认为进程是活动的。
RPC 探测 意味着 CLI 实际上可以连接到网关 WebSocket 并调用 status。
始终信任 探测目标： + 配置（服务）： 作为 "我们实际上尝试了什么？" 的行。

检查：

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

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

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

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

监督程序配置（launchd/systemd/schtasks）缺少当前默认值。
修复：运行 openclaw doctor 更新它（或 openclaw gateway install --force 进行完全重写）。

如果 最后网关错误： 提到 "拒绝绑定 … 没有认证"

您将 gateway.bind 设置为非回环模式（lan/tailnet/custom，或当回环不可用时的 auto）但没有启用认证。
修复：设置 gateway.auth.mode + gateway.auth.token（或导出 OPENCLAW_GATEWAY_TOKEN）并重启服务。

如果 openclaw gateway status 显示 bind=tailnet 但未找到 tailnet 接口

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

如果 探测注释： 说探测使用回环

这对 bind=lan 是预期的：网关监听 0.0.0.0（所有接口），而回环仍应能本地连接。
对于远程客户端，使用真实的局域网 IP（不是 0.0.0.0）加上端口，并确保已配置认证。

地址已在使用（端口 18789）

这意味着网关端口上已有其他程序在监听。

检查：

bash

openclaw gateway status

它将显示监听器和可能的原因（网关已在运行，SSH 隧道）。如有需要，停止服务或选择不同的端口。

检测到额外工作空间文件夹

如果您从旧版本升级，磁盘上可能仍有 ~/openclawot。多个工作空间目录可能导致混乱的认证或状态漂移，因为只有一个工作空间处于活动状态。

修复： 保留单个活动工作空间并归档/删除其余的。参见代理工作空间。

主聊天在沙盒工作空间中运行

症状：pwd 或文件工具显示 ~/.openclaw/sandboxes/... 即使您期望的是主机工作空间。

原因： agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认为 "main"）。群组/频道会话使用自己的键，因此它们被视为非主要会话并获得沙盒工作空间。

修复选项：

如果您希望代理使用主机工作空间：设置 agents.list[].sandbox.mode: "off"。
如果您希望在沙盒内访问主机工作空间：为该代理设置 workspaceAccess: "rw"。

"代理被中止"

代理在响应过程中被中断。

原因：

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

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

"代理回复前失败：未知模型：anthropic/claude-haiku-3-5"

openclaw 故意拒绝 较旧/不安全的模型（特别是那些更容易受到提示注入攻击的模型）。如果您看到此错误，则表示该模型名称已不再受支持。

修复：

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

另请参阅：模型 CLI 和模型提供者。

Messages Not Triggering

检查 1： 发送者是否在允许列表中？

bash

openclaw status

在输出中查找 AllowFrom: ...。

检查 2： 对于群聊，是否需要提及？

bash

# 消息必须匹配 mentionPatterns 或明确提及；默认值位于通道组/公会中。
# 多代理：`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}"

检查 3： 检查日志

bash

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

配对码未到达

如果 dmPolicy 是 pairing，未知发送者应该收到一个代码，在获得批准之前他们的消息会被忽略。

检查 1： 是否有待处理的请求正在等待？

bash

openclaw pairing list <channel>

待处理的 DM 配对请求默认限制为每个通道 3 个。如果列表已满，新请求不会生成代码，直到其中一个被批准或过期。

检查 2： 请求是否已创建但没有发送回复？

bash

openclaw logs --follow | grep "pairing request"

检查 3： 确认该通道的 dmPolicy 不是 open/allowlist。

图片 + 提及不起作用

已知问题：当您仅发送带有提及的消息（没有其他文本）时，WhatsApp 有时不包含提及元数据。

解决方法： 添加一些带提及的文本：

❌ @clawd + 图片
✅ @clawd check this + 图片

会话未恢复

检查 1： 会话文件是否存在？

bash

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

检查 2： 重置窗口是否太短？

json

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

检查 3： 是否有人发送了 /new、/reset 或重置触发器？

代理超时

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

json

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

或者使用 process 工具在后台运行长时间命令。

WhatsApp 断开连接

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

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

修复： 一旦网关运行通常会自动重新连接。如果您卡住了，请重启网关进程（无论您如何监督它），或手动运行详细输出：

bash

openclaw gateway --verbose

如果您已登出/取消链接：

bash

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果登出不能完全清除所有内容
openclaw channels login --verbose       # 重新扫描二维码

媒体发送失败

检查 1： 文件路径是否有效？

bash

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

检查 2： 文件是否太大？

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

检查 3： 检查媒体日志

bash

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

高内存使用

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

修复： 定期重启或设置会话限制：

json

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

通用故障排除

"网关无法启动 — 配置无效"

当配置包含未知键、格式错误的值或无效类型时，OpenClaw 现在拒绝启动。这是为了安全而有意为之的。

使用 Doctor 修复它：

bash

openclaw doctor
openclaw doctor --fix

注意事项：

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

"所有模型都失败了" — 我应该首先检查什么？

凭据：尝试的提供者是否存在凭据（认证配置文件 + 环境变量）。
模型路由：确认 agents.defaults.model.primary 和备用模型是您可以访问的模型。
网关日志：在 /tmp/openclaw/… 中查看确切的提供者错误。
模型状态：使用 /model status（聊天）或 openclaw models status（CLI）。

我在我的个人 WhatsApp 号码上运行 — 为什么自聊很奇怪？

启用自聊模式并允许您自己的号码：

json5

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

参见 WhatsApp 设置。

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

再次运行登录命令并扫描二维码：

bash

openclaw channels login

在 `main` 分支上出现构建错误 — 标准修复路径是什么？

git pull origin main && pnpm install
openclaw doctor
检查 GitHub issues 或 Discord
临时解决方法：检出一个较早的提交

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

如果您从源代码运行，请使用仓库的包管理器：pnpm（推荐）。仓库声明了 packageManager: "pnpm@…"。

典型恢复步骤：

bash

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

原因：pnpm 是此仓库配置的包管理器。

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

使用 网站安装程序 并使用标志选择安装方法。它就地升级并重写网关服务以指向新安装。

切换 到 git 安装：

bash

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

切换 到 npm 全局：

bash

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

注意事项：

git 流程仅在仓库干净时才会变基。请先提交或暂存更改。

切换后，运行：

bash

openclaw doctor
openclaw gateway restart

Telegram 块流在工具调用之间没有分割文本。为什么？

块流只发送完整的文本块。常见的导致单个消息的原因：

agents.defaults.blockStreamingDefault 仍然是 "off"。
channels.telegram.blockStreaming 设置为 false。
channels.telegram.streamMode 是 partial 或 block 并且草稿流是激活的 （私人聊天 + 主题）。在这种情况下，草稿流禁用了块流。
您的 minChars / 合并设置太高，因此块被合并了。
模型发出一个大的文本块（没有中间回复刷新点）。

修复清单：

将块流设置放在 agents.defaults 下，而不是根目录。
如果您想要真正的多消息块回复，请设置 channels.telegram.streamMode: "off"。
调试时使用较小的块/合并阈值。

See Streaming.

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

requireMention 仅在通道通过允许列表后控制提及门控。默认情况下 channels.discord.groupPolicy 是 允许列表，所以公会必须显式启用。如果您设置了 channels.discord.guilds.<guildId>.channels，只有列出的通道被允许；省略它以允许公会中的所有通道。

修复清单：

设置 channels.discord.groupPolicy: "open" 或添加一个公会允许列表条目（以及可选的通道允许列表）。
在 channels.discord.guilds.<guildId>.channels 中使用 数字通道 ID。
将 requireMention: false 放在 channels.discord.guilds 下（全局或每个通道）。顶层 channels.discord.requireMention 不是受支持的键。
确保机器人具有 消息内容意图 和通道权限。
运行 openclaw channels status --probe 获取审核提示。

文档：Discord，通道故障排除。

Cloud Code Assist API 错误：无效的工具模式 (400)。现在怎么办？

这几乎总是 工具模式兼容性 问题。Cloud Code Assist 端点接受严格的 JSON 模式子集。OpenClaw 在当前 main 分支中清理/规范化工具模式，但该修复尚未包含在最新版本中（截至 2026年1月13日）。

修复清单：

更新 OpenClaw：
- 如果您可以从源代码运行，请拉取 main 并重启网关。
- 否则，请等待包含模式清理器的下一个版本。
避免不受支持的关键字，如 anyOf/oneOf/allOf、patternProperties、 additionalProperties、minLength、maxLength、format 等。
如果您定义自定义工具，请保持顶层模式为 type: "object"，并使用 properties 和简单枚举。

参见工具和 TypeBox 模式。

macOS 特定问题

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

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

修复 1：重置 TCC 缓存

bash

tccutil reset All com.openclaw.mac.debug

修复 2：强制新包 ID 如果重置不起作用，请在 scripts/package-mac-app.sh 中更改 BUNDLE_ID（例如，添加 .test 后缀）并重建。这会强制 macOS 将其视为新应用。

网关卡在 "Starting..."

应用程序连接到端口 18789 上的本地网关。如果它一直卡住：

修复 1：停止监督程序（首选） 如果网关由 launchd 监督，杀死 PID 只会使它重新生成。首先停止监督程序：

bash

openclaw gateway status
openclaw gateway stop
# 或：launchctl bootout gui/$UID/com.openclaw.gateway （如需要，替换为 com.openclaw.<profile>）

修复 2：端口正忙（查找监听器）

bash

lsof -nP -iTCP:18789 -sTCP:LISTEN

如果是无人监督的进程，请先尝试优雅停止，然后升级：

bash

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

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

bash

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

调试模式

获取详细日志：

bash

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

日志位置

日志	位置
网关文件日志（结构化）	`/tmp/openclaw/openclaw-YYYY-MM-DD.log` （或 `logging.file`）
网关服务日志（监督程序）	macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log` （默认：`~/.openclaw/logs/...`; 配置文件使用 `~/.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`
会话文件	`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`
媒体缓存	`$OPENCLAW_STATE_DIR/media/`
凭据	`$OPENCLAW_STATE_DIR/credentials/`

健康检查

bash

# 监督程序 + 探测目标 + 配置路径
openclaw gateway status
# 包括系统级扫描（遗留/额外服务，端口监听器）
openclaw gateway status --deep

# 网关是否可访问？
openclaw health --json
# 如果失败，请使用连接详情重新运行：
openclaw health --verbose

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

# 最近活动（RPC 日志尾部）
openclaw logs --follow
# 如果 RPC 关闭则使用备选方案
tail -20 /tmp/openclaw/openclaw-*.log

重置所有内容

终极选项：

bash

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 版本
- 相关日志片段
- 重现步骤
- 您的配置（请编辑掉敏感信息！）

"Have you tried turning it off and on again?" — Every IT person ever

🦞🔧

浏览器未启动（Linux）

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

最可能的原因： Ubuntu 上的 Snap 包装的 Chromium。

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

bash

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

然后在配置中设置：

json

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

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

故障排除 🔧 ​

状态和诊断 ​

常见问题 ​

未找到提供者 "anthropic" 的 API 密钥 ​

OAuth 令牌刷新失败（Anthropic Claude 订阅） ​

控制 UI 在 HTTP 上失败（"需要设备身份" / "连接失败"） ​

Web UI 显示 "disconnected (1008): pairing required" 错误 ​

Web UI 显示 "disconnected (1006): no reason" 错误 ​

CI Secrets Scan 失败 ​

服务已安装但没有运行 ​

"网关启动被阻止：设置 gateway.mode=local" ​

服务环境（PATH + 运行时） ​

技能在沙盒中缺少 API 密钥 ​

服务运行但端口未监听 ​

地址已在使用（端口 18789） ​

检测到额外工作空间文件夹 ​

主聊天在沙盒工作空间中运行 ​

"代理被中止" ​

"代理回复前失败：未知模型：anthropic/claude-haiku-3-5" ​

Messages Not Triggering ​

配对码未到达 ​

图片 + 提及不起作用 ​

会话未恢复 ​

代理超时 ​

WhatsApp 断开连接 ​

媒体发送失败 ​

高内存使用 ​

通用故障排除 ​

"网关无法启动 — 配置无效" ​

"所有模型都失败了" — 我应该首先检查什么？ ​

我在我的个人 WhatsApp 号码上运行 — 为什么自聊很奇怪？ ​

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

在 main 分支上出现构建错误 — 标准修复路径是什么？ ​

npm 安装失败（allow-build-scripts / 缺少 tar 或 yargs）。现在怎么办？ ​

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

Telegram 块流在工具调用之间没有分割文本。为什么？ ​

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

Cloud Code Assist API 错误：无效的工具模式 (400)。现在怎么办？ ​

macOS 特定问题 ​

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

网关卡在 "Starting..." ​

调试模式 ​

日志位置 ​

健康检查 ​

重置所有内容 ​

获取帮助 ​

浏览器未启动（Linux） ​

故障排除 🔧

状态和诊断

常见问题

未找到提供者 "anthropic" 的 API 密钥

OAuth 令牌刷新失败（Anthropic Claude 订阅）

控制 UI 在 HTTP 上失败（"需要设备身份" / "连接失败"）

Web UI 显示 "disconnected (1008): pairing required" 错误

Web UI 显示 "disconnected (1006): no reason" 错误

CI Secrets Scan 失败

服务已安装但没有运行

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

服务环境（PATH + 运行时）

技能在沙盒中缺少 API 密钥

服务运行但端口未监听

地址已在使用（端口 18789）

检测到额外工作空间文件夹

主聊天在沙盒工作空间中运行

"代理被中止"

"代理回复前失败：未知模型：anthropic/claude-haiku-3-5"

Messages Not Triggering

配对码未到达

图片 + 提及不起作用

会话未恢复

代理超时

WhatsApp 断开连接

媒体发送失败

高内存使用

通用故障排除

"网关无法启动 — 配置无效"

"所有模型都失败了" — 我应该首先检查什么？

我在我的个人 WhatsApp 号码上运行 — 为什么自聊很奇怪？

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

在 `main` 分支上出现构建错误 — 标准修复路径是什么？

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

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

Telegram 块流在工具调用之间没有分割文本。为什么？

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

Cloud Code Assist API 错误：无效的工具模式 (400)。现在怎么办？

macOS 特定问题

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

网关卡在 "Starting..."

调试模式

日志位置

健康检查

重置所有内容

获取帮助

浏览器未启动（Linux）