1. 先把opencode放在正确的位置上它到底是个什么东西1.1 从终端里长出来的AI编程代理第一次听说opencode的时候我其实有点麻木了毕竟这两年AI编程工具出来一个接一个从最早的GitHub Copilot到后来的Cursor再到Claude Code和Codex CLI我几乎都试过一遍。但opencode给我的第一印象不太一样它不是一个挂在编辑器侧边栏的补全插件也不是一个只能聊天的对话框而是一个真正跑在终端里的AI编程代理agent你给它一个任务它会自己读代码、查文档、改文件、跑命令甚至自己调试。简单说opencode是一个开源的、命令行优先的AI编程助手。它最大的特点是代理式工作流不是等你逐行敲代码再给你补全而是你提一个需求比如帮我把登录接口的超时时间改成可配置项它会自己定位到相关文件、分析上下游调用、修改代码并给出测试建议。整个过程在终端里完成轻量、直接、可脚本化这种体验和传统IDE里的AI插件完全不同。1.2 聊一聊opencode与传统AI补全工具的差别很多人一听到AI编程工具第一反应就是是不是又一个Copilot。真不是一回事。补全工具的核心逻辑是你写一句它接一句解决的是局部效率问题而opencode这类代理工具解决的是整个任务怎么落地的问题。举个例子我用Copilot的时候写一个函数它能把函数体补完但如果让它把这个模块的重试逻辑统一抽出来它就抓瞎了。而opencode可以自己浏览项目结构、理解现有代码风格、找到所有涉及重试的位置、设计抽取方案、逐个修改文件最后还能跑一遍测试确认没有破坏现有功能。这种从需求到落地的闭环能力才是代理式工具的价值所在。另外opencode是终端工具这意味着它比IDE插件更灵活。你可以把它接到任何编辑器里用也可以在CI脚本里调用甚至可以通过SSH远程操作服务器上的代码。这种脱离IDE束缚的设计让很多习惯Vim和Emacs的老派开发者也能顺畅上手。1.3 谁最适合用opencode从我个人的使用经验来看下面这几类人最能从opencode里拿到实际收益需要频繁接手陌生项目的开发者。opencode读代码的能力相当强你让它先梳理项目结构和核心模块比人肉翻代码快得多。做全栈开发的独立开发者。一个人要兼顾前端、后端、脚本、部署opencode能帮你快速处理那些写着没意思但不得不做的胶水代码。喜欢命令行工作流、不喜欢被IDE绑架的工程师。想在自有代码库上做自动化改造、批量重构的技术负责人。反过来如果你是刚学编程没多久的新手我建议还是先把基础打牢。opencode生成代码的能力很强但代码评审、需求拆解、风险判断这些能力还是得靠人。工具再好不能替代你自己的判断力。提示opencode适合知道自己要什么的人它能帮你快速执行但决策还得自己做。2. 安装与初始配置把opencode跑起来2.1 安装前需要准备什么opencode本质上是一个基于Node.js的命令行工具所以安装前你的机器上需要准备好Node.js环境。我建议安装Node.js 18以上版本太老的版本跑不起来。另外opencode自身不包含AI模型它需要对接大语言模型的API。目前市面上主流的模型服务商都可以接OpenAI的GPT系列、Anthropic的Claude系列、Google的Gemini系列以及一些国产模型都在支持范围内。你需要准备好对应的API Key。有一个容易踩的坑是网络环境。opencode调用模型API走的是HTTPS标准端口如果你的机器有代理设置注意别让终端代理和API请求打架不然会报各种莫名其妙的连接错误。2.2 安装opencode的几种方式opencode的安装方式有好几种我按推荐度排个序第一种通过npm全局安装这也是最常规的方式npm install -g opencode-ai装完以后直接敲opencode --version验证是否成功。第二种通过Homebrew安装适合macOS用户brew install opencode第三种下载预编译的二进制包适合不想装Node.js环境、或者需要在CI里快速集成的场景。直接去opencode的GitHub Releases页面下载对应平台的可执行文件放到PATH目录里就行。这里要特别提醒一下如果你在Windows上安装装完后打开一个新的终端窗口再执行命令。因为npm安装的全局命令路径不会实时刷新到当前会话的PATH变量里很多人明明装成功了但一执行就提示无法识别命令其实是没开新终端。2.3 模型接入与免费模型选择安装完成之后第一步要配置模型服务商。opencode支持多种模型提供商配置方式很灵活既可以通过环境变量也可以在配置文件里指定。以最常用的OpenAI兼容接口为例export OPENAI_API_KEY你的key或者在配置文件~/.config/opencode/config.json里写入{ provider: openai, model: gpt-4o, apiKey: 你的key }关于免费模型很多刚开始接触opencode的朋友会问。市面上确实有一些提供免费额度的模型服务商比如某些开源模型的托管平台会送免费调用次数或者注册即送额度。opencode本身也支持接入本地模型比如通过Ollama跑Llama、Qwen这些开源模型完全不需要API Key就是很吃机器性能建议至少32GB内存的机器才跑得动7B以上的模型。我个人的习惯是日常小任务用轻量模型比如快速解释代码、写单元测试这种成本低、速度快复杂的重构任务再切到Claude或者GPT这类旗舰模型。opencode支持在配置里设置多个模型对话中通过命令快速切换非常方便。2.4 初始化配置opencode第一次启动时会引导你完成初始化配置主要包含几个方面选择你要用的模型提供方确认终端主题和显示风格设置工作目录和相关路径配置完成后在任意项目目录下直接输入opencode它就会以当前目录作为工作空间开始运行。这时它会先扫描项目结构生成一个索引方便后续快速定位文件。如果你是第一次用建议先找一个结构简单的小项目试试水。直接给它一个很具体的任务比如告诉我这个项目的核心模块有哪些各自负责什么先感受一下它的回答质量和速度再逐步加码。3. 日常使用与项目实战从读代码到改代码3.1 打开项目的第一步进入项目后opencode会处于一个交互式会话中有点像进入了REPL环境可以连续对话。第一次进入项目时建议先让它读一遍项目而不是直接给任务。我通常会这么开场请先浏览一下项目结构告诉我这是一个什么类型的项目、用的什么技术栈、核心入口在哪里。这一步看似简单但非常重要。opencode会自己读package.json、README.md、源码目录等核心文件建立一个项目上下文后续的问答和代码修改都会基于这个上下文展开。如果跳过了这一步后面它可能就断章取义只看你提到的文件缺失全局视野。在opencode 2.0之后的版本里项目索引和数据统计做得更好了它会在启动后自动生成一份项目概览包括文件数量、代码量、模块依赖关系等这些信息对快速了解一个陌生项目帮助非常大。3.2 skills给opencode装上行业经验用过ChatGPT类工具的人都知道大模型的能力上限取决于你给它的上下文和指令。opencode里的Skills技能就是干这个的——它是一段预先定义好的指令模板告诉opencode在特定场景下应该怎么思考、怎么行动、按什么标准输出。举个例子我写了一个代码审查的skillname: code-review description: 对指定代码进行系统化审查关注安全性、性能和可维护性 instructions: | 1. 先通读代码理解功能逻辑 2. 检查潜在的安全隐患SQL注入、XSS、硬编码密钥等 3. 检查性能问题循环嵌套、不必要的重复计算等 4. 检查代码风格一致性 5. 输出问题列表按严重程度排序每条附建议修复方案把这个文件放到~/.config/opencode/skills/目录下然后就可以在会话里这样使用应用 code-review skill审查 src/auth/login.js它会按照skill里定义的审查维度逐条检查和输出。这相当于把你自己积累的经验和标准固化成了可复用的指令让AI工具和你用同一套标准做事。Skills还能做得更复杂。比如你可以写一个前端性能优化的skill要求opencode先分析关键渲染路径再检查打包配置最后给出优化建议或者写一个数据库迁移的skill让它按照你团队规定的迁移规范来生成SQL脚本。实际上核心思路就是把你的套路教给工具让它执行得更高效、更符合团队约定。3.3 memory让工具记住你的偏好如果说skills解决的是怎么干活的问题那memory解决的就是记住你这个人的问题。用过几次之后你会发现AI工具经常会忘记你之前告诉过它的偏好。比如你说了很多次注释用中文写但换一个新会话它又用英文写注释了。opencode的memory功能就是为了解决这个问题。你可以在会话中直接说记住本项目所有注释使用中文变量命名采用驼峰式。opencode会把这条偏好记录在memory里后续同一项目下的所有会话都会自动遵守。它还支持更细粒度的记忆比如测试文件统一放在tests目录下提交信息使用Conventional Commits规范等等。这一功能在实际使用中价值极高。尤其是长期维护一个项目时AI工具能越来越贴合你的习惯就像带了一个渐渐懂你的结对编程搭档。配合skills一起用基本可以让opencode按照你团队的标准来输出代码。3.4 用Playwright跑前端bug的实测体验前面说的都是代码读写能力实际开发中还有一个高频需求——定位前端Bug。opencode有意思的一点是它内置了浏览器自动化能力可以直接调起Playwright来做前端测试和Bug复现。我第一次用这个功能的时候是在一个Vue项目里排查一个点击按钮后弹窗不出现的问题。我在opencode里描述了这个Bug它自己写了一个Playwright脚本启动浏览器、打开页面、模拟点击按钮然后截图给我看。整个过程我是全程目睹的终端里会输出每一步的浏览器动作日志。具体操作上只需要给opencode一个指令用playwright打开 http://localhost:3000/login填好测试账号点击登录按钮看控制台有没有报错截图给我。它会自动完成以下步骤检查项目里是否安装了Playwright、没有的话自动安装、编写测试脚本、启动浏览器执行、抓取控制台日志、保存截图并分析。实测下来对那种只在特定交互路径下出现的前端Bug这个能力比让人肉操作浏览器再逐步排查快太多了。不过我建议你在本地跑的时候尽量用一个独立的测试环境或测试账号避免自动化操作污染生产数据。这个坑我踩过差点把测试环境的垃圾订单发到生产仓库去。4. 编辑器生态与桌面版不只在终端里工作4.1 VSCode插件虽然opencode本身是终端工具但实际开发里完全脱离编辑器也不现实。所以官方提供了VSCode插件把opencode的能力嵌入到编辑器里。安装方式不赘述了直接在VSCode扩展市场搜opencode就能找到。装完后的体验是你可以在编辑器里直接打开opencode面板选中一段代码让它解释或者把整个文件扔给它做审查。最常用的场景其实是inline edit选中一段代码后按快捷键opencode会基于上下文给出修改建议你可以直接接受或拒绝类似于GitHub Copilot的inline chat功能。VSCode插件还有一个很贴心的设计它会在编辑器底部状态栏显示当前opencode还在执行的任务进度比如正在修改3个文件正在运行测试你不用切到终端就能知道任务进展。4.2 JetBrains IDEA插件JetBrains用户同样有福IDEA的opencode插件也做得比较成熟。我平时主力IDE是IntelliJ IDEA装了这个插件之后最惊喜的是它能和IDE本身的代码分析能力做联动。比如我让opencode找出项目里所有未捕获的异常并优化处理它做完修改后IDEA自带的Inspections会立刻对修改后的代码做静态分析任何问题都会在编辑器里标红。这种AI修改IDE校验的组合拳大大降低了AI改出问题代码的风险。插件还支持把opencode的对话记录保存为文件方便分享给团队。对于需要写技术方案或代码评审意见的场景这个功能很实用。4.3 opencode桌面版如果说VSCode和IDEA插件是嵌入既有工作流那opencode桌面版就是另外一条路给你一个独立的图形界面。桌面版的定位并不是替代IDE而是做一个更友好的opencode入口。界面左侧是项目文件树中间是对话区右侧可以实时查看opencode改动了哪些文件、每处改动的diff内容。视觉上比终端的纯文本输出友好许多尤其是查看大文件改动时diff视图比终端里的文本对比清晰得多。我用桌面版的主要场景是处理一个比较复杂的跨文件重构任务。在终端里看着满屏的日志很容易抓不住重点但桌面版里可以清晰看到改了哪几个文件、每个文件改了什么、有没有测试失败信息层次非常清楚。如果你完全习惯了终端操作桌面版可以用可不用但如果你更习惯图形界面、或者需要给团队做演示我还是建议装一个。5. 常见问题与排查技巧实录5.1 命令找不到的经典报错先聊一个最基础但出现频率极高的问题。在Windows上很多人执行opencode时遇到这样的提示opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称我在前面提过最常见的原因是安装后没有打开新终端。npm的全局bin目录没有被当前PowerShell会话的PATH变量感知到你只要关掉当前终端重新开一个就好。如果重开终端还是不行那就要检查npm全局目录是否在PATH里。执行npm config get prefix拿到路径后大概率是C:\Users\你的用户名\AppData\Roaming\npm确认这个路径是否出现在系统环境变量PATH中。没有的话手动加进去再重开终端就解决了。5.2 服务端异常(server error)的排查思路另一个高频报错是opencode error: unexpected server error. check server logs for more details.这个报错信息其实挺让人摸不着头脑的。根据我的经验出现这个报错有几种可能的根源按概率排第一API Key没有正确配置或者已经失效。去检查一下环境变量和配置文件里的key是否一致、是否还有效。第二模型服务商那边的接口出问题了或者你选的模型ID填错了。可以从配置里临时换一个模型试试如果能正常运行说明是原模型的问题。第三本地代理工具冲突。如果你开着系统代理而代理规则把opencode发出API请求也给拦截了就会出现这种服务端错误。排查方法是临时关掉代理再跑一次如果问题消失那就是代理规则对该请求的处理有问题在代理工具里加个绕过规则就行。5.3 用ccswitch管理多模型配置说到模型切换这里得提一下ccswitch这个工具。它本质上是一个模型API配置切换器用来管理多个模型服务商的配置。为什么需要它因为opencode的默认配置是一个提供商一个Key但实际使用中每个人手里可能同时有好几个模型渠道有的便宜、有的快、有的效果好。手动改配置文件切换很麻烦尤其是在多个项目之间来回切换时容易搞乱。ccswitch的做法是把不同服务商的配置整理成配置集每个集含baseURL、API Key、模型列表等信息。切换的时候一个命令搞定不用打开配置文件来回改。实际配合opencode使用时我会在opencode配置里把baseURL指到ccswitch的本地代理端口这样opencode发出的所有请求都会经过ccswitch由它来做路由和转发。想换模型的时候在ccswitch里切换配置集就行。这个方案对经常要对比多个模型效果的人来说非常高效。5.4 免费模型下线问题关于免费模型最近有个热点是hy3-free下线了吗这类问题。确实有部分免费模型渠道因为运营原因停止服务或调整额度的现象这在圈子里很常见。我的建议是不要把免费模型当作生产环境的依赖。免费额度适合用来学习、试用、写点脚本工具但正经项目开发还是要选择有稳定商业背书的模型服务。如果你对成本敏感可以关注那些长期提供免费额度的开源模型托管平台或者直接本地部署小型开源模型比如Qwen系列的小参数版本来跑日常简单任务。注意定期关注官方公告一旦发现免费额度有变动及时调整配置别等断服了才手忙脚乱。6. 横向对比opencode、Codex、Claude Code怎么选6.1 三个工具的基本盘现在的AI编程代理市场opencode、OpenAI Codex和Claude Code是三款关注度最高的工具。我不打算做谁全面碾压谁的结论这没有意义因为每个工具的设计理念和适用场景都不尽相同。Claude Code最大的优势在于理解和生成代码的自然度尤其是对复杂业务逻辑的推理能力。处理那种牵一发动全身的跨模块改动它表现确实惊艳。缺点是对非Anthropic系模型的适配不够友好基本绑定了Claude生态。OpenAI Codex的优势是执行速度和对复杂任务的拆解能力毕竟背后是OpenAI的模型体系。它能很好地处理多文件、多步骤的自动化任务在Agent执行链路的稳定性上比较可靠。但如果你不常用OpenAI模型它的优势就体现不出来。opencode的优势在于开放性和可定制性。它不绑定某个特定模型你可以自由配置GPT、Claude、Gemini或者本地模型同时它的skills和memory机制让用户可以深度定制它的行为模式。缺点是它需要你花一些时间去配置和调优开箱即用的爽感不如Claude Code那么直接。6.2 我的真实选择说实话这三个工具我目前都在用但分工不同。日常工作里opencode是我默认的开发助手。原因很简单我是重度的Vim终端工作流用户opencode跑在终端里的体验最顺手而且我可以无缝切换不同模型今天想用Claude跑重构明天想用GPT写测试都是一个指令的事。它的skills让我能把团队规范固化成模板新加入的同学也能用同一套标准跑。Claude Code我会在遇到特别复杂的架构设计问题时打开它的推理能力有时候确实能给出让人眼前一亮的方案。Codex则更多用在批量化代码处理任务上比如大量文件的格式统一、自动生成单元测试等。如果你刚接触这类工具我的建议是直接从opencode入手。它的学习曲线不算陡峭而且因为配置灵活、社区活跃你可以逐步摸索出最适合自己的使用方式。等你对代理式AI编程有了感觉再对比其他工具会有更清晰的判断。6.3 不要忽略社区和生态最后说一个容易被忽略的点工具的生态和社区。opencode是开源项目这意味着它的迭代速度非常快社区的插件和skills仓库也在持续增长。我经常去翻它的GitHub仓库看最新的release notes和社区提交的skills配置总能学到一些新的用法。比如最近社区有人分享了一套前端重构的skills组合包括了代码分割、性能优化、可访问性检查等多个维度拿来即用效果相当不错。这种生态红利是商业闭源工具很难给你的。如果你习惯折腾、愿意折腾opencode会给你很大的想象空间。回到最初的话题AI编程工具这两年发展太快今天写得再详尽的教程可能过两个月就过时了。但有一点是不变的工具只是放大器你的判断力、架构能力和工程素养才是决定项目质量的根本。opencode能帮你写得更快但写什么、为什么这么写终究是你自己的事。如果让我给一个最实在的建议那就是别追求最强工具追求最适合自己的工作流。花一天时间把opencode、Claude Code、Codex都装一遍各自跑几个真实任务哪个用着顺手哪个就是你的主力工具。工具是拿来用的不是拿来崇拜的。 opencode：终端里的AI编程代理，从安装到实战全解析
1. 先把opencode放在正确的位置上它到底是个什么东西1.1 从终端里长出来的AI编程代理第一次听说opencode的时候我其实有点麻木了毕竟这两年AI编程工具出来一个接一个从最早的GitHub Copilot到后来的Cursor再到Claude Code和Codex CLI我几乎都试过一遍。但opencode给我的第一印象不太一样它不是一个挂在编辑器侧边栏的补全插件也不是一个只能聊天的对话框而是一个真正跑在终端里的AI编程代理agent你给它一个任务它会自己读代码、查文档、改文件、跑命令甚至自己调试。简单说opencode是一个开源的、命令行优先的AI编程助手。它最大的特点是代理式工作流不是等你逐行敲代码再给你补全而是你提一个需求比如帮我把登录接口的超时时间改成可配置项它会自己定位到相关文件、分析上下游调用、修改代码并给出测试建议。整个过程在终端里完成轻量、直接、可脚本化这种体验和传统IDE里的AI插件完全不同。1.2 聊一聊opencode与传统AI补全工具的差别很多人一听到AI编程工具第一反应就是是不是又一个Copilot。真不是一回事。补全工具的核心逻辑是你写一句它接一句解决的是局部效率问题而opencode这类代理工具解决的是整个任务怎么落地的问题。举个例子我用Copilot的时候写一个函数它能把函数体补完但如果让它把这个模块的重试逻辑统一抽出来它就抓瞎了。而opencode可以自己浏览项目结构、理解现有代码风格、找到所有涉及重试的位置、设计抽取方案、逐个修改文件最后还能跑一遍测试确认没有破坏现有功能。这种从需求到落地的闭环能力才是代理式工具的价值所在。另外opencode是终端工具这意味着它比IDE插件更灵活。你可以把它接到任何编辑器里用也可以在CI脚本里调用甚至可以通过SSH远程操作服务器上的代码。这种脱离IDE束缚的设计让很多习惯Vim和Emacs的老派开发者也能顺畅上手。1.3 谁最适合用opencode从我个人的使用经验来看下面这几类人最能从opencode里拿到实际收益需要频繁接手陌生项目的开发者。opencode读代码的能力相当强你让它先梳理项目结构和核心模块比人肉翻代码快得多。做全栈开发的独立开发者。一个人要兼顾前端、后端、脚本、部署opencode能帮你快速处理那些写着没意思但不得不做的胶水代码。喜欢命令行工作流、不喜欢被IDE绑架的工程师。想在自有代码库上做自动化改造、批量重构的技术负责人。反过来如果你是刚学编程没多久的新手我建议还是先把基础打牢。opencode生成代码的能力很强但代码评审、需求拆解、风险判断这些能力还是得靠人。工具再好不能替代你自己的判断力。提示opencode适合知道自己要什么的人它能帮你快速执行但决策还得自己做。2. 安装与初始配置把opencode跑起来2.1 安装前需要准备什么opencode本质上是一个基于Node.js的命令行工具所以安装前你的机器上需要准备好Node.js环境。我建议安装Node.js 18以上版本太老的版本跑不起来。另外opencode自身不包含AI模型它需要对接大语言模型的API。目前市面上主流的模型服务商都可以接OpenAI的GPT系列、Anthropic的Claude系列、Google的Gemini系列以及一些国产模型都在支持范围内。你需要准备好对应的API Key。有一个容易踩的坑是网络环境。opencode调用模型API走的是HTTPS标准端口如果你的机器有代理设置注意别让终端代理和API请求打架不然会报各种莫名其妙的连接错误。2.2 安装opencode的几种方式opencode的安装方式有好几种我按推荐度排个序第一种通过npm全局安装这也是最常规的方式npm install -g opencode-ai装完以后直接敲opencode --version验证是否成功。第二种通过Homebrew安装适合macOS用户brew install opencode第三种下载预编译的二进制包适合不想装Node.js环境、或者需要在CI里快速集成的场景。直接去opencode的GitHub Releases页面下载对应平台的可执行文件放到PATH目录里就行。这里要特别提醒一下如果你在Windows上安装装完后打开一个新的终端窗口再执行命令。因为npm安装的全局命令路径不会实时刷新到当前会话的PATH变量里很多人明明装成功了但一执行就提示无法识别命令其实是没开新终端。2.3 模型接入与免费模型选择安装完成之后第一步要配置模型服务商。opencode支持多种模型提供商配置方式很灵活既可以通过环境变量也可以在配置文件里指定。以最常用的OpenAI兼容接口为例export OPENAI_API_KEY你的key或者在配置文件~/.config/opencode/config.json里写入{ provider: openai, model: gpt-4o, apiKey: 你的key }关于免费模型很多刚开始接触opencode的朋友会问。市面上确实有一些提供免费额度的模型服务商比如某些开源模型的托管平台会送免费调用次数或者注册即送额度。opencode本身也支持接入本地模型比如通过Ollama跑Llama、Qwen这些开源模型完全不需要API Key就是很吃机器性能建议至少32GB内存的机器才跑得动7B以上的模型。我个人的习惯是日常小任务用轻量模型比如快速解释代码、写单元测试这种成本低、速度快复杂的重构任务再切到Claude或者GPT这类旗舰模型。opencode支持在配置里设置多个模型对话中通过命令快速切换非常方便。2.4 初始化配置opencode第一次启动时会引导你完成初始化配置主要包含几个方面选择你要用的模型提供方确认终端主题和显示风格设置工作目录和相关路径配置完成后在任意项目目录下直接输入opencode它就会以当前目录作为工作空间开始运行。这时它会先扫描项目结构生成一个索引方便后续快速定位文件。如果你是第一次用建议先找一个结构简单的小项目试试水。直接给它一个很具体的任务比如告诉我这个项目的核心模块有哪些各自负责什么先感受一下它的回答质量和速度再逐步加码。3. 日常使用与项目实战从读代码到改代码3.1 打开项目的第一步进入项目后opencode会处于一个交互式会话中有点像进入了REPL环境可以连续对话。第一次进入项目时建议先让它读一遍项目而不是直接给任务。我通常会这么开场请先浏览一下项目结构告诉我这是一个什么类型的项目、用的什么技术栈、核心入口在哪里。这一步看似简单但非常重要。opencode会自己读package.json、README.md、源码目录等核心文件建立一个项目上下文后续的问答和代码修改都会基于这个上下文展开。如果跳过了这一步后面它可能就断章取义只看你提到的文件缺失全局视野。在opencode 2.0之后的版本里项目索引和数据统计做得更好了它会在启动后自动生成一份项目概览包括文件数量、代码量、模块依赖关系等这些信息对快速了解一个陌生项目帮助非常大。3.2 skills给opencode装上行业经验用过ChatGPT类工具的人都知道大模型的能力上限取决于你给它的上下文和指令。opencode里的Skills技能就是干这个的——它是一段预先定义好的指令模板告诉opencode在特定场景下应该怎么思考、怎么行动、按什么标准输出。举个例子我写了一个代码审查的skillname: code-review description: 对指定代码进行系统化审查关注安全性、性能和可维护性 instructions: | 1. 先通读代码理解功能逻辑 2. 检查潜在的安全隐患SQL注入、XSS、硬编码密钥等 3. 检查性能问题循环嵌套、不必要的重复计算等 4. 检查代码风格一致性 5. 输出问题列表按严重程度排序每条附建议修复方案把这个文件放到~/.config/opencode/skills/目录下然后就可以在会话里这样使用应用 code-review skill审查 src/auth/login.js它会按照skill里定义的审查维度逐条检查和输出。这相当于把你自己积累的经验和标准固化成了可复用的指令让AI工具和你用同一套标准做事。Skills还能做得更复杂。比如你可以写一个前端性能优化的skill要求opencode先分析关键渲染路径再检查打包配置最后给出优化建议或者写一个数据库迁移的skill让它按照你团队规定的迁移规范来生成SQL脚本。实际上核心思路就是把你的套路教给工具让它执行得更高效、更符合团队约定。3.3 memory让工具记住你的偏好如果说skills解决的是怎么干活的问题那memory解决的就是记住你这个人的问题。用过几次之后你会发现AI工具经常会忘记你之前告诉过它的偏好。比如你说了很多次注释用中文写但换一个新会话它又用英文写注释了。opencode的memory功能就是为了解决这个问题。你可以在会话中直接说记住本项目所有注释使用中文变量命名采用驼峰式。opencode会把这条偏好记录在memory里后续同一项目下的所有会话都会自动遵守。它还支持更细粒度的记忆比如测试文件统一放在tests目录下提交信息使用Conventional Commits规范等等。这一功能在实际使用中价值极高。尤其是长期维护一个项目时AI工具能越来越贴合你的习惯就像带了一个渐渐懂你的结对编程搭档。配合skills一起用基本可以让opencode按照你团队的标准来输出代码。3.4 用Playwright跑前端bug的实测体验前面说的都是代码读写能力实际开发中还有一个高频需求——定位前端Bug。opencode有意思的一点是它内置了浏览器自动化能力可以直接调起Playwright来做前端测试和Bug复现。我第一次用这个功能的时候是在一个Vue项目里排查一个点击按钮后弹窗不出现的问题。我在opencode里描述了这个Bug它自己写了一个Playwright脚本启动浏览器、打开页面、模拟点击按钮然后截图给我看。整个过程我是全程目睹的终端里会输出每一步的浏览器动作日志。具体操作上只需要给opencode一个指令用playwright打开 http://localhost:3000/login填好测试账号点击登录按钮看控制台有没有报错截图给我。它会自动完成以下步骤检查项目里是否安装了Playwright、没有的话自动安装、编写测试脚本、启动浏览器执行、抓取控制台日志、保存截图并分析。实测下来对那种只在特定交互路径下出现的前端Bug这个能力比让人肉操作浏览器再逐步排查快太多了。不过我建议你在本地跑的时候尽量用一个独立的测试环境或测试账号避免自动化操作污染生产数据。这个坑我踩过差点把测试环境的垃圾订单发到生产仓库去。4. 编辑器生态与桌面版不只在终端里工作4.1 VSCode插件虽然opencode本身是终端工具但实际开发里完全脱离编辑器也不现实。所以官方提供了VSCode插件把opencode的能力嵌入到编辑器里。安装方式不赘述了直接在VSCode扩展市场搜opencode就能找到。装完后的体验是你可以在编辑器里直接打开opencode面板选中一段代码让它解释或者把整个文件扔给它做审查。最常用的场景其实是inline edit选中一段代码后按快捷键opencode会基于上下文给出修改建议你可以直接接受或拒绝类似于GitHub Copilot的inline chat功能。VSCode插件还有一个很贴心的设计它会在编辑器底部状态栏显示当前opencode还在执行的任务进度比如正在修改3个文件正在运行测试你不用切到终端就能知道任务进展。4.2 JetBrains IDEA插件JetBrains用户同样有福IDEA的opencode插件也做得比较成熟。我平时主力IDE是IntelliJ IDEA装了这个插件之后最惊喜的是它能和IDE本身的代码分析能力做联动。比如我让opencode找出项目里所有未捕获的异常并优化处理它做完修改后IDEA自带的Inspections会立刻对修改后的代码做静态分析任何问题都会在编辑器里标红。这种AI修改IDE校验的组合拳大大降低了AI改出问题代码的风险。插件还支持把opencode的对话记录保存为文件方便分享给团队。对于需要写技术方案或代码评审意见的场景这个功能很实用。4.3 opencode桌面版如果说VSCode和IDEA插件是嵌入既有工作流那opencode桌面版就是另外一条路给你一个独立的图形界面。桌面版的定位并不是替代IDE而是做一个更友好的opencode入口。界面左侧是项目文件树中间是对话区右侧可以实时查看opencode改动了哪些文件、每处改动的diff内容。视觉上比终端的纯文本输出友好许多尤其是查看大文件改动时diff视图比终端里的文本对比清晰得多。我用桌面版的主要场景是处理一个比较复杂的跨文件重构任务。在终端里看着满屏的日志很容易抓不住重点但桌面版里可以清晰看到改了哪几个文件、每个文件改了什么、有没有测试失败信息层次非常清楚。如果你完全习惯了终端操作桌面版可以用可不用但如果你更习惯图形界面、或者需要给团队做演示我还是建议装一个。5. 常见问题与排查技巧实录5.1 命令找不到的经典报错先聊一个最基础但出现频率极高的问题。在Windows上很多人执行opencode时遇到这样的提示opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称我在前面提过最常见的原因是安装后没有打开新终端。npm的全局bin目录没有被当前PowerShell会话的PATH变量感知到你只要关掉当前终端重新开一个就好。如果重开终端还是不行那就要检查npm全局目录是否在PATH里。执行npm config get prefix拿到路径后大概率是C:\Users\你的用户名\AppData\Roaming\npm确认这个路径是否出现在系统环境变量PATH中。没有的话手动加进去再重开终端就解决了。5.2 服务端异常(server error)的排查思路另一个高频报错是opencode error: unexpected server error. check server logs for more details.这个报错信息其实挺让人摸不着头脑的。根据我的经验出现这个报错有几种可能的根源按概率排第一API Key没有正确配置或者已经失效。去检查一下环境变量和配置文件里的key是否一致、是否还有效。第二模型服务商那边的接口出问题了或者你选的模型ID填错了。可以从配置里临时换一个模型试试如果能正常运行说明是原模型的问题。第三本地代理工具冲突。如果你开着系统代理而代理规则把opencode发出API请求也给拦截了就会出现这种服务端错误。排查方法是临时关掉代理再跑一次如果问题消失那就是代理规则对该请求的处理有问题在代理工具里加个绕过规则就行。5.3 用ccswitch管理多模型配置说到模型切换这里得提一下ccswitch这个工具。它本质上是一个模型API配置切换器用来管理多个模型服务商的配置。为什么需要它因为opencode的默认配置是一个提供商一个Key但实际使用中每个人手里可能同时有好几个模型渠道有的便宜、有的快、有的效果好。手动改配置文件切换很麻烦尤其是在多个项目之间来回切换时容易搞乱。ccswitch的做法是把不同服务商的配置整理成配置集每个集含baseURL、API Key、模型列表等信息。切换的时候一个命令搞定不用打开配置文件来回改。实际配合opencode使用时我会在opencode配置里把baseURL指到ccswitch的本地代理端口这样opencode发出的所有请求都会经过ccswitch由它来做路由和转发。想换模型的时候在ccswitch里切换配置集就行。这个方案对经常要对比多个模型效果的人来说非常高效。5.4 免费模型下线问题关于免费模型最近有个热点是hy3-free下线了吗这类问题。确实有部分免费模型渠道因为运营原因停止服务或调整额度的现象这在圈子里很常见。我的建议是不要把免费模型当作生产环境的依赖。免费额度适合用来学习、试用、写点脚本工具但正经项目开发还是要选择有稳定商业背书的模型服务。如果你对成本敏感可以关注那些长期提供免费额度的开源模型托管平台或者直接本地部署小型开源模型比如Qwen系列的小参数版本来跑日常简单任务。注意定期关注官方公告一旦发现免费额度有变动及时调整配置别等断服了才手忙脚乱。6. 横向对比opencode、Codex、Claude Code怎么选6.1 三个工具的基本盘现在的AI编程代理市场opencode、OpenAI Codex和Claude Code是三款关注度最高的工具。我不打算做谁全面碾压谁的结论这没有意义因为每个工具的设计理念和适用场景都不尽相同。Claude Code最大的优势在于理解和生成代码的自然度尤其是对复杂业务逻辑的推理能力。处理那种牵一发动全身的跨模块改动它表现确实惊艳。缺点是对非Anthropic系模型的适配不够友好基本绑定了Claude生态。OpenAI Codex的优势是执行速度和对复杂任务的拆解能力毕竟背后是OpenAI的模型体系。它能很好地处理多文件、多步骤的自动化任务在Agent执行链路的稳定性上比较可靠。但如果你不常用OpenAI模型它的优势就体现不出来。opencode的优势在于开放性和可定制性。它不绑定某个特定模型你可以自由配置GPT、Claude、Gemini或者本地模型同时它的skills和memory机制让用户可以深度定制它的行为模式。缺点是它需要你花一些时间去配置和调优开箱即用的爽感不如Claude Code那么直接。6.2 我的真实选择说实话这三个工具我目前都在用但分工不同。日常工作里opencode是我默认的开发助手。原因很简单我是重度的Vim终端工作流用户opencode跑在终端里的体验最顺手而且我可以无缝切换不同模型今天想用Claude跑重构明天想用GPT写测试都是一个指令的事。它的skills让我能把团队规范固化成模板新加入的同学也能用同一套标准跑。Claude Code我会在遇到特别复杂的架构设计问题时打开它的推理能力有时候确实能给出让人眼前一亮的方案。Codex则更多用在批量化代码处理任务上比如大量文件的格式统一、自动生成单元测试等。如果你刚接触这类工具我的建议是直接从opencode入手。它的学习曲线不算陡峭而且因为配置灵活、社区活跃你可以逐步摸索出最适合自己的使用方式。等你对代理式AI编程有了感觉再对比其他工具会有更清晰的判断。6.3 不要忽略社区和生态最后说一个容易被忽略的点工具的生态和社区。opencode是开源项目这意味着它的迭代速度非常快社区的插件和skills仓库也在持续增长。我经常去翻它的GitHub仓库看最新的release notes和社区提交的skills配置总能学到一些新的用法。比如最近社区有人分享了一套前端重构的skills组合包括了代码分割、性能优化、可访问性检查等多个维度拿来即用效果相当不错。这种生态红利是商业闭源工具很难给你的。如果你习惯折腾、愿意折腾opencode会给你很大的想象空间。回到最初的话题AI编程工具这两年发展太快今天写得再详尽的教程可能过两个月就过时了。但有一点是不变的工具只是放大器你的判断力、架构能力和工程素养才是决定项目质量的根本。opencode能帮你写得更快但写什么、为什么这么写终究是你自己的事。如果让我给一个最实在的建议那就是别追求最强工具追求最适合自己的工作流。花一天时间把opencode、Claude Code、Codex都装一遍各自跑几个真实任务哪个用着顺手哪个就是你的主力工具。工具是拿来用的不是拿来崇拜的。