コンテンツにスキップ
ショーケース エコシステム ソースコード ドキュメント

サーバー

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

使用方法

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

オプション

フラグ説明デフォルト
--portリッスンするポート4096
--hostnameリッスンするホスト名127.0.0.1
--mdnsmDNS 検出を有効化false
--mdns-domainmDNS サービスのカスタムドメイン名opencode.local
--cors許可する追加のブラウザオリジン[]

--cors は複数回指定できます。

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

認証

OPENCODE_SERVER_PASSWORD を設定して、サーバーを HTTP Basic 認証で保護します。ユーザー名はデフォルトで 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 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 を公開します。

Global

メソッドパス説明レスポンス
GET/global/healthサーバーの状態とバージョンを取得{ healthy: true, version: string }
GET/global/eventグローバルイベントを取得 (SSE ストリーム)イベントストリーム

Project

メソッドパス説明レスポンス
GET/projectすべてのプロジェクトを列挙Project[]
GET/project/current現在のプロジェクトを取得Project

Path & VCS

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

Instance

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

Config

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

Provider

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

Sessions

メソッドパス説明注記
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 を返す

Messages

メソッドパス説明注記
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[] } を返す

Commands

メソッドパス説明レスポンス
GET/commandすべてのコマンドを列挙Command[]

Files

メソッドパス説明レスポンス
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" の場合はファイルのみを返す)

Tools (Experimental)

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

LSP, Formatters & MCP

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

Agents

メソッドパス説明レスポンス
GET/agent利用可能なエージェントを列挙Agent[]

Logging

メソッドパス説明レスポンス
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

Auth

メソッドパス説明レスポンス
PUT/auth/:id認証資格情報を設定。Body はプロバイダのスキーマと一致する必要がありますboolean

Events

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

Docs

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