服务器

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

---

路径和 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

---

会话

方法	路径	描述	说明
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	显示提示消息（{ title?, message, variant }）	boolean
GET	/tui/control/next	等待下一个控制请求	控制请求对象
POST	/tui/control/response	响应控制请求（{ body }）	boolean

---

认证

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

---

事件

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

---

文档

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