OpenCode 模型配置全攻略：从云端 API 到本地模型接入

我先说结论OpenCode 并不是那种装完就能直接用的玩具它的价值恰恰在于“什么模型都能接”。无论你手头是云端厂商的付费 API还是只想在本地跑一个开源模型只要服务协议是 OpenAI 兼容的OpenCode 基本都能搞定。这也是它最近热度一直不低的原因——同一个终端工具既能连 Claude、GPT又能切回本地的小模型写代码、改代码、做重构都能在同一个交互界面里完成。这篇内容我会直接按实操来写从安装、配置文件的原理到接入第三方 API、接 Ollama 和 LM Studio再到我实际踩过的一些坑全部整理出来。不管你是第一次用 OpenCode还是已经配好了想优化都可以按图索骥。1. 认识 OpenCode模型配置到底解决什么问题1.1 OpenCode 是什么为什么强调“模型配置”OpenCode 是一个开源的终端 AI 编码代理主程序用 Go 编写交互层是一套类 TUI 的终端界面。你可以在终端里启动它然后像聊天一样让它读代码、改文件、跑命令、提交代码它会把结果直接反馈到你的工作流里。和同类命令行 AI 工具相比OpenCode 一个很突出的特点是模型接入层做得比较开放。它底层默认走 Vercel AI SDK 的生态所以凡是这个生态支持的模型服务商都能以 provider 的形式挂进来。用户不需要改代码只要在 JSON 配置文件里声明 provider、模型名、API 地址和密钥重启就能切换。正因为这个机制“模型配置”就成了使用 OpenCode 时最先需要搞明白的部分。配置不通后面所有能力都白搭。而配置这件事说简单也简单说复杂也确实有些容易踩坑的点——比如 provider 名称写错、模型 ID 填错、环境变量没加载、本地服务端口没监听等等。这篇教程的主要目的就是把这些环节全部打通。1.2 模型配置的核心逻辑Provider 与 ModelOpenCode 的配置模型可以拆成两个核心概念Provider服务提供方和 Model具体模型实例。Provider 描述的是“去哪儿请求模型服务”它包含服务商名称、接口地址baseURL、认证方式、以及这个服务商下可用的一组模型列表。Model 则是你实际发起对话时选择的具体标识比如gpt-4o、claude-sonnet-4或者本地的qwen2.5-coder:7b。在 OpenCode 的配置里这两者通常是嵌套关系一个 Provider 下挂多个 Model。你可以在同一次会话中通过/models命令快速切换模型而不需要频繁修改配置文件。这也体现了 OpenCode 的设计思路把模型当作可插拔的资源而不是绑死在某一家厂商上。理解了这个关系你就知道为什么配置流程总是这几步先找一个能用的服务地址再给它配一个认证密钥最后声明模型 ID。后面所有章节本质上都是围绕这三步展开的细节延伸。2. 配置前准备安装与关键概念2.1 安装 OpenCode 的几种方式OpenCode 的安装方式比较常规我列几种主流渠道你根据自己环境选一种就行。通过 npm 全局安装如果你本机已经有 Node.js 环境直接执行npm install -g opencode-ai装完就能用opencode命令启动。这是最省事的方式版本更新也及时。通过 Homebrew 安装macOS 用户可以用brew install opencode安装过程会自动处理依赖后续升级用brew upgrade opencode就行。通过脚本安装项目 README 里提供了 curl 安装脚本适合 Linux 或 CI 环境快速部署。脚本会下载对应平台的二进制到本地不需要额外依赖。源码编译如果你需要修改行为或者参与开发可以 clone 仓库后用 Go 工具链自己构建。新手不建议走这条路除非你明确知道自己要做什么改动。装完之后在终端里输入opencode如果能进入交互界面基本就说明主程序没问题。接下来要处理的就是模型接入。需要说明的是不同版本的 OpenCode 配置文件路径和字段可能会有微调。如果你是老版本用户看到某些字段在新版本失效优先查看当前版本的opencode --version和官方文档不要盲目照抄旧配置。2.2 理解配置文件opencode.json、Profile 与环境变量OpenCode 的全局配置默认存放在用户配置目录下。macOS/Linux 通常是~/.config/opencode/opencode.jsonWindows 则根据系统环境变量XDG_CONFIG_HOME或用户目录来定位。你可以在启动 OpenCode 后输入/config查看当前加载的配置路径也可以直接用文本编辑器打开配置文件。配置 JSON 的顶层结构通常长这样{ $schema: https://opencode.ai/config.json, provider: { openai: { name: OpenAI, models: { gpt-4o: { name: GPT-4o } } } } }这里的$schema是编辑器提示用的写不写都不影响运行。核心是provider对象它的 key 是 provider 的唯一标识value 是该服务商的具体配置。对于 OpenAI、Anthropic、Google 这类官方服务商OpenCode 内置了默认的 baseURL 和 SDK 适配你只需提供 API key甚至不用写完整的 provider 块也能用。Profile 是 OpenCode 里用来区分“不同配置组合”的机制。简单理解一个 profile 就是一套独立的 provider 和模型配置集。你可以创建多个 profile比如一个放云端 API一个放本地模型启动时用opencode --profile local指定加载哪套。这个功能对经常切换工作环境的用户非常实用。环境变量是另一条重要的配置通道。OpenCode 约定从环境变量读取密钥比如ANTHROPIC_API_KEY、OPENAI_API_KEY这样密钥就不会被写进 JSON 文件。在配置值里你也可以写{env:VAR_NAME}的占位符让 OpenCode 在运行时动态读取环境变量。这个细节在团队协作或需要避免明文密钥的场景里很关键。2.3 API Key 获取与管理安全存放是第一优先级无论接第三方 API 还是本地模型密钥管理都值得单独说。第三方 API 通常会在服务商后台生成一个 key形如sk-...。拿到 key 后我最推荐的做法是写入 shell 配置文件比如~/.zshrc或~/.bashrcexport OPENAI_API_KEYsk-你的key然后source一下让变量生效。之后启动 OpenCode它就能自动识别到。如果你不想写进 shell 配置也可以在启动命令前临时指定OPENAI_API_KEYsk-你的key opencode但这种方式只在当前终端会话有效开新窗口就没了适合临时测试。两个安全提醒第一不要把 key 硬编码进opencode.json后把文件提交到公开仓库GitHub 的扫描机器人会盯上这类泄露第二如果用了第三方聚合服务务必确认对方有没有官方 SDK 适配或者 OpenAI 兼容接口避免因为协议差异导致请求失败。本地模型一般不需要传统意义的 API Key但很多本地推理服务为了兼容 OpenAI 客户端会要求你随便填一个占位 key比如lm-studio或ollama。这个没什么影响OpenCode 只是帮你把值原样塞进请求头而已。3. 接入第三方 API完整配置流程3.1 最小可用的 Provider 配置第三方 API 分两类一类是 OpenCode 内置支持的服务商比如 OpenAI、Anthropic、Google Gemini另一类是各种聚合平台或中转服务它们通常只提供一个“OpenAI 兼容”的接口地址需要你手动配置 provider。内置服务商最简单只要配好环境变量然后在配置文件里列出要用的模型即可。以 Anthropic 为例{ provider: { anthropic: { name: Anthropic, models: { claude-sonnet-4: { name: Claude Sonnet 4 }, claude-opus-4: { name: Claude Opus 4 } } } } }接着设置ANTHROPIC_API_KEY环境变量启动后在/models里就能看到这两个模型方向键选中回车即可切换。对于聚合服务关键是要自定义 baseURL。OpenCode 使用 Vercel AI SDK 的 npm 包来适配服务商所以配置里可以指定 SDK 包名和 baseURL{ provider: { myaggregator: { npm: ai-sdk/openai-compatible, name: My Aggregator, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_AGGREGATOR_API_KEY} }, models: { gpt-4o-mini: { name: GPT-4o mini (via aggregator) }, claude-sonnet-4: { name: Claude Sonnet 4 (via aggregator) } } } } }这里ai-sdk/openai-compatible是 AI SDK 提供的 OpenAI 兼容适配器绝大多数声称“OpenAI 兼容”的服务都能用它。{env:MY_AGGREGATOR_API_KEY}表示从环境变量读取密钥避免明文写入。3.2 环境变量与密钥映射的几种写法环境变量的引用方式我实际用过三种写法各自适用场景不同。第一种是全局环境变量。OpenCode 会隐式读取一批内置的变量名比如OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_GENERATIVE_AI_API_KEY。只要设置好官方内置 provider 就能识别不需要额外映射。第二种是配置值里显式引用。比如在上面的 provider 配置里写{env:MY_AGGREGATOR_API_KEY}适用于非标准变量名或自定义 provider。OpenCode 在加载配置时会把占位符替换成实际的环境变量值。第三种是在 shell 命令行临时设置。适合快速验证但不适合长期使用。我在实践中发现第二种写法的可维护性最好。因为 provider 配置通常比较集中{env:...}一眼就能看出这个 provider 依赖哪个变量不会出现“为什么模型报 401”时还要满世界找 key 来源的情况。另外如果你在 Windows 上使用 PowerShell设置环境变量的语法不同于 bash$env:ANTHROPIC_API_KEYsk-你的key opencode这种会话级设置同样只在当前窗口有效想持久化要用setx或系统环境变量面板。3.3 多模型切换与参数调节配置好多个模型后在 OpenCode 交互界面里输入/models会弹出模型选择列表。列表里会显示你声明的所有模型包括不同服务商的。选择后后续对话就会使用新模型。这个切换是会话级的你可以随时再切回来。除了模型本身OpenCode 还支持一些请求参数调节。常见的包括temperature控制生成随机性代码任务一般建议0到0.3创意写作可以高一点。maxTokens限制返回的最大 token 数防止长输出把上下文撑爆。topP核采样参数多数场景保持默认即可。这些参数可以写在模型定义里作为默认值。如果你在某个会话里想临时覆盖可以直接在提示词里说明“用更严谨的语气”模型通常能理解意图不一定需要真的调参。参数调节有一个经验代码相关的任务不要把temperature调得太高。之前我试过用 0.7 跑一个重构任务同一个问题连续几次给出的方案差别很大而且偶尔会输出格式不完整的代码。调到 0.2 之后输出稳定了很多。这算是模型配置里一个低成本但收益明显的优化点。4. 接入本地模型Ollama 与 LM Studio 实战4.1 为什么接本地模型怎么选型不踩坑接本地模型的核心诉求通常是这三个数据不出本机、没有按 token 计费的压力、可以离线使用。对部分开发者来说隐私敏感代码段不希望发到云端本地模型就成了刚需。但本地模型也不是万能的。你的硬件直接决定了能跑多大参数量的模型。有个粗略的参考7B 参数级别的模型量化后大约需要 4GB 到 6GB 显存13B 级别需要 8GB 到 12GB34B 级别基本要 24GB 以上。如果显存不够可以退而求其次让模型跑在 CPU 上但速度和体验会下降不少。选型方面前端或通用编码任务可以优先看qwen2.5-coder、deepseek-coder这类偏代码的模型如果机器配置一般qwen2.5-coder:3b或phi4-mini这类小模型也能应付简单的代码补全和解释。跑本地模型时建议明确一点你是在“用一台开发机做力所能及的推理”而不是在“复现云端大模型的效果”。4.2 通过 Ollama 接入一条命令跑起来Ollama 是目前最省事的本地模型管理工具它把模型下载、加载、服务暴露都封装好了。安装完成后基本流程是这样的ollama pull qwen2.5-coder:7b ollama serve第一个命令下载模型第二个命令启动 Ollama 服务默认监听127.0.0.1:11434。然后确认服务正常curl http://127.0.0.1:11434/api/tags如果返回 JSON 列表说明服务已经就绪。接下来在 OpenCode 里配置 provider。Ollama 有内置适配配置可以很简洁{ provider: { ollama: { name: Ollama, models: { qwen2.5-coder:7b: { name: Qwen 2.5 Coder 7B } } } } }配置好后重启 OpenCode在/models里选择 Ollama 下的模型就可以开始对话了。Ollama 默认不需要 API keyOpenCode 会向127.0.0.1:11434发送请求。需要注意一点Ollama 拉取模型时要注意模型标签是否完整。qwen2.5-coder:7b和qwen2.5-coder:7b-q4_K_M都是合法的 tag但下载的内容和量化精度不同。建议先看 Ollama 库里的官方 tag 说明再决定拉哪个。模型没拉下来就配置的话OpenCode 能启动但请求时大概率报 model not found。4.3 通过 LM Studio 接入图形化更直观LM Studio 是另一款本地模型运行工具它的优势是图形界面友好适合不习惯纯命令行的用户。操作要点如下在 LM Studio 里搜索并下载模型然后进入 Local Server 面板点击 Start Server它会启动一个监听127.0.0.1:1234的 OpenAI 兼容服务。启动后你可以先用 curl 验证一下接口curl http://127.0.0.1:1234/v1/models拿到模型列表后同样在 OpenCode 里配置 provider。LM Studio 走的是标准 OpenAI 兼容接口所以这里的配置方式与前面聚合服务的示例几乎一样{ provider: { lmstudio: { npm: ai-sdk/openai-compatible, name: LM Studio, options: { baseURL: http://127.0.0.1:1234/v1, apiKey: lm-studio }, models: { qwen2.5-coder-7b-instruct: { name: Qwen 2.5 Coder 7B (LM Studio) } } } } }这里apiKey可以填任意非空字符串因为 LM Studio 本地服务不会校验密钥。配置后重启 OpenCode 即可。用 LM Studio 接入时我最常踩的坑是模型标识符对不上。LM Studio 下载的模型文件名通常会带量化格式比如qwen2.5-coder-7b-instruct-q4_k_m.gguf但 OpenAI 兼容接口返回的 model id 可能只是qwen2.5-coder-7b-instruct。配置 OpenCode 时要以/v1/models返回的 id 为准不要直接照搬文件名否则请求会报 model not found。4.4 本地模型的体验边界与提速建议接完本地模型之后很多人的第一反应是“怎么这么慢”。这很正常本地模型的速度瓶颈主要在生成阶段。几个实用的提速方向第一如果显卡显存支持优先把模型完全加载进显存避免 CPU 与 GPU 混合推理。Ollama 默认会利用 GPULM Studio 里也可以在加载时选择 GPU Offload 层数。第二控制上下文长度。本地模型的小上下文窗口很容易被填满一旦超出要么报错要么会明显变慢。在 OpenCode 里可以通过/context类似命令管理会话上下文或及时开新会话避免历史越长请求越慢。第三模型参数量不要盲目选大。实测下来一台 8GB 显存的机器跑 7B 量化模型生成速度大概是每秒 20 到 40 个 token如果跑 13B 模型速度可能掉到 10 个 token 以下体验就很差了。要从根源上提升本地模型体验优先考虑换一个速度更合适的量化版本而不是硬扛大模型。我自己在 16GB 显存机器上日常用 7B 到 14B 之间的量化模型写代码、改 bug 是够用的复杂架构设计还是会切回云端模型。5. 常见问题与排查技巧实录5.1 高频报错与解决方案这里我把实际使用中最常遇到的问题整理成了一张速查表按报错信息排列方便你对照排查。报错场景可能原因解决方案invalid api key或 401环境变量没设置或 key 填写错误检查env输出里是否存在对应变量确认 key 没有多空格用curl直接请求服务商接口验证 keymodel not found配置里模型 ID 与服务商实际 ID 不一致从服务商文档或/v1/models接口获取准确的模型 ID替换配置请求超时网络连接问题或远端服务响应慢提高系统超时配置换更近的服务地址检查代理设置是否干扰了 API 请求本地服务连接拒绝Ollama/LM Studio 没有启动或端口不对确认进程在跑确认127.0.0.1端口与配置的 baseURL 一致404 错误baseURL 路径不对OpenAI 兼容接口通常需要/v1路径检查是否漏掉加载配置失败JSON 语法错误或字段名拼错用opencode --config输出加载日志用在线 JSON 校验工具检查语法这些错误里出现频率最高的是前两者。我的排查顺序一般是先看配置加载是否成功再看环境变量是否生效最后用 curl 直接请求服务商接口逐层缩小问题范围。5.2 排查技巧从日志到网络层OpenCode 提供了诊断命令遇到问题先别急着改配置按这个顺序走一遍大部分问题都能定位。第一步确认配置文件加载正常opencode --config这条命令会输出当前生效的配置内容你可以核对 provider 和 model 是否都在。第二步检查日志输出。OpenCode 会把请求日志输出到终端或日志文件具体路径可以在 TUI 里输入/logs查看。日志里能看到实际发出的请求 URL 和状态码这对判断 baseURL 是否正确很有帮助。第三步用 curl 模拟同样的请求。这是我最推荐的定位方式。比如接入 OpenAI 兼容接口时curl http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen2.5-coder-7b-instruct, messages: [{role: user, content: hi}]}如果 curl 都返回异常说明问题在服务端或网络层OpenCode 再怎么配也没用。如果 curl 正常而 OpenCode 异常再回头看配置文件的 SDK 包和模型 id 是否匹配。还有一个容易被忽略的问题代理环境变量。很多开发者在终端里设置了HTTP_PROXY、HTTPS_PROXY这些变量会让命令行工具的网络请求走代理。如果你的代理不稳定或不可用OpenCode 请求第三方 API 就会反复超时。排查时可以先临时取消代理再测试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY opencode如果取消后请求正常说明代理是瓶颈再从代理稳定性和规则方面解决。5.3 配置管理的几个小建议配置踩坑踩多了我总结出几个可以让后续使用更省心的习惯。一个是为不同场景建独立 profile。云端模型一个 profile本地模型一个 profile启动时用--profile切换。这样不会出现“本地模型配置文件里混着云端 key”的混乱情况排查问题也更清晰。另一个是配置文件的版本管理。opencode.json里的 provider 配置本质上是一份代码我建议放进 Git 仓库里。如果哪天改了配置导致 OpenCode 异常git diff能帮你快速看到改动点回滚也方便。还有一点养成用{env:...}引用密钥的习惯而不是直接写在 JSON 里。这不仅是安全考虑也是为了配置文件的通用性——换一台机器时只要有环境变量配置文件复制过去就能用不用每次手动改密钥。最后模型配置完成后建议先跑一个简单的冒烟测试比如让它解释一小段代码。不要直接上来就扔一个大型重构任务万一配置有问题一个冒烟测试就能快速暴露成本低得多。就我个人而言折腾 OpenCode 配置最值得投入的部分就是把本地模型和云端 API 都配好然后熟练使用/models快速切换。日常小任务用本地模型省心重大修改切到云端大模型保证质量。这套工作流跑顺之后OpenCode 才算真正成了日常开发的一部分。