前一阵子我把手头一个中型仓库的重构任务分给了三个终端AI Agent去做Claude Code、OpenAI Codex还有一个社区热度涨得很快的opencode。跑完一圈留给我最深印象的反而不是谁的成功率最高而是opencode的定制空间。它不像前两者那样是官方钦定的封闭工具而是把模型、能力、工作流全部拆开允许你自己拼装的一个终端编码代理。用了一段时间之后我决定把安装、配置、skills扩展、IDE接入和横向实测都整理一遍算是对这段折腾经历做一次完整归档。opencode是什么一句话一个开源的、运行在命令行里的、可以对接任意主流大模型并执行真实编码任务的AI代理。它能读你的项目、改你的代码、跑测试、提交commit甚至可以把Issue列表丢给它让它自己处理。适合谁用如果你已经在用Claude Code或者Codex想找一个更可控、更能按团队习惯定制的替代品如果你还没入坑想找一个免费模型也能跑起来的终端Agent作为起点opencode都很值得一试。这篇文章从安装开始一步步讲到配置、skills、IDE联动和实测对比全部基于我实际跑过的流程坑位和结论可以直接参考。1. opencode最核心的竞争力可拆卸的架构而不是开箱即用的神1.1 终端Agent到底在解决什么问题先说一个容易被忽略的前提终端里的AI编码Agent和你在IDE里用的补全插件完全是两个物种。补全插件是你写一句它接一句而Agent是你说一个目标它自己去读代码、规划步骤、改文件、执行命令、验证结果。这意味着它必须拥有对项目的整体理解能力也必须有一个足够灵活的执行框架——比如自主调用命令、并发处理多个文件、在出错后自己调整策略。Claude Code和Codex都是这个思路但它们都有一个共同点底层模型和工具链是绑死的。你用Claude Code基本上就是Claude系列模型你用Codex自然就是GPT系列。模型的选择权不在你手里。opencode做的事情是把模型和执行框架彻底解耦执行框架是它自己用Go写的模型则开放给你随便接。这听起来只是一个小改动实际用起来的差别非常大。1.2 一句opencode用Go写的意味着什么opencode的二进制是用Go编译的启动速度非常快。我印象里Claude Code冷启动经常要等一两秒opencode基本上是秒开。别小看这个差别你一天要开几十次Agent每次省下一秒钟体感是完全不同的。更重要的不是编译语言而是它的客户端/服务端分离架构。opencode的命令行界面只是一个客户端真正的任务执行跑在一个本地服务上。这个设计带来的好处是VSCode插件、JetBrains插件、桌面版本质上连接的都是同一个服务。也就是说你在终端里跑到一半的任务可以无缝切换到IDE插件里继续看日志你用桌面版开的会话也可以在终端里重新打开。这个一处执行、多处接入的能力是我后来把它纳入日常工作流的关键原因。下面这张表可以直观看出它和主流工具的区别维度opencodeClaude CodeOpenAI Codex是否开源是否否模型自由度任意Provider以Claude为主以GPT为主底层实现Go编译单二进制闭源闭源客户端/服务端分离是否否skills自定义支持支持有限有限免费模型接入方便不方便不方便当然这张表只反映我使用时的版本状态工具迭代很快但架构思路短期内不会变。2. 从零装到第一次对话安装方式和我踩过的PATH深坑2.1 三种安装方式按你的操作系统选opencode的安装方式在官方文档里写得很清楚我实际用过两种这里把三种都列出来# 方式一npm全局安装我最初用的方式适合前端/Node开发者 npm install -g opencode-ai # 方式二官方安装脚本适合macOS和Linux自动装到/usr/local/bin curl -fsSL https://opencode.ai/install | bash # 方式三HomebrewmacOS用户 brew install sst/tap/opencode装完之后终端里敲opencode --version能输出版本号就算成功。我在Linux服务器上用的是安装脚本在公司Mac上用的是npm两者都稳定。还有一点opencode桌面版是独立应用装好之后和命令行版共享配置这个放到后面IDE章节细说。2.2 Windows用户最常见的报错cmdlet识别不了搜索热词里有一条特别典型opencode: 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个错我在Windows机器上也遇到过根源几乎都是同一个npm的全局bin目录没有加进PATH。排查链路是这样的先在PowerShell里看npm全局目录装在哪npm prefix -g输出类似C:\Users\你的用户名\AppData\Roaming\npm。然后看看这个目录在不在环境变量的PATH里$env:Path -split ;肉眼扫一遍。如果不在用系统设置把C:\Users\你的用户名\AppData\Roaming\npm加进用户环境变量PATH然后重开一个PowerShell窗口。注意一定要重开终端因为PATH的读取发生在终端启动时。我见过好几个朋友改完环境变量不重开窗口然后跑来问我还是不行每次都哭笑不得。如果你是直接用安装脚本装的那opencode应该在%USERPROFILE%\.opencode\bin或者某个全局目录下同样检查一下这个目录是否在PATH里。另外Windows下我还遇到过一个隐蔽问题如果之前用旧版本装过一次新版装到了不同目录PATH里同时存在两个路径优先命中的是旧版。解决办法很简单把旧路径从PATH里删掉就行。2.3 跑通第一次对话的最小配置安装好之后第一次运行只需要做一件事告诉opencode用哪个模型的Key。最直接的方式是环境变量。我用Anthropic的时候设置ANTHROPIC_API_KEY用OpenAI的时候设置OPENAI_API_KEYopencode启动时会自动读取这些标准环境变量。如果你用的是OpenRouter这类聚合平台就设置该平台对应的Key环境变量。设置完执行# 交互式TUI模式适合日常开发 opencode # 非交互式一次性任务适合脚本和CI opencode run 读取src目录下的代码帮我找出所有未处理的Promise rejection第一次进入TUI之后底部有一个输入框直接打字就能和Agent对话。我建议第一个任务别选太复杂的让它读一下README并总结项目结构就好。这一步能确认三件事Key是否配置正确、模型是否能正常响应、Agent的基础文件读取能力是否正常。实测中如果这一步就报unexpected server error十有八九是Key填错了或者网络环境和模型服务之间不通跟opencode本身没关系。3. 模型接入是opencode的灵魂Provider、Model、Router怎么配3.1 先理解三层结构opencode的模型体系分三层理解这三层后面所有配置都会变得很顺Provider提供商Anthropic、OpenAI、Google、Ollama、OpenRouter等它定义了通过什么渠道访问模型。一个Provider就是一套API地址和认证信息的组合。Model模型具体到用哪个模型比如Claude Sonnet 4、GPT-5、Gemini 2.5 Pro、Llama 3.1。同一个Provider下面可以挂很多个Model。Router路由一个逻辑层帮你决定当前这个任务默认走哪个Provider的哪个Model。opencode里用model字段指定默认模型也支持按任务类型手动切换。我平时最常用的配置模式是把强模型和快模型都配好默认用性价比高的那个遇到复杂重构再手动切换。3.2 免费模型和付费模型怎么搭配搜索热词里opencode免费模型出现频率很高。坦率讲opencode本身没有内置免费模型它只是给了你接入免费模型的通道。目前我实测下来可行的免费或者几乎免费路线有这么几条Ollama本地模型完全免费断网也能跑。用ollama pull llama3.1拉一个8B模型然后在opencode配置里加一个Provider指向本地的http://localhost:11434。适合对隐私要求高、任务不太复杂的场景。OpenRouter上的免费额度模型OpenRouter会周期性地提供一些限额免费模型配置方式和普通OpenRouter模型一样把model字段指向免费模型ID即可。云厂商的新用户额度这个不算严格意义上的免费但新用户送的额度足够跑很久很多人忽略了。我的建议是日常小任务生成注释、写单测、分析报错可以走免费或便宜模型真正的大规模重构、跨文件改动不要省那点钱直接上Claude Opus或者GPT-5这个级别。省下的调试时间远远大于模型费用。我见过太多人为了省几分钱让弱模型改坏一堆文件然后再花半小时收拾残局得不偿失。配置文件的中心是opencode.json放在项目根目录或者~/.config/opencode/下都可以。一个典型的配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, theme: opencode, autoupdate: true, provider: { ollama: { api_key: ollama, base_url: http://localhost:11434 } } }注意model字段的写法是提供商/模型名这个斜杠前面的部分必须和Provider对上。我第一次配置的时候手滑写成了claude-sonnet-4结果opencode完全找不到对应Provider报错信息又不太直白卡了我十分钟。后来养成了习惯凡是和模型相关的配置先检查斜杠前缀。3.3 CC Switch这类工具是干什么的很多人问opencode要不要配合CC Switch。我的理解是CC Switch这类工具解决的是多个模型渠道的配置和切换问题。如果你只用一家API完全不需要如果你手上同时有Anthropic、OpenAI、本地Ollama、聚合平台等多个渠道手动改环境变量或配置文件就很烦用这类工具统一管理API Key和配置预设切换变成一次点击或一条命令效率高很多。我在团队里推荐的做法是把CC Switch的配置项指向opencode把常用的模型组合存成几套预设比如日常编码、深度重构、低成本批量任务。需要切换时直接切预设不需要碰配置文件。但这句话的前提是——你确实有多个渠道需要切换。如果只有一把Key装CC Switch属于自找麻烦没必要跟风。4. skills与memory把团队的干活方式教给Agent4.1 skills到底是什么能解决什么问题这是opencode最让我喜欢的地方。终端Agent默认是一个通用程序员它知道怎么写代码但它不知道你团队的规范你们用什么目录结构、commit信息怎么写、测试文件放哪里、代码风格要求什么。skill就是用来填这个空白的。一个skill本质上是一组指令加可选工具的组合把它丢进opencode的skills目录后Agent在相关场景下会自动加载并使用。我在项目里写过几个很管用的skill代码审查skill规定Agent必须按安全性、性能、可读性、测试覆盖四个维度输出审查报告并且只在diff范围内提意见不许借题发挥。测试生成skill规定Agent在生成测试时必须遵循项目的测试命名规范并且新测试必须先跑一遍确认能失败TDD的红灯阶段再写实现。commit信息skill要求Agent使用Conventional Commits规范且body部分必须写清楚为什么改而不是只写改了什么。实际效果很明显。没有skill的时候Agent生成的commit信息五花八门review代码时经常会提一些和本次改动无关的建议测试命名风格也飘忽不定。加了skill之后基本一次成型。配置方式很简单在opencode配置目录建一个skills文件夹里面每个子文件夹就是一个skill~/.config/opencode/skills/ ├── code-review/ │ ├── SKILL.md │ └── tools.ts ├── generate-tests/ │ └── SKILL.md └── conventional-commit/ └── SKILL.mdSKILL.md里就是普通的Markdown写清楚这个skill的触发条件、执行步骤、必须遵守的规则。opencode会在Agent执行任务时自动判断是否加载。社区里也有一些现成的skill集合比如Superpowers就提供一整套覆盖编码、调试、规划等场景的skills你可以直接clone下来裁减着用不需要从零开始。oh-my-claudecode其实也是类似的思路——把一套好用的配置和技能包放到一个仓库里让大家开箱即用只是它最早是围绕Claude Code生态做的原理和opencode的skills完全互通。4.2 memory长任务和跨会话的记忆从哪来opencode的会话session是持久化的。你每次退出再进入可以恢复到之前的会话Agent对项目的上下文理解也基本保留。这个机制在处理长任务时非常关键。我处理一个跨三天的重构任务时就是靠会话恢复每天结束前把当前进度、下一步计划写进会话第二天直接继续Agent不需要重新读一遍全项目。但需要注意的是恢复会话不等于拥有无限上下文。模型上下文窗口是有限的会话太长之后早期的对话内容会被裁剪或压缩这会导致Agent忘记一些细节。我的经验是一个会话聚焦一个任务任务完成就开新会话。如果任务很大就拆成多个小任务串行推进每个任务都有明确的产出这样既避免上下文污染也方便回溯。4.3 实测用Playwright让opencode自己测前端Bug搜索热词里有一条opencode playwright怎么测试前端bug这个我确实实操过而且效果超出预期。背景是我一个前端项目里有个复现率不高但确实存在的交互Bug用户在特定操作序列下弹窗会闪烁两次。这类Bug靠肉眼手工复现很费时间让Agent纯读代码也很难定位因为问题出在交互时序上。我的做法是给opencode写了一个skill里面配置了Playwright工具。任务描述很简单使用Playwright打开本地开发服务器按这个操作序列执行记录弹窗出现次数定位闪烁原因。opencode自己完成了下面这些步骤启动本地dev server。用Playwright的脚本写一个测试用例模拟点击操作序列。跑测试并把失败输出拿回来看。根据输出定位到是某个状态更新触发了两次渲染修复后重新跑测试验证。整个过程中我唯一手动做的事情是描述问题和按回车。这个案例让我意识到opencode的skills不只是改改代码风格那么轻量它完全可以驱动真实的外部工具进行端到端的验证相当于给Agent装上了眼睛和手。前端Bug如果能在Agent侧自动复现调试效率会提升一个量级。5. 从终端到IDEVSCode、JetBrains插件和桌面版的实际体验5.1 VSCode插件什么时候值得装opencode的VSCode插件解决的是看代码场景和写代码场景之间的割裂。终端TUI再好你总要回到编辑器里看代码、改代码。VSCode插件把Agent的会话嵌入编辑器侧边栏选中代码直接发给Agent它的回复里带文件差异时可以一键预览和采纳不用来回切窗口。我的使用习惯是终端里启动一个长时间运行的Agent任务编辑器里用插件查看和筛选它的改动。两个端连接的是同一个服务所以状态完全同步。如果你主要工作在JetBrains系IDEA、PyCharm、GoLand它们家的插件思路也类似但成熟度比VSCode插件稍晚一些安装前最好看一下版本更新时间。有一点要提醒IDE插件本质上是客户端它的能力取决于本地服务端也就是命令行版opencode的版本。如果你在IDE插件里发现某个功能不生效先升级命令行版多半能解决。5.2 桌面版和2.0带来的变化opencode桌面版我之前印象中一直是预告状态后来正式推出来之后我第一时间试了。它的定位不是替代TUI而是给不太习惯命令行的同学一个图形入口同时把会话管理、模型切换、配置编辑这些操作可视化。打开桌面版左侧是历史会话列表中间是对话主区右侧是当前会话的文件改动列表信息密度设计得不错。至于opencode 2.0最大的变化我认为在于Agent的自主程度和多任务并发能力。1.x时代一个Agent一次只能聚焦一件事2.0之后Agent能拆分子任务并在合适的时候并行处理整个执行节奏更接近一个真实开发者的工作方式。当然并行也意味着对模型的推理质量要求更高配合Claude Sonnet 4这个级别的模型体验最佳用太弱的模型并行只会制造混乱。5.3 Maven这类构建工具的接入怎么配搜索热词里的opencode mvn配置其实问的是同一个问题怎么让Agent在Java/Maven项目里正确执行构建命令。opencode本身不关心你的构建工具它就是执行终端命令关键是配置好Agent能用的命令白名单和工作目录。我在一个Java服务项目里的配置要点是确保mvn在PATH里且版本兼容给Agent明确的构建指令比如用mvn -q -DskipTests compile编译用mvn test跑测试如果项目有多个module需要在skill里写清楚root module的位置和依赖顺序否则Agent可能在错误的目录执行mvn导致失败然后陷入一个反复试错但思路错误的循环。另外Java项目的编译输出和错误信息通常很啰嗦我建议在skill里让Agent优先看日志里的[ERROR]行不要被大量警告信息带偏。这个细节看起来很小实测能显著减少Agent的无效思考。6. 四个主流Agent的横向实测opencode vs Codex vs Claude Code vs Cline6.1 我的实测方法和结果为了写这篇总结我拿同一个测试项目跑了四个工具opencode、OpenAI Codex、Claude Code和社区常用的ClineVSCode插件。项目是一个约2000行的Node.js服务包含文件上传、鉴权、数据库操作三个模块。任务有三个任务A修复一个鉴权漏洞任务B把文件上传逻辑从同步改为流式处理任务C给数据库操作层补齐单元测试。每个任务我都限定了30分钟测试指标看三点是否完成任务、完成质量代码评审打分、过程中需要我人工干预的次数。工具任务A任务B任务C人工干预次数opencodeSonnet 4完成完成完成2Claude Code完成完成基本完成1Codex完成部分完成完成4ClineGPT-4o部分完成未完成完成6这个结果仅供参考因为影响变量太多模型版本、prompt质量、环境状态但和我个人累计几个月的使用感受是一致的Claude Code在同模型下完成度最高opencode紧随其后但胜在可定制和可接入性Codex在简单任务上很快遇到需要多步骤探索的任务就容易跑偏Cline在IDE里看代码方便但长任务的自主能力偏弱。6.2 我最终为什么把opencode当主力这个问题我在很多社区帖子里也回答过。如果把完成任务的能力作为唯一指标Claude Code可能略胜一筹但把能不能按我的方式来干活作为指标opencode甩开其他工具一大截。我团队里的实际场景是不同成员习惯用不同模型有的人偏爱Claude的代码质量有的人觉得GPT的快模型更适合快速迭代。Claude Code绑死了模型没法满足团队多样性需求opencode则允许每个人配自己的默认模型但共享同一套skills和配置。再加上它开源、可审计、本地数据完全可控对于在意代码安全和团队规范的公司来说这几点都是加分项。选型建议一句话单兵作战、追求开箱即用Claude Code不会让你失望团队协作、需要模型自由和深度定制opencode是更合理的选择。7. 长期使用下来的几点提醒长会话、权限和团队协作7.1 长会话变慢是必然的学会及时开新会话我前面提过上下文窗口的局限这里再展开一点。opencode的会话里Agent会自动把关键信息写入一个上下文压缩摘要以便后续继续使用。摘要机制在会话前半段很好用但任务复杂、文件很多时摘要可能会丢失一些关键细节。我的判断标准是如果Agent开始出现明明刚改过某个文件却问你这个文件存不存在这类失忆症状就该开新会话了。新会话里重新描述任务顺便把上一个会话的核心结论贴进去效果通常比硬撑着继续好得多。7.2 权限控制别嫌麻烦opencode默认可以执行命令、修改文件这既是它强大的原因也是风险所在。我见过有人在一次Agent误操作中把整个dist目录删了原因是prompt里没有明确禁止Agent把清理构建产物理解成了删除dist。从那以后我在所有项目的skill顶部都会加一条规则删除操作必须经过用户确认任何影响范围超出当前任务的命令先停下来询问。opencode的命令执行前确认机制可以打开虽然每次多点一下确认确实麻烦但和意外删除代码相比这点麻烦非常值得。7.3 团队共享配置的最佳姿势如果你打算把opencode引入团队我强烈建议把配置文件、skills目录放到Git仓库里管理项目成员clone之后只需要自己做两步安装opencode、填入自己的API Key。模型是私人的规范是共享的——这个边界要明确。API Key永远不要提交进仓库我是见过有人把Key硬编码在opencode.json里然后推上GitHub的第二天Key就被别人刷爆了账单。最后再分享一个小技巧我习惯在项目根目录放一个AGENTS.md之类的说明文件让Agent在新会话开始时自动读取里面写清楚项目架构、常用命令、编码规范。这比在每次对话时口述效率高得多配合skills使用几乎可以把一个新来的Agent训练成熟悉这个项目的老员工。这一步做完opencode在你手里就不再是一个好用的工具而是一个完全属于你团队的数字工程师。 opencode终端AI Agent实战：安装配置、Skills扩展与四大工具对比
前一阵子我把手头一个中型仓库的重构任务分给了三个终端AI Agent去做Claude Code、OpenAI Codex还有一个社区热度涨得很快的opencode。跑完一圈留给我最深印象的反而不是谁的成功率最高而是opencode的定制空间。它不像前两者那样是官方钦定的封闭工具而是把模型、能力、工作流全部拆开允许你自己拼装的一个终端编码代理。用了一段时间之后我决定把安装、配置、skills扩展、IDE接入和横向实测都整理一遍算是对这段折腾经历做一次完整归档。opencode是什么一句话一个开源的、运行在命令行里的、可以对接任意主流大模型并执行真实编码任务的AI代理。它能读你的项目、改你的代码、跑测试、提交commit甚至可以把Issue列表丢给它让它自己处理。适合谁用如果你已经在用Claude Code或者Codex想找一个更可控、更能按团队习惯定制的替代品如果你还没入坑想找一个免费模型也能跑起来的终端Agent作为起点opencode都很值得一试。这篇文章从安装开始一步步讲到配置、skills、IDE联动和实测对比全部基于我实际跑过的流程坑位和结论可以直接参考。1. opencode最核心的竞争力可拆卸的架构而不是开箱即用的神1.1 终端Agent到底在解决什么问题先说一个容易被忽略的前提终端里的AI编码Agent和你在IDE里用的补全插件完全是两个物种。补全插件是你写一句它接一句而Agent是你说一个目标它自己去读代码、规划步骤、改文件、执行命令、验证结果。这意味着它必须拥有对项目的整体理解能力也必须有一个足够灵活的执行框架——比如自主调用命令、并发处理多个文件、在出错后自己调整策略。Claude Code和Codex都是这个思路但它们都有一个共同点底层模型和工具链是绑死的。你用Claude Code基本上就是Claude系列模型你用Codex自然就是GPT系列。模型的选择权不在你手里。opencode做的事情是把模型和执行框架彻底解耦执行框架是它自己用Go写的模型则开放给你随便接。这听起来只是一个小改动实际用起来的差别非常大。1.2 一句opencode用Go写的意味着什么opencode的二进制是用Go编译的启动速度非常快。我印象里Claude Code冷启动经常要等一两秒opencode基本上是秒开。别小看这个差别你一天要开几十次Agent每次省下一秒钟体感是完全不同的。更重要的不是编译语言而是它的客户端/服务端分离架构。opencode的命令行界面只是一个客户端真正的任务执行跑在一个本地服务上。这个设计带来的好处是VSCode插件、JetBrains插件、桌面版本质上连接的都是同一个服务。也就是说你在终端里跑到一半的任务可以无缝切换到IDE插件里继续看日志你用桌面版开的会话也可以在终端里重新打开。这个一处执行、多处接入的能力是我后来把它纳入日常工作流的关键原因。下面这张表可以直观看出它和主流工具的区别维度opencodeClaude CodeOpenAI Codex是否开源是否否模型自由度任意Provider以Claude为主以GPT为主底层实现Go编译单二进制闭源闭源客户端/服务端分离是否否skills自定义支持支持有限有限免费模型接入方便不方便不方便当然这张表只反映我使用时的版本状态工具迭代很快但架构思路短期内不会变。2. 从零装到第一次对话安装方式和我踩过的PATH深坑2.1 三种安装方式按你的操作系统选opencode的安装方式在官方文档里写得很清楚我实际用过两种这里把三种都列出来# 方式一npm全局安装我最初用的方式适合前端/Node开发者 npm install -g opencode-ai # 方式二官方安装脚本适合macOS和Linux自动装到/usr/local/bin curl -fsSL https://opencode.ai/install | bash # 方式三HomebrewmacOS用户 brew install sst/tap/opencode装完之后终端里敲opencode --version能输出版本号就算成功。我在Linux服务器上用的是安装脚本在公司Mac上用的是npm两者都稳定。还有一点opencode桌面版是独立应用装好之后和命令行版共享配置这个放到后面IDE章节细说。2.2 Windows用户最常见的报错cmdlet识别不了搜索热词里有一条特别典型opencode: 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个错我在Windows机器上也遇到过根源几乎都是同一个npm的全局bin目录没有加进PATH。排查链路是这样的先在PowerShell里看npm全局目录装在哪npm prefix -g输出类似C:\Users\你的用户名\AppData\Roaming\npm。然后看看这个目录在不在环境变量的PATH里$env:Path -split ;肉眼扫一遍。如果不在用系统设置把C:\Users\你的用户名\AppData\Roaming\npm加进用户环境变量PATH然后重开一个PowerShell窗口。注意一定要重开终端因为PATH的读取发生在终端启动时。我见过好几个朋友改完环境变量不重开窗口然后跑来问我还是不行每次都哭笑不得。如果你是直接用安装脚本装的那opencode应该在%USERPROFILE%\.opencode\bin或者某个全局目录下同样检查一下这个目录是否在PATH里。另外Windows下我还遇到过一个隐蔽问题如果之前用旧版本装过一次新版装到了不同目录PATH里同时存在两个路径优先命中的是旧版。解决办法很简单把旧路径从PATH里删掉就行。2.3 跑通第一次对话的最小配置安装好之后第一次运行只需要做一件事告诉opencode用哪个模型的Key。最直接的方式是环境变量。我用Anthropic的时候设置ANTHROPIC_API_KEY用OpenAI的时候设置OPENAI_API_KEYopencode启动时会自动读取这些标准环境变量。如果你用的是OpenRouter这类聚合平台就设置该平台对应的Key环境变量。设置完执行# 交互式TUI模式适合日常开发 opencode # 非交互式一次性任务适合脚本和CI opencode run 读取src目录下的代码帮我找出所有未处理的Promise rejection第一次进入TUI之后底部有一个输入框直接打字就能和Agent对话。我建议第一个任务别选太复杂的让它读一下README并总结项目结构就好。这一步能确认三件事Key是否配置正确、模型是否能正常响应、Agent的基础文件读取能力是否正常。实测中如果这一步就报unexpected server error十有八九是Key填错了或者网络环境和模型服务之间不通跟opencode本身没关系。3. 模型接入是opencode的灵魂Provider、Model、Router怎么配3.1 先理解三层结构opencode的模型体系分三层理解这三层后面所有配置都会变得很顺Provider提供商Anthropic、OpenAI、Google、Ollama、OpenRouter等它定义了通过什么渠道访问模型。一个Provider就是一套API地址和认证信息的组合。Model模型具体到用哪个模型比如Claude Sonnet 4、GPT-5、Gemini 2.5 Pro、Llama 3.1。同一个Provider下面可以挂很多个Model。Router路由一个逻辑层帮你决定当前这个任务默认走哪个Provider的哪个Model。opencode里用model字段指定默认模型也支持按任务类型手动切换。我平时最常用的配置模式是把强模型和快模型都配好默认用性价比高的那个遇到复杂重构再手动切换。3.2 免费模型和付费模型怎么搭配搜索热词里opencode免费模型出现频率很高。坦率讲opencode本身没有内置免费模型它只是给了你接入免费模型的通道。目前我实测下来可行的免费或者几乎免费路线有这么几条Ollama本地模型完全免费断网也能跑。用ollama pull llama3.1拉一个8B模型然后在opencode配置里加一个Provider指向本地的http://localhost:11434。适合对隐私要求高、任务不太复杂的场景。OpenRouter上的免费额度模型OpenRouter会周期性地提供一些限额免费模型配置方式和普通OpenRouter模型一样把model字段指向免费模型ID即可。云厂商的新用户额度这个不算严格意义上的免费但新用户送的额度足够跑很久很多人忽略了。我的建议是日常小任务生成注释、写单测、分析报错可以走免费或便宜模型真正的大规模重构、跨文件改动不要省那点钱直接上Claude Opus或者GPT-5这个级别。省下的调试时间远远大于模型费用。我见过太多人为了省几分钱让弱模型改坏一堆文件然后再花半小时收拾残局得不偿失。配置文件的中心是opencode.json放在项目根目录或者~/.config/opencode/下都可以。一个典型的配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, theme: opencode, autoupdate: true, provider: { ollama: { api_key: ollama, base_url: http://localhost:11434 } } }注意model字段的写法是提供商/模型名这个斜杠前面的部分必须和Provider对上。我第一次配置的时候手滑写成了claude-sonnet-4结果opencode完全找不到对应Provider报错信息又不太直白卡了我十分钟。后来养成了习惯凡是和模型相关的配置先检查斜杠前缀。3.3 CC Switch这类工具是干什么的很多人问opencode要不要配合CC Switch。我的理解是CC Switch这类工具解决的是多个模型渠道的配置和切换问题。如果你只用一家API完全不需要如果你手上同时有Anthropic、OpenAI、本地Ollama、聚合平台等多个渠道手动改环境变量或配置文件就很烦用这类工具统一管理API Key和配置预设切换变成一次点击或一条命令效率高很多。我在团队里推荐的做法是把CC Switch的配置项指向opencode把常用的模型组合存成几套预设比如日常编码、深度重构、低成本批量任务。需要切换时直接切预设不需要碰配置文件。但这句话的前提是——你确实有多个渠道需要切换。如果只有一把Key装CC Switch属于自找麻烦没必要跟风。4. skills与memory把团队的干活方式教给Agent4.1 skills到底是什么能解决什么问题这是opencode最让我喜欢的地方。终端Agent默认是一个通用程序员它知道怎么写代码但它不知道你团队的规范你们用什么目录结构、commit信息怎么写、测试文件放哪里、代码风格要求什么。skill就是用来填这个空白的。一个skill本质上是一组指令加可选工具的组合把它丢进opencode的skills目录后Agent在相关场景下会自动加载并使用。我在项目里写过几个很管用的skill代码审查skill规定Agent必须按安全性、性能、可读性、测试覆盖四个维度输出审查报告并且只在diff范围内提意见不许借题发挥。测试生成skill规定Agent在生成测试时必须遵循项目的测试命名规范并且新测试必须先跑一遍确认能失败TDD的红灯阶段再写实现。commit信息skill要求Agent使用Conventional Commits规范且body部分必须写清楚为什么改而不是只写改了什么。实际效果很明显。没有skill的时候Agent生成的commit信息五花八门review代码时经常会提一些和本次改动无关的建议测试命名风格也飘忽不定。加了skill之后基本一次成型。配置方式很简单在opencode配置目录建一个skills文件夹里面每个子文件夹就是一个skill~/.config/opencode/skills/ ├── code-review/ │ ├── SKILL.md │ └── tools.ts ├── generate-tests/ │ └── SKILL.md └── conventional-commit/ └── SKILL.mdSKILL.md里就是普通的Markdown写清楚这个skill的触发条件、执行步骤、必须遵守的规则。opencode会在Agent执行任务时自动判断是否加载。社区里也有一些现成的skill集合比如Superpowers就提供一整套覆盖编码、调试、规划等场景的skills你可以直接clone下来裁减着用不需要从零开始。oh-my-claudecode其实也是类似的思路——把一套好用的配置和技能包放到一个仓库里让大家开箱即用只是它最早是围绕Claude Code生态做的原理和opencode的skills完全互通。4.2 memory长任务和跨会话的记忆从哪来opencode的会话session是持久化的。你每次退出再进入可以恢复到之前的会话Agent对项目的上下文理解也基本保留。这个机制在处理长任务时非常关键。我处理一个跨三天的重构任务时就是靠会话恢复每天结束前把当前进度、下一步计划写进会话第二天直接继续Agent不需要重新读一遍全项目。但需要注意的是恢复会话不等于拥有无限上下文。模型上下文窗口是有限的会话太长之后早期的对话内容会被裁剪或压缩这会导致Agent忘记一些细节。我的经验是一个会话聚焦一个任务任务完成就开新会话。如果任务很大就拆成多个小任务串行推进每个任务都有明确的产出这样既避免上下文污染也方便回溯。4.3 实测用Playwright让opencode自己测前端Bug搜索热词里有一条opencode playwright怎么测试前端bug这个我确实实操过而且效果超出预期。背景是我一个前端项目里有个复现率不高但确实存在的交互Bug用户在特定操作序列下弹窗会闪烁两次。这类Bug靠肉眼手工复现很费时间让Agent纯读代码也很难定位因为问题出在交互时序上。我的做法是给opencode写了一个skill里面配置了Playwright工具。任务描述很简单使用Playwright打开本地开发服务器按这个操作序列执行记录弹窗出现次数定位闪烁原因。opencode自己完成了下面这些步骤启动本地dev server。用Playwright的脚本写一个测试用例模拟点击操作序列。跑测试并把失败输出拿回来看。根据输出定位到是某个状态更新触发了两次渲染修复后重新跑测试验证。整个过程中我唯一手动做的事情是描述问题和按回车。这个案例让我意识到opencode的skills不只是改改代码风格那么轻量它完全可以驱动真实的外部工具进行端到端的验证相当于给Agent装上了眼睛和手。前端Bug如果能在Agent侧自动复现调试效率会提升一个量级。5. 从终端到IDEVSCode、JetBrains插件和桌面版的实际体验5.1 VSCode插件什么时候值得装opencode的VSCode插件解决的是看代码场景和写代码场景之间的割裂。终端TUI再好你总要回到编辑器里看代码、改代码。VSCode插件把Agent的会话嵌入编辑器侧边栏选中代码直接发给Agent它的回复里带文件差异时可以一键预览和采纳不用来回切窗口。我的使用习惯是终端里启动一个长时间运行的Agent任务编辑器里用插件查看和筛选它的改动。两个端连接的是同一个服务所以状态完全同步。如果你主要工作在JetBrains系IDEA、PyCharm、GoLand它们家的插件思路也类似但成熟度比VSCode插件稍晚一些安装前最好看一下版本更新时间。有一点要提醒IDE插件本质上是客户端它的能力取决于本地服务端也就是命令行版opencode的版本。如果你在IDE插件里发现某个功能不生效先升级命令行版多半能解决。5.2 桌面版和2.0带来的变化opencode桌面版我之前印象中一直是预告状态后来正式推出来之后我第一时间试了。它的定位不是替代TUI而是给不太习惯命令行的同学一个图形入口同时把会话管理、模型切换、配置编辑这些操作可视化。打开桌面版左侧是历史会话列表中间是对话主区右侧是当前会话的文件改动列表信息密度设计得不错。至于opencode 2.0最大的变化我认为在于Agent的自主程度和多任务并发能力。1.x时代一个Agent一次只能聚焦一件事2.0之后Agent能拆分子任务并在合适的时候并行处理整个执行节奏更接近一个真实开发者的工作方式。当然并行也意味着对模型的推理质量要求更高配合Claude Sonnet 4这个级别的模型体验最佳用太弱的模型并行只会制造混乱。5.3 Maven这类构建工具的接入怎么配搜索热词里的opencode mvn配置其实问的是同一个问题怎么让Agent在Java/Maven项目里正确执行构建命令。opencode本身不关心你的构建工具它就是执行终端命令关键是配置好Agent能用的命令白名单和工作目录。我在一个Java服务项目里的配置要点是确保mvn在PATH里且版本兼容给Agent明确的构建指令比如用mvn -q -DskipTests compile编译用mvn test跑测试如果项目有多个module需要在skill里写清楚root module的位置和依赖顺序否则Agent可能在错误的目录执行mvn导致失败然后陷入一个反复试错但思路错误的循环。另外Java项目的编译输出和错误信息通常很啰嗦我建议在skill里让Agent优先看日志里的[ERROR]行不要被大量警告信息带偏。这个细节看起来很小实测能显著减少Agent的无效思考。6. 四个主流Agent的横向实测opencode vs Codex vs Claude Code vs Cline6.1 我的实测方法和结果为了写这篇总结我拿同一个测试项目跑了四个工具opencode、OpenAI Codex、Claude Code和社区常用的ClineVSCode插件。项目是一个约2000行的Node.js服务包含文件上传、鉴权、数据库操作三个模块。任务有三个任务A修复一个鉴权漏洞任务B把文件上传逻辑从同步改为流式处理任务C给数据库操作层补齐单元测试。每个任务我都限定了30分钟测试指标看三点是否完成任务、完成质量代码评审打分、过程中需要我人工干预的次数。工具任务A任务B任务C人工干预次数opencodeSonnet 4完成完成完成2Claude Code完成完成基本完成1Codex完成部分完成完成4ClineGPT-4o部分完成未完成完成6这个结果仅供参考因为影响变量太多模型版本、prompt质量、环境状态但和我个人累计几个月的使用感受是一致的Claude Code在同模型下完成度最高opencode紧随其后但胜在可定制和可接入性Codex在简单任务上很快遇到需要多步骤探索的任务就容易跑偏Cline在IDE里看代码方便但长任务的自主能力偏弱。6.2 我最终为什么把opencode当主力这个问题我在很多社区帖子里也回答过。如果把完成任务的能力作为唯一指标Claude Code可能略胜一筹但把能不能按我的方式来干活作为指标opencode甩开其他工具一大截。我团队里的实际场景是不同成员习惯用不同模型有的人偏爱Claude的代码质量有的人觉得GPT的快模型更适合快速迭代。Claude Code绑死了模型没法满足团队多样性需求opencode则允许每个人配自己的默认模型但共享同一套skills和配置。再加上它开源、可审计、本地数据完全可控对于在意代码安全和团队规范的公司来说这几点都是加分项。选型建议一句话单兵作战、追求开箱即用Claude Code不会让你失望团队协作、需要模型自由和深度定制opencode是更合理的选择。7. 长期使用下来的几点提醒长会话、权限和团队协作7.1 长会话变慢是必然的学会及时开新会话我前面提过上下文窗口的局限这里再展开一点。opencode的会话里Agent会自动把关键信息写入一个上下文压缩摘要以便后续继续使用。摘要机制在会话前半段很好用但任务复杂、文件很多时摘要可能会丢失一些关键细节。我的判断标准是如果Agent开始出现明明刚改过某个文件却问你这个文件存不存在这类失忆症状就该开新会话了。新会话里重新描述任务顺便把上一个会话的核心结论贴进去效果通常比硬撑着继续好得多。7.2 权限控制别嫌麻烦opencode默认可以执行命令、修改文件这既是它强大的原因也是风险所在。我见过有人在一次Agent误操作中把整个dist目录删了原因是prompt里没有明确禁止Agent把清理构建产物理解成了删除dist。从那以后我在所有项目的skill顶部都会加一条规则删除操作必须经过用户确认任何影响范围超出当前任务的命令先停下来询问。opencode的命令执行前确认机制可以打开虽然每次多点一下确认确实麻烦但和意外删除代码相比这点麻烦非常值得。7.3 团队共享配置的最佳姿势如果你打算把opencode引入团队我强烈建议把配置文件、skills目录放到Git仓库里管理项目成员clone之后只需要自己做两步安装opencode、填入自己的API Key。模型是私人的规范是共享的——这个边界要明确。API Key永远不要提交进仓库我是见过有人把Key硬编码在opencode.json里然后推上GitHub的第二天Key就被别人刷爆了账单。最后再分享一个小技巧我习惯在项目根目录放一个AGENTS.md之类的说明文件让Agent在新会话开始时自动读取里面写清楚项目架构、常用命令、编码规范。这比在每次对话时口述效率高得多配合skills使用几乎可以把一个新来的Agent训练成熟悉这个项目的老员工。这一步做完opencode在你手里就不再是一个好用的工具而是一个完全属于你团队的数字工程师。