尧图网页设计 
如果你跟我一样这两年一直在用各种AI编程工具写需求、改老项目那你大概率也经历过这样的循环先装了Codex CLI又试了Claude Code插件越装越多配置越改越乱最后发现真正卡点从来不在模型而在工具本身有没有长成生产力工具的样子。opencode是我在这个循环里停下来之后一直用到现在的终端AI编程Agent它开源、不绑定模型、能装技能包还顺手把VSCode、IDEA、桌面版全给补齐了。这篇文章我会从安装到配置、从Skills到MCP、从编辑器插件到实战接项目把我这几个月用opencode踩过的坑和沉淀下来的玩法一次性讲清楚。无论你是刚听说opencode的新人还是已经在用但想把它调教得更好用的老手这篇都值得放进收藏夹慢慢看。1. opencode到底是什么从终端TUI到多模型Agent1.1 为什么是终端Agent而不是IDE补全先说人话opencode是一个跑在终端里的AI编程代理Agent。你在命令行敲下opencode就能进入一个交互式TUI界面它可以直接读写你的项目文件、执行终端命令、跑git、跑测试就像有个同事坐在你旁边用命令行帮你干活。这和GitHub Copilot那种“你写着代码它给补全”的思路完全是两回事它更像一个能把任务从头到尾接过去的执行者。我最早接触这类工具是从Codex CLI开始的后来又用了Claude Code最后才换到opencode。为什么换因为opencode解决了几个让我非常难受的问题模型自由Codex CLI天然偏向OpenAI系模型Claude Code天然偏向Claude系模型而opencode不绑定任何厂商。OpenAI、Anthropic、Google Gemini、DeepSeek、智谱GLM只要能通过兼容API暴露出来opencode都能接。这个自由度对我来说是致命的吸引力。Agent能力完整读写文件、终端命令、搜索替换、git操作、MCP调用、技能调用这些基础能力opencode都有。新版还支持plan模式先出方案再动手特别适合接老项目。不给工作流添乱命令就是opencode脚本化调用非常方便官方还有桌面版和编辑器插件想在哪干活就在哪干活。很多人问opencode是哪家公司的。这里统一回答一下opencode来自SST团队核心开发者是Dax就是做Serverless框架SST那个团队。所以他们做出来的工具在工程化细节上很扎实不是随便套个聊天框就完事。1.2 opencode、Codex CLI、Claude Code怎么选先上一个我自己的对比结论方便你快速判断维度opencodeCodex CLIClaude Code是否开源开源开源闭源模型绑定任意模型都能接优先OpenAI系优先Claude系Skills技能包原生支持机制清晰一般弱一些支持但生态相对封闭MCP支持原生支持配置简单支持支持编辑器扩展VSCode、JetBrains都有官方插件官方以CLI为主有IDE扩展桌面版有没有没有跨平台Windows/macOS/Linux都行三平台都行官方更偏向macOS/Linux如果你是刚入门想找一个通用的、能接各家模型的工具那opencode几乎是最省心的选择。如果你是某个模型的深度用户比如重度依赖Claude Code的生态那继续用也完全没问题。我的建议是不要因为某个工具火就无脑迁移先明确你的痛点是“模型不够强”还是“工具不够自由”。我个人的选择是opencode作为主战场因为我不希望被单一模型锁死。2. 安装与首次起步把opencode跑起来2.1 三种安装方式和它们各自的坑安装这件事网上教程看起来很简单但真正栽跟头的全是细节。opencode的npm包名叫opencode-ai但你装完之后在终端敲的是opencode。这两个名字不一样导致很多人照着教程装完发现找不到命令第一反应是安装失败了其实是名字没对上。我推荐三种主流安装方式按使用习惯选一个就行。用npm全局安装npm install -g opencode-ai用Homebrew安装macOS用户brew install sst/tap/opencode用官方安装脚本Linux服务器或者不想碰npm的场景curl -fsSL https://opencode.ai/install | bash安装完之后验证一下opencode --version能正常输出版本号说明这一步过了。如果提示找不到命令不要慌接着往下看。2.2 Windows下“无法识别cmdlet”的完整解决方案热词里有一条非常典型“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名”。这个报错在Windows上出现的频率极高我总结下来主要有三个原因。第一个原因是终端没重启。npm全局安装的包安装路径其实是在npm的全局目录里但Windows的PATH环境变量在终端启动时才会重新读取。你装完后如果不重开终端新命令就识别不了。解决办法就是重开一个PowerShell窗口再试一次。第二个原因是node版本或者npm全局目录根本没在PATH里。先检查一下你的npm全局目录npm config get prefix正常情况下会输出一个路径比如C:\Users\你的用户名\AppData\Roaming\npm。确认这个路径在系统PATH里。如果不在手动加上。如果你用了nvm-windows来管理node版本切换node版本之后全局包会失效需要在当前node版本下重新执行npm install -g opencode-ai。第三个原因比较隐蔽是执行策略问题。部分Windows系统的PowerShell默认禁止执行脚本文件很多命令行工具的启动脚本会被拦下来。解决方案是用管理员身份打开PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重开终端再试。这个问题我在公司新入职的同事电脑上遇到过好几次都是执行策略卡住导致的。2.3 首次启动认证、模型选择、第一条指令安装成功之后在项目目录里直接敲opencode第一次启动会进入引导流程它要先选一个provider本质就是选模型。我的建议是第一次先用你手上已有的key哪个都行先跑通再精调。如果你有Anthropic的key设置环境变量ANTHROPIC_API_KEY如果是OpenAI家的key设置OPENAI_API_KEY。opencode会主动读这些环境变量。macOS和Linux可以在~/.zshrc或~/.bashrc里写export ANTHROPIC_API_KEY你的keyWindows用户就在系统环境变量里新增一个用户变量变量名ANTHROPIC_API_KEY值填key。跑通了之后第一条指令可以从最简单的开始比如让它解读当前项目看一下这个项目的README和package.json告诉我这个项目是干什么的技术栈是什么有哪些入口文件。如果它能给出有条理的回复说明整个链路已经通了。第一次跑不通绝大多数情况是key没生效或者环境变量没加载重开终端再试一次基本都能解决。3. 模型接入与成本控制免费模型、多provider、配置切换3.1 两级config全局配置与项目配置opencode的配置核心是一个config.json文件。它遵循两级配置策略全局配置和项目配置。全局配置所在的目录macOS和Linux通常在~/.config/opencode/Windows一般在C:\Users\你的用户名\AppData\Roaming\opencode\。用命令行可以随时查看具体路径opencode config项目配置则放在项目根目录下的opencode.json它的优先级高于全局配置。我日常习惯把所有provider配在全局配置里因为我的多模型需求是跨项目的。但如果你在给不同的项目接不同的模型或者不同项目要用不同的系统提示词那就把项目配置单独写清楚这样切项目时不会互相干扰。3.2 免费模型接入实操opencode的杀手级优势就是可以轻松接入各种模型。很多人关心免费模型怎么接说实话我现在的主力工作流里一部分任务确实是由免费额度或限免模型承担的。最省事的免费路子是接OpenRouter上标记为:free的模型把OpenRouter当成一个provider配进去就行。如果你有各家厂商的直接key也可以通过baseURL直接对接官方接口。下面是我现在用的一个配置示例接入了DeepSeek和智谱GLM{ $schema: https://opencode.ai/config.json, provider: { deepseek: { name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: env:DEEPSEEK_API_KEY }, models: { deepseek-chat: { name: DeepSeek V3 }, deepseek-reasoner: { name: DeepSeek R1 } } }, zhipu: { name: Zhipu GLM, options: { baseURL: https://open.bigmodel.cn/api/paas/v4, apiKey: env:ZHIPU_API_KEY }, models: { glm-4.6: { name: GLM-4.6 } } } } }注意apiKey字段我用的是env:DEEPSEEK_API_KEY这种写法意思是从环境变量读取key而不是把key明文写在配置文件里。这样搞的好处是你的config.json随便放到公开仓库都不会泄露密钥换机器也只需要改环境变量。改完配置之后在opencode的交互界面里可以直接切换模型或者用快捷键呼出模型选择列表。不同模型的强项不一样我的习惯是写前端样式调UI用GLM这类性价比高的模型做架构梳理确认方案用Claude重活累活比如大范围重构代码用DeepSeek R1这种推理模型。3.3 ccswitch与快速切换多套模型的工作流如果你手上有好几套key或者经常在Windows和macOS之间来回切换手工改环境变量真的很烦。这里就要提到ccswitch这个工具了热词里也一直有人问“ccswitch配置opencode”怎么搞。ccswitch本质上是一个配置切换小工具最早是给Claude Code系列配置做切换用的图形化选择当前生效的配置组合后来社区里也支持了opencode。它的使用场景是这样的我同时有个人key和公司key个人key跑个人项目公司key跑公司项目偶尔还要切到某个限免模型薅点免费额度。如果没有切换工具我每次都要去改环境变量改完还要重开终端。有了ccswitch键鼠点两下就能切换当前要用的配置组合整个流程从五分钟缩短到五秒钟。另外如果你不想进入交互式界面就是想快速跑一轮任务然后退出opencode也提供了无头执行模式。官方命令是opencode run 检查src目录下的TypeScript类型错误逐个给出修复建议社区里管这种用法叫opencode go模式意思就是“跑一下就走”。我经常把它用在批量任务上比如批量检查代码规范、批量生成git提交信息、批量做代码审查。这类任务用无头模式效率极高因为不需要人盯着页面等回复跑完直接看结果就行。4. 从会用到好用Skills、Memory、MCP三板斧4.1 Skills给agent装可复用的技能包聊完配置来说说让opencode真正拉开体验差距的三板斧Skills、Memory和MCP。先讲Skills。Skills在opencode里就是给agent预设的技能包一个skill就是一个markdown文件开头带YAML frontmatter声明name和description正文是详细的执行指南。agent会根据任务相关性自动调用对应的skill不需要你每次都手动提示。项目里的skills放在.agents/skills/skill名/SKILL.md全局的skills放在~/.config/opencode/skills/skill名/SKILL.md。我拿自己的一个commit规范skill举例--- name: conventional-commit description: 生成符合Conventional Commits规范的git提交信息 --- ## 使用场景 当用户要求提交代码或生成提交信息时先运行 git diff --stat 查看本次改动范围再运行 git diff 查看关键改动。 ## 提交信息格式 type(scope): subject type 可选值 - feat: 新功能 - fix: 修复bug - refactor: 重构 - docs: 文档变更 - test: 测试相关 - chore: 构建或辅助工具变动 ## 要求 - subject 用中文简洁不超过50个字 - 如果有破坏性变更在正文中说明这个skill文件放好之后我在项目里对opencode说“提交一下”它就会自动按这套规范生成提交信息不用我每次啰嗦地交代格式要求。这里有个踩坑心得skill文件里的description一定要写清楚“什么时候用”。这个描述就是agent判断是否调用skill的依据写得模糊agent就不知道该不该调。我见过很多人写skill只写“生成提交信息”没写什么时候触发结果agent总是等到你明确说“提交”才调用。写清楚触发场景和触发条件skill才真正好用。4.2 Memory让agent记住你的项目规矩Memory是另一个让我觉得opencode值回票价的功能。它的思路特别朴素在项目里放一个.agents/memory/目录里面放几个markdown文件把项目的技术栈、目录结构、代码规范、历史决定写进去。agent每次开始干活前会主动读这些文件相当于一个新人进团队先看wiki。我的项目memory文件一般长这样# 项目约定 ## 技术栈 - 前端Vue 3 TypeScript Pinia Vite - 后端Node.js Express PostgreSQL - 包管理器pnpm ## 代码规范 - 组件命名使用 PascalCase - 样式使用 scoped CSS禁止使用全局样式污染 - API请求统一走 src/api 目录下的封装方法 - 状态管理使用 Pinia禁止在组件里直接改store外状态 ## 目录结构 - src/views页面组件 - src/components公共组件 - src/api接口封装 - src/store状态管理 - src/utils工具函数 ## 注意事项 - 不要改动 src/legacy 目录历史遗留代码暂不迁移 - 后端接口返回统一格式{ code, data, message }有了这份memoryagent在改代码时就会主动遵守项目规范而不是给你写出一堆风格完全不一致的代码。比如我用Vue项目如果没写memory它可能会在某个组件里直接引入全局样式写了之后它会主动检查自己写的代码是否符合规范。我现在的习惯是每次新接一个项目先花十分钟写一份memory文件把技术栈、命令、目录结构、雷区写清楚。这个动作看起来不起眼但后面每次和agent协作时都能省下大量沟通成本相当于给agent装了个“项目背景知识包”。4.3 MCP与Playwright逼agent亲手测前端bugMCP这个词现在很多AI编程工具都在讲通俗理解就是给agent接外部的工具和数据源它可以通过MCP协议调用这些工具。opencode原生支持MCP配置在config.json的mcp字段里。我实际用下来最香的一个MCP场景是让它配合Playwright去测前端bug。热词里有人问“opencode playwright怎么测试前端bug”我的方案是在配置里加上Playwright的MCP服务{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }配置好之后我就可以对opencode说用Playwright打开 http://localhost:5173 复现这个问题点击登录按钮后页面报错。把console里的错误信息贴出来然后尝试修复并验证。加了MCP之后opencode会自己启动浏览器、点击按钮、查看控制台报错甚至能边分析边改代码然后重新打开页面做一轮验证。这套流程跑起来前端bug的定位效率是真的高。以前人肉手动点来点去现在agent自己就能完成大半个闭环。同样的思路还可以接文件系统MCP、数据库MCP或者社区里很流行的superpowers技能包。热词里一直有“opencode接入superpowers”的讨论我理解它的核心价值就是一站集成了很多实用的skills和MCP工具组合装完之后能让agent的能力面一下子宽很多。安装方式在opencode的MCP配置里把对应命令配进去就行具体以superpowers仓库的说明为准。我目前主用Playwright这一个因为它解决了我最痛的前端自测问题。5. 编辑器双端与桌面版VSCode、IDEA和desktop客户端5.1 VSCode插件把会话搬回编辑器有朋友习惯在编辑器里干活不太喜欢切到终端里用TUI。opencode官方也出了VSCode插件直接在扩展市场搜opencode就能装。安装后左侧边栏会多出一个opencode面板可以在里面新建会话、切换模型、查看agent当前执行到哪一步。我的VSCode插件使用习惯是阅读和搜索代码用编辑器原生功能调用agent跑任务用opencode面板。这样两个工具各司其职不会互相干扰。特别是改一个跨文件的老功能时我让opencode在面板里跑分析自己在编辑器里继续看关联代码两边同时进行节省等待时间。插件版和终端版的数据是打通的你在终端里开的会话在插件里也能看到历史记录。这一点很贴心因为我在终端里跑完一个任务后往往还想用编辑器打开相关文件这种连接让工作流特别顺滑。5.2 JetBrains IDEA插件怎么配Java后端开发用IDEA比较多。JetBrains系的插件市场里也能搜到opencode安装流程和VSCode插件差不多。装完之后IDEA底部工具窗里会多出一个opencode面板。在Java或Maven项目里用opencode我有个额外的建议在memory里写清楚构建工具是Maven还是Gradle以及项目里关键的pom.xml或build.gradle依赖结构。这样agent在分析代码时就知道项目依赖了哪些第三方库不会给出“用某个工具类但项目里根本没引入”这种错误建议。如果你用Maven做多模块工程建议再让opencode读一下父pom.xml的模块结构它对整个项目边界的理解会提升一个档次。桌面版方面opencode也提供了desktop客户端适合不想用命令行也不想开编辑器的人群。它本质上是把TUI封装成了一个独立应用模型配置、会话管理都内置了登录之后就能干活。我用得不算频繁但在出差借用别人电脑、不方便装开发环境的场景下桌面版的便携性是很大的加分项。6. 实战用opencode接手一个老项目6.1 先让它读项目再让它动代码纸上谈兵说了那么多上点实战记录。前阵子我接了一个没人维护的Vue2老项目依赖还停留在webpack4路由文件几百行组件命名混乱线上还有个bug需要马上修。这种项目你让AI直接上手改代码大概率翻车。我的做法是分两步走。第一步先用无头模式让它读项目只输出分析结果不改任何代码opencode run 分析这个项目的整体结构输出1. 技术栈和依赖清单2. 路由入口和主要页面3. 状态管理方案4. 你发现的疑似问题列表。不要修改任何文件只输出分析报告。这一步跑完后我手里会有一份相对靠谱的项目地图至少知道哪些文件是核心、哪些是历史包袱。然后我把它输出的关键内容整理到.agents/memory/里作为后续合作的基准信息。第二步进入交互模式让它开始干活。注意同样要先限制范围不要一上来就“帮我重构整个项目”那是给自己挖坑。6.2 一次完整修复流程的调度记录线上bug的具体表现是用户在某个页面切换筛选条件后列表数据不刷新。我让opencode排查这段逻辑以下是它的典型工作流先读取用户提到的页面组件文件顺着监听事件找到筛选条件的处理函数发现该函数修改了状态但列表的请求依赖没变导致不会重新触发拉取数据继续回溯到请求相关的watch和生命周期代码确认触发链路给出两套修复方案并说明各自的优缺点在我确认方案之后执行代码修改并跑lint。整个过程我只需要在最关键的方案选择上做决策剩下的查找、分析、修改、验证都是它自己完成的。这种模式比传统“给AI贴一段代码让它改”要实用得多因为agent是真的会顺着代码调用链往下查而不是在一段代码里瞎猜。6.3 接项目时的权限控制和避坑用opencode接手老项目最需要管住的是权限。opencode每次要执行命令前都会询问确认我的建议是永远保留这个确认机制特别是在生产环境或者不熟悉的项目里。我有一次图省事在某个项目里开了自动确认权限结果它把依赖从npm换成了pnpm还跑了一次自动迁移装了一堆项目里根本不需要的东西。虽然最后都清理干净了但这个过程浪费了整整一下午。另外接老项目时一定要在memory里标注“雷区”。比如哪些目录不能动、哪个模块是历史遗留代码、哪个接口废弃了但前端还在用。这些信息agent从代码里不一定能看出来但你提前写在memory里它就有很大概率避开。我自己吃过一次亏没写某一处的雷区结果agent自作主张“优化”了一段看似没用其实在兜底的代码导致线上的一个隐藏逻辑挂了。从那以后我接项目的第一步永远是先写“注意事项”到memory里再让agent动手。7. 高频报错与体验优化速查7.1 报错定位思路用opencode一段时间最常见的几个报错基本都有套路可循。我整理了一个速查表遇到问题先照着排查报错/现象原因解决方案无法将“opencode”项识别为cmdletnpm全局目录不在PATH或终端没重启检查npm config get prefix把目录加入PATH重开终端opencode error: unexpected server errorAPI key失效、模型服务限流或网络问题检查环境变量里的key是否有效换一个模型/provider试试查看日志安装后找不到opencode命令包名和命令名混淆npm包名是opencode-ai安装后执行命令是opencode模型回复特别慢模型本身推理慢或服务端负载高切换到响应更快的模型比如非推理模型中文乱码或显示不全终端字体或编码问题Windows下用Windows Terminal字体建议设置支持中文等宽字体agent改了不该改的文件权限太宽松或prompt范围不清启动会话时明确“只改哪些文件”并保留命令确认日志是排查opencode问题最好的入口默认日志目录在~/.local/share/opencode/log/附近。遇到不明原因的报错直接看日志里的堆栈信息比猜有效得多。7.2 让opencode更好用的几个小设置最后分享几个我实测下来让体验提升明显的小设置。第一学会用主题切换。opencode的TUI支持主题切换深色环境下换一个舒适的主题长时候盯着终端眼睛会轻松不少。这个操作用快捷键就能完成具体看当前版本的帮助说明。第二建立自己的“项目启动指令”。我给自己定了一个标准动作每次进入一个新项目的opencode会话第一句话固定是先读一下项目里的README、package.json、memory目录然后告诉我这个项目的技术栈、启动命令和目录结构。在我明确下一步指令之前不要修改任何文件。这句话相当于给agent设定了一个安全边界避免它拿着八竿子打不着的猜测就开始动手。热词里所谓的“opencode标准使用指南”我觉得核心就是这条先让agent理解项目再让它行动。第三定期整理memory。随着项目迭代你在memory里写的内容可能过时了。我每个迭代结束都会顺手更新一下memory里的目录结构和注意事项保证它始终反映当前代码状态。一个长期维护的memory文件是让agent越用越懂你的关键。第四合理利用无头模式和交互模式的组合。简单的、批量的任务用opencode run一把梭复杂的、需要多次决策的任务进交互式TUI。前者省时间后者保质量两者配合起来整个协作效率非常高。最后再分享一个我自己的习惯不管模型多强接老项目时我还是会先在memory里写清楚项目边界然后让agent只负责改我说的那一个模块。Agent再强需求边界清晰才是真的好用。这也是我用opencode接了好几批项目之后踩坑踩出来的心得。 opencode：开源多模型终端AI编程Agent实战指南
如果你跟我一样这两年一直在用各种AI编程工具写需求、改老项目那你大概率也经历过这样的循环先装了Codex CLI又试了Claude Code插件越装越多配置越改越乱最后发现真正卡点从来不在模型而在工具本身有没有长成生产力工具的样子。opencode是我在这个循环里停下来之后一直用到现在的终端AI编程Agent它开源、不绑定模型、能装技能包还顺手把VSCode、IDEA、桌面版全给补齐了。这篇文章我会从安装到配置、从Skills到MCP、从编辑器插件到实战接项目把我这几个月用opencode踩过的坑和沉淀下来的玩法一次性讲清楚。无论你是刚听说opencode的新人还是已经在用但想把它调教得更好用的老手这篇都值得放进收藏夹慢慢看。1. opencode到底是什么从终端TUI到多模型Agent1.1 为什么是终端Agent而不是IDE补全先说人话opencode是一个跑在终端里的AI编程代理Agent。你在命令行敲下opencode就能进入一个交互式TUI界面它可以直接读写你的项目文件、执行终端命令、跑git、跑测试就像有个同事坐在你旁边用命令行帮你干活。这和GitHub Copilot那种“你写着代码它给补全”的思路完全是两回事它更像一个能把任务从头到尾接过去的执行者。我最早接触这类工具是从Codex CLI开始的后来又用了Claude Code最后才换到opencode。为什么换因为opencode解决了几个让我非常难受的问题模型自由Codex CLI天然偏向OpenAI系模型Claude Code天然偏向Claude系模型而opencode不绑定任何厂商。OpenAI、Anthropic、Google Gemini、DeepSeek、智谱GLM只要能通过兼容API暴露出来opencode都能接。这个自由度对我来说是致命的吸引力。Agent能力完整读写文件、终端命令、搜索替换、git操作、MCP调用、技能调用这些基础能力opencode都有。新版还支持plan模式先出方案再动手特别适合接老项目。不给工作流添乱命令就是opencode脚本化调用非常方便官方还有桌面版和编辑器插件想在哪干活就在哪干活。很多人问opencode是哪家公司的。这里统一回答一下opencode来自SST团队核心开发者是Dax就是做Serverless框架SST那个团队。所以他们做出来的工具在工程化细节上很扎实不是随便套个聊天框就完事。1.2 opencode、Codex CLI、Claude Code怎么选先上一个我自己的对比结论方便你快速判断维度opencodeCodex CLIClaude Code是否开源开源开源闭源模型绑定任意模型都能接优先OpenAI系优先Claude系Skills技能包原生支持机制清晰一般弱一些支持但生态相对封闭MCP支持原生支持配置简单支持支持编辑器扩展VSCode、JetBrains都有官方插件官方以CLI为主有IDE扩展桌面版有没有没有跨平台Windows/macOS/Linux都行三平台都行官方更偏向macOS/Linux如果你是刚入门想找一个通用的、能接各家模型的工具那opencode几乎是最省心的选择。如果你是某个模型的深度用户比如重度依赖Claude Code的生态那继续用也完全没问题。我的建议是不要因为某个工具火就无脑迁移先明确你的痛点是“模型不够强”还是“工具不够自由”。我个人的选择是opencode作为主战场因为我不希望被单一模型锁死。2. 安装与首次起步把opencode跑起来2.1 三种安装方式和它们各自的坑安装这件事网上教程看起来很简单但真正栽跟头的全是细节。opencode的npm包名叫opencode-ai但你装完之后在终端敲的是opencode。这两个名字不一样导致很多人照着教程装完发现找不到命令第一反应是安装失败了其实是名字没对上。我推荐三种主流安装方式按使用习惯选一个就行。用npm全局安装npm install -g opencode-ai用Homebrew安装macOS用户brew install sst/tap/opencode用官方安装脚本Linux服务器或者不想碰npm的场景curl -fsSL https://opencode.ai/install | bash安装完之后验证一下opencode --version能正常输出版本号说明这一步过了。如果提示找不到命令不要慌接着往下看。2.2 Windows下“无法识别cmdlet”的完整解决方案热词里有一条非常典型“opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名”。这个报错在Windows上出现的频率极高我总结下来主要有三个原因。第一个原因是终端没重启。npm全局安装的包安装路径其实是在npm的全局目录里但Windows的PATH环境变量在终端启动时才会重新读取。你装完后如果不重开终端新命令就识别不了。解决办法就是重开一个PowerShell窗口再试一次。第二个原因是node版本或者npm全局目录根本没在PATH里。先检查一下你的npm全局目录npm config get prefix正常情况下会输出一个路径比如C:\Users\你的用户名\AppData\Roaming\npm。确认这个路径在系统PATH里。如果不在手动加上。如果你用了nvm-windows来管理node版本切换node版本之后全局包会失效需要在当前node版本下重新执行npm install -g opencode-ai。第三个原因比较隐蔽是执行策略问题。部分Windows系统的PowerShell默认禁止执行脚本文件很多命令行工具的启动脚本会被拦下来。解决方案是用管理员身份打开PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重开终端再试。这个问题我在公司新入职的同事电脑上遇到过好几次都是执行策略卡住导致的。2.3 首次启动认证、模型选择、第一条指令安装成功之后在项目目录里直接敲opencode第一次启动会进入引导流程它要先选一个provider本质就是选模型。我的建议是第一次先用你手上已有的key哪个都行先跑通再精调。如果你有Anthropic的key设置环境变量ANTHROPIC_API_KEY如果是OpenAI家的key设置OPENAI_API_KEY。opencode会主动读这些环境变量。macOS和Linux可以在~/.zshrc或~/.bashrc里写export ANTHROPIC_API_KEY你的keyWindows用户就在系统环境变量里新增一个用户变量变量名ANTHROPIC_API_KEY值填key。跑通了之后第一条指令可以从最简单的开始比如让它解读当前项目看一下这个项目的README和package.json告诉我这个项目是干什么的技术栈是什么有哪些入口文件。如果它能给出有条理的回复说明整个链路已经通了。第一次跑不通绝大多数情况是key没生效或者环境变量没加载重开终端再试一次基本都能解决。3. 模型接入与成本控制免费模型、多provider、配置切换3.1 两级config全局配置与项目配置opencode的配置核心是一个config.json文件。它遵循两级配置策略全局配置和项目配置。全局配置所在的目录macOS和Linux通常在~/.config/opencode/Windows一般在C:\Users\你的用户名\AppData\Roaming\opencode\。用命令行可以随时查看具体路径opencode config项目配置则放在项目根目录下的opencode.json它的优先级高于全局配置。我日常习惯把所有provider配在全局配置里因为我的多模型需求是跨项目的。但如果你在给不同的项目接不同的模型或者不同项目要用不同的系统提示词那就把项目配置单独写清楚这样切项目时不会互相干扰。3.2 免费模型接入实操opencode的杀手级优势就是可以轻松接入各种模型。很多人关心免费模型怎么接说实话我现在的主力工作流里一部分任务确实是由免费额度或限免模型承担的。最省事的免费路子是接OpenRouter上标记为:free的模型把OpenRouter当成一个provider配进去就行。如果你有各家厂商的直接key也可以通过baseURL直接对接官方接口。下面是我现在用的一个配置示例接入了DeepSeek和智谱GLM{ $schema: https://opencode.ai/config.json, provider: { deepseek: { name: DeepSeek, options: { baseURL: https://api.deepseek.com/v1, apiKey: env:DEEPSEEK_API_KEY }, models: { deepseek-chat: { name: DeepSeek V3 }, deepseek-reasoner: { name: DeepSeek R1 } } }, zhipu: { name: Zhipu GLM, options: { baseURL: https://open.bigmodel.cn/api/paas/v4, apiKey: env:ZHIPU_API_KEY }, models: { glm-4.6: { name: GLM-4.6 } } } } }注意apiKey字段我用的是env:DEEPSEEK_API_KEY这种写法意思是从环境变量读取key而不是把key明文写在配置文件里。这样搞的好处是你的config.json随便放到公开仓库都不会泄露密钥换机器也只需要改环境变量。改完配置之后在opencode的交互界面里可以直接切换模型或者用快捷键呼出模型选择列表。不同模型的强项不一样我的习惯是写前端样式调UI用GLM这类性价比高的模型做架构梳理确认方案用Claude重活累活比如大范围重构代码用DeepSeek R1这种推理模型。3.3 ccswitch与快速切换多套模型的工作流如果你手上有好几套key或者经常在Windows和macOS之间来回切换手工改环境变量真的很烦。这里就要提到ccswitch这个工具了热词里也一直有人问“ccswitch配置opencode”怎么搞。ccswitch本质上是一个配置切换小工具最早是给Claude Code系列配置做切换用的图形化选择当前生效的配置组合后来社区里也支持了opencode。它的使用场景是这样的我同时有个人key和公司key个人key跑个人项目公司key跑公司项目偶尔还要切到某个限免模型薅点免费额度。如果没有切换工具我每次都要去改环境变量改完还要重开终端。有了ccswitch键鼠点两下就能切换当前要用的配置组合整个流程从五分钟缩短到五秒钟。另外如果你不想进入交互式界面就是想快速跑一轮任务然后退出opencode也提供了无头执行模式。官方命令是opencode run 检查src目录下的TypeScript类型错误逐个给出修复建议社区里管这种用法叫opencode go模式意思就是“跑一下就走”。我经常把它用在批量任务上比如批量检查代码规范、批量生成git提交信息、批量做代码审查。这类任务用无头模式效率极高因为不需要人盯着页面等回复跑完直接看结果就行。4. 从会用到好用Skills、Memory、MCP三板斧4.1 Skills给agent装可复用的技能包聊完配置来说说让opencode真正拉开体验差距的三板斧Skills、Memory和MCP。先讲Skills。Skills在opencode里就是给agent预设的技能包一个skill就是一个markdown文件开头带YAML frontmatter声明name和description正文是详细的执行指南。agent会根据任务相关性自动调用对应的skill不需要你每次都手动提示。项目里的skills放在.agents/skills/skill名/SKILL.md全局的skills放在~/.config/opencode/skills/skill名/SKILL.md。我拿自己的一个commit规范skill举例--- name: conventional-commit description: 生成符合Conventional Commits规范的git提交信息 --- ## 使用场景 当用户要求提交代码或生成提交信息时先运行 git diff --stat 查看本次改动范围再运行 git diff 查看关键改动。 ## 提交信息格式 type(scope): subject type 可选值 - feat: 新功能 - fix: 修复bug - refactor: 重构 - docs: 文档变更 - test: 测试相关 - chore: 构建或辅助工具变动 ## 要求 - subject 用中文简洁不超过50个字 - 如果有破坏性变更在正文中说明这个skill文件放好之后我在项目里对opencode说“提交一下”它就会自动按这套规范生成提交信息不用我每次啰嗦地交代格式要求。这里有个踩坑心得skill文件里的description一定要写清楚“什么时候用”。这个描述就是agent判断是否调用skill的依据写得模糊agent就不知道该不该调。我见过很多人写skill只写“生成提交信息”没写什么时候触发结果agent总是等到你明确说“提交”才调用。写清楚触发场景和触发条件skill才真正好用。4.2 Memory让agent记住你的项目规矩Memory是另一个让我觉得opencode值回票价的功能。它的思路特别朴素在项目里放一个.agents/memory/目录里面放几个markdown文件把项目的技术栈、目录结构、代码规范、历史决定写进去。agent每次开始干活前会主动读这些文件相当于一个新人进团队先看wiki。我的项目memory文件一般长这样# 项目约定 ## 技术栈 - 前端Vue 3 TypeScript Pinia Vite - 后端Node.js Express PostgreSQL - 包管理器pnpm ## 代码规范 - 组件命名使用 PascalCase - 样式使用 scoped CSS禁止使用全局样式污染 - API请求统一走 src/api 目录下的封装方法 - 状态管理使用 Pinia禁止在组件里直接改store外状态 ## 目录结构 - src/views页面组件 - src/components公共组件 - src/api接口封装 - src/store状态管理 - src/utils工具函数 ## 注意事项 - 不要改动 src/legacy 目录历史遗留代码暂不迁移 - 后端接口返回统一格式{ code, data, message }有了这份memoryagent在改代码时就会主动遵守项目规范而不是给你写出一堆风格完全不一致的代码。比如我用Vue项目如果没写memory它可能会在某个组件里直接引入全局样式写了之后它会主动检查自己写的代码是否符合规范。我现在的习惯是每次新接一个项目先花十分钟写一份memory文件把技术栈、命令、目录结构、雷区写清楚。这个动作看起来不起眼但后面每次和agent协作时都能省下大量沟通成本相当于给agent装了个“项目背景知识包”。4.3 MCP与Playwright逼agent亲手测前端bugMCP这个词现在很多AI编程工具都在讲通俗理解就是给agent接外部的工具和数据源它可以通过MCP协议调用这些工具。opencode原生支持MCP配置在config.json的mcp字段里。我实际用下来最香的一个MCP场景是让它配合Playwright去测前端bug。热词里有人问“opencode playwright怎么测试前端bug”我的方案是在配置里加上Playwright的MCP服务{ mcp: { playwright: { type: local, command: [npx, -y, playwright/mcplatest], enabled: true } } }配置好之后我就可以对opencode说用Playwright打开 http://localhost:5173 复现这个问题点击登录按钮后页面报错。把console里的错误信息贴出来然后尝试修复并验证。加了MCP之后opencode会自己启动浏览器、点击按钮、查看控制台报错甚至能边分析边改代码然后重新打开页面做一轮验证。这套流程跑起来前端bug的定位效率是真的高。以前人肉手动点来点去现在agent自己就能完成大半个闭环。同样的思路还可以接文件系统MCP、数据库MCP或者社区里很流行的superpowers技能包。热词里一直有“opencode接入superpowers”的讨论我理解它的核心价值就是一站集成了很多实用的skills和MCP工具组合装完之后能让agent的能力面一下子宽很多。安装方式在opencode的MCP配置里把对应命令配进去就行具体以superpowers仓库的说明为准。我目前主用Playwright这一个因为它解决了我最痛的前端自测问题。5. 编辑器双端与桌面版VSCode、IDEA和desktop客户端5.1 VSCode插件把会话搬回编辑器有朋友习惯在编辑器里干活不太喜欢切到终端里用TUI。opencode官方也出了VSCode插件直接在扩展市场搜opencode就能装。安装后左侧边栏会多出一个opencode面板可以在里面新建会话、切换模型、查看agent当前执行到哪一步。我的VSCode插件使用习惯是阅读和搜索代码用编辑器原生功能调用agent跑任务用opencode面板。这样两个工具各司其职不会互相干扰。特别是改一个跨文件的老功能时我让opencode在面板里跑分析自己在编辑器里继续看关联代码两边同时进行节省等待时间。插件版和终端版的数据是打通的你在终端里开的会话在插件里也能看到历史记录。这一点很贴心因为我在终端里跑完一个任务后往往还想用编辑器打开相关文件这种连接让工作流特别顺滑。5.2 JetBrains IDEA插件怎么配Java后端开发用IDEA比较多。JetBrains系的插件市场里也能搜到opencode安装流程和VSCode插件差不多。装完之后IDEA底部工具窗里会多出一个opencode面板。在Java或Maven项目里用opencode我有个额外的建议在memory里写清楚构建工具是Maven还是Gradle以及项目里关键的pom.xml或build.gradle依赖结构。这样agent在分析代码时就知道项目依赖了哪些第三方库不会给出“用某个工具类但项目里根本没引入”这种错误建议。如果你用Maven做多模块工程建议再让opencode读一下父pom.xml的模块结构它对整个项目边界的理解会提升一个档次。桌面版方面opencode也提供了desktop客户端适合不想用命令行也不想开编辑器的人群。它本质上是把TUI封装成了一个独立应用模型配置、会话管理都内置了登录之后就能干活。我用得不算频繁但在出差借用别人电脑、不方便装开发环境的场景下桌面版的便携性是很大的加分项。6. 实战用opencode接手一个老项目6.1 先让它读项目再让它动代码纸上谈兵说了那么多上点实战记录。前阵子我接了一个没人维护的Vue2老项目依赖还停留在webpack4路由文件几百行组件命名混乱线上还有个bug需要马上修。这种项目你让AI直接上手改代码大概率翻车。我的做法是分两步走。第一步先用无头模式让它读项目只输出分析结果不改任何代码opencode run 分析这个项目的整体结构输出1. 技术栈和依赖清单2. 路由入口和主要页面3. 状态管理方案4. 你发现的疑似问题列表。不要修改任何文件只输出分析报告。这一步跑完后我手里会有一份相对靠谱的项目地图至少知道哪些文件是核心、哪些是历史包袱。然后我把它输出的关键内容整理到.agents/memory/里作为后续合作的基准信息。第二步进入交互模式让它开始干活。注意同样要先限制范围不要一上来就“帮我重构整个项目”那是给自己挖坑。6.2 一次完整修复流程的调度记录线上bug的具体表现是用户在某个页面切换筛选条件后列表数据不刷新。我让opencode排查这段逻辑以下是它的典型工作流先读取用户提到的页面组件文件顺着监听事件找到筛选条件的处理函数发现该函数修改了状态但列表的请求依赖没变导致不会重新触发拉取数据继续回溯到请求相关的watch和生命周期代码确认触发链路给出两套修复方案并说明各自的优缺点在我确认方案之后执行代码修改并跑lint。整个过程我只需要在最关键的方案选择上做决策剩下的查找、分析、修改、验证都是它自己完成的。这种模式比传统“给AI贴一段代码让它改”要实用得多因为agent是真的会顺着代码调用链往下查而不是在一段代码里瞎猜。6.3 接项目时的权限控制和避坑用opencode接手老项目最需要管住的是权限。opencode每次要执行命令前都会询问确认我的建议是永远保留这个确认机制特别是在生产环境或者不熟悉的项目里。我有一次图省事在某个项目里开了自动确认权限结果它把依赖从npm换成了pnpm还跑了一次自动迁移装了一堆项目里根本不需要的东西。虽然最后都清理干净了但这个过程浪费了整整一下午。另外接老项目时一定要在memory里标注“雷区”。比如哪些目录不能动、哪个模块是历史遗留代码、哪个接口废弃了但前端还在用。这些信息agent从代码里不一定能看出来但你提前写在memory里它就有很大概率避开。我自己吃过一次亏没写某一处的雷区结果agent自作主张“优化”了一段看似没用其实在兜底的代码导致线上的一个隐藏逻辑挂了。从那以后我接项目的第一步永远是先写“注意事项”到memory里再让agent动手。7. 高频报错与体验优化速查7.1 报错定位思路用opencode一段时间最常见的几个报错基本都有套路可循。我整理了一个速查表遇到问题先照着排查报错/现象原因解决方案无法将“opencode”项识别为cmdletnpm全局目录不在PATH或终端没重启检查npm config get prefix把目录加入PATH重开终端opencode error: unexpected server errorAPI key失效、模型服务限流或网络问题检查环境变量里的key是否有效换一个模型/provider试试查看日志安装后找不到opencode命令包名和命令名混淆npm包名是opencode-ai安装后执行命令是opencode模型回复特别慢模型本身推理慢或服务端负载高切换到响应更快的模型比如非推理模型中文乱码或显示不全终端字体或编码问题Windows下用Windows Terminal字体建议设置支持中文等宽字体agent改了不该改的文件权限太宽松或prompt范围不清启动会话时明确“只改哪些文件”并保留命令确认日志是排查opencode问题最好的入口默认日志目录在~/.local/share/opencode/log/附近。遇到不明原因的报错直接看日志里的堆栈信息比猜有效得多。7.2 让opencode更好用的几个小设置最后分享几个我实测下来让体验提升明显的小设置。第一学会用主题切换。opencode的TUI支持主题切换深色环境下换一个舒适的主题长时候盯着终端眼睛会轻松不少。这个操作用快捷键就能完成具体看当前版本的帮助说明。第二建立自己的“项目启动指令”。我给自己定了一个标准动作每次进入一个新项目的opencode会话第一句话固定是先读一下项目里的README、package.json、memory目录然后告诉我这个项目的技术栈、启动命令和目录结构。在我明确下一步指令之前不要修改任何文件。这句话相当于给agent设定了一个安全边界避免它拿着八竿子打不着的猜测就开始动手。热词里所谓的“opencode标准使用指南”我觉得核心就是这条先让agent理解项目再让它行动。第三定期整理memory。随着项目迭代你在memory里写的内容可能过时了。我每个迭代结束都会顺手更新一下memory里的目录结构和注意事项保证它始终反映当前代码状态。一个长期维护的memory文件是让agent越用越懂你的关键。第四合理利用无头模式和交互模式的组合。简单的、批量的任务用opencode run一把梭复杂的、需要多次决策的任务进交互式TUI。前者省时间后者保质量两者配合起来整个协作效率非常高。最后再分享一个我自己的习惯不管模型多强接老项目时我还是会先在memory里写清楚项目边界然后让agent只负责改我说的那一个模块。Agent再强需求边界清晰才是真的好用。这也是我用opencode接了好几批项目之后踩坑踩出来的心得。