最近我把市面上的 AI 编程 Agent 基本都折腾了一遍Claude Code、Codex CLI、Gemini CLI还有一个以前被我忽略的开源选手——opencode。说实话最早我对它没什么期待终端里这类工具太多了直到某天我把 Gemini Flash 这种免费模型接到 opencode 里在一个老项目上当“临时工”完成了一次前端 Bug 排查我才意识到这玩意儿可能是目前最“不挑食”的一个。这篇不是官方文档的复读而是我从安装到配置、从换模型到接 Skills、从命令行到桌面版的完整折腾记录。如果你正在纠结“该用哪个 AI Agent”或者已经装了 opencode 却不知道怎么配才顺那这篇应该能帮你少走不少弯路。1. 它是什么一个不绑定模型的终端 AI 同事1.1 为什么我会从“试试看”变成“主力”opencode 本质上是一个运行在终端里的 AI 编程助手定位和 Claude Code 很像你给它一个任务它能自主读取项目文件、搜索代码、修改文件、执行命令然后给你反馈。但和 Claude Code 这种深度绑定 Anthropic 模型的产品不同opencode 从设计上就不想“站队”它把大模型抽象成了可替换的 Provider你可以自由选择 Anthropic、OpenAI、Google Gemini、DeepSeek、Ollama 本地模型甚至任何兼容 OpenAI 协议的服务。我之所以从“试试看”变成“主力”就三个原因模型自由。我可以用 Claude 写复杂架构设计用 Gemini Flash 跑日常修 Bug用本地 Ollama 看看代码结构不用为每个模型单独开一套工具。全终端工作流。我本来就常驻终端opencode 的 TUI 界面在 iTerm 里跑起来很顺手开多个会话也不乱。配置看得见摸得着。opencode 的配置就是一份 JSON 文件改模型、改 baseURL、调权限改完重启就能生效不像某些闭源产品选项藏在设置深处。如果你是一个需要同时对接多个模型、又不想被某个厂商锁死的开发者opencode 大概率会戳中你。它特别适合这几类人经常做 PoC、要在不同模型间横向对比效果的人需要本地离线代码分析的人以及看不惯图形 IDE 全家桶、坚持终端流的人。1.2 横向对比opencode / Claude Code / Codex CLI / Gemini CLI为了避免引战我尽量客观地列一下我用过的感受对比工具是否开源多模型支持免费模型接入终端体验生态扩展opencode是强多 Provider支持TUI 完整适合重度终端用户Skills、Memory、插件社区活跃Claude Code否弱主要是 Claude基本不支持好会话管理成熟生态丰富但封闭Codex CLI是弱偏 OpenAI 系受限简洁但功能单薄刚起步插件少Gemini CLI是弱偏 Gemini 系支持自身免费额度简洁刚起步单纯说“谁更好”其实不成立。我的选择是需要深度工程能力、愿意为模型付费时用 Claude Code需要快速白嫖、多模型对比、本地离线分析时用 opencode。Codex CLI 和 Gemini CLI 更像“厂商定制的专用客户端”而 opencode 像“瑞士军刀”。这里要特别提一句opencode 对“免费模型”的支持是一个很实际的优势。很多人玩 AI 编程最先被卡住的就是 API 费用opencode 能接 Gemini Flash、DeepSeek、Ollama 这类低成本或免费渠道相当于把一个入门门槛直接踩平了。后面第 3 章我会给出具体搭配方案。2. 安装与环境准备别在第一步卡住2.1 四种常见安装方式opencode 的安装方式挺多官方文档推荐优先用一键脚本但我个人更建议根据系统选。方式一官方脚本macOS / Linuxcurl -fsSL https://opencode.ai/install | bash这个脚本默认把可执行文件装到用户目录下不会污染系统级 PATH也不要求 sudo适合绝大多数人。安装完脚本会提示你把某个目录加入 PATH我装完后的路径是~/.opencode/bin。方式二npm 全局安装npm i -g opencode-ai这个方式适合已经有 Node.js 环境、且习惯用 npm 管理全局工具的人。注意 npm 全局安装的 bin 目录和系统自带目录不一定一致如果你用的是 nvm那 opencode 会装到当前 Node 版本的 bin 下面换个 Node 版本就“消失”了。方式三HomebrewmacOSbrew tap sst/tap brew install sst/tap/opencode如果你是 Homebrew 的重度用户这个方式最省心后续升级直接用brew upgrade opencode就行。方式四Go 安装go install github.com/sst/opencode/cmd/opencodelatest热词里有人提到“opencode go 需要配合 cc switch 等工具”指的就是这种方式。用go install装出来的二进制默认只读取当前用户环境里的 API Key 配置如果你在机器上同时维护了多套账号或模型 Provider就需要配合 ccswitch 这类工具来切换身份后面 3.4 我会展开。装完之后先跑一下opencode --version看到版本号就说明装成功了。2.2 Windows 环境“无法识别‘opencode’项”的救法如果你在 Windows PowerShell 里执行opencode报这个错opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称别慌这八成是 PATH 没配上不是软件坏了。我看好多人卡在这一步其实就两个检查点确认安装目录。用一键脚本装的话通常会在用户目录下生成.opencode/bin用 npm 装的话npm 全局 bin 目录一般在%APPDATA%\npm或你自定义的 prefix 目录。把目录加进系统 PATH。按Win R输入sysdm.cpl打开“环境变量”在用户变量里找到 Path新增上面那个目录然后重新打开一个终端窗口。注意修改 PATH 后已经打开的 PowerShell 或 CMD 窗口不会自动刷新必须关闭重开。这个细节我踩过坑搞了半天以为是安装问题结果就是没重开窗口。如果加了 PATH 仍不行再检查一下是不是被 PowerShell 的执行策略拦了。可以临时执行Get-ExecutionPolicy如果返回 Restricted用下面这个命令放开当前用户只是当前用户不影响系统Set-ExecutionPolicy -Scope CurrentUser RemoteSigned2.3 第一次启动登录、选模型、跑一个任务安装完成后在项目目录里直接运行opencode第一次启动会进入一个交互式引导。这个引导一般会问你用哪个 Provider、是否需要登录。opencode 支持两种身份建立方式opencode auth login交互式登录适合 Anthropic、OpenAI、Google 这类官方 API。直接设置环境变量比如ANTHROPIC_API_KEY、OPENAI_API_KEY、GOOGLE_API_KEYopencode 读到后会自动关联对应 Provider。我自己的习惯是先不登录先把一个免费模型配上跑通整条链路再说。比如你有一个 Gemini API Key可以先设置export GOOGLE_API_KEY你的key opencode进去之后输入一个最简单的任务比如“请把当前目录下的文件列表和项目结构简要介绍给我”看它能不能正确调用工具、返回结果。如果这一步通了说明工具链没问题后面再慢慢调模型和权限。第一次运行命令时opencode 通常会弹确认提示问你是否允许执行某些操作。这个设计我觉得比某些工具“一声不吭直接跑命令”要安全得多但也会让第一次使用的人觉得“怎么老问我”。习惯就好后面可以配置自动批准白名单命令。3. 模型配置与个性化免费模型也能跑得很顺3.1 API Key 的三种配法opencode 读取模型密钥的方式主要有三种从临时到持久第一种环境变量临时适合单次会话export OPENAI_API_KEYsk-xxxx export ANTHROPIC_API_KEYsk-ant-xxxx export GOOGLE_API_KEYxxxx opencode第二种opencode auth login持久化官方推荐执行后按提示选择 Provider它会帮你把凭证写到系统钥匙串或本地配置文件里之后每次启动自动读取。好处是安全坏处是你想在同一台机器上切换不同账号时会有点麻烦。第三种配置文件opencode.json持久化可版本管理在项目根目录或用户配置目录~/.config/opencode/放一份 JSON可以在里面显式指定要用哪个模型、哪个 Provider 地址。示例如下{ $schema: https://opencode.ai/config.json, model: google/gemini-2.5-flash, provider: { google: { options: { apiKey: {env:GOOGLE_API_KEY} } } } }这个{env:GOOGLE_API_KEY}写法表示从环境变量读取而不是把 Key 硬编码到仓库里。如果你是团队协作强烈建议用这种方式把opencode.json提交到仓库但千万别把 Key 提交上去。3.2 免费与低成本模型组合很多人问 opencode 能不能不花钱用。能但要降低预期。我实测下来比较顺的免费或低成本组合有三个组合 AGoogle Gemini 系列免费额度最香Gemini Flash 系列的免费额度对于个人日常开发非常够用响应速度也快适合做代码解释、重构建议、写单测。配合 opencode 的搜索和文件编辑能力修 Bug 效率很高。组合 BDeepSeek价格低综合能力强DeepSeek 的 API 价格便宜能力在线尤其擅长中文场景下的代码理解。它不是免费但量小时几乎是几分钱级别。如果你不想折腾免费模型这是性价比很高的选择。组合 COllama 本地模型完全离线、完全免费在本地启动 Ollama 后opencode 里配置一个本地 Provider 即可。比如ollama run qwen2.5-coder然后在 opencode 配置里把模型指向ollama/qwen2.5-coder或类似标识。这个适合敏感项目、离线环境或者你只想用 AI 做“代码阅读器”的场景。我的建议是日常高频简单任务用 Gemini Flash写复杂逻辑或架构分析时切到 Claude预算敏感就 DeepSeek完全离线就 Ollama。这就是 opencode 多 Provider 最大的价值——你不需要一个工具伺候一个模型。3.3 opencode.json 示例改模型、改 baseURL、调权限除了模型选择opencode.json最常用的是改 baseURL 和权限控制。如果你用的是某个 OpenAI 协议兼容的网关或企业私有端点就可以把 Provider 的 baseURL 指过去{ provider: { openai: { options: { baseURL: https://your-gateway.example.com/v1 }, models: { my-custom-model: { name: My Custom Model } } } } }这个机制我很喜欢等于把“用哪个模型”和“从哪访问模型”解耦了。很多公司内部有统一的大模型网关opencode 通过 baseURL 直接对接不用改业务代码。权限控制方面你可以在配置里声明哪些命令无需确认、哪些必须确认。比如允许 AI 直接运行npm test和git diff但禁止直接执行rm -rf{ permissions: { allow: [npm test, git diff, git status], deny: [rm -rf *] } }注意权限配置不同版本字段名可能略有差异以官方 schema 为准。我习惯先把deny写保守一点尤其是自动模式下AI 真的会执行命令别等到把环境搞坏了才想起来设权限。3.4 用 ccswitch 管理多个身份配合 Go 版本热词里那句“opencode go 需要配合 cc switch 等工具”我深有体会。用go install装的 opencode 是纯二进制它不会像某些 GUI 应用那样帮你管理“多个登录身份”。当你有多个 API Key、多个 Provider 账号或者一个模型对应多个网关时手动改环境变量很容易乱。ccswitch 在我理解里就是干这个的你用命令行把一个“身份/配置组合”切换好它会把对应的环境变量或凭据导出给当前 shellopencode 启动时自然就读取到了。相当于把“切换模型身份”这件事从“改配置文件 重启”变成了“一行命令”。我的实操流程是# 先创建一个名为 work 的配置绑定公司网关 key ccswitch create work --provider openai --base-url https://gw.example.com --key sk-xxx # 切换到 work 配置并让环境变量生效 ccswitch use work # 在当前终端里启动 opencode opencode这样 opencode 完全不用改任何配置因为它读的是标准环境变量。好处是多个工具opencode、Claude Code、Codex CLI都能共享同一套身份管理不会出现“这个工具能用那个工具不能用”的尴尬。4. 实战场景接手老项目、修前端 Bug、装 Skills 和 Memory4.1 快速盘点一个陌生项目实战是我最看重的部分。先拿“接手老项目”来说这是 opencode 最典型的应用场景丢给你一个 Git 仓库几十个文件没文档没人带。我的做法是在项目根目录启动 opencode然后给它一个非常具体的“盘点任务”请先阅读 README、package.json 和项目目录结构然后告诉我 1. 这个项目是做什么的技术栈是什么 2. 本地启动命令是什么 3. 测试命令是什么 4. 有没有明显的 TODO 或 FIXME 标记集中在哪些文件里。opencode 会调用文件搜索和读取工具把关键文件都翻一遍最后给你一份摘要。这一步能节省大量“人肉翻目录”的时间。而且因为有终端命令执行能力它可以直接跑npm install、npm test来验证依赖是否完整而不只是“纸上谈兵”。不过要注意老项目往往有坑比如某个依赖装不上、某个本地服务没启动opencode 的执行结果会和预期不一致。这种时候别急着让它继续改代码先让它看日志、搜索报错信息把环境问题解决了再说。4.2 用 Playwright 复现并定位前端 Bug“opencode playwright 怎么测试前端 bug”这个热词说明很多人已经意识到AI 写代码是一回事AI 自己验证代码是另一回事。opencode 的一个实用姿势是让它把 Playwright 当作自己的“眼睛”去浏览器里复现问题。具体流程我举一个真实场景某个老项目里“购物车删除商品后数量不更新”。我在 opencode 里的指令是这样下的项目已经启动了跑在 http://localhost:5173。 请写一个 Playwright 脚本完成以下操作 1. 打开首页 2. 搜索商品并加入购物车 3. 进入购物车点击第一个商品的删除按钮 4. 等待页面刷新后读取购物车角标数量 5. 如果数量没有变化把控制台所有报错截图并保存到 /tmp/opencode-debug。 然后运行这个脚本告诉我失败原因。opencode 会生成一个临时的 Node 脚本也可能是 Python 脚本取决于项目环境然后通过终端执行。它可以根据执行结果反复调整选择器、等待条件直到把 Bug 稳定复现出来。比如最终跑出来的结果可能是“删除接口返回 500因为请求头里少了 CSRF token”。这时候再让 opencode 去看对应的请求封装代码修复就是顺理成章的事了。这个模式的核心价值在于AI 不再“我觉得没问题”而是“我用脚本证明有问题”。如果你写前端强烈建议把 Playwright 脚本能力纳入你的 opencode 日常流程。4.3 通过 Skills 扩展能力安装 superpowersopencode 的 Skills 机制简单理解就是给 AI 预装“工作手册”。它是一组结构化的提示词和工具说明告诉 AI 在某类任务上应该按什么流程走。比如“代码审查 Skill”会要求 AI 先看 diff、再定位影响面、最后给出分级意见“架构评审 Skill”会要求 AI 先画依赖关系、再分析循环依赖。热词里的“opencode 安装 superpowers”就是指安装社区里很流行的一套 skills 集合——superpowers里面包含了不少高质量的工作流。安装方式一般有两种把仓库 clone 下来然后将 skills 目录链接到 opencode 的配置目录或者直接把 skill 文件复制进去。常见的目录位置是全局~/.config/opencode/skills/项目级.opencode/skills/我装上之后最直观的感受是AI 处理问题的“套路感”变强了。比如让它做 Code Review它不会只丢一句“看起来不错”而是会按步骤检查错误处理、安全风险、性能隐患并且给每条建议标注严重级别。这就是 Skills 的功劳。如果你开发了内部规范也可以把它们写成自定义 Skill相当于把团队最佳实践固化到工具链里。4.4 让 opencode 记住你的偏好Memory热词里有“opencode memory”。这个功能解决的是“AI 每次对话都失忆”的问题。opencode 会在启动时自动读取一些项目内或用户级的上下文文件作为“长期记忆”。我自己的做法是在项目根目录放一个AGENTS.md具体文件名和 opencode 版本有关你可以看官方文档确认里面写清楚项目的技术栈、目录职责启动和测试命令代码风格要求比如“组件用 TypeScript”“样式用 Tailwind”“禁止不写错误处理”已知的坑比如“这个项目不要执行npm run clean会删掉本地数据库”。这样每次 opencode 进入项目都会先把这份“备忘录”读一遍生成代码时更贴合项目实际。我实际测下来它对生成内容的风格一致性有明显改善尤其适合多人协作、代码规范多的团队。个人用户也可以把通用偏好放在用户级 Memory 文件里比如“提交信息用 Conventional Commits 格式”“测试文件放在 src/tests下”之类这样所有项目都生效。4.5 桌面版和 IDE 插件换一个入口继续用终端虽好但不是所有人都喜欢。opencode 也提供了桌面版和 IDE 插件我理解它们并不是“另一个产品”而是同一套引擎的入口。桌面版的好处是可以把会话、配置、日志都放到一个可视化的界面里适合处理复杂任务时边看边操作。我还是习惯终端但如果你给非命令行重度用户推荐 opencode桌面版显然更容易上手。VSCode 插件和JetBrains IDEA 插件则是另一种形态不用离开编辑器直接在侧边栏打开 opencode 面板选中代码发给 AIAI 返回 diff 后可以快速接受或拒绝。在 IDEA 里用的时候我主要拿它做“局部重构”因为编辑器上下文就在眼前改完马上能跑测试。“opencode vscode 插件”“opencode jetbrains idea 插件”这些热词说明大家确实需要这种无缝融入 IDE 的体验。插件安装就和普通插件一样在插件市场搜索 opencode 即可。装好后注意看它默认绑定的快捷键我经常误触后来直接改了快捷键。5. 常见问题与排查手册5.1 unexpected server error 的排查思路热词里有一条非常具体c:\windows\system32opencode error: unexpected server error. check server logs这个报错我遇到过不止一次而且原因五花八门。下面是我排查此类错误的一套固定套路先看日志。opencode 通常会在本地写日志文件路径一般在~/.local/share/opencode/log/或用户配置目录下按日期滚动。打开最新一份重点找栈信息里的 HTTP 状态码比如 401 是鉴权失败429 是限流500 是模型网关异常。检查 Key 是否正确。先用echo $API_KEY确认环境变量没写错再确认 Key 没有过期。很多“unexpected server error”其实就是 401但被封装成了通用错误。检查代理变量。如果你在终端里设置了HTTPS_PROXY或HTTP_PROXY环境变量opencode 的请求也会走代理。代理本身不可用或返回异常时就会报这种模棱两可的错。可以试试临时unset HTTPS_PROXY HTTP_PROXY ALL_PROXY再跑一次排除代理干扰。切换一个 Provider 试试。比如原来用 OpenAI切到 Gemini如果问题消失基本能锁定是上游模型服务的问题而不是 opencode 本身的问题。我的经验遇到这个错误先别急着重装90% 的情况要么是 Key 失效要么是网络代理问题要么是上游服务限流。按上面顺序排查比盲目重装快得多。5.2 Maven/Java 环境里执行命令失败多半是子进程环境问题热词里有个“opencode mvn配置”。我最初看到也愣了一下后来反应过来这多半是指在 Java/Maven 项目里用 opencode 时AI 执行mvn test或mvn package失败的情况。opencode 执行命令时子进程继承的是你启动 opencode 的那个 shell 环境。这意味着它不一定能拿到你在 GUI 应用里配置的 JAVA_HOME或者你的 Maven 不在 PATH 里又或者本地~/.m2/settings.xml里配了某个私服地址但当前网络不通。遇到这种情况建议先手动在终端里确认环境是好的mvn -v java -version如果手动能跑而 opencode 跑不了看看是不是你启动 opencode 的方式漏掉了环境变量比如用 IDE 内置终端启动时没加载~/.zshrc。解决方案很简单把必要环境变量写进opencode.json里或者直接在项目根目录的 Memory 文件比如 AGENTS.md里写明“构建命令必须显式使用mvn -s /path/to/your/settings.xml”。5.3 免费模型频繁限流怎么办免费模型用久了最典型的问题就是限流。Gemini Flash 的免费额度虽然香但同一时间段的请求太多会返回 429。opencode 遇到限流通常表现为任务跑到一半突然报错然后整个会话卡住。我的应对策略有两个一是在opencode.json里把超时和重试参数调得激进一点让它在限流时多等一会儿再重试具体字段名看官方配置 schema各版本略有差异。二是把模型分级使用简单任务用免费模型复杂任务手动切到付费模型。反正 opencode 切换模型很方便我一般会在任务开始前想清楚“这个活值不值得用好模型”。比如改文案、补注释、整理目录结构都用 Gemini Flash涉及跨模块重构、性能优化、架构设计再切 Claude 或 GPT。5.4 opencode 2.0 升级后的注意点热词里提到“opencode 2.0”。我升级后的第一感受是权限确认更严格了很多以前默认放行的操作现在会拦截这是好事但如果你升级后发现“AI 怎么变笨了总是停下来问我”多半不是模型变笨而是权限策略变了。遇到这种情况先把配置里被拦的命令加进allow列表。另外 2.0 之后的一些底层命令格式也做了调整如果你用旧版本的 prompt 写法可能出现“调用工具失败”的情况把 Skill 里的指令更新一下就好了。升级利器尽量把 opencode 的配置文件和 Skills 都纳入 Git 管理。这样每次升级后出现行为差异你可以直接 diff 配置或回滚而不是靠记忆力排查。最后分享一点个人体会用了这么久我的整体感觉是opencode 不是一个“花架子”工具它的核心价值在“多模型自由”和“可编程的工程化能力”上。它不像某些闭源工具那样开箱即用、体验标准化但恰恰是这个“不标准化”让它变得极其灵活。如果你也想尝试我建议第一天下来的目标就定三个装上、跑通一个免费模型、用 Playwright 复现一个 bug。这三步做完你对它到底适不适合自己心里基本就有数了。踩过几次坑之后我最常做的事反而是在 opencode 里同时开两个会话一个用便宜模型读代码一个用贵模型写核心逻辑配合起来比任何单一工具都省心。这也算是它留给我的最大惊喜吧。