---
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` コマンドは、opencode クライアントが使用できる OpenAPI エンドポイントを公開するヘッドレス HTTP サーバーを実行します。

---

### 使用法

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

---

### 認証

HTTP 基本認証でサーバーを保護するには、`OPENCODE_SERVER_PASSWORD` を設定します。ユーザー名はデフォルトで `opencode` になるか、`OPENCODE_SERVER_USERNAME` を設定してオーバーライドします。これは、`opencode serve` と `opencode web` の両方に当てはまります。

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

---

### 仕組み

`opencode` を実行すると、TUI とサーバーが起動します。 TUI の場所
サーバーと通信するクライアント。サーバーは OpenAPI 3.1 仕様を公開します
終点。このエンドポイントは、[SDK](/docs/sdk).

:::tip
opencode サーバーを使用して、プログラムで opencode と対話します。
:::
This

`opencode serve` を実行してスタンドアロン サーバーを起動できます。持っている場合は、
opencode TUI を実行すると、`opencode serve` が新しいサーバーを起動します。

---

#### 既存のサーバーに接続する

TUI を起動すると、ポートとホスト名がランダムに割り当てられます。代わりに、`--hostname` と `--port` [flags](/docs/cli).次に、これを使用してサーバーに接続します。

[`/tui`](#tui) エンドポイントは、サーバー経由で TUI を駆動するために使用できます。たとえば、プロンプトを事前入力したり、実行したりできます。この設定は、OpenCode [IDE](/docs/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`         | すべてのプロジェクトをリストする | <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` | 現在のインスタンスを破棄する | うーん |

---

### 構成

| 方法    | パス                | 説明                                         | 応答                                                                                       |
| ------- | ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `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 コールバックを処理する | うーん                                                                                |

---

### セッション

| 方法     | パス                                     | 説明                                                | メモ                                                                                       |
| -------- | ---------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `GET`    | `/session`                               | すべてのセッションをリストする                      | 戻り値 <a href={typesUrl}><code>セッション[]</code></a>                                    |
| `POST`   | `/session`                               | 新しいセッションを作成する                          | 本文: `{ parentID?, title? }`、<a href={typesUrl}><code>セッション</code></a> を返します。 |
| `GET`    | `/session/status`                        | すべてのセッションのセッション ステータスを取得する | 戻り値 `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }`                   |
| `GET`    | `/session/:id`                           | セッションの詳細を取得する                          | 戻り値 <a href={typesUrl}><code>セッション</code></a>                                      |
| `DELETE` | `/session/:id`                           | セッションとそのすべてのデータを削除する            | 戻り値 `boolean`                                                                           |
| `PATCH`  | `/session/:id`                           | セッションのプロパティを更新する                    | 本文: `{ title? }`、<a href={typesUrl}><code>セッション</code></a> を返します。            |
| `GET`    | `/session/:id/children`                  | セッションの子セッションを取得する                  | 戻り値 <a href={typesUrl}><code>セッション[]</code></a>                                    |
| `GET`    | `/session/:id/todo`                      | セッションの 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>セッション</code></a> を返します。        |
| `POST`   | `/session/:id/abort`                     | 実行中のセッションを中止する                        | 戻り値 `boolean`                                                                           |
| `POST`   | `/session/:id/share`                     | セッションを共有する                                | 戻り値 <a href={typesUrl}><code>セッション</code></a>                                      |
| `DELETE` | `/session/:id/share`                     | セッションの共有を解除する                          | 戻り値 <a href={typesUrl}><code>セッション</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}>Part[]</a>`}` |
| `GET`  | `/session/:id/message/:messageID` | メッセージの詳細を取得する              | 戻り値 `{ info: `<a href={typesUrl}>メッセージ</a>`, parts: `<a href={typesUrl}>Part[]</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}>Part[]</a>`}`               |
| `POST` | `/session/:id/shell`              | shell コマンドを実行する                | 本文: `{ agent, model?, command }`、`{ info: `<a href={typesUrl}>メッセージ</a>を返します`, parts: `<a href={typesUrl}>Part[]</a>`}`                                       |

---

### コマンド

