最近几个月我基本把终端编程从“自己敲代码”切换到了“指挥 agent 干活”opencode 是我用得最多的一个。如果你也试过 Claude Code、Codex但觉得模型绑定太死、配置不够透明、想接更便宜的模型那 opencode 值得花一晚上折腾一下。这篇文章我就从实际使用的角度把安装、配置、模型接入、项目实操、常见坑全部过一遍全程基于我自己跑过的环境不写空话。1. opencode 到底是什么它解决了什么问题1.1 从“补全代码”到“替你写代码”的转变以前用 GitHub Copilot 这类工具体验是“我在写代码AI 在旁边提示”。它只能在光标附近给出补全遇到跨文件的改动、需要理解整个模块调用链的需求基本帮不上忙。opencode 的逻辑完全不同。它是一个跑在终端里的 AI 编程代理你可以直接对它说“帮我看看这个仓库的结构”“给某个接口补上参数校验”“把测试跑一下失败的话修掉”。它会自己读文件、改文件、执行命令、再根据报错继续调整直到完成你交代的任务。本质上它不再是一个补全工具而是一个能接管任务、独立推进的协作者。在实际使用中我发现它最适合三类场景接手维护一个不熟悉的老项目、做跨文件的重构、还有处理那些“逻辑不复杂但很琐碎”的机械改动。只要你愿意把需求描述清楚它比我见过的大多数终端 agent 更接近“一个真正在干活的人”。1.2 opencode 的身世它不是某家大厂的产品很多刚接触的人会问“opencode 是哪家公司的”。我第一次看到这个项目时也查过。opencode 并不是大厂商业产品它是由开源社区维护的项目主仓库在 GitHub 上核心维护团队来自做 Serverless 工具 SST 的那批人。所以它的基因里有很明显的“开发者工具”气质配置开放、支持多模型、默认命令可控、重终端体验。这也是它和 Claude Code 的一个关键区别。Claude Code 虽然体验很好但整体围绕 Anthropic 的模型生态来设计opencode 一开始就把模型层做了抽象官方支持的模型提供方覆盖了 OpenAI、Anthropic、Google Gemini、DeepSeek、智谱、阿里、本地 Ollama 等一大堆。你可以只用官方模型也可以自己配一个很便宜的模型当主力。到了 opencode 2.0项目还做了一次大的重写从原来的架构换成了 Go 实现。这就是为什么你会看到“opencode go”这种说法以及网上不少旧教程突然不好使了。Go 版带来的好处也很直接单文件二进制、启动速度更快、安装依赖更少在服务器或者老机器上跑起来体验好了很多。1.3 与 Claude Code、Codex 这些终端 agent 的对比热词里有个“opencode codex pi 哪个 agent 好用”我把自己实际对比的结果整理一下。这里说的 Codex 是 OpenAI 的命令行 agent而 Claude Code 是 Anthropic 的官方终端工具。它们仨包括类似 pi 的同类工具本质都是“对话式终端 AI 编程代理”但差异主要在几个维度对比项opencodeClaude CodeOpenAI Codex开源情况开源可自建二次开发不开源不开源模型生态多模型可自由切换以 Anthropic 模型为主以 OpenAI 模型为主配置灵活度高JSON 文件全局可控中等依赖官方配置中等团队协作功能有 project、profile 等能力有但偏商业化一般成本控制支持免费模型和低价模型订阅或按量订阅或按量适合人群喜欢折腾配置、有多模型需求追求开箱即用的体验深度使用 OpenAI 生态我自己现在的选择是主力日常开发用 opencode因为我能把不同项目的模型路由、权限策略、记忆文件都分开管理Claude Code 在某些复杂推理场景下确实更“聪明”但我不太想被绑定在一个模型上。至于“哪个好用”我的答案是不存在绝对的好用只有“是否匹配你的模型预算和团队协作方式”。2. 安装与首次启动把 opencode 跑起来2.1 安装方式怎么选opencode 的安装方式很常规但版本不一样入口稍有区别。我建议优先用这两个之一# 方式一npm 全局安装 npm install -g opencode-ai # 方式二Homebrew 安装 brew install sst/tap/opencode如果你已经在用 Go 工具链也可以直接go install github.com/sst/opencodelatestnpm 版的好处是升级方便几条命令就能更新brew 版适合 macOS 用户统一管理Go 安装版适合你本来就在维护 Go 环境的人。还有第三种方式是直接下载官方编译好的二进制放进 PATH 里。对于 Windows 用户我遇到过 npm 全局安装后命令没有被识别的情况后面在问题排查部分细说。装完之后任何时候都可以用opencode --version自查。注意如果你看到的提示是“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”大概率不是软件本身的问题更多是 PATH 没有把 npm 全局目录加进去。2.2 启动前的模型准备opencode 默认不会有免费可用的模型它需要你配置至少一个模型提供方的 API Key。这一步卡住了很多人因为一上来就要面对各种供应商术语。其实逻辑很简单opencode 本身只是个壳真正干活的是底层的模型。我第一次启动时用的是 Anthropic 的 API配置方式是在终端里设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxx如果想用 OpenAI 官方模型设OPENAI_API_KEY就行。如果用的是 DeepSeek、智谱这类兼容 OpenAI 接口的国内服务可以在 opencode 配置里单独定义 provider设置baseURL和apiKey后面讲配置文件时会给出完整示例。在正式跑项目前我建议先在opencode的 TUI 里随便问一句“你好帮我确认一下当前目录是什么”如果它能正常回复说明模型链路已经通了。这一步排查成本最低。2.3 第一条命令与常见启动报错进入项目目录后直接运行cd /path/to/your/project opencode回车后会进入一个类似聊天终端的界面底部是输入框上方是对话历史。opencode 启动时会自动读取当前项目的文件结构并加载可能的配置。首次启动它不会主动改文件只有你提出明确任务后才会进入执行流程。如果你启动时收到了类似error: unexpected server error. check server logs这样的报错不要慌。这个错误表面上像是 opencode 服务端挂了但绝大多数时候是模型 API 请求失败导致的。常见原因有三个API Key 填错、模型名写错、所选模型的供应商服务暂时不可用。处理方式也很粗暴换一个已知好用的模型名或者换一个 Key 再试。还有一种情况是模型供应商对并发、上下文长度做了限制导致 agent 跑了一段时间后突然报错。这种时候需要改配置文件把模型的上下文窗口参数调小或者干脆换成更稳的模型。这部分在配置章节里展开。3. 配置与模型接入省钱又好用的关键3.1 opencode.json 的核心结构opencode 的全局配置在用户目录下macOS/Linux 是~/.config/opencode/opencode.jsonWindows 是%USERPROFILE%\.config\opencode\opencode.json。如果是团队项目你也可以放一个.opencode/opencode.json在仓库根目录项目级配置会覆盖全局配置。一个最基础的配置文件长这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4, provider: { deepseek: { npm: ai-sdk/deepseek, name: DeepSeek, options: { baseURL: https://api.deepseek.com, apiKey: {env:DEEPSEEK_API_KEY} }, models: { deepseek-chat: { name: DeepSeek V3 } } } } }解释几个关键字段model全局默认模型格式通常是供应商/模型名。provider定义自定义模型供应商baseURL是接口地址apiKey可以从环境变量读取。permission控制 agent 可以执行哪些命令。我会把bash权限默认设为ask避免它不打招呼直接跑删除类命令。include/exclude指定哪些文件可以被 agent 读取或修改。很多新手把配置写错是因为记错了 JSON 结构少一个括号就导致整个配置失效。我自己的习惯是写完配置后先保存再用opencode启动如果配置有问题它会在启动阶段给出比较明确的提示。3.2 怎么接入免费和低价模型热词里反复出现的“opencode 免费模型”其实是很多人入坑的直接原因。便宜确实是它很大的优势但免费模型也有不少坑。我实际用过的免费/低价方案大概有这几种Google Gemini 的免费层适合日常小任务速度快但免费额度有限且政策会调整不适合作为生产环境的唯一依赖。DeepSeek按量计费价格非常低代码能力在同价位里很能打我很多时候把它当作默认模型。智谱 GLM、阿里 Qwen国内几家模型的 OpenAI 兼容接口做得挺完善直接填 baseURL 就能用。本地 Ollama完全免费但需要机器带得动模型。我拿它跑一些测试项目体验上是“能跑但聪明程度和云端模型有明显差距”。之前社区里流传过一些“免费中转模型渠道”比如热词里的hy3-free。这类东西本质上是有人用聚合 API 或免费额度搭建的中转服务质量完全取决于维护者的心情。我见过它跑得好好的第二天突然返回 401、429然后社区里到处在问“hy3-free 下线了吗”。所以我的建议是免费渠道可以拿来学习和体验但正经项目一定要配置至少一个按量付费、有 SLA 的备用模型不要把命根子系在别人的免费流量上。配置免费模型没有捷径就是按照官方文档把 provider 写清楚。这里有一个容易踩的细节如果供应商的接口不是 OpenAI 兼容格式可能需要在provider里额外指定npm包比如ai-sdk/deepseek、ai-sdk/azure-openaiopencode 底层通过 Vercel AI SDK 适配各家接口。3.3 用 ccswitch 管理多套供应商既然模型可以随便换问题就变成“今天用 A 模型跑这个项目明天切到 B 模型跑另一个项目”总不能每次手改 JSON。这里就轮到 ccswitch 出场。ccswitch 是一个专门管理 Claude Code、opencode 等 Cline/Claude 系工具供应商配置的命令行小工具。它的工作方式很简单把自己预设的多套供应商配置写入对应工具的配置文件然后通过交互式选择一键切换。我常用的几个命令大致是这样# 初始化配置 ccswitch init # 交互式选择要用的配置 ccswitch select # 切换到某个配置 ccswitch use deepseek用 ccswitch 的好处不只是省得手改 JSON更关键的是它能统一管理多个工具的配置形态。比如我同时用 Claude Code 和 opencode 时只要在 ccswitch 里维护一份偏好切换工具时模型体系是一致的。但也有一个坑需要提醒ccswitch 切换的是全局配置文件。如果你在项目里放了.opencode/opencode.json项目级配置的优先级更高会导致 ccswitch 切了“好像没生效”。遇到这种情况先检查项目里是不是有局部配置覆盖再检查全局配置文件是否真的被改写成功。3.4 通过 skills 扩展 agent 能力热词里还有“opencode skills”“opencode 安装 superpowers”“oh-my-claudecode”这些都指向同一个方向给 agent 装“技能包”。我最早在 Claude Code 里接触了 superpowers它本质上是一套预置的 skill 集合每个 skill 包含一个 SKILL.md用来教会 agent 在特定场景下怎么做。比如“写测试之前先列出可测点”“重构前生成影响面分析”这类行为规范。后来 oh-my-claudecode 这类工具把 skill 的安装管理做成了类似 oh-my-zsh 的插件体系openccode 也支持读取这些 skill 文件。在 opencode 里使用 skill 的方法不复杂。以项目级 skill 为例在项目根目录建一个skills/xxx/SKILL.md里面用 Markdown 描述技能的触发条件、步骤和禁止事项然后在对话里告诉 agent“请你先加载 xxx 技能再开始”。opencode 会根据 SKILL.md 的内容调整自己的行为。我实际用过的一个场景是前端 E2E 测试。我给项目装了一个“playwright 测试技能”里面写清楚了如何启动测试服务器、如何调用 Playwright、如何把失败页面截图反馈给模型。这样当我对 opencode 说“帮我看看这个登录页面的 bug”时它不再只是盲猜而是按照技能里的步骤先写测试用例、再跑测试、再根据失败结果修复代码。整个过程更接近一个真正的前端工程师的工作流。4. 实操全流程接一个真实项目需求4.1 让 agent 先读项目而不是急着改拿到一个不熟悉的项目时很多人上来就对一个 agent 说“帮我改 xxx”结果 agent 对项目根本不了解一顿乱改。我在实际用 opencode 接手项目时第一件事永远是让它先做项目调研。比如我会输入这样一段话这是公司一个遗留的订单管理系统我先不让你改代码。请你先阅读 README、package.json、目录结构以及核心模块的入口文件然后给我一份项目结构说明标注清楚入口在哪、路由怎么组织的、数据层用什么、最容易出问题的地方在哪。opencode 会逐文件读取然后输出一份结构化的理解。这个过程看着很基础但价值非常大。它能让 agent 在下一次对话前就把相关上下文加载进自己的“工作记忆”减少后续命令里的反复猜测。如果项目里有明显的技术栈信息它也更容易推断出应该用哪套命令来跑测试、哪套配置来构建。在这个阶段我会顺手检查一下 opencode 读文件的效率。如果它读文件非常慢或者经常跳过某些目录我一般会在配置里用exclude排除node_modules、dist、.git这些无关目录让它的扫描更快更聚焦。4.2 提需求、看它干活、review diff项目调研完成后就可以开始提具体需求了。我以一个真实例子来说明订单管理的列表接口需要新增一个按时间范围筛选的搜索条件。我输入的指令大概是现在订单列表接口只支持分页我需要加一个时间段筛选参数。请先找到订单查询相关的 Service 和 Controller 文件然后把查询条件、DTO、SQL 映射全部改完最后跑一遍现有的单元测试确认没有破坏其他功能。opencode 会自动开始执行过程会分成多个步骤每一步都会告诉你它准备做什么。它在执行修改前会生成 diff经过确认才会写入文件。我在实际操作中习惯把权限设置成“写文件前询问”这样每一步我都能看到它要动哪里避免它误改不该动的代码。完成之后我会重点 review 三块第一它有没有按照项目现有的代码风格写第二它改的 DTO 和表结构字段是否匹配第三单元测试是否真的覆盖了新需求而不是被它用跳过的方式糊弄过去。很多人以为有了 agent 就可以不 review这是最大的误区。opencode 是一个非常高效的写代码实习生但它的判断很大程度上依赖 prompt 质量和项目里的上下文。只要能明确约束它的产出质量可以很高一旦需求表达含糊它也会很自信地把错误方案写进项目里。4.3 用 Playwright 修前端 Bug 的实战前端 bug 是终端 agent 的弱项因为它看不到页面渲染效果。opencode 的解法是让 agent 借助 Playwright 这类工具把“看页面”转化为“跑测试脚本 看截图/控制台日志”。我的实际做法分四步先让 agent 阅读页面组件和路由定位它认为最可能导致 bug 的代码。让它用 Playwright 写一个最小复现脚本启动本地开发服务器然后跑测试。如果测试失败把失败信息反馈给 agent同时让它截图保存再根据截图内容和报错栈去改代码。改完后再跑一遍测试直到通过。这一步的难点在于环境准备。如果项目里没有安装 Playwright需要先装依赖并且要给 agent 明确的启动命令npm install -D playwright/test npx playwright install chromiumopencode 在拿到测试失败结果后会自己迭代。我曾经遇到一个表格组件在某些数据下排序错乱的问题agent 写了三轮测试才定位到是数据源里某个字段类型不统一导致的。整个过程如果让我手动来至少得大半天用 agent 配合 Playwright一小时之内就搞定了。不过要注意Playwright 测试对 CI 环境要求比较高首次运行下载浏览器内核可能很慢。如果是老项目还要确认 Node 版本兼容性否则测试脚本本身可能跑不起来。4.4 用 memory 沉淀项目约定终端 agent 一个天然问题是“没有记忆”。每次新开会话它都像第一天入职的新人忘记你之前交代过的东西。opencode 的解决方式是 memory 机制。在会话里输入/memory可以查看当前项目的记忆内容。我通常会让 agent 把下面这些信息写入记忆项目的技术栈和包管理方式代码风格约定比如“DTO 字段用下划线命名”“接口返回统一使用 Result 包裹”常用命令比如“测试用 pnpm test:unit”“构建前必须执行 lint”代理任务时最容易踩的坑比如“不要修改src/generated目录下的文件”这样即使开了一个新的会话agent 也会在加载项目上下文时读取这些记忆省掉每次重复交代的麻烦。而且这些 memory 文件本身也是 Markdown团队成员可以放进 Git 仓库里共享。我觉得这是 opencode 对比很多闭源 agent 的优势之一记忆不是黑盒而是可以被人直接查看、修改、提交到仓库的普通文件整个团队都能维护。对于稍微大一点的项目这套机制对生产效率的提升非常明显。5. 桌面端、VS Code 与 IDEA 扩展5.1 opencode desktop不想用终端的另一种选择热词里出现了“opencode 桌面版”。如果你平时不太习惯纯终端界面或者更喜欢鼠标点击的交互可以试试桌面版。桌面版本质上是把终端会话搬进了 GUI 窗口左侧往往有会话历史、文件变更列表和配置入口。它和 CLI 版共享同一套配置所以你在 CLI 里配好的模型、skills、memory在桌面版里可以直接用不需要重新配置。我的使用体验是桌面版适合在看代码和聊天窗口之间频繁切换的人。它能把 diff 展示得更直观某些操作比如接受/拒绝修改用鼠标点起来更顺手。不过如果你已经习惯了终端快捷键桌面版反而会觉得有点重。对我来说它更多是“给团队里不熟终端的同事准备的入口”自己平时还是主要在终端里用。5.2 VS Code 插件怎么用在 VS Code 的扩展市场搜索“opencode”安装官方插件后侧边栏会多出一个 opencode 面板。它的作用和桌面版有重叠但更深一层地接入了编辑器。我最看重的是两点第一agent 修改文件时插件会在编辑器里高亮显示 diff你可以直接在编辑器里决定 accept 还是 reject第二选中代码片段后可以直接在面板里问 agent“这段逻辑有没有问题”“给我加点注释”不用复制粘贴。实际开发中我的习惯是在 VS Code 里开 opencode 面板处理小范围改动在终端里开 opencode 处理跨文件的大任务。两者之间通过同一个配置文件无缝切换互相不冲突。安装插件后如果发现面板连接不上 CLI通常是因为插件版本和 CLI 版本不匹配。优先把两边都升级到最新版再试。5.3 JetBrains IDEA 插件与 Maven 项目配置Java 后端项目的场景里很多人会关心“opencode jetbrains idea 插件”。JetBrains 系插件IDEA、WebStorm、PyCharm同样支持在编辑器里接入 opencode。在 Settings - Plugins - Marketplace 里搜“opencode”安装即可。对于 Maven 项目配置上会有一个额外的关注点。opencode 要执行mvn test或者mvn compile需要能够找到 JAVA_HOME 和 Maven 的环境变量。如果你的终端里可以直接跑 mvn那问题不大但如果是在 IDEA 内置的终端里使用要确认 IDEA 设置了正确的 JDK 路径。热词里的“opencode mvn 配置”我理解就是两件事一是在权限配置里允许 agent 执行 mvn 相关命令二是把permission里的bash规则设置好避免它每次跑 mvn 前都弹窗问你要权限。比如你可以在项目级配置里加上{ permission: { bash: { pattern: mvn * } } }这样 agent 执行以 mvn 开头的命令时就不需要逐次确认整体流程会顺很多。注意这种宽松权限只建议在可信项目里开启如果你打开的是别人给的代码建议还是保持默认的询问模式。6. 常见问题与排查实录6.1 命令找不到、服务报错这类基础坑我在开头提到了两个高频报错这里集中梳理一下排查思路。第一个是 Windows 下常见的opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因基本是 npm 全局 bin 目录没有加入 PATH。排查步骤npm config get prefix把输出目录下的node_modules/.bin或者 npm 全局目录加入系统 PATH然后重开终端。如果是用 Go install 装的检查$(go env GOPATH)/bin是否在 PATH 里。第二个是启动时或运行中出现的error: unexpected server error. check server logs这个错误很唬人但本质就是模型请求失败。先用最笨的办法排查换个已知可用的 Key或者把模型名改成简单的anthropic/claude-sonnet-4、openai/gpt-4o这类常见模型。如果换了之后正常说明问题出在原配置的模型名或供应商选项上。6.2 配置了却不生效的问题很多人会遇到“我在 opencode.json 里改了模型但 agent 还是用旧模型”。排查顺序是确认配置文件路径是否正确尤其不要和项目级配置混淆。确认 JSON 格式正确字段名大小写是否有误。确认模型名是否在对应 provider 的 models 列表里。如果用了 ccswitch确认它有没有把配置改回你想要的供应商。还有一个容易被忽略的点opencode 启动时会读取配置运行中改了配置不会热生效。改完配置后要重新启动 opencode 再验证。6.3 免费渠道下线与稳定性问题前面提到hy3-free这类免费渠道社区里经常有人问“下线了吗”。这类渠道的生命周期通常很短。假如你真的在用免费渠道跑项目我建议至少做两件事一是把配置拆成多个 provider一个挂了立刻切另一个二是不要保存敏感的业务数据到免费渠道因为你根本不知道数据会被送到哪里。如果只是个人学习免费渠道够用如果涉及公司项目还是老老实实选一个有合同和 SLA 的供应商。这个钱省不得。6.4 几个能提升体验的小技巧最后分享几个我实际用下来觉得提升很大的小技巧。第一给不同项目建不同的 startup 提示词。比如前端项目可以预先要求 agent“先读package.json和README再判断技术栈”后端 Java 项目则可以要求它优先查看pom.xml和现有的分层结构。第二在 TUI 里多利用斜杠命令。常见的有/memory管理记忆、/init让 agent 根据项目生成初始配置、/undo回退上一轮操作。尤其是undo当 agent 改错文件时它比 Git 回滚更精准、更快。第三把 review 视为项目的配置文件。opencode 允许你自定义 review 的类型和范围比如强制要求 agent 在完成改动后跑一遍git diff并列出所有变更文件。把这些规则持久化到项目配置里团队里任何人都能用上同一套标准。我在实际使用中最大的体会是这类 agent 工具厉害归厉害但真正决定产出质量的是你给它划定的边界。别指望一句话就把整个项目交付给它更别跳过后面的 code review。把它当成一个速度快、不知疲倦、但需要你持续盯着的资深实习生来用它的产出会超出预期。最后再补一句如果你手里的项目环境比较特殊比如网络受限、依赖历史包袱重建议先用一个小模块跑通完整流程再逐步放开范围这样哪怕踩坑代价也可控。
