opencode:把编码 agent 拆成客户端与服务器两层的开源终端

一句话定位

opencode 是开源的 AI 编码 agent,仓库 anomalyco/opencode(原 sst/opencode,旧地址 301 跳到新组织, GitHub 仓库 id 975734319 未变), 210,595★ / 27,875 fork, TypeScript, MIT, 2025-04-30 建仓, 最近 push 2026-09-28, 官网 opencode.ai。官方给自己的定义只有一句: The open source AI coding agent。它有三种前端形态——终端 TUI、桌面 app、IDE 扩展——但形态不是重点, 重点是这三个前端共用同一个 HTTP server: 你敲 opencode 的时候, 它起的是一个 server 加一个 TUI 客户端, TUI 只是这个 server 的第一个消费者而已。

用户点名要收的这一条, 与本站 code 域里已有的 XiaomiMiMo/MiMo-Code 是同一个内核的两种加工: MiMo-Code 的 README 自己写明它是 OpenCode 的 fork, 保留了多 provider、TUI、LSP、MCP、插件这些内核能力, 在其上加持久记忆与自主循环。所以读 opencode 等于读开源编码 agent 这一层的参照实现——下游谁继承了什么, 都要以它为基线。

数据面

项	值
仓库 / 组织	anomalyco/opencode(原 sst/opencode)
Stars / Forks	210,595 / 27,875
语言 / 协议	TypeScript / MIT
建仓 / 最近 push	2025-04-30 / 2026-09-28
运行形态	终端 TUI、桌面 app、IDE 扩展、headless server、GitHub Action、ACP 子进程
模型供给	75+ provider(AI SDK + Models.dev)、本地模型、官方精选网关 OpenCode Zen
内置 agent	2 个 primary(Build / Plan)+ 3 个 subagent(General / Explore / Scout)+ 3 个隐藏系统 agent(compaction / title / summary)
内置 LSP	35+ language server, 按文件扩展名自动拉起
安装	curl -fsSL https://opencode.ai/install | bash、npm/bun/pnpm/yarn 全局装 opencode-ai、brew install anomalyco/tap/opencode、pacman、choco、scoop、mise

它真正押注的东西: client/server 分离, 不是 TUI 做得多好看

