终端 AI 编码代理这几年确实火得很快，但大多数人的玩法还停留在“网页版对话框里贴代码”。真正把 AI 编码能力嵌进终端工作流，让模型直接在项目目录里读文件、改代码、跑命令，效率完全是另一码事。OpenCode 是我最近一直在用的终端原生 AI 编码代理，最方便的一点是它不锁死模型，支持通过自定义模型 API 接入任意服务商。这篇文章就围绕 OpenCode 接入 API 全流程展开，讲清楚怎么用 3 步跑通自定义模型，从配置、命令到踩坑实录都给你捋一遍。适合想摆脱网页版、把 AI 编码能力嵌进本地命令行的开发者，也适合那些需要对模型服务商、模型参数做精细控制的团队。

1. 项目整体设计与思路拆解

1.1 我为什么把 AI 编码工具搬回终端

先聊几句背景。早先我用网页版 AI 编码助手，最烦的倒不是生成质量，而是上下文太破碎。我这边改了文件，那边对话框不知道；项目结构变了，还得手动把相关文件粘进去。OpenCode 这类终端原生 AI 编码代理的思路不一样，它以项目目录为工作现场，直接读取仓库文件、搜索代码、执行命令，模型看到的不再是孤零零的一段代码，而是整个项目的结构和上下文。

这带来两个很实际的好处：第一，多文件重构的时候，AI 能自己沿着调用链把相关位置都翻出来，不用你一遍遍贴；第二，改动前后对比、git 状态、编译报错这些信息，工具会主动收集并丢给模型，省掉大量“人工喂上下文”的时间。我日常维护的几个项目，提交信息、接口适配、批量重命名这类活，现在基本都是直接在终端里交给 AI 代理做，我负责审核和兜底。

1.2 OpenCode 与常规 AI 编码工具的核心差异

聊到 OpenCode，得先把它和常见工具做个对比。这里不说具体竞品，就说几个我实际对比过的维度。

我自己的感受是，OpenCode 更像“代码编辑器的协作者”，而不是“问答机器人”。它能在对话过程中直接落地修改文件，也能用计划模式先把方案列出来，等我确认再动手。对长期在终端干活的人来说，这种衔接比网页版顺手得多。

1.3 三种模型接入路线，怎么选才合适

OpenCode 支持自定义模型，这里的关键在于自定义模型 API 的接入路径。我总结下来常见的有三种：

• 官方模型接口直连：直接用某模型服务商官方接口，优点是稳定、参数全，缺点是部分厂商接口只兼容自己的协议，需要额外适配层。
• 兼容 OpenAI 协议的开放端点：很多模型服务商或者私有化部署的服务，都会暴露一个 OpenAI 兼容格式的接口。这类接口路径、鉴权方式、请求体结构都贴近 OpenAI 标准，OpenCode 最省心。
• 本地模型服务：本地部署开源模型，比如通过常见开源推理框架起一个服务，走本地地址就能访问。适合离线要求高、或者要严格控制数据出网的场景。

选型的逻辑很直接：先看你手上的模型 API 是什么协议。只要能兼容 OpenAI 的请求格式，就采用第二种路线，配置最简单。如果只能用官方独有的协议，那就得到 OpenCode 配置里做适配，成本会高一些。

2. 环境准备与配置项

2.1 安装 OpenCode 的几种方式

安装这一步比较简单，常见三种方式，挑一个跑通就行。

# 方式一：npm 全局安装 npm i -g opencode-ai # 方式二：Homebrew 安装 brew install sst/tap/opencode # 方式三：官方安装脚本 curl -fsSL https://opencode.ai/install | bash

装完可以先用opencode --version确认版本，顺便看一眼帮助信息。不同版本对配置字段的小细节可能有差异，比如某些版本把 provider 配置叫provider，某个版本可能用model关键字的写法，这都不奇怪。遇到字段对不上，优先看自带的帮助文档或配置提示。

我建议新手直接装好之后，先跑一次opencode进 TUI，简单体验一下界面，再继续下面的 API 接入。这样后面改配置出问题时，至少知道自己的诉求是往哪个方向去。

2.2 准备自定义模型 API 信息

接入模型前，你要从模型服务商那边拿到三样东西：API 地址、API 密钥、模型名称。

