伺服器

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 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 規範 端點。該端點還用於生成軟件開發工具包。

提示

使用 opencode 服務器以編程方式與 opencode 進行交互。

此架構讓 opencode 支持多個客戶端，並允許您以編程方式與 opencode 進行交互。

您可以運行 opencode serve 來啟動獨立服務器。如果您有 opencode TUI 運行，opencode serve 將啟動一個新服務器。

---

連接到現有服務器

當您啟動 TUI 時，它會隨機分配端口和主機名。您可以改為傳入--hostname 和--port 旗幟。然後使用它連接到其服務器。

/tui 端點可用於通過服務器驅動 TUI。例如，您可以預填充或運行提示。此設置由 opencode 集成開發環境 插件使用。

---

規格

服務器發布了 OpenAPI 3.1 規範，可以在以下位置查看：

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

例如，http://localhost:4096/doc。使用規範生成客戶端或檢查請求和響應類型。或者在 Swagger 瀏覽器中查看它。

---

蜜蜂

opencode 服務器公開以下 API。

---

全球的

方法	路徑	描述	回應
GET	/global/health	獲取服務器運行狀況和版本	{ healthy: true, version: string }
GET	/global/event	獲取全局事件（SSE 流）	事件流

---

專案

方法	路徑	描述	回應
GET	/project	列出所有項目	項目[]
GET	/project/current	獲取當前項目	項目

---

路徑和VCS

方法	路徑	描述	回應
GET	/path	獲取當前路徑	路徑
GET	/vcs	獲取當前項目的 VCS 信息	VcsInfo

---

實例

方法	路徑	描述	回應
POST	/instance/dispose	處置當前實例	boolean

---

配置

方法	路徑	描述	回應
GET	/config	獲取配置信息	配置
PATCH	/config	更新配置	配置
GET	/config/providers	列出提供商和默認模型	{ providers: 提供商[], default: { [key: string]: string } }

---

提供者

方法	路徑	描述	回應
GET	/provider	列出所有提供商	{ all: 提供商[], 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: 消息, parts: Part[]}[]
POST	/session/:id/message	發送消息並等待回复	主體：{ messageID?, model?, agent?, noReply?, system?, tools?, parts }，返回{ info: 消息, parts: 部分[]}
GET	/session/:id/message/:messageID	獲取消息詳情	返回{ info: 消息, parts: 部分[]}
POST	/session/:id/prompt_async	異步發送消息（無需等待）	body：與/session/:id/message相同，返回204 No Content
POST	/session/:id/command	執行斜杠命令	主體：{ messageID?, agent?, model?, command, arguments }，返回{ info: 消息, parts: 部分[]}
POST	/session/:id/shell	運行 shell 命令	主體：{ agent, model?, command }，返回{ info: 消息, parts: 部分[]}

---

命令

方法	路徑	描述	回應
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	ToolID
GET	/experimental/tool?provider=<p>&model=<m>	列出具有模型 JSON 架構的工具	工具列表

---

LSP、格式化程序和 MCP

方法	路徑	描述	回應
GET	/lsp	獲取LSP服務器狀態	LSPStatus[]
GET	/formatter	獲取格式化程序狀態	FormatterStatus[]
GET	/mcp	獲取 MCP 服務器狀態	{ [name: string]: MCPStatus }
POST	/mcp	動態添加MCP服務器	body: { name, config }, 返回 MCP 狀態對象

---

Agents

方法	路徑	描述	回應
GET	/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 頁面