JavaScript 与 TypeScript SDK

创建或连接 OpenCode 服务，正确处理返回包装、错误和事件。

@opencode-ai/sdk 提供服务端的类型化 JavaScript/TypeScript 客户端。它既能启动一个服务，也能连接已经运行的服务。

安装与生命周期

npm install @opencode-ai/sdk

同时创建服务和客户端：

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

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
})

try {
  const result = await opencode.client.global.health()
  console.log(result.data)
} finally {
  opencode.server.close()
}

createOpencode 选项	默认值与用途
`hostname`	`127.0.0.1`
`port`	`4096`
`signal`	`undefined`，取消信号
`timeout`	`5000` 毫秒，服务启动超时
`config`	`{}`，内联 OpenCode 配置

内联 config 可以补充或覆盖配置，实例仍会读取 opencode.json。启动超时与模型请求超时不是同一设置。

连接已有服务

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

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

const result = await client.session.create({
  body: { title: "Repository overview" },
})
if (!result.data) throw new Error("Session creation returned no data")
const sessionId = result.data.id
await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Explain the repository structure." }],
  },
})

示例使用默认导出入口的 path.id 形状，没有启动或关闭已有后端。先配置好模型与权限，再提交实际任务。

返回值与错误

客户端 baseUrl 默认 http://localhost:4096；可提供自定义 fetch。parseAs 默认 auto，根据内容类型选择解析方式。

responseStyle 默认为 fields，响应包含 data、error、response 等字段；设置为 data 时只返回业务数据。throwOnError 默认 false，API 错误通过返回值表达；设置为 true 后才按抛错方式处理。应用仍需处理网络等调用异常。

官方 SDK 页部分示例直接使用 session.id 或直接解构 providers，另一些使用 result.data。本页根据同一提交的客户端类型统一使用 fields 包装，不能混用两种访问方式。

事件订阅

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

这是长时间运行的 SSE 消费循环，事件用于观察会话进度和界面更新。方法分组见SDK 方法参考。

类型与版本

可从包导入 Session、Message、Part 等类型。官方仓库同时导出默认入口和 @opencode-ai/sdk/v2，两者不能仅替换 import 后沿用全部参数；结构化输出尤其存在文档与生成类型差异，见结构化输出。