10 月 12 日，开源终端编码 Agent OpenCode 发布了 2.0，按官方说法这是一次”从架构层面重写”的版本：终端、网页、桌面端共享同一个常驻后台服务，MCP 工具改成用一个内嵌 JavaScript 解释器以写代码的方式批量调用，子代理可以丢到后台跑。发布当天它在 Hacker News 拿了 800 多分、340 多条评论，是那一周讨论度最高的开发者工具。
我之前在cc-switch 管理 Claude Code 多套配置的实测里提过，编码 Agent 换模型、切配置一直是个琐碎活。OpenCode 2.0 的思路不一样——它把 Agent 从”一个终端窗口里的进程”变成了”机器上的一个服务”，这个变化比功能列表本身更值得聊。这篇是我拿到手第一晚的实测记录：装的过程就有一个坑，跑通第一个任务用了 7 秒，还有两处 API 层面的反直觉设计。
先说升级：官方安装脚本装的不是 2.0
第一个坑就出在安装上。我按习惯用了官网首页的安装脚本：
curl -fsSL https://opencode.ai/install | bash装完一查版本，opencode --version 输出的是 1.19.4——脚本默认装的是 1.x 稳定线。要上 2.0 得再执行一次大版本升级（或者直接用官方文档里的 v2 专用安装脚本）：
opencode upgrade --major升级过程有图形化进度提示，结束后再查版本是 v2.1.4。整个过程不到两分钟，没有交互式提问。如果你机器上有 1.x 且是包管理器装的（brew、npm），官方迁移指南建议先卸掉再装——两个版本共用 opencode 这个命令名，不并存。
升级前还有三件事值得检查，都是文档里明说的破坏性变更：1.x 的插件全部不兼容，需要按新插件 API 重写；Server API 完全重做，依赖旧 API 的脚本和编辑器扩展会挂；TUI 配置从 tui.json 改成了 ~/.config/opencode/cli.json。另外 2.0 只发现 AGENTS.md，项目指引写在 CLAUDE.md 里的要手动挪。我在本机看到 2.0 启动后把 9 月份 1.x 时代的旧会话也读进了共享数据库——迁移是无感的，但这也意味着你的历史会话数据换了归属地。
装完第一件事：它是一个服务，不是一条命令
2.0 的核心架构变化在这：默认情况下 OpenCode 会在你的用户账户下起一个后台服务，终端 UI、Web 界面、桌面应用全是它的客户端。你可以手动管理这个服务：
opencode service start # 启动后台服务，输出类似 http://127.0.0.1:49374
opencode service status # 查看状态或当前服务地址我在 M4 MacBook 上实测，service start 直接打印出本机地址 http://127.0.0.1:49374，之后 status 一直显示这个常驻端口。官方文档说同一个服务会被所有客户端自动发现，不开新窗口、不重复加载模型和插件。如果不想要这个常驻进程，opencode --standalone 可以退回 1.x 式的私有进程模式。
这个设计的实际意义：终端崩了会话还在；三个仓库开三个窗口，共享同一份配置和插件；脚本和定时任务可以经 opencode api 直接驱动正在跑的 Agent。从”聊天窗口”变成”可以被编程调用的本地服务”，这是它和 Claude Code 自定义 mods 那类纯配置层玩法最本质的区别。
跑通第一个任务：免登录、免费模型、7 秒修完一个 bug
我没有给 OpenCode 配任何付费 API key，直接用它自带的免费模型档（opencode/ 这个 provider 下有一批 -free 后缀的模型，包括 GLM、DeepSeek、Nemotron 等开源系的免费版本）。用 opencode models 可以列出全部可用模型。
测试任务是经典的”改 bug”：建了个目录，里面放一个故意写错的 calc.py——add(a, b) 返回的是 a - b。然后无头执行：
opencode run -m opencode/glm-5.3-flash-free \
"修复 calc.py 中 add 函数的 bug，让它返回 a+b"实测结果：7.3 秒完成，Agent 自己读了文件、做了编辑、diff 输出干净利落，最终回答一句话确认修改。任务结束后用 opencode api GET /api/session 回查这个会话的统计：输入 16755 tokens（其中缓存读取 16576）、输出 133 tokens、费用 0。全程没有登录、没有填 key。
> build · glm-5.3-flash-free
→ Read calc.py
> build · glm-5.3-flash-free
← Edit calc.py
@@ -1,2 +1,2 @@ def add(a, b):
- return a - b
+ return a + b
已修复 calc.py 中 add 函数的 bug，将 return a - b 改为 return a + b。免费档的能力边界也很清楚：这个级别的”单文件小修”完全没问题，但多文件重构、跨模块追踪这类任务，免费小模型的推理深度会不够——真拿它干活建议还是配一个付费主力模型，免费档当快速试手和低风险小任务的通道。
API 探坑：错误路径不报 404，而是返回网页
第二个坑是我拿 opencode api 子命令试 API 时踩到的。这个子命令可以直接向常驻服务发请求，但我先猜了个路径：
opencode api GET /session返回的不是 JSON，也不是 404，而是一整页 OpenCode Web 界面的 HTML——服务把没匹配上的路径全都兜底到了网页应用上。用 curl 写自动化脚本的人很容易在这里被”返回 200 但内容是 HTML”骗到。
正确的 API 前缀是 /api：
opencode api GET /api/session这才返回 JSON：会话 ID、所用模型、token 统计、费用、工作目录，字段齐全。顺带一提，列表里能看到共享服务确实把我 9 月份用 1.x 跑的旧会话（另一个项目里的）也一起列了出来——”一个服务管所有历史”不是宣传语，是真实行为。
第三个值得知道的点：官方称 Code Mode 默认对所有 MCP 服务器开启，Agent 会写一段 JavaScript 一次性串联多个工具调用，而不是逐轮往返。这类特性官方博客自己的说法是”应该被测试而不是照单全收”——我没有在本次实测中跑通 MCP 链路，这里只能算转述，等你实际验证。同样未实测的还有后台子代理、/pair 远程配对和 @opencode/sdk 嵌入，等我有真实场景再补。
不建议用的场景
结合这次的体验说两句丑话。第一，如果你重度依赖 1.x 的自定义插件或针对旧 Server API 写过集成脚本，2.0 的破坏性变更意味着迁移成本是实打实的，别在 deadline 前一周升级。第二，Code Mode 的解释器虽然是宿主沙箱（脚本不能直接碰网络和文件系统），但工具本身拿着你机器的完整权限——把不认识的第三方 MCP 服务器一股脑接进来，风险等同于给陌生代码开白名单，这一点任何编码 Agent 都一样。第三，免费模型档适合试手，别指望它承担严肃的工程任务。
总结
OpenCode 2.0 把开源编码 Agent 推到了一个新形态：常驻服务、可编程 API、按需付费或干脆免费开跑。实测路径很短——两分钟安装升级，一条命令起服务，免费模型 7 秒修完第一个 bug，成本为零。如果你正在给编码 Agent 做上下文与 token 优化，或者像我在 graft-trail 那篇里一样想省点 token，OpenCode 2.0 的共享服务 + Code Mode 组合值得花一个晚上试。官方文档和迁移指南在 opencode.ai/docs，发布详情可以看官方发布公告。
未实测，需人工确认的部分：Code Mode 对自定义 MCP 服务器的实际行为、后台子代理的稳定性、/pair 远程访问的安全边界（官方明确说配对链接”不是认证”，链接泄露即暴露服务）。这些我会在后续真实使用中验证后更新。