跳到主要內容
安裝

SDK

opencode JS/TS SDK 提供了一個型別安全的用戶端，用於與伺服器進行互動。 您可以用它來建構整合方案，並以程式化方式控制 opencode。

了解更多關於伺服器的運作原理。如需範例，請查看社群建構的專案。

從 npm 安裝 SDK：

終端機
npm install @opencode-ai/sdk

建立一個 opencode 實例：

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

const { client } = await createOpencode()

這會同時啟動伺服器和用戶端。

選項

選項型別描述預設值
hostnamestring伺服器主機名稱127.0.0.1
portnumber伺服器連接埠4096
signalAbortSignal用於取消操作的中止訊號undefined
timeoutnumber伺服器啟動逾時時間（毫秒）5000
configConfig設定物件{}

您可以傳入一個設定物件來自訂行為。實例仍然會讀取您的 opencode.json，但您可以透過內嵌方式覆寫或新增設定：

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

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

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()

如果您已經有一個正在執行的 opencode 實例，可以建立一個用戶端實例來連線：

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

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

選項

選項型別描述預設值
baseUrlstring伺服器 URLhttp://localhost:4096
fetchfunction自訂 fetch 實作globalThis.fetch
parseAsstring回應解析方式auto
responseStylestring回傳風格：data 或 fieldsfields
throwOnErrorboolean拋出錯誤而非回傳錯誤false

SDK 包含所有 API 型別的 TypeScript 定義。您可以直接匯入它們：

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

所有型別均根據伺服器的 OpenAPI 規範產生，可在型別檔案中查看。

SDK 可能會拋出錯誤，您可以捕捉並處理這些錯誤：

TypeScript
try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

您可以透過指定帶有 JSON Schema 的 format 來請求模型回傳結構化的 JSON 輸出。模型會使用 StructuredOutput 工具回傳符合您 Schema 的經過驗證的 JSON。

TypeScript
const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

型別描述
text預設值。標準文字回應（無結構化輸出）
json_schema回傳符合所提供 Schema 的經過驗證的 JSON

使用 type: 'json_schema' 時，需提供以下欄位：

欄位型別描述
type'json_schema'必填。指定 JSON Schema 模式
schemaobject必填。定義輸出結構的 JSON Schema 物件
retryCountnumber選填。驗證重試次數（預設值：2）

如果模型在所有重試後仍無法產生有效的結構化輸出，回應中會包含 StructuredOutputError：

TypeScript
if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

  1. 在 Schema 屬性中提供清晰的描述，幫助模型理解需要擷取的資料
  2. 使用 required 指定哪些欄位必須存在
  3. 保持 Schema 簡潔 — 複雜的巢狀 Schema 可能會讓模型更難正確填充
  4. 設定合適的 retryCount — 對於複雜 Schema 可增加重試次數，對於簡單 Schema 可減少

SDK 透過型別安全的用戶端公開所有伺服器 API。

方法描述回應
global.health()檢查伺服器健康狀態和版本{ healthy: true, version: string }

範例

JavaScript
const health = await client.global.health()
console.log(health.data.version)

方法描述回應
app.log()寫入一筆日誌boolean
app.agents()列出所有可用的代理Agent[]

範例

JavaScript
// 寫入一筆日誌
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// 列出可用的代理
const agents = await client.app.agents()

方法描述回應
project.list()列出所有專案Project[]

範例

JavaScript
// List all projects
const projects = await client.project.list()

方法描述回應
path.get()取得當前路徑Path

範例

JavaScript
// 取得當前路徑資訊
const pathInfo = await client.path.get()

方法描述回應
config.get()取得設定資訊Config
config.providers()列出供應商和預設模型{ providers: Provider[], default: { [key: string]: string } }

範例

JavaScript
const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

方法描述備註
session.list()列出工作階段回傳 Session[]
session.get({ path })取得工作階段回傳 Session
session.children({ path })列出子工作階段回傳 Session[]
session.create({ body })建立工作階段回傳 Session
session.delete({ path })刪除工作階段回傳 boolean
session.update({ path, body })更新工作階段屬性回傳 Session
session.init({ path, body })分析應用程式並建立 AGENTS.md回傳 boolean
session.abort({ path })中止正在執行的工作階段回傳 boolean
session.share({ path })分享工作階段回傳 Session
session.unshare({ path })取消分享工作階段回傳 Session
session.summarize({ path, body })摘要工作階段回傳 boolean
session.messages({ path })列出工作階段中的訊息回傳 { info: Message, parts: Part[]}[]
session.message({ path })取得訊息詳情回傳 { info: Message, parts: Part[]}
session.prompt({ path, body })傳送提示訊息body.noReply: true 回傳 UserMessage（僅注入上下文）。預設回傳帶有 AI 回應的 AssistantMessage。支援透過 body.outputFormat 使用結構化輸出
session.command({ path, body })向工作階段傳送指令回傳 { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })執行 shell 指令回傳 AssistantMessage
session.revert({ path, body })還原訊息回傳 Session
session.unrevert({ path })恢復已還原的訊息回傳 Session
postSessionByIdPermissionsByPermissionId({ path, body })回覆權限請求回傳 boolean

範例

JavaScript
// Create and manage sessions
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

方法描述回應
find.text({ query })搜尋檔案中的文字包含 path、lines、line_number、absolute_offset、submatches 的比對物件陣列
find.files({ query })按名稱尋找檔案和目錄string[]（路徑）
find.symbols({ query })尋找工作區符號Symbol[]
file.read({ query })讀取檔案{ type: "raw" | "patch", content: string }
file.status({ query? })取得已追蹤檔案的狀態File[]

find.files 支援以下選填的查詢欄位：

  • type："file" 或 "directory"
  • directory：覆寫搜尋的專案根目錄
  • limit：最大結果數（1–200）

範例

JavaScript
// 搜尋和讀取檔案
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

const directories = await client.find.files({
  query: { query: "packages", type: "directory", limit: 20 },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

方法描述回應
tui.appendPrompt({ body })向提示詞追加文字boolean
tui.openHelp()開啟說明對話框boolean
tui.openSessions()開啟工作階段選擇器boolean
tui.openThemes()開啟主題選擇器boolean
tui.openModels()開啟模型選擇器boolean
tui.submitPrompt()送出當前提示詞boolean
tui.clearPrompt()清除提示詞boolean
tui.executeCommand({ body })執行指令boolean
tui.showToast({ body })顯示 Toast 通知boolean

範例

JavaScript
// 控制 TUI 介面
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

方法描述回應
auth.set({ ... })設定驗證憑證boolean

範例

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

方法描述回應
event.subscribe()伺服器傳送的事件串流伺服器傳送的事件串流

範例

JavaScript
// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}