---
title: サーバ
description: HTTP 経由でオープンコード サーバーと通信します。
---

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

`opencode serve` コマンドは、オープンコード クライアントが使用できる 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).

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

このアーキテクチャにより、オープンコードで複数のクライアントをサポートできるようになり、プログラムでオープンコードと対話できるようになります。

`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` |サーバーの健全性とバージョンを取得する |うーん
| `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` |シェルコマンドを実行する |本文: `{ 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` |認証資格情報を設定します。本文はプロバイダーのスキーマと一致する必要があります |うーん

---

### イベント

|方法 |パス |説明 |応答 |
| ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- |
| `GET` | `/event` |サーバーから送信されたイベント ストリーム。最初のイベントは `server.connected` で、次にバス イベントです。サーバー送信イベント ストリーム |

---

### ドキュメント

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