🤖 OpenCode📚 官方教程中文版📦 SDK & 服务
SDK
opencode 服务器的类型安全 JS 客户端。
opencode 服务器的类型安全 JS 客户端。
opencode JS/TS SDK 提供了一个类型安全的客户端，用于与服务器进行交互。 你可以用它来构建集成方案，并以编程方式控制 opencode。
了解更多关于服务器的工作原理。如需示例，请查看社区构建的项目。
安装
从 npm 安装 SDK：
npm install @opencode-ai/sdk创建客户端
创建一个 opencode 实例：
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()这会同时启动服务器和客户端。
选项
| 选项 | 类型 | 描述 | 默认值 |
|---|---|---|---|
hostname | string | 服务器主机名 | 127.0.0.1 |
port | number | 服务器端口 | 4096 |
signal | AbortSignal | 用于取消操作的中止信号 | undefined |
timeout | number | 服务器启动超时时间（毫秒） | 5000 |
config | Config | 配置对象 | {} |
配置
你可以传入一个配置对象来自定义行为。实例仍然会读取你的 opencode.json，但你可以通过内联方式覆盖或添加配置：
import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({ hostname: "127.0.0.1", port: 4096, config: { model: "anthropic/claude-3-5-sonnet-20241022", },})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()仅客户端模式
如果你已经有一个正在运行的 opencode 实例，可以创建一个客户端实例来连接它：
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({ baseUrl: "http://localhost:4096",})选项
| 选项 | 类型 | 描述 | 默认值 |
|---|---|---|---|
baseUrl | string | 服务器 URL | http://localhost:4096 |
fetch | function | 自定义 fetch 实现 | globalThis.fetch |
parseAs | string | 响应解析方式 | auto |
responseStyle | string | 返回风格：data 或 fields | fields |
throwOnError | boolean | 抛出错误而非返回错误 | false |
类型
SDK 包含所有 API 类型的 TypeScript 定义。你可以直接导入它们：
import type { Session, Message, Part } from "@opencode-ai/sdk"所有类型均根据服务器的 OpenAPI 规范生成，可在类型文件中查看。
错误处理
SDK 可能会抛出错误，你可以捕获并处理这些错误：
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。
基本用法
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 outputconsole.log(result.data.info.structured_output)// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }输出格式类型
| 类型 | 描述 |
|---|---|
text | 默认值。标准文本响应（无结构化输出） |
json_schema | 返回符合所提供 Schema 的经过验证的 JSON |
JSON Schema 格式
使用 type: 'json_schema' 时，需提供以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
type | 'json_schema' | 必填。指定 JSON Schema 模式 |
schema | object | 必填。定义输出结构的 JSON Schema 对象 |
retryCount | number | 可选。验证重试次数（默认值：2） |
错误处理
如果模型在所有重试后仍无法生成有效的结构化输出，响应中会包含 StructuredOutputError：
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)}最佳实践
- 在 Schema 属性中提供清晰的描述，帮助模型理解需要提取的数据
- 使用
required指定哪些字段必须存在 - 保持 Schema 简洁 — 复杂的嵌套 Schema 可能会让模型更难正确填充
- 设置合适的
retryCount— 对于复杂 Schema 可增加重试次数，对于简单 Schema 可减少
API
SDK 通过类型安全的客户端暴露所有服务器 API。
Global
| 方法 | 描述 | 响应 |
|---|---|---|
global.health() | 检查服务器健康状态和版本 | { healthy: true, version: string } |
示例
const health = await client.global.health()console.log(health.data.version)App
| 方法 | 描述 | 响应 |
|---|---|---|
app.log() | 写入一条日志 | boolean |
app.agents() | 列出所有可用的代理 | Agent[] |
示例
// Write a log entryawait client.app.log({ body: { service: "my-app", level: "info", message: "Operation completed", },})
// List available agentsconst agents = await client.app.agents()Project
示例
// List all projectsconst projects = await client.project.list()
// Get current projectconst currentProject = await client.project.current()Path
| 方法 | 描述 | 响应 |
|---|---|---|
path.get() | 获取当前路径 | Path |
示例
// Get current path informationconst pathInfo = await client.path.get()Config
| 方法 | 描述 | 响应 |
|---|---|---|
config.get() | 获取配置信息 | Config |
config.providers() | 列出提供商和默认模型 | { providers: Provider[], default: { [key: string]: string } } |
示例
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()Sessions
| 方法 | 描述 | 备注 |
|---|---|---|
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 |
示例
// Create and manage sessionsconst session = await client.session.create({ body: { title: "My session" },})
const sessions = await client.session.list()
// Send a prompt messageconst result = await client.session.prompt({ path: { id: session.id }, body: { model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" }, 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." }], },})Files
| 方法 | 描述 | 响应 |
|---|---|---|
find.text({ query }) | 搜索文件中的文本 | 包含 path、lines、line_number、absolute_offset、submatches 的匹配对象数组 |
find.files({ query }) | 按名称查找文件和目录 | string[]（路径） |
find.symbols({ query }) | 查找工作区符号 | Symbol[] |
file.read({ query }) | 读取文件 | { type: "raw" or "patch", content: string } |
file.status({ query? }) | 获取已跟踪文件的状态 | File[] |
find.files 支持以下可选查询字段：
type："file"或"directory"directory：覆盖搜索的项目根目录limit：最大结果数（1–200）
示例
// Search and read filesconst 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
| 方法 | 描述 | 响应 |
|---|---|---|
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 |
示例
// Control TUI interfaceawait client.tui.appendPrompt({ body: { text: "Add this to prompt" },})
await client.tui.showToast({ body: { message: "Task completed", variant: "success" },})Auth
| 方法 | 描述 | 响应 |
|---|---|---|
auth.set({ ... }) | 设置认证凭据 | boolean |
示例
await client.auth.set({ path: { id: "anthropic" }, body: { type: "api", key: "your-api-key" },})Events
| 方法 | 描述 | 响应 |
|---|---|---|
event.subscribe() | 服务器发送的事件流 | 服务器发送的事件流 |
示例
// Listen to real-time eventsconst events = await client.event.subscribe()for await (const event of events.stream) { console.log("Event:", event.type, event.properties)}© Anomaly
最近更新： 2026年5月1日