啟動伺服器
透過 HTTP 與 OpenCode server 互動，並理解 serve、web、TUI、SDK 和 OpenAPI 的關係。
opencode serve 會啟動一個無介面的 HTTP server。它暴露 OpenAPI 3.1 規範和一組 API，讓 TUI、SDK、IDE 外掛或你自己的系統可以透過 HTTP 與 OpenCode 互動。
這一篇用 12 分鐘換什麼：你會知道什麼時候需要 server、如何安全啟動、怎麼訪問 OpenAPI spec、哪些 API 分組最常用，以及為什麼不要把未認證 server 暴露到網路。
先給結論：server 是整合入口，不是第一上手入口
第一次用 OpenCode，先用 TUI 和 CLI。只有當你要把 OpenCode 接進其他客戶端、後臺服務、IDE 外掛或自動化系統時，才需要 server。
| 場景 | 優先入口 |
|---|---|
| 人在終端裡互動式寫程式碼 | opencode TUI |
| 指令碼里跑一次任務 | opencode run |
| 瀏覽器訪問 OpenCode | opencode web |
| 程式透過 HTTP 呼叫 OpenCode | opencode serve |
| JS/TS 程式型別安全呼叫 | SDK |
如果要把 server 繫結到區域網或公網地址，先配置 OPENCODE_SERVER_PASSWORD。未認證 server 會暴露專案上下文和工具能力。
OpenCode 的 server 架構
flowchart LR
TUI[TUI] --> Server[OpenCode server]
Web[Web / Desktop / IDE] --> Server
SDK[JS/TS SDK] --> Server
Custom[你的系統] --> Server
Server --> Project[專案檔案和會話]
Server --> Provider[模型 provider]
Server --> Tools[tools / MCP / LSP / formatter]
Server --> Spec[/doc OpenAPI 3.1]執行 opencode 時，TUI 本身也是一個 client，會和本地 server 通訊。opencode serve 則啟動一個獨立 server；如果 TUI 已經在執行，再執行 serve 會啟動一個新的 server。
啟動方式
最小啟動：
opencode serve常用引數：
--port：監聽埠，預設4096。--hostname：監聽主機名，預設127.0.0.1。--mdns：啟用 mDNS（multicast DNS，區域網內自動發現服務的協議，不依賴 DNS 伺服器）發現。--mdns-domain：自定義 mDNS 服務域名，預設opencode.local。--cors：額外允許的瀏覽器來源（CORS 即跨源資源共享，瀏覽器為防止惡意站點偷調你的 API 預設會攔截跨域請求；這裡寫白名單告訴 server 哪些前端域名是被信任的），可以傳多次。
允許多個 CORS 來源：
opencode serve --cors http://localhost:5173 --cors https://app.example.com認證必須先配
設定 HTTP Basic Auth：
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve預設使用者名稱是 opencode。需要改使用者名稱時：
export OPENCODE_SERVER_USERNAME="team-agent"
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve --hostname 0.0.0.0 --port 4096OPENCODE_SERVER_PASSWORD 同時適用於 opencode serve 和 opencode web。
--hostname 0.0.0.0 會讓其他機器訪問到這個 server。沒有認證、沒有網路邊界、沒有反向代理保護時不要這樣啟動。
OpenAPI spec 在哪裡
server 會發布 OpenAPI 3.1 規範：
http://<hostname>:<port>/doc本機預設是：
http://localhost:4096/doc這個頁面適合做三件事：
- 檢視當前 server 真實暴露的 endpoint。
- 檢查請求體和響應型別。
- 生成客戶端，或和官方 SDK 型別對照。
API 變動時，以當前 /doc 和官方 SDK 生成型別為準，不要長期依賴手抄 endpoint 表。
最小健康檢查
本地無認證時：
curl http://127.0.0.1:4096/global/health啟用認證後：
curl -u "opencode:$OPENCODE_SERVER_PASSWORD" http://127.0.0.1:4096/global/health健康介面返回 server 是否 healthy 和當前版本。它適合放在本地指令碼、容器健康檢查或整合測試的第一步。
常用 API 分組
不需要背完整 endpoint。先按分組理解：
- Global：
/global/health、/global/event，檢查 server 狀態和全域性事件流。 - Project / Path / VCS：讀取當前專案、路徑和版本控制資訊。
- Config / Provider / Auth：讀取或更新配置、列 provider、處理 OAuth 或 provider 憑據。
- Session：建立、讀取、刪除、fork、abort、share、diff、todo、permissions。
- Message：傳送 prompt、非同步傳送、執行 command、執行 shell。
- Files：查詢檔案、搜尋文本、讀取內容、檢視檔案狀態。
- Tools / LSP / Formatter / MCP：讀取工具、語言服務、格式化器和 MCP 狀態。
- TUI：追加 prompt、提交 prompt、開啟幫助、開啟模型選擇器、顯示 toast。
- Docs：
/doc，檢視 OpenAPI 3.1 規範。
其中最常用於自動化的是 Session、Message、Files 和 /global/health。
一條最小整合路徑
先不要一上來寫複雜客戶端。按這個順序驗證：
opencode serve能啟動。/global/health能返回 healthy。/doc能開啟。- 能列出當前專案或 session。
- 能建立一個 session。
- 能傳送一個只讀 message。
- 能讀取 diff 或結果。
- 能正確處理許可權請求、錯誤和 abort。
如果你用 JS/TS，下一步直接用 SDK。SDK 會複用 server 的 OpenAPI 型別，比手寫 fetch 更不容易錯。
TUI endpoint 怎麼理解
/tui/* endpoint 可以透過 server 驅動 TUI，比如追加 prompt、提交 prompt、開啟 help、開啟 session/model/theme 選擇器、顯示 toast。
這類能力適合 IDE 外掛或桌面整合，不適合普通指令碼濫用。普通指令碼更應該直接用 session/message API 或 CLI run。
安全邊界
server 能觸達專案檔案、會話、工具、provider 和模型。上線前至少確認：
- 是否啟用了 Basic Auth。
- 是否限制了 hostname、埠和網路訪問範圍。
- 是否只允許必要 CORS origin。
- 是否停用了不需要的分享、MCP 或高風險工具。
- 是否避免把 auth 資訊寫入程式碼儲存庫和日誌。
- 是否能在請求失敗時 abort session。
- 是否能在整合測試後清理臨時 session。
如果這些答不清，先不要把 OpenCode server 接進團隊後臺或公網服務。
新手常見坑
- TUI 還沒跑通就直接接 server，結果 provider、許可權、專案配置問題全混在一起。
- 繫結
0.0.0.0但沒設定OPENCODE_SERVER_PASSWORD。 - 前端調 server 時隨手放開
--cors "*", 沒有 origin 邊界。 - 手抄 endpoint 表，忘了以
/doc和 SDK 型別為準。 - 用
/tui/*做普通自動化，而不是用 session/message API。 - 沒有處理許可權請求、abort、錯誤重試和 session 清理。
接下來去哪
使用 SDK
JS/TS 整合優先用 SDK，避免手寫 HTTP 型別和請求體。
使用 CLI
只想指令碼化跑一次任務時，CLI run 通常比 server 更簡單。
排查故障
server 連線失敗、埠衝突、provider 錯誤時按排障頁定位。
許可權配置
server 接入真實專案之前，先把檔案、shell、MCP 和分享許可權收緊。