---
title: "使用 SDK"
description: "基于官方 OpenCode SDK 教程，面向新手讲清 SDK 适合什么集成场景、server/client 怎么理解、结构化输出和错误处理怎么验收。"
verifiedAt: "2026-05-09"
---

OpenCode JS/TS SDK 是 opencode server 的类型安全客户端。它适合把 OpenCode 接进你自己的工具、后台服务、自动化平台或产品界面。

新手先记住：SDK 不是用来替代 TUI 的第一入口。你已经能在 TUI / CLI 里稳定完成任务后，才应该考虑 SDK。

> [!NOTE]
> **这一篇用 8 分钟换什么**：你会知道 SDK 和 TUI / CLI / server 的边界，什么时候让 SDK 启动 server，什么时候连接已有 server，以及结构化输出和错误处理怎么验收。

## SDK 集成路径

SDK 是 server 的类型安全客户端，不是模型 API 的简单 wrapper。

```mermaid
flowchart LR
  TUI["TUI / CLI 已跑通"] --> Server{"server 谁来管理?"}
  Server -->|SDK 启动| Local["本地工具 / 一次性实验"]
  Server -->|外部已有| Client["client-only 连接已有 server"]
  Local --> Prompt["只读 prompt"]
  Client --> Prompt
  Prompt --> Structured["结构化输出"]
  Structured --> Product["业务系统 / dashboard / 队列 / PR 检查"]

  style TUI fill:#dbeafe,stroke:#3b82f6
  style Prompt fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Product fill:#fef3c7,stroke:#f59e0b
```

## 先理解：SDK 解决什么问题

TUI 解决“人和 OpenCode 交互”。

CLI 解决“从命令行触发任务”。

Server 解决“OpenCode 对外提供可调用 API”。

SDK 解决“你的 JS/TS 程序类型安全地调用 server”。

如果你只是想手动改代码，用 TUI。如果你只是想在脚本里跑一次任务，先看 CLI。如果你要让内部系统创建 session、发送 prompt、读取结果、做结构化输出、集成到业务流程里，才用 SDK。

## 两种使用方式怎么选

第一种是 SDK 帮你启动 server，并返回 client。这适合本地工具、桌面辅助脚本和一次性集成实验。

第二种是 client-only，连接已经运行的 opencode server。这适合已有后台服务、共享 server、容器化部署或你想自己控制 server 生命周期的场景。

新手先用第一种验证 API 调用，再用第二种做真实集成。不要一开始就把 server 生命周期、认证、端口、日志、错误处理全混在一起。

## 配置怎么理解

SDK 可以传入 config 覆盖或补充本机 `opencode.json`。这适合测试不同模型、切换 provider、限制工具或为某个集成定制行为。

但不要把凭据塞进 SDK 代码。provider key 仍然应该由 `/connect`、环境变量或安全凭据系统管理。

如果 SDK 代码要进仓库，配置里只放可公开的模型名、provider 名和行为策略，不放 token。

## 结构化输出什么时候用

官方 SDK 支持通过 JSON Schema 请求结构化输出。它适合让下游程序消费结果，例如风险报告、项目元数据、发布摘要、分类标签、检查清单。

结构化输出不是为了让回答更好看，而是为了让程序能稳定解析。

新手写 schema 时要简单：字段少、描述清楚、required 明确。复杂嵌套 schema 会增加模型失败和重试成本。

## 错误处理要先设计

SDK 集成一定会遇到错误：server 启动失败、端口被占、模型请求失败、session id 无效、结构化输出校验失败、网络超时。

新手不要只写 happy path。至少要处理：

- server 是否启动成功。
- client 是否连到正确 base URL。
- prompt 是否返回错误对象。
- 结构化输出是否失败并需要重试。
- 操作结束后 server 是否需要关闭。

## 新手常见坑

- TUI 还没跑通就写 SDK：问题会被包装层掩盖。
- 把 SDK 当模型 API：它控制的是 OpenCode server，不只是调用 LLM。
- 不管理 server 生命周期：本地残留进程、端口冲突、测试互相影响。
- 把 API key 写进代码：SDK 示例里出现 config，不代表凭据可以进仓库。
- schema 太复杂：结构化输出频繁失败，最后又回到自然语言解析。
- 忽略 TypeScript 类型：SDK 的价值之一就是让 API shape 在开发时暴露出来。

## 一个稳妥的集成路线

第一步，在 TUI 里确认 provider、model、permissions 和项目配置都能工作。

第二步，用 SDK 做一个只读健康检查：连接 server，确认版本和当前项目。

第三步，创建一个最小 session，发送一个只读 prompt，读取结果。

第四步，加入结构化输出，让结果变成固定字段。

第五步，再接入业务系统，例如 PR 检查、内部 dashboard、任务队列或发布流程。

第二步的最小骨架大概长这样（伪代码 / 概念示意，具体导入名以官方 SDK 当前版本为准）：

```ts
import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk";

// 方式 A：让 SDK 自己启动一个临时 server（适合本地工具）
const server = await createOpencodeServer({ hostname: "127.0.0.1", port: 0 });
const client = createOpencodeClient({ baseUrl: server.url });

// 健康检查：先确认能连通
const { data: health } = await client.app.get();
console.log("opencode 已连接：", health);

// 用完关掉 server，避免后台进程残留
await server.close();
```

如果你已经在外部用 `opencode serve` 起了一个 server，跳过 `createOpencodeServer`，只把 `baseUrl` 指向那个 server 的地址即可（外部启动时记得设 `OPENCODE_SERVER_PASSWORD` + 在 client 里带上 basic auth header）。

## 怎么验收

集成完成后，至少确认：

- 能说明 server 是 SDK 启动的，还是外部已运行的。
- 能区分 server 未启动、client base URL 错误、模型失败、权限失败和结构化输出失败。
- SDK 代码里没有 key、token 和私有配置。
- 输入输出由 TypeScript 类型约束，不是到处写 `any`。
- 本地 server 在任务结束后能关闭，避免测试和开发环境残留。

## 接下来去哪

<Cards>
  <Card title="启动服务器" description="SDK 之前先理解 `opencode serve`、OpenAPI、认证和 server 安全边界。" href="/docs/opencode/official/07-sdk/server" />
  <Card title="Web 入口" description="如果目标是浏览器使用 OpenCode，先确认 web 和 server 的职责区别。" href="/docs/opencode/official/07-sdk/web" />
  <Card title="CLI 入口" description="只想脚本化跑一次任务时，`opencode run` 通常比 SDK 更简单。" href="/docs/opencode/official/00-getting-started/cli" />
  <Card title="权限配置" description="把 SDK 接进真实项目之前，先收紧文件、shell、MCP 和分享权限。" href="/docs/opencode/official/05-security/permissions" />
</Cards>

## 官方资料

- SDK：[https://opencode.ai/docs/sdk](https://opencode.ai/docs/sdk)
- Server：[https://opencode.ai/docs/server](https://opencode.ai/docs/server)
- Ecosystem：[https://opencode.ai/docs/ecosystem](https://opencode.ai/docs/ecosystem)
