前阵子接手一个别人写到一半的Java后端代码能跑但没人说得清订单模块和支付的调用链是怎么串起来的。我在IDE里装了一排AI插件补全和单文件解释没问题真要跨文件重构、顺藤摸瓜改十几处调用点它们瞬间变成复读机。后来我把opencode装回终端里让它自己读日志、跑测试、改代码两条命令下去它自己把问题链路查明白了。这篇文章就讲讲我这一两个月用opencode的实际经验从安装到配置从skills到Playwright踩过的坑和最后沉淀下来的用法一次性写清楚。1. 先搞清楚opencode是什么一个比IDE插件更完整的编程Agentopencode是sst团队开源的一个终端AI Agent用Go语言写的所以很多教程会写成opencode go或go install opencode。很多人第一次听到它是在对比Codex CLI、Claude Code、opencode到底哪个Agent好用的时候。它的定位不是自动补全不是聊天机器人而是能自己打开文件、改代码、执行命令、看运行结果、再继续改的自主代理。简单说你扔给它一个任务它会在项目里自己调研、动手、验证然后把结论告诉你。2.0版本之后opencode热度上来得很快界面改成了类似IDE的上下结构任务能并行挂后台跑完还能继续追问。它底层起了一个本地服务来处理Agent的推理循环CLI只负责交互这也是为什么后面会有unexpected server error这种报错——你看到的界面只是一层皮真正的脑子在那个server进程里。1.1 它和Claude Code、Codex的本质差异这三类工具都在抢终端Agent这个位置但侧重点完全不同。我用了一段时间做了个对比维度Claude CodeopencodeCodex CLI模型绑定偏向Anthropic系列几乎任何OpenAI兼容接口可接Ollama官方偏OpenAI系列配置开放度中主配置以命令为主高opencode.json可自定义provider/models中config.toml可设但生态较少技能生态AGENTS.md skills生态成熟可复用社区skills支持MCP/AGENTS官方提供AGENTS.md能力适合场景想用Claude模型、要开箱即用想自由切换模型、需要长期沉淀环境配置深度绑定OpenAI模型你可能注意到opencode的配置开放度是三类里最高的。这意味着什么意味着同一个工具今天可以接Claude明天可以接GPT后天团队搭了一个私有模型网关改个baseURL就能接进去。对于长期维护多个项目、经常换模型的人来说这个优势非常致命。1.2 为什么终端Agent反而更适合接手老项目老项目最大的痛点是上下文散落在几十个文件里IDE插件的索引再强也不可能替你完成先跑测试、看失败堆栈、打开对应文件、修改、再跑测试这个循环。终端Agent天然能做到这件事因为它在终端里可以直接执行命令能看到真实运行结果而不是靠猜。我当时处理那个订单模块就是这样做的我没有让opencode直接改代码而是给它一个任务——你先跑mvn test -DtestOrderServiceImplTest把失败原因写到work.md里再给出修复方案。它真的先跑了测试然后沿着堆栈找到了一个空指针异常追到一个feign调用的返回值为null又翻了三个配置类最后才动手改。整个过程像是一个带电脑的实习生在干活而不是一个只会聊天的问答机器人。所以如果你是那种每天要维护别人留下的代码、经常被各种历史包袱折磨的开发者opencode这类工具可能是比IDE插件更值得花时间研究的对象。2. 安装与启动从go install到两个高频报错的完整排查安装opencode本身不难难的是装完之后看起来没装上和启动了又崩了这两件事。我在Windows和macOS上都装过先把你最可能遇到的两个坑讲透。2.1 各平台安装方式以及Windows下cmdlet报错的三种原因最常规的安装方式有三种macOS/Linuxbrew install sst/tap/opencode或者用官方脚本curl -fsSL https://opencode.ai/install | bashGo用户go install github.com/sst/opencodelatestWindows建议用winget install或scoop install opencode也可以直接去GitHub Releases下载exe放到一个固定目录如果你在Windows上执行opencode结果看到这句opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称先不要慌这基本上不是opencode本身的问题而是装了但系统找不到它。最常见的三种情况你用go install安装但GOPATH/bin目录不在当前PowerShell的PATH里。opencode.exe其实已经装好了只是终端不知道去哪找它。解决方法是执行go env GOPATH然后把这个路径下的bin加入PATH。你手动下载了exe放在Downloads目录没有把它移到一个固定目录也没有加入PATH。推荐做法是放到C:\Users\你的用户名\bin或C:\tools\opencode然后把这个目录加入PATH。安装成功但当前终端会话没有刷新PATH。关掉PowerShell重新开一个或者用refreshenv需要Chocolatey环境。排查起来很简单先执行Get-Command opencode如果报错说明确实不在PATH里如果返回路径说明已经找到了。然后手动执行opencode --version看能否跑通。2.2 启动时报unexpected server error的排查链路这个报错是很多新用户最容易崩溃的地方opencode打开后界面还没进去直接提示opencode error: unexpected server error. check server log我自己的经验是90%的server error不是网络问题而是本地配置问题。opencode的CLI和本地server是分离的server负责加载配置、连接模型、跑Agent循环CLI只是一个前端。一旦opencode.json里的provider配错、环境变量缺失、或者上次的server进程残留就会出现这种看起来像网络挂了的报错。排查顺序建议如下先找日志。macOS/Linux下一般在~/.local/share/opencode/logWindows下在%LOCALAPPDATA%\opencode\log。打开最新日志文件看server启动时停在哪一行。查看是否有残留进程占用端口。如果你热更新配置后反复重启opencode旧进程可能没退干净新进程起不来。macOS/Linux用lsof -i :portWindows用netstat -ano | findstr。检查opencode.json。最常见的问题是baseURL写错、model名不存在、apiKey没有设置。比如模型写成了ollama/qwen2.5-coder但本地Ollama根本没装server自然起不来。看环境变量。opencode在起server时会读取ANTHROPIC_API_KEY、OPENAI_API_KEY这类变量如果完全没有设置服务端初始化provider时就会失败。有一个快速定位技巧把opencode.json临时改名让opencode用默认配置启动。如果能正常进入界面那基本可以断定是你自己的配置有问题再逐字段检查如果还是报同样的错再回头怀疑端口和残留进程。3. 模型接入与配置opencode.json、免费模型与常见联动工具很多教程会直接给你一段opencode.json让你复制粘贴但很少有人讲清楚这个文件背后的逻辑。其实理解了配置逻辑你就不需要背任何模板随时能自己拼出想要的配置。3.1 opencode.json的配置逻辑opencode的核心配置就是一个JSON文件放在项目根目录或用户主目录下。结构上主要分三块默认模型、provider定义、模型列表。举个例子假设我想用本地Ollama跑一个Qwen2.5 Coder配置大概长这样{ $schema: https://opencode.ai/config.json, model: ollama/qwen2.5-coder:14b, provider: { ollama: { npm: ai-sdk/ollama, name: ollama, options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:14b: { name: Qwen 2.5 Coder 14b } } } } }这里的model字段决定默认使用哪个模型格式是providerName/modelName。provider字段里可以注册多个provider每个provider可以有不同的SDK和baseURL。如果你用的是OpenAI兼容接口一般不需要写npm只需要在options里配置baseURL然后设置环境变量OPENAI_API_KEY。这个设计最大的好处是切换成本低今天公司网关用的是OpenAI兼容协议明天换成Anthropic接口你不需要重装工具只需要改配置。这也是为什么很多人会在一个opencode里同时配Claude、GPT、Ollama三个provider按项目需求切换。3.2 免费模型怎么接本地Ollama与在线兼容接口opencode免费模型是搜索量非常高的关键词我实际用下来免费模型分两条路线一条是本地模型。最常用的方式就是用Ollama跑Qwen2.5 Coder、DeepSeek Coder V2这类开源模型。安装Ollama后先执行ollama pull qwen2.5-coder:7b把模型拉到本地再像上面那样在opencode.json里配置。本地模型的优势是零API费用、数据不出本机劣势是速度和质量受显卡影响。如果机器只有16G内存跑7B模型做简单任务还行做复杂重构会明显力不从心。另一条是在线免费模型或试用额度。不少模型平台提供免费key或者OpenAI兼容的baseURL配置方式非常直接在provider里指定baseURL在环境变量里设置API Key。需要注意两点一是大部分免费额度有速率限制不要开太多并行任务二是不要随便用网上的来路不明的key有安全风险。配置时不确定参数的优先看官方文档别看二手教程。我的建议是如果只是写测试、解释代码、做小范围重构免费模型完全够用但真正要处理跨模块改造、依赖升级、复杂bug定位还是把更强的模型切出来省下的时间比省token划算得多。3.3 配合ccswitch和mvn配置的使用细节opencode go经常和ccswitch一起出现。ccswitch是一个管理多套模型配置的工具它的核心价值是如果你手里有多套API配置不想每次都手动改opencode.json可以用ccswitch维护一个配置列表切换时一条命令搞定然后重启opencode就能生效。实际用下来它的逻辑有点像环境变量开关适合经常要切不同模型服务的人。如果你平时只用一个providerccswitch的收益不大可以跳过。再单独说说mvn配置。很多人会在Java项目里用opencodeAgent要跑mvn test或mvn compile。这时候最常遇到的问题是终端报mvn: command not found更隐蔽的是Windows下执行夹带有mvn的命令时报错但你在IDE里手动跑却是好的。原因多半是mvn不在PATH里。解决方法是给系统配置MAVEN_HOME并把%MAVEN_HOME%\bin加入PATH然后重启终端。还有一个Java项目特有的坑如果你的项目用了公司私服或自定义镜像opencode用mvn拉依赖时可能因为没走镜像而超时它会把依赖下载失败误判成代码问题然后开始改代码越改越乱。所以我建议在Java项目里用opencode之前先确认mvn -v和mvn help:effective-settings能正常输出把环境问题消灭在Agent工作之前。4. 让Agent从能聊到能干Skills、Memory、Superpowers与Playwright配置好模型只是第一步。真正让opencode和其他Agent拉开差距的是它这套扩展能力的机制。你可以把默认状态下的Agent理解成一个聪明但没经验的实习生skills、memory这些就是你在它入职时给的培训手册。4.1 Skills把团队规范变成Agent的条件反射Skills的本质是按触发词加载的指令包。你在项目里放一个.opencode/skills目录里面按技能名建子目录每个子目录里放一个SKILL.md描述技能再放一些辅助文档或prompt。当你在对话里提到对应的技能名时opencode会自动加载这个目录里的内容按里面定义的流程执行。一个简单示例.opencode/ skills/ code-review/ SKILL.mdSKILL.md里面可以写# Code Review 当用户要求执行 code review 时请按以下流程 1. 先列出自上次提交以来变更的文件 2. 检查每个文件的安全风险、性能风险和可读性 3. 用中文输出问题列表按严重程度排序这样做的好处是团队里积累的代码规范、测试流程、常见注意事项都能沉淀成一个个skill每个新会话的Agent都能复用。我自己用过最舒服的是添加新接口skill里面写了DTO校验规则、异常处理方式、接口文档更新位置Agent产出的代码明显更贴近团队风格。4.2 Memory跨会话记住项目约定如果说skills是按需触发memory就是每次启动自动注入。opencode支持在项目根目录放AGENTS.md或者配置memory文件里面写清楚项目的模块结构、代码风格、测试命令、常见雷区。每次会话启动Agent会自动读取这些内容相当于给每个新会话配了一个项目老兵在旁边口述背景。我踩过最值的坑就是初次带一个不熟悉的项目时把generated目录下的代码不要改新增接口必须加DTO校验前端构建用npm run build:app这些约定写进AGENTS.md。后来再让Agent改任何东西它的第一版产出明显更符合项目习惯不用反复纠正不是改这里是改那里。4.3 Superpowers和oh-my-claudecode技能包生态怎么用社区里很火的superpowers是一套强调plan-then-execute先计划后执行的技能集合核心思想是让Agent接到任务后先写实现方案经过确认再动手而不是上来就改文件。对于大改动这个模式能减少很多误操作。oh-my-claudecode原本是针对Claude Code的一套AGENTS规范和skills集合里面收集了大量实用的工作流。opencode社区有人把这套结构迁移过来因为两者的skills机制很相似。实际使用中你可以直接把一些通用skill放到opencode的skills目录里但有几个前提先读一遍SKILL.md确认它要执行的命令你都能接受。技能包本质上是Agent的指挥手册里面的命令最终是Agent自己去跑的如果夹带危险操作后果需要你自己兜底。我一般只装star高、更新频繁、内容看得懂的项目。4.4 Playwright让Agent自己开着浏览器测前端Bug前面说的都是后端改动前端同样有对应的扩展玩法。opencode可以配合Playwright做真实的浏览器测试。做法是给Agent一个任务让它用Playwright打开指定页面、执行点击和输入、收集报错和截图。当年让我决定引入这个方案的是一个小bug登录按钮在某些屏幕尺寸下被遮住页面上没有任何报错纯靠代码审查根本看不出来。我给opencode装了一个前端验证skill里面写了固定的流程启动dev server、用Playwright打开页面、切换几种viewport、点击登录按钮、截图并抓取console错误。从那以后每次改完前端布局我都会让Agent自己跑一遍这个流程效率比手动点高太多。实际接入不算复杂前提是项目里装了Playwright并且Agent知道要调用npx playwright。如果项目还没有初始化先npm init playwright然后写一条包含启动命令和URL的任务描述就行。5. 在编辑器里用opencodeVSCode插件、JetBrains IDEA插件与桌面版的实际取舍用惯了终端的人会觉得CLI已经够用但确实有一部分开发者更希望在编辑器内部完成一切。opencode的插件生态也在补这一块。5.1 官方插件和IDE联动的实际体验VSCode插件和JetBrains IDEA插件做的事情基本一致在编辑器侧边栏或面板里嵌一个opencode界面能直接把光标选中的代码传给AgentAgent改完代码后在集成终端里执行命令测试结果也能直接看到。对日常开发来说这两个插件最大的价值不是替代CLI而是减少窗口切换。但我的实际体验是插件面板里的Agent交互逻辑和终端里是一样的只是换个壳。真正适合用插件的场景是你正在IDE里读代码忽然想让Agent解释某个函数的调用链、或生成一段测试代码这时选中代码直接丢给它比切终端再粘贴方便得多。如果是要跑完整的调研-修改-验证循环我还是习惯切回独立终端因为看日志和命令输出更清晰。一个使用建议在IDE里用Agent生成的改动一定要回到Git diff面板里审一遍再提交。无论用哪个编辑器集成Agent代码都不应该直接进主干这是底线。5.2 桌面版与CLI怎么选opencode Desktop是图形化封装适合刚接触的人因为它把会话列表、配置入口、日志查看都做成了可视界面不用记命令行。多任务管理也更直观几个任务并行跑的时候桌面版能看到每个任务的实时状态。但对我来说CLI仍然是主力。原因很直接CLI更新最快新功能通常在CLI里先出桌面版往往要滞后一两个版本。另外桌面版本质上是Electron/WebView类应用内存占用比终端高不少如果你平时已经开着IDE再加一堆服务端进程再开一个桌面版可能会让机器变卡。我的用法是日常重活用CLI需要翻阅历史会话、对比多个任务结果的时候开桌面版。6. 用了大半个月之后我最后想说的几点关于opencode网上教程和讨论很多但真正上手之后有几个心得是教程里不会写太细的。第一新手上路不要急着装一堆skills和插件。先拿默认配置跑通一个最最简单的小任务比如让我读一下这个项目的README然后用中文总结这个项目是干嘛的。确认opencode能正常读取文件、回复内容正常再逐步加模型、加skills。否则配置和环境问题混在一起出了问题你根本不知道是哪一环炸的。第二任务描述越具体产出越可控。帮我修一下这个bug和先用测试复现bug再定位根因最后给出修复diff是完全不同的效果。给Agent写任务时最好包含验收标准比如改完后mvn test要全部通过“不要改动公共接口签名”。这就像给外包发需求写得越细返工越少。第三有破坏性的操作一定要开确认或审阅。opencode支持在执行命令和修改文件前暂停让你确认后再继续。在大批量替换文件、删除废弃代码、修改数据库脚本这类场景下这个确认步骤是保命用的。我吃过一次亏让Agent清理无用import它顺手删了一个测试类里的静态方法要不是有diff review那次就直接把测试弄挂了。第四版本更新快不一定是坏事但升级后行为变化要先看changelog。opencode的迭代速度相当快2.0版本前后界面和配置方式都有调整网上很多教程可能已经过时。遇到之前明明能跑现在突然报错的情况先去看release note大概率是breaking change而不是你配置坏了。最后如果一个项目你打算长期维护强烈建议在项目里维护一份AGENTS.md把构建命令、测试命令、目录约定、常见坑都写进去。这个东西不仅对opencode有用对未来的同事、对半年后的你自己都是极大的帮助。opencode这类工具的价值不只是帮你写代码它逼着你把项目里的隐性知识显性化这份沉淀才是比工具本身更值钱的东西。