模型网络排障

模型问题通常有三类：凭证错误、网络不可达、模型提供商响应异常。先判断问题发生在主聊天还是运行时 CLI。

先分清调用方

调用方	配置来源	先检查
主聊天	Jarvis 模型池和 .env	模型池模型提供商、base URL、API 密钥
Claude Code	Claude CLI 本地配置	claude 是否能独立运行
Codex	Codex CLI 本地配置	codex 模型提供商和默认模型
OpenCode	OpenCode 本地配置和边车服务	opencode 与边车服务健康

主聊天失败

检查：

1. 模型池是否选择了可用模型提供商。
2. base URL 是否正确。
3. API 密钥是否过期或填错。
4. 当前网络是否能访问模型提供商。
5. 后端日志中是否有超时、401、403、429 或 5xx。

运行时失败

在普通终端直接运行运行时 CLI。若 CLI 自己失败，先修运行时配置。Jarvis 不应该把运行时的模型提供商错误伪装成 Jarvis 错误。

常见 HTTP 错误

错误	常见含义	动作
401 / 403	密钥无效、权限不足或账号状态异常	检查模型提供商凭证并轮换密钥
404	模型名或 endpoint 错误	校对模型名和 base URL
429	速率限制或配额不足	降低频率、换模型或检查账号额度
5xx	模型提供商或代理服务异常	稍后重试，必要时切换模型提供商
timeout	网络慢、被阻断或模型提供商无响应	检查网络、代理和超时设置

网络和代理

如果你在受限网络环境中：

• 先用 curl 验证 base URL 可达；
• 确认代理不会拦截 SSE；
• 区分本机 CLI 代理和 Jarvis 后端进程代理；
• 不要把真实代理地址和 token 贴到公开 issue。

脱敏诊断摘要

公开求助时可以提供：

Jarvis 版本: <版本号>
调用方: 主聊天 / Claude Code / Codex / OpenCode
模型提供商: <提供商名称>
错误类型: timeout / 401 / 429 / 5xx
脱敏消息: <简短错误摘要>

不要提供真实密钥、完整请求头或私有 prompt。

相关页面

• 配置模型提供商
• 配置参考
• 排障