排障

排障时先定位问题属于哪一层：本地后端、前端静态产物、模型提供商、运行时 CLI，还是会话编排。

快速分层

现象	先检查	说明
页面打不开	端口和进程	后端可能没有启动，或端口被其他实例占用。
健康检查返回 HTML	API 路径	使用 /api/v1/health，不是 /health。
主聊天不可用	模型池和模型提供商凭证	主聊天和运行时 CLI 配置是两套系统。
运行时不启动	在终端直接运行 CLI	Jarvis 使用本机 Claude Code、Codex、OpenCode、Kimi Code 配置。
会话无进展	打开会话详情页	可能卡在权限、登录、长命令或工作目录问题。

启动失败

从仓库根目录启动：

./restart.sh

然后检查健康状态：

curl http://127.0.0.1:8888/api/v1/health

如果端口不是 8888，先确认 .env 或 worktree 的端口设置。

前端看起来过期

纯前端修改通常只需要重建静态产物并硬刷新浏览器：

cd frontend
npm run build

如果仍然看到旧 UI，检查浏览器缓存、service worker 和实际连接的后端端口。

模型不可用

先区分主聊天模型和运行时模型：

• 主聊天使用 Jarvis 模型池和 .env 中的内置模型提供商凭证。
• Claude Code、Codex、OpenCode、Kimi Code 通常使用自己的 CLI 登录和配置。

主聊天能用，不代表运行时 CLI 一定能用；反过来也一样。

运行时排障

在普通终端中运行对应 CLI：

claude --version
codex --version
opencode --version

如果 CLI 自己不能启动，先修复运行时安装或登录。Jarvis 不应该掩盖本机 CLI 的基础问题。

编码会话卡住

1. 读摘要胶囊，看是否有明确阻塞。
2. 打开会话详情页，检查最近输出。
3. 查找 ask_human、notify_blocked 或权限提示。
4. 如果会话上下文已混乱，考虑新开托管会话。

自主监督没有继续推进

1. 确认聊天页仍显示 自主监督 N/M，且没有达到默认 60 轮上限。
2. 打开会话列表，确认目标 worker 是睁眼状态。闭眼斜杠表示已排除，不会唤醒主脑。
3. 检查 worker 是否还有活跃任务。没有活跃的被监督 worker 时，Jarvis 会自动收敛并关闭监督。
4. 区分汇报类型：report_progress(working) 不会触发监督轮，阻塞、完成、待审、ask_human 和 notify_blocked 才会触发。
5. 如果是 Workflow，确认定义里的 auto_supervise 为 true，并且 run 是从 Workflow 启动的。

需要重新接力时，可以手动点 开启自主监督，或在主聊天使用 /supervise <任务目标>。

多 worktree 冲突

主仓库默认使用 8888。其他 worktree 应使用不同端口，避免互相停止进程或连接错数据库。

bash scripts/status.sh

重启前确认当前端口属于哪个 checkout。

相关页面

• 重启与健康检查
• 配置模型提供商
• 检查会话
• 开启自主监督
• 运行时能力矩阵