opencode 无法使用 GPT 模型报错很多人第一反应是模型不支持或者工具坏了。我在本地踩过一圈之后结论很明确大多数报错不是模型本身的问题而是安装、配置、认证和网络链路里的某一个环节没对上。用 opencode 接 GPT 模型链路上有三个要素模型名、API Key、可访问的 API 服务。opencode 只是中间那一层壳负责把你的终端指令转发给上层模型服务再把返回结果展示出来。下面按保姆级的顺序拆先让 opencode 本身能跑再配置 GPT 模型再逐条拆报错最后给一套可以直接照做的接入流程。内容基于常见版本整理实际以你当前安装的 opencode 版本为准。1. 先搞清楚 opencode 的 GPT 调用链再动手改配置1.1 opencode 是客户端不是模型opencode 是一个开源终端 AI 编程助手它的定位是“客户端”和“编排层”。它本身不产生模型能力只是把你在终端里的请求转给已配置的模型服务。这意味着你在 opencode 里能不能用 GPT 模型取决于三件事有没有配置正确的 API Key模型名是不是模型服务商真正支持的opencode 能不能连到对应的 API 服务。只要这三件事里有一件不对报错就会出现。而且报错表现往往很相似都是“模型调用失败”或“请求发送失败”。所以排查不能只看最后一行报错要按链路一步步看。1.2 调用链上的三个关键变量我把一条正常请求拆成下面这条链路终端输入 - opencode 读取配置 - 加载 API Key 和模型名 - 请求送到模型 API 服务 - 返回结果 - opencode 展示任何一个环节断了最终都会表现为某个报错。常见断点有三个API Key 没加载成功opencode 启动时没有读取到环境变量或者读取到了空值。模型名不匹配你写的是gpt-4o但服务商那边没有这个模型名或者账户没有访问权限。API 服务不可达网络不通、域名解析失败、服务商临时故障都会让请求发不出去。1.3 先把报错分类再去找原因遇到报错先别急着改配置。我一般把报错分成六类每类都有固定的检查顺序。报错类型常见表现优先检查方向认证错误Invalid API Key、401、AuthenticationErrorAPI Key 是否配置、是否过期、是否填错模型错误Model not found、404模型名是否写错、账户是否有权限限流/额度错误429、RateLimitError、quota exceeded并发是否太高、账户余额或配额是否够网络错误connection refused、fetch failed、timeoutAPI 服务是否可达、DNS、防火墙策略服务端错误500、502、503服务商临时故障稍后重试配置错误JSON parse error、provider not found配置文件格式、路径、字段名这个分类表可以帮你快速锁定方向。后面每一类都会有更细的解法。2. 安装和启动阶段先让 opencode 本身能跑起来2.1 命令找不到怎么办Windows 的 cmdlet 报错很多人下载安装 opencode 后在 PowerShell 里执行opencode会看到类似这样的错误opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个报错和 GPT 模型没有关系是系统 PATH 里找不到opencode的可执行文件路径。常见原因有三个安装过程没有把 opencode 所在目录写进 PATH安装后没有重开终端进程安装目录比较特殊PowerShell 没有刷新环境变量。解法分两步。第一步手动刷新当前终端的 PATH 环境变量不用重开电脑$env:Path [System.Environment]::GetEnvironmentVariable(Path,Machine) ; [System.Environment]::GetEnvironmentVariable(Path,User)第二步确认 opencode 能不能被找到Get-Command opencode opencode --version如果能输出版本号说明命令已经可用。如果还是找不到就检查 opencode 可执行文件所在的目录然后把它手动加到系统 PATH 里。安装时如果有输出安装路径优先看那个路径。不要反复重装先确认路径后再动 PATH。2.2 Linux/macOS 安装后闪退或权限不足Linux 和 macOS 上常见的坑是权限不够。用官方安装脚本或 npm 全局安装时如果当前用户没有写权限会出现类似EACCES: permission denied的错误。处理顺序是先看位置which opencode ls -l $(which opencode)如果文件存在但没有执行权限可以加上执行权限chmod x $(which opencode)如果which opencode没有输出说明命令不在 PATH 里。检查安装脚本输出的安装目录比如~/.opencode/bin或~/.local/bin之类的目录然后把它加入 shell 配置export PATH$HOME/your-install-dir:$PATH改完后执行source ~/.bashrc或source ~/.zshrc再验证一次。2.3 安装后第一件事确认版本和帮助信息不管什么平台装完后第一件事不是马上接 GPT 模型而是先确认命令行工具本身是正常的。执行opencode --version opencode --help如果这两条命令都正常说明安装阶段没有问题了。后面再报 GPT 相关错误就可以把重点放到模型配置和网络链路上。这一步能省掉很多无意义的重复安装。注意如果你用的是桌面版、VS Code 插件或 Idea 插件插件内部往往也是调用 CLI 或本地服务。遇到模型报错时先用命令行版验证能更快区分是插件问题还是模型配置问题。3. GPT 模型配置五个最容易出错的点3.1 API Key 没有加载进环境变量GPT 模型能不能用第一个关键就是 API Key。opencode 读取 Key 的常见方式是通过环境变量比如OPENAI_API_KEY。配置地方不对或者配置后没有在当前终端生效就会出现 401 或 Invalid API Key。Linux 和 macOS 临时设置export OPENAI_API_KEYsk-你的key opencodeWindows PowerShell 临时设置$env:OPENAI_API_KEYsk-你的key opencode临时设置只对当前终端窗口有效。如果你重开终端后没有重新设置Key 就没了。所以我建议把 Key 写进 shell 配置文件。以 macOS/Linux 为例echo export OPENAI_API_KEYsk-你的key ~/.zshrc source ~/.zshrcWindows 用户可以把 Key 写进系统环境变量或者在 PowerShell profile 里配置。配置后不要用echo把完整 Key 打印出来只检查前几位即可echo ${OPENAI_API_KEY:0:8}如果输出为空说明 Key 没有真正进入当前终端的进程opencode 必然拿不到。3.2 模型名写错模型名写错是最常见的人为错误。OpenAI 系模型常见名字包括gpt-4o、gpt-4o-mini、gpt-4.1、gpt-4.1-mini等。不同账户、不同服务商开放访问的模型不一样。写错模型名时openCode 通常会返回类似Model not found或404的报错。解决方法是去服务商后台的模型列表里复制完整的模型 ID不要凭记忆手敲。注意以下几点模型名区分大小写GPT-4O不等于gpt-4o名字里不要有多余空格、换行或引号如果用的是 OpenAI 兼容服务模型名要和该服务商后台一致而不是照抄 OpenAI 官方列表。3.3 Provider 和 BaseURL 不匹配opencode 支持的不只有 OpenAI 官方服务。很多第三方服务提供 OpenAI 兼容接口。这时除了 API Key还要配置 Provider 对应的 BaseURL。如果 Provider 写成了 openai但 API Key 是第三方服务商的 Key报错仍然是 401 或 403。反过来如果 Provider 写的是第三方服务但 BaseURL 指向 OpenAI 官方那请求也会失败。配置原则只有一条API Key、BaseURL、模型名必须属于同一个服务商。不要混搭。换一个服务商时把这三项当成一个整体一起换不要只改其中一项。3.4 配置文件放错位置或格式错误opencode 支持配置文件来管理模型和 Provider。常见配置格式有 JSON 或 TOML具体路径取决于版本。一般会在当前项目目录或者用户配置目录下寻找。格式错误的典型表现是JSON parse error provider not found看到这类报错先别怀疑模型直接检查配置文件。一个通用原则是先看opencode --help里有没有提示配置文件路径如果帮助信息没有就去用户目录下找opencode.json或opencode.yml之类的文件。配置结构如果版本较新可能长这样{ provider: { openai: { apiKey: {env:OPENAI_API_KEY}, models: { gpt-4o: {} } } } }不同版本字段差异很大上面是示例不是所有版本都通用。你只需要理解一个逻辑配置里必须有 Provider、API Key、模型名三个信息并且它们要指向同一个服务。配置文件里的语法错误会导致 opencode 启动时无法正确加载模型列表。3.5 默认模型和自定义模型混用有些版本的 opencode 会自带一个模型列表你在列表里选了gpt-4o但没有在配置里给这个模型配上对应的 Provider 或 API Key结果就是“选了模型但调用时出错”。建议做法是把你要用的 GPT 模型在配置里单独声明然后手动指定为默认模型。不要在自定义 Provider 里放一个 openai 默认模型名又指望 opencode 自动帮你填好 Key。比如你只用一个 OpenAI 兼容服务那就把项目配置文件里所有和 openai 官方相关的默认项都理清楚只保留你当前要用的服务。混着用最容易出现“这边看着配置没问题那边请求就是失败”。4. 常见报错逐条拆解先看状态码再改配置4.1 401/403API Key 无效或没权限报错信息类似AuthenticationError: invalid_api_key这种报错基本可以确定是认证环节出了问题。按照这个顺序排查先确认环境变量已经加载echo ${OPENAI_API_KEY:0:8}。再确认 Key 没有前后空格或隐藏换行。然后确认 Key 还能用去服务商后台看一眼状态。最后确认 Provider 和 BaseURL 与 Key 属于同一个服务。很多 401 不是 Key 本身错而是 Key 没有传到 opencode 进程里。比如在.env里写了 Key但 opencode 没加载.env或者你在终端窗口 A 里配置了环境变量在窗口 B 里启动 opencode也会漏掉。4.2 404/Model not found模型名或权限问题报错信息类似ModelNotFoundError: The model gpt-4o does not exist这时候先不着急改 opencode直接到服务商后台查询模型列表。如果列表里没有这个模型说明你的账户没有该模型访问权限或者模型名已经下线。如果列表里有但 opencode 还是报 404就检查配置里的模型名是否多写了空格或者 Provider 指向的服务商根本没有这个模型。有些服务商会把模型 ID 写成带版本号的格式比如gpt-4-0613这种旧版本。不要指望所有版本都能用。只要服务商后台明确不支持的模型换配置也没用。4.3 429限流或额度不足报错信息类似RateLimitError: You exceeded your current quota429 有两种常见情况。一种是请求频率太高超过接口限制另一种是账户余额不足或配额耗尽。先看服务商后台的剩余额度和并发限制再决定改哪边。如果你正在跑批量任务或者并发请求很高先把并发数降下来。opencode 的任务队列如果一次发太多请求很容易触发 429。不要一上来就开最大并发先用 1 到 2 个并发跑通再慢慢往上加。4.4 connection timeout / fetch failed / ECONNREFUSED报错信息类似TypeError: fetch failed这种错误和模型名无关是 opencode 到 API 服务之间的网络链路没通。可能是服务商域名在当前网络环境不可达也可能是 DNS 解析失败或者是本地防火墙拦了请求。排查方法很简单先在终端里用一条普通请求验证 API 服务是否可达。以 OpenAI 官方接口为例curl -sS https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY | head -n 20如果这条命令都连不上那问题不在 opencode而在网络链路。这种情况需要检查当前网络到 API 服务商是不是能连通或者联系网络管理员。反复重启 opencode 没有意义。4.5 上游 500/502/503服务商临时故障报错信息类似Request failed with status code 500500 以上状态码大多是模型服务商那边临时故障不是 opencode 配置问题。这时候不要频繁重试等几分钟或者去服务商状态页确认。如果连续多次都是 5xx可以怀疑是不是当前 API Key 所属的服务商节点有问题换一个服务商或换一个 BaseURL 验证。还有一种 500 是请求内容本身太大导致上游服务处理失败。常见于你让 opencode 处理超大文件或超长上下文。可以先清空对话历史再试一条小请求。4.6 400 invalid_request_error上下文超长或消息格式异常如果你的输入特别长可能出现Error code: 400 - invalid_request_error这通常是上下文长度超过模型限制。GPT 模型有 token 上限不是无限长。处理方法是清空历史、把文件拆小、或者换支持更长上下文的模型。opencode 本身没问题是请求超出了模型服务允许的范围。5. 保姆级完整接入流程从零开始把 GPT 用起来5.1 准备阶段拿 API Key、确认模型名在使用 opencode 之前先把两样东西准备好一个可用的 API Key一个当前账户可用的模型名。我建议先在服务商后台看模型列表把模型 ID 复制出来。对于 OpenAI 官方服务可以先确认gpt-4o是否能访问。如果账户是新的可能只有部分模型可用不要默认所有 GPT 模型都能用。5.2 设置环境变量设置好OPENAI_API_KEY然后让它在当前终端生效。Linux/macOSexport OPENAI_API_KEYsk-你的key echo ${OPENAI_API_KEY:0:8}Windows PowerShell$env:OPENAI_API_KEYsk-你的key $env:OPENAI_API_KEY.Substring(0,8)看到输出前几位不是空串再继续下一步。5.3 启动 opencode 并切换到 GPT 模型启动 opencodeopencode进入界面后找到模型切换入口。不同版本可能叫/models也可能是功能菜单里的 Model 选项。你可以先看opencode --help或者界面的命令提示。这里不要凭感觉选一个名字直接在模型列表里找gpt-4o或你确认过的模型名。如果你的版本支持非交互式运行也可以用一条命令先验证链路opencode run 请用一句话介绍你自己如果不支持就进界面手动发一条消息。重点是先打通最小链路不要一进来就让它读项目几百个文件。5.4 用最小请求验证第一步只问一句简单的话例如“请用一句话回复测试成功”。判断标准很明确如果模型正常回复说明 API Key、模型名、网络链路、配置文件全通如果报 401检查 Key如果报 404检查模型名如果报 timeout检查网络如果报配置错误检查配置文件。最小请求验证通过后再尝试带文件的请求或者让 opencode 读取某个目录。不要在一个报错还没定位清楚时同时改三四个配置。这样只会把问题变复杂。5.5 成功后再做项目和批量任务模型能正常对话了再进入项目场景。比如让 opencode 读一个项目里某个文件、修改某段代码、跑测试命令。项目级任务还需要额外关注几个问题项目上下文是否太大会不会触发上下文超限同时请求的文件数量是不是太多输出是否会覆盖原有文件有没有备份。批量任务不要一上来就同时处理几十个文件。先用一个小目录跑一条任务看输出格式是否正确再逐步扩展。资源占用和失败重试在项目级任务里比单条对话更容易暴露问题。注意无论是免费额度还是第三方兼容服务稳定性和官方接口不一定一致。用于学习可以长期跑生产任务前先确认服务商的稳定性、限流策略和数据安全边界。6. 最后要记住的几个边界6.1 版本更新快升级后要重新验证opencode 这类终端 AI 工具更新速度很快。今天能用的配置升级后不一定还能无脑跑。我一般会在升级后重新执行一遍最小链路opencode --version、一条简单对话、一个项目小任务。遇到升级后报错先看 changelog 或帮助信息不要直接怀疑模型。6.2 插件和桌面版的问题先用 CLI 定位VS Code 插件、Idea 插件、桌面版可能封装了不同的启动路径和配置入口。有时插件里无法使用 GPT 模型不是模型的问题而是插件没有把环境变量或配置文件传给 CLI。遇到这种情况直接回到命令行执行 opencode。命令行能跑通再回来说插件配置命令行也报同样错误才能确定是模型或配置链路问题。这个定位顺序能省很多时间。6.3 日志和输出目录要提前固定批量任务或项目级任务跑久之后日志和输出目录很容易乱。建议提前做三件事固定配置文件路径固定日志输出目录每次任务完成后检查输出内容是否完整。opencode 的日志通常会写到用户目录下的某个 log 目录具体路径以你当前版本的--help或文档为准。报错时先看日志里的请求状态码再改配置。不要只凭借前端显示的简短错误去猜。6.4 大多数“模型报错”其实是配置链路问题整理下来你会发现真正的“GPT 模型能力不行”很少见。大部分报错都集中在 API Key 没传对、模型名写错、网络链路不通、配置文件格式错误这几个点。我的建议是把最小链路先跑稳再上复杂场景。不要一上来就期待 opencode 能把所有项目任务都自动处理好也不要因为一个报错就觉得模型用不了。如果你现在正好卡在某一个报错上可以按照第 4 章的表格先分类再对应检查。这样比随便搜一个命令复制粘贴要稳得多。