年底这段时间AI编程工具圈子里最热闹的事莫过于大家开始折腾各种CLI编码工具接入第三方模型了。昨天在群里看到有人用Opencode跑DeepSeek的R1跑得飞起今天就有人跑来问我“Opencode到底怎么接第三方模型配置文件怎么写为什么我配了半天报错”。正好我最近把Opencode从零到一完整跑通了从安装、配置、调优到踩坑每一步都试过好几遍今天就把这份详细的接入教程完整整理出来。Opencode是一款开源的终端AI编程助手跟Codex CLI、Claude Code是同一类工具但它对第三方模型的支持非常友好不像某些工具那样锁死官方模型。这篇教程会从零开始带你完成Opencode的安装、API Key准备、配置文件编写、模型切换最后补齐常见报错的排查思路。不管你是想接DeepSeek、智谱GLM、Kimi还是本地Ollama这篇文章都能直接照着抄。1. Opencode是什么为什么大家都说它适合接第三方模型1.1 一个跑在终端里的AI编程搭档Opencode本质上是一个终端环境下的AI编程代理Agent。它跟你在Web端用ChatGPT、Claude最大区别在于它直接跑在你的项目目录里能读取你的代码、执行终端命令、修改文件、跑测试然后基于实际运行结果继续干活。你不需要把代码复制粘贴到网页对话框里它天然就“长”在项目里顺手程度比我用过的多数工具都高。跟同类的Codex CLI、Claude Code相比Opencode有几个很突出的特点。首先它是开源的代码完全公开、协议宽松这意味着你不用被绑定在某一家厂商的商业服务里数据流向和调用逻辑都在你自己掌控之下。其次它对模型提供商的支持非常丰富内置了OpenAI、Anthropic、Google、Mistral、Groq等多家主流提供商的接入配置同时兼容OpenAI格式的API。这一点非常关键——现在国内不少模型厂商比如DeepSeek、智谱、月之暗面都提供了OpenAI兼容的HTTP接口这意味着只要配置得当你可以让Opencode跑在任何一个你想要的模型上而不是被官方默认模型绑死。还有一点Opencode在交互体验上做得不错。终端里有清晰的对话流、文件改动高亮、命令执行状态展示还有多文件编辑、并发工具调用这些高阶能力。哪怕你之前没有用过类似的终端AI工具上手成本也不算高。整个项目从安装到跑通半小时以内绝对能搞定剩下的事情就是你每天怎么用它干活了。1.2 为什么必须折腾“接入第三方模型”这步刚接触Opencode的人第一次启动时会被引导使用它内置的免费模型官方托管的console通道。但这个免费通道有很明显的限制首先是并发低、速率受限人多的时候排队特别严重其次它只是一个试用性质的通道官方明确说这个免费通道只能从Opencode本身使用不能作为API接口供其他程序调用——很多人在这个问题上报错后面我会专门讲。更重要的一点是免费通道能用的模型往往只有基础型号像DeepSeek-R1这类推理模型、Claude Sonnet这类强编码模型你根本用不上。所以真正要把它用起来90%的人都会走“接入第三方模型”这条路。这里说的“第三方模型”可以是国内的大模型API比如DeepSeek、智谱GLM、通义千问、Kimi它们大多便宜且响应快国外的模型API比如OpenAI、Anthropic、Google的Gemini聚合平台比如OpenRouter一个Key能切换几百个模型不用每家单独注册本地模型比如通过Ollama跑起来的Qwen2.5-Coder、DeepSeek蒸馏版。不管选哪条路核心要解决的问题是一致的让Opencode知道去哪里请求模型API、用什么身份认证、模型叫什么名字以及用哪个SDK去跟对方的接口通信。这篇文章后面所有内容都是围绕这个核心展开的。2. 接入前必须搞懂的几个基础概念2.1 模型提供商、BaseURL、API Key 三者是什么关系这一步我建议所有人先花两分钟搞清楚否则后面配置看着就像天书。我们把整个调用链路类比成“点外卖”模型提供商Provider就是“餐厅”它生产模型。DeepSeek是一家餐厅OpenAI也是一家餐厅BaseURL就是“餐厅的地址”。每家模型厂商都会在文档里写明接口地址比如DeepSeek的地址是https://api.deepseek.comOpenAI的是https://api.openai.com/v1API Key就是“你在这家餐厅办的会员卡/取餐凭证”是厂商发给你的一串密钥用来标识身份和计费账户。当你跟Opencode说“帮我用DeepSeek-V3写一个Python脚本”它实际做的事情是拿着API Key向BaseURL这个地址发一个HTTP请求请求体里写明模型名称和对话内容然后接收返回结果渲染到终端里。整个链路就是这么简单所谓“接入第三方模型”本质就是把这几个参数正确地告诉Opencode。我遇到过不少人卡在这一步是因为把这几个概念混在一起了。比如有人以为BaseURL就是官网首页地址结果填了个https://platform.deepseek.com这当然连不上——你得填的是API的请求地址而不是网页控制台的地址。记住网页控制台是给人看的BaseURL是给程序用的两者不是一回事。2.2 OpenAI兼容协议是什么为什么它很重要这里要展开讲一个关键概念OpenAI兼容协议。OpenAI是最早把大模型API服务化的厂商之一它的HTTP接口设计包括路径、请求格式、返回格式后来成了行业事实标准。现在国内外的模型厂商几乎都对外提供一套“类OpenAI”的接口只是地址和密钥不同。这意味着什么意味着Opencode不需要为每家模型厂商单独写一套接入逻辑它只要兼容OpenAI的协议就能通吃绝大多数第三方模型。这也是为什么你会在各家教程里看到类似“xxx支持OpenAI兼容格式所以可以接入”这样的话。用大白话讲OpenAI兼容协议就像USB接口虽然不同厂商的设备长得不一样但只要接口统一就能插上去用。当然有些厂商会提供专门的SDK适配包比如DeepSeek在AI SDK生态里就有自己的适配器配置方式略有差别但底层原理完全一样。文章后面我会分别给出基于专用SDK包的配置和基于OpenAI兼容协议的配置两种写法你可以根据自己用的模型灵活选。2.3 全局配置 vs 项目配置配置文件放在哪Opencode的配置支持两个层级理解这个能避免很多“为什么我改了没生效”的困惑全局配置放在用户主目录下的~/.config/opencode/opencode.json对所有项目生效。API Key、默认模型这些适合放全局项目配置放在项目根目录的opencode.json只对当前项目生效。项目特定的模型、指令、权限可以放这里。配置合并的规则是项目配置会覆盖全局配置的同名字段。也就是说如果全局配置里默认模型是DeepSeek但某项目配置文件里把默认模型改成GLM那你进这个项目时就会用GLM。这个机制很灵活但也容易踩坑——你以为改了全局配置结果项目里有一条局部配置把它顶掉了。另外一个重要的点是环境变量。apiKey这种敏感信息除了写在配置文件里也可以用环境变量的方式提供比如export DEEPSEEK_API_KEYsk-xxx然后在配置里写apiKey: {env:DEEPSEEK_API_KEY}。这样即使配置文件不小心被别人看到也不会泄露密钥。我自己的习惯是能走环境变量就走环境变量尤其是多人协作或代码要提交到Git仓库时一定要用环境变量否则等于把钥匙挂在门口。3. 环境准备安装Opencode和准备API Key3.1 安装OpencodemacOS / Linux / Windows 三平台说明Opencode的安装方式非常友好官方提供了脚本一键安装也支持通过包管理器安装、手动下载二进制文件。macOS用户如果装了Homebrew一条命令就搞定brew install sst/tap/opencodeLinux和macOS通用的官方脚本安装curl -fsSL https://opencode.ai/install | bashWindows用户我建议优先用Scoop如果你装了的话scoop install opencode装完以后执行opencode --version验证一下能看到版本号就说明装好了。如果没有大概率是PATH变量没配置好把Opencode的安装目录加到PATH里即可。安装工具这种事我多说一句不要偷懒用老旧的版本。Opencode迭代速度很快很多新模型的支持和bug修复都依赖新版本我遇到过一次因为版本太旧导致无法识别新模型的配置升级到最新版就正常了。建议安装完成后顺手跑一次opencode upgrade确认拿到最新版。3.2 获取DeepSeek API Key详细步骤和费用预估我自己用得最多的是DeepSeek这一步就拿DeepSeek举例其他厂商流程大同小异。先去DeepSeek开放平台platform.deepseek.com注册账号登录后在控制台的“API Keys”页面创建一个新的Key。创建时它会让你设置一个备注名方便你记住这个Key是干嘛用的。创建完成后Key只显示一次一定要立刻复制保存关掉页面就再也看不到了。关于费用DeepSeek的定价目前大概是deepseek-chatV3输入百万token几块钱输出百万token十几块钱这个量级具体以官网实时价格为准。平时写代码、改bug跑一天可能也就几毛钱比某些海外模型便宜一个数量级。这也是为什么这么多人折腾DeepSeek接入——性价比确实高。拿到Key之后建议先在本地终端里用curl快速验证一下这个Key能不能用curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d {model:deepseek-chat,messages:[{role:user,content:你好}],max_tokens:50}能返回一段JSON就说明Key没问题。这一步花一分钟能帮你后面排查问题时少绕很多弯——至少你知道问题不在Key本身。3.3 本地模型党先装好Ollama如果你打算接入本地模型比如Qwen2.5-Coder、DeepSeek蒸馏版那你需要先装Ollama。Ollama可以理解成“本地版的模型管理器”一键拉模型、一键跑服务。安装Ollamacurl -fsSL https://ollama.com/install.sh | sh然后拉取你想要的模型比如ollama pull qwen2.5-coder:7b拉完以后启动服务ollama serve默认监听在http://localhost:11434。记住这个地址后面配置Opencode时要用。本地模型的优势是数据不出机器、不需要联网、没有额外的API费用缺点是模型小的话能力有限且非常吃CPU/内存/显存。你要是只有8G内存的笔记本跑7B模型会很吃力建议至少16G内存起步有独显更好。4. 核心环节手把手配置Opencode接入第三方模型4.1 第一次启动与默认配置路径安装完成后在任意项目的根目录执行opencode如果是第一次启动它会进入一个交互式的初始化流程问你要不要登录或者使用内置免费通道。这里你可以先直接回车跳过或者选“暂不”因为我们后面要手动写配置文件。Opencode正常启动后会生成默认配置文件目录Linux和macOS在~/.config/opencode/Windows在用户AppData下的对应目录。我个人建议一开始就直接告诉Opencode“我用第三方模型”省得它老想着引导你走内置通道。另外如果你在项目里发现已经有opencode.json这个文件那说明项目级配置存在后面改配置时要注意是改全局还是改项目。4.2 配置DeepSeek最常用、最多人问的方案现在进入正题。打开~/.config/opencode/opencode.json没有就新建写入如下配置{ $schema: https://opencode.ai/config.json, provider: { deepseek: { npm: ai-sdk/deepseek, name: DeepSeek, options: { apiKey: {env:DEEPSEEK_API_KEY}, baseURL: https://api.deepseek.com }, models: { deepseek-chat: { name: DeepSeek V3 }, deepseek-reasoner: { name: DeepSeek R1 } } } }, model: deepseek/deepseek-chat }逐行解释一下provider字段声明了一个名为deepseek的模型提供商npm字段指定Opencode用来跟DeepSeek API通信的SDK包这里用的是AI SDK的DeepSeek适配器options里的apiKey和baseURL分别是认证密钥和接口地址models字段列举了这个提供商可用的模型。deepseek-chat就是V3对话模型deepseek-reasoner就是R1推理模型最外层的model字段设置默认模型格式是“提供商名/模型名”。写完保存后在项目里重新运行opencode。如果一切正常你会看到它用DeepSeek V3来响应你的消息。我们可以先发一句“你好请介绍一下你自己”确认能正常对话再开始干正事。如果你不想用环境变量也可以直接把Key的字符串写在apiKey字段里但千万要注意别把配置文件提交到Git仓库否则等于公开了自己的密钥。这个坑我踩过当时一个朋友把Key写死在配置里还传到了GitHub几分钟就被扫描机器人薅走了损失了一笔费用。我补充一个很多人问的点为什么这里要用ai-sdk/deepseek这个包因为DeepSeek官方推荐的接入方式之一就是走AI SDK的适配器这个包内部处理了请求格式、流式响应、错误码等细节比手写OpenAI兼容请求稳定得多。如果你不想用这个包也可以用4.4小节的OpenAI兼容写法效果差不多。4.3 配置智谱GLM / 通义千问 / Kimi举一反三DeepSeek配通了其他厂商就很简单了原理一模一样只是换一个SDK包和API地址。智谱GLM的配置示例{ $schema: https://opencode.ai/config.json, provider: { zhipu: { npm: ai-sdk/zhipu, name: 智谱GLM, options: { apiKey: {env:ZHIPU_API_KEY}, baseURL: https://open.bigmodel.cn/api/paas/v4 }, models: { glm-4-plus: { name: GLM-4-Plus }, glm-4-flash: { name: GLM-4-Flash } } } }, model: zhipu/glm-4-flash }通义千问的接入它的API地址是https://dashscope.aliyuncs.com/compatible-mode/v1模型名是qwen-plus、qwen-max这一系列。Kimi月之暗面的地址是https://api.moonshot.cn/v1模型名是moonshot-v1-8k、moonshot-v1-32k等。配置这些东西的最高效方式不是靠记忆而是去查厂商的官方文档确认“接口地址”和“模型名”这两个字段。很多时候配不上不是格式写错而是模型名写错了——比如把API文档里的deepseek-chat写成DeepSeek-V3大小写和连字符对不上接口直接返回404。4.4 万能方案OpenAI兼容协议 自定义BaseURL如果某个厂商没有专门的AI SDK适配器或者你用的是某个聚合平台比如OpenRouter甚至某个公司内部部署的模型网关怎么办别急Opencode支持直接用OpenAI兼容协议配置一个自定义Provider{ $schema: https://opencode.ai/config.json, provider: { mycustom: { npm: ai-sdk/openai-compatible, name: My Custom Provider, options: { baseURL: https://你的接口地址/v1, apiKey: {env:MY_API_KEY} }, models: { my-model: { name: My Model } } } }, model: mycustom/my-model }这个写法的关键点在于ai-sdk/openai-compatible这个SDK包它把任何“长得像OpenAI接口”的服务都包装成Opencode能识别的Provider。我在实际工作中有相当一部分第三方模型都是靠这个方案接进来的尤其是公司内部部署的模型网关和那些小众厂商的API。要注意的是OpenAI兼容协议虽然“兼容”但不同厂商在细节上可能会有差异比如有的要求请求里加上固定的额外参数有的对max_tokens命名有不同要求有的叫max_completion_tokens。遇到这种问题最直接的排查方法就是看报错内容——一般接口会明确告诉你哪个参数不合法照着调整就行。4.5 接Ollama本地模型完全离线的方案如果你要接本地模型配置如下{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ollama-ai-provider, name: Ollama, options: { baseURL: http://localhost:11434 }, models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B }, deepseek-r1:7b: { name: DeepSeek R1 7B } } } }, model: ollama/qwen2.5-coder:7b }注意到没有Ollama的配置连apiKey都不用填因为本地服务根本不需要认证。接本地模型有一个使用上的提醒本地小参数模型的编码能力跟云端的大模型还是有差距。你在让它写复杂业务逻辑时可能会频繁返工但如果是做代码解释、重构小函数、写单元测试这些相对机械的活本地模型其实表现还不错。我自己的组合是日常简单的活用本地模型跑复杂任务切到DeepSeek或GLM上这样既不浪费钱也不浪费卡。5. 实战验证让Opencode真正跑起来干活5.1 配置验证三板斧配置写好后别急着扔给AI一个巨大任务。先做三个简单验证opencode能正常启动且不报错在对话里发一句“你好”能收到正常回复让它执行一个简单命令比如ls或pwd确认工具调用链路正常。这三步都通过说明你的接入已经成功了可以开始实际使用。如果卡在第二步先别急着改配置把报错信息完整读一遍。大部分问题在报错里都能找到线索——比如“401 Unauthorized”就是Key不对“404 Model Not Found”就是模型名写错“Connection Timeout”就是地址有问题。5.2 一个真实的小任务让AI帮你写个工具脚本为了演示整个流程我用一个真实场景让Opencode帮我写一个批量重命名文件的Python脚本。我的输入是“帮我写一个Python脚本把当前目录下所有.txt文件名中的空格替换成下划线要求处理前先打印将要改名的文件列表确认后再执行。”Opencode收到任务后会先读取当前目录的文件列表确认哪些文件需要改名然后生成脚本或直接调用工具来执行。整个过程你可以在终端里看到它每一步的操作比如读文件、分析、写代码、执行命令。如果它执行完之后结果正确你就能看到文件被重命名了。这个过程看起来简单但背后其实涉及Opencode的多轮工具调用能力理解需求、检查环境、编写代码、执行代码、验证结果。配置第三方模型时模型能力越强这整条链路就越顺滑。如果你发现某个模型经常在中间步骤出错比如生成代码不规范、执行命令时犹豫不决大概率是模型本身的能力天花板不是配置问题。5.3 在VSCode等编辑器里用Opencode虽然Opencode是终端工具但很多人在VSCode里用着更顺手。你可以在VSCode的集成终端里直接运行opencode代码在编辑器里看AI在终端里跑两边不冲突。如果你想的话也可以给Opencode配置编辑器集成方便AI直接读取当前打开的文件上下文。关键词里有一个“Opencode在VSCode扩展搜不到”的问题这里顺带说一句Opencode目前主要还是以CLI工具为主官方生态里并没有一个大家熟知的VSCode扩展叫“opencode”所以你在扩展商店里搜不到它是正常的。日常使用在VSCode的终端里跑就行体验已经很好。6. 常见问题与排查技巧实录6.1 “error from provider (console): opencodes free tier can only be used from within opencode”怎么破这是最近很多人问到过的一个报错几乎成了Opencode新手区的第一道坎。这个报错的意思很明确你正在尝试把Opencode的内置免费通道当作一个普通API从Opencode外部或者其他程序里调用但官方规定这个免费通道只能从Opencode自身使用。解决思路其实很简单不要依赖内置的免费通道按照上面第4节的方法接入你自己的第三方模型API Key。一旦配置了有效的第三方Provider并把它设为默认模型这个报错就不会再出现了。如果你确实不想付费那么你也可以在Opencode内部以交互方式使用免费通道只是别想着拿它做二次封装或当API用。6.2 配置文件写了但模型没生效很多人遇到“我明明在配置里写了默认模型但opencode启动后还是老模型”的情况。最常见的原因是你同时存在项目级配置和全局配置项目级的model字段覆盖了全局配置。解决办法是检查项目根目录下有没有opencode.json如果有把它里面的model字段改掉或删除。另一个常见原因是配置文件语法错误。JSON里多了一个逗号、少了一个括号都会导致整个配置被静默忽略。这时候可以用opencode doctor这类诊断命令或者直接把配置内容贴到任何一个JSON校验工具里检查格式。配置文件的格式必须是严格的JSON不像JavaScript对象那样允许尾逗号和注释这点要特别注意。6.3 请求超时、连接失败这种情况我遇到最多的是BaseURL配置错误。常见错误包括把https://api.deepseek.com写成了https://api.deepseek.com/v1多加了路径导致404或者少写了https://前缀还有的复制配置时不小心带上了空格或换行。建议直接对照厂商文档检查BaseURL一个字符都不要错。另外如果你用的是本地Ollama连接失败大概率是ollama serve没有启动或者端口被占用。先跑到浏览器里访问一下http://localhost:11434能通再回来排查Opencode的配置。如果是端口被占用就在Ollama的配置里改个端口再把Opencode配置里的baseURL同步改掉。6.4 对话归档后去哪了Opencode的对话历史默认保存在本地的数据目录里Linux和macOS通常是~/.local/share/opencode/Windows在AppData对应的目录下。你可以用opencode list或者直接在数据目录里找到归档的对话记录。这一点对在意数据安全的人很重要Opencode的对话记录默认留在本机不会上传到任何Opencode官方的服务器。这其实也是它比某些云端工具更让人放心的地方。你接的是第三方模型的API请求是直接发给模型厂商的Opencode本身开源客户端不承担数据中转的角色。当然这也意味着你在对话里发的代码、指令等同于发给对应模型厂商了在意保密的话要么用本地模型要么注意脱敏。6.5 常见问题速查表我把这段时间实操中遇到的典型问题整理成一个速查表方便你遇到问题时快速定位。问题现象可能原因解决办法启动报free tier错误在外部调用内置免费通道配置自己的第三方API Key配置了但没生效项目配置覆盖全局配置检查项目根目录的opencode.json请求超时BaseURL写错或网络问题对照官方文档检查地址确保网络环境合规401认证失败API Key错误或未设置环境变量重新生成Key检查env引用写法404模型不存在模型名写错去厂商文档确认准确模型ID输出中断/截断上下文长度超限缩短任务拆解步骤或调整maxTokens限制终端显示异常终端编码问题检查终端UTF-8编码重启opencode最后分享几点我实际用了这段时间后的体会。第一Opencode接第三方模型这件事最核心的不是配置语法而是你要清楚每一个字段背后的含义。你理解了Provider、BaseURL、API Key、Model ID这四个概念不管未来Opencode怎么迭代、模型厂商怎么换你都能快速迁移。这也是为什么我在前面花了很大篇幅讲基础概念——它真的能帮你省下后面无数个小时的排查时间。第二多模型配合使用才是正确姿势。Opencode支持在对话中一键切模型。我自己的习惯是代码生成和修改用DeepSeek V3复杂推理和架构设计切到R1简单的终端操作和文本处理用本地7B模型跑。这样既控制了成本也保证了质量。第三善用Skills和指令配置。Opencode支持通过AGENTS.md这种项目说明文件告诉AI这个项目的技术栈、代码规范、注意事项。你会发现当AI“懂”项目背景后生成的代码质量会有一个明显提升。接到第三方模型后建议在项目里补一份简洁的AGENTS.md效果立竿见影。我踩过最大的坑就是一开始贪图方便直接用了内置免费通道结果想把它接到其他程序时才发现各种限制。老老实实配了自己的API Key之后整个世界都清净了。希望这篇教程能帮你顺利跑通少走我走过的弯路。