我是在一个加班到晚上十一点的周五晚上第一次装上 opencode 的。当时项目里堆了十几个 issue传统的工作流已经让我提不起劲打开编辑器翻代码猜上下文改完再跑测试发现问题又得回头改。我真正想要的是一个能在终端里听我说话、自己翻代码、自己跑命令、把改动直接落到文件里的工具而不是又一个只会生成代码片段的聊天框。opencode 就是冲着这个需求来的。它是做 serverless 框架 SST 的那个团队Anomaly 公司开源的一款 AI 编码智能体定位很明确终端优先、配置本地化、支持多模型、能真正读写文件并执行命令。到 2.0 版本之后又补上了桌面版、VSCode 插件、JetBrains 插件生态一下子完整了不少。这两天在各个技术群里关于它的讨论热度明显在涨问安装、问配置、问和 Codex CLI / Claude Code 对比的声音特别多。这篇文章不是官方文档的翻译而是我这两个月实际用下来的经验整理从安装报错怎么排查到模型怎么配才省钱再到 Skills、Memory、Playwright 这些进阶玩法和真实踩坑记录。如果你正准备上手 opencode或者已经装了但用不顺手这篇应该能帮你省下不少折腾时间。1. opencode 到底是什么一个不甘心只做“聊天助手”的开源编码智能体1.1 出身与定位SST 团队为什么做这个很多人第一次听到 opencode第一反应是SST 不是做无服务器框架的吗怎么跑来做 AI 工具了。没错正是那个团队。可能正因为常年做开发者基础设施他们对开发者工作流的理解非常实际AI 编程工具不应该是一个网页对话框而应该待在你本来就在的地方——终端和编辑器里。opencode 和 Claude Code、Codex CLI 是同一类东西业内管这类工具叫 terminal AI coding agent。它们和普通 AI 编程助手的核心区别不在聊天能力而在动手能力能递归读取项目文件理解整个代码库的结构和上下文能直接创建、修改文件而不是只给你一段代码让你自己粘贴能执行 shell 命令跑测试、跑构建、看报错能基于命令输出自我修正多轮迭代直到任务完成opencode 开源是它很大的一个卖点。代码全部公开配置存在本地不强制绑定某一家模型厂商。你可以把 Anthropic、OpenAI、Google 的模型甚至本地用 Ollama 跑的模型都配置进去同一个工具随时切换。这一点对我这种喜欢东用一下西用一下的人来说非常友好。1.2 它和传统 AI 编程工具有什么本质区别如果你用过 Copilot 时代的补全工具再用 opencode体感是完全不同的。补全工具是你写它猜智能体是你下达目标它自己干。举个我真实经历的例子有次我接了个活要把项目里所有硬编码的错误提示文案抽到一个 i18n 文件里。以前这种活我要手动开十几个文件一行一行找出来改。用 opencode我只说了一句把 src 下所有硬编码的中文错误提示抽到 locales/zh-CN.ts更新所有引用跑一遍测试确认没破。它自己先列了改动清单然后逐个文件改再跑 yarn test中途发现有个测试用例断言的是旧文案又自己改掉最后把结果汇报给我。整个过程我基本只在旁边看偶尔喊停。这种目标驱动的工作方式把 AI 从配角变成了真正干活的角色。它不再是你问一句它答一句而是你交代一个目标它自己规划路径、执行、验证、交付。1.3 适合谁不适合谁先说明白opencode 不是给所有人的。适合的人有一定命令行基础、日常用终端或者 IDE 重度开发的程序员想要一个能真正干活、而不是只会建议的 AI 工具的人做全栈或者前端、经常需要改一堆相关文件的场景喜欢自己掌控模型选择、不想被厂商锁定的人。不适合的人完全没接触过命令行的新手可能先从编辑器里的 AI 插件上手更舒服对AI 直接改代码这件事接受度低、必须自己逐行手敲的人以及希望工具开箱即用、不想花十分钟看配置文档的人。opencode 的安装和配置已经不算复杂但它毕竟是个面向开发者的开源工具默认假设你有点折腾能力。2. 装好 opencode从下载、PATH 到“cmdlet 无法识别”的解决思路2.1 三种安装方式怎么选我接触到的 opencode 安装方式主要有三种npm 安装、Go 安装、桌面版安装。三种我都试过各有适用场景。第一种npm 全局安装。如果你平时用 Node.js 开发这是最顺的一条路npm install -g opencode-ai装完直接opencode就能进交互界面。我最早就是这条路装的前后不到一分钟。需要留意的是npm 包名可能会随版本调整安装前最好去官方仓库确认一下当前的名字别凭记忆装错包。第二种Go 安装。如果你机器上有 Go 环境也可以用go install github.com/sst/opencodelatest装完的可执行文件在$(go env GOPATH)/bin下。这种方式适合本来就在 Go 生态里的人或者 npm 这边出了奇怪的权限问题作为备选。网上有些人说opencode go 需要配合 cc switch 等工具来管理模型配置其实 go 安装和 npm 安装得到的核心程序是一样的区别只是装到哪个目录、由谁管理版本后面配模型时统一走配置文件即可。第三种桌面版。opencode 官方提供了桌面客户端有图形界面适合不想碰终端、或者想把 opencode 当作一个独立 App 来用的人。桌面版内置了终端面板本质上还是同一套引擎外面套了一层壳。我个人的建议是如果你主力开发在终端或 IDE 里用前两种就够桌面版更像是独立工具党的选择。2.2 Windows 下最常见的“无法识别”报错排查很多人在 Windows 上装完 opencode兴冲冲打开 PowerShell 敲opencode结果看到这么一行红字opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确保路径正确然后再试一次。我第一次看到这个报错也愣了一下以为安装失败了。后来排查多了才明白这条报错的本质是系统在 PATH 环境变量列出的所有目录里都没找到 opencode 这个可执行文件。也就是说程序可能装上了但系统看不见它。常见原因有这么几个按概率排序npm 全局安装目录不在 PATH 里。这是最普遍的原因。npm 全局包的安装目录默认不是 Windows 系统 PATH 的一部分你要手动把它加进去。安装过程失败或者没装完。比如权限不足npm 静默跳过了一些写入。这种重新用管理员权限装一次就好。装完后没重开终端。PATH 是 shell 启动时加载的你装完立刻敲命令当前这个 shell 还是旧环境。用了 nvm、fnm 这类 Node 版本管理工具。PATH 是由版本管理工具动态注入的不同 shell 加载的路径可能不一致。排查的步骤我建议按这个顺序来node -v npm -v npm prefix -g npm ls -g --depth0第一条和第二条确认 Node 环境本身没问题第三条确认 npm 全局包装到了哪个目录第四条确认 opencode 确实在全局包里。如果npm ls里能看到 opencode说明装成功了纯粹是 PATH 问题。接下来把 npm 全局目录加进用户 PATH。PowerShell 里可以直接执行setx PATH $env:APPDATA\npm;%PATH%setx会写进用户环境变量改完一定要新开一个终端窗口再试。如果你不想改全局 PATH临时方案是直接用完整路径调用$env:APPDATA\npm\opencode.exe但这个只能救急长期用还是改 PATH 省心。2.3 验证安装与目录结构装好并解决了 PATH 问题后先跑一下版本号确认安装完整opencode --version能正常输出版本号就说明核心程序没问题。opencode 的配置和数据默认放在用户目录下Linux/macOS 是~/.config/opencode/Windows 是%USERPROFILE%\.config\opencode\里面有全局配置文件、日志等每个项目的配置则放在项目根目录的opencode.json或.opencode/目录里。熟悉这个目录结构挺重要后面改模型配置、加 Skills 都要往这里放东西。建议第一次启动前先确认自己有可用的模型 API Key不然进去会卡在选择模型的环节。第一次真正跑起来的体验很重要别让配置把你劝退了。3. 模型配置是重中之重免费模型、多 Provider 与 CC Switch 协同3.1 先搞懂 opencode 的模型路由逻辑opencode 的模型配置思路很清晰它本身不生产模型只负责把请求路由到你配置好的模型服务上。在配置文件里声明 provider模型提供商再指定默认用哪个模型的哪个版本。全局配置文件位于~/.config/opencode/opencode.json项目级配置文件放在项目根目录支持opencode.json。一个典型的全局配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-5, provider: { openai: { api_key: {env:OPENAI_API_KEY}, models: [gpt-4o, gpt-4o-mini] }, ollama: { models: [qwen2.5-coder:14b] } } }这里有个关键点api_key可以用{env:变量名}的形式引用环境变量我强烈建议你这么做而不是把 Key 明文写进配置文件。一个是安全问题另一个是配置文件可能会被提交到 Git 仓库Key 一旦上去就收不回来了。我用了个笨办法——把配置模板提交到仓库真实 Key 只存在本地环境变量里这样换机器也不怕丢。模型名的格式通常是provider/model因为同一个提供商下面可能有多个模型版本配置时把你要用的都列进models数组运行时可以用快捷键切换非常方便。3.2 免费模型怎么接本地模型和免费额度opencode 免费模型是很多人搜得最多的关键词也确实是最容易踩坑的地方。先说结论opencode 本身是免费的但模型服务是要花钱的——除非你用免费额度或者本地模型。第一种方案是本地模型用 Ollama 跑开源模型。装好 Ollama 后拉一个代码模型下来ollama pull qwen2.5-coder:14b然后在配置里加上对应的 provider就能在 opencode 里选到本地模型。好处是完全免费、数据不出本机、没有限流坏处是效果和大厂闭源模型有差距尤其复杂代码重构这种任务14B 模型经常力不从心。我的经验是本地模型适合做小改动、写测试、改文案这类轻任务重活还是交给云端模型。第二种方案是各家云厂商的免费额度。OpenAI、Google、Anthropic 以及一些模型服务平台都会给新用户一定量的免费调用额度把对应的 API Key 配进去就能用。这种方案的优点是模型能力强缺点是额度有限用完了就得付费或者换一家。免费额度通常有有效期和速率限制别拿来做自动化流水线。第三种方案是社区维护的免费模型端点。这类端点确实存在过网上也一直有讨论比如最近就有人在问某个免费端点是不是下线了。我的态度很明确社区免费端点的稳定性没法保证今天能用明天可能就挂了而且 Key 和流量都要经过第三方敏感项目千万别用。玩玩可以干正事强烈不建议。3.3 用 CC Switch 管理多套配置当你同时用 opencode、Claude Code、Codex CLI 几个工具每个工具又要配置不同的模型和 Key 时配置管理就开始变得烦人。每个工具一套配置文件换模型要开好几个文件去改很容易改出问题。CC Switch 解决的就是这个问题。它是一个用来管理多套模型配置的图形化小工具可以把你常用的配置组合模型名、接口地址、API Key存成一个个配置档然后在不同配置档之间一键切换。它支持的配置档可以导出给 opencode、Claude Code、Codex 等多个工具使用相当于给所有 AI 编程工具做了一个统一的配置遥控器。我现在的用法是在 CC Switch 里存三套配置档一套用 Anthropic 的模型一套用 OpenAI 的模型一套用某个开源模型的商业托管版本。接不同项目时一键切过去opencode 那边读到的配置就变了。省去了每次都要打开 JSON 文件手动改 Key 和模型名的麻烦。不过要注意CC Switch 这类工具本质上是替你写配置文件它改的是 opencode 的配置文件内容。所以你还是得理解前面那个 JSON 的结构不然切换出问题的时候会一脸懵。工具负责效率原理负责兜底。3.4 配置文件里的几个常见坑我配置过程中踩过的坑挑三个典型的说。第一个坑是环境变量引用格式不对。{env:OPENAI_API_KEY}这套语法有的版本支持有的地方要求直接写$OPENAI_API_KEY如果你照着老教程配完发现 Key 没被识别先检查是不是格式问题。判断方法很简单在 opencode 里跑一个简单请求看日志里有没有报鉴权失败。第二个坑是 models 数组和默认 model 不一致。你声明了 provider但全局model字段写了一个 provider 里不存在的模型启动时就会报错或者说模型找不到。改配置后一定要确认两边的模型 ID 拼写一致别少个后缀多个横杠。第三个坑是项目管理器和模型 provider 的命名冲突。你看网上教程的时候会发现provider 的名字在不同版本里可能有差异比如 Ollama 接口遵循 OpenAI 兼容格式有的人就配成了 openai provider 的 custom baseURL有的人配成独立的 ollama provider。两种思路都有人用但混着来容易乱。我的建议是本地模型用独立的 provider 配置云厂商模型用官方 provider逻辑清楚排查也容易。4. 建会话、下命令、看智能体干活opencode 的核心使用逻辑4.1 终端界面与会话基本操作装好配好后在项目目录里敲opencode会进入一个交互式 TUI 界面。顶部是输入框中间是会话内容区底部有快捷键提示。整个界面是终端原生的不依赖浏览器SSH 到服务器上也能用这点很对得起终端优先的定位。基本操作逻辑和大多数终端聊天工具类似输入自然语言指令回车发送AI 开始处理。会话历史会保存在本地下次opencode --continue可以接续上次的对话继续干活不用重新交代上下文。这是个很容易被忽略但实际很重要的功能——AI 编程往往需要多轮迭代断一次会话从头再来非常让人崩溃。在会话中你可以临时切换模型。我一般默认用能力强的大模型做规划中途遇到简单机械的改动切换到快一点、便宜一点的模型能让成本降不少。具体快捷键不同版本略有差异进去之后按?看帮助就懂了。4.2 Agent 的工作循环从计划到执行很多第一次用 opencode 的人会困惑它到底是怎么干活的核心是一个循环解析任务 → 制定计划 → 调用工具执行 → 观察结果 → 调整计划 → 再执行直到任务完成或者被你喊停。opencode 内置了几类关键工具文件工具读取文件、写入文件、列目录这是它改代码的基础命令工具在项目里执行 shell 命令比如npm test、git diff搜索工具在代码库里按语义或正则搜索定位相关代码Web 工具抓取网页、查文档通常用于解决依赖报错或查阅 API浏览器工具可以调用 Playwright 操作浏览器用来测前端页面后面细说每次它要执行一个操作时界面上会显示意图和结果。你可以随时打断也可以让它继续。我建议在前几次使用时不要全程当甩手掌柜而是观察它的计划是否合理。比如让它改一个问题时如果它打算动一个明显不相干的文件这时候打断它还来得及等它改错了再回来解释就麻烦了。4.3 让 opencode 接手开发项目的正确打开方式opencode 接手开发项目是个很诱人的说法但千万不能一上来就丢给它一个把这个项目的功能做完这种巨型指令。我的经验是把它当成一个能力很强但需要明确边界的新同事任务颗粒度要合适期望目标要清晰验收标准要提前说。一个比较科学的下指令框架是背景 目标 约束 验证方式。举个例子不要说把这个页面的样式改好看点而是说登录页的按钮在移动端被键盘顶起来了固定底部栏盖住了输入框。请修复这个布局问题保持现在的设计风格不变只改相关组件的样式文件。改完后在本地跑一遍构建确认没有报错。有背景什么问题、有目标修复布局、有约束不动设计、有验证跑构建。这样 AI 能快速定位范围不会跑去重构你整个项目的 CSS。还有一个技巧让 opencode 在大动作前先输出计划确认后再执行。大多数智能体工具都有 plan 模式或类似功能opencode 也支持先规划再动手。对付十几个文件以上的重构任务这个步骤能救你很多次。4.4 几个我每天都在用的命令和技巧除了自然语言对话opencode 还支持一些快捷操作我挑几个常用的opencode在项目目录启动进入交互界面opencode --continue接续上次会话/init让 opencode 分析项目结构并生成一份项目说明文件AGENTS.md相当于给它自己建立上下文手册/help查看可用命令和快捷键会话中输入!开头可以直接执行 shell 命令不用退出界面/init这个命令特别推荐。它生成的 AGENTS.md 里包含项目结构、技术栈、开发和测试命令等关键信息后续每次会话 opencode 都会自动把这份文件当作背景知识加载。相当于你先花五分钟教它咱们项目是怎么回事后面它干活的质量会有明显提升。这个文件和后面要说的 Memory 机制配合起来效果翻倍。5. 把 opencode 搬进 IDEVSCode 与 JetBrains 插件实战5.1 VSCode 插件侧边栏与选区上下文命令行用久了你会发现有些场景还是离不开 IDE比如看某个函数的调用链、对比改动前后的 diff、直接在断点前调试。所以 opencode 官方做了 IDE 插件让智能体能力可以直接在编辑器里用。VSCode 插件装好之后侧边栏会出现 opencode 面板本质上是在编辑器里内嵌了一个会话窗口。它比终端多一个很实用的能力可以直接把当前打开的文件、甚至选中的代码段作为上下文发送给 AI。比如你选中一段有问题的代码让 opencode 分析这段代码的 Bug它不需要先凭记忆找文件上下文就在眼前定位准确率会高很多。另外一个我很常用的场景是配合 Git 工作。改完代码后让 opencode 帮忙看一下git diff生成 commit message或者让它检查这次改动有没有遗漏的引用。因为这些操作都围绕当前工作区IDE 插件的上下文感知比纯终端要自然。安装 VSCode 插件之后第一次使用会要求指定 opencode 可执行文件的路径。如果插件提示找不到 opencode多半是前面 PATH 问题的余波——把 opencode 的完整路径填进插件设置里就能解决。5.2 JetBrains IDEA 插件与 Maven 项目配置JetBrains 全家桶的插件也是类似思路在 IDEA、PyCharm 等产品的 Marketplace 里搜 opencode 就能安装。它同样支持侧边栏会话、选中代码发送上下文、查看 AI 对文件的改动。不过 Java 项目这边有个特有的坑opencode 要在项目里执行命令时依赖你机器上已经配置好的构建工具比如 Maven。如果你在终端里执行mvn是好的但 opencode 在 IDEA 里执行mvn test却报错找不到命令通常是因为 IDEA 内置终端的环境变量没有继承你用户配置的 PATH尤其在你用 IDEA 自带的 JBR 时更容易出现。解决办法有两个层面。一是确保 Maven 本身配置正确包括M2_HOME环境变量、mvn在 PATH 中二是让 opencode 知道的 JDK 路径.mvn目录下可以配置toolchains.xml或者直接在会话里告诉 opencode 用 jdk 17 跑 mvn test。我实际用下来大部分 Maven 相关报错都不是 opencode 的问题而是环境变量没打通。先在系统终端里把mvn -v跑通再去排查 opencode 那边就简单了。5.3 终端和插件到底该用哪个用了这两周我的感受是终端和 IDE 插件不是替代关系而是各有分工。终端适合整个项目的活——重构、批量改文件、跨多个模块的任务让它自己有充分的自由度在代码库里搜索和修改。这类任务在终端里跑反而清爽不会被编辑器内嵌面板限制。IDE 插件适合当前文件附近的活——分析一段代码、解释报错、生成单测、检查 git diff这些任务强依赖你眼睛正在看的上下文插件有天然优势。我现在的习惯是白天写代码时在 VSCode/IDEA 里开着插件面板处理局部问题需要大范围改动时开一个终端对着项目根目录跑 opencode 会话晚上走之前看一眼所有待办挑几个能委派的丢给 opencode第二天早上看结果和汇报。6. 再进一步Skills、Memory 与 Playwright把 opencode 调教成老手6.1 Skills给智能体装技能包如果你用过 Claude Code 的 skills对 opencode 的 Skills 机制会非常熟悉。它本质上是一组预设能力和行为规范的打包把一个任务的专业流程、注意事项、处理模板写成结构化文档放在指定目录下当任务命中时opencode 会自动加载这套指令来执行。举个例子。我在团队里负责代码评审以前每次 review PR 都要靠脑内清单先看改动范围、再看核心逻辑、检查错误处理、最后看测试覆盖。后来我把这套流程写成了一个 Skill命名为 code-review内容包含评审顺序和重点检查项常见反模式清单输出格式要求必须按问题严重度 文件位置 修改建议输出之后我让它 review 代码时它会自动加载这个 Skill按我定义的流程工作输出质量比我临时口头描述稳定得多。对于一个团队来说这相当于把资深工程师的经验沉淀成了可复用的资产。创建 Skill 的流程不复杂在~/.config/opencode/skills/下建一个目录目录里放一个 SKILL.md 写说明和步骤需要的话再加一些辅助脚本。具体格式建议看官方文档版本更新比较快。社区里也有不少人分享现成的 Skills 集合比如 Superpowers 这类项目把很多成熟的技能包做了整合虽然最初可能为别的工具设计但格式相通思路可以迁移过来——装上后试一下能用就留着不行就当作参考自己改写。6.2 Memory让 opencode 记住项目规矩Memory 机制解决的是每次都要重新交代项目背景的痛点。opencode 读取项目根目录的 AGENTS.md 作为项目级记忆读取用户配置目录下的 AGENTS.md 作为个人级记忆这些文件会在每次会话时自动作为系统背景注入相当于给智能体一本员工手册。我在项目 AGENTS.md 里一般会写这几类内容项目技术栈和目录结构让它快速知道什么东西在哪开发和测试命令比如npm run dev、pnpm test代码规范比如组件统一用函数式写法错误文案必须走 i18n一些特殊约定比如不要改 generated 目录下的文件数据库迁移必须经过确认这些内容写好了opencode 的行为边界就清晰了不会动不动踩到你的红线。我观察到一个规律AGENTS.md 写得越具体AI 的失误率越低。它就像给新同事的 onboarding 文档质量直接决定这个人干活靠不靠谱。Memory 要和 Skills 配合使用AGENTS.md 负责记住规矩Skills 负责知道怎么做。一个是背景知识一个是操作流程合在一起才是完整的老手状态。6.3 用 Playwright 复现和定位前端 Bug前端项目的 Bug 是最难用想来定位的光看代码往往看不出问题必须跑起来看页面表现。opencode 支持通过 Playwright 调用浏览器来测试前端页面这让它可以做复现 Bug → 定位问题 → 修复 → 验证的完整闭环。我实际用下来的操作流程是这样的。先在会话里给它描述 Bug比如列表页点击筛选后URL 参数变了但数据没刷新。然后让它用 Playwright 打开本地开发服务器访问对应页面执行筛选操作观察网络请求和页面状态。它会把操作过程、页面截图、控制台报错原样带回来然后基于这些信息定位代码问题。有一次它发现筛选条件变化后请求参数没带上最新的 state顺着组件树找到了一个有闭包陷阱的 handler自己修完又用 Playwright 跑了一遍同样的操作确认修复生效。我在旁边看着它从头到尾把前端 Bug 的完整链路走了一遍说实话当时有点感慨这就是以前一个中级前端工程师干的事。用 Playwright 测前端有一个实用技巧让 opencode 先写一个最小化的复现脚本而不是直接让它全量跑你的 E2E 测试套件。最小化复现脚本跑得快、失败信息明确定位效率高得多。等它确认修好了再跑完整的测试套件做回归。6.4 社区技能集Superpowers 这类资源的接入思路现在围绕这类智能体工具社区里已经形成了一个生态各种 Skills 集合层出不穷Superpowers 就是其中很出名的一个。它的思路是把很多资深工程师的工作方法固化成一个个可加载的技能包从如何写设计文档到如何进行调试都有现成的模板。接入思路很简单把技能包的内容下载下来按 opencode 的 Skills 目录格式放好然后在 AGENTS.md 里提示 opencode遇到 XX 类任务时优先使用对应 Skill。要注意的是这类社区资源更新频率不一有的技能包很久没维护了里面的命令或格式可能已经过时。用的时候保持参考不盲从的心态把优秀的部分吸收过时的部分自己改写成适合自己的。我的经验是Skills 这东西自己动手写的永远比抄来的管用。因为你自己最清楚项目的痛点和团队的规范。社区资源的意义是给你灵感告诉你原来还可以这样沉淀经验最终还是要落到自己项目的实际需求上。7. 和 Codex CLI、Claude Code、Pi 同场竞技我为什么还在用 opencode7.1 四款智能体的横向对比用了这么久群里被问得最多的就是opencode、Codex CLI、Claude Code、Pi 到底哪个好用。这个问题其实没有标准答案因为每款工具的侧重点和擅长领域不一样。我按自己了解的情况整理了一张对比表维度opencodeClaude CodeCodex CLIPi开源情况完全开源闭源官方开源部分开源模型绑定多模型自由切换以 Anthropic 模型为主以 OpenAI 模型为主绑定自家/指定模型安装方式npm / Go / 桌面版官方脚本npm / 官方渠道官方渠道IDE 插件VSCode JetBrains有扩展支持集成在 OpenAI 生态有配套工具Skills 机制原生支持支持有限看版本项目记忆AGENTS.mdCLAUDE.md类似机制有浏览器测试支持 Playwright支持有限有限这张表只是我目前了解的大致情况版本更新太快细节可能随时变化。7.2 各自的适用场景选型不是选最好的而是选最匹配你工作流和偏好的。我的观察是这样的Claude Code 的优势在于 Anthropic 模型的自然语言理解和长上下文处理能力强写代码时懂人话的程度很高很多复杂重构任务交给它沟通成本低。缺点是闭源有一定技术栈绑定而且官方模型价格不便宜。Codex CLI 背靠 OpenAI 生态如果你们公司已经重度使用 OpenAI 的 API衔接会很顺畅。它和 GitHub、IDE 的联动做得不错适合已经泡在 OpenAI 生态里的人。缺点是如果你平时用的是 Anthropic 或 Google 的模型就不太合适。Pi 的定位更轻量界面和交互做得比较顺手适合快速问答和小范围改代码。它给我的感觉是日常辅助强于大型重构重度复杂的多文件任务表现相对普通。opencode 在里面最突出的特点是开放和灵活。模型随便换配置全在本地开源意味着你可以自己改它甚至接入内部系统。对于我这种今天用这个模型明天想试试那个模型的开发者来说它是唯一一个不逼我做选择的工具。7.3 我的选型思路我现在的搭配是主力日常用 opencode因为它多模型切换最自由一个工具能覆盖我手头的所有项目涉及特别复杂的架构设计讨论时我会临时切到 Claude Code因为它的对话理解能力确实强适合头脑风暴型任务Codex CLI 主要在我需要和 GitHub Actions、OpenAI 生态联动的场景下用。Pi 装过但用得少主要是界面确实舒服轻任务时会顺手用一下。这里想多说一句工具比较网上天天有但每个项目的代码库结构、技术栈、团队习惯都不同别人的使用体验只能当参考。最靠谱的做法是给自己半天时间四个都装上拿一个真实的中等难度任务各跑一遍看哪个最顺手。工具是为你服务的不是用来集邮的。8. 实战踩坑记录与上手建议8.1 我遇到过的几个典型错误两个月用下来我踩过的坑不算少挑几个有代表性的列出来希望你能绕开。第一个是error: unexpected server error. check server logs。这个报错我见过好几次第一次遇到以为 opencode 坏了折腾了半天。后来发现大部分时候是模型服务端返回了异常比如模型名称不存在、API Key 对应的模型权限不足、或者模型服务本身在限流。处理思路很直接先在同一个终端里用curl之类的工具直接请求一次模型 API看能不能通。如果直接请求也有问题那是模型服务的事如果直接请求正常而 opencode 报错再去看配置里的模型名和 Key 是不是对的。第二个是改了配置文件不生效。opencode 的配置有全局和项目两个层级项目级配置会覆盖全局配置。有时候你明明改了全局配置里的模型项目里跑起来还是旧的是因为项目根目录的opencode.json里也写了一个模型把全局的覆盖了。排查时先看当前项目有没有项目级配置文件别在全局文件里反复折腾。第三个是长会话越来越慢、效果变差。这是所有智能体工具的共性问题上下文窗口再大也有限。当你发现它开始忘事或者理解偏移正确的做法不是继续追问而是开一个新会话把关键背景重新交代一遍最好让它先读一遍 AGENTS.md。很多情况下重启会话比努力挽回旧会话高效得多。8.2 新手上手的顺序建议如果让我给一个完全没用过 opencode 的人规划学习路径我会建议按这个顺序来第一步先装好、把模型配通跑一个最简单的任务比如帮我把 README 里的错别字改了。确认它能正常读写文件、执行命令就行。第二步学会/init生成 AGENTS.md并手动补充项目的关键信息。这一步决定了后续所有会话的上下文质量。第三步尝试一个中等规模的真实任务比如把某个模块的错误处理统一重构一下。观察它的工作计划学会在计划不合理时打断和纠正。第四步开始配置自己的 Skills把你最常做的任务流程固化下来。同时维护 AGENTS.md 里的规则让工具的默认行为越来越贴合你的习惯。第五步再探索 Playwright 这类进阶能力让它具备自己验证自己的能力。按这个顺序走基本上一周内就能进入顺手的状态。8.3 一点个人体会最后说点不那么技术的话。我见过很多人用这类工具的心态是让 AI 帮我把活干完然后发现质量不行又收回来自己干来回几次就下结论说AI 编程不靠谱。但我自己的体会是AI 编码智能体更像是一个需要管理的执行者它的产出质量取决于你交代任务的质量也取决于你有没有给它沉淀足够的项目上下文。把 AGENTS.md 写好、把常用流程固化成 Skills、在关键节点人工审查这几件事做好了opencode 就是一个相当得力的队友。它不会取代你思考但它能把那些重复的、搜索式的、机械的工作从你身上卸下来让你把精力留在真正需要判断力的事务上。在我现在的日常里opencode 已经变成了和编辑器、终端并列的固定工作台之一。它不是完美到无可替代但开源、本地配置、多模型自由切换这一点恰好满足了我对工具的全部核心诉求。如果你也是那种喜欢掌控工具、而不是被工具绑架的人它值得你花一个周末来试试。
我是在一个加班到晚上十一点的周五晚上第一次装上 opencode 的。当时项目里堆了十几个 issue传统的工作流已经让我提不起劲打开编辑器翻代码猜上下文改完再跑测试发现问题又得回头改。我真正想要的是一个能在终端里听我说话、自己翻代码、自己跑命令、把改动直接落到文件里的工具而不是又一个只会生成代码片段的聊天框。opencode 就是冲着这个需求来的。它是做 serverless 框架 SST 的那个团队Anomaly 公司开源的一款 AI 编码智能体定位很明确终端优先、配置本地化、支持多模型、能真正读写文件并执行命令。到 2.0 版本之后又补上了桌面版、VSCode 插件、JetBrains 插件生态一下子完整了不少。这两天在各个技术群里关于它的讨论热度明显在涨问安装、问配置、问和 Codex CLI / Claude Code 对比的声音特别多。这篇文章不是官方文档的翻译而是我这两个月实际用下来的经验整理从安装报错怎么排查到模型怎么配才省钱再到 Skills、Memory、Playwright 这些进阶玩法和真实踩坑记录。如果你正准备上手 opencode或者已经装了但用不顺手这篇应该能帮你省下不少折腾时间。1. opencode 到底是什么一个不甘心只做“聊天助手”的开源编码智能体1.1 出身与定位SST 团队为什么做这个很多人第一次听到 opencode第一反应是SST 不是做无服务器框架的吗怎么跑来做 AI 工具了。没错正是那个团队。可能正因为常年做开发者基础设施他们对开发者工作流的理解非常实际AI 编程工具不应该是一个网页对话框而应该待在你本来就在的地方——终端和编辑器里。opencode 和 Claude Code、Codex CLI 是同一类东西业内管这类工具叫 terminal AI coding agent。它们和普通 AI 编程助手的核心区别不在聊天能力而在动手能力能递归读取项目文件理解整个代码库的结构和上下文能直接创建、修改文件而不是只给你一段代码让你自己粘贴能执行 shell 命令跑测试、跑构建、看报错能基于命令输出自我修正多轮迭代直到任务完成opencode 开源是它很大的一个卖点。代码全部公开配置存在本地不强制绑定某一家模型厂商。你可以把 Anthropic、OpenAI、Google 的模型甚至本地用 Ollama 跑的模型都配置进去同一个工具随时切换。这一点对我这种喜欢东用一下西用一下的人来说非常友好。1.2 它和传统 AI 编程工具有什么本质区别如果你用过 Copilot 时代的补全工具再用 opencode体感是完全不同的。补全工具是你写它猜智能体是你下达目标它自己干。举个我真实经历的例子有次我接了个活要把项目里所有硬编码的错误提示文案抽到一个 i18n 文件里。以前这种活我要手动开十几个文件一行一行找出来改。用 opencode我只说了一句把 src 下所有硬编码的中文错误提示抽到 locales/zh-CN.ts更新所有引用跑一遍测试确认没破。它自己先列了改动清单然后逐个文件改再跑 yarn test中途发现有个测试用例断言的是旧文案又自己改掉最后把结果汇报给我。整个过程我基本只在旁边看偶尔喊停。这种目标驱动的工作方式把 AI 从配角变成了真正干活的角色。它不再是你问一句它答一句而是你交代一个目标它自己规划路径、执行、验证、交付。1.3 适合谁不适合谁先说明白opencode 不是给所有人的。适合的人有一定命令行基础、日常用终端或者 IDE 重度开发的程序员想要一个能真正干活、而不是只会建议的 AI 工具的人做全栈或者前端、经常需要改一堆相关文件的场景喜欢自己掌控模型选择、不想被厂商锁定的人。不适合的人完全没接触过命令行的新手可能先从编辑器里的 AI 插件上手更舒服对AI 直接改代码这件事接受度低、必须自己逐行手敲的人以及希望工具开箱即用、不想花十分钟看配置文档的人。opencode 的安装和配置已经不算复杂但它毕竟是个面向开发者的开源工具默认假设你有点折腾能力。2. 装好 opencode从下载、PATH 到“cmdlet 无法识别”的解决思路2.1 三种安装方式怎么选我接触到的 opencode 安装方式主要有三种npm 安装、Go 安装、桌面版安装。三种我都试过各有适用场景。第一种npm 全局安装。如果你平时用 Node.js 开发这是最顺的一条路npm install -g opencode-ai装完直接opencode就能进交互界面。我最早就是这条路装的前后不到一分钟。需要留意的是npm 包名可能会随版本调整安装前最好去官方仓库确认一下当前的名字别凭记忆装错包。第二种Go 安装。如果你机器上有 Go 环境也可以用go install github.com/sst/opencodelatest装完的可执行文件在$(go env GOPATH)/bin下。这种方式适合本来就在 Go 生态里的人或者 npm 这边出了奇怪的权限问题作为备选。网上有些人说opencode go 需要配合 cc switch 等工具来管理模型配置其实 go 安装和 npm 安装得到的核心程序是一样的区别只是装到哪个目录、由谁管理版本后面配模型时统一走配置文件即可。第三种桌面版。opencode 官方提供了桌面客户端有图形界面适合不想碰终端、或者想把 opencode 当作一个独立 App 来用的人。桌面版内置了终端面板本质上还是同一套引擎外面套了一层壳。我个人的建议是如果你主力开发在终端或 IDE 里用前两种就够桌面版更像是独立工具党的选择。2.2 Windows 下最常见的“无法识别”报错排查很多人在 Windows 上装完 opencode兴冲冲打开 PowerShell 敲opencode结果看到这么一行红字opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写如果包括路径请确保路径正确然后再试一次。我第一次看到这个报错也愣了一下以为安装失败了。后来排查多了才明白这条报错的本质是系统在 PATH 环境变量列出的所有目录里都没找到 opencode 这个可执行文件。也就是说程序可能装上了但系统看不见它。常见原因有这么几个按概率排序npm 全局安装目录不在 PATH 里。这是最普遍的原因。npm 全局包的安装目录默认不是 Windows 系统 PATH 的一部分你要手动把它加进去。安装过程失败或者没装完。比如权限不足npm 静默跳过了一些写入。这种重新用管理员权限装一次就好。装完后没重开终端。PATH 是 shell 启动时加载的你装完立刻敲命令当前这个 shell 还是旧环境。用了 nvm、fnm 这类 Node 版本管理工具。PATH 是由版本管理工具动态注入的不同 shell 加载的路径可能不一致。排查的步骤我建议按这个顺序来node -v npm -v npm prefix -g npm ls -g --depth0第一条和第二条确认 Node 环境本身没问题第三条确认 npm 全局包装到了哪个目录第四条确认 opencode 确实在全局包里。如果npm ls里能看到 opencode说明装成功了纯粹是 PATH 问题。接下来把 npm 全局目录加进用户 PATH。PowerShell 里可以直接执行setx PATH $env:APPDATA\npm;%PATH%setx会写进用户环境变量改完一定要新开一个终端窗口再试。如果你不想改全局 PATH临时方案是直接用完整路径调用$env:APPDATA\npm\opencode.exe但这个只能救急长期用还是改 PATH 省心。2.3 验证安装与目录结构装好并解决了 PATH 问题后先跑一下版本号确认安装完整opencode --version能正常输出版本号就说明核心程序没问题。opencode 的配置和数据默认放在用户目录下Linux/macOS 是~/.config/opencode/Windows 是%USERPROFILE%\.config\opencode\里面有全局配置文件、日志等每个项目的配置则放在项目根目录的opencode.json或.opencode/目录里。熟悉这个目录结构挺重要后面改模型配置、加 Skills 都要往这里放东西。建议第一次启动前先确认自己有可用的模型 API Key不然进去会卡在选择模型的环节。第一次真正跑起来的体验很重要别让配置把你劝退了。3. 模型配置是重中之重免费模型、多 Provider 与 CC Switch 协同3.1 先搞懂 opencode 的模型路由逻辑opencode 的模型配置思路很清晰它本身不生产模型只负责把请求路由到你配置好的模型服务上。在配置文件里声明 provider模型提供商再指定默认用哪个模型的哪个版本。全局配置文件位于~/.config/opencode/opencode.json项目级配置文件放在项目根目录支持opencode.json。一个典型的全局配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-5, provider: { openai: { api_key: {env:OPENAI_API_KEY}, models: [gpt-4o, gpt-4o-mini] }, ollama: { models: [qwen2.5-coder:14b] } } }这里有个关键点api_key可以用{env:变量名}的形式引用环境变量我强烈建议你这么做而不是把 Key 明文写进配置文件。一个是安全问题另一个是配置文件可能会被提交到 Git 仓库Key 一旦上去就收不回来了。我用了个笨办法——把配置模板提交到仓库真实 Key 只存在本地环境变量里这样换机器也不怕丢。模型名的格式通常是provider/model因为同一个提供商下面可能有多个模型版本配置时把你要用的都列进models数组运行时可以用快捷键切换非常方便。3.2 免费模型怎么接本地模型和免费额度opencode 免费模型是很多人搜得最多的关键词也确实是最容易踩坑的地方。先说结论opencode 本身是免费的但模型服务是要花钱的——除非你用免费额度或者本地模型。第一种方案是本地模型用 Ollama 跑开源模型。装好 Ollama 后拉一个代码模型下来ollama pull qwen2.5-coder:14b然后在配置里加上对应的 provider就能在 opencode 里选到本地模型。好处是完全免费、数据不出本机、没有限流坏处是效果和大厂闭源模型有差距尤其复杂代码重构这种任务14B 模型经常力不从心。我的经验是本地模型适合做小改动、写测试、改文案这类轻任务重活还是交给云端模型。第二种方案是各家云厂商的免费额度。OpenAI、Google、Anthropic 以及一些模型服务平台都会给新用户一定量的免费调用额度把对应的 API Key 配进去就能用。这种方案的优点是模型能力强缺点是额度有限用完了就得付费或者换一家。免费额度通常有有效期和速率限制别拿来做自动化流水线。第三种方案是社区维护的免费模型端点。这类端点确实存在过网上也一直有讨论比如最近就有人在问某个免费端点是不是下线了。我的态度很明确社区免费端点的稳定性没法保证今天能用明天可能就挂了而且 Key 和流量都要经过第三方敏感项目千万别用。玩玩可以干正事强烈不建议。3.3 用 CC Switch 管理多套配置当你同时用 opencode、Claude Code、Codex CLI 几个工具每个工具又要配置不同的模型和 Key 时配置管理就开始变得烦人。每个工具一套配置文件换模型要开好几个文件去改很容易改出问题。CC Switch 解决的就是这个问题。它是一个用来管理多套模型配置的图形化小工具可以把你常用的配置组合模型名、接口地址、API Key存成一个个配置档然后在不同配置档之间一键切换。它支持的配置档可以导出给 opencode、Claude Code、Codex 等多个工具使用相当于给所有 AI 编程工具做了一个统一的配置遥控器。我现在的用法是在 CC Switch 里存三套配置档一套用 Anthropic 的模型一套用 OpenAI 的模型一套用某个开源模型的商业托管版本。接不同项目时一键切过去opencode 那边读到的配置就变了。省去了每次都要打开 JSON 文件手动改 Key 和模型名的麻烦。不过要注意CC Switch 这类工具本质上是替你写配置文件它改的是 opencode 的配置文件内容。所以你还是得理解前面那个 JSON 的结构不然切换出问题的时候会一脸懵。工具负责效率原理负责兜底。3.4 配置文件里的几个常见坑我配置过程中踩过的坑挑三个典型的说。第一个坑是环境变量引用格式不对。{env:OPENAI_API_KEY}这套语法有的版本支持有的地方要求直接写$OPENAI_API_KEY如果你照着老教程配完发现 Key 没被识别先检查是不是格式问题。判断方法很简单在 opencode 里跑一个简单请求看日志里有没有报鉴权失败。第二个坑是 models 数组和默认 model 不一致。你声明了 provider但全局model字段写了一个 provider 里不存在的模型启动时就会报错或者说模型找不到。改配置后一定要确认两边的模型 ID 拼写一致别少个后缀多个横杠。第三个坑是项目管理器和模型 provider 的命名冲突。你看网上教程的时候会发现provider 的名字在不同版本里可能有差异比如 Ollama 接口遵循 OpenAI 兼容格式有的人就配成了 openai provider 的 custom baseURL有的人配成独立的 ollama provider。两种思路都有人用但混着来容易乱。我的建议是本地模型用独立的 provider 配置云厂商模型用官方 provider逻辑清楚排查也容易。4. 建会话、下命令、看智能体干活opencode 的核心使用逻辑4.1 终端界面与会话基本操作装好配好后在项目目录里敲opencode会进入一个交互式 TUI 界面。顶部是输入框中间是会话内容区底部有快捷键提示。整个界面是终端原生的不依赖浏览器SSH 到服务器上也能用这点很对得起终端优先的定位。基本操作逻辑和大多数终端聊天工具类似输入自然语言指令回车发送AI 开始处理。会话历史会保存在本地下次opencode --continue可以接续上次的对话继续干活不用重新交代上下文。这是个很容易被忽略但实际很重要的功能——AI 编程往往需要多轮迭代断一次会话从头再来非常让人崩溃。在会话中你可以临时切换模型。我一般默认用能力强的大模型做规划中途遇到简单机械的改动切换到快一点、便宜一点的模型能让成本降不少。具体快捷键不同版本略有差异进去之后按?看帮助就懂了。4.2 Agent 的工作循环从计划到执行很多第一次用 opencode 的人会困惑它到底是怎么干活的核心是一个循环解析任务 → 制定计划 → 调用工具执行 → 观察结果 → 调整计划 → 再执行直到任务完成或者被你喊停。opencode 内置了几类关键工具文件工具读取文件、写入文件、列目录这是它改代码的基础命令工具在项目里执行 shell 命令比如npm test、git diff搜索工具在代码库里按语义或正则搜索定位相关代码Web 工具抓取网页、查文档通常用于解决依赖报错或查阅 API浏览器工具可以调用 Playwright 操作浏览器用来测前端页面后面细说每次它要执行一个操作时界面上会显示意图和结果。你可以随时打断也可以让它继续。我建议在前几次使用时不要全程当甩手掌柜而是观察它的计划是否合理。比如让它改一个问题时如果它打算动一个明显不相干的文件这时候打断它还来得及等它改错了再回来解释就麻烦了。4.3 让 opencode 接手开发项目的正确打开方式opencode 接手开发项目是个很诱人的说法但千万不能一上来就丢给它一个把这个项目的功能做完这种巨型指令。我的经验是把它当成一个能力很强但需要明确边界的新同事任务颗粒度要合适期望目标要清晰验收标准要提前说。一个比较科学的下指令框架是背景 目标 约束 验证方式。举个例子不要说把这个页面的样式改好看点而是说登录页的按钮在移动端被键盘顶起来了固定底部栏盖住了输入框。请修复这个布局问题保持现在的设计风格不变只改相关组件的样式文件。改完后在本地跑一遍构建确认没有报错。有背景什么问题、有目标修复布局、有约束不动设计、有验证跑构建。这样 AI 能快速定位范围不会跑去重构你整个项目的 CSS。还有一个技巧让 opencode 在大动作前先输出计划确认后再执行。大多数智能体工具都有 plan 模式或类似功能opencode 也支持先规划再动手。对付十几个文件以上的重构任务这个步骤能救你很多次。4.4 几个我每天都在用的命令和技巧除了自然语言对话opencode 还支持一些快捷操作我挑几个常用的opencode在项目目录启动进入交互界面opencode --continue接续上次会话/init让 opencode 分析项目结构并生成一份项目说明文件AGENTS.md相当于给它自己建立上下文手册/help查看可用命令和快捷键会话中输入!开头可以直接执行 shell 命令不用退出界面/init这个命令特别推荐。它生成的 AGENTS.md 里包含项目结构、技术栈、开发和测试命令等关键信息后续每次会话 opencode 都会自动把这份文件当作背景知识加载。相当于你先花五分钟教它咱们项目是怎么回事后面它干活的质量会有明显提升。这个文件和后面要说的 Memory 机制配合起来效果翻倍。5. 把 opencode 搬进 IDEVSCode 与 JetBrains 插件实战5.1 VSCode 插件侧边栏与选区上下文命令行用久了你会发现有些场景还是离不开 IDE比如看某个函数的调用链、对比改动前后的 diff、直接在断点前调试。所以 opencode 官方做了 IDE 插件让智能体能力可以直接在编辑器里用。VSCode 插件装好之后侧边栏会出现 opencode 面板本质上是在编辑器里内嵌了一个会话窗口。它比终端多一个很实用的能力可以直接把当前打开的文件、甚至选中的代码段作为上下文发送给 AI。比如你选中一段有问题的代码让 opencode 分析这段代码的 Bug它不需要先凭记忆找文件上下文就在眼前定位准确率会高很多。另外一个我很常用的场景是配合 Git 工作。改完代码后让 opencode 帮忙看一下git diff生成 commit message或者让它检查这次改动有没有遗漏的引用。因为这些操作都围绕当前工作区IDE 插件的上下文感知比纯终端要自然。安装 VSCode 插件之后第一次使用会要求指定 opencode 可执行文件的路径。如果插件提示找不到 opencode多半是前面 PATH 问题的余波——把 opencode 的完整路径填进插件设置里就能解决。5.2 JetBrains IDEA 插件与 Maven 项目配置JetBrains 全家桶的插件也是类似思路在 IDEA、PyCharm 等产品的 Marketplace 里搜 opencode 就能安装。它同样支持侧边栏会话、选中代码发送上下文、查看 AI 对文件的改动。不过 Java 项目这边有个特有的坑opencode 要在项目里执行命令时依赖你机器上已经配置好的构建工具比如 Maven。如果你在终端里执行mvn是好的但 opencode 在 IDEA 里执行mvn test却报错找不到命令通常是因为 IDEA 内置终端的环境变量没有继承你用户配置的 PATH尤其在你用 IDEA 自带的 JBR 时更容易出现。解决办法有两个层面。一是确保 Maven 本身配置正确包括M2_HOME环境变量、mvn在 PATH 中二是让 opencode 知道的 JDK 路径.mvn目录下可以配置toolchains.xml或者直接在会话里告诉 opencode 用 jdk 17 跑 mvn test。我实际用下来大部分 Maven 相关报错都不是 opencode 的问题而是环境变量没打通。先在系统终端里把mvn -v跑通再去排查 opencode 那边就简单了。5.3 终端和插件到底该用哪个用了这两周我的感受是终端和 IDE 插件不是替代关系而是各有分工。终端适合整个项目的活——重构、批量改文件、跨多个模块的任务让它自己有充分的自由度在代码库里搜索和修改。这类任务在终端里跑反而清爽不会被编辑器内嵌面板限制。IDE 插件适合当前文件附近的活——分析一段代码、解释报错、生成单测、检查 git diff这些任务强依赖你眼睛正在看的上下文插件有天然优势。我现在的习惯是白天写代码时在 VSCode/IDEA 里开着插件面板处理局部问题需要大范围改动时开一个终端对着项目根目录跑 opencode 会话晚上走之前看一眼所有待办挑几个能委派的丢给 opencode第二天早上看结果和汇报。6. 再进一步Skills、Memory 与 Playwright把 opencode 调教成老手6.1 Skills给智能体装技能包如果你用过 Claude Code 的 skills对 opencode 的 Skills 机制会非常熟悉。它本质上是一组预设能力和行为规范的打包把一个任务的专业流程、注意事项、处理模板写成结构化文档放在指定目录下当任务命中时opencode 会自动加载这套指令来执行。举个例子。我在团队里负责代码评审以前每次 review PR 都要靠脑内清单先看改动范围、再看核心逻辑、检查错误处理、最后看测试覆盖。后来我把这套流程写成了一个 Skill命名为 code-review内容包含评审顺序和重点检查项常见反模式清单输出格式要求必须按问题严重度 文件位置 修改建议输出之后我让它 review 代码时它会自动加载这个 Skill按我定义的流程工作输出质量比我临时口头描述稳定得多。对于一个团队来说这相当于把资深工程师的经验沉淀成了可复用的资产。创建 Skill 的流程不复杂在~/.config/opencode/skills/下建一个目录目录里放一个 SKILL.md 写说明和步骤需要的话再加一些辅助脚本。具体格式建议看官方文档版本更新比较快。社区里也有不少人分享现成的 Skills 集合比如 Superpowers 这类项目把很多成熟的技能包做了整合虽然最初可能为别的工具设计但格式相通思路可以迁移过来——装上后试一下能用就留着不行就当作参考自己改写。6.2 Memory让 opencode 记住项目规矩Memory 机制解决的是每次都要重新交代项目背景的痛点。opencode 读取项目根目录的 AGENTS.md 作为项目级记忆读取用户配置目录下的 AGENTS.md 作为个人级记忆这些文件会在每次会话时自动作为系统背景注入相当于给智能体一本员工手册。我在项目 AGENTS.md 里一般会写这几类内容项目技术栈和目录结构让它快速知道什么东西在哪开发和测试命令比如npm run dev、pnpm test代码规范比如组件统一用函数式写法错误文案必须走 i18n一些特殊约定比如不要改 generated 目录下的文件数据库迁移必须经过确认这些内容写好了opencode 的行为边界就清晰了不会动不动踩到你的红线。我观察到一个规律AGENTS.md 写得越具体AI 的失误率越低。它就像给新同事的 onboarding 文档质量直接决定这个人干活靠不靠谱。Memory 要和 Skills 配合使用AGENTS.md 负责记住规矩Skills 负责知道怎么做。一个是背景知识一个是操作流程合在一起才是完整的老手状态。6.3 用 Playwright 复现和定位前端 Bug前端项目的 Bug 是最难用想来定位的光看代码往往看不出问题必须跑起来看页面表现。opencode 支持通过 Playwright 调用浏览器来测试前端页面这让它可以做复现 Bug → 定位问题 → 修复 → 验证的完整闭环。我实际用下来的操作流程是这样的。先在会话里给它描述 Bug比如列表页点击筛选后URL 参数变了但数据没刷新。然后让它用 Playwright 打开本地开发服务器访问对应页面执行筛选操作观察网络请求和页面状态。它会把操作过程、页面截图、控制台报错原样带回来然后基于这些信息定位代码问题。有一次它发现筛选条件变化后请求参数没带上最新的 state顺着组件树找到了一个有闭包陷阱的 handler自己修完又用 Playwright 跑了一遍同样的操作确认修复生效。我在旁边看着它从头到尾把前端 Bug 的完整链路走了一遍说实话当时有点感慨这就是以前一个中级前端工程师干的事。用 Playwright 测前端有一个实用技巧让 opencode 先写一个最小化的复现脚本而不是直接让它全量跑你的 E2E 测试套件。最小化复现脚本跑得快、失败信息明确定位效率高得多。等它确认修好了再跑完整的测试套件做回归。6.4 社区技能集Superpowers 这类资源的接入思路现在围绕这类智能体工具社区里已经形成了一个生态各种 Skills 集合层出不穷Superpowers 就是其中很出名的一个。它的思路是把很多资深工程师的工作方法固化成一个个可加载的技能包从如何写设计文档到如何进行调试都有现成的模板。接入思路很简单把技能包的内容下载下来按 opencode 的 Skills 目录格式放好然后在 AGENTS.md 里提示 opencode遇到 XX 类任务时优先使用对应 Skill。要注意的是这类社区资源更新频率不一有的技能包很久没维护了里面的命令或格式可能已经过时。用的时候保持参考不盲从的心态把优秀的部分吸收过时的部分自己改写成适合自己的。我的经验是Skills 这东西自己动手写的永远比抄来的管用。因为你自己最清楚项目的痛点和团队的规范。社区资源的意义是给你灵感告诉你原来还可以这样沉淀经验最终还是要落到自己项目的实际需求上。7. 和 Codex CLI、Claude Code、Pi 同场竞技我为什么还在用 opencode7.1 四款智能体的横向对比用了这么久群里被问得最多的就是opencode、Codex CLI、Claude Code、Pi 到底哪个好用。这个问题其实没有标准答案因为每款工具的侧重点和擅长领域不一样。我按自己了解的情况整理了一张对比表维度opencodeClaude CodeCodex CLIPi开源情况完全开源闭源官方开源部分开源模型绑定多模型自由切换以 Anthropic 模型为主以 OpenAI 模型为主绑定自家/指定模型安装方式npm / Go / 桌面版官方脚本npm / 官方渠道官方渠道IDE 插件VSCode JetBrains有扩展支持集成在 OpenAI 生态有配套工具Skills 机制原生支持支持有限看版本项目记忆AGENTS.mdCLAUDE.md类似机制有浏览器测试支持 Playwright支持有限有限这张表只是我目前了解的大致情况版本更新太快细节可能随时变化。7.2 各自的适用场景选型不是选最好的而是选最匹配你工作流和偏好的。我的观察是这样的Claude Code 的优势在于 Anthropic 模型的自然语言理解和长上下文处理能力强写代码时懂人话的程度很高很多复杂重构任务交给它沟通成本低。缺点是闭源有一定技术栈绑定而且官方模型价格不便宜。Codex CLI 背靠 OpenAI 生态如果你们公司已经重度使用 OpenAI 的 API衔接会很顺畅。它和 GitHub、IDE 的联动做得不错适合已经泡在 OpenAI 生态里的人。缺点是如果你平时用的是 Anthropic 或 Google 的模型就不太合适。Pi 的定位更轻量界面和交互做得比较顺手适合快速问答和小范围改代码。它给我的感觉是日常辅助强于大型重构重度复杂的多文件任务表现相对普通。opencode 在里面最突出的特点是开放和灵活。模型随便换配置全在本地开源意味着你可以自己改它甚至接入内部系统。对于我这种今天用这个模型明天想试试那个模型的开发者来说它是唯一一个不逼我做选择的工具。7.3 我的选型思路我现在的搭配是主力日常用 opencode因为它多模型切换最自由一个工具能覆盖我手头的所有项目涉及特别复杂的架构设计讨论时我会临时切到 Claude Code因为它的对话理解能力确实强适合头脑风暴型任务Codex CLI 主要在我需要和 GitHub Actions、OpenAI 生态联动的场景下用。Pi 装过但用得少主要是界面确实舒服轻任务时会顺手用一下。这里想多说一句工具比较网上天天有但每个项目的代码库结构、技术栈、团队习惯都不同别人的使用体验只能当参考。最靠谱的做法是给自己半天时间四个都装上拿一个真实的中等难度任务各跑一遍看哪个最顺手。工具是为你服务的不是用来集邮的。8. 实战踩坑记录与上手建议8.1 我遇到过的几个典型错误两个月用下来我踩过的坑不算少挑几个有代表性的列出来希望你能绕开。第一个是error: unexpected server error. check server logs。这个报错我见过好几次第一次遇到以为 opencode 坏了折腾了半天。后来发现大部分时候是模型服务端返回了异常比如模型名称不存在、API Key 对应的模型权限不足、或者模型服务本身在限流。处理思路很直接先在同一个终端里用curl之类的工具直接请求一次模型 API看能不能通。如果直接请求也有问题那是模型服务的事如果直接请求正常而 opencode 报错再去看配置里的模型名和 Key 是不是对的。第二个是改了配置文件不生效。opencode 的配置有全局和项目两个层级项目级配置会覆盖全局配置。有时候你明明改了全局配置里的模型项目里跑起来还是旧的是因为项目根目录的opencode.json里也写了一个模型把全局的覆盖了。排查时先看当前项目有没有项目级配置文件别在全局文件里反复折腾。第三个是长会话越来越慢、效果变差。这是所有智能体工具的共性问题上下文窗口再大也有限。当你发现它开始忘事或者理解偏移正确的做法不是继续追问而是开一个新会话把关键背景重新交代一遍最好让它先读一遍 AGENTS.md。很多情况下重启会话比努力挽回旧会话高效得多。8.2 新手上手的顺序建议如果让我给一个完全没用过 opencode 的人规划学习路径我会建议按这个顺序来第一步先装好、把模型配通跑一个最简单的任务比如帮我把 README 里的错别字改了。确认它能正常读写文件、执行命令就行。第二步学会/init生成 AGENTS.md并手动补充项目的关键信息。这一步决定了后续所有会话的上下文质量。第三步尝试一个中等规模的真实任务比如把某个模块的错误处理统一重构一下。观察它的工作计划学会在计划不合理时打断和纠正。第四步开始配置自己的 Skills把你最常做的任务流程固化下来。同时维护 AGENTS.md 里的规则让工具的默认行为越来越贴合你的习惯。第五步再探索 Playwright 这类进阶能力让它具备自己验证自己的能力。按这个顺序走基本上一周内就能进入顺手的状态。8.3 一点个人体会最后说点不那么技术的话。我见过很多人用这类工具的心态是让 AI 帮我把活干完然后发现质量不行又收回来自己干来回几次就下结论说AI 编程不靠谱。但我自己的体会是AI 编码智能体更像是一个需要管理的执行者它的产出质量取决于你交代任务的质量也取决于你有没有给它沉淀足够的项目上下文。把 AGENTS.md 写好、把常用流程固化成 Skills、在关键节点人工审查这几件事做好了opencode 就是一个相当得力的队友。它不会取代你思考但它能把那些重复的、搜索式的、机械的工作从你身上卸下来让你把精力留在真正需要判断力的事务上。在我现在的日常里opencode 已经变成了和编辑器、终端并列的固定工作台之一。它不是完美到无可替代但开源、本地配置、多模型自由切换这一点恰好满足了我对工具的全部核心诉求。如果你也是那种喜欢掌控工具、而不是被工具绑架的人它值得你花一个周末来试试。
