排障 🔧

当 OpenClaw 表现不正常时，可以按下面的方法修复。

如果你只想要一份快速的“先救火”流程，先看 FAQ 的 First 60 seconds。本页会更深入覆盖运行时失败与诊断手段。

按 provider 的快捷入口：/channels/troubleshooting

状态与诊断

快速排查命令（按顺序）：

命令	它能告诉你什么	何时使用
`openclaw status`	本地概要：OS + 更新状态、gateway 可达性/模式、service、agents/sessions、provider 配置状态	第一次检查、快速概览
`openclaw status --all`	完整本地诊断（只读、可粘贴、相对安全）包含日志尾部（log tail）	当你需要分享一份 debug 报告
`openclaw status --deep`	运行 gateway 健康检查（包含 provider probes；需要 gateway 可达）	当“已配置”不等于“能工作”
`openclaw gateway probe`	gateway 发现 + 可达性（本地 + 远程目标）	当你怀疑自己探测的是“错误的 gateway”时
`openclaw channels status --probe`	询问运行中的 gateway 以获取 channel 状态（并可选执行 probe）	当 gateway 可达但 channels 行为异常
`openclaw gateway status`	supervisor 状态（launchd/systemd/schtasks）、运行时 PID/退出信息、最近一次 gateway 错误	当 service 看起来“已加载”但实际没有进程运行
`openclaw logs --follow`	实时日志（排障信号最强）	当你需要看到真实失败原因时

分享输出： 优先使用 openclaw status --all（会脱敏 tokens）。如果你要粘贴 openclaw status 的输出，建议先设置 OPENCLAW_SHOW_SECRETS=0（避免 token 预览）。

另见：Health checks 与 Logging。

常见问题

No API key found for provider "anthropic"

这表示 该 agent 的 auth store 为空，或者缺少 Anthropic 凭据。鉴权是 按 agent 管理的，因此新 agent 不会继承 main agent 的 keys。

修复方式：

重新运行 onboarding，并为该 agent 选择 Anthropic。

或在 gateway host 上粘贴 setup-token：

bash

openclaw models auth setup-token --provider anthropic

或把 main agent 目录里的 auth-profiles.json 复制到新 agent 的目录。

验证：

bash

openclaw models status

OAuth token refresh failed（Anthropic Claude subscription）

这表示存储的 Anthropic OAuth token 已过期，且刷新失败。如果你使用 Claude 订阅（没有 API key），最可靠的修复方式是切换到 Claude Code setup-token，并在 gateway host 上粘贴。

推荐（setup-token）：

bash

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

如果你在别处生成了 token：

bash

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

更多细节：Anthropic 与 OAuth。

Control UI 在 HTTP 下失败（"device identity required" / "connect failed"）

如果你通过普通 HTTP 打开 dashboard（例如 http://<lan-ip>:18789/ 或 http://<tailscale-ip>:18789/），浏览器处于 非安全上下文，WebCrypto 会被阻止，因此无法生成 device identity。

修复：

优先使用 Tailscale Serve 提供 HTTPS。
或在 gateway host 本机打开：http://127.0.0.1:18789/。
如果你必须使用 HTTP，启用 gateway.controlUi.allowInsecureAuth: true 并使用 gateway token（仅 token；不做 device identity/pairing）。见 Control UI。

CI Secrets Scan Failed

这表示 detect-secrets 发现了 baseline 中尚未记录的新候选项。请按 Secret scanning 处理。

Service Installed but Nothing is Running

如果 gateway service 已安装但进程会立刻退出，那么 service 可能看起来“已加载”，但实际上没有进程在运行。

检查：

bash

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）：
json
```
{ "logging": { "level": "debug" } }
```

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

json

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

小提示：--verbose 只影响 控制台 输出；文件日志仍由 logging.level 控制。

关于格式/配置/访问的完整说明见：/logging。

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

这表示 config 存在，但 gateway.mode 未设置（或不是 local），因此 Gateway 拒绝启动。

修复（推荐）：

运行向导并把 Gateway run mode 设置为 Local：
bash
```
openclaw configure
```
或直接设置：
bash
```
openclaw config set gateway.mode local
```

如果你本来想运行 remote Gateway：

设置 remote 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 的情况下启动 gateway。

还没有 config 文件？ 运行 openclaw setup 生成 starter config，然后再运行 gateway。

Service Environment（PATH + runtime）

gateway service 为了避免加载 shell/manager 的杂项，会以 最小 PATH 运行：

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

