服务器

通过 HTTP 与 opencode 服务器交互。

opencode serve 命令运行一个无头 HTTP 服务器，暴露一个 OpenAPI 端点供 opencode 客户端使用。

使用方法

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

选项

标志	描述	默认值
`--port`	监听端口	`4096`
`--hostname`	监听主机名	`127.0.0.1`
`--mdns`	启用 mDNS 发现	`false`
`--mdns-domain`	mDNS 服务的自定义域名	`opencode.local`
`--cors`	允许的额外浏览器来源	`[]`

--cors 可以多次传递：

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

身份验证

设置 OPENCODE_SERVER_PASSWORD 以使用 HTTP 基本认证保护服务器。用户名默认为 opencode，或设置 OPENCODE_SERVER_USERNAME 来覆盖它。这适用于 opencode serve 和 opencode web。

OPENCODE_SERVER_PASSWORD=your-password opencode serve

工作原理

当你运行 opencode 时，它会启动一个 TUI 和一个服务器。TUI 是与服务器通信的客户端。服务器暴露一个 OpenAPI 3.1 规范端点。这个端点也用于生成 SDK。

提示： 使用 opencode 服务器以编程方式与 opencode 交互。

这种架构让 opencode 支持多个客户端，并允许你以编程方式与 opencode 交互。

你可以运行 opencode serve 来启动一个独立服务器。如果你已经运行了 opencode TUI，opencode serve 将启动一个新服务器。

连接到现有服务器

当你启动 TUI 时，它会随机分配端口和主机名。你可以改为传入 --hostname 和 --port 标志。然后使用它来连接到其服务器。

/tui 端点可用于通过服务器驱动 TUI。例如，你可以预填或运行提示。这种设置被 OpenCode IDE 插件使用。

规范

服务器发布一个 OpenAPI 3.1 规范，可以在以下地址查看：

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

例如，http://localhost:4096/doc。使用该规范生成客户端或检查请求和响应类型。或在 Swagger 浏览器中查看。

API

opencode 服务器暴露以下 API。

全局

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

项目

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

路径和版本控制

方法	路径	描述	响应
`GET`	`/path`	获取当前路径	`Path`
`GET`	`/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`

会话

方法	路径	描述	备注
`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.md`	body: `{ 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`	获取此会话的差异	query: `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`

消息

方法	路径	描述	备注
`GET`	`/session/:id/message`	列出会话中的消息	query: `limit?`，返回 `{ info: Message, parts: Part[] }[]`
`POST`	`/session/:id/message`	发送消息并等待响应	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，返回 `{ info: Message, parts: Part[] }`
`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: Message, parts: Part[] }`
`POST`	`/session/:id/shell`	运行 shell 命令	body: `{ agent, model?, command }`，返回 `{ info: Message, parts: Part[] }`

命令

方法	路径	描述	响应
`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=<p>`	读取文件	`FileContent`
`GET`	`/file/status`	获取已跟踪文件的状态	`File[]`

`/find/file` 查询参数

query（必需）— 搜索字符串（模糊匹配）
type（可选）— 将结果限制为 "file" 或 "directory"
directory（可选）— 覆盖搜索的项目根目录
limit（可选）— 最大结果数（1–200）
dirs（可选）— 旧版标志（"false" 仅返回文件）

工具（实验性）

方法	路径	描述	响应
`GET`	`/experimental/tool/ids`	列出所有工具 ID	`ToolIDs`
`GET`	`/experimental/tool?provider=<p>&model=<m>`	列出带有模型 JSON 模式的工具	`ToolList`

LSP、格式化器和 MCP

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

代理

方法	路径	描述	响应
`GET`	`/agent`	列出所有可用代理	`Agent[]`

日志

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

认证

方法	路径	描述	响应
`PUT`	`/auth/:id`	设置认证凭据。Body 必须匹配提供商模式	`boolean`

事件

方法	路径	描述	响应
`GET`	`/event`	服务器发送事件流。第一个事件是 `server.connected`，然后是总线事件	服务器发送事件流

文档

方法	路径	描述	响应
`GET`	`/doc`	OpenAPI 3.1 规范	包含 OpenAPI 规范的 HTML 页面

SDK 插件

服务器