OpenCode 中文教程

Appearance

5.9b HTTP API 参考 ​

💡 一句话总结：OpenCode 服务器提供完整的 REST API，支持编程方式与 OpenCode 交互。

📝 课程笔记 ​

本课核心知识点整理：

5.9b HTTP API 参考学霸笔记

学完你能做什么 ​

  • 理解 OpenCode API 的整体结构
  • 使用 API 管理会话和消息
  • 通过 API 执行命令和操作文件
  • 监听 SSE 事件流

API 概览 ​

OpenCode 服务器发布 OpenAPI 3.1 规范，可在以下地址查看交互式文档：

http://<hostname>:<port>/doc

例如：http://localhost:4096/doc

全局 API ​

/global ​

方法路径描述响应
GET/global/health服务器健康状态{ healthy: true, version: string }
GET/global/event全局事件流（SSE）Event stream

示例：

bash
# 检查服务器健康状态
curl http://localhost:4096/global/health

响应：

json
{
  "healthy": true,
  "version": "1.0.48"
}

来源：opencode/packages/opencode/src/server/server.ts:131-150

项目 API ​

/project ​

方法路径描述响应
GET/project列出所有项目Project[]
GET/project/current获取当前项目Project

来源：opencode/packages/web/src/content/docs/server.mdx:88-94

路径与版本控制 API ​

/path, /vcs ​

方法路径描述响应
GET/path获取当前路径Path
GET/vcs获取当前项目的 VCS 信息VcsInfo

来源：opencode/packages/web/src/content/docs/server.mdx:97-103

实例 API ​

/instance ​

方法路径描述响应
POST/instance/dispose销毁当前实例boolean

来源：opencode/packages/web/src/content/docs/server.mdx:106-111

配置 API ​

/config ​

方法路径描述响应
GET/config获取配置信息Config
PATCH/config更新配置Config
GET/config/providers列出提供商和默认模型{ providers: Provider[], default: Record<string, string> }

来源：opencode/packages/web/src/content/docs/server.mdx:114-121

提供商 API ​

/provider ​

方法路径描述响应
GET/provider列出所有提供商{ all: Provider[], default: {...}, connected: string[] }
GET/provider/auth获取提供商认证方式{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorize发起 OAuth 授权ProviderAuthAuthorization
POST/provider/{id}/oauth/callback处理 OAuth 回调boolean

来源：opencode/packages/web/src/content/docs/server.mdx:124-132

会话 API ​

/session ​

这是最常用的 API，用于管理对话会话。

方法路径描述备注
GET/session列出所有会话返回 Session[]
POST/session创建新会话body: { parentID?, title? }
GET/session/status获取所有会话状态{ [sessionID: string]: SessionStatus }
GET/session/:id获取会话详情返回 Session
DELETE/session/:id删除会话及其数据返回 boolean
PATCH/session/:id更新会话属性body: { title? }
GET/session/:id/children获取子会话返回 Session[]
GET/session/:id/todo获取会话的待办列表返回 Todo[]
POST/session/:id/init分析应用并创建 AGENTS.mdbody: { messageID, providerID, modelID }
POST/session/:id/fork从指定消息分叉会话body: { messageID? }
POST/session/:id/abort中止运行中的会话返回 boolean
POST/session/:id/share分享会话返回 Session
DELETE/session/:id/share取消分享返回 Session
GET/session/:id/diff获取会话的文件差异query: messageID?
POST/session/:id/summarize总结会话body: { providerID, modelID }
POST/session/:id/revert还原消息body: { messageID, partID? }
POST/session/:id/unrevert恢复所有已还原的消息返回 boolean
POST/session/:id/permissions/:permissionID响应权限请求body: { response, remember? }

来源：opencode/packages/web/src/content/docs/server.mdx:135-157

示例 - 创建新会话：

bash
curl -X POST http://localhost:4096/session \
  -H "Content-Type: application/json" \
  -d '{"title": "代码审查会话"}'

消息 API ​

/session/:id/message ​

方法路径描述备注
GET/session/:id/message列出消息query: limit?
POST/session/:id/message发送消息并等待响应body 见下方
GET/session/:id/message/:messageID获取消息详情返回 { info, parts }
POST/session/:id/prompt_async异步发送消息（不等待）返回 204 No Content
POST/session/:id/command执行斜杠命令body: { command, arguments, ... }
POST/session/:id/shell运行 shell 命令body: { agent, model?, command }

发送消息的请求体 ​

typescript
{
  messageID?: string,     // 可选，消息 ID
  model?: string,         // 可选，指定模型
  agent?: string,         // 可选，指定 agent
  noReply?: boolean,      // 可选，不等待回复
  system?: string,        // 可选，系统提示
  tools?: string[],       // 可选，启用的工具
  parts: Part[]           // 消息内容
}

来源：opencode/packages/web/src/content/docs/server.mdx:160-170

示例 - 发送消息：

bash
curl -X POST http://localhost:4096/session/abc123/message \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {"type": "text", "text": "解释这段代码的作用"}
    ]
  }'

命令 API ​

/command ​

方法路径描述响应
GET/command列出所有命令Command[]

来源：opencode/packages/web/src/content/docs/server.mdx:173-178

文件 API ​

/find, /file ​

方法路径描述响应
GET/find?pattern=<pat>搜索文件内容匹配结果数组
GET/find/file?query=<q>按名称查找文件string[]（路径）
GET/find/symbol?query=<q>查找工作区符号Symbol[]
GET/file?path=<path>列出目录内容FileNode[]
GET/file/content?path=<p>读取文件内容FileContent
GET/file/status获取已跟踪文件的状态File[]

