今年代码助手的圈子是真的热闹Codex CLI 开源之后Claude Code 又火了一把社区里还冒出来一个叫 opencode 的终端 Agent。我本来是抱着试试看的心态装的结果连续用了一个多月现在每天打开终端第一件事就是敲 opencode。这篇文章就把我这段时间的使用经验完整记录下来从安装、配置、模型接入到 Skills、Memory、LSP 这些进阶功能再到 VSCode/IDEA 插件和桌面版怎么配合用最后把我踩过的坑和报错解决方案一并列出。如果你正在选型 AI 编程助手或者刚把 opencode 装好却不知道怎么配置这篇应该能帮你省下不少时间。1. 为什么是 opencode它和 Codex、Claude Code 的定位差异1.1 终端 Agent 到底在解决什么问题先说终端 Agent 这类工具的定位。它跟你在 IDE 里装个 Copilot 完全不一样Copilot 是你写一半它帮你补全而终端 Agent 是你把任务交给它它自己读代码、改代码、跑命令、看报错然后给你交付结果。opencode 的交互基本都在终端里启动后是一个交互式 TUI 界面左边是会话历史右边是当前任务的对话流你能看到它每一步在干什么——读了哪个文件、执行了什么命令、改了什么内容。这种形态最大的好处是你不用把上下文来回复制粘贴。它可以直接访问项目目录自己定位相关文件自己跑测试来验证修改是否正确。说白了它把写代码这件事从补全键变成了提需求 验收。一开始我也觉得这玩意儿是不是噱头但真正跑了一个重构任务之后我意识到终端 Agent 的价值不在于自动补全得有多准而在于它能替你完成读代码—理解—动手改—验证这个完整闭环。1.2 和 Codex、Claude Code 的核心差异当时我手上同时装了 OpenAI Codex CLI 和 Claude Code对比着用了几天最后长期留下来的是 opencode原因很具体维度opencodeCodex CLIClaude Code模型绑定程度多模型可切换主要围绕 OpenAI 系列围绕 Claude 系列Skills 自定义有用 Markdown/脚本定义有但生态成熟度一般支持插件Memory 跨会话支持有限依赖项目内约定LSP 接入支持近期加入支持编辑器插件VSCode/IDEA 都有依赖外部官方 IDE 扩展配置复杂度中高灵活低中后面几节会具体展开。这里我想强调一个观点选哪个工具本质上不是比谁更聪明而是比谁更适合你的工作流。Codex 的优势是跟 OpenAI 生态无缝Claude Code 的优势是 Anthropic 模型本身的编码能力而 opencode 的优势则是我不绑定你的模型你想接哪家接哪家想做技能就做技能想记长期记忆就记。我用 opencode 接 Anthropic 的模型时基本能获得和 Claude Code 接近的编码体验但同时又能在同一个工具里切到 OpenAI、本地 Ollama甚至一些聚合网关提供的模型。这种灵活性对我这种哪个模型好用就用哪个的人来说比单一厂商深度绑定更舒服。1.3 适合什么人用按我自己的体会这几类人最适合用 opencode一是手里有多家模型 API比如 OpenAI、Anthropic、Google或者本地模型的人因为可以在一个会话里动态切模型二是团队里希望把代码规范、提交流程这类东西沉淀成 Skills 的人三是喜欢终端工作流、不想被 IDE 绑住的开发者。反过来如果你完全不想读配置、不想折腾只想要一个开箱即用的助手那 opencode 的默认配置会让你有点懵因为它默认不绑定任何厂商模型你得先配一个 provider。换句话说opencode 给你的是全套工具但调校这件事它也交给了你。用好了它是利器用不好你就只会觉得怎么配了这么久还不能跑。2. 安装 opencode 的几种方式以及 cmdlet 报错的根源2.1 安装方式与版本选择安装这事看起来简单其实有坑。opencode 的版本迭代非常快不同版本对 Node 版本的要求也不一样我建议优先看官方仓库 README 里最新的安装命令但一般来说有这么几种方式npm 全局安装npm install -g opencode某些版本包名是 opencode-ai以 README 为准Homebrew 安装brew install opencodemacOS 上比较省事直接下载二进制从 GitHub Releases 下载对应平台的可执行文件解压后加入 PATH我的习惯是用 npm 装因为后面升级方便npm update -g opencode一条命令搞定。用二进制的话升级就得重新下载替换稍微麻烦一点。但 Windows 上如果 Node 环境本身比较乱直接下二进制可能更省心至少不会出现npm 全局目录到底在哪这种问题。另外提醒一句opencode 的 2.0 版本和早期版本在配置结构上有不少变化。网上很多教程截图还是老版本界面所以你在搜资料的时候最好确认对方用的版本和你一致否则照着抄可能配不出来。2.2 Windows 下 无法将 opencode 项识别为 cmdlet 的排查这是搜索热词里出现频率很高的问题我自己也遇到过。现象是在 PowerShell 里执行 opencode报opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的根源90% 是命令文件存在但终端找不到。拆开来说就两层原因。第一层npm 全局安装的 bin 目录没有加到系统 PATH 里。很多人以为npm install -g之后命令就全局可用了实际上 npm 会把可执行文件放进类似%APPDATA%\npm的目录这个目录必须在 PATH 里PowerShell 才会去搜。检查方式是在 PowerShell 里执行npm config get prefix拿到全局目录再确认这个目录在 PATH 环境变量中。第二层安装完成之后没有重开终端。PATH 环境变量在终端启动时就读取了安装完命令后你需要新开一个终端窗口或者执行下面这行命令手动刷新当前会话$env:Path [System.Environment]::GetEnvironmentVariable(Path,Machine) ; [System.Environment]::GetEnvironmentVariable(Path,User)如果这两步都做了还报错再用npx opencode --version验证一下包本身有没有装好。能输出版本号说明只是 PATH 问题如果 npx 也报错那就是安装本身失败了需要检查 Node 版本和 npm 日志。2.3 安装后第一件事认证opencode 不像 Codex 那样默认绑定登录账户它需要你主动配置认证信息。不同模型商的认证方式不同一般有两种通过opencode auth login交互式登录适用于 OpenAI、Anthropic 这类支持 OAuth 的厂商。在配置文件中直接写 apiKey或者设置环境变量适用于大多数第三方 API。我第一次用的时候直接跳过了认证步骤结果启动后每个模型请求都报 401还以为是软件坏了。所以装好之后先花一分钟把认证搞定再开始玩其他功能。这里也顺便回答热搜里opencode 是哪家公司的这个疑问它不是一个商业大厂的产品更多是开源社区驱动所以在使用方式和文档上都有点极客气质别指望它有商业软件那种新手引导。3. 一份能跑通的配置模型接入与免费模型的取舍3.1 配置文件放哪opencode 的配置约定类似很多现代 CLI全局配置放在用户目录的~/.config/opencode/下项目级配置放在项目根目录的.opencode/下项目配置会覆盖全局配置。这个设计非常实用尤其当你同时在几个项目里用不同模型组合的时候。我在公司接了一个老项目用的是 Java Maven另一个个人项目是 TypeScript pnpm。如果只靠一个全局配置每次切换项目都要改半天。有了项目级配置我可以在各自的.opencode/目录里放不同的模型偏好和 LSP 设置互不干扰。3.2 config.json 的基础结构我当前项目的配置结构大致是这样的具体字段名会随版本变化以你实际版本为准{ provider: { openai: { apiKey: {env:OPENAI_API_KEY}, model: gpt-4.1 }, anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4 }, ollama: { baseUrl: http://localhost:11434, model: qwen3-coder } }, default: anthropic, lsp: { enabled: true }, memory: { enabled: true } }先别急着照抄因为 opencode 的配置字段经常调整我见过好几个版本用 provider、model、lsp、memory 这些键但也见过用 models 数组的写法。所以最稳妥的路径是装好之后先跑一次opencode让它生成默认配置文件再基于默认配置去改而不是从网上复制一个可能已经过时的配置。这样你至少能知道当前版本认识哪些字段改起来心里有底。3.3 免费模型能用但别期待太高热搜里有很多人问 opencode 免费模型说明大家确实希望零成本跑起来。目前社区里提到的免费渠道大致有三类一是部分云厂商提供的免费额度 API二是本机跑的 Ollama 开源模型三是某些平台送的试用积分。我的实际感受是免费额度类适合写脚本、改小 bug、回答技术问题但通常有每分钟请求数限制跑长任务时容易断。本地模型类完全免费且没有频率限制但编码能力跟商用模型有明显差距尤其是大仓库重构这种任务经常改着改着就丢了上下文。试用积分类适合短时间体验不适合作为日常主力。我自己现在的方案是日常主力用付费 API本地 Ollama 作为备用免费额度只用来做一次性咨询。如果你真的想完全免费跑 opencode我建议接受它只适合做辅助编程不能全托管这个现实否则体验落差会很大。3.4 模型切换的日常姿势opencode 的 TUI 里一般支持会话中切换模型快捷键通常是CtrlM或者/models命令不用重新启动。这个功能对我来说很重要因为让 agent 读代码、梳理逻辑用便宜模型就行改一段复杂算法再切到更强的模型能省不少 token 费用。打个比方这就像你不可能天天开着货车去上班但在搬家那天你肯定会租一辆。opencode 把选什么车这件事完全交给你而不是规定你每天都只能开同一辆。对我来说这是它最值钱的地方。4. Skills、Memory、LSPopencode 最值得花的三个进阶功能4.1 Skills把团队规范变成可复用技能Skills 是 opencode 里我很喜欢的一个设计。简单说你可以把一些固定的操作流程、代码规范、提示词模板做成一个技能包让 agent 在对应场景自动或按需调用。比如我在团队里遇到最多的场景是提交代码前要跑 lint 和单测并且遵循 commit message 规范。以前在 Claude Code 里我会在会话里反复粘贴这段要求而 opencode 里我可以写一个 skill在.opencode/skills/precommit/下建一个SKILL.md里面写清楚触发条件和使用步骤当用户提到提交或准备 PR的时候先执行pnpm lint再执行pnpm test最后按 Conventional Commits 格式生成提交信息。实际用下来这个 skill 的稳定性比我手动粘贴提示词高很多因为 agent 会在相关节点主动去读这个文件而不是只靠一次上下文的记忆。写 skill 有几个小技巧触发词要写明确模糊的触发条件会让 agent 有时候用有时候不用。步骤尽量编号避免让它自由发挥。每个 skill 只聚焦一个目标别把一堆规则塞进一个文件。我见过有人把公司代码风格和部署流程写在同一个 skill 里结果 agent 在改代码时跑去执行部署命令差点酿成事故。所以技能一定要单一职责宁可多建几个目录也别贪心。4.2 Memory跨会话的长期记忆Memory 解决的是昨天聊过的东西今天不要再解释一遍。opencode 的 memory 会把一些长期信息持久化下次会话自动加载。比如你可以告诉它这个项目的测试框架是 Vitest不要用 Jest它会记下来下次会话再让它加测试时它就不会默认生成 Jest 的测试。用法上我喜欢在会话开始时直接说记住...也可以主动查看/编辑 memory 文件。不过要提醒一点memory 默认是项目级的还是全局级的不同版本设计不同如果你发现记忆串项目了检查一下配置。我有一次在 A 项目里让它记住了不要动 public 目录结果切到 B 项目它也在守这条规则搞得我排查了半天。4.3 LSP让 Agent 从猜代码变成读代码LSPLanguage Server Protocol语言服务协议本来是给编辑器用的opencode 把它接进来之后agent 就能像 IDE 一样获取更准确的代码语义。具体体现为跳转定义、查找引用、获取类型信息。以前 agent 改代码经常靠正则和文本扫描改了 A 文件忘了 B 文件的引用接了 LSP 之后它能拿到真实的符号关系修改前会先找到所有引用它的地方漏改的情况少了很多。配置上主要是确认 config.json 里lsp.enabled为 true。不过有一点要注意LSP 需要项目里装好对应的语言服务比如 TypeScript 项目要有 node_modules 里的 typescriptJava 项目要有对应的 LSP 配置否则开了也白开。我见过有人开了 lsp.enabled 之后抱怨怎么没效果一看项目里连语言服务都没装那当然不起作用。5. 从终端到编辑器VSCode / IDEA 插件和桌面版的实际体验5.1 VSCode 插件终端的 Agent 进到编辑器虽然 opencode 的主力场景是终端但写代码这件事最终还是落在编辑器里所以 VSCode 插件很有价值。我在 VSCode 里装好 opencode 插件后主要用三个功能。一是选中代码后让 agent 解释或重构。在编辑器里选中一段复杂逻辑右键发送给 opencode它能结合整个项目的上下文来分析而不是只看选中片段。这个能力比单独把代码贴给 ChatGPT 要强很多因为 agent 能自己去找相关的接口定义和调用方。二是修改建议以 diff 形式呈现。和终端里的无差别输出相比编辑器里的 diff 预览我可以直接逐个 hunk 接受或拒绝不会出现改了一大堆不是我要的的失控感。这个交互方式我觉得是所有插件里做得比较舒服的。三是把当前文件路径作为上下文自动带上。这个细节很实用省得在终端里还要手动写文件路径。如果你经常在 这个文件逻辑给我讲一下 和 帮我在这个文件里修个 bug 之间来回切换插件的便利性是终端没法比的。5.2 IDEA 插件Java/Kotlin 项目的接入JetBrains 系插件我也用过一阵。IDEA 里 opencode 插件的功能和 VSCode 版基本对齐但在 Java 项目上有个额外的好处IDEA 本身对 Maven/Gradle 项目的语义分析很完整插件能把项目模型信息传给 agent再做改动的时候对 pom.xml 或者 build.gradle 的修改会靠谱很多。热点词里有人问 opencode mvn 配置其实就是想在 IDEA 里让 agent 能读懂 Maven 项目的依赖关系。这个需要注意在 IDEA 里如果项目是 Maven 结构最好先让插件同步一下项目配置否则 agent 看到的是文件系统层面的目录而不是依赖解析后的模型。比如 agent 想加一个新依赖它可能不知道应该用哪个版本最合适因为那需要查 Maven 仓库元数据。IDEA 插件如果能把本地仓库已有的版本信息同步给它这个问题会好很多。5.3 桌面版给不想碰终端的人一条退路opencode 还有桌面版客户端界面和终端 TUI 不一样但底层是同一套引擎。对完全抗拒命令行的同事来说桌面版友好很多装好后选模型、填 API key、打开项目文件夹就能聊。桌面版还支持多窗口一个项目开一个窗口互不干扰适合同时处理多个小需求的场景。不过我的个人体验是桌面版在长会话下的稳定性不如终端版可能是还在快速迭代。如果你只是想做轻量代码问答桌面版够了如果要做大量代码修改我仍然推荐终端版各种快捷键和上下文控制更顺手。6. 踩坑记录从启动报错到 Playwright 测前端 bug6.1 unexpected server error. check server logs 的定位思路这条错误在热搜里也出现了报错形式类似opencode error: unexpected server error. check server logs.看到这个第一反应不要重装先按顺序排查。第一步确认 API key 是否有效尤其是免费额度用完的 key经常报 unexpected server error。第二步确认配置的 baseUrl 是否可达。如果你用的是第三方服务或本地代理网络不通也会包装成这个错误。第三步看 opencode 的日志。一般在~/.local/share/opencode/log/或项目.opencode/log/下里面会有真正的原因。很多时候是上游返回了 5xx而 opencode 只是把错误统一包装了。这个方法其实也适用于其他类似的通用报错。AI 编程工具为了不把技术细节糊在用户脸上经常会把上游的一堆错误合并成一句“unexpected server error”所以你要做的不是对着这句提示发呆而是想法子往上游看先去日志看请求到底有没有发出去再确认发出去之后响应是什么问题往往出在认证或网络层。6.2 this model is not available in your country 是什么情况这个报错文字很容易让人误会是网络问题其实它通常是服务商侧的模型地域限制。也就是说你账号所在的区域或你请求的 IP 所属区域不在该模型允许的服务范围内。我的建议是三件事不要在配置层面硬绕因为它不是配置错误先换一个在当前区域可用的模型比如报错的是某个地区的专用模型那就换通用模型再检查一下账号绑定的区域信息有时候是账号地区和请求地区不一致导致的。该报错不影响其他模型的正常请求所以在配置里把默认模型换成可用模型是最快的解。6.3 配置改了不生效很多人改了 config.json发现 opencode 行为没变化。常见原因有两个。一是改了项目级配置但当前工作目录不在项目根目录下agent 没读到。opencode 一般会自动检测项目根但如果你在子目录启动可能不会主动向上找。我习惯在项目根目录启动 opencode这样至少能保证项目级配置被正确读取。二是改了全局配置而项目里存在一个低优先级的配置把它覆盖了。建议先用 opencode 的配置查看命令确认实际生效值不确定就先用小实验验证。比如你改了一个模型参数就在会话里问一句“你当前用的什么模型”看看它答的是不是你想配的那个。如果答出来的不是你配的再去查覆盖关系。6.4 用 Playwright 驱动 opencode 查前端 bug这个用法我觉得很值得单独说。opencode 可以通过 MCP 或内置能力接入 Playwright也就是说你可以让 agent 自己打开浏览器、复现 bug、截图、再把控制台报错带回来分析。我实际遇到过一个前端样式错乱问题纯看代码一直找不到原因后来让 opencode 用 Playwright 打开本地开发服务器把页面关键操作录了一遍拿到截图之后它发现是某个异步组件渲染时父容器的高度计算把错位了。这个排查过程如果让我自己来至少得开 DevTools 反复看半天agent 几分钟就给了一个可验证的结论。使用上要注意给 agent 的指令要明确先复现再分析不要直接改代码。否则它很容易跳步还没复现清楚就动手改改完又无法验证。我现在的习惯是把它当成一个带眼睛的调试员先让它把复现步骤和截图贴出来我再决定要不要让它继续改。另外如果你想要 opencode 查 bug 更顺手可以在操作指令里写清楚打开 URL 后等待多少秒点击哪些元素把 console 和 network 的报错一并抓回来。这样它给回来的信息会更完整。Playwright 这块其实也是很多人的知识盲区因为大家平时只把它当测试框架用忘了它本质上是一个浏览器自动化遥控器结合 AI Agent 之后它能帮你做视觉回归、交互流程验证、异常复现潜力比单纯写测试用例大得多。最后再说一点个人体会。从 Codex CLI 到 Claude Code 再到 opencode这些工具的能力上限越来越接近真正拉开差距的其实是工作流适配你能不能把自己的规范沉淀成技能能不能让它记住项目的长期上下文能不能让它自己打开浏览器验证结果。opencode 给我的感觉是它愿意把这些能力都开放给你而不是替你做决定。如果你正在找一个能长期磨合、越用越顺手的终端编码 Agent我建议给它一周时间配好 Skills 和 Memory再对比回其他工具你会感觉到差别。
opencode 终端 AI 编程助手实测：从模型配置到 Skills、Memory 与 LSP 实战
今年代码助手的圈子是真的热闹Codex CLI 开源之后Claude Code 又火了一把社区里还冒出来一个叫 opencode 的终端 Agent。我本来是抱着试试看的心态装的结果连续用了一个多月现在每天打开终端第一件事就是敲 opencode。这篇文章就把我这段时间的使用经验完整记录下来从安装、配置、模型接入到 Skills、Memory、LSP 这些进阶功能再到 VSCode/IDEA 插件和桌面版怎么配合用最后把我踩过的坑和报错解决方案一并列出。如果你正在选型 AI 编程助手或者刚把 opencode 装好却不知道怎么配置这篇应该能帮你省下不少时间。1. 为什么是 opencode它和 Codex、Claude Code 的定位差异1.1 终端 Agent 到底在解决什么问题先说终端 Agent 这类工具的定位。它跟你在 IDE 里装个 Copilot 完全不一样Copilot 是你写一半它帮你补全而终端 Agent 是你把任务交给它它自己读代码、改代码、跑命令、看报错然后给你交付结果。opencode 的交互基本都在终端里启动后是一个交互式 TUI 界面左边是会话历史右边是当前任务的对话流你能看到它每一步在干什么——读了哪个文件、执行了什么命令、改了什么内容。这种形态最大的好处是你不用把上下文来回复制粘贴。它可以直接访问项目目录自己定位相关文件自己跑测试来验证修改是否正确。说白了它把写代码这件事从补全键变成了提需求 验收。一开始我也觉得这玩意儿是不是噱头但真正跑了一个重构任务之后我意识到终端 Agent 的价值不在于自动补全得有多准而在于它能替你完成读代码—理解—动手改—验证这个完整闭环。1.2 和 Codex、Claude Code 的核心差异当时我手上同时装了 OpenAI Codex CLI 和 Claude Code对比着用了几天最后长期留下来的是 opencode原因很具体维度opencodeCodex CLIClaude Code模型绑定程度多模型可切换主要围绕 OpenAI 系列围绕 Claude 系列Skills 自定义有用 Markdown/脚本定义有但生态成熟度一般支持插件Memory 跨会话支持有限依赖项目内约定LSP 接入支持近期加入支持编辑器插件VSCode/IDEA 都有依赖外部官方 IDE 扩展配置复杂度中高灵活低中后面几节会具体展开。这里我想强调一个观点选哪个工具本质上不是比谁更聪明而是比谁更适合你的工作流。Codex 的优势是跟 OpenAI 生态无缝Claude Code 的优势是 Anthropic 模型本身的编码能力而 opencode 的优势则是我不绑定你的模型你想接哪家接哪家想做技能就做技能想记长期记忆就记。我用 opencode 接 Anthropic 的模型时基本能获得和 Claude Code 接近的编码体验但同时又能在同一个工具里切到 OpenAI、本地 Ollama甚至一些聚合网关提供的模型。这种灵活性对我这种哪个模型好用就用哪个的人来说比单一厂商深度绑定更舒服。1.3 适合什么人用按我自己的体会这几类人最适合用 opencode一是手里有多家模型 API比如 OpenAI、Anthropic、Google或者本地模型的人因为可以在一个会话里动态切模型二是团队里希望把代码规范、提交流程这类东西沉淀成 Skills 的人三是喜欢终端工作流、不想被 IDE 绑住的开发者。反过来如果你完全不想读配置、不想折腾只想要一个开箱即用的助手那 opencode 的默认配置会让你有点懵因为它默认不绑定任何厂商模型你得先配一个 provider。换句话说opencode 给你的是全套工具但调校这件事它也交给了你。用好了它是利器用不好你就只会觉得怎么配了这么久还不能跑。2. 安装 opencode 的几种方式以及 cmdlet 报错的根源2.1 安装方式与版本选择安装这事看起来简单其实有坑。opencode 的版本迭代非常快不同版本对 Node 版本的要求也不一样我建议优先看官方仓库 README 里最新的安装命令但一般来说有这么几种方式npm 全局安装npm install -g opencode某些版本包名是 opencode-ai以 README 为准Homebrew 安装brew install opencodemacOS 上比较省事直接下载二进制从 GitHub Releases 下载对应平台的可执行文件解压后加入 PATH我的习惯是用 npm 装因为后面升级方便npm update -g opencode一条命令搞定。用二进制的话升级就得重新下载替换稍微麻烦一点。但 Windows 上如果 Node 环境本身比较乱直接下二进制可能更省心至少不会出现npm 全局目录到底在哪这种问题。另外提醒一句opencode 的 2.0 版本和早期版本在配置结构上有不少变化。网上很多教程截图还是老版本界面所以你在搜资料的时候最好确认对方用的版本和你一致否则照着抄可能配不出来。2.2 Windows 下 无法将 opencode 项识别为 cmdlet 的排查这是搜索热词里出现频率很高的问题我自己也遇到过。现象是在 PowerShell 里执行 opencode报opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的根源90% 是命令文件存在但终端找不到。拆开来说就两层原因。第一层npm 全局安装的 bin 目录没有加到系统 PATH 里。很多人以为npm install -g之后命令就全局可用了实际上 npm 会把可执行文件放进类似%APPDATA%\npm的目录这个目录必须在 PATH 里PowerShell 才会去搜。检查方式是在 PowerShell 里执行npm config get prefix拿到全局目录再确认这个目录在 PATH 环境变量中。第二层安装完成之后没有重开终端。PATH 环境变量在终端启动时就读取了安装完命令后你需要新开一个终端窗口或者执行下面这行命令手动刷新当前会话$env:Path [System.Environment]::GetEnvironmentVariable(Path,Machine) ; [System.Environment]::GetEnvironmentVariable(Path,User)如果这两步都做了还报错再用npx opencode --version验证一下包本身有没有装好。能输出版本号说明只是 PATH 问题如果 npx 也报错那就是安装本身失败了需要检查 Node 版本和 npm 日志。2.3 安装后第一件事认证opencode 不像 Codex 那样默认绑定登录账户它需要你主动配置认证信息。不同模型商的认证方式不同一般有两种通过opencode auth login交互式登录适用于 OpenAI、Anthropic 这类支持 OAuth 的厂商。在配置文件中直接写 apiKey或者设置环境变量适用于大多数第三方 API。我第一次用的时候直接跳过了认证步骤结果启动后每个模型请求都报 401还以为是软件坏了。所以装好之后先花一分钟把认证搞定再开始玩其他功能。这里也顺便回答热搜里opencode 是哪家公司的这个疑问它不是一个商业大厂的产品更多是开源社区驱动所以在使用方式和文档上都有点极客气质别指望它有商业软件那种新手引导。3. 一份能跑通的配置模型接入与免费模型的取舍3.1 配置文件放哪opencode 的配置约定类似很多现代 CLI全局配置放在用户目录的~/.config/opencode/下项目级配置放在项目根目录的.opencode/下项目配置会覆盖全局配置。这个设计非常实用尤其当你同时在几个项目里用不同模型组合的时候。我在公司接了一个老项目用的是 Java Maven另一个个人项目是 TypeScript pnpm。如果只靠一个全局配置每次切换项目都要改半天。有了项目级配置我可以在各自的.opencode/目录里放不同的模型偏好和 LSP 设置互不干扰。3.2 config.json 的基础结构我当前项目的配置结构大致是这样的具体字段名会随版本变化以你实际版本为准{ provider: { openai: { apiKey: {env:OPENAI_API_KEY}, model: gpt-4.1 }, anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4 }, ollama: { baseUrl: http://localhost:11434, model: qwen3-coder } }, default: anthropic, lsp: { enabled: true }, memory: { enabled: true } }先别急着照抄因为 opencode 的配置字段经常调整我见过好几个版本用 provider、model、lsp、memory 这些键但也见过用 models 数组的写法。所以最稳妥的路径是装好之后先跑一次opencode让它生成默认配置文件再基于默认配置去改而不是从网上复制一个可能已经过时的配置。这样你至少能知道当前版本认识哪些字段改起来心里有底。3.3 免费模型能用但别期待太高热搜里有很多人问 opencode 免费模型说明大家确实希望零成本跑起来。目前社区里提到的免费渠道大致有三类一是部分云厂商提供的免费额度 API二是本机跑的 Ollama 开源模型三是某些平台送的试用积分。我的实际感受是免费额度类适合写脚本、改小 bug、回答技术问题但通常有每分钟请求数限制跑长任务时容易断。本地模型类完全免费且没有频率限制但编码能力跟商用模型有明显差距尤其是大仓库重构这种任务经常改着改着就丢了上下文。试用积分类适合短时间体验不适合作为日常主力。我自己现在的方案是日常主力用付费 API本地 Ollama 作为备用免费额度只用来做一次性咨询。如果你真的想完全免费跑 opencode我建议接受它只适合做辅助编程不能全托管这个现实否则体验落差会很大。3.4 模型切换的日常姿势opencode 的 TUI 里一般支持会话中切换模型快捷键通常是CtrlM或者/models命令不用重新启动。这个功能对我来说很重要因为让 agent 读代码、梳理逻辑用便宜模型就行改一段复杂算法再切到更强的模型能省不少 token 费用。打个比方这就像你不可能天天开着货车去上班但在搬家那天你肯定会租一辆。opencode 把选什么车这件事完全交给你而不是规定你每天都只能开同一辆。对我来说这是它最值钱的地方。4. Skills、Memory、LSPopencode 最值得花的三个进阶功能4.1 Skills把团队规范变成可复用技能Skills 是 opencode 里我很喜欢的一个设计。简单说你可以把一些固定的操作流程、代码规范、提示词模板做成一个技能包让 agent 在对应场景自动或按需调用。比如我在团队里遇到最多的场景是提交代码前要跑 lint 和单测并且遵循 commit message 规范。以前在 Claude Code 里我会在会话里反复粘贴这段要求而 opencode 里我可以写一个 skill在.opencode/skills/precommit/下建一个SKILL.md里面写清楚触发条件和使用步骤当用户提到提交或准备 PR的时候先执行pnpm lint再执行pnpm test最后按 Conventional Commits 格式生成提交信息。实际用下来这个 skill 的稳定性比我手动粘贴提示词高很多因为 agent 会在相关节点主动去读这个文件而不是只靠一次上下文的记忆。写 skill 有几个小技巧触发词要写明确模糊的触发条件会让 agent 有时候用有时候不用。步骤尽量编号避免让它自由发挥。每个 skill 只聚焦一个目标别把一堆规则塞进一个文件。我见过有人把公司代码风格和部署流程写在同一个 skill 里结果 agent 在改代码时跑去执行部署命令差点酿成事故。所以技能一定要单一职责宁可多建几个目录也别贪心。4.2 Memory跨会话的长期记忆Memory 解决的是昨天聊过的东西今天不要再解释一遍。opencode 的 memory 会把一些长期信息持久化下次会话自动加载。比如你可以告诉它这个项目的测试框架是 Vitest不要用 Jest它会记下来下次会话再让它加测试时它就不会默认生成 Jest 的测试。用法上我喜欢在会话开始时直接说记住...也可以主动查看/编辑 memory 文件。不过要提醒一点memory 默认是项目级的还是全局级的不同版本设计不同如果你发现记忆串项目了检查一下配置。我有一次在 A 项目里让它记住了不要动 public 目录结果切到 B 项目它也在守这条规则搞得我排查了半天。4.3 LSP让 Agent 从猜代码变成读代码LSPLanguage Server Protocol语言服务协议本来是给编辑器用的opencode 把它接进来之后agent 就能像 IDE 一样获取更准确的代码语义。具体体现为跳转定义、查找引用、获取类型信息。以前 agent 改代码经常靠正则和文本扫描改了 A 文件忘了 B 文件的引用接了 LSP 之后它能拿到真实的符号关系修改前会先找到所有引用它的地方漏改的情况少了很多。配置上主要是确认 config.json 里lsp.enabled为 true。不过有一点要注意LSP 需要项目里装好对应的语言服务比如 TypeScript 项目要有 node_modules 里的 typescriptJava 项目要有对应的 LSP 配置否则开了也白开。我见过有人开了 lsp.enabled 之后抱怨怎么没效果一看项目里连语言服务都没装那当然不起作用。5. 从终端到编辑器VSCode / IDEA 插件和桌面版的实际体验5.1 VSCode 插件终端的 Agent 进到编辑器虽然 opencode 的主力场景是终端但写代码这件事最终还是落在编辑器里所以 VSCode 插件很有价值。我在 VSCode 里装好 opencode 插件后主要用三个功能。一是选中代码后让 agent 解释或重构。在编辑器里选中一段复杂逻辑右键发送给 opencode它能结合整个项目的上下文来分析而不是只看选中片段。这个能力比单独把代码贴给 ChatGPT 要强很多因为 agent 能自己去找相关的接口定义和调用方。二是修改建议以 diff 形式呈现。和终端里的无差别输出相比编辑器里的 diff 预览我可以直接逐个 hunk 接受或拒绝不会出现改了一大堆不是我要的的失控感。这个交互方式我觉得是所有插件里做得比较舒服的。三是把当前文件路径作为上下文自动带上。这个细节很实用省得在终端里还要手动写文件路径。如果你经常在 这个文件逻辑给我讲一下 和 帮我在这个文件里修个 bug 之间来回切换插件的便利性是终端没法比的。5.2 IDEA 插件Java/Kotlin 项目的接入JetBrains 系插件我也用过一阵。IDEA 里 opencode 插件的功能和 VSCode 版基本对齐但在 Java 项目上有个额外的好处IDEA 本身对 Maven/Gradle 项目的语义分析很完整插件能把项目模型信息传给 agent再做改动的时候对 pom.xml 或者 build.gradle 的修改会靠谱很多。热点词里有人问 opencode mvn 配置其实就是想在 IDEA 里让 agent 能读懂 Maven 项目的依赖关系。这个需要注意在 IDEA 里如果项目是 Maven 结构最好先让插件同步一下项目配置否则 agent 看到的是文件系统层面的目录而不是依赖解析后的模型。比如 agent 想加一个新依赖它可能不知道应该用哪个版本最合适因为那需要查 Maven 仓库元数据。IDEA 插件如果能把本地仓库已有的版本信息同步给它这个问题会好很多。5.3 桌面版给不想碰终端的人一条退路opencode 还有桌面版客户端界面和终端 TUI 不一样但底层是同一套引擎。对完全抗拒命令行的同事来说桌面版友好很多装好后选模型、填 API key、打开项目文件夹就能聊。桌面版还支持多窗口一个项目开一个窗口互不干扰适合同时处理多个小需求的场景。不过我的个人体验是桌面版在长会话下的稳定性不如终端版可能是还在快速迭代。如果你只是想做轻量代码问答桌面版够了如果要做大量代码修改我仍然推荐终端版各种快捷键和上下文控制更顺手。6. 踩坑记录从启动报错到 Playwright 测前端 bug6.1 unexpected server error. check server logs 的定位思路这条错误在热搜里也出现了报错形式类似opencode error: unexpected server error. check server logs.看到这个第一反应不要重装先按顺序排查。第一步确认 API key 是否有效尤其是免费额度用完的 key经常报 unexpected server error。第二步确认配置的 baseUrl 是否可达。如果你用的是第三方服务或本地代理网络不通也会包装成这个错误。第三步看 opencode 的日志。一般在~/.local/share/opencode/log/或项目.opencode/log/下里面会有真正的原因。很多时候是上游返回了 5xx而 opencode 只是把错误统一包装了。这个方法其实也适用于其他类似的通用报错。AI 编程工具为了不把技术细节糊在用户脸上经常会把上游的一堆错误合并成一句“unexpected server error”所以你要做的不是对着这句提示发呆而是想法子往上游看先去日志看请求到底有没有发出去再确认发出去之后响应是什么问题往往出在认证或网络层。6.2 this model is not available in your country 是什么情况这个报错文字很容易让人误会是网络问题其实它通常是服务商侧的模型地域限制。也就是说你账号所在的区域或你请求的 IP 所属区域不在该模型允许的服务范围内。我的建议是三件事不要在配置层面硬绕因为它不是配置错误先换一个在当前区域可用的模型比如报错的是某个地区的专用模型那就换通用模型再检查一下账号绑定的区域信息有时候是账号地区和请求地区不一致导致的。该报错不影响其他模型的正常请求所以在配置里把默认模型换成可用模型是最快的解。6.3 配置改了不生效很多人改了 config.json发现 opencode 行为没变化。常见原因有两个。一是改了项目级配置但当前工作目录不在项目根目录下agent 没读到。opencode 一般会自动检测项目根但如果你在子目录启动可能不会主动向上找。我习惯在项目根目录启动 opencode这样至少能保证项目级配置被正确读取。二是改了全局配置而项目里存在一个低优先级的配置把它覆盖了。建议先用 opencode 的配置查看命令确认实际生效值不确定就先用小实验验证。比如你改了一个模型参数就在会话里问一句“你当前用的什么模型”看看它答的是不是你想配的那个。如果答出来的不是你配的再去查覆盖关系。6.4 用 Playwright 驱动 opencode 查前端 bug这个用法我觉得很值得单独说。opencode 可以通过 MCP 或内置能力接入 Playwright也就是说你可以让 agent 自己打开浏览器、复现 bug、截图、再把控制台报错带回来分析。我实际遇到过一个前端样式错乱问题纯看代码一直找不到原因后来让 opencode 用 Playwright 打开本地开发服务器把页面关键操作录了一遍拿到截图之后它发现是某个异步组件渲染时父容器的高度计算把错位了。这个排查过程如果让我自己来至少得开 DevTools 反复看半天agent 几分钟就给了一个可验证的结论。使用上要注意给 agent 的指令要明确先复现再分析不要直接改代码。否则它很容易跳步还没复现清楚就动手改改完又无法验证。我现在的习惯是把它当成一个带眼睛的调试员先让它把复现步骤和截图贴出来我再决定要不要让它继续改。另外如果你想要 opencode 查 bug 更顺手可以在操作指令里写清楚打开 URL 后等待多少秒点击哪些元素把 console 和 network 的报错一并抓回来。这样它给回来的信息会更完整。Playwright 这块其实也是很多人的知识盲区因为大家平时只把它当测试框架用忘了它本质上是一个浏览器自动化遥控器结合 AI Agent 之后它能帮你做视觉回归、交互流程验证、异常复现潜力比单纯写测试用例大得多。最后再说一点个人体会。从 Codex CLI 到 Claude Code 再到 opencode这些工具的能力上限越来越接近真正拉开差距的其实是工作流适配你能不能把自己的规范沉淀成技能能不能让它记住项目的长期上下文能不能让它自己打开浏览器验证结果。opencode 给我的感觉是它愿意把这些能力都开放给你而不是替你做决定。如果你正在找一个能长期磨合、越用越顺手的终端编码 Agent我建议给它一周时间配好 Skills 和 Memory再对比回其他工具你会感觉到差别。
