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 或包含凭据的配置发布到问题反馈中。
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、Go 和其他 Provider 的付费方式、免费模型与使用限制可能不同。
遇到限额错误时，先确认正在使用哪个 Provider、哪个账号、哪个模型，再查看对应控制台。换一个客户端不会自动重置服务商额度。套餐和模型清单会变化，以官方 Go 文档 (opens in a new tab)和Zen 文档 (opens in a new tab)为准。
4. 仍无法解决时记录什么
保留错误发生时间、操作系统、OpenCode 版本、Provider 名称、模型 ID、错误码，以及是否使用代理。按照故障排查文档查找日志，并在分享前移除 Key、个人信息和项目内容。
如果连接已经成功，但代理修改代码的行为不符合预期，应继续检查 AGENTS.md 规则和工具权限，这是另一类问题。
依据与更新
核对日期：2026-09-14。依据：官方入门 (opens in a new tab)、网络设置 (opens in a new tab)、故障排查 (opens in a new tab)。本站为社区文档，不提供模型账号或官方客服服务。