这会刻意排除版本管理器（nvm/fnm/volta/asdf）与包管理器（pnpm/npm），因为 service 不会加载你的 shell init。像 DISPLAY 这类 runtime 变量应写入 ~/.openclaw/.env（gateway 会在早期加载）。

当 exec 运行在 host=gateway 时，会把你的 login-shell PATH 合并到 exec 环境；所以缺少工具通常意味着你的 shell init 没有导出它们（或设置 tools.exec.pathPrepend）。见 /tools/exec。

WhatsApp + Telegram channels 需要 Node；不支持 Bun。如果你的 service 以 Bun 或版本管理器的 Node 路径安装，运行 openclaw doctor 迁移到系统安装的 Node。

sandbox 里 skill 缺少 API key

现象： skill 在宿主机能用，但在 sandbox 中因为缺少 API key 失败。

原因： 沙箱 exec 在 Docker 内运行，且 不会继承 宿主机的 process.env。

修复：

设置 agents.defaults.sandbox.docker.env（或 per-agent agents.list[].sandbox.docker.env）
或把 key 烘焙进自定义 sandbox image
然后运行 openclaw sandbox recreate --agent <id>（或 --all）

Service Running but Port Not Listening

如果 supervisor 报告 running，但 gateway 端口上没有任何监听，通常是 Gateway 拒绝 bind。

这里的 “running” 是什么意思

Runtime: running 表示 supervisor（launchd/systemd/schtasks）认为进程还活着。
RPC probe 表示 CLI 实际连上了 gateway WebSocket，并成功调用了 status。
永远信任 Probe target: + Config (service): 这两行，它们回答“我们实际探测了哪里”。

检查：

对 openclaw gateway 与 service 来说，gateway.mode 必须是 local。
如果你设置了 gateway.mode=remote，CLI 会默认使用 remote URL。此时 service 可能仍在本地运行，但 CLI 可能探测的是错误目标。用 openclaw gateway status 查看 service 的解析端口 + probe target（或传 --url）。
当 service 看似运行但端口关闭时，openclaw gateway status 与 openclaw doctor 会从日志中给出 last gateway error。
非 loopback binds（lan/tailnet/custom，或 loopback 不可用时的 auto）需要配置 auth： gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
gateway.remote.token 仅用于 remote CLI calls；它不会启用本地鉴权。
gateway.token 会被忽略；请使用 gateway.auth.token。

如果 openclaw gateway status 显示 config 不匹配

Config (cli): ... 与 Config (service): ... 通常应一致。
若不一致，几乎可以肯定你在编辑一份 config，但 service 在使用另一份。
修复：用你希望 service 使用的 --profile / OPENCLAW_STATE_DIR 重新运行 openclaw gateway install --force。

如果 openclaw gateway status 报告 service config 问题

supervisor config（launchd/systemd/schtasks）缺少当前默认值。
修复：运行 openclaw doctor 更新（或 openclaw gateway install --force 全量重写）。

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

你把 gateway.bind 设为非 loopback（lan/tailnet/custom，或 loopback 不可用时的 auto），但没有配置 auth。
修复：设置 gateway.auth.mode + gateway.auth.token（或导出 OPENCLAW_GATEWAY_TOKEN），然后重启 service。

如果 openclaw gateway status 显示 bind=tailnet 但找不到 tailnet 网卡

gateway 试图绑定到 Tailscale IP（100.64.0.0/10），但主机上没检测到。
修复：在该机器上启动 Tailscale（或把 gateway.bind 改为 loopback/lan）。

如果 Probe note: 提示 probe 使用 loopback

对 bind=lan 这是预期：gateway 监听 0.0.0.0（所有网卡），本机 loopback 仍应可连。
对远程客户端，请使用真实 LAN IP（不是 0.0.0.0）加端口，并确保配置了 auth。

Address Already in Use（端口 18789）

表示已经有进程在监听 gateway 端口。

检查：

bash

openclaw gateway status

它会展示 listener(s) 与可能原因（gateway 已运行、SSH 隧道）。需要时停止 service 或换一个端口。

Extra Workspace Folders Detected

如果你从旧安装升级，磁盘上可能还残留 ~/openclaw。多个 workspace 目录会导致鉴权或 state 漂移的困惑，因为只有一个 workspace 会被实际使用。

修复： 只保留一个活跃 workspace，其它归档/移除。见 Agent workspace。

主聊天跑在 sandbox workspace 中

