5.10a SDK 基础

一句话总结：使用 JavaScript/TypeScript SDK 以编程方式控制 OpenCode，实现自动化工作流和自定义集成。

📝 课程笔记

本课核心知识点整理：

学完你能做什么

安装和配置 OpenCode SDK

创建服务器和客户端实例

启动 TUI 界面

管理会话和发送消息

监听实时事件

你现在的困境

想在自己的应用里调用 OpenCode

想以编程方式批量处理任务

想构建自定义集成（IDE 插件、CI/CD 工具等）

想在脚本中自动化 OpenCode 操作

SDK 架构概览

┌─────────────────────────────────────────────────────────┐
│                    你的应用程序                           │
├─────────────────────────────────────────────────────────┤
│                   @opencode-ai/sdk                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │createOpencode│  │createOpencode│  │createOpencode│    │
│  │             │  │   Client    │  │    Tui      │      │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │
│         │                │                │              │
│  服务器+客户端      仅客户端连接      启动 TUI 界面       │
└─────────┼────────────────┼────────────────┼─────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────┐
│                  OpenCode Server                         │
│            HTTP API (默认端口 4096)                       │
└─────────────────────────────────────────────────────────┘

安装 SDK

三种使用方式

1. 创建服务器 + 客户端（推荐）

同时启动服务器和客户端，适合独立脚本和自动化场景：

ServerOptions 参数

参数	类型	描述	默认值
`hostname`	`string`	服务器主机名	`127.0.0.1`
`port`	`number`	服务器端口	`4096`
`signal`	`AbortSignal`	用于取消的中止信号	`undefined`
`timeout`	`number`	服务器启动超时（毫秒）	`2000+`
`config`	`Config`	配置对象，覆盖 `opencode.json`	`{}`

来源：packages/sdk/js/src/server.ts:4-10

配置覆盖示例

2. 仅客户端模式

连接到已运行的 OpenCode 实例，适合插件开发：

ClientOptions 参数

参数	类型	描述	默认值
`baseUrl`	`string`	服务器 URL	`http://localhost:4096`
`fetch`	`function`	自定义 fetch 实现	`globalThis.fetch`
`parseAs`	`string`	响应解析方式：`auto`, `json`, `text`, `blob`, `arrayBuffer`, `stream`, `formData`	`auto`
`responseStyle`	`"data" \| "fields"`	返回风格：`data` 仅返回数据，`fields` 返回完整响应	`fields`
`throwOnError`	`boolean`	出错时抛出异常而非返回	`false`
`directory`	`string`	指定项目目录（通过 `X-Opencode-Directory` header 传递）	`undefined`

来源：packages/sdk/js/src/gen/client/types.gen.ts:10-52、packages/sdk/js/src/client.ts:8

多项目目录切换

远程连接（带认证）

当连接远程 OpenCode 服务器时，如果服务器设置了 OPENCODE_SERVER_PASSWORD，需要通过 headers 传递 Basic Auth 认证：

::: details Node.js 环境用 Buffer

:::

场景	用户名	说明
默认	`opencode`	服务器默认用户名
自定义	环境变量 `OPENCODE_SERVER_USERNAME` 的值	如果服务器设置了自定义用户名

来源：packages/opencode/src/server/server.ts:84-87（Basic Auth 中间件）

3. 启动 TUI 界面

以编程方式启动 OpenCode 的终端界面：

TuiOptions 参数

参数	类型	描述
`project`	`string`	项目目录路径
`model`	`string`	使用的模型（格式：`provider/model`）
`session`	`string`	恢复指定会话 ID
`agent`	`string`	使用的 Agent（如 `build`, `plan`）
`signal`	`AbortSignal`	用于取消的中止信号
`config`	`Config`	配置对象

来源：packages/sdk/js/src/server.ts:12-19

基础 API 使用

会话管理

发送消息

异步发送（不等待响应）

文件操作

TUI 控制

实时事件监听

订阅事件流

常用事件类型

事件类型	说明
`message.updated`	消息内容更新
`message.part.updated`	消息部分更新（含 delta 增量）
`session.status`	会话状态变更（idle/busy/retry）
`session.idle`	会话进入空闲状态
`permission.updated`	权限请求待处理
`file.edited`	文件被编辑
`todo.updated`	Todo 列表更新

完整事件类型列表请参阅 5.10b API 参考

类型导入

SDK 提供完整的 TypeScript 类型定义：

错误处理

标准错误处理

使用 throwOnError 选项

检查返回值

实战示例：批量代码审查

踩坑提醒

现象	原因	解决
SDK 连接失败	服务器未启动	先运行 `opencode serve` 或使用 `createOpencode()`
端口冲突	默认端口 4096 被占用	指定其他端口 `port: 4097`
类型错误	SDK 版本不匹配	更新到最新版本 `npm update @opencode-ai/sdk`
超时错误	服务器启动慢或网络问题	增加 `timeout` 值
事件流中断	连接断开	实现重连逻辑
响应格式困惑	`responseStyle` 配置	默认为 `fields`，返回 `{ data, error, request, response }`

本课小结

你学会了：

安装 SDK：npm install @opencode-ai/sdk

三种使用方式：

createOpencode() - 服务器 + 客户端

createOpencodeClient() - 仅客户端

createOpencodeTui() - 启动 TUI

基础 API：会话管理、消息发送、文件操作、TUI 控制

事件监听：实时接收状态变更

下一课预告

5.10b API 参考将详细介绍所有 21 个 API 模块、完整类型定义和 35+ 种事件类型。

📝 课程笔记#

学完你能做什么#

你现在的困境#

SDK 架构概览#

安装 SDK#

三种使用方式#

1. 创建服务器 + 客户端（推荐）#

ServerOptions 参数#

配置覆盖示例#

2. 仅客户端模式#

ClientOptions 参数#

多项目目录切换#

远程连接（带认证）#

3. 启动 TUI 界面#

TuiOptions 参数#

基础 API 使用#

会话管理#

发送消息#

异步发送（不等待响应）#

文件操作#

TUI 控制#

实时事件监听#

订阅事件流#

常用事件类型#

类型导入#

错误处理#

标准错误处理#

使用 throwOnError 选项#

检查返回值#

实战示例：批量代码审查#

踩坑提醒#

本课小结#

相关资源#

下一课预告#