如果你最近刷技术社区,应该会频繁看到一个词:opencode。作为一款开源的AI编程代理(AI coding agent),它和Claude Code、Codex一起,几乎成了Agent式编程工具里讨论度最高的三个名字。一句话解释它的价值:opencode能跑在终端里,自己读项目代码、理解业务逻辑、改文件、执行命令、跑测试,最后把改动结果以diff的形式交给你审查,而不是像传统IDE插件那样只负责补全代码。这篇内容我不打算复述官方文档,而是把这段时间实际使用opencode的经验、踩过的坑、配置多模型的方法、IDE插件的用法,以及从skills到memory的扩展玩法全部梳理一遍,给出一份可以直接照着用的实践指南。
1. 先弄清楚:opencode到底是干嘛的
1.1 它不是一个普通的代码补全插件
很多人第一次听说opencode,都会误以为它和GitHub Copilot一样,是个“帮你补全代码”的编辑器插件。实际上完全不是一回事。opencode是一个跑在终端里的AI编程代理,它不止会补全代码,而是会自己读项目目录、理解业务逻辑、设计改动方案,然后一次性修改多个文件并执行命令、跑测试,最后把结果汇报给你。换句话说,Copilot是“你打字它补全”,opencode是“你下指令它干活”。
为了让你更好理解,可以把它想象成一个刚入职但学习能力极强的实习生:你告诉它“把用户列表接口加上分页”,它会自己去翻Controller、Service、Mapper,找到入口和数据结构,改完代码再帮你跑一下编译或者测试,遇到报错还会自己定位修复。整个过程你只需要在旁边看diff、决定接受还是拒绝。这种工作方式,和传统IDE插件的体验是完全不同的。
它出现的大背景,是近两年以Claude Code、Codex为代表的一批“Agent式”编程工具开始流行。这类工具不再把模型当成一个聊天窗口,而是把模型放进一个能执行命令、读写文件的沙箱里,赋予它调用终端工具的权限。opencode就是这条路线里最值得关注的开源选手之一,由做Serverless开发框架的sst团队发起,代码完全公开,社区迭代非常快。
1.2 opencode、Claude Code、Codex,三选一到底该选谁
我刚接触opencode的时候,最大的困惑就是它和Claude Code、Codex到底有什么区别。这三个都是“Agent式编程工具”,但定位和使用场景有明显差异。我做了一张对比表,看完基本就能确定自己该用哪个:
| 维度 | opencode | Claude Code | Codex |
|---|---|---|---|
| 开源情况 | 完全开源 | 核心闭源,文档开放 | OpenAI官方,核心闭源 |
| 模型依赖 | 自由接入多模型 | 依赖Claude系列模型 | 依赖OpenAI模型 |
| 上手成本 | 需要自己配模型Key | 开箱即用,需Claude订阅或API | 需要OpenAI账号/API |
| IDE集成 | VSCode、JetBrains插件 | 官方CLI,社区也有插件 | 编辑器集成较好 |
| 扩展能力 | skills、MCP、自定义provider | skills、subagents、MCP成熟 | plugins、MCP |
| 主要优势 | 开源、模型自由、可定制 | 对复杂长任务的推理能力强 | 与ChatGPT生态绑定紧密 |
从表格能看出来,如果你的主要诉求是“不想被某一家模型厂商绑定”,那opencode就是最合适的选择。我自己日常其实会在三个工具之间切换:追求复杂业务重构效果时用Claude Code,和OpenAI生态走得近的项目用Codex,而凡是需要开源可控、或者想省点模型费用的场景,我都会落到opencode上。这不是一个“谁取代谁”的问题,更像工具箱里多了一把好用的螺丝刀。
1.3 为什么我最终把opencode留在了日常武器库里
坦白说,opencode的上手难度比Claude Code要高一点,因为它把很多选择权交到了你自己手里——用什么模型、怎么配置Provider、走什么样的工作流,都要自己决定。但也正因为如此,它成为了我日常使用频率最高的编程Agent。
最打动我的点有三个。第一是完全开源,这意味着我能看清楚它到底做了什么、哪些地方可以改,公司里做技术选型也更容易过合规这一关。第二是多模型自由切换,同一个项目我可以根据任务难度选择“便宜大碗”的模型处理机械化改动,碰到真正复杂的问题再切换到推理能力更强的模型,成本控制灵活得多。第三是它的社区生态,持续有人在贡献插件和玩法,比如后面要讲的桌面版、IDE插件、skills扩展,都是社区推动起来的能力。
当然,它也不是没有缺点。因为迭代速度快,某些版本会出现兼容性问题;配置分散在JSON文件和环境变量里,新人不熟悉的话确实容易踩坑。接下来的章节,我会把这些坑挨个说清楚。
2. 环境准备与安装:Windows用户最容易卡住的环节
2.1 安装之前,先确认你的环境
opencode的安装其实不算复杂,但很多人失败都失败在前置环境上。我的建议是动手之前先花一分钟确认三样东西:Node.js版本、Git、以及一份可用的模型API Key。
opencode基于Node.js构建,官方通常建议Node 18以上,实际体验中我觉得直接上最新的LTS版本最省心(目前建议20或22)。如果你的机器上Node版本很旧,后面安装或运行时会出现各种莫名其妙的报错,到时候再回头排查就麻烦了。Git主要用于让opencode读取仓库信息和执行一些git操作,Windows用户装了Git Bash也会顺手解决一些终端环境问题。API Key方面,只要你有任意一家支持OpenAI兼容接口或Anthropic接口的模型服务即可,刚开始不一定要多好,能跑通流程最重要。
检查环境很简单,终端里分别执行node -v和git --version,能看到版本号就行。如果你的机器上还没有Node,去官网下载LTS安装包装一遍,整个过程大概五分钟。这里有个小细节:Windows用户装Node时记得勾选“Add to PATH”选项,否则装完Node却找不到npm命令,后面又得手动配环境变量。
2.2 三种安装方式:npm、Homebrew、Go
opencode提供多种安装渠道,官方主推的还是npm和Homebrew,另外因为热词里提到“opencode go”,这里也单独说一下Go安装方式。我把三种方式整理成了表格,方便你按自己的环境选择:
| 安装方式 | 命令 | 适合场景 | 备注 |
|---|---|---|---|
| npm全局安装 | npm install -g opencode-ai | 最通用,Windows/macOS/Linux都行 | 包名以官方npm页面为准 |
| Homebrew | brew install sst/tap/opencode | macOS用户 | 通过tap仓库安装 |
| Go install | go install github.com/sst/opencode@latest | 开发者、想用go版本 | 机器上需要装好Go |
我个人在macOS上习惯用Homebrew,升级方便,一条命令就能搞定。Linux服务器上则更喜欢用Go安装,因为这种方式会生成单个二进制文件,部署到远程机器时不依赖Node环境,热词里说的“opencode go”其实就是这个方向。Windows用户最稳妥的还是npm方式,装完之后注意看终端输出的安装路径。
装完以后,验证一下安装是否成功,运行opencode --version,能输出版本号就说明基础环境ok。如果你是在Windows的PowerShell里运行这一步时看到“无法将opencode项识别为cmdlet”的红色报错,那你多半踩中了下面这个经典坑。
2.3 Windows下“无法将opencode项识别为cmdlet”的真相
这个问题在社区里被问过无数次,我第一次装的时候也懵了一下。其实报错本身说得很清楚:系统不认识opencode这个命令,最常见的原因就是npm的全局安装目录没有加入系统PATH,或者安装没有真正成功。
排查的第一步,先确认包有没有装上去。运行npm ls -g opencode-ai,如果列表里能看到这个包,说明安装本身没问题,问题出在PATH。接下来运行npm config get prefix,会输出npm全局目录的路径,比如C:\Users\你的用户名\AppData\Roaming\npm。你需要把这个目录手动加入系统环境变量的Path里,然后重新打开一个终端窗口,再执行opencode --version,一般就能识别了。
这里有个非常容易忽略的细节:一定要新开终端窗口,而不是在原来的窗口里继续敲命令。因为环境变量是进程启动时读取的快照,不会动态刷新,旧窗口里的PATH信息还是老的。我见过不少人改完Path之后在旧窗口里反复试,试了半天报错依旧,最后换个窗口瞬间就好了。另外,如果你用的是PowerShell,还要留意一下执行策略,有些机器默认禁止运行脚本,需要以管理员身份设置Set-ExecutionPolicy RemoteSigned,否则即使命令能识别也可能被拦下来。
2.4 顺手把ccswitch配好:多模型密钥统一管理
opencode支持多个模型Provider,但这也带来一个问题:当你有Anthropic、OpenAI、Gemini、还有本地模型的Key时,每次切换都要去改配置,特别麻烦。热词里频繁出现的ccswitch,就是解决这个痛点的开源工具。它的作用类似于一个“密钥交换机”,专门用来统一管理多个AI平台的API Key和模型配置,并且支持把同一份配置一键同步给opencode、Claude Code等不同工具。
用ccswitch配置opencode的流程很直观:打开ccswitch的TUI界面,添加一个opencode对接项,填入你想要的Provider名称、API Key和BaseURL,保存后它会把对应的配置同步到opencode的配置文件里。之后想换模型,直接在ccswitch里切换,不用再手动编辑opencode的JSON配置。
为什么说“opencode go 需要配合 cc switch 等工具”?因为Go版本的原生配置方式更偏命令行,没有像桌面版那样完善的图形设置面板,大多数人更习惯用ccswitch来统一管理。我的建议是,不管你是npm装的还是go装的,都配一个ccswitch,它能让你后续切换模型时省下大量时间。
3. 配置与模型接入:把opencode真正喂饱
3.1 首次启动:进入TUI后的第一件事
安装完成后,在你自己的项目目录下执行opencode,会进入一个全屏的TUI交互界面。这个界面乍一看有点像终端版的聊天软件,左下角输入框可以直接发消息,右侧会实时展示opencode读文件、执行命令的日志。第一次启动时,它会询问你要用哪个模型Provider,如果没有提前配置,界面里也会有提示。
我的建议是:在进TUI之前先手动把配置文件写好,这样体验更流畅。opencode的配置文件支持全局和项目两个层级,全局配置文件一般在~/.config/opencode/opencode.json,项目根目录也可以放一个opencode.json,项目级配置会覆盖全局配置。下面是一个最基础的配置示例:
{ "$schema": "https://opencode.ai/config.json", "provider": { "openai": { "apiKey": "sk-你的key" } }, "model": "gpt-4o" }如果你用的是Anthropic接口,配置也类似,把provider改成anthropic,apiKey填成Anthropic的Key。还有人会问,Key能不能不写进配置文件?可以,opencode同样支持通过环境变量读取API Key,比如设置OPENAI_API_KEY,这样配置文件里就不需要明文写上Key了,安全性更高,尤其适合会把配置文件提交到仓库里的团队项目。
配置完成后,先让它做个最简单的活来验证连通性:在输入框里发一句“看一下当前项目结构,告诉我这是什么技术栈”。如果它能正确回复出目录文件和框架信息,说明模型接入成功,可以开始正经使用了。
3.2 免费模型怎么接:省钱可以,但别当真主力
opencode之所以受欢迎,还有一个重要原因是它能接免费模型,这对个人开发者、学生党非常友好。免费模型的来源大概有三种:云厂商的免费额度、开源模型的本地部署、社区的免费中转接口。
先说云厂商免费额度,典型代表是Google Gemini的免费层和一些大模型厂商的新用户免费额度,这些接口本身稳定可靠,只是有调用次数或速率限制,用来学习体验完全够用。接入方式也很简单,因为它们大多提供OpenAI兼容接口,你只需要在配置文件里加一个自定义Provider,把BaseURL指向对应厂商的接口地址就行。下面是接入一个OpenAI兼容免费模型的示例:
{ "provider": { "custom": { "npm": "@ai-sdk/openai-compatible", "name": "free-model-provider", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "免费模型的key" } } }, "model": "free-model-provider:模型名" }再说社区免费中转接口,这类服务确实存在,便宜甚至免费,但稳定性参差不齐。社区里时不时就有“某个免费接口下线了”的传闻,就是这个现状的缩影——很多免费接口说关就关,或者改个鉴权方式就让你白折腾半天。我的态度是:免费中转可以拿来尝鲜、跑测试,但不要把正经项目的自动化工作流搭在它上面,一旦服务下线,你的开发节奏就断了。
最后说本地模型,如果你有一块像样的显卡,跑一个量化版的开源模型也不是不行。但opencode这种Agent式工具对模型的工具调用能力要求很高,本地小模型的指令遵循能力往往不够,经常出现“让它改代码它改错位置”的情况。所以我的结论是:想低成本体验用云厂商免费额度,想省心还是直接上好一点的收费模型,免费模型省下来的是钱,花掉的是时间和耐心。
3.3 多Provider配置与切换的进阶玩法
等到你用顺手之后,大概率会同时配置多个Provider,因为不同任务适合不同模型。这时候配置文件就会变成下面这样:
{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "apiKey": "sk-ant-你的key" }, "openai": { "apiKey": "sk-你的key" }, "deepseek": { "npm": "@ai-sdk/openai-compatible", "name": "deepseek", "options": { "baseURL": "https://api.deepseek.com/v1", "apiKey": "你的key" } } }, "model": "anthropic:claude-sonnet-4-20250514" }配置好之后,你可以在启动opencode时用--model参数临时指定模型,也可以在会话里切换。如果配合前面提到的ccswitch,切换就更丝滑了。这里我要提醒一点:别为了追求“所有模型都能用”把配置文件堆得特别长,模型的工具调用兼容性是有差异的,有些模型即使接口能通,实际干活时也会频繁报错。我建议你先固定1到2个经过验证的模型用来干活,等有余力再去尝试新模型,不要贪多。
还有个常见的配置诉求是设置低风险模式或限制工具权限。opencode默认会用一些只读工具来了解项目,但需要修改文件、执行命令时也有对应开关。对于刚上手的用户,我建议把工具调用的确认级别调高一点,让它在执行重要操作前向你确认,避免它自作主张改坏文件。这个设置在不同版本里位置略有区别,但一般在配置的permission或tools相关字段,可以自己翻翻配置说明。
4. 上手实操:命令行、桌面版、IDE插件一网打尽
4.1 命令行交互:两种最常用的用法
先说最核心的命令行用法。opencode其实提供两种基本模式:交互模式和非交互模式。
交互模式就是我们前面说的,直接运行opencode进入TUI,然后一问一答地干活。适合快速探索、对话式修改代码。非交互模式则是一次性执行,命令格式是opencode run "你的指令",它会在后台跑完任务后直接退出,适合脚本化、批处理。我给团队写自动化脚本时就很喜欢这种模式,比如每天定时让opencode去扫描某个目录下的TODO注释,并生成一份报告。
除了run子命令,还有几个常用参数值得记住。--model可以临时指定模型;--file可以给opencode指定聚焦某个文件;加上-v参数可以输出详细日志,排查问题时会很有用。举个例子,我想让opencode检查某个服务的超时逻辑并给出优化建议,可以这么写:
opencode run "检查 src/service/order.ts 里的超时处理,找出可能导致请求挂起的问题,并给出修复建议" --file src/service/order.ts这样opencode会先把注意力放在这个文件上,再结合项目上下文给出更精准的分析。实际体验中,任务描述得越具体,它干活的效果越好,那种“帮我优化一下代码”这种模糊指令,它往往不知道从哪下手,最后只会给你一堆无关痛痒的建议。
4.2 桌面版与VSCode、JetBrains插件:编辑器党的正确姿势
命令行虽然硬核,但很多人还是更习惯在IDE里工作。opencode在这一点上想得很明白,官方和社区分别做了桌面版、VSCode插件和JetBrains插件,正好对应不同使用习惯的人群。
opencode desktop是桌面客户端,本质上是把opencode的界面包装成一个独立应用,适合不想碰终端、又想享受Agent式编程体验的人。它和TUI模式共享同一套配置,所以你在命令行里配好的模型和skills,桌面版里直接就能用。
VSCode插件则是更贴近开发流程的选择。装好插件后,在侧边栏可以直接打开opencode会话,它会把文件改动以diff形式展示出来,你能在编辑器里逐行查看建议,决定接受还是拒绝。这个体验对前端调试特别友好,改完代码立即能在预览或浏览器里验证。JetBrains系(IDEA、PyCharm等)也有对应的插件,用法类似,尤其配合热词里的“mvn配置”,Java项目里改pom.xml、跑Maven构建,在IDE里操作起来非常顺手。
我的个人习惯是:日常开发主力用VSCode插件,因为能看到diff和文件树;独立处理批量任务时用命令行模式,因为可以更快地跑脚本和批处理。插件和命令行之间是共享配置的,不用担心两边状态不一致。
4.3 skills、memory与superpowers:让它越用越懂你
如果只是把opencode当成聊天窗口来用,那其实没有完全发挥它的价值。真正让Agent工具拉开差距的,是自定义扩展能力。opencode在这块提供了两个核心机制:skills和memory。
skills可以理解成“预置的技能包”。你可以为特定任务写一份skill,里面包含这个任务的背景、操作流程、注意事项,这样opencode遇到类似任务时会自动加载这套方法论,不会再从头摸索。一个经典场景是代码评审:我日常做团队评审时,会让opencode按照我定义的检查项去审查新代码,包括安全性、性能隐患、命名规范等,效果比直接说“帮我看看代码”好得多。
memory则是通过项目里的AGENTS.md文件实现的。你可以在AGENTS.md里写下项目的技术栈约定、构建命令、目录结构等长期上下文,opencode每次开始干活前会自动读取这个文件,相当于给它一份“项目入职手册”。有了它,即使隔了很久再打开一个旧项目,opencode也能快速回忆起项目约定,不用每次重新解释一遍。
热词里的oh-my-claudecode和superpowers,都是社区里很火的技能包/工作流增强方案。oh-my-claudecode原本是给Claude Code做的技能集,现在社区也有方案能复用到opencode上(比如openclaude项目),它把常见开发流程拆成了大量可复用的skill。superpowers则是另一套强调“给Agent超能力”的工作流包。我的建议是:可以先从别人的技能包抄作业,但用一段时间后一定要沉淀出自己的skill集合,因为别人的工作流不一定适合你的项目,自己整理的才是最高效的。
5. 实战案例:让opencode接手一个真实项目
5.1 快速接手陌生项目的正确姿势
很多人第一次用opencode接手项目时,上来就让它“给我加个登录功能”,然后发现它东改西改,diff爆炸,最后代码还跑不起来。这个问题不在于opencode能力不行,而在于任务拆解方式不对。我的经验是,接手一个陌生项目时,把它当成一个刚入职的程序员来带,分阶段给任务。
第一阶段是熟悉项目。进入项目目录启动opencode后,先发一个探索型prompt:“先读README和AGENTS.md,看一下目录结构,告诉我这个项目的技术栈、入口文件和主要模块,不用改任何代码。”opencode会把项目扫描一遍,输出一份概览。这一步能验证两件事:模型有没有读懂项目、opencode的文件读取工具是否正常。如果模型连概览都给不出来,后面再怎么细化任务都是白搭。
第二阶段是做一个小而具体的需求。比如“给登录接口的password字段增加长度校验,长度不足时返回400错误。”这个任务足够明确:改一个文件、可能加一个测试,风险小,能快速验证它是否理解业务逻辑。等它改完,你要做的是逐行看diff,确认改动符合预期,再让它跑一下相关测试。
第三阶段才是让它独立处理一些范围较大的任务,但也一定要约定边界。我一般会在prompt里明确“只修改src/module/user下面的文件,不要动其他模块”“不要执行数据库迁移命令”等限制条件。让Agent在可控范围内自由发挥,效果往往是最好的。
5.2 opencode + Playwright:前端bug复现与验证
做前端的同学最头疼的事之一,就是bug复现困难。opencode配合Playwright,能把这个环节自动化起来。思路很简单:让opencode写一段自动化脚本,通过浏览器把问题复现出来。
比如你遇到一个交互bug:点击某个按钮后,弹窗没有出现。你可以这样给opencode下指令:“用playwright写一个脚本,打开本地开发服务器,点击首页上的‘获取详情’按钮,断言弹窗元素在3秒内可见,如果不可见就把页面截图保存下来。”opencode会生成类似下面的脚本并尝试运行:
const { test, expect } = require('@playwright/test'); test('点击按钮后弹窗应出现', async ({ page }) => { await page.goto('http://localhost:3000'); await page.getByRole('button', { name: '获取详情' }).click(); await expect(page.locator('.modal')).toBeVisible({ timeout: 3000 }); });脚本跑起来之后,如果断言失败,opencode会读取失败信息,进一步定位问题。这个过程非常直观,能省下不少手工点击和截图的时间。但说实话,opencode用Playwright做“复现bug”是一把好手,做“修复样式类bug”就容易陷入循环:它改一版你看一版,调来调去都不满意。所以我的建议是,把Playwright定位到的具体问题交给opencode修,但复杂的视觉样式调整,还是人肉上手更快。
5.3 Java项目里用opencode:mvn配置与实操
最后说说Java项目,这是很多IDEA用户关心的场景。Java项目相比Node/Python项目,构建链路更重,对工具链的要求也更高,opencode在Java项目里能不能用得顺手,关键在环境配置。
首先,确保opencode启动时的环境里能识别Java和Maven。很多人遇到的问题是:在IDEA终端里运行opencode,让它在项目里跑mvn test,结果报“mvn不是内部或外部命令”。原因很简单,IDEA内置终端默认加载的是系统环境变量,如果你是在IDEA里手动设置的JDK路径,没有写进系统Path,那Maven命令自然找不到。解决办法是确认JAVA_HOME和Maven的bin目录都在系统环境变量里,然后重启IDEA或终端再试。
其次,给Java项目写好AGENTS.md非常关键。我会在里面写清楚项目的构建命令是mvn clean package还是gradle build、测试命令是什么、主类入口在哪里、依赖管理用的什么仓库。这样opencode每次干活前都能自动掌握这些信息,不至于反复问“这个项目怎么构建”。它自己在执行构建失败时,也能更快定位是依赖问题还是代码问题。
实操层面,一个典型的场景是让opencode改pom.xml加依赖并写单元测试。你可以直接说:“给项目加上spring-boot-starter-validation依赖,并在UserServiceTest里补充一个校验注解的测试用例,最后跑mvn test验证。”opencode会修改pom.xml、添加或修改测试类、执行Maven测试,然后汇报结果。Java项目上下文普遍偏大,模型更容易在复杂依赖里迷路,所以我个人建议Java项目尽量用能力更强的模型,比如Claude Sonnet或GPT-4o级别,便宜的小模型在Java大型项目里表现会明显打折扣。
6. 常见问题排查与避坑指南
6.1 高频报错与解决方案速查表
opencode用久了,总会碰到各种报错。我把这段时间遇到的高频问题整理成了一张速查表,建议收藏备用:
| 报错或现象 | 可能原因 | 解决方案 |
|---|---|---|
| 无法将opencode项识别为cmdlet | npm全局目录未加入PATH | 找到npm全局目录并配置系统Path,重开终端 |
| unexpected server error,check server logs | 模型API Key失效、Provider配置错误 | 检查Key是否正确、过期,核对BaseURL |
| 请求超时或一直转圈 | 模型服务端响应慢、网络波动 | 切换模型重试,或检查网络环境 |
| 报错找不到node/npm/mvn等命令 | 对应运行时的bin目录不在PATH | 把运行时加入系统PATH,重开终端 |
| 模型返回格式错误 | 接入了不兼容的模型 | 换成opencode社区验证过的模型 |
| 免费中转模型突然不可用 | 服务下线或变更鉴权 | 换备用Provider,不建议依赖中转服务 |
| opencode执行命令被拒绝 | 权限确认机制拦截 | 在配置中调整工具权限,或手动确认 |
这几类问题里,最容易被忽略的是第二种“unexpected server error”。它看着像opencode自己崩溃了,其实大多是模型服务端的锅。有一次我排查了半天,最后发现是API Key所在的账户额度用完了。所以遇到这类报错,先别急着怀疑opencode,先检查Key和Provider,成功率最高。
6.2 这几个坑我替你们踩过了
第一个坑:盲目追最新版。opencode迭代速度极快,几乎每周都发新版本。有一段时间我图新鲜,每次发版立刻升级,结果某个版本把配置文件格式改了,我前一天还能跑的项目第二天整个起不来。从那以后我学乖了:生产环境固定在一个稳定版本,新版本先在测试目录里体验,确认没问题再升。
第二个坑:把Key写进配置文件然后提交到仓库。我见过不止一个开发者把API Key直接写在项目根目录的opencode.json里,还顺手git push到了远端,几分钟内Key就被别人盗刷。正确的做法是优先用环境变量注入Key,全局配置文件里的敏感信息也要做好脱敏,更不要把带Key的文件提交到公开仓库。
第三个坑:没有范围控制就让Agent自由发挥。有一次我让它修一个接口的bug,它顺手帮我“优化”了同一个模块里的另外五个文件,diff变得巨大,review成本直线上升。现在我会在任务里明确边界,改哪些文件、不动哪些文件,一开始就说清楚。这不仅是控制质量,也是在省Agent的调用次数,毕竟每次工具调用都是要花模型钱的。
第四个坑:对大项目不写AGENTS.md。项目越大,模型就越容易迷失。你不给它项目地图,它就靠猜,猜错方向就会出现“明明只改一个文件的事,它翻遍了整个项目”的情况。给项目写一份简洁的AGENTS.md,相当于给Agent配了一副地图,收益率极高。
第五个坑:把免费模型的稳定性当成必然。前面说过,免费中转接口随时可能下线,哪怕是一开始表现不错的服务,也可能在一夜之间变成错误接口。如果你真的在意稳定性,建议至少准备两个Provider作为灾备,一个收费一个免费,关键时刻能切换。
6.3 最后分享两个我自己觉得很好用的小技巧
第一个技巧是用alias简化高频操作。我每天最常用的命令是opencode run,所以我给终端加了一个别名,一键进入开发模式:
alias oc="opencode run"这样写起来短很多,比如oc "给order服务加上重试逻辑,超时时间设置为3秒",敲起来非常顺手。如果你经常切换模型,还可以配合--model写几个别名,比如oc-claude对应使用Claude模型,oc-gpt对应使用GPT模型,用起来就像是在终端里快速切换“不同水平的实习生”。
第二个技巧是把日常工作流沉淀成skill。我给自己定义了一个“daily-review”技能,专门用来每天review当天改动的代码。它包含了一套固定的检查清单,包括安全风险、异常处理、日志输出、代码格式等。每次运行,opencode都能按照这套标准去审查代码,比临时口头描述清楚多了。这类技能文件放在项目的.skills目录里,一次创建,长久复用。随着你的技能库越来越丰富,opencode就不再只是一个“问一句答一句”的工具,而是一个真正理解你开发习惯的编程伙伴。
我自己现在的工作流已经离不开opencode了,从接手新项目到日常开发再到代码审查,它几乎全程参与。虽然它有时候也会写出不太聪明的代码,但站在个人效率和项目管理成本的角度,这些小的不完美完全可以接受。希望这份实践指南能帮你少踩点坑,更早地把opencode用起来。