伺服器

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 頁面