API 地址一般是形如https://api.example-ai.com/v1的完整端点。注意看文档里是否要求带上/v1，有的服务商文档写的是根地址，实际上模型调用路径在/v1下面；有的服务商又只写根地址，但你手动补/v1反而 404。这里后面我会专门讲踩坑。

API 密钥就是你的访问凭证，通常在服务商控制台创建，格式不一，以 Bearer Token 为主。模型名称则是你要调用的那个模型 ID，比如某个服务商的小模型叫small-model-latest，大模型叫big-model-v3之类。这个 ID 不一定是它对外宣传的名字，记得去 API 文档确认。

拿到这三样信息之后，不要硬编码进配置文件里。我习惯把密钥放到环境变量，配置里只引用环境变量名。比如：

export MY_AI_API_KEY="你的密钥" export MY_AI_BASE_URL="https://api.example-ai.com/v1"

终端重启后环境变量会丢，所以建议写进 shell 的配置文件里，或者用 direnv 这类工具按项目目录管理环境变量。团队协作时，更不要共用同一个 shell，否则密钥容易一锅端。

2.3 写一个最小可用的自定义 provider 配置

OpenCode 的配置文件叫opencode.json，可以放在项目根目录，也可以放在全局配置目录。优先级一般是项目配置优先于全局配置。先给一份最小配置：

{ "$schema": "https://opencode.ai/config.json", "provider": { "type": "openai", "name": "my-custom-provider", "baseURL": "env:MY_AI_BASE_URL", "apiKey": "env:MY_AI_API_KEY", "models": [ { "id": "small-model-latest", "name": "小模型", "context": 16000, "max_output": 4096 }, { "id": "big-model-v3", "name": "大模型", "context": 128000, "max_output": 8192 } ] } }

字段解释一下：

• type：目前常见的兼容协议是openai，表示这个端点走 OpenAI 兼容格式。如果你的服务商只提供其他协议，需要看 OpenCode 对应支持的类型。
• name：自定义 provider 的名字，随便取，目的是在配置里做区分。
• baseURL：服务商的 API 地址。用env:前缀引用环境变量，避免直接写死。
• apiKey：密钥引用，同样走环境变量。
• models：这个 provider 下挂的模型列表，id字段必须和服务商的模型 ID 完全一致，name是展示名。
• context：模型上下文窗口长度，也就是模型能看到的 token 数上限。
• max_output：模型单次最大输出 token 数，写成 4096 到 8192 之间比较常见。

越大的 context 意味着模型能一次性看到越多文件内容，但也意味着单次请求占用的资源更高。按项目实际情况调整即可，不用盲目追大。

3. 三个步骤跑通自定义模型

3.1 第一步：设置 API Key 与服务地址

这一步的核心就是让 OpenCode 启动时能读到自定义模型 API 的地址和密钥。先把环境变量准备好：

export MY_AI_API_KEY="your-secret-key" export MY_AI_BASE_URL="https://api.example-ai.com/v1"

这里有个小技巧，配置好后不要直接启动工具，先用 curl 验证一下 API 通不通。很多问题其实不在 OpenCode，而是模型服务商那边的网络、鉴权或者路径不对。

curl -s https://api.example-ai.com/v1/models \ -H "Authorization: Bearer $MY_AI_API_KEY"

如果返回 401，说明密钥有问题；如果 404，多半是路径不对，比如根路径和/v1的关系没搞对；如果返回了一串模型列表，说明凭证和基础路径都通。再进一步，可以手动发一个最小对话请求验证模型本身可用：

curl -s https://api.example-ai.com/v1/chat/completions \ -H "Authorization: Bearer $MY_AI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "small-model-latest", "messages": [{"role": "user", "content": "say hi"}] }'

能正常返回就说明万事俱备。这一步跑通的本质，是把“OpenCode 的问题”和“上游模型服务商的问题”切分开。我见过不少朋友一上来直接改配置，报错之后分不清是配置写错还是服务商那边路径不对，白白折腾半小时。先 curl，能省掉一大半排查时间。

3.2 第二步：写入自定义模型配置

环境变量确认无误后，接着把 provider 配置写进opencode.json。这里我会用和前面一致的名字：

{ "$schema": "https://opencode.ai/config.json", "provider": { "type": "openai", "name": "my-custom-provider", "baseURL": "env:MY_AI_BASE_URL", "apiKey": "env:MY_AI_API_KEY", "models": [ { "id": "small-model-latest", "name": "小模型", "context": 16000, "max_output": 4096 }, { "id": "big-model-v3", "name": "大模型", "context": 128000, "max_output": 8192 } ] } }

