故障排查 🔧

网关无法启动或未授权？从这里开始。Moltbot 异常时的修复思路。若只需快速排查，可先看 FAQ 的前 60 秒。本页侧重运行时失败与诊断。按提供商排查见频道故障排查。

状态与诊断

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

命令	说明	何时使用
`moltbot status`	本地摘要：OS + 更新、网关可达性/模式、服务、agents/会话、提供商配置状态	首次检查，快速概览
`moltbot status --all`	完整本地诊断（只读、可粘贴、较安全）含日志尾部	需要分享调试报告时
`moltbot status --deep`	运行网关健康检查（含提供商探测；需可达网关）	当「已配置」不等于「可用」时
`moltbot gateway probe`	网关发现与可达性（本地 + 远程目标）	怀疑探测了错误网关时
`moltbot channels status --probe`	询问运行中的网关频道状态（可选探测）	网关可达但频道异常时
`moltbot gateway status`	监管状态（launchd/systemd/schtasks）、运行时 PID/退出、最后网关错误	服务「看起来已加载」但无进程运行时
`moltbot logs --follow`	实时日志（运行时问题的最佳信号）	需要实际失败原因时

分享输出： 优先使用 moltbot status --all（会脱敏令牌）。若粘贴 moltbot status，考虑先设 CLAWDBOT_SHOW_SECRETS=0（令牌预览）。另见健康检查与日志。

常见问题

未找到提供商「anthropic」的 API 密钥

表示该代理的认证存储为空或缺少 Anthropic 凭证。认证按代理，新代理不会继承主代理的密钥。解决办法：

重新运行引导并为该代理选择 Anthropic。
或在网关主机上粘贴 setup-token：


moltbot models auth setup-token --provider anthropic

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

验证：


moltbot models status

OAuth token 刷新失败（Anthropic Claude 订阅）

表示存储的 Anthropic OAuth token 已过期且刷新失败。若使用 Claude 订阅（无 API 密钥），最可靠的修复是切换到 Claude Code setup-token 并在网关主机上粘贴。推荐（setup-token）：


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

若在其他机器生成令牌：


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

更多详情：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。

CI 密钥扫描失败

表示 detect-secrets 发现尚未在基线中的新候选。遵循密钥扫描。

服务已安装但无进程运行

若网关服务已安装但进程立即退出，服务可能显示「已加载」但无进程运行。检查：


moltbot gateway status
moltbot doctor

Doctor/服务会显示运行时状态（PID/最后退出）与日志提示。日志：

优先：moltbot logs --follow
文件日志（始终）：/tmp/moltbot/moltbot-YYYY-MM-DD.log（或你配置的 logging.file）
macOS LaunchAgent（若安装）：$CLAWDBOT_STATE_DIR/logs/gateway.log 与 gateway.err.log
Linux systemd（若安装）：journalctl --user -u moltbot-gateway[-<profile>].service -n 200 --no-pager
Windows：schtasks /Query /TN "Moltbot Gateway (<profile>)" /V /FO LIST

启用更多日志：

提高文件日志详细度（持久化 JSONL）：


{ "logging": { "level": "debug" } }

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


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

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

见日志了解格式、配置与访问的完整概览。

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

表示配置存在但 gateway.mode 未设置（或不是 local），因此网关拒绝启动。修复（推荐）：

运行向导并将网关运行模式设为 Local：


moltbot configure

或直接设置：


moltbot config set gateway.mode local

若你本意是运行远程网关：

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


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

临时/开发专用： 传递 --allow-unconfigured 在没有 gateway.mode=local 时启动网关。还没有配置文件？ 运行 moltbot setup 创建初始配置，然后重新运行网关。

服务环境（PATH + 运行时）

网关服务以最小 PATH 运行以避免 shell/管理器干扰：

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 应放在 ~/.clawdbot/.env（网关早期加载）。在 host=gateway 上的 Exec 运行会将你的登录 shell PATH 合并到 exec 环境，因此缺失工具通常表示你的 shell 初始化未导出它们（或设置 tools.exec.pathPrepend）。见 exec 工具。WhatsApp + Telegram 频道需要 Node；不支持 Bun。若服务用 Bun 或版本管理的 Node 路径安装，运行 moltbot doctor 迁移到系统 Node 安装。

沙箱中技能缺失 API 密钥

症状： 技能在主机上可用但在沙箱中因缺失 API 密钥失败。原因： 沙箱 exec 在 Docker 内运行且不继承主机 process.env。修复：

设置 agents.defaults.sandbox.docker.env（或按 agent agents.list[].sandbox.docker.env）
或将密钥烘焙到自定义沙箱镜像
然后运行 moltbot sandbox recreate --agent <id>（或 --all）

服务运行但端口未监听

若服务报告运行中但网关端口上无监听，网关可能拒绝绑定。此处「运行中」的含义：

