服务器

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

---

使用方法

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。

Tip

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

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

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

---

连接到现有服务器

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

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

---

规范

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

http://<主机名>:<端口>/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	获取当前项目的 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	创建新会话	请求体：{ 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 模式	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	设置认证凭据。请求体必须符合提供商的模式	boolean

---

事件

Method	Path	Description	Response
GET	/event	服务器发送事件流。第一个事件是 server.connected，然后是总线事件	服务器发送事件流

---

文档

Method	Path	Description	Response
GET	/doc	OpenAPI 3.1 规范	包含 OpenAPI 规范的 HTML 页面