---
title: 伺服器
description: 通過 HTTP 與 opencode 服務器交互。
---

import config from "../../../../config.mjs"
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`

`opencode serve` 命令運行一個無頭 HTTP 服務器，該服務器公開opencode客戶端可以使用的 OpenAPI 端點。

---

### 用法

```bash
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` 可以多次傳遞：

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

---

### 驗證

設置`OPENCODE_SERVER_PASSWORD`以使用HTTP基本身份驗證保護服務器。用戶名默認為`opencode`，或設置`OPENCODE_SERVER_USERNAME`來覆蓋它。這適用於`opencode serve` 和`opencode web`。

```bash
OPENCODE_SERVER_PASSWORD=your-password opencode serve
```

---

### 它是如何運作的

當您運行 `opencode` 時，它會啟動 TUI 和服務器。 TUI 是哪裡
與服務器對話的客戶端。服務器公開 OpenAPI 3.1 規範
端點。該端點還用於生成[軟件開發工具包](/docs/sdk)。

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

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

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

---

#### 連接到現有服務器

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

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

---

## 規格

服務器發布了 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`         | 列出所有項目 | <a href={typesUrl}><code>項目[]</code></a> |
| `GET` | `/project/current` | 獲取當前項目 | <a href={typesUrl}><code>項目</code></a>   |

---

### 路徑和VCS

| 方法  | 路徑    | 描述                    | 回應                                        |
| ----- | ------- | ----------------------- | ------------------------------------------- |
| `GET` | `/path` | 獲取當前路徑            | <a href={typesUrl}><code>路徑</code></a>    |
| `GET` | `/vcs`  | 獲取當前項目的 VCS 信息 | <a href={typesUrl}><code>VcsInfo</code></a> |

---

### 實例

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

---

### 配置

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

---

### 提供者

| 方法   | 路徑                             | 描述                    | 回應                                                                              |
| ------ | -------------------------------- | ----------------------- | --------------------------------------------------------------------------------- |
| `GET`  | `/provider`                      | 列出所有提供商          | `{ all: `<a href={typesUrl}>提供商[]</a>`, default: {...}, connected: string[] }` |
| `GET`  | `/provider/auth`                 | 獲取提供商身份驗證方法  | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }`         |
| `POST` | `/provider/{id}/oauth/authorize` | 使用 OAuth 授權提供商   | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a>                     |
| `POST` | `/provider/{id}/oauth/callback`  | 處理提供商的 OAuth 回調 | `boolean`                                                                         |

---

### 會議

| 方法     | 路徑                                     | 描述                          | 筆記                                                                            |
| -------- | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
| `GET`    | `/session`                               | 列出所有會話                  | 返回 <a href={typesUrl}><code>Session[]</code></a>                              |
| `POST`   | `/session`                               | 創建新會話                    | 正文：`{ parentID?, title? }`，返回 <a href={typesUrl}><code>Session</code></a> |
| `GET`    | `/session/status`                        | 獲取所有會話的會話狀態        | 返回 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }`          |
| `GET`    | `/session/:id`                           | 獲取會話詳細信息              | 返回 <a href={typesUrl}><code>Session</code></a>                                |
| `DELETE` | `/session/:id`                           | 刪除會話及其所有數據          | 返回 `boolean`                                                                  |
| `PATCH`  | `/session/:id`                           | 更新會話屬性                  | 正文：`{ title? }`，返回 <a href={typesUrl}><code>Session</code></a>            |
| `GET`    | `/session/:id/children`                  | 獲取會話的子會話              | 返回 <a href={typesUrl}><code>Session[]</code></a>                              |
| `GET`    | `/session/:id/todo`                      | 獲取會話的待辦事項列表        | 返回 <a href={typesUrl}><code>Todo[]</code></a>                                 |
| `POST`   | `/session/:id/init`                      | 分析應用程序並創建`AGENTS.md` | 主體：`{ messageID, providerID, modelID }`，返回`boolean`                       |
| `POST`   | `/session/:id/fork`                      | 在消息中分叉現有會話          | 正文：`{ messageID? }`，返回 <a href={typesUrl}><code>Session</code></a>        |
| `POST`   | `/session/:id/abort`                     | 中止正在運行的會話            | 返回 `boolean`                                                                  |
| `POST`   | `/session/:id/share`                     | 分享會議                      | 返回 <a href={typesUrl}><code>Session</code></a>                                |
| `DELETE` | `/session/:id/share`                     | 取消共享會話                  | 返回 <a href={typesUrl}><code>Session</code></a>                                |
| `GET`    | `/session/:id/diff`                      | 獲取本次會話的差異            | 查詢：`messageID?`，返回 <a href={typesUrl}><code>FileDiff[]</code></a>         |
| `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: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]`                                                         |
| `POST` | `/session/:id/message`            | 發送消息並等待回复       | 主體：`{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`，返回`{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}` |
| `GET`  | `/session/:id/message/:messageID` | 獲取消息詳情             | 返回`{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}`                                                                           |
| `POST` | `/session/:id/prompt_async`       | 異步發送消息（無需等待） | body：與`/session/:id/message`相同，返回`204 No Content`                                                                                                       |
| `POST` | `/session/:id/command`            | 執行斜杠命令             | 主體：`{ messageID?, agent?, model?, command, arguments }`，返回`{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}`               |
| `POST` | `/session/:id/shell`              | 運行 shell 命令          | 主體：`{ agent, model?, command }`，返回`{ info: `<a href={typesUrl}>消息</a>`, parts: `<a href={typesUrl}>部分[]</a>`}`                                       |