配置文件里我通常会放两到三个不同档位的模型，方便临时切换。比如小模型用来做批量重命名、写提交信息这些轻量任务；大模型用来做架构设计、复杂重构。OpenCode 在界面里可以通过快捷键调出模型切换列表，不用改配置。

如果你不确定自己服务商端点应该配成什么格式，有个笨办法：先按上面的模板写，然后启动 OpenCode 看报错信息，再根据报错里的路径去和服务商的 API 文档比对。这个流程虽然慢一点，但对你理解自己的接入链路非常有帮助。

3.3 第三步：启动会话并跑第一轮真实任务

配置写完之后，启动 TUI：

opencode

进入交互界面后，首先在模型菜单里确认已经能选到my-custom-provider下面的模型。选中小模型，随便问一个问题试试。能正常回复，说明管道已经通了。

如果不想进 TUI，OpenCode 也支持非交互执行。这个对做自动化非常有用，比如我用它一键生成某个模块的测试用例：

opencode run "给 src/utils/format.ts 写一组单元测试，覆盖边界情况"

跑完之后 OpenCode 会在终端显示模型的修改过程。这里要确认一下它确实调用的是你的自定义模型，而不是某个默认模型，有两个办法：

• 看模型服务商的后台请求日志，能看到刚发出的这一条请求记录。
• 在 OpenCode 界面里显示模型名的位置，能确认当前模型的 ID 是你配置的那个。

我第一次跑通时，顺手在代码里埋了一个两个数字相加的测试任务，命令行里观察它是否能沿着项目结构找到工具函数并调用，大概一分钟左右就返回了完整的改动。那会儿才真正感受到终端原生 AI 编码代理和网页版的差异：它不是“给一段代码”，而是“直接改你的代码”。

4. 常见问题与排查技巧实录

4.1 高频报错速查表

接入自定义模型 API 的过程中，绝大多数报错都属于下面几类。我把实际遇到过的和同事碰到过的整理成了表，方便速查。

第一行和第二行最常见。区分它俩的方法是看 curl 的输出：curl 返回 401，问题在密钥；curl 返回 404，问题在路径；curl 已经通了但 OpenCode 里还是报错，问题才在 OpenCode 的配置上。

4.2 让自定义模型跑得更稳的配置细节

接入跑通只是第一步，想让模型在项目里用得顺手，还得调整几个细节。

第一，上下文窗口别拍脑袋填。模型的实际 context 长度是服务商给定值，配置里填多大，OpenCode 就会按多大去组织发送内容。填大了，实际服务商不支持时会在请求时报错；填小了，模型会“看不到”前面的内容，表现成自己失忆。我一般是先查模型文档，然后把 context 填到官方标注值的 80%，留一点余量。

第二，max_output值别设太小。写代码场景经常需要生成长文件，如果输出上限只有 1024 token，模型写到一半就会被掐断。我日常设置在 4096 以上，复杂项目会设到 8192。

第三，关于重试机制。有些模型服务商会因为瞬时高峰报 429，OpenCode 内部往往有重试逻辑，但不同版本重试次数不一致。在乎稳定性的场景，我会在网络层或者调度层面再包一层重试策略，并在日志里观察实际重试次数。

第四，流式输出问题。有些兼容端点没有完整实现流式响应，直接对接会产生解析异常。如果遇到这类问题，先检查端点文档里的流式支持；不行的话，看 OpenCode 是否有关闭流式的配置项。

4.3 我踩过的几个具体坑

写这节的时候，脑子里翻出来不少过去的报错现场。挑三个最有代表性的讲。

第一个坑是 baseURL 的/v1重复。当时某个服务商给的是https://api.example.com/v1，我下意识在配置里又拼了一个v1，结果请求路径变成/v1/v1/chat/completions，一直 404。排查时 curl 手写路径去掉一个/v1就通了，回头再看配置，恨不得拍自己一下。建议：先看服务商文档里给的完整请求示例，照着把路径抄进 baseURL，不要再手动拼接。

