サーバー

HTTP 経由で opencode サーバーと対話します。

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

使い方

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 は複数回指定できます：

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

認証

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

OPENCODE_SERVER_PASSWORD=your-password opencode serve

仕組み

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

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

このアーキテクチャにより、opencode は複数のクライアントをサポートし、プログラムから opencode と対話できます。

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

既存のサーバーに接続

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

/tui エンドポイントを使用して、サーバー経由で TUI を操作できます。例えば、プロンプトを事前入力したり実行したりできます。この設定は OpenCode 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`	すべてのプロジェクトを一覧表示	`Project[]`
`GET`	`/project/current`	現在のプロジェクトを取得	`Project`

パスと VCS

メソッド	パス	説明	レスポンス
`GET`	`/path`	現在のパスを取得	`Path`
`GET`	`/vcs`	現在のプロジェクトの VCS 情報を取得	`VcsInfo`

インスタンス

メソッド	パス	説明	レスポンス
`POST`	`/instance/dispose`	現在のインスタンスを破棄	`boolean`

設定

メソッド	パス	説明	レスポンス
`GET`	`/config`	設定情報を取得	`Config`
`PATCH`	`/config`	設定を更新	`Config`
`GET`	`/config/providers`	プロバイダーとデフォルトモデルを一覧表示	`{ providers: Provider[], default: { [key: string]: string } }`

プロバイダー

メソッド	パス	説明	レスポンス
`GET`	`/provider`	すべてのプロバイダーを一覧表示	`{ all: Provider[], default: {...}, connected: string[] }`
`GET`	`/provider/auth`	プロバイダーの認証方法を取得	`{ [providerID: string]: ProviderAuthMethod[] }`
`POST`	`/provider/{id}/oauth/authorize`	OAuth でプロバイダーを認可	`ProviderAuthAuthorization`
`POST`	`/provider/{id}/oauth/callback`	プロバイダーの OAuth コールバックを処理	`boolean`

セッション

メソッド	パス	説明	備考
`GET`	`/session`	すべてのセッションを一覧表示	`Session[]` を返す
`POST`	`/session`	新しいセッションを作成	body: `{ parentID?, title? }`、`Session` を返す
`GET`	`/session/status`	すべてのセッションのステータスを取得	`{ [sessionID: string]: SessionStatus }` を返す
`GET`	`/session/:id`	セッションの詳細を取得	`Session` を返す
`DELETE`	`/session/:id`	セッションとそのすべてのデータを削除	`boolean` を返す
`PATCH`	`/session/:id`	セッションのプロパティを更新	body: `{ title? }`、`Session` を返す
`GET`	`/session/:id/children`	セッションの子セッションを取得	`Session[]` を返す
`GET`	`/session/:id/todo`	セッションの TODO リストを取得	`Todo[]` を返す
`POST`	`/session/:id/init`	アプリを分析して `AGENTS.md` を作成	body: `{ messageID, providerID, modelID }`、`boolean` を返す
`POST`	`/session/:id/fork`	メッセージで既存のセッションをフォーク	body: `{ messageID? }`、`Session` を返す
`POST`	`/session/:id/abort`	実行中のセッションを中止	`boolean` を返す
`POST`	`/session/:id/share`	セッションを共有	`Session` を返す
`DELETE`	`/session/:id/share`	セッションの共有を解除	`Session` を返す
`GET`	`/session/:id/diff`	このセッションの差分を取得	query: `messageID?`、`FileDiff[]` を返す
`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` を返す

メッセージ

メソッド	パス	説明	備考
`GET`	`/session/:id/message`	セッション内のメッセージを一覧表示	query: `limit?`、`{ info: Message, parts: Part[] }[]` を返す
`POST`	`/session/:id/message`	メッセージを送信してレスポンスを待つ	body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`、`{ info: Message, parts: Part[] }` を返す
`GET`	`/session/:id/message/:messageID`	メッセージの詳細を取得	`{ info: Message, parts: Part[] }` を返す
`POST`	`/session/:id/prompt_async`	メッセージを非同期で送信（待機なし）	body: `/session/:id/message` と同じ、`204 No Content` を返す
`POST`	`/session/:id/command`	スラッシュコマンドを実行	body: `{ messageID?, agent?, model?, command, arguments }`、`{ info: Message, parts: Part[] }` を返す
`POST`	`/session/:id/shell`	シェルコマンドを実行	body: `{ agent, model?, command }`、`{ info: Message, parts: Part[] }` を返す

コマンド

メソッド	パス	説明	レスポンス
`GET`	`/command`	すべてのコマンドを一覧表示	`Command[]`

ファイル

メソッド	パス	説明	レスポンス
`GET`	`/find?pattern=<pat>`	ファイル内のテキストを検索	`path`、`lines`、`line_number`、`absolute_offset`、`submatches` を含むマッチオブジェクトの配列
`GET`	`/find/file?query=<q>`	名前でファイルとディレクトリを検索	`string[]`（パス）
`GET`	`/find/symbol?query=<q>`	ワークスペースシンボルを検索	`Symbol[]`
`GET`	`/file?path=<path>`	ファイルとディレクトリを一覧表示	`FileNode[]`
`GET`	`/file/content?path=<p>`	ファイルを読み取る	`FileContent`
`GET`	`/file/status`	追跡されたファイルのステータスを取得	`File[]`

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

query（必須）— 検索文字列（あいまい一致）
type（オプション）— 結果を "file" または "directory" に制限
directory（オプション）— 検索のプロジェクトルートを上書き
limit（オプション）— 最大結果数（1–200）
dirs（オプション）— レガシーフラグ（"false" はファイルのみを返す）

ツール（実験的）

メソッド	パス	説明	レスポンス
`GET`	`/experimental/tool/ids`	すべてのツール ID を一覧表示	`ToolIDs`
`GET`	`/experimental/tool?provider=<p>&model=<m>`	モデルの JSON スキーマ付きツールを一覧表示	`ToolList`

LSP、フォーマッタ、MCP

メソッド	パス	説明	レスポンス
`GET`	`/lsp`	LSP サーバーのステータスを取得	`LSPStatus[]`
`GET`	`/formatter`	フォーマッタのステータスを取得	`FormatterStatus[]`
`GET`	`/mcp`	MCP サーバーのステータスを取得	`{ [name: string]: MCPStatus }`
`POST`	`/mcp`	MCP サーバーを動的に追加	body: `{ name, config }`、MCP ステータスオブジェクトを返す

エージェント

メソッド	パス	説明	レスポンス
`GET`	`/agent`	利用可能なすべてのエージェントを一覧表示	`Agent[]`

ロギング

メソッド	パス	説明	レスポンス
`POST`	`/log`	ログエントリを書き込む。Body: `{ 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`	認証資格情報を設定。Body はプロバイダースキーマに一致する必要がある	`boolean`

イベント

メソッド	パス	説明	レスポンス
`GET`	`/event`	サーバー送信イベントストリーム。最初のイベントは `server.connected`、その後バスイベント	サーバー送信イベントストリーム

ドキュメント

メソッド	パス	説明	レスポンス
`GET`	`/doc`	OpenAPI 3.1 仕様	OpenAPI 仕様を含む HTML ページ

SDK プラグイン