---

### 命令

| 方法  | 路徑       | 描述         | 回應                                          |
| ----- | ---------- | ------------ | --------------------------------------------- |
| `GET` | `/command` | 列出所有命令 | <a href={typesUrl}><code>Command[]</code></a> |

---

### 文件

| 方法  | 路徑                     | 描述                 | 回應                                                                                |
| ----- | ------------------------ | -------------------- | ----------------------------------------------------------------------------------- |
| `GET` | `/find?pattern=<pat>`    | 搜索文件中的文本     | 具有 `path`, `lines`, `line_number`, `absolute_offset`, `submatches` 的匹配對象陣列 |
| `GET` | `/find/file?query=<q>`   | 按名稱查找文件和目錄 | `string[]`（路徑）                                                                  |
| `GET` | `/find/symbol?query=<q>` | 查找工作區符號       | <a href={typesUrl}><code>Symbol[]</code></a>                                        |
| `GET` | `/file?path=<path>`      | 列出文件和目錄       | <a href={typesUrl}><code>FileNode[]</code></a>                                      |
| `GET` | `/file/content?path=<p>` | 讀取文件             | <a href={typesUrl}><code>FileContent</code></a>                                     |
| `GET` | `/file/status`           | 獲取跟蹤文件的狀態   | <a href={typesUrl}><code>File[]</code></a>                                          |

#### `/find/file`查詢參數

- `query`（必需）- 搜索字符串（模糊匹配）
- `type`（可選）- 將結果限制為`"file"` 或`"directory"`
- `directory` (可選) — 覆蓋搜索的項目根目錄
- `limit`（可選）— 最大結果 (1–200)
- `dirs`（可選）- 舊標誌（`"false"` 僅返回文件）

---

### 工具（實驗）

| 方法  | 路徑                                        | 描述                         | 回應                                         |
| ----- | ------------------------------------------- | ---------------------------- | -------------------------------------------- |
| `GET` | `/experimental/tool/ids`                    | 列出所有工具 ID              | <a href={typesUrl}><code>ToolID</code></a>   |
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出具有模型 JSON 架構的工具 | <a href={typesUrl}><code>工具列表</code></a> |

---

### LSP、格式化程序和 MCP

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

---

### 代理商

| 方法  | 路徑     | 描述               | 回應                                       |
| ----- | -------- | ------------------ | ------------------------------------------ |
| `GET` | `/agent` | 列出所有可用的代理 | <a href={typesUrl}><code>代理[]</code></a> |

---

### 記錄

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