OpenCode 2.0 新增开发包：client / codemode / sdk

版本：2.0.27 · 发布日期：2026-10-12（公测 2026-07-10）· 文档定位：开发包说明（面向二次开发与集成）

速查：关键结论

关键结论：

• 三个包都面向开发者；只是使用 OpenCode（TUI / 网页 / 手机）的人不需要。
• client 与 sdk 的区别只在传输层：网络 vs 内存，API 形状一致。
• codemode 默认对所有 MCP 服务器开启，普通使用者无需任何配置。

一、定位总览

官方将"在 OpenCode 之上构建"归纳为三种方式：

三者不在同一层：

• client、sdk 解决"引擎在哪运行、程序怎么连"；
• codemode 解决"引擎内部的模型如何调用工具"。

二、@opencode/client —— 网络客户端库

2.1 定义与边界

• 官方定义：the TypeScript client for the OpenCode HTTP API，用于"应用程序通过网络连接一台正在运行的 OpenCode 服务器"。
• 底层全部是 HTTP 请求（REST + SSE 事件流），本包只是把这些请求封装成带类型的 JS/TS 方法。
• 其类型与方法由与 API reference 同一份契约生成（/openapi.json），新接口出现后客户端同步更新。

2.2 语言与技术栈

注意区分两层含义：

• 架构角色：凡通过网络连接服务的程序都是 client（与语言无关）；
• 官方实现：@opencode/client 特指官方那个 TS 库，只在 JS/TS 技术栈可用。

2.3 使用示例

import { OpenCode } from "@opencode/client"

const client = OpenCode.make({
  baseUrl: "http://localhost:4096",
})

const session = await client.session.create({
  location: { directory: "/workspace" },
})

await client.session.prompt({
  sessionID: session.id,
  text: "Review the current changes",
})

带认证头与超时：

const client = OpenCode.make({
  baseUrl: "https://opencode.example.com",
  headers: { authorization: `Bearer ${process.env.OPENCODE_TOKEN}` },
})

await client.session.list(undefined, { signal: AbortSignal.timeout(10_000) })

事件订阅（返回异步迭代器）：

for await (const event of client.event.subscribe()) {
  console.log(event.type)
}

2.4 要点

三、@opencode/sdk —— 嵌入式引擎

3.1 与 client 的本质区别

官方原文：the SDK … assembles the OpenCode server and routes API calls through its HTTP router in memory. It opens no HTTP listener and adds no network hop between the client and server.

sdk 是引擎本体，不是接口封装：OpenCode.create() 在你进程内实例化整个 server（router、Location 服务、fiber、插件注册、会话执行等），API 调用走内存中的 HTTP router。

3.2 使用示例

import { OpenCode } from "@opencode/sdk"

await using opencode = await OpenCode.create()
const session = await opencode.sessions.create({
  location: { directory: "/workspace" },
})

await opencode.sessions.prompt({
  sessionID: session.id,
  text: "Review the current changes",
})

• OpenCode.create() 返回显式持有的宿主；无显式资源管理环境时调用 await opencode.close()。
• 与 client 共用同一套 Promise 值、声明的错误类型、请求选项、AsyncIterable 流；并额外提供 sessions / events 便捷别名。
• worktree 操作需 projectID。
• 可在内嵌实例上加载插件：OpenCode.create({ plugins: [plugin] })，插件 API 与 CLI 相同。

3.3 典型用途

• 把 agent 能力嵌入自有产品（内嵌 server + 自绘界面/工作流），并对外包装成独立产品；
• 部署到受限环境（如 Cloudflare Durable Objects，官方提供专项指南），引擎可裁剪；
• 由于对外走的是标准 OpenCode server 协议，任何 OpenCode 客户端都可连接它。

3.4 许可注意

项目为 MIT 许可：可商用、可修改、可闭源，义务是保留版权声明（LICENSE）。

四、@opencode/codemode —— 模型调用工具的机制（重点）

4.1 一句话

传统方式一次工具调用 = 一次模型往返；Code Mode 让模型写一段 JS 程序，由运行时一次执行，循环、并行、条件、结果后处理都在程序内完成，中间结果不进模型上下文。

4.2 与传统方式的对比

4.3 机制：search + execute

模型侧只保留两个"骨架工具"的说明（固定大小）：

• execute：执行一段 JS；工具通过 tools.<server>.<tool>(...) 调用。其 schema 是通用且固定大小的，不枚举任何具体工具。
• search：按关键词 / 命名空间查询工具，返回命中的"工具卡片"（path、描述、参数签名）。

工具定义存放在运行时一侧的 catalog（注册表）中，按需拉取：

• 不搜 → 不进上下文；
• 只搜命中项 → 只有命中的卡片进入上下文；
• 上下文成本 = O(1)（两个骨架工具）+ O(实际查询/使用的工具数)。

对比"全量 push"：传统方式把全部工具 schema 每轮推给模型；Code Mode 是"按需 pull"，用偶尔一次 search 的往返，换掉每轮常驻的全量 schema。工具越多，交换越划算。

4.4 常见疑问（结论）

关键词说明：实际的查找是查询已注册的 catalog，返回精确的 path / description / signature，不是统计或猜测。

4.5 示例（以 unityMCP 为例）

任务：把场景中所有 Cube 沿 X 轴排开。

传统方式

模型 → manage_scene(get_hierarchy)             ← 整棵场景树 JSON 进入上下文
模型 → manage_gameobject(set_transform, Cube1)  ← 结果进入上下文
模型 → manage_gameobject(set_transform, Cube2)  ← 结果进入上下文
... N 个 Cube 需要 N 次

→ N+1 次往返，中间数据全部经过上下文。

Code Mode：模型先 search("gameobject transform") 获取卡片，再输出一段 execute 脚本（示意）：

const h = await tools.unityMCP.manage_scene({ action: "get_hierarchy" })
const cubes = h.tree.filter(o => o.name.startsWith("Cube"))

await Promise.all(cubes.map((c, i) =>
  tools.unityMCP.manage_gameobject({
    action: "set_transform",
    target: c.name,
    position: { x: i * 2, y: 0, z: 0 },
  })))

→ 1 次往返；场景树与每个中间结果留在解释器内，只有结果回到模型。（参数形态以实际 MCP 服务器定义为准。）

官方发布说明中的同型示例：查出标记为 bug 的 GitHub issue → 写入 Linear → 返回新建 ID，同样在一次程序内完成。

4.6 配置

• 默认对所有 MCP 服务器开启。
• 关闭单个服务器：配置中 "codemode": false，该服务器的工具回到模型原生工具列表。
• 效果：MCP 工具的 schema 不再每轮进入模型上下文，可挂载大量服务器而上下文开销可控。

五、什么时候用哪个

六、常见误区

参考

• 官方文档：opencode.ai/v2/docs/build/（Intro / Client / SDK）
• 官方文档：opencode.ai/v2/docs/tools/（Execute / Code Mode）
• 官方发布说明：OpenCode 2.0 launch note（Anomaly，2026-10-12）