Runtime: running 表示监管器（launchd/systemd/schtasks）认为进程存活。
RPC probe 表示 CLI 实际可连接到网关 WebSocket 并调用 status。
始终信任 Probe target: + Config (service): 作为「我们实际尝试了什么？」的行。

检查：

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

若 moltbot gateway status 显示配置不匹配：

Config (cli): ... 与 Config (service): ... 通常应匹配。
若不匹配，几乎肯定是在编辑一个配置而服务运行另一个。
修复：从你希望服务使用的同一 --profile / CLAWDBOT_STATE_DIR 重新运行 moltbot gateway install --force。

若 moltbot gateway status 报告服务配置问题：

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

若 Last gateway error: 提到「拒绝绑定…无认证」：

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

若 moltbot gateway status 说 bind=tailnet 但未找到 tailnet 接口：

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

若 Probe note: 说探测使用回环：

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

地址已被使用（端口 18789）

表示已有进程在监听网关端口。检查：


moltbot gateway status

会显示监听器与可能原因（网关已在运行、SSH 隧道）。若需要，停止服务或选择不同端口。

检测到额外工作区文件夹

若从旧安装升级，磁盘上可能仍有 ~/moltbot。多个工作区目录可能导致混淆的认证或状态漂移，因为只有一个工作区是活跃的。修复： 保持单一活跃工作区并归档/删除其余。见 Agent 工作区。

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

症状：pwd 或文件工具显示 ~/.clawdbot/sandboxes/... 尽管你期望主机工作区。原因： agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认 "main"）。群组/频道会话使用自己的 key，因此被视为非主并获得沙箱工作区。修复选项：

若希望 agent 使用主机工作区：设置 agents.list[].sandbox.mode: "off"。
若希望在沙箱内访问主机工作区：为该 agent 设置 workspaceAccess: "rw"。

「Agent 被中止」

Agent 在回复中途被中断。原因：

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

修复： 再发一条消息。会话继续。

「Agent 在回复前失败：未知模型：anthropic/claude-haiku-3-5」

Moltbot 有意拒绝旧/不安全模型（特别是更容易受提示注入攻击的）。若看到此错误，该模型名称不再受支持。修复：

为提供商选择最新模型并更新配置或模型别名。
若不确定哪些模型可用，运行 moltbot models list 或 moltbot models scan 并选择受支持的。
检查网关日志获取详细失败原因。

另见 Models CLI 与模型提供商。

消息未触发

检查 1： 发件人是否在白名单中？


moltbot status

在输出中查找 AllowFrom: ...。检查 2： 对于群聊，是否需要 @ 提及？


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

检查 3： 检查日志


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

配对码未到达

若 dmPolicy 为 pairing，未知发件人应收到码，其消息在批准前被忽略。检查 1： 是否已有待处理请求在等待？


moltbot pairing list <channel>

待处理私信配对请求默认每频道上限3 个。若列表已满，新请求不会生成码直到一个被批准或过期。检查 2： 请求是否已创建但未发送回复？


moltbot logs --follow | grep "pairing request"

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

图片 + @ 提及不工作

已知问题：当你仅发送带 @ 提及的图片（无其他文本）时，WhatsApp 有时不包含 @ 提及元数据。变通： 在 @ 提及时添加一些文本：

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

会话未恢复

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


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

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


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

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

Agent 超时

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


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

或使用 process 工具将长命令放到后台。

WhatsApp 断开


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

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

修复： 通常网关运行后会自动重连。若卡住，重启网关进程（无论你如何监管它），或手动运行并带详细输出：


moltbot gateway --verbose

若已登出/未链接：


moltbot channels logout
trash "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/credentials" # 若 logout 无法干净删除所有内容
moltbot channels login --verbose       # 重新扫描 QR

媒体发送失败

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


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

检查 2： 是否太大？

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

检查 3： 检查媒体日志


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

高内存使用

Moltbot 在内存中保留对话历史。修复： 定期重启或设置会话限制：


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

常见故障排查

「网关不会启动 — 配置无效」

Moltbot 现在在配置包含未知键、格式错误值或无效类型时拒绝启动。这是为安全有意为之。用 Doctor 修复：


moltbot doctor
moltbot doctor --fix

说明：

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

「所有模型失败」— 应首先检查什么？

凭据：正在尝试的提供商存在（auth profiles + 环境变量）。
模型路由：确认 agents.defaults.model.primary 与回退是你可访问的模型。
网关日志：在 /tmp/moltbot/… 中查看确切的提供商错误。
模型状态：使用 /model status（聊天）或 moltbot models status（CLI）。

我在个人 WhatsApp 号上运行 — 为何自聊异常？

启用自聊模式并白名单你自己的号码：


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

见 WhatsApp 设置。

WhatsApp 已登出。如何重新认证？

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


moltbot channels login

`main` 上的构建错误 — 标准修复路径是什么？

git pull origin main && pnpm install
moltbot doctor
检查 GitHub issues 或 Discord
临时变通：检出旧提交

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