| 方法  | パス       | 説明                         | 応答                                           |
| ----- | ---------- | ---------------------------- | ---------------------------------------------- |
| `GET` | `/command` | すべてのコマンドをリストする | <a href={typesUrl}><code>コマンド[]</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>シンボル[]</code></a>                                               |
| `GET` | `/file?path=<path>`      | ファイルとディレクトリをリストする       | <a href={typesUrl}><code>FileNode[]</code></a>                                               |
| `GET` | `/file/content?path=<p>` | ファイルを読む                           | <a href={typesUrl}><code>ファイルコンテンツ</code></a>                                       |
| `GET` | `/file/status`           | 追跡されたファイルのステータスを取得する | <a href={typesUrl}><code>ファイル[]</code></a>                                               |

#### `/find/file` クエリパラメータ

- `query` (必須) — 検索文字列 (あいまい一致)
- `type` (オプション) — 結果を `"file"` または `"directory"` に制限します
- `directory` (オプション) — 検索用のプロジェクト ルートをオーバーライドします。
- `limit` (オプション) — 最大結果 (1 ～ 200)
- `dirs` (オプション) — 従来のフラグ (`"false"` はファイルのみを返します)

---

### ツール (実験的)

| 方法  | パス                                        | 説明                                           | 応答                                             |
| ----- | ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ |
| `GET` | `/experimental/tool/ids`                    | すべてのツール ID をリストする                 | <a href={typesUrl}><code>ツール ID</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 サーバーを動的に追加する       | 本文: `{ name, config }`、MCP ステータス オブジェクトを返します。 |

---

### エージェント

| 方法  | パス     | 説明                                       | 応答                                               |
| ----- | -------- | ------------------------------------------ | -------------------------------------------------- |
| `GET` | `/agent` | 利用可能なすべてのエージェントをリストする | <a href={typesUrl}><code>エージェント[]</code></a> |

---

### ロギング

| 方法   | パス   | 説明                                                                   | 応答   |
| ------ | ------ | ---------------------------------------------------------------------- | ------ |
| `POST` | `/log` | ログエントリを書き込みます。本体:`{ service, level, message, extra? }` | うーん |

---

### トゥイ

| 方法   | パス                    | 説明                                            | 応答                               |
| ------ | ----------------------- | ----------------------------------------------- | ---------------------------------- |
| `POST` | `/tui/append-prompt`    | プロンプトにテキストを追加します                | うーん                             |
| `POST` | `/tui/open-help`        | ヘルプダイアログを開く                          | うーん                             |
| `POST` | `/tui/open-sessions`    | セッションセレクターを開く                      | うーん                             |
| `POST` | `/tui/open-themes`      | テーマセレクターを開く                          | うーん                             |
| `POST` | `/tui/open-models`      | モデルセレクターを開く                          | うーん                             |
| `POST` | `/tui/submit-prompt`    | 現在のプロンプトを送信します                    | うーん                             |
| `POST` | `/tui/clear-prompt`     | プロンプトをクリア                              | うーん                             |
| `POST` | `/tui/execute-command`  | コマンドを実行する (`{ command }`)              | うーん                             |
| `POST` | `/tui/show-toast`       | トーストを表示 (`{ title?, message, variant }`) | うーん                             |
| `GET`  | `/tui/control/next`     | 次の制御リクエストを待ちます                    | コントロールリクエストオブジェクト |
| `POST` | `/tui/control/response` | 制御リクエストに応答する (`{ body }`)           | うーん                             |

---

### 認証

| 方法  | パス        | 説明                                                                           | 応答   |
| ----- | ----------- | ------------------------------------------------------------------------------ | ------ |
| `PUT` | `/auth/:id` | 認証資格情報を設定します。本文はプロバイダーのスキーマと一致する必要があります | うーん |

---

### イベント

| Method | Path     | Description                                                                   | Response                  |
| ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- |
| `GET`  | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream |

---

### ドキュメント

| 方法  | パス   | 説明             | 応答                             |
| ----- | ------ | ---------------- | -------------------------------- |
| `GET` | `/doc` | OpenAPI 3.1 仕様 | OpenAPI 仕様を備えた HTML ページ |
