如果你最近在折腾AI编程工具大概率会看到opencode这个名字频繁出现。它来自SST团队一个做开发者基础设施的开源组织和Claude Code、OpenAI Codex这类老牌终端Agent放在一起比较时opencode最显眼的标签就是开源、多模型、终端原生以及一套非常干净的配置文件体系。我大概是两周前把日常主力Agent从Claude Code切到了opencode起因倒不是Claude Code不好用而是项目里的MCP服务越来越多、模型也想在不同供应商之间换来换去Claude Code的配置体系越卷越重。opencode把这一切收敛成了两个JSON文件加一个本地服务模型可以随时换运行日志也透明这对我是刚需。这篇文章就记录我这段时间的完整上手过程从安装到配置免费模型从Skills到Memory从VSCode/IDEA插件到用Playwright让Agent自己复现前端Bug还包含大量报错排查记录希望给正在观望或者已经装上但没玩明白的朋友一份能直接照着做的参考。1. opencode是什么一个重新思考过的终端AI编程Agent1.1 为什么我从Claude Code迁移过来先说结论不是Claude Code不好而是opencode更适合“模型中立”的开发者。Claude Code很强但它的配置和生态始终围绕Anthropic的模型展开一旦你想换成别的模型或者想在同一套Agent里对比各家模型的表现就会觉得很别扭。opencode在这一点上做得非常彻底。它的模型抽象层基于Vercel AI SDK只要是OpenAI兼容格式的API都能接进来甚至你可以自定义一个本地兼容服务把请求路由到任意模型上。对我来说这意味着同一个项目、同一套Skills、同一条指令我可以随时在Claude、Gemini、本地模型之间切换而不需要改任何业务代码。还有一个让我愿意切换的关键点是透明。opencode安装后会启动一个本地服务所有请求和响应都会记录在日志里出了问题可以直接看请求报文和响应报文。之前用Claude Code时遇到“Agent自己改了配置”“上下文被悄悄截断”这类问题排查起来非常痛苦。opencode把日志和diff都摊开给你看心态上踏实很多。1.2 与Codex、Claude Code、Pi的基础对比这几款终端Agent我最近都实际用过简单做个横向对比工具开源模型绑定配置复杂度上下文管理特色能力opencodeMIT开源不绑定任意OpenAI兼容模型中低JSON配置自动压缩手动MemoryLSP、Skills、MCP、桌面端、IDE插件齐全Claude Code闭源基本绑定Claude系列中官方封装较多CLI原生但定制空间有限Anthropic生态整合最深长上下文对话体验好OpenAI Codex闭源绑定OpenAI模型中依赖ChatGPT后台会话与ChatGPT产品联动好适合OpenAI全家桶用户Pi开源/闭源混合多模型但偏好特定厂商中高依赖外部网关主打聊天式编程多模态支持有亮点选型建议很简单如果你重度依赖Anthropic模型并且不打算换Claude Code已经是天花板如果你希望一套Agent配置同时应对多个模型供应商并且享受“改JSON等于换模型”的灵活度opencode更合适如果你每天都在ChatGPT Plus生态里工作Codex的集成度会让你更顺手。至于Pi我试下来觉得它更适合偏聊天交互的场景做严肃的工程重构时opencode的Plan/Build模式更可控。1.3 opencode适合什么类型的开发者从我的体验来看这批人最适合把opencode用起来开源项目维护者。需要频繁审视Agent提交的代码opencode的权限控制和diff展示非常友好不会让Agent乱动手脚。需要在多个模型之间切换对比的人。无论是比效果还是比成本opencode的模型配置就是一组JSON字段切换成本几乎为零。被桌面IDE卡到内存焦虑的人。opencode本体是一个终端TUI资源占用比Electron类编辑器小太多跑在老MacBook上很流畅。团队需要标准化Agent行为的人。Skills机制可以把团队的代码规范、测试流程、发布检查变成Agent自动执行的技能这是其他工具很难做到的。2. opencode安装从零到跑通第一个对话2.1 三种安装方式与选择建议opencode的安装方式很常规官方提供了脚本、npm和Homebrew三种渠道。我个人的建议是有Node.js环境就用npmmacOS用户用Homebrew也行最省心的其实是官方脚本。# 方式一npm全局安装需要Node.js npm install -g opencode-ai # 方式二Homebrew安装 brew install sst/tap/opencode # 方式三官方脚本 curl -fsSL https://opencode.ai/install | bash注意包名是opencode-ai不是opencode。很多人在npm上找不到或者装错包就是被这个名字坑了。Windows用户还可以用Scoop安装scoop install opencode但这个包未必是最新版本我的建议还是走npm。装完以后直接在项目目录下运行opencode会进入TUI交互界面。如果想跳过TUI直接执行任务可以这样opencode 帮我分析一下src/main.go的入口流程并输出调用关系这是opencode一个很香的设计非交互模式可以直接挂在CI或者脚本里用后面接--model参数还能临时切换模型比如强制用便宜的模型跑一遍快速检查。2.2 Windows报错“无法将‘opencode’项识别为cmdlet”的完整排查这个报错在热搜里出现了也是Windows用户装完后第一道坎。报错原文是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。别慌基本上只有两个原因。第一个原因是npm的全局安装目录根本不在你的PATH里。Node安装后全局包路径默认在C:\Users\你的用户名\AppData\Roaming\npm如果这个目录没加进系统变量无论装什么全局命令都跑不起来。排查方法很简单npm root -g把输出的路径添加到系统环境变量的Path里重开终端再试opencode --version。这时候如果还没好多半是PowerShell执行策略挡住了。npm会在全局目录下生成opencode.ps1而Windows默认执行策略可能禁止运行脚本报错就变成“无法加载...因为在此系统上禁止运行脚本”。执行下面这行放开当前用户限制即可Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里有个小坑RemoteSigned只信任远程签名脚本本地创建的ps1可以跑但如果是从网上直接下载的脚本可能还是会被拦。如果不想动执行策略也可以直接使用opencode.cmd它不会受这个限制影响。第二个常见原因是安装中断或者版本冲突。遇到这种情况先卸载再重装比人肉清残留变量快得多npm uninstall -g opencode-ai npm cache clean --force npm install -g opencode-ai重装后再用where.exe opencode验证命令路径。如果能看到路径输出说明命令本身已经生效了。2.3 首次启动认证、模型供应商与项目打开装好后第一次运行opencode最优先做的是认证。在TUI里输入/auth或者直接跑opencode auth login会进入一个交互式面板可以添加多个模型的API Key比如Anthropic、OpenAI、Google Gemini以及任意自定义供应商。我强烈建议用系统钥匙串来存Key而不是把Key写进终端环境变量。opencode在登录时会把Key安全地存到系统钥匙串里之后运行不会再让你反复粘贴。如果实在要用环境变量也记得以ANTHROPIC_API_KEY这类前缀命名而不是找个随便的变量名硬塞。首次启动时opencode会检查当前目录和上级目录里的配置文件包括opencode.json、AGENTS.md、CLAUDE.md等一旦发现项目级配置就会自动加载。所以打开项目的正确姿势是先cd到项目根目录再运行opencode。如果你在~下打开它能看到的项目上下文就是空白的回答质量会差很多。另外提一嘴opencode运行时会在本地起一个服务终端会打印出类似Local: http://127.0.0.1:xxxxx的信息这是IDE插件和桌面版连接它的通道不用关掉。如果端口被占可以在配置里改端口后面讲配置的时候会提到。3. opencode配置模型、参数与免费模型接入3.1 核心配置文件opencode.json与config.jsonopencode的配置体系很轻但不同版本之间有过命名调整早期版本用的是config.json后来统一成了opencode.json。所以网上教程经常打架有的人说改这个、有的人说改那个其实是版本差异。我的建议是先运行一次opencode让它生成默认配置然后用编辑器打开配置文件带JSON Schema提示的那份就是你要改的。opencode配置分两个层级。全局配置放在用户目录下作用于所有项目项目级配置放在项目根目录会覆盖全局配置。我习惯把全局配置只放API Key和通用偏好把模型列表、权限规则、MCP服务这些跟项目强相关的内容放在项目里这样clone一个新仓库时配置能跟着代码走。一个典型的配置文件长这样{ $schema: https://opencode.ai/config.json, autoupdate: true, theme: opencode, model: my-provider/my-model, provider: { my-provider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { my-model: { name: My Model } } } }, permission: { edit: ask, bash: ask, webfetch: allow } }provider定义了“模型从哪来”models定义“有哪些模型可选”model决定默认用哪个模型。这个结构非常直白只要理解一遍后面所有模型切换都靠它。3.2 免费模型接入的通用做法很多人问我opencode能不能用免费模型答案是可以而且配置思路和收费模型没有任何区别就是增加一个provider。只要对方提供OpenAI兼容APIopencode就能适配。最典型的免费渠道是Google Gemini系列。去官方平台申请一个API Key创建自定义provider填写兼容接口地址和Key就可以在opencode里用Gemini的免费额度了。以Gemini为例配置大概是这样{ provider: { gemini: { npm: ai-sdk/openai-compatible, name: Google Gemini (OpenAI Compatible), options: { baseURL: https://generativelanguage.googleapis.com/v1beta/openai/, apiKey: {env:GEMINI_API_KEY} }, models: { gemini-2.0-flash: { name: Gemini 2.0 Flash } } } } }另一个经常被用到的渠道是OpenRouter它的免费模型都带:free后缀配置方式就是设一个OpenAI兼容的providerbaseURL填https://openrouter.ai/api/v1然后在models里列出你想用的模型名。这里要提醒一句免费模型的稳定性参差不齐同一个模型一天之内响应速度可能差好几倍建议在opencode里配两个备选模型一个主力一个救急。网络上有些教程会推荐一些第三方聚合网关说什么hy3-free之类我的态度一直是小众网关适合临时折腾不适合当主力。这类服务挂掉就像吃饭吃到一半老板跑路既影响效率又没法追责真要用也一定要在项目配置里留好退路。3.3 常用配置参数与模型选择建议除了provider下面几个配置项几乎没有争议属于开箱必改。permission是最重要的安全开关。我默认开edit: ask和bash: ask这样Agent每次要改文件或者执行命令前都会征求我的意见虽然多了一步确认但能防止它脑补一个离谱的删库命令。如果你在写一个纯文档项目可以把edit改成allow省得烦如果你在做一个包含生产数据读取的运维脚本我建议把bash也改成deny彻底禁止Agent执行危险命令。autoupdate建议设成true。opencode迭代非常快旧版经常有奇奇怪怪的模型兼容问题自动更新能少踩很多坑。theme按个人喜好来我喜欢opencode默认主题高亮对比度适中长时间盯终端不疲劳。模型参数上代码任务我一般把temperature控制在0到0.3之间。超过0.5代码就开始“自由发挥”经常给你整出一些看起来很优雅但根本跑不起来的方案。想快速验证配置是否生效可以运行opencode models它会列出当前配置里所有可用的模型。如果这里看不到你新加的模型说明provider配置有问题优先检查baseURL和apiKey。4. 从聊天到写代码核心使用方式复盘4.1 Plan/Build双模式先规划再动手opencode的TUI里最核心的是Plan和Build两种模式。我把它理解为“先出方案再动代码”和真实团队里写方案再实施的工作流完全一致。在Plan模式下Agent会调研项目、分析代码、输出一份实施计划但不改任何文件。你可以把它当成一个免费的技术顾问先看它对整个任务的理解是否正确。确认方案没问题后Tab切到Build模式让它真正动手。这个设计让我避免了很多次“方向错了还改了一堆代码”的悲剧。举个例子有一次我让它重构一个用户登录模块。Plan模式下它发现了项目中已有一个我没有注意到的token刷新逻辑然后建议把新逻辑挂在现有拦截器上而不是另起一套。如果直接让它开干大概率会好心办坏事把原有鉴权逻辑一起推翻。Plan模式不是必须的流程但对于复杂重构花几十秒让它先列计划收益非常高。非交互模式也能使用Plan/Build模式区分命令大致是这样opencode 分析当前支付模块的异常处理列出需要加固的3个点 --agent plan挂上--agent plan参数opencode就只输出计划不碰代码。用脚本批量跑项目健康检查时这个功能非常实用。4.2 文件修改审批与LSP补全在Build模式下Agent每提出一个文件修改opencode都会把改动以diff形式展示给你。配合permission.edit: ask你可以逐文件审查确认无误后再应用。这里必须夸一下LSP集成这是opencode和普通聊天Agent最大的区别之一。它在本地会启动语言服务器意味着Agent“看到”的代码不是纯文本而是带类型信息、带编译错误的语义化代码。实际效果就是它改代码时会更合理比如自动补齐未导入的类型或者在你改了函数签名后同步提醒调用方需要调整。这对TypeScript项目尤其明显我在一个Vite React项目里让opencode改接口返回结构它居然自动把相关组件的类型标注一起修正了这一点很多同类工具做不到。如果你不想让Agent乱动格式可以在项目配置里把格式化工具交给Prettier让Agent只改逻辑不改格式。opencode本身支持外部格式化工具集成具体配置位是format字段设置成你的格式化命令即可。4.3 Skill机制给Agent装“岗位说明书”Skills是目前opencode社区最热的话题之一。简单理解Skills就是给Agent的一份“岗位说明书”。它不是一句临时prompt而是放在项目里的结构化技能文件Agent在处理相关任务时会自动加载并遵循。创建方法很简单在项目根目录建一个.opencode/skills目录每个技能是一个Markdown文件文件头部用YAML frontmatter写元信息正文写详细操作步骤。一个代码审查技能的模板大概是这样的--- name: code-review description: 执行代码审查时遵循团队的Checklist规则 --- # Code Review Checklist 1. 检查是否有未捕获的Promise异常 2. 检查是否直接修改了props或state 3. 检查是否有遗留的console.log 4. 检查样式是否依赖了全局class写好之后你在聊天里提到“帮我做一次代码审查”Agent就会自动加载这个技能按里面的Checklist逐项检查而不是泛泛地看一遍。社区还流传一些成熟的技能包比如superpowers这类集合安装方式基本是clone下来然后在配置里把skills路径指到对应目录。我这里多说一句技能不是越多越好如果一个项目放了几十个技能Agent加载上下文会变得很重实际响应会变慢。按需放三五个最常用的就够。4.4 Memory配置让Agent记住项目上下文刚开始用opencode的人都有一个痛点每个新会话Agent都像失忆了一样忘了项目的技术栈、忘了代码风格、忘了之前定的规范。opencode的解法是让项目根目录的AGENTS.md来充当长期记忆。我在每个项目里都会维护一份AGENTS.md它可以在会话开始时被opencode自动读取相当于给Agent一份“入职手册”。我的模板一般包含四部分项目概览、代码规范、常用命令和架构约定。# 项目概览 - 技术栈React TypeScript Vite - 前端路由React Router - 状态管理Zustand # 代码规范 - 组件文件使用PascalCase命名 - 所有API请求统一走src/api/client.ts - UI样式优先使用Tailwind禁止内联style # 常用命令 - 启动开发环境pnpm dev - 运行测试pnpm test - 构建产物pnpm build # 架构约定 - 页面级组件在src/pages - 可复用组件在src/components - API类型定义在src/types/api.ts有了这份文件opencode新会话里写出来的代码明显更“懂规矩”。如果你有些全局习惯比如提交信息规范、注释语言、变量命名风格也可以放在全局配置的custom instructions里这样任何项目都会遵守。实测效果是切换新项目后第一次对话Agent给出的代码风格和项目原有代码几乎一致省了来回纠正的功夫。5. 进阶玩法插件、桌面版与老项目接手5.1 在VSCode和JetBrains IDEA里用opencodeopencode不是只能活在终端里官方提供了VSCode和JetBrains系插件。VSCode插件在扩展市场直接搜opencode就能装装好后它会连接本地运行的opencode服务你可以在编辑器侧边栏里看到当前会话、浏览diff、甚至把选中的代码块直接发给Agent。IDEA插件同理在插件市场搜opencode安装后会在工具窗口里打开一个同步会话面板。我个人的使用习惯是签入代码前用IDEA插件对比Agent的改动方便和现有IDE的Git集成一起使用。插件的响应速度和终端TUI基本同步因为底层共享同一个服务进程。要注意的是插件只是“遥控器”核心的Agent进程还是在后台跑。如果你在终端里关了opencode插件的会话也会断开。所以正确姿势是让opencode一直开着终端可以关掉面板服务不退出就行。5.2 OpenCode Go与CC Switch的搭配社区里很多人在讨论opencode go和cc switch这两个工具实际上解决的是同一个问题的两个侧面。CC Switch是给Agent工具切换模型供应商配置的面板工具而OpenCode Go则像一个模型聚合入口把多个模型出口聚合成一个本地OpenAI兼容服务。我用下来的感受是这两个工具配合opencode最大的价值是让“换模型”变成一件无感的事。比如你项目配置里只写了一个provider指向OpenCode Go的本地地址然后在CC Switch里切换出口用的是哪家的模型opencode这边不需要改任何配置下次请求自动走新出口。我建议不要一开始就把这套组合架起来容易一头雾水。先跑通opencode 单个API Key熟练之后再引入聚合入口。如果你在团队里经常帮同事排查模型配置问题这套组合能让你少接很多“为什么我的opencode不响应”的咨询。这里要多说一句网络上很多聚合入口来自个人维护稳定性没有保障配置前建议先单独用curl验证一下地址是否可用。别把时间浪费在一个已经下线的服务上。5.3 用opencode Playwright定位前端Bug前端调试是opencode比较惊艳我的一个场景。传统的流程是报Bug → 自己启动项目 → 手动复现 → 看Network和Console → 定位问题。有了opencode Playwright MCP插件这个流程可以大幅自动化。先说配置。opencode支持MCP服务你可以注册一个Playwright的MCP Server让Agent具备操作浏览器的能力。在项目配置里加一段{ mcp: { playwright: { type: local, command: [ npx, playwright/mcplatest ], enabled: true } } }配置好之后在对话里给Agent下指令比如“启动开发环境然后用浏览器打开登录页输入错误密码把控制台报错信息截图给我”。接下来opencode会自己启动浏览器、执行操作、读取Console和Network信息再结合代码库分析问题根因。上次遇到一个按钮点击没反应的Bug我人肉点了五分钟没看明白Agent一次性就定位到事件监听器被上层stopPropagation拦截了。用这个功能要注意两点第一确保本地开发服务已经跑起来否则浏览器打开是404第二MCP工具调用比较吃资源Agent连续开十几个页面时旧电脑可能会卡用完之后建议在配置里把enabled改成false需要时再打开。5.4 接手老项目让opencode快速建立代码地图接手一个从没见过的老项目最耗时间的是建立“代码地图”。以前我都是自己翻package.json、找入口文件、画模块依赖关系现在我会把这些全部丢给opencode。第一次打开老项目我会先给它一个Plan模式任务“梳理src目录结构找出核心入口和模块边界输出一份项目架构说明保存为ARCHITECTURE.md”。它会读目录、看配置文件、追踪依赖关系生成一份开头很粗但其实框架正确的文档。随后我会在会话里逐步追问细节“支付模块的调用链是什么”、“用户鉴权在哪里落库”每一步都在原来的认知上加深理解。如果是Java/Maven项目可以让它先读pom.xml梳理模块依赖再定位Spring Boot入口和Controller路由。它会帮你把所有Request Mapping整理成表格这份东西比人工翻代码快太多。我统计过一个三十万行的老项目用opencode建立初步认知大概只需要二十分钟之后带着问题去精读代码效率比盲翻高好几倍。接手项目的过程中AGENTS.md也派得上大用场。我会把opencode在梳理过程中发现的架构约定同步记录进去让后续会话甚至团队其他成员都能共享这份认知避免下一个人再从头开始交学费。5.5 桌面版体验如果你实在不习惯纯终端操作opencode也有桌面版。它基于Tauri做的本质上是一个带TUI界面的桌面壳子启动后依然是连本地的opencode服务配置文件和终端版完全通用。桌面版最方便的是可以独立开一个窗口不会和我的终端窗口混在一起。我会把终端版的opencode专门用来处理项目A桌面版开项目B两个项目并行推进互不干扰。不过要提醒的是桌面版的发版节奏跟着TUI走偶尔会遇到版本滞后如果遇到插件连接不上先看桌面版是否需要更新。6. 常见问题排查与避坑指南6.1 报错速查表整理一份我实际遇到过的报错和解决方案按频率排序现象可能原因解决办法安装后opencode无法识别npm全局目录不在PATH将npm root -g输出目录加入系统PathPowerShell提示禁止运行脚本执行策略限制ps1脚本Set-ExecutionPolicy -Scope CurrentUser RemoteSignedauth login后仍提示找不到API KeyKey没存进当前shell会话确认使用opencode auth login或重开终端生效发起对话后一直转圈provider的baseURL不可达用curl验证接口地址查看opencode debug输出模型返回400/401API Key无权限或模型名错误检查opencode models列表中的模型名是否与供应商一致TUI中文显示乱码缺少Nerd Font字体终端字体切换为JetBrains Mono Nerd Font等升级后配置失效JSON字段命名调整查看release notes按新schema迁移配置MCP工具不响应本地MCP服务未启动检查对应MCP进程是否存活重启opencodeopencode debug是排查问题的第一利器它会输出完整的系统信息、配置路径、服务端口和最近的错误日志。遇到任何诡异问题先跑它看日志比自己瞎猜快很多。6.2 六个容易踩的坑坑一把API Key直接写进JSON。文件提交到Git仓库后Key就裸奔了正确做法是用{env:NAME}占位符配合环境变量注入。坑二权限全开爽一时后悔一整天。把edit和bash直接设成allowAgent确实更像自己的员工了但一旦prompt描述有歧义它可能直接改动几十个文件。我的经验是至少在第一周保持ask摸清它的行为习惯后再逐步放开。坑三让opencode和Claude Code同时维护一份AGENTS.md。两个Agent对规范的理解不一样改出来的风格会互相打架。建议团队明确指定一个主力Agent另一个只读不写。坑四免费模型扛主力。免费模型做补充、做测试、做简单任务都行扛主力项目容易在中途碰到限流或服务降级影响心态。我的策略是主力付费模型 备用免费模型关键时刻切过去顶一下。坑五接MCP服务排行越多越好。每接入一个MCP服务都会增加Agent要感知的工具数量工具多了以后Agent容易选错工具反而拖慢速度。我只保留Playwright、数据库查询两个主力MCP其余按需启用。坑六升级不看release notes。opencode版本迭代很快有时候改动是破坏性的比如某个配置字段改名。我吃过一次亏升级后直接跑不起来查了半天发现是config.json换成了opencode.json。所以升级前一定先扫一眼官方的更新说明有破坏性更新就按迁移文档走别硬跑。6.3 prompt使用习惯建议最后聊几个我在使用中积累的prompt习惯。第一给Agent明确的范围限制比如“只修改src/pages/user目录下的文件”比“帮我优化用户模块”更可控。第二让它先汇报再行动用Plan模式确认理解比让它直接写代码再返工省时得多。第三把大任务拆成多个小任务一次性给它塞十个需求往往每个都做得不彻底。我把这些习惯跟身边朋友交流过大家普遍反馈最值钱的是第一条范围限制。越是老项目Agent越容易在改动时顺手优化它看不顺眼的代码最后diff变得一片混乱。加上范围限制后Agent会变得克制很多diff也干净得多审查起来十分钟就能搞定。如果你刚上手opencode我建议先从一个小项目开始练手把AGENTS.md建好、模型配好、权限设好然后挑一个你熟悉的功能让它重构。等它在你的监督下完成第一次任务你就能感受到这工具真正的边界和潜力在哪。我自己的体会是opencode不是替你写代码的魔法棒而是一个能听懂项目上下文、能按规范执行、还能让你随时介入审查的技术合伙人用顺了之后一天的工作流里至少有一半时间都在和它对话。 opencode完整上手指南：安装配置、模型切换与实战技巧
如果你最近在折腾AI编程工具大概率会看到opencode这个名字频繁出现。它来自SST团队一个做开发者基础设施的开源组织和Claude Code、OpenAI Codex这类老牌终端Agent放在一起比较时opencode最显眼的标签就是开源、多模型、终端原生以及一套非常干净的配置文件体系。我大概是两周前把日常主力Agent从Claude Code切到了opencode起因倒不是Claude Code不好用而是项目里的MCP服务越来越多、模型也想在不同供应商之间换来换去Claude Code的配置体系越卷越重。opencode把这一切收敛成了两个JSON文件加一个本地服务模型可以随时换运行日志也透明这对我是刚需。这篇文章就记录我这段时间的完整上手过程从安装到配置免费模型从Skills到Memory从VSCode/IDEA插件到用Playwright让Agent自己复现前端Bug还包含大量报错排查记录希望给正在观望或者已经装上但没玩明白的朋友一份能直接照着做的参考。1. opencode是什么一个重新思考过的终端AI编程Agent1.1 为什么我从Claude Code迁移过来先说结论不是Claude Code不好而是opencode更适合“模型中立”的开发者。Claude Code很强但它的配置和生态始终围绕Anthropic的模型展开一旦你想换成别的模型或者想在同一套Agent里对比各家模型的表现就会觉得很别扭。opencode在这一点上做得非常彻底。它的模型抽象层基于Vercel AI SDK只要是OpenAI兼容格式的API都能接进来甚至你可以自定义一个本地兼容服务把请求路由到任意模型上。对我来说这意味着同一个项目、同一套Skills、同一条指令我可以随时在Claude、Gemini、本地模型之间切换而不需要改任何业务代码。还有一个让我愿意切换的关键点是透明。opencode安装后会启动一个本地服务所有请求和响应都会记录在日志里出了问题可以直接看请求报文和响应报文。之前用Claude Code时遇到“Agent自己改了配置”“上下文被悄悄截断”这类问题排查起来非常痛苦。opencode把日志和diff都摊开给你看心态上踏实很多。1.2 与Codex、Claude Code、Pi的基础对比这几款终端Agent我最近都实际用过简单做个横向对比工具开源模型绑定配置复杂度上下文管理特色能力opencodeMIT开源不绑定任意OpenAI兼容模型中低JSON配置自动压缩手动MemoryLSP、Skills、MCP、桌面端、IDE插件齐全Claude Code闭源基本绑定Claude系列中官方封装较多CLI原生但定制空间有限Anthropic生态整合最深长上下文对话体验好OpenAI Codex闭源绑定OpenAI模型中依赖ChatGPT后台会话与ChatGPT产品联动好适合OpenAI全家桶用户Pi开源/闭源混合多模型但偏好特定厂商中高依赖外部网关主打聊天式编程多模态支持有亮点选型建议很简单如果你重度依赖Anthropic模型并且不打算换Claude Code已经是天花板如果你希望一套Agent配置同时应对多个模型供应商并且享受“改JSON等于换模型”的灵活度opencode更合适如果你每天都在ChatGPT Plus生态里工作Codex的集成度会让你更顺手。至于Pi我试下来觉得它更适合偏聊天交互的场景做严肃的工程重构时opencode的Plan/Build模式更可控。1.3 opencode适合什么类型的开发者从我的体验来看这批人最适合把opencode用起来开源项目维护者。需要频繁审视Agent提交的代码opencode的权限控制和diff展示非常友好不会让Agent乱动手脚。需要在多个模型之间切换对比的人。无论是比效果还是比成本opencode的模型配置就是一组JSON字段切换成本几乎为零。被桌面IDE卡到内存焦虑的人。opencode本体是一个终端TUI资源占用比Electron类编辑器小太多跑在老MacBook上很流畅。团队需要标准化Agent行为的人。Skills机制可以把团队的代码规范、测试流程、发布检查变成Agent自动执行的技能这是其他工具很难做到的。2. opencode安装从零到跑通第一个对话2.1 三种安装方式与选择建议opencode的安装方式很常规官方提供了脚本、npm和Homebrew三种渠道。我个人的建议是有Node.js环境就用npmmacOS用户用Homebrew也行最省心的其实是官方脚本。# 方式一npm全局安装需要Node.js npm install -g opencode-ai # 方式二Homebrew安装 brew install sst/tap/opencode # 方式三官方脚本 curl -fsSL https://opencode.ai/install | bash注意包名是opencode-ai不是opencode。很多人在npm上找不到或者装错包就是被这个名字坑了。Windows用户还可以用Scoop安装scoop install opencode但这个包未必是最新版本我的建议还是走npm。装完以后直接在项目目录下运行opencode会进入TUI交互界面。如果想跳过TUI直接执行任务可以这样opencode 帮我分析一下src/main.go的入口流程并输出调用关系这是opencode一个很香的设计非交互模式可以直接挂在CI或者脚本里用后面接--model参数还能临时切换模型比如强制用便宜的模型跑一遍快速检查。2.2 Windows报错“无法将‘opencode’项识别为cmdlet”的完整排查这个报错在热搜里出现了也是Windows用户装完后第一道坎。报错原文是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。别慌基本上只有两个原因。第一个原因是npm的全局安装目录根本不在你的PATH里。Node安装后全局包路径默认在C:\Users\你的用户名\AppData\Roaming\npm如果这个目录没加进系统变量无论装什么全局命令都跑不起来。排查方法很简单npm root -g把输出的路径添加到系统环境变量的Path里重开终端再试opencode --version。这时候如果还没好多半是PowerShell执行策略挡住了。npm会在全局目录下生成opencode.ps1而Windows默认执行策略可能禁止运行脚本报错就变成“无法加载...因为在此系统上禁止运行脚本”。执行下面这行放开当前用户限制即可Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里有个小坑RemoteSigned只信任远程签名脚本本地创建的ps1可以跑但如果是从网上直接下载的脚本可能还是会被拦。如果不想动执行策略也可以直接使用opencode.cmd它不会受这个限制影响。第二个常见原因是安装中断或者版本冲突。遇到这种情况先卸载再重装比人肉清残留变量快得多npm uninstall -g opencode-ai npm cache clean --force npm install -g opencode-ai重装后再用where.exe opencode验证命令路径。如果能看到路径输出说明命令本身已经生效了。2.3 首次启动认证、模型供应商与项目打开装好后第一次运行opencode最优先做的是认证。在TUI里输入/auth或者直接跑opencode auth login会进入一个交互式面板可以添加多个模型的API Key比如Anthropic、OpenAI、Google Gemini以及任意自定义供应商。我强烈建议用系统钥匙串来存Key而不是把Key写进终端环境变量。opencode在登录时会把Key安全地存到系统钥匙串里之后运行不会再让你反复粘贴。如果实在要用环境变量也记得以ANTHROPIC_API_KEY这类前缀命名而不是找个随便的变量名硬塞。首次启动时opencode会检查当前目录和上级目录里的配置文件包括opencode.json、AGENTS.md、CLAUDE.md等一旦发现项目级配置就会自动加载。所以打开项目的正确姿势是先cd到项目根目录再运行opencode。如果你在~下打开它能看到的项目上下文就是空白的回答质量会差很多。另外提一嘴opencode运行时会在本地起一个服务终端会打印出类似Local: http://127.0.0.1:xxxxx的信息这是IDE插件和桌面版连接它的通道不用关掉。如果端口被占可以在配置里改端口后面讲配置的时候会提到。3. opencode配置模型、参数与免费模型接入3.1 核心配置文件opencode.json与config.jsonopencode的配置体系很轻但不同版本之间有过命名调整早期版本用的是config.json后来统一成了opencode.json。所以网上教程经常打架有的人说改这个、有的人说改那个其实是版本差异。我的建议是先运行一次opencode让它生成默认配置然后用编辑器打开配置文件带JSON Schema提示的那份就是你要改的。opencode配置分两个层级。全局配置放在用户目录下作用于所有项目项目级配置放在项目根目录会覆盖全局配置。我习惯把全局配置只放API Key和通用偏好把模型列表、权限规则、MCP服务这些跟项目强相关的内容放在项目里这样clone一个新仓库时配置能跟着代码走。一个典型的配置文件长这样{ $schema: https://opencode.ai/config.json, autoupdate: true, theme: opencode, model: my-provider/my-model, provider: { my-provider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { my-model: { name: My Model } } } }, permission: { edit: ask, bash: ask, webfetch: allow } }provider定义了“模型从哪来”models定义“有哪些模型可选”model决定默认用哪个模型。这个结构非常直白只要理解一遍后面所有模型切换都靠它。3.2 免费模型接入的通用做法很多人问我opencode能不能用免费模型答案是可以而且配置思路和收费模型没有任何区别就是增加一个provider。只要对方提供OpenAI兼容APIopencode就能适配。最典型的免费渠道是Google Gemini系列。去官方平台申请一个API Key创建自定义provider填写兼容接口地址和Key就可以在opencode里用Gemini的免费额度了。以Gemini为例配置大概是这样{ provider: { gemini: { npm: ai-sdk/openai-compatible, name: Google Gemini (OpenAI Compatible), options: { baseURL: https://generativelanguage.googleapis.com/v1beta/openai/, apiKey: {env:GEMINI_API_KEY} }, models: { gemini-2.0-flash: { name: Gemini 2.0 Flash } } } } }另一个经常被用到的渠道是OpenRouter它的免费模型都带:free后缀配置方式就是设一个OpenAI兼容的providerbaseURL填https://openrouter.ai/api/v1然后在models里列出你想用的模型名。这里要提醒一句免费模型的稳定性参差不齐同一个模型一天之内响应速度可能差好几倍建议在opencode里配两个备选模型一个主力一个救急。网络上有些教程会推荐一些第三方聚合网关说什么hy3-free之类我的态度一直是小众网关适合临时折腾不适合当主力。这类服务挂掉就像吃饭吃到一半老板跑路既影响效率又没法追责真要用也一定要在项目配置里留好退路。3.3 常用配置参数与模型选择建议除了provider下面几个配置项几乎没有争议属于开箱必改。permission是最重要的安全开关。我默认开edit: ask和bash: ask这样Agent每次要改文件或者执行命令前都会征求我的意见虽然多了一步确认但能防止它脑补一个离谱的删库命令。如果你在写一个纯文档项目可以把edit改成allow省得烦如果你在做一个包含生产数据读取的运维脚本我建议把bash也改成deny彻底禁止Agent执行危险命令。autoupdate建议设成true。opencode迭代非常快旧版经常有奇奇怪怪的模型兼容问题自动更新能少踩很多坑。theme按个人喜好来我喜欢opencode默认主题高亮对比度适中长时间盯终端不疲劳。模型参数上代码任务我一般把temperature控制在0到0.3之间。超过0.5代码就开始“自由发挥”经常给你整出一些看起来很优雅但根本跑不起来的方案。想快速验证配置是否生效可以运行opencode models它会列出当前配置里所有可用的模型。如果这里看不到你新加的模型说明provider配置有问题优先检查baseURL和apiKey。4. 从聊天到写代码核心使用方式复盘4.1 Plan/Build双模式先规划再动手opencode的TUI里最核心的是Plan和Build两种模式。我把它理解为“先出方案再动代码”和真实团队里写方案再实施的工作流完全一致。在Plan模式下Agent会调研项目、分析代码、输出一份实施计划但不改任何文件。你可以把它当成一个免费的技术顾问先看它对整个任务的理解是否正确。确认方案没问题后Tab切到Build模式让它真正动手。这个设计让我避免了很多次“方向错了还改了一堆代码”的悲剧。举个例子有一次我让它重构一个用户登录模块。Plan模式下它发现了项目中已有一个我没有注意到的token刷新逻辑然后建议把新逻辑挂在现有拦截器上而不是另起一套。如果直接让它开干大概率会好心办坏事把原有鉴权逻辑一起推翻。Plan模式不是必须的流程但对于复杂重构花几十秒让它先列计划收益非常高。非交互模式也能使用Plan/Build模式区分命令大致是这样opencode 分析当前支付模块的异常处理列出需要加固的3个点 --agent plan挂上--agent plan参数opencode就只输出计划不碰代码。用脚本批量跑项目健康检查时这个功能非常实用。4.2 文件修改审批与LSP补全在Build模式下Agent每提出一个文件修改opencode都会把改动以diff形式展示给你。配合permission.edit: ask你可以逐文件审查确认无误后再应用。这里必须夸一下LSP集成这是opencode和普通聊天Agent最大的区别之一。它在本地会启动语言服务器意味着Agent“看到”的代码不是纯文本而是带类型信息、带编译错误的语义化代码。实际效果就是它改代码时会更合理比如自动补齐未导入的类型或者在你改了函数签名后同步提醒调用方需要调整。这对TypeScript项目尤其明显我在一个Vite React项目里让opencode改接口返回结构它居然自动把相关组件的类型标注一起修正了这一点很多同类工具做不到。如果你不想让Agent乱动格式可以在项目配置里把格式化工具交给Prettier让Agent只改逻辑不改格式。opencode本身支持外部格式化工具集成具体配置位是format字段设置成你的格式化命令即可。4.3 Skill机制给Agent装“岗位说明书”Skills是目前opencode社区最热的话题之一。简单理解Skills就是给Agent的一份“岗位说明书”。它不是一句临时prompt而是放在项目里的结构化技能文件Agent在处理相关任务时会自动加载并遵循。创建方法很简单在项目根目录建一个.opencode/skills目录每个技能是一个Markdown文件文件头部用YAML frontmatter写元信息正文写详细操作步骤。一个代码审查技能的模板大概是这样的--- name: code-review description: 执行代码审查时遵循团队的Checklist规则 --- # Code Review Checklist 1. 检查是否有未捕获的Promise异常 2. 检查是否直接修改了props或state 3. 检查是否有遗留的console.log 4. 检查样式是否依赖了全局class写好之后你在聊天里提到“帮我做一次代码审查”Agent就会自动加载这个技能按里面的Checklist逐项检查而不是泛泛地看一遍。社区还流传一些成熟的技能包比如superpowers这类集合安装方式基本是clone下来然后在配置里把skills路径指到对应目录。我这里多说一句技能不是越多越好如果一个项目放了几十个技能Agent加载上下文会变得很重实际响应会变慢。按需放三五个最常用的就够。4.4 Memory配置让Agent记住项目上下文刚开始用opencode的人都有一个痛点每个新会话Agent都像失忆了一样忘了项目的技术栈、忘了代码风格、忘了之前定的规范。opencode的解法是让项目根目录的AGENTS.md来充当长期记忆。我在每个项目里都会维护一份AGENTS.md它可以在会话开始时被opencode自动读取相当于给Agent一份“入职手册”。我的模板一般包含四部分项目概览、代码规范、常用命令和架构约定。# 项目概览 - 技术栈React TypeScript Vite - 前端路由React Router - 状态管理Zustand # 代码规范 - 组件文件使用PascalCase命名 - 所有API请求统一走src/api/client.ts - UI样式优先使用Tailwind禁止内联style # 常用命令 - 启动开发环境pnpm dev - 运行测试pnpm test - 构建产物pnpm build # 架构约定 - 页面级组件在src/pages - 可复用组件在src/components - API类型定义在src/types/api.ts有了这份文件opencode新会话里写出来的代码明显更“懂规矩”。如果你有些全局习惯比如提交信息规范、注释语言、变量命名风格也可以放在全局配置的custom instructions里这样任何项目都会遵守。实测效果是切换新项目后第一次对话Agent给出的代码风格和项目原有代码几乎一致省了来回纠正的功夫。5. 进阶玩法插件、桌面版与老项目接手5.1 在VSCode和JetBrains IDEA里用opencodeopencode不是只能活在终端里官方提供了VSCode和JetBrains系插件。VSCode插件在扩展市场直接搜opencode就能装装好后它会连接本地运行的opencode服务你可以在编辑器侧边栏里看到当前会话、浏览diff、甚至把选中的代码块直接发给Agent。IDEA插件同理在插件市场搜opencode安装后会在工具窗口里打开一个同步会话面板。我个人的使用习惯是签入代码前用IDEA插件对比Agent的改动方便和现有IDE的Git集成一起使用。插件的响应速度和终端TUI基本同步因为底层共享同一个服务进程。要注意的是插件只是“遥控器”核心的Agent进程还是在后台跑。如果你在终端里关了opencode插件的会话也会断开。所以正确姿势是让opencode一直开着终端可以关掉面板服务不退出就行。5.2 OpenCode Go与CC Switch的搭配社区里很多人在讨论opencode go和cc switch这两个工具实际上解决的是同一个问题的两个侧面。CC Switch是给Agent工具切换模型供应商配置的面板工具而OpenCode Go则像一个模型聚合入口把多个模型出口聚合成一个本地OpenAI兼容服务。我用下来的感受是这两个工具配合opencode最大的价值是让“换模型”变成一件无感的事。比如你项目配置里只写了一个provider指向OpenCode Go的本地地址然后在CC Switch里切换出口用的是哪家的模型opencode这边不需要改任何配置下次请求自动走新出口。我建议不要一开始就把这套组合架起来容易一头雾水。先跑通opencode 单个API Key熟练之后再引入聚合入口。如果你在团队里经常帮同事排查模型配置问题这套组合能让你少接很多“为什么我的opencode不响应”的咨询。这里要多说一句网络上很多聚合入口来自个人维护稳定性没有保障配置前建议先单独用curl验证一下地址是否可用。别把时间浪费在一个已经下线的服务上。5.3 用opencode Playwright定位前端Bug前端调试是opencode比较惊艳我的一个场景。传统的流程是报Bug → 自己启动项目 → 手动复现 → 看Network和Console → 定位问题。有了opencode Playwright MCP插件这个流程可以大幅自动化。先说配置。opencode支持MCP服务你可以注册一个Playwright的MCP Server让Agent具备操作浏览器的能力。在项目配置里加一段{ mcp: { playwright: { type: local, command: [ npx, playwright/mcplatest ], enabled: true } } }配置好之后在对话里给Agent下指令比如“启动开发环境然后用浏览器打开登录页输入错误密码把控制台报错信息截图给我”。接下来opencode会自己启动浏览器、执行操作、读取Console和Network信息再结合代码库分析问题根因。上次遇到一个按钮点击没反应的Bug我人肉点了五分钟没看明白Agent一次性就定位到事件监听器被上层stopPropagation拦截了。用这个功能要注意两点第一确保本地开发服务已经跑起来否则浏览器打开是404第二MCP工具调用比较吃资源Agent连续开十几个页面时旧电脑可能会卡用完之后建议在配置里把enabled改成false需要时再打开。5.4 接手老项目让opencode快速建立代码地图接手一个从没见过的老项目最耗时间的是建立“代码地图”。以前我都是自己翻package.json、找入口文件、画模块依赖关系现在我会把这些全部丢给opencode。第一次打开老项目我会先给它一个Plan模式任务“梳理src目录结构找出核心入口和模块边界输出一份项目架构说明保存为ARCHITECTURE.md”。它会读目录、看配置文件、追踪依赖关系生成一份开头很粗但其实框架正确的文档。随后我会在会话里逐步追问细节“支付模块的调用链是什么”、“用户鉴权在哪里落库”每一步都在原来的认知上加深理解。如果是Java/Maven项目可以让它先读pom.xml梳理模块依赖再定位Spring Boot入口和Controller路由。它会帮你把所有Request Mapping整理成表格这份东西比人工翻代码快太多。我统计过一个三十万行的老项目用opencode建立初步认知大概只需要二十分钟之后带着问题去精读代码效率比盲翻高好几倍。接手项目的过程中AGENTS.md也派得上大用场。我会把opencode在梳理过程中发现的架构约定同步记录进去让后续会话甚至团队其他成员都能共享这份认知避免下一个人再从头开始交学费。5.5 桌面版体验如果你实在不习惯纯终端操作opencode也有桌面版。它基于Tauri做的本质上是一个带TUI界面的桌面壳子启动后依然是连本地的opencode服务配置文件和终端版完全通用。桌面版最方便的是可以独立开一个窗口不会和我的终端窗口混在一起。我会把终端版的opencode专门用来处理项目A桌面版开项目B两个项目并行推进互不干扰。不过要提醒的是桌面版的发版节奏跟着TUI走偶尔会遇到版本滞后如果遇到插件连接不上先看桌面版是否需要更新。6. 常见问题排查与避坑指南6.1 报错速查表整理一份我实际遇到过的报错和解决方案按频率排序现象可能原因解决办法安装后opencode无法识别npm全局目录不在PATH将npm root -g输出目录加入系统PathPowerShell提示禁止运行脚本执行策略限制ps1脚本Set-ExecutionPolicy -Scope CurrentUser RemoteSignedauth login后仍提示找不到API KeyKey没存进当前shell会话确认使用opencode auth login或重开终端生效发起对话后一直转圈provider的baseURL不可达用curl验证接口地址查看opencode debug输出模型返回400/401API Key无权限或模型名错误检查opencode models列表中的模型名是否与供应商一致TUI中文显示乱码缺少Nerd Font字体终端字体切换为JetBrains Mono Nerd Font等升级后配置失效JSON字段命名调整查看release notes按新schema迁移配置MCP工具不响应本地MCP服务未启动检查对应MCP进程是否存活重启opencodeopencode debug是排查问题的第一利器它会输出完整的系统信息、配置路径、服务端口和最近的错误日志。遇到任何诡异问题先跑它看日志比自己瞎猜快很多。6.2 六个容易踩的坑坑一把API Key直接写进JSON。文件提交到Git仓库后Key就裸奔了正确做法是用{env:NAME}占位符配合环境变量注入。坑二权限全开爽一时后悔一整天。把edit和bash直接设成allowAgent确实更像自己的员工了但一旦prompt描述有歧义它可能直接改动几十个文件。我的经验是至少在第一周保持ask摸清它的行为习惯后再逐步放开。坑三让opencode和Claude Code同时维护一份AGENTS.md。两个Agent对规范的理解不一样改出来的风格会互相打架。建议团队明确指定一个主力Agent另一个只读不写。坑四免费模型扛主力。免费模型做补充、做测试、做简单任务都行扛主力项目容易在中途碰到限流或服务降级影响心态。我的策略是主力付费模型 备用免费模型关键时刻切过去顶一下。坑五接MCP服务排行越多越好。每接入一个MCP服务都会增加Agent要感知的工具数量工具多了以后Agent容易选错工具反而拖慢速度。我只保留Playwright、数据库查询两个主力MCP其余按需启用。坑六升级不看release notes。opencode版本迭代很快有时候改动是破坏性的比如某个配置字段改名。我吃过一次亏升级后直接跑不起来查了半天发现是config.json换成了opencode.json。所以升级前一定先扫一眼官方的更新说明有破坏性更新就按迁移文档走别硬跑。6.3 prompt使用习惯建议最后聊几个我在使用中积累的prompt习惯。第一给Agent明确的范围限制比如“只修改src/pages/user目录下的文件”比“帮我优化用户模块”更可控。第二让它先汇报再行动用Plan模式确认理解比让它直接写代码再返工省时得多。第三把大任务拆成多个小任务一次性给它塞十个需求往往每个都做得不彻底。我把这些习惯跟身边朋友交流过大家普遍反馈最值钱的是第一条范围限制。越是老项目Agent越容易在改动时顺手优化它看不顺眼的代码最后diff变得一片混乱。加上范围限制后Agent会变得克制很多diff也干净得多审查起来十分钟就能搞定。如果你刚上手opencode我建议先从一个小项目开始练手把AGENTS.md建好、模型配好、权限设好然后挑一个你熟悉的功能让它重构。等它在你的监督下完成第一次任务你就能感受到这工具真正的边界和潜力在哪。我自己的体会是opencode不是替你写代码的魔法棒而是一个能听懂项目上下文、能按规范执行、还能让你随时介入审查的技术合伙人用顺了之后一天的工作流里至少有一半时间都在和它对话。