opencode实战：从安装配置到用AI Agent重构开发流程

最近一段时间我的日常开发流程里多了一个离不开的工具——opencode。如果你还没听过它简单说它是一个跑在终端里的开源AI编程Agent能自己读代码、改文件、跑命令、调测试而不是像聊天机器人一样只给你贴一段代码让你自己手动复制粘贴。配合VS Code、JetBrains插件或者桌面版基本能做到“我把需求讲清楚它把活干完”。很多人第一次听说opencode都是从“安装失败”或者“命令行无法识别”这类报错开始的。这也正常越是这类工具越需要在环境准备上花点心思。这篇文章不打算复读官方文档而是把我从安装、配置模型、接Skills和MCP到拿它实际接手一个半成品项目的完整过程记录下来。如果你正准备把AI Agent真正用进开发流程这篇值得看完。1. 整体定位opencode到底解决什么问题1.1 从“聊天机器人”到“能动手干活的Agent”过去几年我们熟悉的AI编程工具多数停留在“补全代码”或者“对话生成代码”的阶段。你写一句注释它帮你补函数你贴一段报错它给你解释原因。但最终动手改文件、跑测试、看运行结果的人还是你自己。opencode不一样。它运行在终端里被赋予了执行命令、读写文件的权限因此它能直接操作整个代码仓库。你说“这个订单接口缺了库存校验”它会自己找到接口文件、看懂上下游调用、写出修改方案然后真的把代码改了再跑一遍测试给你看。它的定位不是“更聪明的自动补全”而是“能独立完成小任务的实习程序员”。这正是Agent类工具和以前Copilot类工具最本质的区别前者手里有工具能行动能验证结果后者只负责出主意。1.2 设计上做对了什么我实际用下来觉得它在设计上有几个点特别值得聊会话在终端里和命令行工作流天然契合。你不会被从编辑器里拽出去随时随地一个opencode就进入工作状态。所有操作可追溯。它改了哪些文件、执行了哪些命令都会列出来你可以随时叫停、审查、回滚。配置驱动。模型、MCP服务、Skills都可以通过配置文件统一管理项目里放一份配置团队其他人拉下来就能用。不锁定单一模型。Claude、GPT、Gemini、本地Ollama模型都可以接这对不想被某一家厂商绑死的团队来说非常重要。扩展性强。Skills能教它执行团队特有的工作流MCP能让它调用浏览器、数据库等外部工具插件和桌面版又降低了非终端用户的上手成本。1.3 什么时候该用它什么时候要慎用先说适合的场景。接手一个没文档的老项目让它先梳理技术栈和目录结构批量替换或重构重复代码给关键函数补单元测试让它在浏览器里复现前端bug并定位问题甚至是按团队规范生成commit信息。这些事情的特点是规则明确、重复度高、需要动很多文件。不太适合的场景也有。一个超大仓库的整体架构重构它一次性handle不住容易改到一半“忘掉”前面的约束涉及生产环境部署、数据库迁移、支付权限这类高危操作也别让它直接执行。它更像一个能力很强但需要你盯着的实习生不是可以做甩手掌柜的合伙人。2. 环境准备与安装最快10分钟跑起来2.1 需要提前准备哪些环境在安装opencode之前先把基础环境检查一遍Node.js 20 或更高版本。推荐用nvm或nvm-windows管理版本因为它会直接影响npm全局包的安装位置。Git。opencode在操作项目时经常依赖git做变更查看和回滚。一个模型API Key。可以来自Anthropic、OpenAI等云服务商也可以本地搭Ollama跑开源模型。IDE插件或桌面版可选如果你想在编辑器里直接用可以一并装好。检查Node版本很简单终端执行node -v npm -v如果提示找不到node先装好Node环境再继续。2.2 三条安装路径官方提供了多种安装方式我试下来最常用的是npm全局安装npm install -g opencode-ai如果你的机器上有Bun也可以用Bun装速度会快一些bun install -g opencode-aimacOS用户可以使用Homebrewbrew install sst/tap/opencodeLinux用户还可以用官方安装脚本不过我更建议优先走包管理器因为后续升级和卸载都方便。装完之后验证一下opencode --version能正常输出版本号说明安装成功了。2.3 WindowsPATH问题的完整解法如果你在Windows上遇到下面这个报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这基本可以断定npm的全局安装目录没有加到PATH环境变量里。解决办法不复杂按步骤来第一步查看npm全局目录到底在哪npm config get prefix默认情况下Windows上输出的是C:\Users\你的用户名\AppData\Roaming\npm。第二步把这个目录加到用户PATH里。图形界面操作是右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“用户变量”里找到Path → 新建 → 粘贴上面的路径。想用命令行一步搞定的话在PowerShell里执行[Environment]::SetEnvironmentVariable(Path, [Environment]::GetEnvironmentVariable(Path, User) ;C:\Users\你的用户名\AppData\Roaming\npm, User)第三步必须重新打开一个终端窗口再试opencode --version。这里有个很多人踩过的坑改完PATH后不重开终端新环境变量不会生效。还有一个容易忽略的情况如果你用nvm-windows管理多个Node版本每次切换版本后某些全局包可能找不到。这属于nvm的已知行为建议把常用的Node版本固定下来或者切完版本后重装一次全局包。注意不要为了省事把npm全局目录直接放到C:\Program Files\nodejs下面普通权限下会遇到“管理员权限不足”的连锁问题。走用户级目录是更稳妥的选择。2.4 首次启动与API配置安装完成后在项目目录里直接执行opencode首次启动会让你选择模型Provider。如果选择Anthropic可以用登录命令完成认证opencode login它会打开浏览器完成授权流程。想用环境变量的方式配置API Key也很简单。macOS/Linux在shell配置里加export ANTHROPIC_API_KEYsk-ant-xxxWindows PowerShell里则是$env:ANTHROPIC_API_KEYsk-ant-xxx这里要提醒一句不要把API Key写进项目里面的文件再提交到Git仓库。正确的做法是放在系统环境变量里或者用direnv这类工具做目录级的环境变量管理。如果你不想用云服务商的API本地装Ollama跑开源模型也完全可以。先启动Ollama并拉一个代码模型ollama pull qwen3-coder ollama serve然后在opencode里用/model命令切换到对应模型。这种方式对隐私敏感的项目特别友好模型推理全部在本地完成。3. 模型选择与配置文件不要只会用一个模型3.1 opencode.json 配置文件入门opencode的配置遵循一个原则命令行参数适合临时切换配置文件适合固化习惯。配置文件默认放在用户目录下macOS/Linux~/.config/opencode/opencode.jsonWindows%USERPROFILE%\.config\opencode\opencode.json同时也支持项目级配置放在.opencode/opencode.json。项目级配置的优先级更高适合团队统一约束。最简配置文件长这样{ $schema: https://opencode.ai/config.json, model: sonnet, provider: { anthropic: { models: { sonnet: { name: Claude Sonnet 4 } } } } }这个配置声明了两件事默认使用sonnet这个模型以及这个模型由Anthropic Provider提供。实际使用中模型名必须和你所选Provider支持的ID一致否则启动时会报“模型不存在”之类的错误。3.2 模型怎么选不同模型的代码能力、速度、价格差异很大。我根据自己的使用体验整理了一张对照表模型/Provider特点适合场景Claude Sonnet 4代码理解强推理稳定速度均衡日常开发、重构、代码审查Claude Opus 4推理能力更强但速度慢、费用高复杂架构设计、疑难bug定位GPT-5系列通用能力强工具调用成熟多语言项目、脚本生成Gemini 2.5 Pro长上下文突出价格有优势大仓库分析、长文档代码库Qwen / DeepSeek 等开源模型Ollama本地运行隐私好、零API费用离线环境、敏感代码我的习惯是日常小改动用速度快的中型模型重大重构才切到Opus这类更强的模型。毕竟Agent跑任务是要计token的不是越强的模型越划算。3.3 对话中快速切换模型在opencode会话里最常用的命令是/model。输入之后会弹出可选模型列表直接上下键选择再回车就行。切换只对后续对话生效前面生成的代码不会受影响。命令行里还有一些高频操作/help查看当前版本的命令列表/init让Agent先理解项目结构建立全局认知/plan进入规划模式只出方案不写代码/build进入执行模式实际动手改代码/mcp管理外部工具连接提示如果你发现Agent开始“答非所问”往往不是模型坏了而是对话历史太长、上下文窗口被无关内容占满了。这时候最有效的操作不是继续追问而是新开一个会话把关键约束写进一个markdown文件里让Agent先读文件再开工。3.4 一个容易忽略的成本问题模型切换越自由越容易忽略token消耗。同一个任务Claude Opus可能比Claude Haiku贵好几倍。我的建议是长对话任务尽量分段执行每完成一个阶段就总结出关键进展然后新开会话接着做。这样既省token又能避免上下文过长导致的“失忆”。4. 核心能力实战Skills、MCP与IDE插件4.1 Skills把团队经验“写”给AgentSkills是opencode里非常实用的扩展机制。本质上它是放在项目目录下的一组Markdown文档用来告诉Agent遇到什么场景、按什么步骤做事。相当于把团队的代码规范、发布流程、审查标准“写下来让AI照做”。创建步骤很简单。在项目根目录建一个技能文件夹.opencode/skills/code-review/SKILL.mdSKILL.md的内容格式如下--- name: code-review description: 审查项目中的代码改动输出问题清单和改进建议 --- # 代码审查技能 当需要代码审查时按以下步骤执行 1. 运行 git diff HEAD~1 查看最近一次提交的改动 2. 逐文件阅读变更内容 3. 重点检查错误处理、边界条件、安全问题、可读性 4. 输出 Markdown 格式的审查报告按严重程度排列以后在对话里说“帮我审查最近一次提交”Agent就会按照这个流程执行。你还可以写代码提交规范、环境搭建步骤、测试执行策略等技能效果类似给Agent写了一份“岗位说明书”。我个人的体会是Skills真正的价值在于知识沉淀。以前新人入职要花几天熟悉团队的规范和流程现在把这些东西写成技能Agent能帮助新人以一致的方式完成基础工作效率提升非常明显。4.2 MCP让Agent接进你的工具链MCPModel Context Protocol是一个开放协议让AI Agent可以调用外部工具。opencode实现了MCP客户端可以连接Playwright、GitHub、数据库等外部服务。有了MCPAgent就不再只是“改代码的工具”而是能打开浏览器、操作页面、查数据的自动化助手。在配置文件里添加MCP服务{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }保存后重启opencode再用/mcp查看连接状态。确认显示已连接就可以让Agent调用Playwright了。4.3 用Playwright MCP让Agent自己测前端bug前端bug的复现往往很磨人手动点击、看控制台、抓接口请求一套流程下来十几分钟就没了。接了Playwright MCP之后这个过程可以直接交给Agent。假设项目跑在localhost:3000你可以这样说帮我复现这个bug在首页点击“提交订单”按钮控制台报错。Agent会调用Playwright打开页面、点击按钮、捕获浏览器控制台的报错信息再根据调用栈定位到具体文件。整个交互过程大致是opencode我调用Playwright打开页面并点击按钮发现控制台报错 Unhandled Rejection (TypeError): Cannot read properties of undefined (reading items) opencode根据调用栈定位到 src/components/CartSummary.tsx 第42行库存字段在接口返回为空时没有做兜底。我先加上默认值再跑一次测试。这才是Agent类工具最有价值的地方它能验证自己的修改结果而不是像传统补全工具那样给你一段“看起来对”的代码。4.4 IDE插件和桌面版终端虽然强大但不少人还是更习惯在IDE里用AI。opencode在这方面做得比较全VS Code插件直接在扩展市场搜索OpenCode装完会在侧边栏或编辑面板出现可以选中代码段发送给Agent改动以diff形式展示。JetBrains插件支持IDEA、WebStorm、GoLand等Java和Go项目用起来很方便。OpenCode Desktop独立桌面应用Windows、macOS、Linux都有安装包适合不想开终端也不想开IDE的场景。我个人的建议是先在VS Code插件里体验降低上手成本。等熟悉了工作流再迁到终端也不迟。5. 实战用opencode接手一个半成品项目5.1 先让Agent“读”项目再谈改代码接手老项目最忌讳上来就改代码。你连项目结构都没理清Agent自然也会乱。正确的顺序是先让它建立全局认知。cd ~/work/legacy-app opencode然后输入先帮我梳理这个项目的技术栈、目录结构和启动方式输出一份README级别的说明。Agent会自己读package.json、README、关键目录然后把梳理结果整理出来。如果发现项目根本没有README它还会主动生成一份到docs/PROJECT_SUMMARY.md。这一步做完无论后续是你自己改还是让Agent继续改效率都会高很多。5.2 让它修第一个bug拿一个常见bug举例表单提交后列表不刷新。你需要给Agent提供足够的信息包括复现步骤、期望行为和当前现象复现步骤打开用户管理页填写用户名点击提交列表没有出现新用户。 期望行为提交成功后列表自动刷新并显示新用户。 请先定位原因说明修改方案后再动手。注意最后一句“先说明修改方案再动手”这非常关键。它把Agent从“盲目改代码”切换成“先计划后执行”。复杂任务建议先/plan让它出方案确认无误后再/build执行。实际执行过程中Agent会检查表单提交逻辑、接口调用、列表数据刷新函数通常能自己找到问题所在。如果它连续两次给出相同方案都没解决果断中断清理会话重新描述问题。5.3 让Agent补测试给老项目补测试是Agent擅长的方向之一。你可以直接下指令帮这个下单接口写单元测试覆盖正常路径、库存不足、用户未登录三种情况。Agent会读取接口代码分析分支逻辑然后生成测试文件。生成后运行测试有失败它会自己看原因再改。我自己实操时有个小技巧补完测试后故意改坏一个函数让它跑挂看Agent能否根据报错自己定位并修复。大部分情况下它能完成但复杂业务逻辑的修复结果必须人工验收。5.4 什么时候必须人工介入Agent再强也不能完全放手。我在实践中总结了几个必须叫停的节点涉及生产环境部署、数据库迁移的操作绝对不要让Agent直接执行。修改鉴权、支付、权限控制的核心代码一定要人工看完整diff。当Agent连续两次给出相同错误方案时果断停下清理会话重新描述。强烈建议在独立git分支上跑Agent任务方便随时回滚。我把这四条当成使用红线。守住它们Agent是效率利器守不住它可能就是事故源头。6. 常见问题与排查技巧实录6.1 问题速查表这段时间我踩过不少坑也帮朋友排查过一些问题整理成对照表现象可能原因解决办法无法将“opencode”识别为cmdlet、函数或程序npm全局目录不在PATH参照2.3节将npm全局目录加入用户PATHunexpected server error. check server logsAPI Key无效、额度不足、模型ID错误、远端服务异常检查环境变量是否生效、模型ID拼写是否正确、用官方接口测试连通性Agent改了代码但没生效会话上下文太长Agent基于过期信息操作新开会话先让Agent重新读相关文件本地Ollama模型响应很慢模型参数太大或硬件不足换小参数量模型减少并行任务配置文件改了但没生效项目级配置覆盖了用户级配置确认项目下.opencode/opencode.json的内容插件连不上opencode后端版本不匹配或端口被占用升级插件和CLI到最新版本重启IDE6.2 日志文件是最后的排查手段如果遇到查不出原因的问题直接看日志。日志路径一般在macOS/Linux~/.local/share/opencode/log/Windows%USERPROFILE%\.local\share\opencode\log\还可以用环境变量开启debug日志export OPENCODE_LOG_LEVELdebug这样下次复现问题时日志里会记录Agent每一步的思考、命令执行、API请求详情排查起来直接命中要害。6.3 我的一些避坑心得最后分享几个实操中总结出来的经验。第一任务描述一定要具体“帮我优化一下登录模块”这种话连人都不知道从哪下手Agent也会迷路。好的描述是“登录接口在密码错误时返回的提示语不统一请统一为‘用户名或密码错误’”。第二一次只给Agent一个任务。让它同时做三件事每件事都做不深。拆成三个会话每个都做透效率反而更高。第三把项目约定写进根目录的AGENTS.md文件。opencode每次决策前都会自动读取这个文件你可以把编码风格、目录规范、禁止事项都写进去比在对话里反复强调有效得多。这也是我用下来觉得最值得推荐的一个小技巧。