现象：pwd 或文件 tools 显示 ~/.openclaw/sandboxes/...，但你期望的是宿主机 workspace。

原因： agents.defaults.sandbox.mode: "non-main" 依赖 session.mainKey（默认 "main"）。群聊/频道 sessions 使用自己的 key，因此被视为 non-main，从而获得 sandbox workspaces。

修复选项：

若你希望某个 agent 使用宿主机 workspace：设置 agents.list[].sandbox.mode: "off"。
若你希望在 sandbox 内访问宿主机 workspace：为该 agent 设置 workspaceAccess: "rw"。

"Agent was aborted"

agent 在回复过程中被中断。

原因：

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

修复： 直接再发一条消息即可；session 会继续。

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

OpenClaw 会有意拒绝 旧/不安全的模型（尤其是更容易受到 prompt injection 的模型）。出现该错误表示该模型名已不再支持。

修复：

选择该 provider 的最新模型，并更新你的 config 或 model alias。
如果你不确定有哪些可用模型，运行 openclaw models list 或 openclaw models scan 并选一个受支持的。
查看 gateway logs 获取更详细的失败原因。

另见：Models CLI 与 Model providers。

Messages Not Triggering

检查 1：发送者是否在 allowlist 中？

bash

openclaw status

查看输出中的 AllowFrom: ...。

检查 2：群聊是否要求 mention？

bash

# 消息必须匹配 mentionPatterns 或显式 mentions；默认值位于各 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：查看日志

bash

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

Pairing Code Not Arriving

如果 dmPolicy 是 pairing，未知发送者应收到一个 code，并且他们的消息在被批准前会被忽略。

检查 1：是否已经有 pending request？

bash

openclaw pairing list <channel>

默认情况下，pending DM pairing requests 每个 channel 上限为 3。如果列表满了，新的请求不会生成 code，直到有请求被批准或过期。

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

bash

openclaw logs --follow | grep "pairing request"

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

Image + Mention Not Working

已知问题：当你发送一张图片，并且消息内容只有一个 mention（没有其它文本）时，WhatsApp 有时不会包含 mention 的元数据。

绕过： 给 mention 加一点文字：

❌ @openclaw + image
✅ @openclaw check this + image

Session Not Resuming

检查 1：session 文件是否存在？

bash

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

检查 2：reset 窗口是不是太短？

json

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

检查 3：是否有人发送了 /new、/reset 或其它 reset trigger？

Agent Timing Out

默认超时是 30 分钟。对长任务可以提高超时：

json

{
  "reply": {
    "timeoutSeconds": 3600 // 1 hour
  }
}

或者使用 process tool 把长命令放到后台。

WhatsApp Disconnected

bash

# 查看本地状态（creds、sessions、队列事件）
openclaw status
# 探测运行中的 gateway + channels（WA 连接 + Telegram + Discord APIs）
openclaw status --deep

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

修复： 通常只要 Gateway 运行，就会自动重连。若一直卡住，重启 Gateway（按你的 supervisor 方式），或手动运行并开启 verbose：

bash

openclaw gateway --verbose

如果你已登出/未关联：

bash

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果 logout 无法干净清理
openclaw channels login --verbose       # 重新扫码

Media Send Failing

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

bash

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

检查 2：是否太大？

Images：最大 6MB
Audio/Video：最大 16MB
Documents：最大 100MB

检查 3：查看 media 日志

bash

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

High Memory Usage

OpenClaw 会把对话历史保存在内存里。

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

json

{
  "session": {
    "historyLimit": 100 // Max messages to keep
  }
}

常见排障

“Gateway won’t start — configuration invalid”

当 config 中包含未知 key、错误的值或非法类型时，OpenClaw 现在会拒绝启动。这是出于安全考虑的刻意设计。

用 Doctor 修复：

bash

openclaw doctor
openclaw doctor --fix

备注：

openclaw doctor 会报告每一条无效项。
openclaw doctor --fix 会应用 migrations/repairs 并重写 config。
即使 config 无效，像 openclaw logs、openclaw health、openclaw status、openclaw gateway status、openclaw gateway probe 这类诊断命令仍可运行。

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

要尝试的 provider(s) 是否具备凭据（auth profiles + env vars）。
模型路由：确认 agents.defaults.model.primary 与 fallbacks 是你能访问的模型。
查看 /tmp/openclaw/… 中的 Gateway logs，获取准确的 provider 报错。
模型状态：在聊天中用 /model status，或在 CLI 中用 openclaw models status。

