Server

HTTP 経由で opencode サーバーとやり取りします。

opencode serve コマンドは、opencode クライアントが使用できる OpenAPI エンドポイントを公開する、ヘッドレス HTTP サーバーを実行します。

Usage

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

Flag	Description	Default
`--port`	待ち受けるポート	`4096`
`--hostname`	待ち受けるホスト名	`127.0.0.1`
`--mdns`	mDNS 検出を有効にします	`false`
`--mdns-domain`	mDNS サービスのカスタムドメイン名	`opencode.local`
`--cors`	許可する追加のブラウザオリジン	`[]`

--cors は複数回渡せます:

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

Authentication

OPENCODE_SERVER_PASSWORD を設定して、HTTP basic 認証でサーバーを保護します。ユーザー名はデフォルトで opencode ですが、OPENCODE_SERVER_USERNAME を設定して上書きできます。これは opencode serve と opencode web の両方に適用されます。

OPENCODE_SERVER_PASSWORD=your-password opencode serve

How it works

opencode を実行すると、TUI とサーバーが起動します。ここで TUI は、サーバーと通信するクライアントです。サーバーは OpenAPI 3.1 仕様のエンドポイントを公開します。このエンドポイントは、SDK の生成にも使われます。

ヒント: opencode サーバーを使って、opencode をプログラム的に操作してください。

このアーキテクチャにより、opencode は複数のクライアントをサポートでき、opencode をプログラム的に操作できます。

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

Connect to an existing server

TUI を起動すると、ポートとホスト名がランダムに割り当てられます。代わりに --hostname と --port フラグを渡すこともできます。そして、これを使ってそのサーバーに接続します。

/tui エンドポイントを使って、サーバーを通じて TUI を操作できます。例えば、プロンプトを事前入力したり実行したりできます。このセットアップは、OpenCode の IDE プラグインで使用されています。

Spec

サーバーは、次の場所で閲覧できる OpenAPI 3.1 仕様を公開します:

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

例えば、http://localhost:4096/doc です。この仕様を使って、クライアントを生成したり、リクエストとレスポンスの型を調べたりします。あるいは Swagger エクスプローラーで表示します。

APIs

opencode サーバーは、次の API を公開します。

Global

Method	Path	Description	Response
`GET`	`/global/health`	サーバーのヘルスとバージョンを取得	`{ healthy: true, version: string }`
`GET`	`/global/event`	グローバルイベントを取得（SSE ストリーム）	Event stream

Project

Method	Path	Description	Response
`GET`	`/project`	すべてのプロジェクトを一覧表示	`Project[]` (opens in a new tab)
`GET`	`/project/current`	現在のプロジェクトを取得	`Project` (opens in a new tab)

Path & VCS

Method	Path	Description	Response
`GET`	`/path`	現在のパスを取得	`Path` (opens in a new tab)
`GET`	`/vcs`	現在のプロジェクトの VCS 情報を取得	`VcsInfo` (opens in a new tab)

Instance

Method	Path	Description	Response
`POST`	`/instance/dispose`	現在のインスタンスを破棄	`boolean`

Config

Method	Path	Description	Response
`GET`	`/config`	設定情報を取得	`Config` (opens in a new tab)
`PATCH`	`/config`	設定を更新	`Config` (opens in a new tab)
`GET`	`/config/providers`	プロバイダーとデフォルトモデルを一覧表示	`{ providers:` Provider[] (opens in a new tab)`, default: { [key: string]: string } }`

Provider

Method	Path	Description	Response
`GET`	`/provider`	すべてのプロバイダーを一覧表示	`{ all:` Provider[] (opens in a new tab)`, default: {...}, connected: string[] }`
`GET`	`/provider/auth`	プロバイダーの認証方法を取得	`{ [providerID: string]:` ProviderAuthMethod[] (opens in a new tab) `}`
`POST`	`/provider/{id}/oauth/authorize`	OAuth を使ってプロバイダーを認可	`ProviderAuthAuthorization` (opens in a new tab)
`POST`	`/provider/{id}/oauth/callback`	プロバイダーの OAuth コールバックを処理	`boolean`

Sessions