第二个坑是模型 ID 带了时间戳。服务商控制台里展示的名字是“big-model”，但 API 文档里的模型 ID 其实是big-model-20250101这种带版本后缀的。我直接把展示名丢进去，一直报模型不存在。后来仔细看文档才发现模型 ID 得用带后缀的那个。所以填模型 ID 时，要去 API 文档或GET /v1/models返回结果里复制，不要凭印象写。

第三个坑更隐蔽：某些兼容服务商默认关闭了流式响应，但打开后偶尔会在流中间断掉。现象是对话有时能回复，有时回复到一半就停住。我排查到最后发现是服务商侧网关对长流有超时限制。这个不属于 OpenCode 配置能完全解决的问题，最终我用了一个折衷方案：把任务拆小，避免单次生成过长内容，并关闭该模型的流式开关，保证稳定。这个问题也提醒我：模型服务商和编码工具之间，兼容性并不是“看起来能用就行”，流式、重试、超时都得过一遍。

5. 进阶建议：把自定义模型接入沉淀成自己的工作流

5.1 项目级配置与全局配置分开管理

跑通自定义模型之后，我建议马上从“一次性的接入”转成“可持续的管理方式”。

全局配置放在用户目录的配置目录里，适合放那些跨项目通用的 provider 信息和默认参数。项目级opencode.json则放在具体仓库，适合放当前项目要用的专属模型和提示词。项目里如果有特殊指令，比如要求 AI 遵循团队的代码规范、命名风格，也可以在项目配置里通过 system prompt 的方式注入。这样可以做到：换一个项目 checkout 下来，打开终端opencode，它自动采用这个项目的规则，不需要手工切来切去。

这里要提醒一点：项目级配置如果含密钥，一定要用env:引用环境变量，不要写成明文。.gitignore里要把敏感配置排除掉。我这里说的是通用的密钥管理习惯，不管在什么环境、什么开发理念下都适用。

5.2 不同任务切换不同的模型策略

模型不是越大越好，也不是越贵越好。我的经验是按任务难度分层：

• 简单任务，比如生成提交信息、单文件格式化、写简单注释：用小模型，速度快、成本低。
• 中等任务，比如给函数补测试、解释一段陌生代码：用中档模型。
• 复杂任务，比如跨文件重构、技术方案设计、架构评审：用大模型。

OpenCode 在单次会话里可以随时切换模型，所以我一般会在配置里放两个档位。这样遇到复杂任务，我不会把一个 128K 上下文的大模型从头用到尾，而是先快速用一个小模型把简单部分处理完，再把最复杂的核心环节切到大模型上。算下来，成本和时间都能省不少。

如果你的团队有统一的模型接入标准，但不同成员的 OpenCode 配置五花八门，可以把一份推荐配置放在仓库的docs/下，同时维护一个.env.example文件，把需要设置的环境变量都列清楚。新成员进来照着填就行。

5.3 最后几个实用小习惯

文章快结尾了，分享几个我在实际使用中沉淀下来的习惯。

第一个习惯是：每次接入新模型，都先拿一个固定的小任务做冒烟测试。我用的固定测试内容是“读取当前仓库 README 前 50 个字，用一句话概括项目用途”。这个任务会触发文件读取、上下文组织、模型调用一整条链路，只要它能跑通，说明基本功能都正常。

第二个习惯是：注意观察模型日志，不要只在界面上看回复。OpenCode 在做复杂任务时会打印很多工具调用信息，有些问题是静默失败的，比如模型说自己改了文件，但实际文件并没有变化。如果你发现回复内容和文件改动对不上，先看日志里是否有权限拦截或者路径问题，再决定要不要手动介入。

第三个习惯是：给 OpenCode 设置好提示词层面的边界。比如让它默认不碰某些目录、不自动执行破坏性命令。这个不是配置层面的活，是要在会话开始时明确告知模型的约束。AI 编码代理已经能直接改代码，那么“什么该让它动、什么不该让它动”这件事，比“让它跑得更快”更值得花时间。

从安装、配置，到跑通自定义模型，再到日常稳定使用，整个过程说复杂也复杂，说简单也简单。核心就是把每一步验证拆开：环境变量验证链路、配置字段验证映射、任务执行验证最终效果。我自己接入自定义模型 API 断断续续折腾了好几个晚上，回头来看，最值钱的不是最后那套配置，而是调试过程中对模型 API 协议、路径规则、上下文上限这些基础概念的理解。希望你能少走点弯路，一次跑通。