排障

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

快速分层

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

启动失败

从仓库根目录启动：

./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 通常使用自己的 CLI 登录和配置。

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

运行时排障

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

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

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

编码会话卡住

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

多 worktree 冲突

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

bash scripts/status.sh

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

相关页面

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