我用的是自己的 WhatsApp 号码，为什么 self-chat 很奇怪？

启用 self-chat mode，并 allowlist 你自己的号码：

json5

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

见 WhatsApp setup。

WhatsApp 把我登出了，我怎么重新鉴权？

重新运行登录命令并扫码：

bash

openclaw channels login

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

git pull origin main && pnpm install
openclaw doctor
查看 GitHub issues 或 Discord
临时 workaround：切到更旧的 commit

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

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

常见恢复流程：

bash

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

原因：pnpm 是该仓库配置的 package manager。

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

使用 网站安装脚本 并通过 flag 选择安装方式。它会就地升级，并重写 gateway service 指向新的安装路径。

切换 到 git install：

bash

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

切换 到 npm global：

bash

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

备注：

git 流程只有在 repo 干净时才会 rebase；先 commit 或 stash 改动。

切换后建议运行：

bash

openclaw doctor
openclaw gateway restart

Telegram block streaming 没有在 tool calls 间分段。为什么？

Block streaming 只发送 已完成的文本块。常见导致只有一条消息的原因：

agents.defaults.blockStreamingDefault 仍为 "off"。
channels.telegram.blockStreaming 被设为 false。
channels.telegram.streamMode 为 partial 或 block，并且 draft streaming 处于启用状态（私聊 + topics）。在这种情况下 draft streaming 会禁用 block streaming。
minChars / coalesce 设置过高，导致 chunks 被合并。
模型一次性输出一个大文本块（没有中途 flush 点）。

修复清单：

把 block streaming 设置放在 agents.defaults 下，而不是根上。
如果你希望真正的多消息 block replies，将 channels.telegram.streamMode: "off"。
排障时先把 chunk/coalesce 阈值调小。

见 Streaming。

Discord 在我的 server 里不回复，即使 `requireMention: false`。为什么？

requireMention 只控制在 allowlists 通过之后的 mention-gating。默认 channels.discord.groupPolicy 是 allowlist，因此 guild 必须显式启用。如果你设置了 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 不是受支持的 key。
确认 bot 开启了 Message Content Intent 且具备 channel 权限。
运行 openclaw channels status --probe 获取审计提示。

文档：Discord，Channels troubleshooting。

Cloud Code Assist API error: invalid tool schema（400）。怎么办？

这几乎总是 tool schema 兼容性 问题。Cloud Code Assist 端点只接受 JSON Schema 的严格子集。 OpenClaw 在当前 main 中会对 tool schemas 做 scrub/归一化，但截至 2026-01-13，该修复尚未进入上一个 release。

修复清单：

更新 OpenClaw：
- 如果你能从源码运行，拉取 main 并重启 gateway。
- 否则等待包含 schema scrubber 的下一个 release。
避免不受支持的关键字，例如 anyOf/oneOf/allOf、patternProperties、additionalProperties、minLength、maxLength、format 等。
如果你定义自定义 tools，请保持顶层 schema 为 type: "object"，使用 properties 与简单 enums。

见 Tools 与 TypeBox schemas。

macOS 特有问题

在授权权限（Speech/Mic）时 app 崩溃

如果你在隐私弹窗点击 “Allow” 后 app 直接消失或显示 “Abort trap 6”：

修复 1：重置 TCC 缓存

bash

tccutil reset All bot.molt.mac.debug

修复 2：强制新 Bundle ID

如果重置无效，修改 scripts/package-mac-app.sh 中的 BUNDLE_ID（例如加一个 .test 后缀）并重新构建。这会让 macOS 把它当作一个新 app。

Gateway 卡在 “Starting...”

app 会连接本地 18789 端口上的 gateway。如果一直卡住：

修复 1：先停止 supervisor（推荐）

如果 gateway 由 launchd 监管，直接 kill PID 会立刻被拉起。先停 supervisor：

bash

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

修复 2：端口被占用（找 listener）

bash

lsof -nP -iTCP:18789 -sTCP:LISTEN

如果是未被 supervisor 管理的进程，先温和停止，再升级：

bash

kill -TERM <PID>
sleep 1
kill -9 <PID> # last resort

修复 3：检查 CLI 安装

确认全局 openclaw CLI 已安装且与 app 版本匹配：

bash

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

Debug 模式

获取更详细日志：

bash

# 在 config 中打开 trace logging：
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# 然后用 verbose 命令把 debug 输出镜像到 stdout：
openclaw gateway --verbose
openclaw channels login --verbose

日志位置

