当你已经摸透了 OpenCode 的基础玩法，肯定在想：能不能把它塞进我自己的工具链？或者加点自定义功能？好消息是，OpenCode 给你准备了三套「进阶装备」——类型安全的 JavaScript SDK、HTTP 服务器 API，还有灵活的插件系统。接下来咱们就一起逛逛这三层接口，看看怎么玩转它们。
SDK：类型安全的 JS 客户端
SDK 是 OpenCode 的「遥控器」，用 TypeScript 写的，类型安全又省心。装起来也简单：
npm install @opencode-ai/sdk
初始化方式
SDK 有两种启动姿势。第一种是「全家桶模式」，一键启动服务器+客户端：
import { createOpencode } from "@opencode-ai/sdk"
const { client, server } = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-3-5-sonnet-20241022",
},
})
console.log(`Server running at ${server.url}`)
如果你已经跑着一个 OpenCode 实例，也可以只开个客户端连上去：
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})
结构化输出
想让 AI 按固定格式吐数据？SDK 支持 JSON Schema 约束输出，妈妈再也不用担心我解析字符串了：
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"],
},
},
},
})
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
要是模型不听话输出格式不对，StructuredOutputError 会跳出来提醒你，这时候改改提示词或者重试就行。
核心 API 概览
SDK 的类型是从服务器的 OpenAPI 规范自动生成的，靠谱！主要模块有这些：
- Global: 健康检查 (
client.global.health()) - App: 日志记录 (
client.app.log()) 和代理列表 (client.app.agents()) - Project: 项目列表与当前项目信息
- Session: 会话的 CRUD、消息发送、提示词注入、撤销/重做
- Files: 文本搜索、文件查找、符号搜索、文件读取
- TUI: 控制终端界面（追加提示词、打开面板、显示通知等）
- Events: 实时事件订阅 (
client.event.subscribe())
所有类型定义都可以在 SDK 的类型文件中查看。
服务器 API：HTTP 接口全览
OpenCode 服务器走 HTTP 协议，啥语言都能跟它聊。用 opencode serve 就能启动：
opencode serve --port 4096 --hostname 127.0.0.1 --cors http://localhost:5173
安全认证
正经环境记得加个密码，别让人随便蹭你的 API：
OPENCODE_SERVER_PASSWORD=your-password OPENCODE_SERVER_USERNAME=admin opencode serve
API 端点分类
服务器的 API 和 SDK 方法一一对应，来认个门：
项目管理: GET /project, GET /project/current
会话操作: POST /session, GET /session/:id, POST /session/:id/prompt
消息处理: GET /session/:id/message, POST /session/:id/command, POST /session/:id/shell
文件系统: GET /find?pattern=, GET /file?path=, GET /file/content?path=
LSP/MCP/格式化器: GET /lsp, GET /mcp, GET /formatter
TUI 控制: POST /tui/append-prompt, POST /tui/show-toast, POST /tui/execute-command
完整的 OpenAPI 3.1 规范可在 http://<hostname>:<port>/doc 查看，也可直接导入 Swagger UI 进行测试。
有趣的是，TUI 自己也是服务器的客户端。通过 /tui 端点，你能往输入框塞内容或者执行命令——OpenCode 的 IDE 插件就是这么干的。
插件开发：给 OpenCode 加点料
想让 OpenCode 按你的想法行事？插件就是最佳切入点。你可以拦截事件、改行为、加工具，甚至替换内部逻辑。
插件放哪儿
有两种方式加载插件。本地文件直接丢进插件目录：
.opencode/plugins/—— 项目级插件~/.config/opencode/plugins/—— 全局插件
npm 插件则在配置文件中声明：
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-helicone-session", "opencode-wakatime"]
}
npm 插件启动时会自动 bun install 到 ~/.cache/opencode/node_modules/，不用你操心。
加载顺序记住这个口诀：先全局配置，后项目配置；先全局插件，后项目插件。
插件基本结构
插件其实就是一个导出了异步函数的 JS/TS 文件。函数接收上下文，返回一堆钩子：
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
console.log("Plugin initialized!")
return {
// 钩子实现
}
}
上下文对象里都有啥：
- project: 当前项目信息
- directory: 你在哪个目录干活
- worktree: Git 工作树路径
- client: SDK 客户端，可以直接调服务器 API
- $: Bun 的 Shell API，想执行啥命令都行
用 TypeScript 的话，类型定义可以从 @opencode-ai/plugin import：
import type { Plugin } from "@opencode-ai/plugin"
export const MyPlugin: Plugin = async (ctx) => { /* ... */ }
事件系统
插件靠事件钩子来「插手」OpenCode 的各种环节。常用事件有这些：
会话事件: session.created, session.updated, session.idle, session.error
消息事件: message.updated, message.part.removed
工具事件: tool.execute.before, tool.execute.after
文件事件: file.edited, file.watcher.updated
权限事件: permission.asked, permission.replied
LSP 事件: lsp.client.diagnostics, lsp.updated
TUI 事件: tui.prompt.append, tui.toast.show, tui.command.execute
Shell 事件: shell.env
所有钩子都是异步的，拿到 input 和 output 对象，改 output 就能影响后续行为。
插件实战示例
安全与通知类
不想让 AI 偷看你的 .env 文件？几行代码搞定：
export const EnvProtection = async () => {
return {
"tool.execute.before": async (input, output) => {
if (input.tool === "read" && output.args.filePath.includes(".env")) {
throw new Error("Do not read .env files")
}
},
}
}
长任务跑完了，让它弹个通知：
export const NotificationPlugin = async ({ $ }) => {
return {
event: async ({ event }) => {
if (event.type === "session.idle") {
await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
}
},
}
}
工具扩展类
想让 AI 用你的专属工具？自己造一个：
import { type Plugin, tool } from "@opencode-ai/plugin"
export const CustomToolsPlugin: Plugin = async (ctx) => {
return {
tool: {
mytool: tool({
description: "This is a custom tool",
args: {
foo: tool.schema.string(),
},
async execute(args, context) {
const { directory, worktree } = context
return `Hello ${args.foo} from ${directory}`
},
}),
},
}
}
工具用 Zod schema 校验参数，execute 函数里能拿到上下文。
会话控制类
会话压缩时想塞点自己的上下文？这样搞：
import type { Plugin } from "@opencode-ai/plugin"
export const CompactionPlugin: Plugin = async (ctx) => {
return {
"experimental.session.compacting": async (input, output) => {
output.context.push(`## Custom Context
- Current task status
- Important decisions made
- Files being actively worked on`)
},
}
}
想完全接管压缩提示词？设置 output.prompt 就行，这时候 output.context 会被忽略。
生态系统与社区资源
OpenCode 的社区越来越热闹，已经有 30 多个插件，覆盖各种奇葩需求：
可观测性: Helicone Session（追踪成本）、Wakatime（编码时长统计）、Sentry Monitor（错误追踪）
认证扩展: Gemini Auth、OpenAI Codex Auth、Antigravity Auth
开发工具: DevContainers、Dynamic Context Pruning、PTY 支持
集成增强: Supermemory（记忆持久化）、Scheduler（任务调度）、Background Agents
除插件外，社区还开发了多个集成项目：
- opencode.nvim: Neovim 插件，在编辑器内直接使用 OpenCode
- OpenWork: 基于 OpenCode 的工作流自动化平台
- OpenChamber: 多代理协作框架
- ocx: 命令行增强工具
这些轮子大大降低了造新轮子的难度。完整清单可以去生态系统页面翻翻看。
总结
总结一下：SDK 适合在 Node.js/TypeScript 项目里直接调用；服务器 API 让任何语言都能接入；插件系统让你深度定制 OpenCode 的行为。
不管你是想做 IDE 插件、自动化流水线，还是搞个自己的 AI 编码助手，这三件套都能给你撑腰。建议先从 SDK 玩起，慢慢摸索服务器 API 和插件开发，玩得开心！