Method	Path	Description	Notes
`GET`	`/session`	すべてのセッションを一覧表示	`Session[]` (opens in a new tab) を返します
`POST`	`/session`	新しいセッションを作成	body: `{ parentID?, title? }`、`Session` (opens in a new tab) を返します
`GET`	`/session/status`	すべてのセッションのステータスを取得	`{ [sessionID: string]:` SessionStatus (opens in a new tab) `}` を返します
`GET`	`/session/:id`	セッションの詳細を取得	`Session` (opens in a new tab) を返します
`DELETE`	`/session/:id`	セッションとそのすべてのデータを削除	`boolean` を返します
`PATCH`	`/session/:id`	セッションのプロパティを更新	body: `{ title? }`、`Session` (opens in a new tab) を返します
`GET`	`/session/:id/children`	セッションの子セッションを取得	`Session[]` (opens in a new tab) を返します
`GET`	`/session/:id/todo`	セッションの todo リストを取得	`Todo[]` (opens in a new tab) を返します
`POST`	`/session/:id/init`	アプリを分析して `AGENTS.md` を作成	body: `{ messageID, providerID, modelID }`、`boolean` を返します
`POST`	`/session/:id/fork`	既存のセッションをメッセージ位置でフォーク	body: `{ messageID? }`、`Session` (opens in a new tab) を返します
`POST`	`/session/:id/abort`	実行中のセッションを中止	`boolean` を返します
`POST`	`/session/:id/share`	セッションを共有	`Session` (opens in a new tab) を返します
`DELETE`	`/session/:id/share`	セッションの共有を解除	`Session` (opens in a new tab) を返します
`GET`	`/session/:id/diff`	このセッションの diff を取得	query: `messageID?`、`FileDiff[]` (opens in a new tab) を返します
`POST`	`/session/:id/summarize`	セッションを要約	body: `{ providerID, modelID }`、`boolean` を返します
`POST`	`/session/:id/revert`	メッセージを元に戻す	body: `{ messageID, partID? }`、`boolean` を返します
`POST`	`/session/:id/unrevert`	元に戻したすべてのメッセージを復元	`boolean` を返します
`POST`	`/session/:id/permissions/:permissionID`	権限リクエストに応答	body: `{ response, remember? }`、`boolean` を返します

Messages

Method	Path	Description	Notes
`GET`	`/session/:id/message`	セッション内のメッセージを一覧表示	query: `limit?`、`{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}[]` を返します
`POST`	`/session/:id/message`	メッセージを送信して応答を待つ	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`、`{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}` を返します
`GET`	`/session/:id/message/:messageID`	メッセージの詳細を取得	`{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}` を返します
`POST`	`/session/:id/prompt_async`	メッセージを非同期で送信（待機なし）	body: `/session/:id/message` と同じ、`204 No Content` を返します
`POST`	`/session/:id/command`	スラッシュコマンドを実行	body: `{ messageID?, agent?, model?, command, arguments }`、`{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}` を返します
`POST`	`/session/:id/shell`	シェルコマンドを実行	body: `{ agent, model?, command }`、`{ info:` Message (opens in a new tab)`, parts:` Part[] (opens in a new tab)`}` を返します

Commands

Method	Path	Description	Response
`GET`	`/command`	すべてのコマンドを一覧表示	`Command[]` (opens in a new tab)

Files

Method	Path	Description	Response
`GET`	`/find?pattern=<pat>`	ファイル内のテキストを検索	`path`、`lines`、`line_number`、`absolute_offset`、`submatches` を持つ一致オブジェクトの配列
`GET`	`/find/file?query=<q>`	名前でファイルとディレクトリを検索	`string[]`（パス）
`GET`	`/find/symbol?query=<q>`	ワークスペースのシンボルを検索	`Symbol[]` (opens in a new tab)
`GET`	`/file?path=<path>`	ファイルとディレクトリを一覧表示	`FileNode[]` (opens in a new tab)
`GET`	`/file/content?path=<p>`	ファイルを読み取り	`FileContent` (opens in a new tab)
`GET`	`/file/status`	追跡対象のファイルのステータスを取得	`File[]` (opens in a new tab)

`/find/file` query parameters

query（必須）— 検索文字列（ファジーマッチ）
type（任意）— 結果を "file" または "directory" に制限
directory（任意）— 検索のためにプロジェクトルートを上書き
limit（任意）— 最大結果数（1-200）
dirs（任意）— レガシーフラグ（"false" はファイルのみを返します）

Tools (Experimental)

Method	Path	Description	Response
`GET`	`/experimental/tool/ids`	すべてのツール ID を一覧表示	`ToolIDs` (opens in a new tab)
`GET`	`/experimental/tool?provider=<p>&model=<m>`	モデルの JSON スキーマ付きでツールを一覧表示	`ToolList` (opens in a new tab)

LSP, Formatters & MCP

Method	Path	Description	Response
`GET`	`/lsp`	LSP サーバーのステータスを取得	`LSPStatus[]` (opens in a new tab)
`GET`	`/formatter`	フォーマッターのステータスを取得	`FormatterStatus[]` (opens in a new tab)
`GET`	`/mcp`	MCP サーバーのステータスを取得	`{ [name: string]:` MCPStatus (opens in a new tab) `}`
`POST`	`/mcp`	MCP サーバーを動的に追加	body: `{ name, config }`、MCP ステータスオブジェクトを返します

Agents

Method	Path	Description	Response
`GET`	`/agent`	利用可能なすべてのエージェントを一覧表示	`Agent[]` (opens in a new tab)

Logging

Method	Path	Description	Response
`POST`	`/log`	ログエントリを書き込み。Body: `{ service, level, message, extra? }`	`boolean`

TUI

Method	Path	Description	Response
`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`

Auth

Method	Path	Description	Response
`PUT`	`/auth/:id`	認証情報を設定。Body はプロバイダーのスキーマに一致する必要があります	`boolean`

Events

Method	Path	Description	Response
`GET`	`/event`	Server-sent events ストリーム。最初のイベントは `server.connected`、その後にバスイベント	Server-sent events ストリーム

Docs

Method	Path	Description	Response
`GET`	`/doc`	OpenAPI 3.1 仕様	OpenAPI 仕様付きの HTML ページ

SDK プラグイン