OpenCode 中转站接入指南：开源免费，多模型切换更灵活

上一篇我先把 Claude Code 的链路打通了，核心思路很简单：先把 Key 和 Base URL 配对，再做一次最小验证。

轮到 OpenCode，事情会稍微复杂一点，但不是因为它更难装，而是因为它更灵活。你既可以直接用 /connect 交互式接入，也可以走 OPENAI_API_KEY、OPENAI_BASE_URL 加配置文件这条路。对新手来说，这种灵活有时反而更容易把自己绕进去。

所以这篇我只抓一个目标：让你把 OpenCode 通过中转站接起来，并且搞清楚它到底在用哪套配置、哪一个模型。

本文继续用 Tokenfty 作为演示站点，原因和上一篇一样：控制台路径直观，适合拿来演示 OpenAI 兼容接口的接入逻辑，尤其是 Key、Base URL 和模型名这三件事，不容易搞混。

图 1：OpenCode 真正麻烦的地方不是“能不能连上”，而是“到底哪套配置在生效”。

一、先说结论：OpenCode 最容易踩的不是安装，而是配置入口太多

如果你第一次接 OpenCode，最容易遇到的不是命令报错，而是这种情况：

• 明明填过 Key 了，为什么还是不通
• 明明改了模型，为什么跑出来还是旧模型
• 明明配了环境变量，为什么项目里又不按这套走

本质上就一个原因：OpenCode 的配置入口不止一个。

常见入口包括：

• /connect 交互式接入
• OPENAI_API_KEY 和 OPENAI_BASE_URL 环境变量
• 项目级 opencode.json
• 之前留下的认证信息，比如本地 auth.json

你只要没弄清楚谁在覆盖谁，后面排错就很容易陷进去。

二、开始前先避开 4 个高频坑

1. 先别急着配项目级配置文件

第一次接入，建议先只做一件事：让它跑通。项目级 opencode.json 很适合后面做默认模型和团队规范，但不适合第一次就叠太多层。

2. 不要只填 Key，不核对模型名

OpenCode 走 OpenAI 兼容链路时，很多时候 Key 和地址都没问题，真正卡住的是模型 ID 填错了。控制台里怎么写，你就怎么抄，不要凭印象猜。

3. /connect 成功，不代表模型选择也完全对了

不少人以为连上就结束了，其实那只是 provider 认证通过了。真正跑任务时，用的是不是你期望的模型，还要再确认一次。

4. 看见 404，优先怀疑地址和模型，不要先怀疑 OpenCode

这类错误在 OpenCode 里尤其常见，因为它本身支持多模型、多 provider，一旦地址或模型不匹配，看起来就像工具坏了，实际上多数还是接入层的问题。

三、前置准备：拿到 OpenAI 兼容的 Key、Base URL 和模型名

OpenCode 这篇的核心比上一篇多一个点：除了 API Key 和 Base URL，你还要明确知道模型名。

也就是说，至少要准备好这 3 样：

• OPENAI_API_KEY
• OPENAI_BASE_URL
• 中转站控制台里实际可用的模型 ID

如果你用的是 Tokenfty，建议在控制台先确认下面几件事：

1. Key 已创建且能正常复制
2. 你要用的是 OpenAI 兼容接口，不是别的产品入口
3. 控制台有明确的接口地址说明
4. 模型列表里能看到你准备接入的模型名

这里我还是强调一句：不要自己脑补模型 ID。 很多 404 就是这么来的。

四、推荐方式：先用 /connect，最快把链路跑通

如果你是第一次接 OpenCode，我更推荐你先走 /connect。原因不是它更高级，而是它更省心。

图 2：第一次接入先求确定性，用 /connect 往往最稳；后面需要复用和规范化，再切到环境变量和配置文件。

大致流程是这样的：

1. 启动 OpenCode
2. 输入 /connect
3. 选择自定义或 Other 类型的 provider
4. 按提示填入中转站的 API Key
5. 确认它已经把认证信息写入本地

这类方式的好处是，你不用先去背一堆变量名，交互里大部分关键项都会引导你走完。

通常来说，认证信息会写到类似下面的位置：

~/.local/share/opencode/auth.json

这个路径本身不是重点，重点是你要知道：**/connect 不是只在当前窗口里临时生效，它通常会留下一份本地认证状态。** 这在后面排错时非常关键。

五、备选方式：用环境变量接入，更适合多项目复用