Log	Location
Gateway file logs (structured)	`/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or `logging.file`)
Gateway service logs (supervisor)	macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.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 files	`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`
Media cache	`$OPENCLAW_STATE_DIR/media/`
Credentials	`$OPENCLAW_STATE_DIR/credentials/`

健康检查

bash

# Supervisor + probe target + config paths
openclaw gateway status
# 包含系统级扫描（legacy/额外 services、端口 listeners）
openclaw gateway status --deep

# gateway 可达吗？
openclaw health --json
# 如果失败，加上连接细节重试：
openclaw health --verbose

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

# 最近活动（RPC log tail）
openclaw logs --follow
# RPC 不通时的 fallback
tail -20 /tmp/openclaw/openclaw-*.log

全量重置

核弹选项：

bash

openclaw gateway stop
# 如果你安装了 service 并希望干净重装：
# openclaw gateway uninstall

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

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

获取帮助

先看日志：/tmp/openclaw/（默认 openclaw-YYYY-MM-DD.log，或你的 logging.file）
在 GitHub 搜索已有 issues
新开 issue 时附上：
- OpenClaw version
- 相关日志片段
- 复现步骤
- 你的 config（务必脱敏！）

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

🦞🔧

Browser Not Starting（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

然后在 config 中设置：

json

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

完整指南： 见 browser-linux-troubleshooting

排障 🔧 ​

状态与诊断 ​

常见问题 ​

No API key found for provider "anthropic" ​

OAuth token refresh failed（Anthropic Claude subscription） ​

Control UI 在 HTTP 下失败（"device identity required" / "connect failed"） ​

CI Secrets Scan Failed ​

Service Installed but Nothing is Running ​

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

Service Environment（PATH + runtime） ​

sandbox 里 skill 缺少 API key ​

Service Running but Port Not Listening ​

Address Already in Use（端口 18789） ​

Extra Workspace Folders Detected ​

主聊天跑在 sandbox workspace 中 ​

"Agent was aborted" ​

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

Messages Not Triggering ​

Pairing Code Not Arriving ​

Image + Mention Not Working ​

Session Not Resuming ​

Agent Timing Out ​

WhatsApp Disconnected ​

Media Send Failing ​

High Memory Usage ​

常见排障 ​

“Gateway won’t start — configuration invalid” ​

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

我用的是自己的 WhatsApp 号码，为什么 self-chat 很奇怪？ ​

WhatsApp 把我登出了，我怎么重新鉴权？ ​

main 分支构建失败——标准修复路径是什么？ ​

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

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

Telegram block streaming 没有在 tool calls 间分段。为什么？ ​

Discord 在我的 server 里不回复，即使 requireMention: false。为什么？ ​

Cloud Code Assist API error: invalid tool schema（400）。怎么办？ ​

macOS 特有问题 ​

在授权权限（Speech/Mic）时 app 崩溃 ​

Gateway 卡在 “Starting...” ​

Debug 模式 ​

日志位置 ​

健康检查 ​

全量重置 ​

获取帮助 ​

Browser Not Starting（Linux） ​

排障 🔧

状态与诊断

常见问题

No API key found for provider "anthropic"

OAuth token refresh failed（Anthropic Claude subscription）

Control UI 在 HTTP 下失败（"device identity required" / "connect failed"）

CI Secrets Scan Failed

Service Installed but Nothing is Running

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

Service Environment（PATH + runtime）

sandbox 里 skill 缺少 API key

Service Running but Port Not Listening

Address Already in Use（端口 18789）

Extra Workspace Folders Detected

主聊天跑在 sandbox workspace 中

"Agent was aborted"

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

Messages Not Triggering

Pairing Code Not Arriving

Image + Mention Not Working

Session Not Resuming

Agent Timing Out

WhatsApp Disconnected

Media Send Failing

High Memory Usage

常见排障

“Gateway won’t start — configuration invalid”

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

我用的是自己的 WhatsApp 号码，为什么 self-chat 很奇怪？

WhatsApp 把我登出了，我怎么重新鉴权？

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

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

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

Telegram block streaming 没有在 tool calls 间分段。为什么？

Discord 在我的 server 里不回复，即使 `requireMention: false`。为什么？

Cloud Code Assist API error: invalid tool schema（400）。怎么办？

macOS 特有问题

在授权权限（Speech/Mic）时 app 崩溃

Gateway 卡在 “Starting...”

Debug 模式

日志位置

健康检查

全量重置

获取帮助

Browser Not Starting（Linux）