---
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="/zh-Hant/docs/opencode/official/07-sdk/server" />
  <Card title="Web 入口" description="如果目標是瀏覽器使用 OpenCode，先確認 web 和 server 的職責區別。" href="/zh-Hant/docs/opencode/official/07-sdk/web" />
  <Card title="CLI 入口" description="只想指令碼化跑一次任務時，`opencode run` 通常比 SDK 更簡單。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="許可權配置" description="把 SDK 接進真實專案之前，先收緊檔案、shell、MCP 和分享許可權。" href="/zh-Hant/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)
