上个月我把日常的AI编程助手从Claude Code整个换成了opencode跑了两个真实项目后决定把这套迁移过程完整记录下来。opencode是一个开源的终端原生AI编程代理核心卖点是不绑定任何一家模型厂商能自由接入本地模型、各家云厂商模型还能通过Skills和Memory机制让Agent记住项目规范。这篇文章适合已经被Claude Code、Codex这类工具勾起兴趣但还没入坑的新手也适合想从闭源工具逃离、又怕折腾的老用户。我会把安装报错、模型配置、技能包落地、浏览器自动复现前端Bug这些环节挨个拆开讲。1. 为什么从Claude Code切到opencode一个开源CLI编程助手的选型逻辑1.1 opencode到底是什么opencode是SST团队开源的一个终端AI编程助手本质是一个跑在终端里的Agent能读取你的项目文件、执行命令、修改代码、跑测试遇到前端问题还能直接拉起浏览器实测。它和Claude Code长得像但底层思路完全不同Claude Code绑定Anthropic的模型而opencode只做Agent框架模型后端走OpenAI兼容协议你想接哪个就接哪个。这个模型无关的设计是它这两年口碑起来的关键原因。很多人在第一次听到这个项目时习惯性地把它归类成又一个Claude Code山寨。实际用下来差别挺大opencode把Agent能力拆成了几个模块对话管理、命令行执行、文件编辑、浏览器自动化、技能系统、记忆系统全部走配置文件驱动。这也意味着你可以像搭积木一样按需组合而不是接受一个开了箱但改不了内部逻辑的黑盒子。1.2 我选它而不是继续用闭源工具的四个理由第一个理由是token成本。Claude Code的订阅是按月固定费用、按量又贵而opencode可以把我手头几个模型服务的额度全用上甚至可以在项目里跑本地模型成本直接降到接近零。第二个理由是配置透明。opencode的配置全是JSON文件在项目里能直接看到当前用了哪个模型、哪个provider、哪些skill被激活。出了问题可以沿着配置查而不是对着一个只能开关的闭源面板干瞪眼。第三个理由是生态接口。opencode支持Skills规范社区里已经有不少现成的技能包包括那个有名的superpowers技能集合。装上之后Agent会自动拆解任务、写TODO清单、分步执行一下子从只会接话变成真能干活。第四个理由是开源可控。它遵循开源许可证发布本地优先网络状况不好时有offline模式可以配合本地模型续命。这一点对在飞行途中、网络不稳定场所工作的人尤其重要。说到底编程助手这种工具长期用下来还是想握在自己手里。2. 安装到能跑通第一轮对话PowerShell报错、server error排查实录2.1 安装方式和各自的坑opencode的官方安装方式有三种我用下来分别说说它们的坑。macOS和Linux下最省事的是一条curl命令curl -fsSL https://opencode.ai/install | bash这个脚本会把二进制装到用户目录下然后自动写入shell配置。坑在于如果你的~/.bashrc或~/.zshrc里有自定义PATH逻辑安装脚本追加的export语句可能没生效重启终端后再次执行opencode --version报command not found。这时候别慌手动把安装目录加到PATH就行export PATH$HOME/.opencode/bin:$PATHWindows用户最容易遇到的就是热词里那个经典报错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名。这个报错十有八九不是opencode本身装坏了而是npm的全局bin目录没进PATH。如果你是用npm装的装完后PowerShell里立刻执行opencode大概率会碰到。解法是找到npm全局目录npm prefix -g得到路径后把该路径加到系统Path环境变量里或者直接跑$env:Path ;该路径临时生效。如果你是手动下载二进制解压到某个文件夹的那就把那个文件夹加进Path。还有一条普遍好用的兜底命令不需要任何PATH配置npx opencode-ai这个包名特别注意因为npm上已经有一个叫opencode的同名包但那是个其他项目别装错了。官方包名是opencode-ainpx会临时拉取最新版本然后启动适合你不确定要不要全局安装的时候先体验一把。2.2 一次顺手升级引发的server error我遇到的另一个报错是运行时报错启动时直接弹红色日志opencode error: unexpected server error. check server logs...这个报错第一次遇到容易懵因为提示信息很短没有告诉你具体哪里坏了。排查链路我建议按下面这个顺序来。第一步先看它到底为什么起不来。opencode会在本地起一个服务进程模型API、文件操作全走这个进程。如果你是在旧版本还开着服务的情况下直接升级二进制新老进程的通信协议对不上就会报unexpected server error。处理办法很简单先彻底退出旧进程再重新执行opencode。第二步是确认模型API配置是否有效。很多人第一次启动时还没配模型key或者key写错了opencode也会把它归类成server error。看配置的路子opencode models如果你的provider显示unauthenticated说明key没生效。第三步是看详细日志。执行opencode --print-logs日志会输出到终端里面通常会有具体的HTTP状态码和报错原因。opencode的日志文件默认在用户数据目录下的log里比如macOS是~/Library/Application Support/opencode/logLinux是~/.local/share/opencode/log。有时候你配置的模型域名网络不通日志里会明确写connection timeout你就能立刻定位到是网络侧的连通性问题不用再瞎猜。2.3 版本迭代带来的配置兼容问题opencode的迭代速度非常快2.0版本之后TUI界面和配置项都有过一波调整。如果你在网上找到一篇稍早的教程里面的opencode.json字段名可能已经废弃了。比如早期版本里部分provider配置用的字段在新版本里被归并进models对象直接照抄老配置会启动报错。遇到这种情况不要硬试打开官方文档看当前版本的配置schema最稳妥。3. 模型接入与免费模型的真相一条opencode.json搞定所有后端3.1 配置文件的层级和加载顺序opencode的配置分为全局配置和项目配置两层。全局配置默认在~/.config/opencode/opencode.json项目配置在项目根目录下的opencode.json。加载顺序是项目配置覆盖全局配置同名配置项以项目为准。这个设计很实用比如你全局默认用贵的旗舰模型但某个demo项目只想跑便宜的轻量模型就在项目配置里覆盖model字段即可。配置里最核心的字段是provider和model。provider解决连到哪的问题model解决用哪个具体模型的问题。打开你的配置文件典型长这样{ $schema: https://opencode.ai/config.json, provider: { deepseek: { npm: ai-sdk/deepseek, name: DeepSeek, options: { apiKey: xxxx }, models: { deepseek-chat: { name: DeepSeek V3 } } } }, model: deepseek/deepseek-chat }注意npm字段指向的是AI SDK的provider包opencode底层是Vercel的AI SDK所以它能兼容所有AI SDK已经适配过的provider。这就是为什么它接模型那么快生态是现成的。3.2 三种模型接入演示第一种是云服务商模型。我本地主力用的是DeepSeek、智谱、通义千问这几家全都能用同一种openai-compatible写法接进来原因很简单它们的请求协议都兼容OpenAI标准。以智谱为例{ provider: zhipu-ai, options: { apiKey: 你的key }, models: { glm-4.5: {} } }第二种是本地模型。用Ollama跑开源权重比如阿里的Qwen2.5-Coder系列配置方式更简单{ provider: ollama, models: { qwen2.5-coder:32b: {} } }前提是你本地装了Ollama并且已经pull了对应模型。本地模型的优势是断网也能干活劣势是代码理解和长上下文能力跟云端旗舰模型还是有差距大项目里我一般只拿它做简单重构和批处理任务。第三种是免费额度型接口。不少云服务商会给新用户赠送体验额度这类渠道接入方式和第一种完全相同只要把apiKey和baseURL换掉即可。我的经验是可以用来学习和低成本跑小任务但别把关键项目的自动化流程绑在免费渠道上因为你永远猜不到它哪天会调整策略。3.3 多模型切换和配置管理配置多个provider之后在opencode对话界面里用Tab键或快捷键就能循环切换模型。切换时界面会显示当前模型名方便你在同一个会话里对比不同模型的回答质量这个功能对于多模型对比太实用了。但是如果你的provider、key特别多手写JSON管理就吃力了。这就轮到ccswitch这类工具出场。ccswitch是一个配置切换工具它管理多个配置档每个档对应一套模型组合你可以在不同档之间快速切换。比如我建了两个档work档专用云厂商大模型local档专用本地模型切换时一条命令的事。配合opencode使用确实顺手尤其是你经常在不同客户项目之间切换、每个项目用的模型要求还不同的时候。环境变量也是个好帮手。opencode支持通过环境变量指定模型export OP_MODELdeepseek/deepseek-chat opencode优先级上环境变量高于配置文件适合在shell脚本里临时指定。3.4 关于免费模型的实话搜索热词里反复出现opencode免费模型我得说句泼冷水的话opencode本身不提供任何模型它只是个客户端。你所谓的免费通常来自三个方向本地开源模型、云厂商免费额度、社区公开渠道。前两个能用且稳社区渠道就不好说了。我还见过一些看起来配置很简单就能用的公共接口今天还能用、明天就下线把整个自动化流程卡死。真正想把opencode当生产工具我建议模型这块要么用本地模型扛底要么用正规云厂商的有偿服务别把根基建在沙子上。4. Skills与Memory让Agent记住项目、学会专业技能的运行机制4.1 AGENTS.md把项目规约写进Agent的潜意识opencode的Memory机制核心是一个叫AGENTS.md的文件放在项目根目录Agent启动后会自动读取它。凡是跟项目相关的常识性问题比如这门项目用什么技术栈测试命令是什么代码风格有什么约定部署流程分几步都写进这个文件里Agent干活的时候就会带着这些背景知识来思考不用你每次重复交代。写AGENTS.md有个关键技巧不要写成洋洋洒洒的README要当入职手册来写越具体越好。比如你写构建用Maven不如写构建命令是mvn clean package多模块项目需要先mvn install父模块再打包子模块。Agent看到前一种描述还要猜看到后一种描述就直接能跑。下面是我给一个Java项目写的简化版示例# AGENTS.md ## 项目技术栈 - Java 17 Spring Boot 3 - 前端 Vue 3 Vite - 构建工具 Maven ## 常用命令 - 启动后端mvn spring-boot:run - 跑单元测试mvn test - 打包mvn clean package -DskipTests ## 代码约定 - Service 层必须面向接口编程 - 所有对外接口返回统一 Result 包装对象 - 不要修改公共模块的 pom.xml 版本号全局级别的AGENTS.md放在~/.config/opencode/AGENTS.md里面放你对所有项目通用的偏好比如禁止在代码里写死密钥所有新增配置项要补充注释之类。4.2 Skills机制给Agent装上专业手册和小工具如果说AGENTS.md是让Agent记住事那Skills就是让Agent会干活。opencode采用了OpenAI Agent Skills的规范原理是在项目里建一个.skills目录每个技能一个子目录目录里必须有SKILL.md文件。这个文件用Markdown YAML frontmatter开头里面写清楚这个技能的触发条件、使用步骤、注意事项还可以放配套的脚本文件。举个例子我写了一个生成Git提交信息的技能--- name: git-commit-message description: 根据git diff内容生成符合Conventional Commits规范的提交信息 --- 当用户需要提交代码时按以下步骤操作 1. 执行 git diff --cached 查看暂存区内容 2. 分析改动类型feat/fix/docs/refactor 3. 用祈使句写summary不超过50字符 4. 如有必要添加body说明为什么做这个改动装上之后Agent遇到帮我把这些改动提交一下这种请求时就会自动加载这个技能按SKILL.md里定义的流程走最终产出信息和常规做法完全不同。最妙的是技能文件就在项目的.skills目录里任何人都能审阅和修改团队可以一起维护。4.3 社区技能包落地经验热词里那个superpowers频繁被提到它是一个开源的技能集合装好之后Agent会自动获得任务拆解能力接到复杂需求先列计划、拆步骤、写TODO清单然后一步步执行。我自己的体会是这个技能集合对于从聊天助手升级成项目执行者帮助很大。因为默认情况下模型接到一个复杂任务通常会急着直接生成结果有了任务拆解技能它会先想清楚要做什么、按什么顺序做再动手。安装方式其实很简单把对应的skills目录克隆到项目的.skills目录下或者利用opencode的配置把技能路径指过去即可。但要注意技能包里部分技能会比较激进比如自动安装依赖、自动修改全局配置这在你没看明白它要干什么之前是有风险的。我的建议是先让Agent告诉你它会执行哪些命令再决定是否放行。opencode支持确认交互把它开成高危操作需要确认模式比较稳妥。5. 用opencodePlaywright实测前端Bug从帮我看看到完整定位链路5.1 前端Bug为什么难修以及Playwright在这里的意义前端Bug是最折磨人的因为问题往往不在代码逻辑里而在浏览器运行时的状态里。某个组件渲染不出来、某个交互偶发报错、某个按钮点了没反应光看代码很难定位必须真实打开页面跑一遍。传统做法是自己启动前端服务、打开浏览器、手动点几下复现路径费时费力。opencode通过MCP协议接入Playwright之后Agent可以自己启动浏览器、导航到指定页面、点击元素、截图、读取控制台日志然后根据观察到的现象结合代码定位问题。这个能力强在哪它把复现和修复两个环节在同一个Agent线程里打通了。过去我要先手动复现把现象用自然语言描述给AIAI再找代码信息传递有损耗。现在Agent自己看页面、自己看控制台报错、自己比对代码整个过程是闭环的。5.2 实操链路从复现到修复我在一个Vue3项目里实测过一次完整的Bug定位。先启动前端开发服务器再打开opencode给它下了一个任务打开 http://localhost:5173点击首页的发布按钮复现页面上报的报错并定位到具体代码行。opencode会调用Playwright MCP工具启动无头浏览器访问页面找到发布按钮并点击。如果点击后页面有报错它会从控制台捕获异常堆栈再根据报错信息去项目代码里找对应组件和逻辑。整个过程它会像真人一样给你汇报当前打开的是什么页面、点击了哪个按钮、控制台捕获到了什么错误、怀疑是哪个文件的哪一行。你还可以让它把关键操作截图保存下来打开页面后对弹出的Modal框截图保存到 /tmp/issue-shot.png这样你不需要开着电脑盯它等它跑完回来看截图和日志就可以。对有视觉能力的多模态模型来说截图信息还能直接帮助定位样式和布局问题。5.3 实测中的翻车点与经验第一Playwright需要一个干净的浏览器环境。如果本地没装Chromium第一次调用会提示安装依赖。你可以单独装一下或者让opencode自动处理。某些服务器环境缺少系统依赖库报错信息类似failed to launch这时按提示安装系统级依赖即可别想着绕过去。第二Agent自己操作浏览器时对弹窗、登录态、随机数据这些场景容易犯迷糊。它打开页面时如果没有登录态所有交互都会失败它可能还意识不到是登录的问题。我的经验是在任务描述里把所有前置条件写清楚比如已通过mock账号登录无需处理登录流程。第三权限确认别关死。opencode在执行命令和修改文件时默认会有确认机制。在让它跑浏览器和改代码的混合任务里把确认级别设成高风险才确认效率和安全能兼顾。如果全放开它在改坏了文件后停下来问你你又得回滚反而更慢。6. 桌面版与VSCode/IDEA插件编辑器集成时最容易被忽略的两个设置6.1 终端、桌面版、IDE插件怎么选opencode的形态越来越多了除了终端TUI官方还推出了桌面版应用社区也做了VSCode插件和JetBrains IDEA插件。选型逻辑不复杂终端TUI适合专注命令行工作流的开发者桌面版适合想要一个独立窗口、减少终端切换的人IDE插件则适合希望AI补全和阅读代码都发生在编辑器里、不用切来切去的人。我的主力形态是终端 IDEA插件结合终端跑重活IDE里用插件做轻量问答互补。6.2 VSCode插件集成时要注意的发布渠道VSCode插件在应用市场里能搜到opencode官方插件确认作者和仓库指向官方渠道再装。早期有一些第三方同名插件功能和更新节奏都跟不上。装好之后插件会尝试连接本地的opencode服务如果你的PATH里没有opencode可执行文件插件会提示找不到。解决方法是插件设置里手动指定opencode可执行文件的绝对路径尤其macOS用户如果在终端里能跑但插件里跑不通几乎都是因为这个原因。6.3 IDEA里的Maven路径坑最容易踩的Java项目集成问题IDEA插件集成时热词里有个opencode mvn配置这个坑我在Java项目里确实踩过。IDEA插件启动opencode后Agent要执行Maven命令时会发现mvn命令不存在但你在Terminal窗口里明明能跑。原因很简单IDEA的GUI进程不会加载你在.bashrc或.zshrc里设置的PATH环境变量所以Agent拿不到Maven的路径。解法有两个。一个是在IDEA里设置全局环境变量把MAVEN_HOME和PATH补上Java的Maven其实只要有JAVA_HOME用完整路径调用/usr/local/maven/bin/mvn也行。另一个是直接在AGENTS.md里写清楚Maven的绝对路径Agent每次构建前都知道去哪里找命令## 构建命令 - 使用 mvn路径为 /usr/local/apache-maven-3.9.6/bin/mvn - 打包/usr/local/apache-maven-3.9.6/bin/mvn clean package把这种环境差异写进AGENTS.md算是奇招但确实管用。更彻底的做法是在IDEA插件设置里配置扩展PATH让插件启动的子进程继承你Terminal里的完整PATH这样mvn、java、node这些命令就全都能识别了。7. opencode、Codex、Claude Code、Pi放在一起我现在的实际分工7.1 四个工具的定位对比市面上现在最常被放在一起比较的四款终端AI编程工具我整理了一个表格方便你对照工具开源模型绑定技能系统浏览器自动化多模型切换适合人群opencode开源模型无关支持支持支持想自由接模型、喜欢折腾的人Claude Code闭源Anthropic部分支持有限不支持追求开箱即用、认可Claude效果的人Codex CLI闭源OpenAI初步支持有限基本不支持OpenAI生态重度用户Pi开源模型无关支持有限支持喜欢极简工具链、注重隐私的人这里说的Codex CLI是OpenAI出的命令行AgentPi是另外一款主打隐私的开源Agent这几个名字现在经常出现在同一批讨论里。看下来opencode最大的差异化优势就是模型无关和浏览器自动化的成熟度。其它几个也不差Claude Code在复杂代码理解上确实强Codex和OpenAI自家模型配合很顺但恰好它们的短板都在不能自由接模型上。7.2 我现在的日常分工经历一个月混用后我现在的实际分工是这样的主干开发任务比如写一个新的微服务、重构一个模块我用opencode接DeepSeek或者通义千问的旗舰模型效果能打token成本还低。代码评审任务我会切到本地Qwen2.5-Coder 32B来跑因为它主要做模式匹配和问题发现不太需要极其强的上下文能力跑本地成本为零。前端Bug复现和视觉类问题我固定用opencode Playwright这是其它工具目前替代不了的。一些极短小的脚本生成我会用轻量模型解决没必要每次都上最贵的。这里面有个很关键的细节因为opencode能在一个会话里随时切换模型我做先复现、再修复、最后写测试这种完整链路时可以让不同步骤用不同模型。这种工作方式在Claude Code里完全不可能实现也算是开源工具给的独有自由。7.3 如果只能留一个如果逼我只能留一个我的选择还是opencode。理由有两条。第一条是成本可控跨模型切换意味着我可以根据任务重要性动态调整花费不会出现一个简单脚本烧掉了大模型额度这种心疼时刻。第二条是它把Agent的能力和模型的能力解耦了技能系统和记忆系统都有文件沉淀换模型不换工作流今天用这个、明天换那个整个工作方式不会推倒重来。对一个把工具当生产力而非玩具的人来说这种稳定性比短期单个模型的效果更重要。最后分享一个小技巧opencode对话界面里输入/help能看到内置命令列表常用的/model直接切换当前会话模型/memory查看当前已加载的记忆文件/skills列出项目里可用的技能。我建议你装好后第一件事就把这几条命令背下来因为80%的配置问题都能在会话内自己看到答案不用反复翻文档。另外如果你的项目里有大量历史遗留代码想快速上手不要一上来就让它读全库先在AGENTS.md里把模块结构写给它再让它按模块逐个啃速度和准确度会明显提升。