OpenCode SDK（@opencode-ai/sdk）提供类型安全的 JavaScript/TypeScript 客户端，用于以编程方式与 OpenCode 服务器交互。支持创建会话、发送 Prompt、请求结构化输出、监听实时事件，以及控制 TUI 界面。

OpenCode JS/TS SDK 提供类型安全的客户端，用于以编程方式控制 OpenCode 服务器。适合构建自动化工具、CI/CD 集成或自定义 OpenCode 客户端。

详细了解服务器工作原理，参见 Server 文档。社区项目示例见生态系统。

---

安装

npm install @opencode-ai/sdk

---

创建客户端

createOpencode() 会同时启动服务器和客户端：

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

选项	类型	说明	默认值
hostname	string	服务器主机名	127.0.0.1
port	number	服务器端口	4096
signal	AbortSignal	取消信号	undefined
timeout	number	服务器启动超时（ms）	5000
config	Config	配置对象	{}

---

配置覆盖

传入配置对象覆盖 opencode.json 中的设置：

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`服务器运行在 ${opencode.server.url}`)

opencode.server.close()

---

只创建客户端（连接已有服务器）

如果 OpenCode 服务器已在运行，直接创建客户端实例：

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

选项	类型	说明	默认值
baseUrl	string	服务器 URL	http://localhost:4096
fetch	function	自定义 fetch 实现	globalThis.fetch
throwOnError	boolean	错误时抛异常而非返回	false

---

TypeScript 类型

SDK 包含完整的 TypeScript 类型定义，从服务器 OpenAPI 规范自动生成：

import type { Session, Message, Part } from "@opencode-ai/sdk"

---

结构化输出

通过 format 参数请求符合 JSON Schema 的结构化输出：

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "研究 Anthropic 公司并提供公司信息" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "公司名称" },
          founded: { type: "number", description: "成立年份" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "主要产品",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// 获取结构化数据
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

输出格式	说明
text	默认，标准文本响应
json_schema	返回符合指定 Schema 的 JSON

如果模型无法在重试后生成有效结构化输出，响应中会包含 StructuredOutputError：

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("结构化输出失败:", result.data.info.error.message)
}

---

主要 API

会话管理

// 创建会话
const session = await client.session.create({
  body: { title: "我的会话" },
})

// 列出所有会话
const sessions = await client.session.list()

// 发送 Prompt
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "你好！" }],
  },
})

// 注入上下文而不触发 AI 响应（适合插件场景）
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "你是一个专业的代码助手。" }],
  },
})

// 中止运行中的会话
await client.session.abort({ path: { id: session.id } })

文件操作

// 搜索文件内容
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

// 按名称查找文件
const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

// 读取文件内容
const content = await client.file.read({
  query: { path: "src/index.ts" },
})

服务器状态

// 检查服务器健康状态
const health = await client.global.health()
console.log(health.data.version)

// 列出可用 Agents
const agents = await client.app.agents()

// 获取当前配置
const config = await client.config.get()

控制 TUI

// 向提示框附加文本
await client.tui.appendPrompt({
  body: { text: "帮我分析这个函数" },
})

// 显示 Toast 通知
await client.tui.showToast({
  body: { message: "任务完成", variant: "success" },
})

// 执行命令
await client.tui.executeCommand({
  body: { command: "/models" },
})

实时事件监听

const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("事件:", event.type, event.properties)
}

配置认证凭证

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

---

错误处理

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("获取会话失败:", (error as Error).message)
}

---

常见问题

Q: SDK 和直接调用 opencode run CLI 有什么区别？

A: SDK 提供完整的编程接口，适合需要持久会话、监听事件流、控制 TUI 状态等场景。opencode run 更适合简单的单次调用。

Q: 如何在不启动新服务器的情况下连接到正在运行的 TUI？

A: 使用 createOpencodeClient({ baseUrl: "http://localhost:<port>" }) 连接到已有服务器。TUI 启动时会输出服务器端口，也可以通过 --port 参数固定端口。

Q: 结构化输出在哪些模型上可用？

A: 结构化输出使用 StructuredOutput Tool 实现，因此支持 Tool Call 的模型均可使用。如果模型不支持 Tool Call，则无法使用结构化输出。