---
title: "啟動伺服器"
description: "透過 HTTP 與 OpenCode server 互動，並理解 serve、web、TUI、SDK 和 OpenAPI 的關係。"
verifiedAt: "2026-05-09"
---

`opencode serve` 會啟動一個無介面的 HTTP server。它暴露 OpenAPI 3.1 規範和一組 API，讓 TUI、SDK、IDE 外掛或你自己的系統可以透過 HTTP 與 OpenCode 互動。

> [!NOTE]
> **這一篇用 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 |

> [!IMPORTANT]
> 如果要把 server 繫結到區域網或公網地址，先配置 `OPENCODE_SERVER_PASSWORD`。未認證 server 會暴露專案上下文和工具能力。

## OpenCode 的 server 架構

```mermaid
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。

## 啟動方式

最小啟動：

```bash
opencode serve
```

常用引數：

- `--port`：監聽埠，預設 `4096`。
- `--hostname`：監聽主機名，預設 `127.0.0.1`。
- `--mdns`：啟用 mDNS（multicast DNS，區域網內自動發現服務的協議，不依賴 DNS 伺服器）發現。
- `--mdns-domain`：自定義 mDNS 服務域名，預設 `opencode.local`。
- `--cors`：額外允許的瀏覽器來源（CORS 即跨源資源共享，瀏覽器為防止惡意站點偷調你的 API 預設會攔截跨域請求；這裡寫白名單告訴 server 哪些前端域名是被信任的），可以傳多次。

允許多個 CORS 來源：

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

## 認證必須先配

設定 HTTP Basic Auth：

```bash
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve
```

預設使用者名稱是 `opencode`。需要改使用者名稱時：

```bash
export OPENCODE_SERVER_USERNAME="team-agent"
export OPENCODE_SERVER_PASSWORD="change-me"
opencode serve --hostname 0.0.0.0 --port 4096
```

`OPENCODE_SERVER_PASSWORD` 同時適用於 `opencode serve` 和 `opencode web`。

> [!WARNING]
> `--hostname 0.0.0.0` 會讓其他機器訪問到這個 server。沒有認證、沒有網路邊界、沒有反向代理保護時不要這樣啟動。

## OpenAPI spec 在哪裡

server 會發布 OpenAPI 3.1 規範：

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

本機預設是：

```text
http://localhost:4096/doc
```

這個頁面適合做三件事：

- 檢視當前 server 真實暴露的 endpoint。
- 檢查請求體和響應型別。
- 生成客戶端，或和官方 SDK 型別對照。

> [!TIP]
> API 變動時，以當前 `/doc` 和官方 SDK 生成型別為準，不要長期依賴手抄 endpoint 表。

## 最小健康檢查

本地無認證時：

```bash
curl http://127.0.0.1:4096/global/health
```

啟用認證後：

```bash
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`。

## 一條最小整合路徑

先不要一上來寫複雜客戶端。按這個順序驗證：

1. `opencode serve` 能啟動。
2. `/global/health` 能返回 healthy。
3. `/doc` 能開啟。
4. 能列出當前專案或 session。
5. 能建立一個 session。
6. 能傳送一個只讀 message。
7. 能讀取 diff 或結果。
8. 能正確處理許可權請求、錯誤和 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 清理。

## 接下來去哪

<Cards>
  <Card title="使用 SDK" href="/zh-Hant/docs/opencode/official/07-sdk/sdk">
    JS/TS 整合優先用 SDK，避免手寫 HTTP 型別和請求體。
  </Card>
  <Card title="使用 CLI" href="/zh-Hant/docs/opencode/official/00-getting-started/cli">
    只想指令碼化跑一次任務時，CLI `run` 通常比 server 更簡單。
  </Card>
  <Card title="排查故障" href="/zh-Hant/docs/opencode/official/08-platform/troubleshooting">
    server 連線失敗、埠衝突、provider 錯誤時按排障頁定位。
  </Card>
  <Card title="許可權配置" href="/zh-Hant/docs/opencode/official/05-security/permissions">
    server 接入真實專案之前，先把檔案、shell、MCP 和分享許可權收緊。
  </Card>
</Cards>

## 官方資料

- [OpenCode server](https://opencode.ai/docs/server/)
- [OpenCode SDK](https://opencode.ai/docs/sdk/)
- [OpenCode CLI](https://opencode.ai/docs/cli/)
- [OpenCode permissions](https://opencode.ai/docs/permissions/)