若从源码运行，使用仓库的包管理器：pnpm（推荐）。仓库声明 packageManager: "pnpm@…"。典型恢复：


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

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

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

使用网站安装程序并通过标志选择安装方法。它会原地升级并重写网关服务指向新安装。切换到 git 安装：


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

切换到 npm 全局：


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

说明：

git 流程仅在仓库干净时 rebase。先提交或 stash 变更。
切换后运行：


moltbot doctor
moltbot gateway restart

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

块流式仅发送完成的文本块。你看到单条消息的常见原因：

agents.defaults.blockStreamingDefault 仍为 "off"。
channels.telegram.blockStreaming 设为 false。
channels.telegram.streamMode 为 partial 或 block 且草稿流式活跃（私聊 + 主题）。草稿流式在该情况下禁用块流式。
你的 minChars / coalesce 设置过高，因此块被合并。
模型发出一个大文本块（无中间回复刷新点）。

修复清单：

将块流式设置放在 agents.defaults 下，而非根。
若希望真实多消息块回复，设置 channels.telegram.streamMode: "off"。
调试时使用更小的块/coalesce 阈值。

见流式。

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

requireMention 仅在频道通过白名单后控制 @ 提及门控。默认 channels.discord.groupPolicy 为 allowlist，因此 guild 必须显式启用。若设置 channels.discord.guilds.<guildId>.channels，仅列出的频道允许；省略它以允许 guild 中的所有频道。修复清单：

设置 channels.discord.groupPolicy: "open" 或添加 guild 白名单条目（可选频道白名单）。
在 channels.discord.guilds.<guildId>.channels 中使用数字频道 ID。
将 requireMention: false 放在 channels.discord.guilds 下（全局或按频道）。顶级 channels.discord.requireMention 不是受支持的键。
确保机器人有消息内容 Intent 与频道权限。
运行 moltbot channels status --probe 获取审计提示。

文档：Discord、频道故障排查。

Cloud Code Assist API 错误：无效工具 schema（400）。现在怎么办？

这几乎总是工具 schema 兼容性问题。Cloud Code Assist 端点接受 JSON Schema 的严格子集。Moltbot 在当前 main 中清理/规范化工具 schema，但修复尚未包含在最新发布中（截至 2026 年 1 月 13 日）。修复清单：

更新 Moltbot：
- 若可从源码运行，拉取 main 并重启网关。
- 否则，等待包含 schema 清理器的下一发布。
避免不支持的关键字如 anyOf/oneOf/allOf、patternProperties、additionalProperties、minLength、maxLength、format 等。
若定义自定义工具，保持顶级 schema 为 type: "object" 带 properties 与简单枚举。

见工具与 TypeBox schemas。

macOS 专项问题

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

若应用消失或点击隐私提示上的「允许」时显示「Abort trap 6」：修复 1：重置 TCC 缓存


tccutil reset All bot.molt.mac.debug

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

网关卡在「Starting…」

应用连接到端口 18789 上的本地网关。若一直卡住：修复 1：停止监管器（推荐） 若网关由 launchd 监管，杀死 PID 只会重新生成。先停止监管器：


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

修复 2：端口被占用（查找监听器）


lsof -nP -iTCP:18789 -sTCP:LISTEN

若是未监管进程，先尝试优雅停止，然后升级：


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

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


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

调试模式

获取详细日志：


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

日志位置

日志	位置
网关文件日志（结构化）	`/tmp/moltbot/moltbot-YYYY-MM-DD.log`（或 `logging.file`）
网关服务日志（监管器）	macOS：`$CLAWDBOT_STATE_DIR/logs/gateway.log` + `gateway.err.log`（默认：`~/.clawdbot/logs/...`；profile 使用 `~/.clawdbot-<profile>/logs/...`）。Linux：`journalctl --user -u moltbot-gateway[-<profile>].service -n 200 --no-pager`。Windows：`schtasks /Query /TN "Moltbot Gateway (<profile>)" /V /FO LIST`
会话文件	`$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/`
媒体缓存	`$CLAWDBOT_STATE_DIR/media/`
凭据	`$CLAWDBOT_STATE_DIR/credentials/`

健康检查


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

# 网关是否可达？
moltbot health --json
# 若失败，使用连接详情重新运行：
moltbot health --verbose

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

# 最近活动（RPC 日志尾部）
moltbot logs --follow
# RPC 关闭时的回退
tail -20 /tmp/moltbot/moltbot-*.log

重置一切

核选项：


moltbot gateway stop
# 若安装了服务并希望干净安装：
# moltbot gateway uninstall

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

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

获取帮助

先检查日志：/tmp/moltbot/（默认：moltbot-YYYY-MM-DD.log，或你配置的 logging.file）
在 GitHub 上搜索现有 issues
打开新 issue，包含：
- Moltbot 版本
- 相关日志片段
- 复现步骤
- 你的配置（脱敏密钥！）

“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：


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