诊断工具

适用范围

在以下情况使用此页面：

• 添加或修改诊断迁移
• 引入重大配置更改

moltbot doctor 是 Moltbot 的修复 + 迁移工具。它修复过时的 配置/状态、检查健康状况并提供可操作的修复步骤。

快速入门

moltbot doctor

无头/自动化

moltbot doctor --yes

接受默认值而不提示（包括重启/服务/沙箱修复步骤（如适用））。

moltbot doctor --repair

应用推荐的修复而不提示（在安全的情况下修复 + 重启）。

moltbot doctor --repair --force

也应用激进修复（覆盖自定义监督程序配置）。

moltbot doctor --non-interactive

无提示运行，仅应用安全迁移（配置规范化 + 磁盘状态移动）。跳过需要人工确认的重启/服务/沙箱操作。 传统状态迁移在检测到时自动运行。

moltbot doctor --deep

扫描系统服务以查找额外的网关安装（launchd/systemd/schtasks）。

如果您想在写入之前查看更改，请先打开配置文件：

cat ~/.moltbot/moltbot.json

它的作用（摘要）

• git 安装的可选飞行前更新（仅限交互式）。
• UI 协议新鲜度检查（当协议架构更新时重建控制 UI）。
• 健康检查 + 重启提示。
• 技能状态摘要（符合条件/缺失/已阻止）。
• 传统值的配置规范化。
• OpenCode Zen 提供程序覆盖警告（models.providers.opencode）。
• 传统磁盘状态迁移（会话/代理目录/WhatsApp 身份验证）。
• 状态完整性和权限检查（会话、脚本、状态目录）。
• 本地运行时的配置文件权限检查（chmod 600）。
• 模型身份验证健康状况：检查 OAuth 过期、可以刷新即将过期的令牌、报告身份验证配置文件冷却/已禁用状态。
• 额外的工作空间目录检测（~/moltbot）。
• 启用沙箱时的沙箱映像修复。
• 传统服务迁移和额外网关检测。
• 网关运行时检查（服务已安装但未运行；缓存的 launchd 标签）。
• 通道状态警告（从正在运行的网关探测）。
• 监督程序配置审计（launchd/systemd/schtasks）和可选修复。
• 网关运行时最佳实践检查（Node vs Bun、版本管理器路径）。
• 网关端口冲突诊断（默认 18789）。
• 打开 DM 策略的安全警告。
• 当未设置 gateway.auth.token 时的网关身份验证警告（本地模式；提供令牌生成）。
• Linux 上的 systemd linger 检查。
• 源安装检查（pnpm 工作空间不匹配、缺少 UI 资产、缺少 tsx 二进制文件）。
• 写入更新的配置 + 向导元数据。

详细行为和基本原理

0) 可选更新（git 安装）

如果是 git 检出并且诊断程序以交互模式运行，它会提供 在运行诊断程序之前更新（fetch/rebase/build）。

1) 配置规范化

如果配置包含传统值形状（例如没有通道特定覆盖的 messages.ackReaction）， 诊断程序会将其规范化为当前架构。

2) 传统配置键迁移

当配置包含已弃用的键时，其他命令拒绝运行并要求 您运行 moltbot doctor。

诊断程序将：

• 解释找到了哪些传统键。
• 显示它应用的迁移。
• 使用更新的架构重写 ~/.moltbot/moltbot.json。

网关还在启动时自动运行诊断程序迁移，当它检测到 传统配置格式时，因此无需手动干预即可修复过时的配置。

当前迁移：

• routing.allowFrom → channels.whatsapp.allowFrom
• routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
• routing.groupChat.historyLimit → messages.groupChat.historyLimit
• routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
• routing.queue → messages.queue
• routing.bindings → 顶级 bindings
• routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• bindings[].match.accountID → bindings[].match.accountId
• identity → agents.list[].identity
• agent.* → agents.defaults + tools.*（tools/elevated/exec/sandbox/subagents）
• agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks

2b) OpenCode Zen 提供程序覆盖

如果您手动添加了 models.providers.opencode（或 opencode-zen），它 会覆盖来自 @mariozechner/pi-ai 的内置 OpenCode Zen 目录。这可能会 强制每个模型使用单个 API 或将成本归零。诊断程序会警告，以便您可以 删除覆盖并恢复每模型 API 路由 + 成本。

3) 传统状态迁移（磁盘布局）

诊断程序可以将较旧的磁盘布局迁移到当前结构：

• 会话存储 + 脚本：
  • 从 ~/.moltbot/sessions/ 到 ~/.moltbot/agents/<agentId>/sessions/
• 代理目录：
  • 从 ~/.moltbot/agent/ 到 ~/.moltbot/agents/<agentId>/agent/
