写 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 装配行业规范和团队约定。 - Memory：opencode 会维护跨会话的项目记忆和用户全局记忆。一个项目里你告诉过它“这里用的是标准库的 log，不要引入 zap”，下次再开这个项目的时候它仍然记得。这解决了很多终端 Agent “每次会话都失忆”的痛点。
这四个模块加在一起，opencode 就不再是一个“聊天框”，而是一个可以复用的开发流程执行器。我的理解是，Agent 循环负责“干活”，Skills 负责“定义怎么干活”，Memory 负责“记住活是怎么干的”，多模型负责“换不同人来干”。后面我具体展开每一步怎么配置和使用。
2. 安装与配置：从零到能跑第一个任务
2.1 安装方式的对比与选择
opencode 目前提供了几种安装途径，我挨个试过，给你一个明确的优先级参考。
| 安装方式 | 适用平台 | 速度 | 我推荐 |
|---|---|---|---|
| 官方 curl 脚本 | macOS/Linux | 快 | 最省事，首选 |
| Homebrew | macOS/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.json（macOS 上是~/.config/opencode/opencode.json，Windows 在%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。你在交互界面里按快捷键（默认是Ctrl+X或/models命令），就能在当前会话里上下切换不同模型，不需要改配置文件。
分环境变量是最干净的用法。比如你在公司电脑上不想把 Key 明文写进 JSON，可以直接设置环境变量：
export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." export GOOGLE_API_KEY="AIza..."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.json，ccswitch 能把不同场景的模型、Key、base_url 都整理好。它的配置思路是把 opencode 的配置模板化，然后按 profile 来覆盖。
我用下来的体验是：如果只是自己写代码，完全不需要 ccswitch，直接用环境变量和/models切换就够了。但如果你是那种“同时维护五六个项目、每个项目用不同模型渠道”的重度用户，折腾一次 ccswitch 是值得的。
3.3 Skills：给 Agent 定义“怎么干活”
Skills 是 opencode 生态里最被低估的功能。它的本质是“预置指令”，但你不用每次都在对话框里把规则重新敲一遍——只要触发对应的 Skill，Agent 就会自动加载这些规则。
先看怎么装。Skill 的本质是一个目录，里面放一个SKILL.md文件。目录路径是：
~/.config/opencode/skills/比如我建了一个review技能，用于让 opencode 做代码审查：
# Review Skill 当用户请求“review”或“审查代码”时，执行以下步骤： 1. 运行 git diff 查看本次改动的文件 2. 逐个文件审查，重点检查： - 是否有明显的空指针 / 未捕获异常 - 是否有调试用的 console.log / print 残留 - 数据库查询是否缺少索引或存在 N+1 - 错误处理是否吞掉异常 3. 输出审查意见，按“严重”“建议”“可忽略”分级 4. 不要直接改代码，除非用户明确要求把这段存成~/.config/opencode/skills/review/SKILL.md，然后在会话里输入@review，opencode 就会加载这个 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 或者 403，opencode 统一显示成 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 不生效 | 改完没重启会话 | 开一个新会话或重启 opencode |
| VSCode 插件连不上 | 插件版本和 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），到底用哪个？我三个都深度用过，把感受直接留在表里：
| 维度 | opencode | Claude Code | Codex |
|---|---|---|---|
| 开源 | 是 | 否 | 否 |
| 模型绑定 | 不绑定，支持多模型 | 绑定 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 工具更值得长期投入的原因。
