写 opencode 这篇文章之前我特意把它从热词榜里翻出来看了看发现周围不少同事已经在用这个终端 AI 编程助手干活了。很多人第一反应是“又一个 Claude Code 的平替”但真正上手之后你会发现opencode 走的路线不太一样——它更强调本地优先、模型自由切换还有一套可扩展的 Skills 机制。这篇文章我会从安装配置讲起逐步拆解多模型切换、Skills、Memory、编辑器插件这些核心功能再把我在实际使用中踩过的坑和排查思路一并整理出来给想入门或者已经卡在某个问题上的朋友一份可以直接照着做的参考。1. opencode 到底是什么凭什么让这么多人换掉手上的工具1.1 终端 AI Agent 的定位它和普通的聊天助手有什么区别先说说大背景。这两年的 AI 编程工具已经从“帮你补全代码”进化到了“替你把整个任务跑完”的阶段。终端里跑起来的 Agent 和你在网页上用的 ChatGPT、Copilot 聊天窗口完全是两码事终端 Agent 能直接读写你的项目文件、执行 Shell 命令、跑测试、看报错日志然后根据结果自己决定下一步干什么。它像一个坐在你电脑前面、能亲手操作代码仓库的实习生而不是一个只会给建议的顾问。opencode 就是这类终端 Agent 里比较有代表性的一个。它的核心定位是“开源的、模型无关的、适合日常开发流程的终端 AI 助理”支持 Claude、GPT、Gemini 以及本地模型比如 Ollama 拉起来的 Qwen、Llama作为后端。所以它天然适合这几类人用 Vim/Neovim 或者纯终端工作流的老手想在 IDE 里补一个趁手 AI 插件的同学以及被某个云厂商模型绑定搞得很烦、想随时换模型的人。我第一次把它当成主力工具是因为一个实际需求当时手上有个 Go 微服务项目需要把老的 HTTP 客户端统一替换成 Resty涉及几十个文件。这种活儿说难不难但就是量大、重复、容易漏。用 opencode 跑了一遍它在项目里自己 grep 出了所有用到net/http的文件逐个重写跑go build报错了自动修最后跑了一遍go test——这个过程我基本没插手它自己完成了一个“从分析到验收”的闭环。从那以后我就意识到终端 Agent 的价值不是帮你写几行代码而是把整个“改代码-验证-修错”的循环压缩了。1.2 核心功能拆解Agent 循环、多模型、Skills 与 Memory要理解 opencode 的设计思路我把它拆成四个功能模块来看。Agent 循环opencode 启动后处于交互式终端界面你给它一个任务它会自动拆解成步骤每次只操作一个文件、执行一条命令然后观察结果继续下一步。这个过程不是一次性的“问一句答一句”而是一个持续到任务完成才停止的循环。你随时可以按Esc打断它手动接管某个文件的修改。多模型后端它不绑定某一家模型。你可以同时配置 Anthropic、OpenAI、Google 的 Key在会话中用快捷键或者命令随时切换。这一点在对比模型效果、控制成本、规避某个模型抽风的时候特别有用。Skills这是我很看重的一个能力。Skill 是一段 Markdown 格式的“技能说明书”放在~/.config/opencode/skills目录下告诉 Agent“遇到这类任务时你应该按什么流程做”。比如我写了一个commit-message的 Skill让它在生成提交信息之前先看git diff和项目里的 commit 规范。这相当于给 Agent 装配行业规范和团队约定。Memoryopencode 会维护跨会话的项目记忆和用户全局记忆。一个项目里你告诉过它“这里用的是标准库的 log不要引入 zap”下次再开这个项目的时候它仍然记得。这解决了很多终端 Agent “每次会话都失忆”的痛点。这四个模块加在一起opencode 就不再是一个“聊天框”而是一个可以复用的开发流程执行器。我的理解是Agent 循环负责“干活”Skills 负责“定义怎么干活”Memory 负责“记住活是怎么干的”多模型负责“换不同人来干”。后面我具体展开每一步怎么配置和使用。2. 安装与配置从零到能跑第一个任务2.1 安装方式的对比与选择opencode 目前提供了几种安装途径我挨个试过给你一个明确的优先级参考。安装方式适用平台速度我推荐官方 curl 脚本macOS/Linux快最省事首选HomebrewmacOS/Linux快喜欢用 brew 统一管理就选它手动下载二进制全平台取决于网速Windows 用户、想固定版本时用Go install已装 Go 环境中等开发者尝鲜、想装特定 commit 时用以最常见的 macOS 和 Linux 为例官方脚本就一行curl -fsSL https://opencode.ai/install | bash脚本会把可执行文件放到~/.opencode/bin并在 shell 配置里加好 PATH。装完执行opencode --version能输出版本号就说明没问题。如果你装了 Homebrew那就更简单brew install opencode两条路我都走过。国内网络环境下curl 脚本偶尔会因为 GitHub 下载慢而卡住可以用手动下载二进制的方案去仓库的 Releases 页面拿对应架构的压缩包解压之后放到/usr/local/bin或者你自己建的工具目录。Go install 适合喜欢尝鲜编译最新版的人但要注意你的 Go 版本不能太老否则可能编译失败。Windows 用户建议直接用 PowerShell 配合下载二进制包解压然后把目录加进系统 PATH。这个后面在常见问题部分我会专门提一句因为热词里好几个搜索都指向 Windows 上“无法识别 opencode 命令”的问题其实是 PATH 没配好。2.2 基本配置模型、API Key 与代理环境opencode 安装完之后不会自动有模型可用你需要先告诉它用谁的模型。配置文件默认位置是~/.config/opencode/opencode.jsonmacOS 上是~/.config/opencode/opencode.jsonWindows 在%USERPROFILE%\.config\opencode\opencode.json。最小化的配置长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { anthropic: { api_key: sk-ant-..., options: { base_url: https://api.anthropic.com } } } }这里有个概念容易让新手懵anthropic/claude-sonnet-4这种带斜杠的写法其实是“提供商/模型名”的组合。opencode 内置了一个模型路由支持anthropic/、openai/、google/这些前缀甚至支持本地模型ollama/qwen2.5-coder:14b。你在交互界面里按快捷键默认是CtrlX或/models命令就能在当前会话里上下切换不同模型不需要改配置文件。分环境变量是最干净的用法。比如你在公司电脑上不想把 Key 明文写进 JSON可以直接设置环境变量export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-... export GOOGLE_API_KEYAIza...opencode 会优先读取环境变量。这一点在 CI/CD 里特别重要不用把密钥提交到仓库。有个细节值得注意如果你在的团队走的是公司内部网关需要在配置里加一个base_url指向内网地址。provider.options.base_url这个字段就是干这个的。2.3 编辑器插件VSCode 和 IDEA 的接入方式光在终端里用很多人会觉得不过瘾毕竟日常写代码还是要在编辑器里。opencode 官方和第三方的生态里都有编辑器插件热词里也反复出现“opencode vscode”“opencode idea 插件”“opencode jetbrains idea 插件”说明这块需求确实大。VSCode 插件的安装最简单直接在扩展市场搜 “opencode”装好之后在侧边栏会多出一个 AI 面板能直接和终端会话联动。最实用的功能是你在编辑器里选中一段代码右键选择“发送到 opencode”它会把代码上下文带到终端会话里同时把当前文件路径告诉 Agent。这样 Agent 修改完文件编辑器里会自动刷新不用手动 reload。JetBrains 全系IDEA、PyCharm、GoLand也有社区插件JetBrains 插件市场和插件仓库里能找到。功能上比 VSCode 版本略朴素一点但核心的“发送选中代码到 opencode”“读取项目上下文”都能用。装完插件后再配合 IDEA 自带的终端整个体验已经接近“原生 AI IDE”的感觉了。我的建议是如果你平时用 VSCode插件必装用 IDEA 的可以先在终端里跑熟练了再装插件因为这个插件目前的版本相比 VSCode 还是平了一点。插件本质上是“终端 Agent 的遥控器”真正干活的大脑在 opencode 的 Agent 循环里编辑器只是把你选中的代码、报错信息更方便地丢给它而已。3. 实操从修 Bug 到自动化重构opencode 到底怎么干活3.1 第一个任务让它在真实项目里修一个 Bug光说不练没意思我带你把第一个任务跑起来。假设你在一个 Node.js 项目里前端同事报了个 bug“列表页偶尔会出现重复数据”。你打开终端cd 到项目目录执行opencode进入 TUI 界面后直接输入看下这个项目里列表页的数据请求逻辑重点查一下分页参数找出可能出现重复数据的原因先不要改代码把分析结果告诉我。注意这里我特意说了“先不要改代码”因为刚上手的时候最好先观察它是怎么分析和行动的不要一上来就让它自由发挥。opencode 会先列出项目结构然后 grep 相关的请求代码找到分页逻辑后告诉你它怀疑是page和offset混用导致的。等它分析完你再继续输入分析得有道理直接按你的方案修修完跑一遍测试。这时候 Agent 才会真正动手改代码。改完一个文件它自己会执行npm test如果某个测试挂了它会读日志、回滚或者换个思路继续修。整个过程你会看到它快速地在“改文件-跑命令-看结果”之间切换这就是 Agent 循环。第一次用的时候我建议你别急着跑开盯着它操作两三分钟。这样做有几个好处一是确认它不会乱删文件二是学习它的操作习惯比如它会先备份再改还是直接改三是能及时按Esc打断免得它在一个明显错误的方向上越走越远。这个“人盯着、Agent 干”的节奏是使用终端 Agent 最核心的习惯。3.2 多模型切换与省钱策略opencode 最吸引我的一个设计就是“模型自由”。我用它干活时同一个会话里可能换三个模型简单问题写一个函数、解释一段代码用便宜的模型比如openai/gpt-5-mini或者anthropic/claude-haiku速度快价格低。中等任务重构某个模块、改测试用anthropic/claude-sonnet。复杂任务跨多个文件的架构调整、疑难 Bug 定位再切到openai/gpt-5或者google/gemini-2.5-pro。切换方式在 TUI 界面里敲/models它会列出当前配置的所有模型回车就能切换。也可以在对话中直接说“接下来用 GPT 来思考”这种指令它也能听懂。这里有个省钱三板斧一默认模型不要设成最贵的二遇到简单任务主动手动切到 haiku 这类便宜模型三长对话跑到后期历史很长的时候换到上下文窗口更大的模型避免因为截断导致遗漏。另外热词里提到的 “ccswitch 配置 opencode” 实际上是很多人在玩的一套“多配置切换”方案。ccswitch 本身是一个切换 AI 配置的工具通过它你可以给 opencode 准备多套 provider 配置比如一套走官方 API一套走第三方中转一套走本地模型然后用命令行一键切换。它的价值在于如果你同时给公司项目和私人项目服务不想手动改opencode.jsonccswitch 能把不同场景的模型、Key、base_url 都整理好。它的配置思路是把 opencode 的配置模板化然后按 profile 来覆盖。我用下来的体验是如果只是自己写代码完全不需要 ccswitch直接用环境变量和/models切换就够了。但如果你是那种“同时维护五六个项目、每个项目用不同模型渠道”的重度用户折腾一次 ccswitch 是值得的。3.3 Skills给 Agent 定义“怎么干活”Skills 是 opencode 生态里最被低估的功能。它的本质是“预置指令”但你不用每次都在对话框里把规则重新敲一遍——只要触发对应的 SkillAgent 就会自动加载这些规则。先看怎么装。Skill 的本质是一个目录里面放一个SKILL.md文件。目录路径是~/.config/opencode/skills/比如我建了一个review技能用于让 opencode 做代码审查# Review Skill 当用户请求“review”或“审查代码”时执行以下步骤 1. 运行 git diff 查看本次改动的文件 2. 逐个文件审查重点检查 - 是否有明显的空指针 / 未捕获异常 - 是否有调试用的 console.log / print 残留 - 数据库查询是否缺少索引或存在 N1 - 错误处理是否吞掉异常 3. 输出审查意见按“严重”“建议”“可忽略”分级 4. 不要直接改代码除非用户明确要求把这段存成~/.config/opencode/skills/review/SKILL.md然后在会话里输入reviewopencode 就会加载这个 Skill并按里面的步骤来执行。更妙的是它能把 Skill 和项目路径关联起来我把review这个 Skill 限定在团队项目里用其他项目不触发。Skills 的适用场景非常广提交信息的格式规范、新接手项目时的代码摸底流程、发布前的检查清单、特定框架的写法约定……基本上你希望 Agent “按团队规矩干活”的事情都可以写成 Skill。我现在的习惯是每在一个项目里踩一次大坑就把它沉淀成一个 Skill下次同类任务直接复用。3.4 Memory、Superpowers 和 Playwright 测试Memory 功能让 opencode 的记忆力明显提升。有两种记忆全局记忆存在~/.local/share/opencode/下主要是你告诉过它的通用偏好比如“我不喜欢 TypeScript 的非空断言”。项目记忆则存在项目目录的.opencode/下比如“这个项目用 pnpm不用 npm”“这个模块的接口文档在 docs/api.md 里”。下次再在这个项目里开会话它会主动加载这些记忆。热词里还有 “opencode superpowers” 和 “opencode playwright 怎么测试前端 bug” 这两条我一起说。Superpowers 是一个 Skill 集合包类似于给 Agent 装配了一堆现成的“职业技能”包括需求拆解、TDD测试驱动开发、Debug 流程等。你想给 opencode 装上只要有对应的 skills 目录把仓库克隆进去就行cd ~/.config/opencode git clone https://github.com/xxx/superpowers skills/superpowers装好后在会话里可以用/skills查看已加载的技能。Playwright 的接入则是我认为 opencode 前端能力的体现。终端 Agent 不是只能改后端代码它可以调用 Playwright 来打开浏览器页面、点击按钮、断言 DOM。想让它测一个前端 bug只需要在会话里告诉它用 playwright 打开本地开发服务器进入 /list 页面模拟用户快速点击翻页按钮 5 次观察是否出现重复数据。如果有把复现步骤和截图路径告诉我。opencode 会在当前项目里找 Playwright 的安装和环境然后执行测试脚本把结果反馈给你。这套能力尤其适合“前端 bug 难以描述、需要自动化复现”的场景实测下来帮我节省了大量和前端同学沟通的时间——直接给一条复现命令比文字描述一百遍管用。4. 常见问题与排查技巧实录4.1 Windows 下提示“无法将 opencode 项识别为 cmdlet”热词里这条出现频率很高几乎可以确定是 Windows 上最常见的安装问题。报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个问题的本质只有一个PowerShell 找不到 opencode 的可执行文件也就是 PATH 没配好。解决办法分步走确认 opencode 可执行文件的绝对路径。如果你是用go install安装的默认在%USERPROFILE%\go\bin\opencode.exe如果你手动解压二进制就看你放到了哪里。把那个目录加进系统 PATH。在 PowerShell 里执行[Environment]::SetEnvironmentVariable(Path, $env:Path ;C:\Users\你的用户名\go\bin, User)注意第二个参数要用实际的路径。加完之后一定要重开一个终端窗口因为 PATH 修改不会自动刷新到已打开的会话。重新执行opencode --version能出版本号就成功了。还有一种隐藏情况你明明装了 Node.js于是想用npm install -g opencode但如果你没装 Node 或 npm 的全局目录没进 PATH也会出现同样的报错。我的建议是 Windows 上就别折腾脚本安装和 npm 了直接下载官方 Release 里的.exe压缩包解压放到C:\tools\这种简单路径下手动配 PATH最稳。4.2 运行时报 unexpected server error另一个高频报错是这个error: unexpected server error. check server logs这个报错的信息量很大但也很容易误导人。“server error”并不一定是 opencode 服务端出了问题大多数时候是上游模型 API 返回了错误opencode 把它们包装成了这个提示。我按踩坑频率排了几种原因API 密钥失效或额度用尽查一下ANTHROPIC_API_KEY或OPENAI_API_KEY是否有效看官网的余额和限额。第三方中转或聚合 API 尤其容易出现这种情况因为服务商对并发、tokens 的限制比较多。模型名写错或者该渠道不支持指定模型配置里写了anthropic/claude-opus-4但你的 API 渠道没有这个权限服务器会报 404 或者 403opencode 统一显示成 unexpected server error。这种时候去/models看看确认当前模型到底是啥。base_url 配置错误如果你改了provider.options.base_url一定要检查路径对不对比如多写了/v1或者少了版本号。调试方式是用 curl 手测一下接口是否能通。上下文超长如果你的对话历史非常长超过模型上下文窗口上游会拒绝服务。解决办法是/new开一个新会话或者用compact命令压缩历史。排查思路推荐顺序先看 opencode 自己的日志再 curl 测 API最后看是不是网络代理或防火墙问题。在终端里执行opencode --log-level DEBUG它会把请求细节打出来你会看到具体是哪一步报错、HTTP 状态码是多少比瞎猜高效得多。4.3 免费模型的接入和下线的坑热词里有 “opencode 免费模型” 和 “opencode hy3-free 下线了吗” 这两条我重点说一下。很多人刚接触 opencode不想马上花钱充 Claude 或者 GPT 的 API就想找免费模型先用起来。这是可行的但要擦亮眼睛。目前我用过的免费方案大概三类本地模型Ollama最稳的免费方案。装好 Ollama 后拉一个 Qwen2.5-Coder 或 DeepSeek-Coder 的本地模型然后 opencode 配置里加{ provider: { ollama: { options: { base_url: http://localhost:11434 } } } }模型名写成ollama/qwen2.5-coder:14b这样。本地模型的缺点是能力上限和云端模型差距明显但它免费、离线可用、不泄露代码适合一些敏感项目。厂商限时免费额度有些云厂商会给新用户送试用额度或者提供永久免费的低配模型。这类渠道通常要求你在 opencode 里配置自定义 provider 和 base_url能跑通但响应速度和稳定性就看厂商脸色了。第三方聚合渠道网上很多第三方中转 API 提供所谓的免费模型比如热词里那个 hy3-free 就是某平台提供的免费 Claude 模型。这种做法我不太推荐——免费渠道往往不稳定今天能用明天就下线而且密钥托管在第三方有安全隐患。如果你真的想长期用 opencode 干活我的建议是把免费方案当成“体验入口”真正产生生产力之后直接升级到官方 API。为了省一点小钱把项目里真实代码发送给不靠谱的第三方风险完全不成比例。4.4 配置不生效、插件连不上等杂项排查还有几个小问题我整理成速查表都是我被问过多次的现象可能原因建议操作改了 opencode.json 不生效改完没重启会话开一个新会话或重启 opencodeVSCode 插件连不上插件版本和 opencode 版本差距太大两边都升级到最新版/models列表是空的没有配任何 provider 的 key先设置环境变量并确认 json 语法Agent 操作到一半卡住上游 API 超时或网络抖动按Esc打断用/retry重试最后一步修改文件后没保存某些编辑器插件没监听文件变化在编辑器里手动 reload 一次这些问题的共同点就是凡是改动配置后发现问题先别急着怀疑 opencode 有 bug先确认会话是不是新的、日志里有没有报错、Key 是不是真的有效。终端 Agent 的成熟度已经比较高了绝大多数问题是环境问题而不是工具本身。5. 选型对比opencode、Codex 和 Claude Code 到底选哪个5.1 横向对比与适用场景分析每个用过终端 Agent 的人都会面临一个选择opencode、Codex、Claude Code甚至还有热词里提到的 Pi一个更轻量的终端 Agent到底用哪个我三个都深度用过把感受直接留在表里维度opencodeClaude CodeCodex开源是否否模型绑定不绑定支持多模型绑定 Claude绑定 OpenAI 系Skills/自定义技能有基于 Markdown有类似功能但生态封闭较弱多配置切换支持得最好一般一般IDE 插件VSCode/IDEA 都有VSCode/JetBrains 也有主推 VSCode上手难度配置略复杂开箱即用开箱即用适合什么用户愿意折腾、想掌控工具链的人Claude 重度用户、追求省心OpenAI 生态用户、VSCode 用户这张表其实说明了一个趋势Claude Code 是 Anthropic 为了卖 Claude 模型设计的Codex 是为了卖 OpenAI 的模型设计的它们都在“模型”上设置了墙。opencode 则像是一个“协议层”把不同模型统一成一个 Agent 操作界面。我给周围人的选型建议是三条如果你只用 Claude 且不想折腾直接 Claude Code体验最顺。如果你在 VSCode 里深度依赖 Copilot、已经用惯了 Codex选 Codex 可以少学一套工具。如果你会同时在多个模型间切换、对定制化有需求、希望工具本地化并且可控选 opencode。5.2 我的个人使用组合与最终建议现在我的日常开发组合是“opencode VSCode 插件 Ollama 本地模型”。听起来有点折腾但用惯之后很舒服日常写代码在编辑器里选中代码丢给 opencode 改复杂的重构任务直接放终端里跑 Agent遇到需要离线处理的场景就切到本地模型。它最大的价值是“工具链自由”——不会被任何一家模型厂商锁死API 价格波动了、模型效果变差了我随时能换。如果你正在从零开始接触 opencode我的最终建议是第一周先只用默认配置跑通终端里的 Agent 循环不要碰 Skills 和 Memory第二周开始把项目中反复做的流程写成 Skill等用顺手了再折腾 ccswitch、Superpowers 这些扩展。一口气上全配置只会让你分不清是哪一环出了问题。写在最后的几个小经验我的体会是opencode 这类终端 Agent 会把“程序员的工作方式”从“写代码”往“指挥代码”方向推。你不需要事无巨细地告诉它每一行怎么写而是要能清晰地定义任务边界、验收标准和约束条件。它做得好的地方是把这些“约束”的工具化做到了位——Skills 和 Memory 就是干这个的。最后再分享一个小技巧如果你发现某个任务让 Agent 做一遍之后效果很好别急着关会话直接把它刚才用的思考过程存成一个 Skill 文件。这样下次再遇到类似任务按一下skill名称就能复现同样高质量的过程。测试下来这比每次从头写 prompt 稳定得多也是 opencode 比普通聊天式 AI 工具更值得长期投入的原因。