• WhatsApp 身份验证状态（Baileys）：
  • 从传统 ~/.moltbot/credentials/*.json（除了 oauth.json）
  • 到 ~/.moltbot/credentials/whatsapp/<accountId>/...（默认账户 id：default）

这些迁移是尽力而为且幂等的；当诊断程序将任何传统文件夹作为备份留下时，它会发出警告。网关/CLI 还会在启动时自动迁移 传统会话 + 代理目录，因此历史记录/身份验证/模型会进入 每代理路径，而无需手动运行诊断程序。WhatsApp 身份验证仅通过 moltbot doctor 迁移。

4) 状态完整性检查（会话持久性、路由和安全）

状态目录是操作脑干。如果它消失，您将丢失 会话、凭据、日志和配置（除非您在其他地方有备份）。

诊断程序检查：

• 状态目录丢失：警告灾难性状态丢失，提示重新创建 目录，并提醒您它无法恢复丢失的数据。
• 状态目录权限：验证可写性；提供修复权限 （并在检测到所有者/组不匹配时发出 chown 提示）。
• 会话目录丢失：sessions/ 和会话存储目录是 持久化历史记录并避免 ENOENT 崩溃所必需的。
• 脚本不匹配：当最近的会话条目缺少 脚本文件时发出警告。
• 主会话"1 行 JSONL"：当主脚本只有一行时发出标志（历史记录未累积）。
• 多个状态目录：当主目录中存在多个 ~/.moltbot 文件夹时或当 MOLTBOT_STATE_DIR 指向其他地方时发出警告（历史记录可能在安装之间拆分）。
• 远程模式提醒：如果 gateway.mode=remote，诊断程序提醒您在远程主机上运行它（状态驻留在那里）。
• 配置文件权限：如果 ~/.moltbot/moltbot.json 是组/世界可读的，则发出警告并提供收紧到 600。

5) 模型身份验证健康状况（OAuth 过期）

诊断程序检查身份验证存储中的 OAuth 配置文件，当令牌即将过期/已过期时发出警告，并在安全时刷新它们。如果 Anthropic Claude Code 配置文件过时，它建议运行 claude setup-token（或粘贴 setup-token）。 刷新提示仅在以交互模式运行（TTY）时出现；--non-interactive 跳过刷新尝试。

诊断程序还报告因以下原因暂时不可用的身份验证配置文件：

• 短暂冷却（速率限制/超时/身份验证失败）
• 较长时间的禁用（计费/信用失败）

6) Hooks 模型验证

如果设置了 hooks.gmail.model，诊断程序会根据目录和允许列表验证模型引用，并在它无法解析或被不允许时发出警告。

7) 沙箱映像修复

启用沙箱时，诊断程序检查 Docker 映像并在当前映像缺失时提供构建或切换到传统名称。

8) 网关服务迁移和清理提示

诊断程序检测传统网关服务（launchd/systemd/schtasks）并 提供删除它们并使用当前网关端口安装 Moltbot 服务。它还可以扫描额外的类似网关的服务并打印清理提示。 命名为配置文件的 Moltbot 网关服务被视为一等公民，不会 被标记为"额外"。

9) 安全警告

当提供程序在没有允许列表的情况下向 DM 开放或以危险方式配置策略时，诊断程序会发出警告。

10) systemd linger（Linux）

如果作为 systemd 用户服务运行，诊断程序会确保启用 linger，以便网关在注销后保持活动。

11) 技能状态

诊断程序打印当前工作空间的符合条件/缺失/已阻止技能的快速摘要。

12) 网关身份验证检查（本地令牌）

当本地网关上缺少 gateway.auth 时，诊断程序会发出警告并提供生成令牌。使用 moltbot doctor --generate-gateway-token 在自动化中强制创建令牌。

13) 网关健康检查 + 重启

诊断程序运行健康检查并在网关看起来不健康时提供重启网关。

14) 通道状态警告

如果网关健康，诊断程序运行通道状态探测并报告带有建议修复的警告。

15) 监督程序配置审计 + 修复

诊断程序检查已安装的监督程序配置（launchd/systemd/schtasks）是否存在 缺失或过时的默认值（例如，systemd network-online 依赖项和重启延迟）。当发现不匹配时，它建议更新并可以 将服务文件/任务重写为当前默认值。

注意：

• moltbot doctor 在重写监督程序配置之前提示。
• moltbot doctor --yes 接受默认修复提示。
• moltbot doctor --repair 在无提示的情况下应用推荐的修复。
• moltbot doctor --repair --force 覆盖自定义监督程序配置。
• 您始终可以通过 moltbot gateway install --force 强制完全重写。

16) 网关运行时 + 端口诊断

诊断程序检查服务运行时（PID、上次退出状态），并在服务已安装但实际未运行时发出警告。它还检查网关端口上的端口冲突（默认 18789）并报告可能的原因（网关已运行、SSH 隧道）。

17) 网关运行时最佳实践

当网关服务在 Bun 或版本管理的 Node 路径（nvm、fnm、volta、asdf 等）上运行时，诊断程序会发出警告。WhatsApp + Telegram 通道需要 Node， 并且版本管理器路径可能在升级后中断，因为服务不会 加载您的 shell 初始化。诊断程序提供在可用时迁移到系统 Node 安装（Homebrew/apt/choco）。

18) 配置写入 + 向导元数据

诊断程序持久化任何配置更改并标记向导元数据以记录诊断程序运行。

19) 工作空间提示（备份 + 内存系统）

诊断程序在缺失时建议工作空间内存系统，如果工作空间尚未在 git 下，则打印备份提示。

有关工作空间结构和 git 备份的完整指南，请参阅 /concepts/agent-workspace（建议使用私有 GitHub 或 GitLab）。