SDK

SDK JS/TS с открытым кодом предоставляет типобезопасный клиент для взаимодействия с сервером. Используйте его для создания интеграции и программного управления открытым кодом.

Узнайте больше о том, как работает сервер. Примеры можно найти в projects, созданном сообществом.

Установите SDK из npm:

Терминал

npm install @opencode-ai/sdk

Создайте экземпляр opencode:

JavaScript

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

const { client } = await createOpencode()

Это запускает и сервер, и клиент.

Параметры

Вариант	Тип	Описание	По умолчанию
`hostname`	`string`	Server hostname	`127.0.0.1`
`port`	`number`	Server port	`4096`
`signal`	`AbortSignal`	Abort signal for cancellation	`undefined`
`timeout`	`number`	Timeout in ms for server start	`5000`
`config`	`Config`	Configuration object	`{}`

Вы можете передать объект конфигурации для настройки поведения. Экземпляр по-прежнему получает ваш 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",
})

Параметры

Вариант	Тип	Описание	По умолчанию
`baseUrl`	`string`	URL of the server	`http://localhost:4096`
`fetch`	`function`	Custom fetch implementation	`globalThis.fetch`
`parseAs`	`string`	Response parsing method	`auto`
`responseStyle`	`string`	Return style: `data` or `fields`	`fields`
`throwOnError`	`boolean`	Throw errors instead of return	`false`

SDK включает определения TypeScript для всех типов API. Импортируйте их напрямую:

TypeScript

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

Все типы генерируются на основе спецификации OpenAPI сервера и доступны в файле types.

SDK может выдавать ошибки, которые вы можете отловить и обработать:

TypeScript

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

Вы можете запросить структурированный вывод JSON от модели, указав format со схемой JSON. Модель будет использовать инструмент StructuredOutput для возврата проверенного 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`	Возвращает проверенный JSON, соответствующий предоставленной схеме

При использовании type: 'json_schema', укажите:

Поле	Тип	Описание
`type`	`'json_schema'`	Обязательно. Указывает режим схемы JSON
`schema`	`object`	Обязательно. Объект JSON Schema, определяющий структуру вывода
`retryCount`	`number`	Необязательно. Количество повторных попыток проверки (по умолчанию: 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)
}

Предоставляйте четкие описания в свойствах вашей схемы, чтобы помочь модели понять, какие данные извлекать
Используйте required, чтобы указать, какие поля должны присутствовать
Делайте схемы сфокусированными — сложные вложенные схемы могут быть труднее для правильного заполнения моделью
Устанавливайте соответствующий retryCount — увеличивайте для сложных схем, уменьшайте для простых

SDK предоставляет все серверные API через типобезопасный клиент.

Метод	Описание	Ответ
`global.health()`	Check server health and version	`{ healthy: true, version: string }`

Примеры

JavaScript

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

Метод	Описание	Ответ
`app.log()`	Write a log entry	`boolean`
`app.agents()`	List all available agents	`Agent[]`

Примеры

JavaScript

// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()

Метод	Описание	Ответ
`project.list()`	List all projects	`Project[]`

Примеры

JavaScript

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

Метод	Описание	Ответ
`path.get()`	Get current path	`Path`

Примеры

JavaScript

// Get current path information
const pathInfo = await client.path.get()

Метод	Описание	Ответ
`config.get()`	Get config info	`Config`
`config.providers()`	List providers and default models	`{ providers:` `Provider[], default: { [key: string]: string } }`

Примеры

JavaScript

const config = await client.config.get()

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

Метод	Описание	Примечания
`session.list()`	List sessions	Returns `Session[]`
`session.get({ path })`	Get session	Returns `Session`
`session.children({ path })`	List child sessions	Returns `Session[]`
`session.create({ body })`	Create session	Returns `Session`
`session.delete({ path })`	Delete session	Returns `boolean`
`session.update({ path, body })`	Update session properties	Returns `Session`
`session.init({ path, body })`	Analyze app and create `AGENTS.md`	Returns `boolean`
`session.abort({ path })`	Abort a running session	Returns `boolean`
`session.share({ path })`	Share session	Returns `Session`
`session.unshare({ path })`	Unshare session	Returns `Session`
`session.summarize({ path, body })`	Summarize session	Returns `boolean`
`session.messages({ path })`	List messages in a session	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Get message details	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Send prompt message	`body.noReply: true` возвращает UserMessage (только контекст). По умолчанию возвращает `AssistantMessage` с ответом ИИ. Поддерживает `body.outputFormat` для структурированного вывода
`session.command({ path, body })`	Send command to session	Returns `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Run a shell command	Returns `AssistantMessage`
`session.revert({ path, body })`	Revert a message	Returns `Session`
`session.unrevert({ path })`	Restore reverted messages	Returns `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Respond to a permission request	Returns `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 })`	Search for text in files	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Find files and directories by name	`string[]` (paths)
`find.symbols({ query })`	Find workspace symbols	`Symbol[]`
`file.read({ query })`	Read a file	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Get status for tracked files	`File[]`

find.files поддерживает несколько дополнительных полей запроса:

type: "file" или "directory"
directory: переопределить корень проекта для поиска.
limit: максимальное количество результатов (1–200)

Примеры

JavaScript

// Search and read files
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 })`	Append text to the prompt	`boolean`
`tui.openHelp()`	Open the help dialog	`boolean`
`tui.openSessions()`	Open the session selector	`boolean`
`tui.openThemes()`	Open the theme selector	`boolean`
`tui.openModels()`	Open the model selector	`boolean`
`tui.submitPrompt()`	Submit the current prompt	`boolean`
`tui.clearPrompt()`	Clear the prompt	`boolean`
`tui.executeCommand({ body })`	Execute a command	`boolean`
`tui.showToast({ body })`	Show toast notification	`boolean`

Примеры

JavaScript

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

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

Метод	Описание	Ответ
`auth.set({ ... })`	Set authentication credentials	`boolean`

Примеры

JavaScript

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

Метод	Описание	Ответ
`event.subscribe()`	Server-sent events stream	Server-sent events stream

Примеры

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)
}

SDK

Установить

Создать клиента

Параметры

Конфигурация

Только клиент

Параметры

Типы

Ошибки

Структурированный вывод

Основное использование

Типы форматов вывода

Формат схемы JSON

Обработка ошибок

Лучшие практики

API

Глобальный

Примеры

Приложение

Примеры

Проект

Примеры

Путь

Примеры

Конфигурация

Примеры

Сессии

Примеры

Файлы

Примеры

TUI

Примеры

Аутентификация

Примеры

События

Примеры