兄弟们最近群里多了好多问 OpenCode 的。装倒是装得快真正卡住的全是些细枝末节——不是提示“无法将 opencode 项识别为 cmdlet”就是进去了不知道模型怎么接要么就是运行半天报一个 unexpected server error。刚好我之前从安装到日常使用折腾了好几轮踩了不少坑这篇就当第二期食用指南把大家问得最多的问题一次性串起来。先说 OpenCode 是什么。它是一个跑在终端里的开源 AI 编程助手名字里的 Code 很直白核心就是帮你读项目、改代码、跑命令、修 bug。它和 Claude Code 这类工具最大的区别是模型不是绑死的你想接哪个模型服务、用什么样的模型都可以自己配。所以很多开发者本身就把它当成默认 Agent 在工作流里用。这篇内容适合谁装了 OpenCode 还没跑通的人、从其他 Agent 转过来不知道怎么配置的人、以及想把它接入 VSCode/IDEA 甚至桌面端的人。我会尽量把“为什么这么做”也讲清楚而不是只丢给你一堆命令。1. 安装与启动先把环境盘明白1.1 为什么选 OpenCode安装前要检查什么OpenCode 是 SST 团队维护的开源项目许可证很宽松社区活跃度也不错。相比同类命令行 Agent它最大的优势是配置透明你能清楚地看到自己用的是哪个模型、什么参数、请求发到了哪里而不是被封闭在某个厂商的生态里。不过在安装之前我建议先检查一下本机环境。OpenCode 的包是通过 Node.js 生态分发的所以 Node 版本太老会直接装不上或者装完启动报错。我自己的习惯是先跑两条命令node -v npm -v只要 Node 是 20 以上的 LTS 版本大概率没问题。如果你用的是 Windows还有一个很容易忽略的点npm 的全局安装目录到底在哪里。很多人报“opencode 无法识别”其实就是因为全局 bin 目录没有进 PATH这个我待会专门讲。另外提醒一句如果你以前装过其他命令行 Agent建议先把它们的环境变量、全局 npm 包列表看一眼避免 OpenCode 装好后启动时读到旧配置到时候排查起来很头疼。1.2 三种安装方式与常见环境问题我推荐按场景选安装方式。第一种npm 全局安装适合绝大多数开发环境。npm install -g opencode-ai安装包名是 opencode-ai但命令名是 opencode别搞混。装完先跑一下opencode --version能输出版本号就说明基本没问题。第二种官方一键脚本。如果你不想让 Node 全局目录变得太乱或者你在 Linux/macOS 上更习惯二进制方式直接用官方安装脚本curl -fsSL https://opencode.ai/install | bash这种方式会把可执行文件放到用户目录下不需要 sudo也更好清理。第三种桌面版。OpenCode 官方还提供了桌面端安装包不想碰命令行的朋友可以直接下载安装。桌面版本质还是同一套配置所以后面讲的配置文件它全都认只是交互方式从终端换成了图形界面。安装成功后真正的劝退点来了。如果你在 Windows 的 PowerShell 里执行 opencode 报“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”先别急着重装。用下面这条命令看看 npm 全局目录在哪npm prefix -g然后把输出的目录下的 node_modules/.bin 或者对应的 bin 目录加到系统的 PATH 环境变量里。改完 PATH 后记得重新开一个终端窗口因为旧窗口的环境变量不会自动刷新。还要注意一个很容易踩的坑不要为了加速 npm 安装乱改 registry。改坏了之后装包会一直卡住或者装出一个半成品OpenCode 启动时会报各种莫名其妙的错误。真要用镜像源也请选公共 npm 镜像装完再关掉不要长期指向不稳定的地址。1.3 第一次启动进入 TUI 并确认模型链路环境没问题后直接在终端输入opencode会进入一个全屏的 TUI 交互界面。第一次启动时它会引导你选择模型服务或者填写 API Key。如果你暂时不想进全屏界面我更推荐先用一次性任务模式验证安装opencode run 用一句话介绍你自己能正常回复就说明安装和模型链路都通了。这一步非常关键因为它把“安装问题”和“模型配置问题”在早期就切分开了。很多朋友一上来直接进 TUI 操作结果发现无法对话就误以为是 OpenCode 坏了其实可能只是模型没配好。2. 模型接入与配置把模型路线彻底打通2.1 Provider、模型、BASE_URL 的关系OpenCode 本身不生产回答它只是帮你调度模型。你可以把它理解成一个手机输入法系统键盘是固定的但输入法皮肤、词库、语音引擎都能换。OpenCode 把每次请求抽象成三样东西Provider、模型 ID、BASE_URL。BASE_URL 是模型服务的入口地址API Key 是你的身份凭证模型 ID 决定具体调用哪个模型。OpenCode 的整体配置其实就围绕这三者展开。配置可以写在两个地方全局配置~/.config/opencode/opencode.json项目配置项目根目录下的opencode.json项目配置的优先级更高这样你可以在不同项目里切换不同模型而不用频繁改动全局配置。配置结构很简单核心是 provider 这段。一个最小的自定义 Provider 大概长这样{ $schema: https://opencode.ai/config.json, provider: { custom-openai-compatible: { npm: ai-sdk/openai-compatible, name: 自定义模型服务, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { main: { name: 主模型 } } } }, model: custom-openai-compatible/main }这里的关键点是ai-sdk/openai-compatible。OpenCode 底层用的是 Vercel AI SDK它对 OpenAI 兼容协议的支持最省事。市面上绝大多数模型服务都提供了 OpenAI 兼容接口所以你拿到一个服务的 baseURL 和 API Key 后通常只需要改这两个字段就能接上。{env:MY_API_KEY}这种写法是我强烈推荐的不要在配置文件里硬编码 Key否则你一不小心把项目传到公网仓库就泄露了。把 Key 放到环境变量里既安全又方便多台机器同步配置。2.2 免费模型与 ccswitch 的配合使用很多人搜索“opencode 免费模型”和“opencode go 需要配合 ccswitch 等工具”其实它们说的是同一个需求OpenCode 不限制你用什么模型有些公开平台会提供免费额度或限时赠送你只要把对应的 API 配置填进去就能用。但问题也随之而来同时用好几个模型服务时今天用 A明天用 B手改 baseURL 和 Key 很容易出错。ccswitch 就是干这个用的。它是一个模型配置切换工具你可以把多套接口配置统一放在里面切换时点一下OpenCode 等工具就能读到对应的配置。我自己用下来的感受是ccswitch 的价值不在于省那几秒钟而在于它把“模型切换”变成了一个确定性的操作不用每次去翻配置文件也不用担心改错格式。尤其当你同时在 OpenCode 和别的 Agent 工具之间切换时一份配置多处使用体验要顺滑得多。要提醒的是免费模型普遍存在不稳定、额度有限、偶尔下线的现象。今天还能用的接口明天可能就返回 401 或者超时。这不是 OpenCode 的问题而是上游服务变动。我建议把免费模型当成尝鲜和辅助核心的、不能断的日常工作还是配一个稳定可用的量产模型。2.3 配置文件推荐写法与参数解读除了 Provider配置文件里还有几个参数值得关注。model默认模型可以是自定义 Provider 下的模型 ID也可以是 OpenCode 内置支持的模型。temperature控制回答的随机性。写代码、改 bug 我习惯设低一点比如 0.2 到 0.4太高的温度容易让它“自由发挥”写出不靠谱的代码。system系统提示词。你可以在这里写一些通用规则比如“所有代码必须有注释”或者“不要修改锁文件”。autoupdate控制 OpenCode 是否自动更新。如果你在公司内网或网络受限环境我建议关掉避免启动时卡在更新检查上。themeTUI 主题纯个人喜好不影响功能。如果你用的是 Maven 项目还有一个很容易被忽略的点。有热搜词是“opencode mvn 配置”实际上这不是 OpenCode 配置文件里的东西而是你的 Java/Maven 环境变量问题。OpenCode 在帮你执行mvn test或mvn compile时需要能找到JAVA_HOME和mvn命令。所以装 OpenCode 之前先在终端里确认java -version mvn -version如果这两条命令都能正常输出那 OpenCode 调用 Maven 就没问题。反过来IDEA 插件里遇到 Maven 相关报错十有八九也是环境变量没传进去。3. 实战集成VSCode、IDEA 与桌面版3.1 VSCode 插件从终端走进编辑器OpenCode 虽然出生在终端但日常写代码时大家还是更习惯待在编辑器里。VSCode 插件的好处是它和全局配置完全打通你在终端里配好的模型、Skills、AGENTS.md插件都能直接复用。安装方式很简单在 VSCode 扩展市场搜“OpenCode”装好后左侧会多出对话面板。你可以直接选中一段代码让它解释、重构或者补测试。它给出的修改会以 diff 形式呈现你自己确认后再 apply而不是一言不合直接改文件。用下来我最喜欢的是“选代码提问”这个场景。比如从一个大类里选中一个方法问问它这段逻辑有没有边界问题它给出的答案通常比在终端里描述半天上下文要准确得多因为上下文就是当前文件本身。有个细节需要注意VSCode 插件安装后要确保它能找到opencode可执行文件。如果你在终端里明明能跑插件却报找不到多半是插件启动时的 PATH 和终端不一致。直接在插件配置里把 opencode 的绝对路径填上最省事。3.2 IDEA 插件Java/Kotlin 项目的舒适圈如果你是 Java 开发者JetBrains IDEA 也有对应的 OpenCode 插件安装后在右侧工具窗口就能直接对话。IDEA 插件和 VSCode 插件的使用逻辑一样但有一个非常典型的问题IDEA 本身是从桌面图标启动的它的 PATH 环境变量可能不包含你终端里配置的那些路径。所以你在 IDEA 插件里配 OpenCode 时不要想当然地以为它能自动找到命令。我建议在插件设置里手动指定 opencode 可执行文件的绝对路径比如 Windows 下的C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd或者 mac 下的/usr/local/bin/opencode。另外Maven 项目在 IDEA 插件中跑构建时如果出现“mvn 命令找不到”或者“JAVA_HOME 找不到”不要怪 OpenCode看看 IDEA 本身能不能正常执行 Maven。这里有个很实用的排查方法在 OpenCode 对话里直接让它运行mvn -version看返回的结果如果这一步就不通过那问题出在环境变量而不是 Agent 本身。3.3 桌面版与 CLI 工作流的取舍桌面版适合刚入门、不想记命令的人。它能用图形界面完成模型配置、对话和文件修改确认体验比较友好。但我个人的观点是如果你已经是一个会写代码的人CLI TUI 的收益其实更高。原因是 CLI 可以编进脚本可以做自动化可以在任意的项目目录里快速启动而桌面版更适合点一点、看一看的轻量使用。日常我比较推荐用opencode run做一次性任务比如opencode run 看一下 src 目录下的代码找出没有错误处理的函数这种用法比每次都开全屏 TUI 更快也方便你把它接进自己的项目脚本里。桌面版、IDE 插件、CLI 三者可以共存底层共用同一套配置所以不用担心冲突。我的建议是终端党直接用 CLIIDE 重度用户装插件完全不想碰命令行的用桌面版。4. Skills 与 Memory从“能用”到“好用”4.1 AGENTS.md给 OpenCode 一份项目说明书很多人的 OpenCode 装完之后只会简单问答但真正好用的 Agent 应该知道你的项目是怎么组织的。AGENTS.md 就是干这个的。你可以把它理解成给每个新入职的工程师准备的交接文档。模型本身没有记忆每次对话它都是“新人”而 AGENTS.md 能让它快速了解项目的技术栈、目录结构、构建命令、编码规范。一个典型的 AGENTS.md 长这样# 项目说明 这是一个基于 Vue 3 TypeScript 的前端项目包管理工具使用 pnpm。 ## 常用命令 - 安装依赖pnpm install - 启动开发服务pnpm dev - 运行测试pnpm test ## 代码规范 - 组件文件统一放在 src/components 下 - 状态管理使用 Pinia - 不要修改锁文件除非升级依赖 - 所有对外接口必须有类型定义 ## 注意事项 - 测试环境接口地址在 .env.development 中配置 - 修改后端接口时需要同步更新 src/api 下的文件写完之后放到项目根目录OpenCode 在项目里启动时会自动读取它。全局规则可以放在~/.config/opencode/AGENTS.md这样所有项目都生效项目级规则就放项目根目录只对当前项目生效。我自己实测下来写完 AGENTS.md 之后OpenCode 生成的代码风格明显更贴近项目实际减少了很多来回纠正的次数。这比你在每次对话里重复说明命令要高效得多。4.2 Skills 机制让 Agent 具备专项技能OpenCode 较新的版本支持 Skills 机制。简单来说你可以把一组提示词和脚本打包成一个“技能”比如代码审查技能、Docker 运维技能、日志排查技能。模型在遇到对应场景时会主动调用这些技能而不是每次从零开始理解你的需求。这种思路和 oh-my-claudecode、superpowers 这些社区项目是相通的。它们本质上都是把大量实用的提示词和技能目录整理好让你复制到自己的环境里直接用。OpenCode 2.0 之后这种“技能包”的使用越来越顺手很多原本在 Claude Code 里流行的玩法都能平移到 OpenCode 里。如果你下载了某个技能包注意看它的目录结构通常里面会带 skill 描述文件和相关的脚本。把这些内容放到项目根目录的 skills 目录或者放到全局配置对应的 skills 目录重启 OpenCode 后就能看到技能列表。我自己更倾向于先用原生的 AGENTS.md 把项目规范喂给模型再按需引入技能包避免一上来就装一堆技能反而不知道该用哪个。4.3 用 Playwright 做前端 Bug 自动修复“opencode playwright 怎么测试前端 bug”这个问题问得非常多我展开说一下。在很多前端项目里bug 并不是靠看代码就能定位的尤其是复杂的交互问题需要真实打开浏览器复现。OpenCode 配合 Playwright 技能可以自动启动浏览器、访问本地开发地址、点击元素、抓取控制台报错和网络请求然后把完整现场信息交回给模型分析。操作流程大概是这样的让 OpenCode 用 Playwright 打开本地开发服务比如http://localhost:5173。让它执行你描述的操作比如“点击提交按钮”。它会返回页面截图、控制台报错和关键网络请求信息。模型基于这些信息分析问题根源再回到代码里给出修复方案。一个比较实用的 prompt 示例opencode run 用 Playwright 打开 http://localhost:5173点击登录按钮如果出现报错或者页面无法跳转把控制台错误和页面截图发给我然后定位原因并给出修复建议需要注意的是用这个功能前你得确保本地已经装好 Playwright 和对应浏览器。如果项目里已经集成了 Playwright 测试框架那 OpenCode 会直接复用现有环境体验更好。这条链路是我目前觉得 OpenCode 最有价值的使用方式它不只是“帮你写一段代码”而是“帮你复现问题、分析问题、再给出修复方案”。对于复杂前端 bug这一套流程能把排查时间从几小时压缩到几分钟。5. 常见问题与避坑速查5.1 Windows 命令无法识别怎么办这个问题的出现频率最高尤其是在 Windows PowerShell 环境。报错信息一般是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。我直接给一个排查顺序错误现象可能原因解决思路输入 opencode 提示无法识别npm 全局 bin 目录不在 PATH执行npm prefix -g找到 bin 目录加入 PATH安装了却提示找不到模块npm 安装过程中断或 registry 异常卸载重装检查 npm registry能启动但闪退终端或系统环境变量异常重新打开终端或换一个终端再试执行 opencode run 无反应Node 版本过低升级 Node 到 20 以上如果 PATH 已经配好但还是不行可以在终端里输入Get-Command opencode看看系统到底找没找到这个命令。找到的话它会显示完整路径找不到就继续排查 PATH。5.2 unexpected server error 的排查思路这个报错的完整提示通常是error: unexpected server error. check server logs很多人以为这是安装问题其实不是。出现这种报错OpenCode 本身已经启动成功了但它向后端模型服务发请求时失败了。常见原因包括API Key 填错了或者已经失效。BASE_URL 地址不可达或者路径写错。模型 ID 在当前服务下不存在。免费模型额度耗尽或者服务已经下线。网络超时请求迟迟没有响应。排查思路是先在项目目录里跑一条最简单的命令opencode run 你好如果连最简单的对话都报错那就是模型配置问题。换一个已知可用的模型服务测试或者打开 OpenCode 的日志目录通常位于用户目录下的~/.local/share/opencode/log看具体的错误信息。如果你用的是免费模型刚看到这个报错第一反应应该是去查上游服务状态而不是反复重装 OpenCode。网上经常有人问“hy3-free 下线了吗”这种问题本质上就是因为免费模型的上线、下线、额度耗尽都会让用户产生“是不是我装错了”的错觉。5.3 OpenCode、Codex、Claude Code 怎么选这个问题基本每周都有人问。我根据自己的使用感受做个横向对比维度OpenCodeCodexClaude Code开源开源MIT 协议闭源闭源模型绑定可自由切换模型绑定同类模型生态绑定 Claude 系列配置灵活度高支持自定义 Provider中和官方生态绑定深中模型相对固定上手难度中等配置项多低开箱即用低命令简单直接适合场景想掌控全流程的开发者GitHub 生态重度用户追求高质量代码生成的用户如果你喜欢折腾、想让 Agent 按自己的规则来OpenCode 是最合适的。如果你只想开箱即用并且主要工作在 GitHub 上进行Codex 会更顺手。如果你对写码质量要求极高也不介意模型绑定Claude Code 的体验确实顶。老板问“Opencode 是哪家公司的”简单说一句就是 SST 团队的开源项目不是某个大厂闭门造的车。它也正因为开源才让插件、技能包、模型接入这些事情玩得这么花。最后分享一个我实际工作中的小体会OpenCode 真正让我留下来的是opencode run加上 AGENTS.md 和 Playwright 这条链路。它改变了我处理 bug 的方式——以前是我自己开浏览器、抓报错、猜根因现在是我把问题描述清楚Agent 带着工具先去收集现场再回到代码里给方案。装好之后别急着折腾一堆技能先把最小链路跑通安装、配模型、写 AGENTS.md、执行一次真实任务。这条路走顺了后面所有扩展都是锦上添花。
OpenCode 完整食用指南：安装、模型配置与项目集成避坑
兄弟们最近群里多了好多问 OpenCode 的。装倒是装得快真正卡住的全是些细枝末节——不是提示“无法将 opencode 项识别为 cmdlet”就是进去了不知道模型怎么接要么就是运行半天报一个 unexpected server error。刚好我之前从安装到日常使用折腾了好几轮踩了不少坑这篇就当第二期食用指南把大家问得最多的问题一次性串起来。先说 OpenCode 是什么。它是一个跑在终端里的开源 AI 编程助手名字里的 Code 很直白核心就是帮你读项目、改代码、跑命令、修 bug。它和 Claude Code 这类工具最大的区别是模型不是绑死的你想接哪个模型服务、用什么样的模型都可以自己配。所以很多开发者本身就把它当成默认 Agent 在工作流里用。这篇内容适合谁装了 OpenCode 还没跑通的人、从其他 Agent 转过来不知道怎么配置的人、以及想把它接入 VSCode/IDEA 甚至桌面端的人。我会尽量把“为什么这么做”也讲清楚而不是只丢给你一堆命令。1. 安装与启动先把环境盘明白1.1 为什么选 OpenCode安装前要检查什么OpenCode 是 SST 团队维护的开源项目许可证很宽松社区活跃度也不错。相比同类命令行 Agent它最大的优势是配置透明你能清楚地看到自己用的是哪个模型、什么参数、请求发到了哪里而不是被封闭在某个厂商的生态里。不过在安装之前我建议先检查一下本机环境。OpenCode 的包是通过 Node.js 生态分发的所以 Node 版本太老会直接装不上或者装完启动报错。我自己的习惯是先跑两条命令node -v npm -v只要 Node 是 20 以上的 LTS 版本大概率没问题。如果你用的是 Windows还有一个很容易忽略的点npm 的全局安装目录到底在哪里。很多人报“opencode 无法识别”其实就是因为全局 bin 目录没有进 PATH这个我待会专门讲。另外提醒一句如果你以前装过其他命令行 Agent建议先把它们的环境变量、全局 npm 包列表看一眼避免 OpenCode 装好后启动时读到旧配置到时候排查起来很头疼。1.2 三种安装方式与常见环境问题我推荐按场景选安装方式。第一种npm 全局安装适合绝大多数开发环境。npm install -g opencode-ai安装包名是 opencode-ai但命令名是 opencode别搞混。装完先跑一下opencode --version能输出版本号就说明基本没问题。第二种官方一键脚本。如果你不想让 Node 全局目录变得太乱或者你在 Linux/macOS 上更习惯二进制方式直接用官方安装脚本curl -fsSL https://opencode.ai/install | bash这种方式会把可执行文件放到用户目录下不需要 sudo也更好清理。第三种桌面版。OpenCode 官方还提供了桌面端安装包不想碰命令行的朋友可以直接下载安装。桌面版本质还是同一套配置所以后面讲的配置文件它全都认只是交互方式从终端换成了图形界面。安装成功后真正的劝退点来了。如果你在 Windows 的 PowerShell 里执行 opencode 报“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”先别急着重装。用下面这条命令看看 npm 全局目录在哪npm prefix -g然后把输出的目录下的 node_modules/.bin 或者对应的 bin 目录加到系统的 PATH 环境变量里。改完 PATH 后记得重新开一个终端窗口因为旧窗口的环境变量不会自动刷新。还要注意一个很容易踩的坑不要为了加速 npm 安装乱改 registry。改坏了之后装包会一直卡住或者装出一个半成品OpenCode 启动时会报各种莫名其妙的错误。真要用镜像源也请选公共 npm 镜像装完再关掉不要长期指向不稳定的地址。1.3 第一次启动进入 TUI 并确认模型链路环境没问题后直接在终端输入opencode会进入一个全屏的 TUI 交互界面。第一次启动时它会引导你选择模型服务或者填写 API Key。如果你暂时不想进全屏界面我更推荐先用一次性任务模式验证安装opencode run 用一句话介绍你自己能正常回复就说明安装和模型链路都通了。这一步非常关键因为它把“安装问题”和“模型配置问题”在早期就切分开了。很多朋友一上来直接进 TUI 操作结果发现无法对话就误以为是 OpenCode 坏了其实可能只是模型没配好。2. 模型接入与配置把模型路线彻底打通2.1 Provider、模型、BASE_URL 的关系OpenCode 本身不生产回答它只是帮你调度模型。你可以把它理解成一个手机输入法系统键盘是固定的但输入法皮肤、词库、语音引擎都能换。OpenCode 把每次请求抽象成三样东西Provider、模型 ID、BASE_URL。BASE_URL 是模型服务的入口地址API Key 是你的身份凭证模型 ID 决定具体调用哪个模型。OpenCode 的整体配置其实就围绕这三者展开。配置可以写在两个地方全局配置~/.config/opencode/opencode.json项目配置项目根目录下的opencode.json项目配置的优先级更高这样你可以在不同项目里切换不同模型而不用频繁改动全局配置。配置结构很简单核心是 provider 这段。一个最小的自定义 Provider 大概长这样{ $schema: https://opencode.ai/config.json, provider: { custom-openai-compatible: { npm: ai-sdk/openai-compatible, name: 自定义模型服务, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { main: { name: 主模型 } } } }, model: custom-openai-compatible/main }这里的关键点是ai-sdk/openai-compatible。OpenCode 底层用的是 Vercel AI SDK它对 OpenAI 兼容协议的支持最省事。市面上绝大多数模型服务都提供了 OpenAI 兼容接口所以你拿到一个服务的 baseURL 和 API Key 后通常只需要改这两个字段就能接上。{env:MY_API_KEY}这种写法是我强烈推荐的不要在配置文件里硬编码 Key否则你一不小心把项目传到公网仓库就泄露了。把 Key 放到环境变量里既安全又方便多台机器同步配置。2.2 免费模型与 ccswitch 的配合使用很多人搜索“opencode 免费模型”和“opencode go 需要配合 ccswitch 等工具”其实它们说的是同一个需求OpenCode 不限制你用什么模型有些公开平台会提供免费额度或限时赠送你只要把对应的 API 配置填进去就能用。但问题也随之而来同时用好几个模型服务时今天用 A明天用 B手改 baseURL 和 Key 很容易出错。ccswitch 就是干这个用的。它是一个模型配置切换工具你可以把多套接口配置统一放在里面切换时点一下OpenCode 等工具就能读到对应的配置。我自己用下来的感受是ccswitch 的价值不在于省那几秒钟而在于它把“模型切换”变成了一个确定性的操作不用每次去翻配置文件也不用担心改错格式。尤其当你同时在 OpenCode 和别的 Agent 工具之间切换时一份配置多处使用体验要顺滑得多。要提醒的是免费模型普遍存在不稳定、额度有限、偶尔下线的现象。今天还能用的接口明天可能就返回 401 或者超时。这不是 OpenCode 的问题而是上游服务变动。我建议把免费模型当成尝鲜和辅助核心的、不能断的日常工作还是配一个稳定可用的量产模型。2.3 配置文件推荐写法与参数解读除了 Provider配置文件里还有几个参数值得关注。model默认模型可以是自定义 Provider 下的模型 ID也可以是 OpenCode 内置支持的模型。temperature控制回答的随机性。写代码、改 bug 我习惯设低一点比如 0.2 到 0.4太高的温度容易让它“自由发挥”写出不靠谱的代码。system系统提示词。你可以在这里写一些通用规则比如“所有代码必须有注释”或者“不要修改锁文件”。autoupdate控制 OpenCode 是否自动更新。如果你在公司内网或网络受限环境我建议关掉避免启动时卡在更新检查上。themeTUI 主题纯个人喜好不影响功能。如果你用的是 Maven 项目还有一个很容易被忽略的点。有热搜词是“opencode mvn 配置”实际上这不是 OpenCode 配置文件里的东西而是你的 Java/Maven 环境变量问题。OpenCode 在帮你执行mvn test或mvn compile时需要能找到JAVA_HOME和mvn命令。所以装 OpenCode 之前先在终端里确认java -version mvn -version如果这两条命令都能正常输出那 OpenCode 调用 Maven 就没问题。反过来IDEA 插件里遇到 Maven 相关报错十有八九也是环境变量没传进去。3. 实战集成VSCode、IDEA 与桌面版3.1 VSCode 插件从终端走进编辑器OpenCode 虽然出生在终端但日常写代码时大家还是更习惯待在编辑器里。VSCode 插件的好处是它和全局配置完全打通你在终端里配好的模型、Skills、AGENTS.md插件都能直接复用。安装方式很简单在 VSCode 扩展市场搜“OpenCode”装好后左侧会多出对话面板。你可以直接选中一段代码让它解释、重构或者补测试。它给出的修改会以 diff 形式呈现你自己确认后再 apply而不是一言不合直接改文件。用下来我最喜欢的是“选代码提问”这个场景。比如从一个大类里选中一个方法问问它这段逻辑有没有边界问题它给出的答案通常比在终端里描述半天上下文要准确得多因为上下文就是当前文件本身。有个细节需要注意VSCode 插件安装后要确保它能找到opencode可执行文件。如果你在终端里明明能跑插件却报找不到多半是插件启动时的 PATH 和终端不一致。直接在插件配置里把 opencode 的绝对路径填上最省事。3.2 IDEA 插件Java/Kotlin 项目的舒适圈如果你是 Java 开发者JetBrains IDEA 也有对应的 OpenCode 插件安装后在右侧工具窗口就能直接对话。IDEA 插件和 VSCode 插件的使用逻辑一样但有一个非常典型的问题IDEA 本身是从桌面图标启动的它的 PATH 环境变量可能不包含你终端里配置的那些路径。所以你在 IDEA 插件里配 OpenCode 时不要想当然地以为它能自动找到命令。我建议在插件设置里手动指定 opencode 可执行文件的绝对路径比如 Windows 下的C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd或者 mac 下的/usr/local/bin/opencode。另外Maven 项目在 IDEA 插件中跑构建时如果出现“mvn 命令找不到”或者“JAVA_HOME 找不到”不要怪 OpenCode看看 IDEA 本身能不能正常执行 Maven。这里有个很实用的排查方法在 OpenCode 对话里直接让它运行mvn -version看返回的结果如果这一步就不通过那问题出在环境变量而不是 Agent 本身。3.3 桌面版与 CLI 工作流的取舍桌面版适合刚入门、不想记命令的人。它能用图形界面完成模型配置、对话和文件修改确认体验比较友好。但我个人的观点是如果你已经是一个会写代码的人CLI TUI 的收益其实更高。原因是 CLI 可以编进脚本可以做自动化可以在任意的项目目录里快速启动而桌面版更适合点一点、看一看的轻量使用。日常我比较推荐用opencode run做一次性任务比如opencode run 看一下 src 目录下的代码找出没有错误处理的函数这种用法比每次都开全屏 TUI 更快也方便你把它接进自己的项目脚本里。桌面版、IDE 插件、CLI 三者可以共存底层共用同一套配置所以不用担心冲突。我的建议是终端党直接用 CLIIDE 重度用户装插件完全不想碰命令行的用桌面版。4. Skills 与 Memory从“能用”到“好用”4.1 AGENTS.md给 OpenCode 一份项目说明书很多人的 OpenCode 装完之后只会简单问答但真正好用的 Agent 应该知道你的项目是怎么组织的。AGENTS.md 就是干这个的。你可以把它理解成给每个新入职的工程师准备的交接文档。模型本身没有记忆每次对话它都是“新人”而 AGENTS.md 能让它快速了解项目的技术栈、目录结构、构建命令、编码规范。一个典型的 AGENTS.md 长这样# 项目说明 这是一个基于 Vue 3 TypeScript 的前端项目包管理工具使用 pnpm。 ## 常用命令 - 安装依赖pnpm install - 启动开发服务pnpm dev - 运行测试pnpm test ## 代码规范 - 组件文件统一放在 src/components 下 - 状态管理使用 Pinia - 不要修改锁文件除非升级依赖 - 所有对外接口必须有类型定义 ## 注意事项 - 测试环境接口地址在 .env.development 中配置 - 修改后端接口时需要同步更新 src/api 下的文件写完之后放到项目根目录OpenCode 在项目里启动时会自动读取它。全局规则可以放在~/.config/opencode/AGENTS.md这样所有项目都生效项目级规则就放项目根目录只对当前项目生效。我自己实测下来写完 AGENTS.md 之后OpenCode 生成的代码风格明显更贴近项目实际减少了很多来回纠正的次数。这比你在每次对话里重复说明命令要高效得多。4.2 Skills 机制让 Agent 具备专项技能OpenCode 较新的版本支持 Skills 机制。简单来说你可以把一组提示词和脚本打包成一个“技能”比如代码审查技能、Docker 运维技能、日志排查技能。模型在遇到对应场景时会主动调用这些技能而不是每次从零开始理解你的需求。这种思路和 oh-my-claudecode、superpowers 这些社区项目是相通的。它们本质上都是把大量实用的提示词和技能目录整理好让你复制到自己的环境里直接用。OpenCode 2.0 之后这种“技能包”的使用越来越顺手很多原本在 Claude Code 里流行的玩法都能平移到 OpenCode 里。如果你下载了某个技能包注意看它的目录结构通常里面会带 skill 描述文件和相关的脚本。把这些内容放到项目根目录的 skills 目录或者放到全局配置对应的 skills 目录重启 OpenCode 后就能看到技能列表。我自己更倾向于先用原生的 AGENTS.md 把项目规范喂给模型再按需引入技能包避免一上来就装一堆技能反而不知道该用哪个。4.3 用 Playwright 做前端 Bug 自动修复“opencode playwright 怎么测试前端 bug”这个问题问得非常多我展开说一下。在很多前端项目里bug 并不是靠看代码就能定位的尤其是复杂的交互问题需要真实打开浏览器复现。OpenCode 配合 Playwright 技能可以自动启动浏览器、访问本地开发地址、点击元素、抓取控制台报错和网络请求然后把完整现场信息交回给模型分析。操作流程大概是这样的让 OpenCode 用 Playwright 打开本地开发服务比如http://localhost:5173。让它执行你描述的操作比如“点击提交按钮”。它会返回页面截图、控制台报错和关键网络请求信息。模型基于这些信息分析问题根源再回到代码里给出修复方案。一个比较实用的 prompt 示例opencode run 用 Playwright 打开 http://localhost:5173点击登录按钮如果出现报错或者页面无法跳转把控制台错误和页面截图发给我然后定位原因并给出修复建议需要注意的是用这个功能前你得确保本地已经装好 Playwright 和对应浏览器。如果项目里已经集成了 Playwright 测试框架那 OpenCode 会直接复用现有环境体验更好。这条链路是我目前觉得 OpenCode 最有价值的使用方式它不只是“帮你写一段代码”而是“帮你复现问题、分析问题、再给出修复方案”。对于复杂前端 bug这一套流程能把排查时间从几小时压缩到几分钟。5. 常见问题与避坑速查5.1 Windows 命令无法识别怎么办这个问题的出现频率最高尤其是在 Windows PowerShell 环境。报错信息一般是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。我直接给一个排查顺序错误现象可能原因解决思路输入 opencode 提示无法识别npm 全局 bin 目录不在 PATH执行npm prefix -g找到 bin 目录加入 PATH安装了却提示找不到模块npm 安装过程中断或 registry 异常卸载重装检查 npm registry能启动但闪退终端或系统环境变量异常重新打开终端或换一个终端再试执行 opencode run 无反应Node 版本过低升级 Node 到 20 以上如果 PATH 已经配好但还是不行可以在终端里输入Get-Command opencode看看系统到底找没找到这个命令。找到的话它会显示完整路径找不到就继续排查 PATH。5.2 unexpected server error 的排查思路这个报错的完整提示通常是error: unexpected server error. check server logs很多人以为这是安装问题其实不是。出现这种报错OpenCode 本身已经启动成功了但它向后端模型服务发请求时失败了。常见原因包括API Key 填错了或者已经失效。BASE_URL 地址不可达或者路径写错。模型 ID 在当前服务下不存在。免费模型额度耗尽或者服务已经下线。网络超时请求迟迟没有响应。排查思路是先在项目目录里跑一条最简单的命令opencode run 你好如果连最简单的对话都报错那就是模型配置问题。换一个已知可用的模型服务测试或者打开 OpenCode 的日志目录通常位于用户目录下的~/.local/share/opencode/log看具体的错误信息。如果你用的是免费模型刚看到这个报错第一反应应该是去查上游服务状态而不是反复重装 OpenCode。网上经常有人问“hy3-free 下线了吗”这种问题本质上就是因为免费模型的上线、下线、额度耗尽都会让用户产生“是不是我装错了”的错觉。5.3 OpenCode、Codex、Claude Code 怎么选这个问题基本每周都有人问。我根据自己的使用感受做个横向对比维度OpenCodeCodexClaude Code开源开源MIT 协议闭源闭源模型绑定可自由切换模型绑定同类模型生态绑定 Claude 系列配置灵活度高支持自定义 Provider中和官方生态绑定深中模型相对固定上手难度中等配置项多低开箱即用低命令简单直接适合场景想掌控全流程的开发者GitHub 生态重度用户追求高质量代码生成的用户如果你喜欢折腾、想让 Agent 按自己的规则来OpenCode 是最合适的。如果你只想开箱即用并且主要工作在 GitHub 上进行Codex 会更顺手。如果你对写码质量要求极高也不介意模型绑定Claude Code 的体验确实顶。老板问“Opencode 是哪家公司的”简单说一句就是 SST 团队的开源项目不是某个大厂闭门造的车。它也正因为开源才让插件、技能包、模型接入这些事情玩得这么花。最后分享一个我实际工作中的小体会OpenCode 真正让我留下来的是opencode run加上 AGENTS.md 和 Playwright 这条链路。它改变了我处理 bug 的方式——以前是我自己开浏览器、抓报错、猜根因现在是我把问题描述清楚Agent 带着工具先去收集现场再回到代码里给方案。装好之后别急着折腾一堆技能先把最小链路跑通安装、配模型、写 AGENTS.md、执行一次真实任务。这条路走顺了后面所有扩展都是锦上添花。