服务器

通过 HTTP 与 opencode 服务器交互。

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

用法

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 https://: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 serve 来启动一个独立服务器。如果 opencode TUI 正在运行，opencode serve 将启动一个新服务器。

连接到现有服务器

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

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

规范

服务器发布了一个 OpenAPI 3.1 规范，可在以下位置查看：

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

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

API接口

opencode 服务器暴露以下 API。

全局

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

项目

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

路径 & 版本控制系统

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

实例

方法	路径	描述	响应
`POST`	`/instance/dispose`	处置当前实例	`boolean`

配置

方法	路径	描述	响应
`GET`	`/config`	获取配置信息	`配置`
`PATCH`	`/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`	创建新会话	请求体: `{ parentID?, title? }`, 返回 `Session`
`GET`	`/session/status`	获取所有会话的状态	返回 `{ [sessionID: string]:` SessionStatus `}`
`GET`	`/session/:id`	获取会话详情	返回 `Session`
`DELETE`	`/session/:id`	删除会话及其所有数据	返回 `boolean`
`PATCH`	`/session/:id`	更新会话属性	请求体: `{ title? }`, 返回 `Session`
`GET`	`/session/:id/children`	获取会话的子会话	返回 `Session[]`
`GET`	`/session/:id/todo`	获取会话的待办事项列表	返回 `Todo[]`
`POST`	`/session/:id/init`	分析应用并创建 `AGENTS.md`	请求体: `{ messageID, providerID, modelID }`, 返回 `boolean`
`POST`	`/session/:id/fork`	在消息处派生现有会话	请求体: `{ messageID? }`, 返回 `Session`
`POST`	`/session/:id/abort`	中止正在运行的会话	返回 `boolean`
`POST`	`/session/:id/share`	共享会话	返回 `Session`
`DELETE`	`/session/:id/share`	取消共享会话	返回 `Session`
`GET`	`/session/:id/diff`	获取此会话的差异	查询参数: `messageID?`, 返回 `FileDiff[]`
`POST`	`/session/:id/summarize`	总结会话	请求体: `{ providerID, modelID }`, 返回 `boolean`
`POST`	`/session/:id/revert`	回滚消息	请求体: `{ messageID, partID? }`, 返回 `boolean`
`POST`	`/session/:id/unrevert`	恢复所有已回滚的消息	返回 `boolean`
`POST`	`/session/:id/permissions/:permissionID`	响应权限请求	请求体: `{ response, remember? }`, 返回 `boolean`

消息

方法	路径	描述	备注
`GET`	`/session/:id/message`	列出会话中的消息	查询参数: `limit?`, 返回 `{ info:` Message`, parts:` Part[]`}[]`
`POST`	`/session/:id/message`	发送消息并等待响应	请求体: `{ 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`	异步发送消息（不等待）	请求体: 与 `/session/:id/message` 相同, 返回 `204 No Content`
`POST`	`/session/:id/command`	执行斜杠命令	请求体: `{ messageID?, agent?, model?, command, arguments }`, 返回 `{ info:` Message`, parts:` Part[]`}`
`POST`	`/session/:id/shell`	运行 shell 命令	请求体: `{ 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 Schema 工具	`ToolList`

LSP、格式化工具 & MCP

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

代理

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

日志记录

方法	路径	描述	响应
`POST`	`/log`	写入日志条目。请求体: `{ 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`	显示 Toast 通知 (`{ title?, message, variant }`)	`boolean`
`GET`	`/tui/control/next`	等待下一个控制请求	控制请求对象
`POST`	`/tui/control/response`	响应控制请求 (`{ body }`)	`boolean`

认证

方法	路径	描述	响应
`PUT`	`/auth/:id`	设置认证凭据。请求体必须与提供商 Schema 匹配	`boolean`

事件

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

文档

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