最近一直在评估哪款 AI 编程代理真正值得放进日常工作流而不是装在电脑里吃灰。我把 codex、claude code、opencode 这些终端类的 agent 工具挨个试了一遍最后稳定留下来的反而是 opencode——它没有那么多花哨包装但胜在开源、模型无关、配置完全透明而且社区给你的玩法skills、memory、接 playwright 跑前端 bug稍微一折腾就能搭起来。这篇就沿着 opencode 从安装到上手再到落地的整个链条把我实际用下来的东西完整讲一遍包括踩过的坑和最终留下来的原因。1. opencode 是什么它和 Copilot/Cursor 根本不是一类东西1.1 先说清楚它不是补全工具很多人一听到 AI 编程工具第一反应是 Copilot 或者 Cursor 那种你写着代码它给你补下一行或者开个对话框问问题。opencode 不是这个定位它属于agent 类工具你给它一个任务比如给结算页的优惠券按钮加个防重复提交逻辑它会自己搜索项目代码、定位到相关文件、改多处代码、跑测试、看报错再迭代修复最后把 diff 给你看。区别在谁主导这件事上。补全工具是人在写AI 在旁边给建议agent 工具是你把意图说清楚它替你执行整个过程你负责审核结果。opencode 就是后者而且它跑在终端里是一个基于 Go 语言实现的 TUI 工具。这里说一句为什么 Go 实现很关键opencode 的启动速度是真的快冷启动基本没有等待感资源占用也比那些套个 Electron 壳的桌面编程工具低得多。你在终端里用久了就会发现工具链的快慢其实就是使用频率的分水岭一个要等三秒才弹出的面板你很快就懒得用了。1.2 opencode 核心特性拆解我整理了一个表把 opencode 的功能维度、实际表现、以及价值点列出来这样比文字描述直观能力实际表现对我而言的核心价值多模型支持Anthropic、OpenAI、Gemini、Ollama 本地模型等都能接不被单一厂商绑死哪个模型好用用哪个Skills支持技能包机制agent 按需调用把团队约定、工作流沉淀成可复用文件Memory跨会话记住项目偏好新开一个会话不用重新解释项目背景LSP 支持能感知代码符号、引用关系改代码时上下文更准不是瞎猜字符串权限控制分 ask/allow/deny 等模式给 agent 放权时留了安全边界产品形态终端 TUI、桌面版、VSCode / JetBrains 插件按场景切换入口其中 skills 和 memory 是我后来真正用起来的两个机制后面的章节我会单独展开。LSP 支持这点平时不太被注意到但它决定了 agent 在搜索这个函数在哪些地方被调用了的时候是走语法分析去做精确查找还是只能靠文本硬搜。我实际体感是打开 LSP 之后 agent 找符号的准确率明显更高跨文件重构的时候尤其明显。1.3 什么人适合用 opencode我自己的判断是下面这几类人是 opencode 的目标用户终端重度用户你本来就生活在 shell 里多一个 TUI 工具零学习成本。不想被模型厂商绑死的人今天用 Claude、明天想试试 Gemini、后天切回本地 Ollamaopencode 切换起来很轻松不需要为每个模型装一个工具。需要本地模型或者常处理敏感代码的人代码不想出内网那就直接接 Ollama 跑本地模型。想自己折腾、改造工具的人opencode 开源遇到 bug 可以看源码想要新功能可以先去看看有没有 issue。反过来如果你只想要一个装完就能用的AI 结对编程不想碰任何配置那可能 Kits 一点的商业图形化工具更合适。opencode 终归有配置成本但好在它配置也透明实际上不算难。2. 安装和无法识别 cmdlet报错的完整排查过程opencode 的安装方式官方文档里写得很清楚但我发现新手尤其 Windows 用户基本都会卡在第一步。热搜里那句opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称基本是 PowerShell 用户绕不开的一个坎。2.1 三种常用安装方式我按个人推荐度排序说说为什么这么选官方安装脚本curl -fsSL https://opencode.ai/install | bash。这是 macOS/Linux 上最省事的方式它会自动下载对应平台的二进制放到/usr/local/bin这类目录。缺点是你要先确认系统里存在 curl并且信任脚本内容才能执行。npm 全局安装npm install -g opencode-ai。注意包名是opencode-ai而不是opencode因为 npm 上opencode这个包名早就被占了。这种方式适合本来就很熟悉 Node 生态的人但 Windows 上最容易出 PATH 问题下面展开说。Homebrewbrew install sst/tap/opencode。mac 用户如果已经有 Homebrew这是最干净的方案装完就进 PATH不需要任何额外配置。我自己在 Mac 上用的是官方脚本干净利落在 Windows 的 WSL 环境里也装过一次没出问题。但如果你直接在 Windows 的 PowerShell 里 npm 全局安装那基本都会遇到开头那句报错。2.2 PowerShell 报错无法识别 cmdlet到底什么原因这个问题本质不是 opencode 的问题而是npm 全局可执行文件目录没有加进系统 PATH。npm 全局装包的时候可执行文件会被放进 npm 的全局 prefix 目录。在 Windows 上这个目录通常是C:\Users\你的用户名\AppData\Roaming\npm但这个目录经常没有被自动加入 PATH。于是你在任意路径执行opencodePowerShell 自然告诉你它找不到这个命令。排查步骤我给你列一下跟着走就能确认问题先确认 opencode 到底装没装进去npm ls -g --depth0看输出列表里有没有opencode-ai。查 npm 全局目录npm config get prefix拿到实际路径。看这个路径里有没有 opencode.cmd 文件有的话就说明装好了只是 PATH 里没包含这个目录。打开系统环境变量编辑器在用户变量 PATH 里追加%APPDATA%\npm或刚才 prefix 命令返回的路径。关掉当前终端重新打开一个 PowerShell 窗口执行opencode --version。这里有个小坑值得提醒改完 PATH 之后必须全新开一个终端窗口直接在当前窗口里执行$env:Path刷新有时不生效很多人在这一步反复怀疑自己操作错了。理论上你可以用npx opencode-ai绕过 PATH 问题但我不推荐因为 npx 每次运行都有一层额外解析而且如果项目里嵌套了不同版本很容易调用了不想要的那个版本。既然要用终端 agent把环境一次配好是值得的。2.3 安装完成后的基础校验装好以后我建议按这个顺序做一轮基础校验opencode --version确认版本号能打出来。opencode直接进入 TUI 界面。第一次启动时它会引导你选择一个模型服务商并配置 API Key。这里先不要急随便选一个进去看看界面即可模型配置下一章详细说。TUI 里最常用的操作/models切换模型、/new开启新会话、CtrlC 取消当前执行。这些都是进入界面之后可以慢慢摸索的。我个人的小建议是第一次配的时候把权限模式设成 ask每次执行命令都询问不要图省事直接开 auto-accept。等你观察几天了解它平常都会跑哪些命令之后再按需放权。3. 模型接入、免费模型与多厂商配置管理opencode 最大的优势就是模型无关。它不像某些工具那样默认锁定一个厂商你可以自由配置 API Key 和模型列表也可以接入本地模型。这一章把常见接法和我自己的方案写透。3.1 官方模型的接入方式接入流程大概分三种第一次启动时选择TUI 启动后会弹出 provider 列表选一个进入认证流程。Anthropic、OpenAI、Google 基本上都有对应的操作路径有的支持 OAuth有的直接把 API Key 填进去就行。环境变量这也是最推荐的方式。Anthropic 读ANTHROPIC_API_KEYOpenAI 读OPENAI_API_KEYGemini 一般读GOOGLE_API_KEY。你在 shell 的配置文件里 export 之后opencode 就自动识别了。配置文件在~/.config/opencode/opencode.jsonLinux/macOS或者项目目录下的opencode.json里显式配置。我推荐环境变量的原因很简单它不污染配置文件而且你想换 key 的时候只需要改 shell 配置不影响 opencode 本体。当然用配置文件的场景也有比如固定某个项目必须用某一套模型参数那项目级配置文件更合适。3.2 配置文件的常用字段和示例opencode 的配置文件是 JSON 格式支持 JSON Schema官方提供了 schema 地址编辑器里写的时候会自动补全。我自己的一个精简配置长这样{ $schema: https://opencode.ai/config.json, provider: { ollama: { models: { qwen3:8b: {} } } }, model: qwen3:8b, permission: { edit: allow, bash: ask } }简单解释一下每个字段的作用$schema让编辑器认识配置格式写错字段会直接标红强烈建议写上。provider注册你自定义的模型提供方。上面示例是注册一个 Ollama 本地模型。model默认使用的模型名。permission权限控制。edit: allow表示允许它直接修改文件bash: ask表示执行 shell 命令前需要问我。有一点要特别说明权限配置别一上来全开。bash: ask意味着每个命令都会经过你确认虽然麻烦但是安全。等你有把握了再针对特定命令或目录放权。3.3 免费模型与本地模型方案免费模型是很多人关心的点。opencode 里想不花钱跑起来最靠谱的方案就是Ollama 本地模型。做法很直接安装 Ollama然后拉一个代码能力还过得去的模型比如ollama pull qwen3:8b或者llama3.1。在 opencode 的配置里把 Ollama 注册成 provider就是上面例子里的写法。启动 opencode 后用/models切到本地模型。实测下来本地 8B 级别的模型处理常规代码补全、写单测、解释代码片段是够的但到了跨文件重构、复杂业务 bug 定位这种需要大上下文推理的任务明显不如旗舰模型。我的用法是日常简单任务让本地模型跑遇到真正难啃的问题再切到官方大模型。这样一个月下来 API 费用能压到一个很低的水平。3.4 为什么我不再依赖第三方免费中转服务社区里曾流行过一些提供免费或低价模型中转的服务就是把各家模型的 API 聚合起来用一个普通的价格或者免费的 key 提供给用户。这类服务确实存在过也有人用得很欢。但我要提醒一句这类服务的生命周期不稳定随时可能下线。社区里已经有某个中转服务被关停导致大量使用它的人配置一夜之间全部失效。即使不谈稳定性从数据安全角度看把代码和对话全部过一遍第三方服务器风险也是实实在在的——你的业务代码被谁看过、存不存在日志里你根本无法审计。所以我最后的结论是想免费就老老实实用本地模型至少数据不出机。想效果好就花钱走官方 API流程可追溯。不要把核心工作流押在一个你控制不了的中转服务上。3.5 ccswitch 这类配置切换工具的实践思路用过 Claude Code 的人可能知道 ccswitch它就是一个快速的配置切换器帮你一键换不同的模型服务商。opencode 其实也经常被拿来配合这类工具使用因为你自己在终端里完全可以实现同样的切换逻辑不需要依赖第三方工具。我自己的做法是维护了一套环境变量脚本不同项目用不同的 API Key 和 base URL在 shell 配置里放几个函数一键切换。比如在 zsh 里oc-work() { export ANTHROPIC_API_KEY$(cat ~/.secrets/work-key) export ANTHROPIC_BASE_URLhttps://your-internal-endpoint.example.com opencode } oc-local() { unset ANTHROPIC_API_KEY opencode }这样的话上班模式和本地模式就是两条命令的事。比装独立切换工具更透明因为每一步发生了什么你自己完全清楚。这也是 opencode 这类开源工具的好处——你能用最朴素的方式控制它。4. Skills 与 Memory 机制从聊天助手到项目成员用过一段时间 opencode 之后你会发现裸工具的能力上限其实取决于你每次对话给了它多少上下文。如果你每次都从零开始讲项目背景那它每次都是从零开始理解。Skills 和 Memory 这两个机制就是来解决这个问题的。4.1 Skills 到底是干什么的Skills 可以理解成一份操作手册里面写清楚某个任务的标准做法agent 在遇到对应场景时会主动读取并照着执行。它不是一个插件式的魔术本质是Markdown 描述 一些可执行脚本的组合。举个例子。你想让 opencode 遵守团队 Git 提交规范可以写一个 commit 相关的 skill里面写明commit message 必须遵循 xx 格式超过 72 字符要换行提交前要跑 lint。之后每当你让它提交代码它就会加载这个 skill而不是凭模型自己的常识乱来。Skill 的目录结构在社区里已经形成惯例一个SKILL.md文件描述 skill 的用途、触发条件和操作步骤旁边可以放辅助脚本。opencode 会扫描这些目录让模型在合适的时候去调用。4.2 oh-my-claudecode 和 superpowers 这类 skill 包怎么用起来现在社区里已经有不少现成的 skill 集合热搜词里的oh-my-claudecode就是一个典型的 skill 包。严格来说它是为 Claude Code 做的但 skill 这种机制由于大家都在用 Markdown 脚本搬到 opencode 上的成本极低。我的操作方式是这样把 skill 包 clone 到本地。看目录结构找到放 skill 的文件夹。复制到 opencode 的全局目录~/.config/opencode/skills/或者复制到当前项目的.opencode/skills/目录。重启 opencode在对话里触发对应场景观察它是否读取到 skill。superpowers 的定位稍微不太一样它更强调做事方法比如写代码前先写测试、先拆解任务再动手、失败之后做复盘等。这类东西与其说是技能不如说是给 agent 灌入一套系统化的思维框架。在 opencode 里安装方式和普通 skill 差不多但要注意的是superpowers 类 skill 往往体积大、步骤多如果你在同一个模型上同时塞了很多 skill模型会选择困难反而降低效率。我的建议是一个项目最多放 3 到 5 个核心 skill按需启用别囤货。skill 不是越多越好关键是让模型清楚什么时候该用哪一个否则它可能会在两个 skill 之间来回犹豫陷入不必要的 prompt 开销。4.3 Memory让跨会话记忆真正落地opencode 的 memory 机制解决的是我上星期已经告诉过你项目怎么启动了你这次怎么又忘了的问题。它会把这些信息沉淀下来下次新开会话依然生效。我用 memory 主要记这几类东西项目启动命令pnpm dev、go run ./cmd/server这种。测试命令比如pnpm test -- --run以及改完必须跑测试这个约定。代码约定哪些目录不能动、项目用什么格式标准、某个历史包袱为什么留着。个人偏好比如我喜欢用单引号还是双引号、注释用中文还是英文、commit 的格式。具体操作上opencode 支持你在对话里直接提出记住……或以后……这类指令它会把这些内容写入项目级或全局的记忆文件。下次新会话开始它读一下记忆文件项目背景基本上就恢复了七七八八。我实测过一个小场景一个项目隔了两周没碰重新打开 opencode 新会话直接说按上次的约定继续改支付模块它成功调出了记忆里的测试命令和约束没有重复解释。这个体验和裸工具是真的不一样。4.4 用 Playwright 测前端 bug 的完整实战再分享一个我最近很常用的场景前端 bug 复现。以前发现页面某个按钮没反应你得自己打开浏览器、找元素、看控制台报错来回折腾。opencode 配合 Playwright可以把这个过程交给 agent 自动跑。我的做法是在对话里给它一个清晰的任务指令类似这样用 playwright 复现这个 bug 1. 启动 dev serverpnpm dev 2. 打开 http://localhost:5173/checkout 3. 点击页面上的使用优惠券按钮 4. 等网络请求结束后把 console 和 network 的报错信息保存到 /tmp/bug-reportopencode 会自己决定安装或者调用已有的 Playwright 环境写一个临时脚本执行然后把执行结果拿回来分析。我遇到过一次实际案例按钮点击后控制台报了一个Uncaught TypeError: Cannot read properties of undefined (reading promo)agent 顺着这个报错定位到接口返回的数据里缺少 promo 字段前端代码没做空值兜底。整个过程从发指令到定位根因大概十几分钟。这里有一个非常重要的实操心得给 agent 下 Playwright 任务时一定要让它把 console 输出重定向到一个文件里不要让大段日志直接刷在对话流中否则上下文很快被无关信息塞满agent 反而会迷失。我在指令最后通常会加一句将完整的页面 console 输出写入文件后总结关键报错效果立竿见影。5. 编辑器集成与桌面版终端工具的边界在哪里opencode 的本体是终端 TUI但它也提供了 VSCode 插件、JetBrains 插件和桌面版在终端力所不能及的场景里补位。这一章聊聊我实际使用的分工。5.1 VSCode 和 JetBrains 插件的定位VSCode 插件解决的问题是看 diff 和在编辑器里交互。终端里展示文件改动毕竟是逐行文本如果一次改了十几个文件在纯粹的文字界面里检查 diff 效率很低。VSCode 侧边栏里打开 opencode就能像聊 AI 一样对话同时用编辑器原生的 diff 视图检查每一处改动顺畅很多。JetBrains 系的 IDEA 插件思路类似对 Java/Kotlin 等项目比较友好。这两类插件的底层都是调本机的 opencode所以模型配置、skills、memory 都是互通的不存在装了个插件就要重新配一遍的问题。5.2 opencode desktop 桌面版桌面版是后来社区呼声很高的产品形态。它本质上是把 TUI 包装成了一个图形界面加了对话框、历史会话列表、更友好的配置入口。适合两类人一类是刚接触 opencode、不习惯终端 TUI 的新手另一类是你想给别人演示的时候图形界面比终端录屏更直观。不过就我自己的习惯而言日常开发还是终端里用得更顺手。桌面版启动要带图形环境多一层开销而且一些高级功能比如权限询问、脚本交互在终端里操作反而更直接。桌面版我更多是当作一个展示窗口真正干活的还是终端。5.3 我在实际工作流里的入口分配最后总结一下我这几个月形成的固定分工场景我用的入口原因日常对话改代码终端 TUI快、顺手、上下文连贯检查大范围 diffVSCode 插件diff 视图比文本清晰前端 bug 复现终端 TUI Playwright命令行跑脚本更灵活给同事演示、新手入门Desktop 桌面版图形界面门槛低这里还要提一个容易被忽略的问题权限模式在不同入口下的表现要提前确认清楚。终端 TUI 里的权限询问是交互式的弹出来你就知道了但 VSCode 插件里的对话可能会走异步处理权限请求需要你在插件界面里回应别让它挂着。我建议编辑器插件场景尽量把权限设成 ask 或 allow 的明确组合避免出现任务已经跑起来但一直等你批准的尴尬状态。6. 用 opencode 接手存量项目的完整流程搜索引擎里很多人搜opencode 接手开发项目这恰恰是我认为它最实用的场景之一。接手老项目的最大痛点是上下文缺失而 opencode 只要配置得当就能在很短时间里建立对项目的整体认知再带着这个认知去改代码。下面是基于我实际经验总结的四步流程。6.1 第一步先让它讲出项目故事而不是直接动手接到一个老项目我第一件事不是让它改需求而是让它介绍项目。我会在对话里这样问先不要改任何代码。请完成下面的事情 1. 阅读 README 和项目根目录的文档梳理项目的定位和模块划分。 2. 根据目录结构画出主要模块的关系。 3. 找出核心链路比如用户从发请求到落库经过哪些主要文件。 4. 列出项目启动方式、测试方式、构建方式。 5. 总结你在阅读过程中看到的明显风险点。这一步其实是在验证两件事它有没有真的把代码读进去以及它的总结能不能给你提供参考价值。如果它给出的架构摘要与自己理解的对得上那后续就能放心让它做实际改动如果对不上你也能及时纠偏避免后面基于错误理解乱改。6.2 第二步把启动命令和约束固化到 Memory 和 Skills等它把项目结构理清之后我会立刻把这些信息固化下来。比如在对话里说记住本项目通过pnpm dev启动测试命令是pnpm test -- --run不要在运行时修改db/migrations目录下的文件。之后这些约定就会进入记忆后续会话不需要重复。更进一步的话把项目常用的操作流程写成 skill比如如何新增一个接口如何跑迁移脚本。这样即使过了两个月再回到项目你只需要说按项目规范加一个新接口它就能自己读 skill、查记忆、按规范执行。对一个长期维护的老项目来说这个投资回报非常可观。6.3 第三步挑一个小任务试水验证它的真实水平固化了上下文之后先不要上大任务。我通常会挑一个改动量小、但需要它真正理解业务的小 bug 或小需求给它练手。比如订单列表页的日期格式显示不对统一改成 YYYY-MM-DD这一类。重点观察三点它改动的范围是不是精确命中有没有误伤无关文件。它有没有主动跑测试或者至少检查上下文。它的 commit 信息是否符合项目规范。如果这三样都过关我才会逐步把更大的任务交给它。如果第一轮就表现混乱那我会先回头看 memory 和 skill 写的是不是有歧义而不是硬着头皮继续让它在错误基础上叠加错误。6.4 第四步设置安全边界防呆要先行接手存量项目最怕的不是 agent 改错而是它在你不注意的时候执行了危险命令。我的安全配置经验是初期权限设 ask每条 bash 命令都经过确认避免它擅自跑数据库迁移或者 git push。明确禁止命令在配置文件里把某些高危命令直接 deny比如强制删除数据库、生产环境部署等。改完必须跑测试在 memory 里固化一条任何代码改动完成后必须运行测试相当于给它设了一个自动校验关卡。限制自动允许目录如果开放了 edit allow尽量限制到 src 等业务目录范围别让它随便动配置文件和 lock 文件。这套组合下来即使 agent 在某些环节判断失误也顶多是在可控范围内多改几行代码不至于捅出安全事故。等你对它的行为模式足够熟悉之后再逐步放宽权限这个节奏更稳妥。7. opencode 与 codex、claude code 的选型对比与我的最终组合最后聊一个所有用过 agent 工具的人都会纠结的问题几个主流的终端 agent 到底怎么选。我在这几个工具上都花过时间下面基于真实的体感做个横向对比。7.1 三个工具的横向对比对比维度opencodecodexclaude code开源开源社区活跃CLI 开源但模型强绑定 OpenAI官方工具不开源模型绑定模型无关可接多厂商和本地模型基本绑定 OpenAI 系列模型基本绑定 Anthropic 系列模型Skill 生态处于上升期社区内容正在变多相对封闭最成熟oh-my-claudecode 等大量生态都长在这里编辑器集成VSCode / JetBrains 插件 桌面版有较多官方集成官方支持较完善上手门槛需要配置模型和配置文件需要 OpenAI 账号和 API订阅 Claude 之后很顺滑自由定制空间很高配置透明、源码可看中等较低更多是官方给什么用什么7.2 我最后为什么选了 opencode三个工具我都实际用过最终把 opencode 留了下来核心原因有三个第一模型自由。我可以把 Anthropic 的模型用在复杂重构上把本地 Ollama 用在琐碎小任务上没人规定我买了一个工具就得永远绑定某个厂商。对个人开发者来说这直接意味着成本可控。第二配置透明可审计。opencode 所有行为都体现在配置文件和对话记录里它准备执行什么命令、为什么要执行你在 ask 模式下看得一清二楚。出了问题时我不需要去猜测黑盒内部发生了什么。第三开源意味着主动权。遇到官方没有的小功能我可以看源码、提 issue甚至自己改一版。这种工具可被自己掌控的感觉在商业闭源产品里是永远得不到的。当然claude code 的成熟生态和顺滑体验我也认可。如果你是 Anthropic 深度用户又不想折腾配置claude code 必然更省心。codex 则适合 OpenAI 生态的忠实用户。我不觉得有哪个工具绝对最好只有哪个更匹配自己的工作方式。7.3 我现在的固定组合说下我现在工作流里的最终组合供你参考主力是 opencode Anthropic 官方 API日常琐碎任务切到本地 Ollama 模型兜底。切换模型就用/models命令成本灵敏度和效果灵敏度可以随时调整。最后再分享一个我使用过程中沉淀下来的小习惯也算给刚上手的你一个方向接到一个新项目先花半小时把项目启动命令、测试命令和代码约定写进 memory让 agent 动手前先跑一次测试作为基线。这一步做完后面所有对话的效率都会有质的提升。这个初始投资很值得。opencode 还在快速迭代社区里新的 skills 和玩法几乎每周都有更新如果你的需求是寻找一把趁手的终端编程搭档它值得你在周末花上两小时认真折腾一次。