服务器 Server

opencode serve 命令会启动的一个无头 HTTP 服务，暴露 opencode 客户端可以使用的 OpenAPI 端点。

---

用法 Usage

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

选项 Options

标志 Flag	描述 Description	默认值 Default
--port	监听的端口	4096
--hostname	监听的主机名	127.0.0.1
--mdns	启用 mDNS 发现	false
--cors	允许的其他浏览器源	[]

--cors 可以传递多次：

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

---

认证 Authentication

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

OPENCODE_SERVER_PASSWORD=your-password opencode serve

---

工作原理 How it works

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

提示

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

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

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

---

连接到现有服务器 Connect to an existing server

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

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

---

规范 Spec

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

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

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

---

API APIs

opencode 服务器暴露以下 API。

---

Global (全局)

方法 Method	路径 Path	描述 Description	响应 Response
GET	/global/health	获取服务器健康状况和版本	{ healthy: true, version: string }
GET	/global/event	获取全局事件 (SSE 流)	Event stream

---

Project (项目)

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

---

Path & VCS (路径 & 版本控制)

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

---

Instance (实例)

方法 Method	路径 Path	描述 Description	响应 Response
POST	/instance/dispose	销毁当前实例	boolean

---

Config (配置)

方法 Method	路径 Path	描述 Description	响应 Response
GET	/config	获取配置信息	Config
PATCH	/config	更新配置	Config
GET	/config/providers	列出提供商和默认模型	{ providers: Provider[], default: { [key: string]: string } }

---

Provider (提供商)

方法 Method	路径 Path	描述 Description	响应 Response
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

---

Sessions (会话)

方法 Method	路径 Path	描述 Description	备注 Notes
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

---

Messages (消息)

方法 Method	路径 Path	描述 Description	备注 Notes
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: same as /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[]}

---

Commands (命令)

方法 Method	路径 Path	描述 Description	响应 Response
GET	/command	列出所有命令	Command[]

---

Files (文件)

方法 Method	路径 Path	描述 Description	响应 Response
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 parameters

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

---

Tools (Experimental) (工具 - 实验性)

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

---

LSP, Formatters & MCP

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

---

Agents (智能体)

方法 Method	路径 Path	描述 Description	响应 Response
GET	/agent	列出所有可用智能体	Agent[]

---

Logging (日志)

方法 Method	路径 Path	描述 Description	响应 Response
POST	/log	写入日志条目。Body: { service, level, message, extra? }	boolean

---

TUI

方法 Method	路径 Path	描述 Description	响应 Response
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	等待下一个控制请求	Control request object
POST	/tui/control/response	响应控制请求 ({ body })	boolean

---

Auth (认证)

方法 Method	路径 Path	描述 Description	响应 Response
PUT	/auth/:id	设置认证凭据。Body 必须匹配提供商架构	boolean

---

Events (事件)

方法 Method	路径 Path	描述 Description	响应 Response
GET	/event	服务器发送事件流。第一个事件是 server.connected，然后是总线事件	Server-sent events stream

---

Docs (文档)

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