故障排除 🔧

文档

网关（Gateway）

故障排除 🔧

适用范围

在以下情况使用此页面：

调查运行时问题或故障

当 Moltbot 行为异常时，以下是修复方法。

首先查看 FAQ 的前 60 秒（如果你只是想要一个快速的分类食谱）。本页更深入地介绍运行时故障和诊断。

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

状态与诊断

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

命令	告诉你什么	何时使用它
`moltbot status`	本地摘要：操作系统 + 更新、网关可达性/模式、服务、代理/会话、提供商配置状态	首次检查，快速概览
`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，请考虑首先设置 MOLTBOT_SHOW_SECRETS=0（令牌预览）。

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

常见问题

未找到提供商 “anthropic” 的 API 密钥

这意味着代理的身份验证存储为空或缺少 Anthropic 凭证。身份验证是每个代理的，因此新代理不会继承主代理的密钥。

修复选项：

重新运行配置并为该代理选择 Anthropic。

或在网关主机上粘贴 setup-token：

moltbot models auth setup-token --provider anthropic

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

验证：

moltbot models status

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

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

推荐（setup-token）：

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

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

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

如果你想保留 OAuth 重用： 在网关主机上使用 Claude Code CLI 登录，然后运行 moltbot models status 将刷新的令牌同步到 Moltbot 的身份验证存储中。

更多详细信息：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#insecure-http)。

CI 密钥扫描失败

这意味着 detect-secrets 发现了基线中不存在的候选者。请遵循密钥扫描。

服务已安装但未运行

如果网关服务已安装但进程立即退出，服务可能看起来"已加载"但没有任何运行。

检查：

moltbot gateway status
moltbot doctor

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

日志：

推荐：moltbot logs --follow
文件日志（始终）：/tmp/moltbot/moltbot-YYYY-MM-DD.log（或你配置的 logging.file）
macOS LaunchAgent（如果已安装）：$MOLTBOT_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 控制。

参见 /logging 以获取格式、配置和访问的完整概述。

“Gateway start blocked: set 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 应该位于 ~/.moltbot/.env 中（由网关提前加载）。在 host=gateway 上运行的 exec 会将你的登录 shell PATH 合并到 exec 环境中，因此缺少的工具通常意味着你的 shell 初始化没有导出它们（或设置 tools.exec.pathPrepend）。参见 /tools/exec。

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

沙箱中技能缺少 API 密钥

**症状：**技能在主机上工作但在沙箱中失败，缺少 API 密钥。

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

修复：

设置 agents.defaults.sandbox.docker.env（或每个代理的 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): 作为"我们实际尝试了什么？“行。

检查：

工具调用（HTTP）后台执行 + 进程工具