OpenCode 模型连接排障
如果 OpenCode 能打开，但发送消息时报错，先根据错误类型检查连接链路。重复安装客户端通常不能修复 API Key、模型权限或余额问题。本清单整理自官方文档，不代表所有提供商都使用相同错误码。
先确认问题发生在哪里
| 现象 | 优先检查 | 对应文档 |
|---|---|---|
找不到 opencode 命令 | 安装是否完成、终端 PATH 是否更新 | 安装 · Windows / WSL |
| 界面启动，但提示认证失败、401 或 403 | Provider、凭据、账号权限；403 也可能来自网络策略 | Provider |
| 连接超时、证书校验失败 | 代理、本地连接绕过、企业 CA | 网络 |
| 找不到模型或模型不可用 | 当前 Provider 的模型列表、模型 ID 与账号权限 | 模型 |
| 429、额度用尽或余额不足 | 服务商限速、套餐额度、计费账户 | Zen · 提供商控制台 |
| 修改配置后行为没有变化 | 配置位置、项目与全局配置是否冲突 | 配置 |
1. 从最小配置验证连接
先在 OpenCode 的 TUI 中使用 /connect 连接一个 Provider，再用 /models 选择这个 Provider 下的模型。发送一个简单问题，暂时不要同时启用额外插件或 MCP 服务，以便定位失败环节。
- 确认 API Key 属于当前选中的服务商，不能把不同服务商的 Key 混用。
- 查看服务商控制台，确认 Key 仍有效、模型已授权，且账户满足计费要求。
- 使用自定义 OpenAI 兼容服务时，核对其文档中的端点与模型 ID；名称相似不代表 ID 相同。
- 不要把完整 API Key 或包含凭据的配置发布到问题反馈中。
按具体报错修复
| 报错 | 先改什么 | 怎么确认修好 |
|---|---|---|
| 401 / invalid API key | 用当前服务商的密钥重新连接，并检查启动 OpenCode 的环境变量 | 小请求返回结果，同一个服务账户能查到用量 |
| 403 / access denied | 检查模型授权、组织权限和网络限制；仅换 Key 不一定有效 | 已授权模型能从目标网络正常请求 |
| 404 / model not found | 对齐提供商前缀、准确模型 ID 与端点协议；自定义 base URL 避免重复 /v1 | 所选模型在配置端点成功返回 |
| 429 / rate limit | 区分每分钟限速与余额用尽；降低并发或处理账户额度 | 限制重置或账户修正后请求成功 |
| TLS / certificate error | 用 NODE_EXTRA_CA_CERTS 指定企业 CA，从该环境重启 | 保持证书校验开启时 HTTPS 正常 |
自定义网关可对照API 配置模板放置端点、密钥与模型 ID。固定同一个请求和模型，每次只改一项，避免同时换配置后无法判断原因。
2. 公司网络或代理环境
OpenCode 支持标准代理环境变量。TUI 还需要连接本地服务，因此应让本地地址绕过代理。以下是 macOS/Linux shell 示例，代理地址需替换为你实际使用的地址；Windows 请使用对应终端的环境变量语法。
# 配置实际可用的代理；保留已有的其他绕过项。
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1${NO_PROXY:+,$NO_PROXY}设置后，从同一个终端启动 OpenCode。终端中设置的变量不一定会传给已经打开的桌面应用。
企业网络使用自定义 CA 时，按管理员提供的证书设置 NODE_EXTRA_CA_CERTS，具体步骤见网络配置。不要通过关闭 TLS 校验掩盖证书错误。
3. 区分免费软件与模型费用
OpenCode 客户端免费，不意味着所有模型调用都免费。Zen 和其他 Provider 的付费方式、免费模型与使用限制可能不同。
遇到限额错误时，先确认正在使用哪个 Provider、哪个账号、哪个模型，再查看对应控制台。换一个客户端不会自动重置服务商额度。使用 Zen 时，查看模型价格与消费设置；使用其他服务商时，检查该账户的用量和限速设置。
4. 仍无法解决时记录什么
保留错误发生时间、操作系统、OpenCode 版本、Provider 名称、模型 ID、错误码，以及是否使用代理。按照故障排查文档查找日志，并在分享前移除 Key、个人信息和项目内容。
如果连接已经成功，但代理修改代码的行为不符合预期，应继续检查 AGENTS.md 规则和工具权限，这是另一类问题。