/find/file 查询参数 ​

参数必需描述
query是搜索字符串（模糊匹配）
type否限制为 "file" 或 "directory"
directory否覆盖项目根目录
limit否最大结果数（1-200）
dirs否旧参数，"false" 只返回文件

来源：opencode/packages/web/src/content/docs/server.mdx:181-199

示例 - 搜索文件：

bash
# 搜索文件名包含 "config" 的文件
curl "http://localhost:4096/find/file?query=config&limit=10"

# 搜索文件内容
curl "http://localhost:4096/find?pattern=TODO"

工具 API（实验性） ​

/experimental/tool ​

方法路径描述响应
GET/experimental/tool/ids列出所有工具 IDToolIDs
GET/experimental/tool?provider=<p>&model=<m>获取模型可用的工具及 JSON SchemaToolList

来源：opencode/packages/web/src/content/docs/server.mdx:202-208

LSP、格式化器与 MCP API ​

/lsp, /formatter, /mcp ​

方法路径描述响应
GET/lsp获取 LSP 服务器状态LSPStatus[]
GET/formatter获取格式化器状态FormatterStatus[]
GET/mcp获取 MCP 服务器状态{ [name: string]: MCPStatus }
POST/mcp动态添加 MCP 服务器body: { name, config }
POST/mcp/:name/auth启动 MCP OAuth 认证{ authorizationUrl: string }
POST/mcp/:name/auth/callback处理 MCP OAuth 回调boolean

来源：opencode/packages/web/src/content/docs/server.mdx:211-218, server.ts:2197-2230

Agent API ​

/agent ​

方法路径描述响应
GET/agent列出所有可用 agentAgent[]

来源：opencode/packages/web/src/content/docs/server.mdx:222-227

日志 API ​

/log ​

方法路径描述响应
POST/log写入日志条目boolean

请求体：

typescript
{
  service: string,           // 服务名称
  level: "debug" | "info" | "warn" | "error",
  message: string,           // 日志消息
  extra?: Record<string, any> // 附加元数据
}

来源：opencode/packages/web/src/content/docs/server.mdx:230-235

TUI 控制 API ​

/tui ​

用于远程控制 TUI 界面，IDE 插件主要使用这些接口。

方法路径描述响应
POST/tui/append-prompt向提示框追加文本boolean
POST/tui/open-help打开帮助对话框boolean
POST/tui/open-sessions打开会话选择器boolean
POST/tui/open-themes打开主题选择器boolean
POST/tui/open-models打开模型选择器boolean
POST/tui/submit-prompt提交当前提示boolean
POST/tui/clear-prompt清空提示框boolean
POST/tui/execute-command执行命令body: { command }
POST/tui/show-toast显示提示通知body: { title?, message, variant }
GET/tui/control/next等待下一个控制请求Control request object
POST/tui/control/response响应控制请求body: { body }

来源：opencode/packages/web/src/content/docs/server.mdx:238-253

示例 - 远程控制 TUI：

bash
# 向提示框添加文本
curl -X POST http://localhost:4096/tui/append-prompt \
  -H "Content-Type: application/json" \
  -d '{"text": "请帮我审查这段代码"}'

# 提交提示
curl -X POST http://localhost:4096/tui/submit-prompt

# 显示通知
curl -X POST http://localhost:4096/tui/show-toast \
  -H "Content-Type: application/json" \
  -d '{"message": "操作完成", "variant": "success"}'

认证 API ​

/auth ​

方法路径描述响应
PUT/auth/:id设置认证凭据boolean

请求体必须匹配对应提供商的 schema。

来源：opencode/packages/web/src/content/docs/server.mdx:256-261

事件流 API ​

/event ​

方法路径描述响应
GET/eventSSE 事件流Server-sent events

连接后，首先收到 server.connected 事件，之后是各种总线事件。

来源：opencode/packages/web/src/content/docs/server.mdx:264-269

示例 - 监听事件：

bash
curl -N http://localhost:4096/event

输出示例：

event: server.connected
data: {}

event: session.created
data: {"id":"abc123","title":"新会话"}

event: message.created
data: {"sessionID":"abc123","content":"..."}

API 文档 ​

/doc ​

方法路径描述响应
GET/docOpenAPI 3.1 规范文档HTML 页面

来源：opencode/packages/web/src/content/docs/server.mdx:272-277

类型定义 ​

完整的 TypeScript 类型定义可在 SDK 中查看：

https://github.com/opencode-ai/opencode/blob/dev/packages/sdk/js/src/gen/types.gen.ts

常用类型：

  • Session - 会话信息
  • Message - 消息信息
  • Part - 消息内容部分
  • Provider - 提供商信息
  • Agent - Agent 信息
  • Config - 配置信息

踩坑提醒 ​

现象原因解决
请求返回 CORS 错误客户端来源未在白名单启动时添加 --cors <origin>
消息发送后无响应使用了 prompt_async改用 /session/:id/message 同步接口
SSE 连接频繁断开网络超时或代理问题检查代理设置，增加超时时间
404 错误会话或消息 ID 不存在先通过 GET 接口确认资源存在
实验性 API 不可用功能可能变更或移除查看最新文档确认

本课小结 ​

你学会了：

  1. API 结构：19 个 API 分类，覆盖会话、消息、文件、工具等
  2. 会话管理：创建、查询、分叉、分享会话
  3. 消息交互：同步/异步发送消息，执行命令
  4. 文件操作：搜索、读取、列出文件
  5. TUI 控制：远程操控 TUI 界面
  6. 事件监听：通过 SSE 接收实时事件

相关资源 ​

下一课预告 ​

下一课我们将学习如何使用 SDK 进行开发。