服务器

通过 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`
`--cors`	允许的其他浏览器源	`[]`

--cors 可以多次传递：

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

工作原理

当你运行 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

例如，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>`	查找工作区符号 (symbols)	`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 服务器	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`	显示 Toast (`{ title?, message, variant }`)	`boolean`
`GET`	`/tui/control/next`	等待下一个控制请求	控制请求对象
`POST`	`/tui/control/response`	响应控制请求 (`{ body }`)	`boolean`

认证

方法	路径	描述	响应
`PUT`	`/auth/:id`	设置身份验证凭据。Body 必须符合提供商的 schema	`boolean`

事件

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

文档

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