跳转到内容
OpenCode
HomeDocs

服务端

通过 HTTP 与 OpenCode Server 交互。

opencode serve 命令会运行一个无头（headless）HTTP 服务，暴露一个 OpenAPI 接口，供 OpenCode 客户端调用。

用法

Terminal window
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

选项

参数说明默认值
--port监听端口4096
--hostname监听主机名127.0.0.1
--mdns启用 mDNS 服务发现false
--cors允许的额外浏览器来源（CORS Origin）[]

--cors 可以传多次：

Terminal window
opencode serve --cors http://localhost:5173 --cors https://app.example.com

工作原理

当你运行 opencode 时，它会同时启动一个 TUI 客户端和一个服务端；TUI 是客户端，通过 HTTP 和服务端通信。服务端暴露一个 OpenAPI 3.1 规范接口，这个接口也用于生成 SDK。

这种架构使得 OpenCode 能同时支持多个客户端，并允许你通过代码与 OpenCode 交互。

你可以单独运行 opencode serve 来启动一个独立的服务。如果 TUI 已经在运行，额外运行 opencode serve 会启动一个新的 Server 实例。

连接到已有服务

默认情况下，启动 TUI 时会随机分配端口和主机名。你也可以通过 CLI 的 --hostname 和 --port 参数来固定它们，然后使用这些信息连接到同一个服务端。

/tui 接口可以用来通过 Server 远程驱动 TUI，例如预填 Prompt 或直接触发执行。这也是 OpenCode IDE 插件 所使用的方式。

规格说明

Server 会发布一个 OpenAPI 3.1 规范，可以通过下面地址查看：

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

例如：http://localhost:4096/doc。你可以使用该规范自动生成客户端、查看请求/响应类型，或在 Swagger 等工具中浏览。

接口概览

OpenCode Server 暴露的主要 HTTP 接口如下。

全局

方法路径说明返回值
GET/global/health获取服务健康状态和版本信息{ healthy: true, version: string }
GET/global/event获取全局事件（SSE 流）事件流（Server-Sent Events）

项目

方法路径说明返回值
GET/project列出所有项目Project[]
GET/project/current获取当前项目Project

路径 & VCS

方法路径说明返回值
GET/path获取当前路径Path
GET/vcs获取当前项目的 VCS 信息VcsInfo

实例

方法路径说明返回值
POST/instance/dispose销毁当前服务实例boolean

配置

方法路径说明返回值
GET/config获取当前配置Config
PATCH/config更新配置Config
GET/config/providers列出提供商及默认模型{ providers: Provider[], default: { [key: string]: string } }

提供商

方法路径说明返回值
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

会话（Sessions）

方法路径说明备注
GET/session列出所有会话返回 Session[]
POST/session创建新会话body: { parentID?, title? }，返回 Session
GET/session/status获取所有会话的状态返回 { [sessionID: string]: SessionStatus }
GET/session/:id获取指定会话详情返回 Session
DELETE/session/:id删除会话及其所有数据返回 boolean
PATCH/session/:id更新会话属性body: { title? }，返回 Session
GET/session/:id/children获取某会话的子会话返回 Session[]
GET/session/:id/todo获取会话对应的待办列表返回 Todo[]
POST/session/:id/init分析项目并创建 AGENTS.mdbody: { messageID, providerID, modelID }，返回 boolean
POST/session/:id/fork在某条消息处分叉会话body: { messageID? }，返回 Session
POST/session/:id/abort中止正在运行的会话返回 boolean
POST/session/:id/share分享会话返回 Session
DELETE/session/:id/share取消分享会话返回 Session
GET/session/:id/diff获取会话的文件 diffquery: messageID?，返回 FileDiff[]
POST/session/:id/summarize压缩/总结会话body: { providerID, modelID }，返回 boolean
POST/session/:id/revert撤销某条消息对应更改body: { messageID, partID? }，返回 boolean
POST/session/:id/unrevert恢复所有被撤销的消息返回 boolean
POST/session/:id/permissions/:permissionID对某条权限请求作出响应body: { response, remember? }，返回 boolean

消息（Messages）

方法路径说明备注
GET/session/:id/message列出会话中的所有消息query: limit?，返回 { info: Message, parts: Part[]}[]
POST/session/:id/message发送一条消息并等待完整回复body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }，返回 { info, parts }
GET/session/:id/message/:messageID获取单条消息详情返回 { info: Message, parts: Part[]}
POST/session/:id/prompt_async异步发送消息（不等待返回）body 同 /session/:id/message，返回 204 No Content
POST/session/:id/command执行斜杠命令body: { messageID?, agent?, model?, command, arguments }，返回 { info, parts }
POST/session/:id/shell运行 Shell 命令body: { agent, model?, command }，返回 { info, parts }

命令

方法路径说明返回值
GET/command列出全部可用命令Command[]

文件

方法路径说明返回值
GET/find?pattern=<pat>在文件中搜索文本包含 path、lines、line_number、absolute_offset、submatches 的匹配结果数组
GET/find/file?query=<q>按名称查找文件或目录string[]（路径列表）
GET/find/symbol?query=<q>搜索工作区符号Symbol[]
GET/file?path=<path>列出某路径下的文件和目录FileNode[]
GET/file/content?path=<path>读取文件内容FileContent
GET/file/status获取被跟踪文件的状态File[]

/find/file 的常用查询参数：

  • query（必填）：模糊搜索字符串
  • type（可选）：仅返回 "file" 或 "directory"
  • directory（可选）：覆盖默认项目根目录
  • limit（可选）：最大结果数量（1–200）
  • dirs（可选）：兼容旧用法（"false" 时只返回文件）

工具（实验性）

方法路径说明返回值
GET/experimental/tool/ids列出全部工具 IDToolIDs
GET/experimental/tool?provider=<p>&model=<m>列出某模型可用的工具及其 JSON SchemaToolList

LSP / 格式化器 / MCP

方法路径说明返回值
GET/lsp获取 LSP 服务状态LSPStatus[]
GET/formatter获取格式化器状态FormatterStatus[]
GET/mcp获取 MCP 服务器状态{ [name: string]: MCPStatus }
POST/mcp动态添加 MCP 服务器body: { name, config }，返回对应 MCP 状态对象

Agents

方法路径说明返回值
GET/agent列出所有可用的 AgentsAgent[]

日志

方法路径说明返回值
POST/log写日志，body: { service, level, message, extra? }boolean

TUI 控制

方法路径说明返回值
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提交当前 Promptboolean
POST/tui/clear-prompt清空 Promptboolean
POST/tui/execute-command执行命令（{ command }）boolean
POST/tui/show-toast显示 toast（{ title?, message, variant }）boolean
GET/tui/control/next等待下一条控制请求控制请求对象
POST/tui/control/response对控制请求进行响应（{ body }）boolean

认证

方法路径说明返回值
PUT/auth/:id设置认证凭据，body 需符合对应 provider 的 schemaboolean

事件流

方法路径说明返回值
GET/eventSSE 事件流。首条事件是 server.connected，之后是总线事件Server-Sent Events 事件流

文档

方法路径说明返回值
GET/docOpenAPI 3.1 规范页面带有 OpenAPI 文档的 HTML 页面