OpenCode 故障排查指南
先确认客户端版本与报错位置，再检查凭据和模型配置。本站是独立使用指南，官方项目为 opencode.ai。
核对日期：
如何让 OpenCode 默认回答中文？
临时使用时在提示词中加上“请使用简体中文回答”。长期使用可在项目根目录的 AGENTS.md 中加入“默认使用简体中文解释与汇报，保留代码、命令与日志原文”。检查是否存在冲突的项目或全局规则；语言偏好并不保证所有模型始终遵循。
为什么执行 opencode init 不成功？
常见搜索词“opencode init”通常指 TUI 中的 /init：先进入项目目录并运行 opencode，再在交互界面输入 /init。不要直接把它当作终端子命令。运行前确认仓库范围，结束后审阅生成或更新的 AGENTS.md。
401、403、429 分别检查什么？
- 401：检查 API Key 是否失效、是否给错提供商，以及运行进程是否能读取对应环境变量。用
opencode auth list检查已配置提供商。 - 403：核对账户和模型调用权限、地区或服务策略限制。具体原因以服务商返回的信息为准。
- 429：查看限流、配额或余额说明，减少并发并按服务商建议重试；不要立即循环发送大量请求。
状态码仅是排查起点。分享日志前移除 API Key、Authorization 头和私人项目内容。
/models 中为什么找不到自定义模型？
- 确认
/connect的 provider ID 与opencode.json中provider的键一致。 - 确认自定义服务在
models中配置了真实可用的模型 ID，默认模型写成提供商ID/模型ID。 - 确认
options.baseURL是服务商要求的 API 根地址，而不是管理后台或网页地址。 - 核对协议：Chat Completions 兼容示例常用
@ai-sdk/openai-compatible；Responses 协议可能需要@ai-sdk/openai。Claude 协议不能假定与这两种格式互换。
连接超时或请求失败怎么办？
依次检查 API 域名是否可访问、地址路径是否正确、代理环境和证书配置是否匹配。不要通过关闭证书验证来绕过问题。公司网络应按团队安全策略配置；切换网络后重新测试时，使用不含敏感内容的简单请求。
需要第三方接入说明可查看AI镜像服务。模型、价格、连接表现与协议支持以服务商当前说明为准，本站不保证特定延迟或可用性。