如果你已经不是第一次折腾这类工具，或者你明确想把配置复用到多个项目，那环境变量方式会更顺手。

常见核心变量就是两个：

• OPENAI_API_KEY
• OPENAI_BASE_URL

macOS / Linux

export OPENAI_API_KEY="tkfy-替换成你自己的API Key"
export OPENAI_BASE_URL="https://api.tokenfty.net"

如果你希望长期生效，再写进 ~/.zshrc 或 ~/.bashrc，然后执行：

source ~/.zshrc

Windows CMD

set OPENAI_API_KEY=tkfy-替换成你自己的API Key
set OPENAI_BASE_URL=https://api.tokenfty.net

这里还是那句老建议：先临时验证，通了再固化。

六、进阶一点：用 opencode.json 固定默认模型和 provider

如果你已经把基础链路跑通，那下一步就该解决“每次都要手动选模型太烦”的问题了。这时候，项目级配置文件就有价值了。

你可以在项目里放一份 opencode.json，把默认 provider 和模型写进去。示意写法可以像这样：

{
  "provider": "openai-compatible",
  "model": "gpt-4.1",
  "baseURL": "{env:OPENAI_BASE_URL}"
}

这里最重要的不是字段名写得多炫，而是两件事：

• 让模型选择跟项目绑定
• 把敏感信息尽量放回环境变量，不要直接硬编码在项目里

如果你的团队里有多人协作，这种方式会比每个人自己手填稳定很多。

七、验证是否真的接通，不要只看“能启动”

OpenCode 最容易出现的假象就是：它能打开，交互也正常，但模型根本不是你以为的那个，或者请求其实没走到你想要的中转站。

所以验证时，建议至少做两件事：

1. 先发一个很短的测试任务，比如让它生成一段简单函数或解释一段代码
2. 再主动切一次模型，确认切换后也能正常返回

只验证第一步不够，因为很多问题恰恰是在“多模型切换”时暴露出来的。

八、配不通时，按这个顺序排查最省时间

图 3：OpenCode 的排错一定要按层级来，不然你会反复改错地方。

经验上我建议这样查：

1. 先查当前会话和当前命令

如果你刚刚在当前窗口里设过环境变量，那先确认它们是不是生效了。不要一边改 shell 配置，一边又在旧窗口里测试，最后把自己绕进去。

2. 再查项目级 opencode.json

很多人以为自己改的是全局模型，结果项目里早就有一份配置把它覆盖掉了。这是 OpenCode 最典型的坑之一。

3. 再查全局环境变量和全局配置

重点看：

• OPENAI_API_KEY 是否正确
• OPENAI_BASE_URL 是否正确
• shell 配置文件是否已经重新加载

4. 最后查 /connect 留下的认证信息

如果你之前走过 /connect，本地认证文件可能还在起作用。也就是说，你以为现在是环境变量在生效，实际上可能还是旧的 provider 认证在接管。

九、3 类高频报错怎么判断

1. 401

优先查 Key。先看是不是复制错误，再看套餐或权限是否支持当前模型。

2. 404

优先查 OPENAI_BASE_URL 和模型 ID。OpenCode 这类工具里，404 很多时候不是路径真的不存在，而是你打到了不兼容的地址，或者用了站点不认的模型名。

3. 能连上，但模型切换混乱

这类问题通常不是网络问题，而是配置层级冲突。先看当前项目有没有 opencode.json，再看是不是旧的 /connect 配置还在生效。

十、这篇给一个最务实的建议

如果你第一次用 OpenCode，最稳的顺序不是“先把所有配置都学会”，而是：

1. 先去 Tokenfty 这类控制台清晰的站点拿到 Key、接口地址和模型名
2. 第一次先用 /connect 跑通
3. 跑通之后，再根据需要切到环境变量方式
4. 最后再上 opencode.json 做项目级固化

你会发现，OpenCode 真正需要掌握的不是更多命令，而是更清楚的配置边界。

十一、下一篇写什么

到这里，Claude Code 和 OpenCode 两条路已经分别打通了。下一篇我会写 Codex，重点会从“单工具接入”再往前推一步，讲清楚怎么把 OpenAI 生态下的配置做得更统一，尤其是怎么减少反复手改配置的成本。

如果你在 OpenCode 这篇里踩到的坑是 401、404、模型切换不生效，还是“明明都配了但不知道哪层在生效”，也建议你先记下来。后面统一排错篇，我会把这类问题汇总成一张更完整的对照表。