最近这段时间AI 编程代理工具几乎是一周一换从 Claude Code 到 Codex CLI再到 Gemini CLI我基本都试用过。但真正让我决定在某几个项目里长期留下来的是 opencode。它不像 Claude Code 那样绑定某一个模型生态也不像 Codex CLI 那样跟 GitHub 体系贴得那么紧而是一个基于终端、开源、可以自由配置模型的 AI 编码代理。今天这篇我就把这段时间折腾 opencode 的安装、配置、接模型、上生产项目的完整过程写出来包括踩过的坑和排查思路希望对正在研究 opencode 怎么用的人有帮助。这篇文章适合谁两类人。一类是想把 AI 编码代理真正用到日常开发里的工程师不管你是前端、后端还是全栈另一类是已经用过 Claude Code 或 Codex CLI想横向对比一下看看 opencode 有没有资格在工具链里占一个位置。我会从安装说起逐步讲到模型配置、编辑器集成、skills、memory、以及最常见的报错处理尽量做到你照着操作就能跑起来。1. opencode 到底是个什么东西1.1 为什么突然大家都在聊 opencode先说结论opencode 本质上是一个运行在终端里的 AI 编码代理你可以把它理解成 Claude Code 的开源替代品但它比 Claude Code 更“中立”对模型没有强绑定默认支持 Anthropic、OpenAI、Gemini、DeepSeek、本地 Ollama 等一堆 provider。你甚至可以在一个项目里随时切换模型不满意就换不用迁移整个工作流。我自己第一次注意到 opencode是因为它在技术社区的讨论热度涨得非常快。很多人拿它和 Claude Code、Codex CLI 对比核心论点其实是同一个AI 编码代理不应该被某一家模型厂商绑架。Claude Code 再强很多能力是跟 Claude 模型深度绑定的Codex CLI 则是 OpenAI 生态里的产物。而 opencode 走的是“一个终端代理 可插拔模型”的路线。你今天用 Claude 写后端明天换 Gemini 试试配置文件里改一行就行这种自由度对长期使用来说非常关键。另外opencode 的交互体验做得足够现代。它不只是一个能聊天的命令行工具而是一个完整的 TUI文本用户界面程序支持多会话、多 agent、差异对比、自动编辑文件、执行命令、调用 MCP 工具等。我第一次打开它的界面时说实话有点意外一个终端工具能做到这种完成度确实不容易。1.2 它和 Claude Code、Codex CLI、PI 这类 Agent 工具怎么选很多人在搜索里会问“opencode、Codex、Claude Code 哪个 agent 好用”或者“opencode 和 Codex PI终端 AI 代理哪个更值得用”。我个人的答案是不要先问哪个好用先问你的约束是什么。如果你追求开箱即用且你就用 Claude 模型Claude Code 依然是最省事的因为它跟 Anthropic 官方 API 的联动最自然新模型上线后也是第一时间可用。如果你深度使用 GitHub 和 Copilot 生态Codex CLI 有天然优势尤其是跟 GitHub Actions、代码评审流程结合的时候。而 opencode 的优势在于场景自由你可能有多个项目的 key 来源你可能要用国产模型或者本地模型你可能不想被某个厂商的订阅套餐绑死这时候 opencode 就是更适合的那一个。至于“PI”这类终端 agent我也试过它们更像是帮你管理命令行的对话助手和 opencode 这种能直接改文件、建分支、跑测试、修 bug 的编码代理不完全是一个物种。真要比较opencode 的定位更接近 Claude Code 和 Codex CLI而不是一个简单的终端助手。2. 安装 opencode从零到能跑2.1 三种安装方式选哪个opencode 官方提供的主流安装方式有三种npm、curl 脚本、Homebrew。我自己的使用场景比较杂Windows 和 macOS 都会用所以我试过两条路简单说一下区别。npm 全局安装命令是npm install -g opencode-ai。适合已经在电脑上装了 Node.js 的开发者。这种方式安装速度不算快但好处是版本切换方便以后升级直接npm update -g opencode-ai就行。我目前的主力环境就是这种。curl 脚本安装命令是curl -fsSL https://opencode.ai/install | bash。适合不想依赖 Node 环境或者想装到用户目录下的场景。脚本会直接把可执行文件放到你的本地 bin 目录不污染全局依赖。Homebrew在 macOS 上用brew install sst/tap/opencode也能装。这个对原生 macOS 用户最友好但 Homebrew tap 的更新可能比 npm 稍微慢一点极端情况下会滞后小版本。我个人的建议是你平时用 Node 就选 npm不用 Node 就选 curl 脚本。Homebrew 不是不行只是我不太喜欢在 macOS 上同时维护两套包管理器的软件依赖容易乱。安装完成之后在终端输入opencode --version能输出版本号就说明基础安装没问题。如果这一步报错先别急绝大多数情况是环境变量问题第三节我会专门讲。2.2 装完第一件事跑通一次对话装完 opencode 之后我建议你不要一上来就忙着写配置文件先跑一个最小可用的对话把链路打通再说。在终端直接输入opencode会进入一个交互式 TUI 界面。第一次启动时它会引导你选择模型 provider你也可以直接按esc或q退出回到命令行用非交互模式测试。比如你配置好了 Anthropic 的 key可以运行opencode run 用一句话解释什么是数据库索引如果配置正确你会看到模型返回一句通俗解释。如果返回的是报错多半是 API key 没配好或者模型名不对。很多人卡在第一步就是因为没搞明白 opencode 是“命令行的外壳 后面一大堆模型连接通道”这么个结构。你没配 key 之前它就是个空壳什么都干不了。所以别把“opencode 能不能用”理解成一个独立问题要先回答“opencode 连的是哪个模型、key 是哪个 key”。2.3 Windows 下“无法将‘opencode’项识别为 cmdlet”到底怎么救这个报错在热搜词里出现频率非常高原文一般是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。我第一次在 Windows 上装完也遇到过。这个问题的本质是你已经把 opencode 装上了但 PowerShell 在当前环境变量PATH里找不到opencode这个可执行文件。排查顺序大概是这样的先确认你确实装上了。如果你是用 npm 装的在 PowerShell 里执行npm list -g看输出里有没有opencode-ai。如果列表里有说明安装成功问题出在 npm 全局目录没有被加到系统PATH。这种情况的处理方法是找到 npm 全局 bin 目录在 PowerShell 里执行npm prefix -g然后把输出的路径拼上加到用户环境变量PATH里。加完记得关闭当前终端重新开一个窗口因为 PowerShell 不会自动刷新环境变量。如果你没有用 npm 装而是直接下载了某个可执行文件那要确认你把可执行文件放到了哪个目录并把那个目录加到PATH。还有一种情况你只是下载了压缩包解压后没有把它放到任何 PATH 目录里就换了个终端直接敲opencode那当然找不到。如果实在不想折腾环境变量可以用npx opencode-ai直接跑npx 会临时去 npm 仓库拉取并执行。这个方法适合应急但不建议作为长期用法因为每次执行的路径解析会有额外开销而且部分版本在 Windows 下通过 npx 调用时TUI 渲染可能会有问题。3. 模型接入与配置官方、免费模型与本地模型3.1 配置文件在哪长什么样opencode 的配置都集中在一个 JSON 文件里macOS 和 Linux 默认路径是~/.config/opencode/opencode.jsonWindows 上是%USERPROFILE%\.config\opencode\opencode.json。这个文件有点像你的 IDE 设置全局生效但你可以通过环境变量或者在项目目录下放一个同名配置来覆盖。一个非常典型的配置文件长这样{ $schema: https://opencode.ai/config.json, provider: { anthropic: { options: { apiKey: sk-ant-xxxxxxxx, model: claude-sonnet-4-20250514 } }, openai: { options: { apiKey: sk-xxxxxxxx, model: gpt-4.1 } } } }注意不同版本的 opencode 对字段的支持略有差异$schema的作用就是让你的编辑器能对配置文件做校验和自动补全。我建议你在 VS Code 里打开这个 JSON 文件写配置的时候会有字段提示能少踩很多坑。我看到网上很多人问“opencode mvn 配置”实际上 opencode 本身并没有一个叫mvn的配置项。你搜索这个词大概率是想问“怎么配置模型提供商provider”因为中英文输入习惯下很多教程都把 provider 简写成pv或者直接叫“模型配置”时间一长大家就开始用mvn来指代。也有小概率你确实是在 Maven 项目里用 opencode那这个问题会在后面讲 IDEA 插件的时候展开。3.2 默认模型与自定义 provideropencode 默认自带一批官方 provider 的接入方式比如 Anthropic、OpenAI、Google、DeepSeek 等。如果你用的是这些官方模型只要在配置文件里写上对应的 API key 就行不需要额外声明 provider 类型。但如果你想接一个比较小众的模型或者公司内部的 OpenAI 兼容服务那就要自定义 provider。常见写法是使用 AI SDK 的 openai-compatible 通道配置里标注npm字段、baseURL和apiKey{ provider: { my-custom: { npm: ai-sdk/openai-compatible, name: My Custom Service, options: { baseURL: https://api.example.com/v1, apiKey: sk-xxxx }, models: { my-model-1: { name: My Model 1 } } } } }这里有一个容易犯迷糊的地方options.model和models字段是两回事。options.model是给这个 provider 设置默认模型而models字段是声明这个 provider 下有哪些模型可选相当于一个模型清单。如果你在 TUI 里切换模型时发现列表是空的大概率就是只写了options.model没写models清单。接入自定义 provider 之后我建议你先跑一个最简单的opencode run hi来验证通道是否通。如果日志里出现 401说明 key 有问题如果出现 404说明baseURL拼错了如果是超时那要检查你的 API 服务本身通不通。3.3 免费模型与本地模型怎么选“opencode 免费模型”在热搜里排得很靠前。免费模型分两种一种是模型厂商官方提供的免费额度比如某些厂商注册就送 token 体验金另一种是本地模型比如通过 Ollama 跑的能塞进显存的开源模型。我个人的结论是官方免费额度适合用来测试产品流程但做正经开发的时候一定要准备好付费额度或者本地方案。免费额度通常有并发限制、有速率限制用着用着突然被限流这种体验非常影响效率。本地模型的好处是完全免费、数据不出机器、离线可用。opencode 连 Ollama 很简单在配置文件里加一个 provider{ provider: { ollama: { options: { baseURL: http://localhost:11434/v1, apiKey: ollama } } } }然后我一般会在本地跑一个 Qwen Coder 或者 DeepSeek Coder 系列的模型专门用来处理一些不太需要复杂推理的机械性任务比如批量改注释、生成单元测试框架、格式化代码。这些任务用本地小模型跑速度反而比云端大模型更快因为省去了网络往返。不过也别对本地模型抱太高期望。写复杂业务逻辑、跨文件重构、理解历史遗留代码这种高难度任务本地小模型还是会明显吃力。所以我现在的组合是云端大模型负责思考密集的核心任务本地模型负责体力活两者通过 opencode 的模型切换快捷键无缝切换。3.4 用 CC Switch、oh-my-claudecode 这类工具切换配置需要注意什么很多朋友之前用 Claude Code 的时候会配合 cc switch、oh-my-claudecode 这类工具来切换不同账号或 provider。换了 opencode 之后第一反应也是找类似工具。cc switch 这类工具的原理其实不复杂它们本质上是在帮你写或改配置文件。比如你在 cc switch 里选一个 provider它把你选的那组 API key 和 baseURL 写入 Claude Code 的配置文件。opencode 也有不少社区玩家在做类似的对接但我的建议是不要过度依赖这些图形化工具先把 opencode.json 本身读明白。原因很简单opencode 的配置结构跟 Claude Code 不一样字段名不完全通用。有些 cc switch 版本虽然做了“opencode 模式”但它写出来的配置可能不完全符合当前 opencode 版本的 schema尤其是版本升级后某些字段会被重命名。这时候你打开配置文件自己对照$schema检查一遍往往比找一个工具去“一键修复”更快。另外网上还有“opencode go 需要配合 cc switch 等工具”的说法。这里的 opencode go 基本上是社区的一些分支或封装版本核心逻辑没有变。只要你掌握了 opencode.json 的写法用不用 cc switch 都只是习惯问题不是能力问题。顺便提醒一句凡是涉及 API key 的切换工具尽量不要用那些要上传配置到云端同步的版本。key 是敏感信息最好只在本地配置和应用之间流转。这也是为什么我一直强调手动读配置文件的原因——至少你知道自己的 key 存在哪、发给谁了。3.5 关于第三方免费接口的提醒搜索热词里有“opencode hy3-free 下线了吗”这种问题。我先直接说结论这类第三方免费接口无论叫什么名字本质上都是别人转发的模型通道稳定性完全取决于维护者随时可能跑路、限流、调整格式你今天能用不代表明天还能用。我理解大家想省钱的诉求尤其是一些国产第三方通道价格确实很低。但作为开发工具稳定性比省钱重要太多。如果你在用某类第三方免费接口时突然遇到unexpected server error不要急着怀疑 opencode 坏了先想想是不是这个通道的问题。我的做法是临时切到官方 key或者本地模型确认 opencode 本身没问题再回头排查通道。一旦一个第三方通道连续出问题果断换掉不要在它上面消耗排查时间。4. 从“能对话”到“能干活”代理模式与项目实战4.1 核心命令速查opencode 安装好、配置好模型之后大家最关心的就是它能干什么。我先给一份速查命令后面再展开讲用法。opencode进入交互式 TUI适合日常开发中一边看代码一边让 AI 改东西。opencode run 需求描述非交互模式执行一次就退出。适合脚本化调用、CI 里跑、或者测试模型通不通。opencode run --agent build 描述指定某个子代理角色。opencode 内置了 build、plan 这类 agent也可以自定义。opencode models查看当前可用模型列表确认你的 provider 配置有没有生效。opencode auth login登录某个 provider 的账号体系适用于支持 OAuth 的模型服务。opencode mcp add添加 MCP 服务比如 Playwright、数据库工具、文件系统工具等。命令本身不复杂真正的难点在于怎么让 opencode 在你项目里产生有价值的输出这个需要一点使用技巧。4.2 让 opencode 接手开发项目前的三件事网上有人问“opencode 接手开发项目”到底怎么操作。我自己接过一个历史包袱比较重的 Spring Boot 项目刚开始直接对 opencode 说“帮我修一下登录接口的 bug”结果它把整条链路都改得乱七八糟反而把能跑的功能弄坏了。后来我总结了三个必须提前做的事。第一件事先让它读项目说明。如果项目里有 README、ARCHITECTURE.md 这类文档先让 opencode 通读一遍并且在对话里复述一遍它理解的项目结构确保它知道项目是干什么的技术栈是什么。没有文档的话就让它自己扫描目录并生成一份AGENTS.md作为后续所有对话的共享上下文。第二件事给出可验证的命令。不能说“帮我改一下登录流程”而要说“帮我修一下登录流程改完必须跑mvn -q test和npm run build这两个命令验证”。没有验证标准的 agent 输出是不可控的。你给它的验证命令越明确它干活越靠谱。第三件事控制改动范围。让 opencode 第一批任务集中在一个模块或一个文件上不要一上来就让它跨五个模块做重构。等它跑通小任务再逐步扩大授权范围。这个过程就像放风筝绳子一点点放别一次放完不然收不回来。4.3 用 opencode Playwright 定位前端 bug搜索热词里有一条很有针对性“opencode playwright 怎么测试前端 bug”。这个我专门踩过坑值得单独说。opencode 本身不会直接操作浏览器它需要借助 Playwright 的 MCP 服务来获得“看网页、点按钮、读控制台”的能力。先添加 MCPopencode mcp add playwright -- npx playwright/mcplatest添加成功之后你可以在 TUI 里要求 opencode“用 Playwright 打开本地开发服务器 http://localhost:5173复现一下登录按钮点击后控制台报错的问题”。opencode 会调用 Playwright MCP 启动浏览器、跳转页面、点击元素、抓取控制台输出然后基于这个现象去分析代码。这个流程听起来很自动化但实际使用中要特别注意两个点。一是开发服务器必须先启动好MCP 工具只会去访问你给它的 URL不会替你启动项目。二是在 headless 模式下某些依赖浏览器指纹、懒加载、或者 websocket 的场景可能无法正常复现遇到这种情况我一般会先手动打开页面确认 bug 能稳定复现再交给 opencode 去操作。另外Playwright MCP 跑起来之后会比较占用系统资源尤其是同时开两个窗口的时候电脑会明显变卡。我现在的做法是单独开一个 session 专门跑浏览器调试不跟主任务混在一起这样互相干扰最小。5. 进阶玩法skills 与记忆memory5.1 skills把常用操作变成可复用技能opencode 的 skills 可以理解成“给 AI 的专属操作手册”。你在某个项目里反复做的一类操作比如“给登录模块补安全日志”“按团队规范生成 commit message”“扫描 TODO 并汇总”都可以写成一个 skill让 opencode 以后用同一个标准去执行。skills 在 opencode 里的落地方式非常轻量在~/.config/opencode/skills/目录下一个技能一个文件夹里面放一个SKILL.md文件用 Markdown 写清楚技能名称、适用场景、操作步骤。一个简单的例子--- name: frontend-bug-report description: 当用户报告前端 bug 时先复现、再定位、最后给修复建议 --- 1. 使用 Playwright MCP 打开项目本地地址复现用户描述的问题。 2. 打开浏览器控制台记录所有报错信息。 3. 根据报错搜索对应源码文件定位可疑代码。 4. 输出一份 bug 报告包含复现步骤、报错信息和修复建议。写好之后opencode 在遇到符合描述的场景时会自动加载这个技能。你也可以在对话里直接说“使用 frontend-bug-report 技能处理这个问题”显式触发。我刚用 skills 的时候最大的误区是把它当成插件系统觉得要写很复杂的代码。实际上它就是一份 Markdown 说明复杂逻辑都靠 AI 自己理解你只需要把步骤写清楚。如果以后某个技能里的命令集比较固定可以再放一个 shell 脚本在同一个目录下AI 会自己调用。5.2 项目级记忆AGENTS.md 和配置文件“opencode memory”也是热搜词之一。关于 memory我想先澄清一个概念在 opencode 里最可靠、最跨会话的“记忆”不是某个自动回忆功能而是项目目录下的AGENTS.md文件。AGENTS.md类似于 Claude Code 生态里的CLAUDE.md。它放在项目根目录里面记录的是这个项目的约定、架构、构建命令、避坑点。opencode 每次开启会话时都会把AGENTS.md作为上下文读进去相当于 AI 在这个项目里的“长期记忆”。我自己习惯在接手每个新项目时第一时间让 opencode 生成一份AGENTS.md然后我再手动补上几项它不可能知道的内容比如某些历史 bug 的原因、某个目录负责人的联系方式如果是团队项目、以及不要动哪些文件。这些内容写进去之后下一次会话它就不会再犯同样的错了。对于真正的自动化记忆我的态度是保持观望。AI 编码代理这个领域很多“memory”功能其实还在早期误记、串场、过期信息的问题都可能发生。与其依赖自动记忆不如把关键信息稳定地写在AGENTS.md和 skills 里至少它们是你可以手动检查和维护的。5.3 桌面版、Superpowers、技能包怎么接搜索热词里还有“opencode 桌面版”“opencode 接入 superpowers”“opencode 安装 superpowers”这几条我一起说。opencode 官方目前的形态还是命令行优先我还没有看到官方正式发布的桌面版。网上能搜到的桌面版绝大多数是社区封装就是把 CLI 包了一层 Electron 或者 Tauri 界面本质上还是调用命令行工具。我的建议是不要迷信桌面版先用好 CLI 和编辑器插件等官方出了正式桌面版再迁移也不迟。Superpowers 是 Claude Code 生态里比较出名的一个技能包里面提供了一系列角色扮演和任务执行的技能模板。opencode 用户拿到这类技能包之后如果不做处理直接扔进去是不一定能被识别的。比较稳妥的做法是打开技能包目录把里面SKILL.md的格式和 opencode 要求的格式对齐确认 frontmatter 里name和description字段齐全再把内容合并到~/.config/opencode/skills/下。我实际用下来这类技能包给我的启发更多是写作思路上的。我不太建议把一堆现成技能全部灌进去因为技能定义越多AI 在匹配时越容易出错。我现在只保留三四个真正频繁使用的技能其他的都删掉了准确率反而更高。6. 编辑器集成VS Code、IDEA 与 Maven 项目6.1 VS Code 里用 opencode日常写代码大多数人还是离不开 IDE 或者编辑器。opencode 在 VS Code 里的体验已经不是一个“在终端里另开窗口”的水平了官方插件把整个交互面板直接嵌进了编辑器侧边栏。安装方式很简单VS Code 扩展市场搜索 opencode安装官方插件后重启编辑器。插件默认会去读你本机的 opencode 可执行文件和全局配置所以只要你命令行能跑编辑器里就能直接用。使用上我一般是这么配合的在侧边栏打开 opencode 面板选中当前工作区然后直接描述需求。它会读取当前打开的文件、编辑器里的选择区域甚至能看到终端面板的输出这比单纯在终端里操作要顺不少。有几个小技巧值得说。第一在 VS Code 里让 opencode 修改代码之前最好先按CtrlShiftP打开命令面板把当前文件保存一下免得 agent 读到的是未保存的缓存版本。第二如果项目很大插件启动时索引会卡几秒这是正常的不要反复重开面板。第三VS Code 插件里的会话和你终端里的会话不互通别指望两边能无缝切换上下文。6.2 JetBrains 系列插件与 Maven 项目注意事项JetBrains 系的用户也不用担心IDEA 和 PyCharm 等产品都有 opencode 插件可以安装。安装之后会在底部或侧边工具窗口出现一个专属面板交互逻辑和 VS Code 插件类似。但 JetBrains 用户里有很多是 Java/Maven 项目这里我想专门说下“opencode mvn 配置”这个高频搜索词。我在前面提过 opencode 没有mvn这个配置项如果你用 opencode 改 Maven 项目时构建失败问题多半出在环境不在 opencode。下面这三个点是我实际踩坑后总结的建议检查顺序也按这个来。第一确认本机 Maven 和 JDK 环境能正常构建。在 IDEA 里手动执行一次mvn -q clean compile如果这里就报错那 opencode 肯定也救不了你它是 AI不是环境修复器。第二在 AGENTS.md 里写明构建命令。比如写清楚“本项目构建使用mvn -q test不要使用 gradle”这样 opencode 就不会猜错。第三如果你给 opencode 授权的目录是整个项目它可能会试图修改pom.xml来“修复”依赖问题。这种操作我强烈建议阻止。Java 项目的依赖管理非常敏感让 AI 快速改pom.xml很可能引发连锁问题。遇到依赖缺失先自己确认是不是环境问题再决定要不要让 AI 动手。所以“opencode mvn 配置”的正确打开方式其实是“配置好本机 Maven 环境把你的构建命令写进 AGENTS.md让 opencode 学会用 Maven 替你做验证”而不是去给 opencode 装什么 Maven 插件。7. 高频报错与避坑速查7.1 命令、安装相关我把这段时间在群里看到的高频报错整理成了一个速查表先解决“装不上、跑不起”这一类现象原因处理方式PowerShell 提示无法识别 opencodePATH 未配置或安装不完整检查npm list -g确认安装存在用npm prefix -g拿到全局目录后加入 PATH重启终端输入opencode后直接闪退TUI 渲染不兼容当前终端换用 Windows Terminal、iTerm2 或 VS Code 自带终端关闭终端硬件加速用 npx 启动很慢npx 每次实时解析包临时应急可用长期还是npm i -g opencode-ai全局安装升级后配置不生效版本升级后字段兼容性变化删除旧配置中的废弃字段以$schema提示为准重写关键配置7.2 启动、服务器与报错搜索里有这么一条典型报错opencode error: unexpected server error. check server logs这条报错出现在 Windows 系统路径下很多人一看到就懵了。其实这个错误的本质是opencode 的客户端连不到它背后的模型服务或者模型服务返回了一个异常响应。排查顺序我建议这样来。第一步看提供者。如果你用的是 OpenAI 兼容的自定义接口先用 curl 直接打一下baseURL确认服务本身可用。比如curl -X POST https://api.example.com/v1/chat/completions \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d {model:my-model,messages:[{role:user,content:hi}]}如果 curl 返回正常说明问题在 opencode 配置侧如果 curl 就报错那问题在服务侧跟 opencode 无关。第二步看 key。很多第三方模型服务的 key 有 IP 白名单限制你在家里能用在公司网络下就报错这不是 opencode 的问题是服务商的策略。第三步如果服务正常、key 正常那看是不是模型名写错了。模型名是一个非常容易被忽略的坑有些服务商对模型名大小写敏感claude-sonnet-4-20250514和Claude-Sonnet-4-20250514在部分通道上表现不一样。7.3 模型、免费接口相关模型相关的排查很多时候是配置结构问题不是服务商问题。下面这几个点我几乎每周都会在社区里看到模型列表为空确认配置文件里有没有写models清单。切换模型没反应保存配置文件后需要重启 opencode 会话TUI 不是热加载配置的。同一个 key在网页端能用opencode 里报错八成是 baseURL 没写对网页端的 API 入口和客户端 API 入口经常不是同一个地址。模型能力忽强忽弱检查是不是在多个 provider 之间切换了。opencode 的 TUI 里如果显示的是 provider 名称而不是具体模型名称非常容易搞混。另外关于“免费模型”我再说一次不要长期绑定某个第三方免费接口。免费接口的生命周期不可控今天能用明天可能就下线了。你真正需要的是“稳定的模型通道 opencode 的模型切换能力”这两者的结合才是高效开发的保障。7.4 一个容易被忽略的坑同时装了两个 opencode最后分享一个我踩过的比较隐蔽的坑。有朋友可能电脑上既有 npm 全局装的 opencode又通过 curl 脚本装了一个两个版本的配置文件指向同一个目录但可执行文件版本不一样结果就是配置在终端里执行正常在 VS Code 插件里却报 schema 错误。如果遇到这种“一边能用一边不能用”的诡异问题第一件事先查 opencode 可执行文件到底指向哪个路径which opencodeWindows 上则是Get-Command opencode看到输出之后顺手再看一下配置文件路径和版本opencode --version如果你发现有多个安装源我的建议是统一成一个。要么全走 npm要么全走 curl 脚本不要混着来。混装带来的一堆玄学问题往往比多花五分钟重新安装要难缠得多。另外日常使用中我还有一个习惯每次做重大配置变更之前先备份一份opencode.json。这个文件改错了轻则模型连不上重则 AI 在项目里执行了一堆你不想让它执行的操作。备份一个文件成本很低关键时候能救命。在我的实际使用体验里opencode 最值得肯定的地方不是某个单一功能而是它把“模型自由”和“工程化能力”结合得很好。你既可以用最顶尖的云模型做复杂推理也可以用本地模型处理琐碎任务还能通过 skills 和 AGENTS.md 把项目经验沉淀下来。这个工作流的形态我觉得是接下来一段时间 AI 编程工具的主流方向。如果你正在犹豫要不要从 Claude Code 或 Codex CLI 迁过来我的建议是别急着整体迁移先拿一个小项目跑一个星期感受一下配置、交互和模型切换的节奏再决定要不要把它放进主力工具链。