opencode serve 起一个 headless HTTP server, 暴露 OpenAPI 3.1 规范(默认 http://127.0.0.1:4096/doc), JS/TS SDK @opencode-ai/sdk 里的类型是从这份 spec 生成的, 不是手写的。这个决定的后果比看上去大:

• 一份 agent 内核, 五种客户端: 终端、桌面、IDE、CI 脚本、SDK 集成都打同一组端点, 没有人为每种宿主重写一遍 agent 循环。
• /tui 端点可以远程驱动 TUI: 预填 prompt、直接跑一轮。官方 IDE 插件就是这么实现的——IDE 不是另一个 agent, 它是同一个 server 的遥控器。
• server 可以被发现、被保护、被跨源访问: --mdns 打开 mDNS 服务发现(默认域名 opencode.local), OPENCODE_SERVER_PASSWORD 加 HTTP basic auth(用户名默认 opencode, 可用 OPENCODE_SERVER_USERNAME 改), --cors 可重复传多个来源。
• 事件是 SSE 流: /global/event 给全局事件流, /global/health 给健康与版本。做监控面板或多 agent 编排的人不用去解析终端输出。
• 端点面覆盖 project(列项目 / 当前项目)、path 与 vcs(当前路径、版本控制信息)、instance、session、消息与工具调用等, 是一份能直接拿去 Swagger 里读的真实契约。

本站判断: 这是 opencode 与「又一个终端聊天客户端」的分水岭。把 agent 做成有 OpenAPI 契约的服务, 意味着它的下游生态(MiMo-Code 这类 fork、IDE 插件、CI 集成)继承的是接口而不是代码——210k★ 里有相当一部分是这个决定带来的。

Agent 编排: 主 agent 分权, 子 agent 分工

opencode 把 agent 分成两类, 而且用权限系统而不是提示词来区分它们:

Agent	类型	工具面	用途
Build	primary(默认)	全部工具开启	真实开发: 读写文件、跑命令、改仓库
Plan	primary	file edits 与 bash 默认 ask	只分析与给方案, 不落任何修改。想让模型读代码、提改动建议、出计划而不动仓库时用它
General	subagent	全工具(除 todo)	研究复杂问题、执行多步任务; 官方明确说可以用它并行跑多个工作单元
Explore	subagent	只读, 不能改文件	快速按模式找文件、按关键词搜代码、回答关于代码库的问题
Scout	subagent	只读	外部文档与依赖研究: 把依赖仓库 clone 进 opencode 托管的缓存、读库源码、拿本地代码和上游实现对照, 全程不动工作区
compaction / title / summary	primary(隐藏)	系统内部	长上下文压缩成摘要、生成会话短标题、生成会话总结; 自动跑, UI 里选不到

Tab 键(或自定义 switch_agent 键位)在 primary 之间切换, @ 提及召唤 subagent。Scout 这一条值得单独记: 它把「查上游实现」这件在编码里极常见、但会污染工作区的动作, 做成了一个只读子 agent 加一份托管缓存——不是让主 agent 去 git clone 到当前目录里。

模型供给: 75+ provider, 外加一个「把供给质量当产品做」的 Zen

opencode 走 AI SDK + Models.dev, 支持 75+ 个 LLM provider, 也能跑本地模型。/connect 加的凭据落在 ~/.local/share/opencode/auth.json, provider.options.baseURL 可以改任意 provider 的端点(走代理、走公司内网关都靠这个)。/models 选模型。

OpenCode Zen 是官方自己做的 AI 网关, 完全可选(不用它 opencode 一样能跑)。它的立论很实在: 市面上模型很多, 但真正适合当编码 agent 的没几个, 而且各家 provider 的配置差别很大, 同一个模型经不同 provider 出来性能和质量都不一致——你经 OpenRouter 之类的中转用某个模型, 永远不确定拿到的是不是这个模型的最佳版本。他们的做法是三步: 挑一组模型测过、和模型团队聊怎么跑最好, 再和几家 provider 对齐服务方式, 最后 benchmark「模型 + provider」这个组合, 给出一份他们敢推荐的清单。

本站判断: 这一段的价值不在网关本身, 而在它承认了一件事——编码 agent 的表现是「模型 × 供给配置」的乘积, 只报模型名是不够的。这与本站 LLM 域「智能 / 容量 / 供给」三把尺子同口径。官方文档里给出的推荐模型(非穷尽, 且明说可能不是最新)是 GPT 5.2、GPT 5.1 Codex、Claude Opus 4.5、Claude Sonnet 4.5、Minimax M2.1、Gemini 3 Pro。

工程反馈回路: LSP、AGENTS.md、skills、自定义工具、MCP、插件

这一层是 opencode 最厚的地方, 也是它被 fork 得最多的原因。逐条给判据:

• LSP(35+ 内置): 覆盖 typescript / pyright / gopls / rust-analyzer / clangd / jdtls / sourcekit-lsp / ruby-lsp / hls / julials / elixir-ls / ocaml-lsp / nixd / zls / gleam / dart / deno / csharp / fsharp / razor / kotlin-ls / lua-ls / php intelephense / clojure-lsp / bash / eslint / oxlint / prisma / terraform / tinymist / yaml-ls / astro / svelte / vue 等, 按扩展名检测、缺依赖时自动安装, 把 language server 的诊断当成 agent 的反馈信号。默认关闭。OPENCODE_DISABLE_LSP_DOWNLOAD=true 可禁止自动下载。
• 官方对 LSP 的反向建议(罕见且值得抄): 文档明写 LSP「不总是净收益」——language server 会失步、吃内存、随版本和项目而变、拖慢 agent 工作流; 很多项目里更好的做法是让 agent 直接跑 lint / typecheck 这类诊断 CLI, 把命令写进 AGENTS.md 或 skill 里让 agent 知道该跑什么。一个把功能推销给用户的文档不会写这段。
• Rules: AGENTS.md 就是项目自定义指令(类比 Cursor rules), /init 会扫仓库重要文件、必要时问几个针对性问题, 然后生成或就地改进已有的 AGENTS.md(不是盲目覆盖)。它聚焦未来会话最可能需要的东西: build/lint/test 命令、命令顺序与关键验证步骤、从文件名看不出来的架构与仓库结构、项目特有约定与运维坑、以及已存在的 Cursor / Copilot 规则引用。
• Skills: .opencode/skills/<name>/SKILL.md, 同时兼容 .claude/skills/ 与 .agents/skills/(项目级与全局 ~/.config/opencode、~/.claude、~/.agents 都找)。项目内路径会从当前工作目录一路向上走到 git worktree 根。机制是渐进披露: 工具描述里只列 name + description(YAML frontmatter 里认 name/description/license/compatibility/metadata 五个字段, 未知字段忽略), agent 需要时调 skill({ name }) 才加载全文。name 必须 1-64 字符、小写字母数字加单连字符、不能以 - 开头结尾、不能有连续 --, 且必须与所在目录同名。
• 自定义工具: .opencode/tools/*.ts(或全局), 文件名即工具名; 用 @opencode-ai/plugin 的 tool() helper 定义, 带 schema 与类型校验。工具定义只能是 TS/JS, 但它可以在内部调任意语言写的脚本。
• MCP: 本地与远程 server 都支持, 配在 mcp 段, 每个 server 有独立名字与 enabled 开关(临时关掉不用删配置), 加进来后与内置工具一起对模型可见。文档同样给了反向警告: MCP 会吃上下文, 工具一多涨得很快, 像 GitHub MCP 这类很容易顶穿上下文上限, 要挑着用。
• 插件: JS/TS 文件放 .opencode/plugins/(项目级)或 ~/.config/opencode/plugins/(全局), 启动自动加载; 也可以在配置里 "plugin": [...] 直接引 npm 包(支持 scoped 包)。插件是 hook 事件、改默认行为、接外部服务的入口。

权限与自主度: 三态, 而且可一键放开

permission 配置决定一个动作是自动跑 / 问你 / 直接拒绝(allow / ask / deny), 可以全局用 * 设一条再按工具覆盖。自 v1.1.1 起旧的 tools 布尔配置被废弃并合并进 permission(仍向后兼容)。

--auto 会自动批准所有不是显式 deny 的请求——注意口径: 它只改「本来要问你」的那些, 显式 deny 依然拦住。opencode run --auto "Refactor this module" 是脚本化用法; TUI 里可以在命令面板切自动批准, 生效时当前 agent 旁边会显示一个 muted 的 auto 标记。Plan agent 的默认 ask 加上 --auto 的例外规则, 合起来就是一套「可控自主度」的旋钮, 而不是一个 yolo 开关。

协作与交付: share、GitHub、ACP、企业版

• /share: 给会话生成公开链接 opncd.ai/s/<share-id>, 历史同步到官方服务器。三种模式, 默认 manual(不自动分享, 手动 /share 才生成并复制到剪贴板)。链接对任何拿到它的人公开。
• GitHub: 在 issue 或 PR 评论里提 /opencode 或 /oc, 任务在你自己的 GitHub Actions runner 里执行。能干三类事: 分诊 issue(让它看并解释)、修 issue 或实现功能(自动开新分支、提 PR 带上全部改动)、以及因为跑在你的 runner 里所以代码不出你的执行环境。opencode github install 一条命令走完装 GitHub app、建 workflow、配 secrets; 也可以手动装 app(github.com/apps/opencode-agent)再加 .github/workflows/opencode.yml。
• ACP(Agent Client Protocol): opencode acp 把自己作为 ACP 兼容子进程起来, 与编辑器走 stdio 上的 JSON-RPC。Zed 可以从 ACP Registry 直接装, 或在 ~/.config/zed/settings.json 的 agent_servers 里配 command: opencode, args: [acp]。意义是 opencode 不必自带所有编辑器插件——协议在, 编辑器就能接。
• 企业版: 面向「代码与数据不出自己基础设施」的组织, 用集中配置接 SSO 与内部 AI 网关。官方明确声明 opencode 不存你的代码与上下文数据, 所有处理在本地或直接打你选的 provider; 唯一例外是可选的 /share——开启后会话数据会送到 opencode.ai 托管分享页的服务, 经 CDN 边缘网络分发并缓存在离用户近的边缘节点, 因此官方建议企业试用时把它关掉。

怎么把它放进本站的坐标系

维度	opencode 的位置	与本站其它资产的对照
能力域	主挂 code(AI 编程)	它是编码 agent 本体; 其 server/SDK/插件面又使它同时是 harness(智能体运行时)的证据
开源侧角色	参照实现	MiMo-Code 是它的 fork(加持久记忆、上下文管理、目标裁判、compose 工作流); deepseek-harness 走「一切皆插件」的另一条路
模型立场	模型中立	75+ provider 都能接, 不绑某一家; Zen 是可选的精选网关而不是必需入口
可扩展面	五条并列: LSP / skills / custom tools / MCP / plugins	与 Claude Code、Codex 这类闭源 harness 相比, 五条全部对用户敞开且写进了 OpenAPI 契约
自主度控制	permission 三态 + --auto + Plan agent 只读	属于「可控自主」这一派, 不是无条件自动批准

最后一条与本站自身工作流直接相关: opencode 的 skill 发现路径同时认 .claude/skills/ 与 .agents/skills/, 也就是说同一份 skill 目录能被多家 harness 消费。这正是把 skill 当成跨 harness 资产(而不是某家产品的私有配置)的现实依据——写一次, 在 opencode、Claude Code 兼容层与其它 agent 目录约定里都能被找到。