OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

RPC and API

外部アプリ向けのGateway統合

外部アプリは Gateway プロトコル（WebSocket トランスポートと RPC メソッド）を介して OpenClaw と通信します。スクリプト、ダッシュボード、CI ジョブ、IDE 拡張機能、または別のプロセスから、エージェント実行の開始、イベントのストリーミング、結果の待機、処理のキャンセル、Gateway リソースの調査を行う場合に使用します。

現在利用できるもの

サーフェス 状態 用途
Gateway プロトコル 利用可能 WebSocket トランスポート、接続ハンドシェイク、認証スコープ、プロトコルのバージョニング、イベント。
Gateway RPC リファレンス 利用可能 エージェント、セッション、タスク、モデル、ツール、成果物、承認に関する現在の Gateway メソッド。
openclaw agent 利用可能 CLI をシェルから呼び出すだけで十分な場合の、単発のスクリプト統合。
openclaw message 利用可能 スクリプトからのメッセージまたはチャンネルアクションの送信。

将来のクライアントライブラリパッケージは内部で開発中ですが、まだ公開インストールサーフェスではありません。公開されたバージョン付きパッケージがリリースで発表されるまでは、プレビュー段階の実装詳細として扱ってください。

推奨手順

  1. Gateway を実行または検出します。
  2. Gateway プロトコルを介して接続します。
  3. Gateway RPC リファレンスに記載された RPC メソッドを呼び出します。
  4. テスト対象の OpenClaw バージョンを固定します。
  5. OpenClaw のアップグレード時に RPC リファレンスを再確認します。

エージェント実行では、agent RPC から開始し、最終結果を得るために agent.wait と組み合わせます。永続的な会話状態には sessions.* メソッドを使用します。UI 統合では Gateway イベントを購読し、アプリが理解できるイベントファミリーだけをレンダリングします。

ホストの協調的なサスペンド

実行中のプロセスを凍結またはスナップショットするホスティングコントローラーでは、ホストに依存しない次のサスペンドハンドシェイクを使用できます。

  1. ホストが制御する外部からの受信を停止します。
  2. 安定した一意の requestId を指定して gateway.suspend.prepare を呼び出します。
  3. 応答が busy の場合は、プロセスを実行したままにして後で再試行します。
  4. ready の場合は、返された suspensionId を保存し、expiresAtMs より前にプロセスを凍結またはスナップショットします。
  5. 凍結解除後、またはサスペンドを中止した場合は、既存の WebSocket または Admin HTTP 制御パスを介して、その suspensionId を指定して gateway.suspend.resume を呼び出します。

準備済みの Gateway は新しい WebSocket ハンドシェイクを拒否します。WebSocket コントローラーは、ホスト操作中も認証済み接続を開いたままにする必要があります。それを保証できない場合は、準備前に Admin HTTP RPC Pluginを有効化して使用してください。制御パスが失われた場合は、再接続する前に 2 分間のリースが期限切れになるまで待ってください。期限切れになると受け入れが自動的に再開されます。

RPC コントラクトは次のとおりです。

  • gateway.suspend.prepare — operator.admin、パラメーター { "requestId": "stable-host-operation-id" }
  • gateway.suspend.status — operator.read、パラメーター { "suspensionId": "id-from-prepare" }
  • gateway.suspend.resume — operator.admin、パラメーター { "suspensionId": "id-from-prepare" }

ID は前後の空白が除去され、空白以外の文字を含む必要があり、128 文字に制限されます。ビジー状態の準備結果には status: "busy"、reason、retryAfterMs、activeCount、blockers が含まれます。準備完了の結果は次の形式です。

json
{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

ステータスは {"status":"running"}、または expiresAtMs を含む準備完了結果を返します。再開は {"ok":true,"status":"running","resumed":true} を返します。正常に再開した後に繰り返すと、resumed: false が返されます。

競合するリクエスト ID、または一時的なスケジューラー再開失敗では、retryAfterMs を含む再試行可能な UNAVAILABLE が返されます。スケジューラーの復旧中は、準備、ステータス、再開のすべてでこのエラーが返され、Gateway は準備未完了かつフェイルクローズの状態を維持するため、ホストは凍結またはスナップショットしてはいけません。OpenClaw はスケジューラーを自動的に再試行し、復旧に成功した後にのみ受け入れを再開します。一致しない再開 ID では INVALID_REQUEST が返されます。準備処理は、1 分あたり 3 回までという Gateway のコントロールプレーン書き込みバジェットを共有します。返された再試行遅延に従ってください。WebSocket クライアントはデバイスと IP ごとにバケット分けされます。Admin HTTP コントローラーは解決済みのクライアント IP ごとにバケット分けされるため、1 つのプロキシの背後にあるコントローラーはバジェットを共有する場合があります。

準備処理は拒否専用です。OpenClaw は新しいルート、セッション、コマンドの受け入れを閉じ、自動 Cron ティックを一時停止し、処理を同期的に調査します。何かがアクティブな場合は、busy を返す前にスケジューラーを再開して受け入れを再開します。その処理を中断したり、完了まで待ったりすることはありません。準備完了リースは 2 分間継続します。同じ requestId で prepare を繰り返すとリースが更新されます。期限切れ時には、受け入れを再開する前にスケジューラーが再開されます。 準備完了リース中に期限を迎えた再起動通知は、リースが再開されるまで待機します。実行中の再起動がある場合、準備処理は busy を返します。

準備完了中も /healthz は稼働を維持し、/readyz は 503 を返します。ローカルまたは認証済みの準備状態応答には gateway-draining が含まれます。認証されていないリモートプローブには { "ready": false } だけが返されます。HTTP ヘルスプローブ、既存の WebSocket 接続上のサスペンドメソッド、すでに有効化されている Admin HTTP RPC ルートは引き続き利用できます。その他の RPC は再試行可能な UNAVAILABLE を返します。OpenAI 互換 API、ツールおよびセッション操作、Node ウォッチ、構成済みフックを含む、組み込みの HTTP ユーザー処理ルートと通常の Plugin HTTP ルートは、error.code: "gateway_unavailable" とともに 503 を返します。Plugin が所有する新しい WebSocket アップグレードも 503 を返します。これはアップグレードの所有権を対象とし、確立済みの Plugin ソケット上で後から実行される処理は対象外です。

このハンドシェイクは受信メッセージを永続化せず、サードパーティーのチャンネルトランスポートを停止せず、ホスティングプラットフォームを制御しません。ホストは準備前に受信を遮断する必要があり、ウェイク、スナップショットまたは凍結、停止について引き続き責任を負います。activeCount は追跡対象処理の総数であり、blockers にはゼロ以外のカテゴリ別件数と、上限付きのタスク詳細が含まれます。これは汎用的なプロセス静止バリアではありません。background-exec ブロッカーは集計値のみです。コマンドテキスト、プロセス ID、出力、セッション識別子またはスコープ識別子がプロトコルを通過することはありません。チャンネルの健全性確認、メンテナンス、キャッシュ更新、確立済みの Plugin WebSocket セッション、未登録の Plugin 所有バックグラウンド処理は、アクティブなままになる場合があります。 ホスティングプラットフォームは、プロセスツリー全体とそのファイルシステムを一貫して凍結またはスナップショットする必要があります。この最初のコントラクトでは、未登録の処理がアイドル状態であることを証明できません。

アプリコードと Plugin コード

コードが OpenClaw の外部にある場合は Gateway RPC を使用します。

  • エージェント実行を開始または監視する Node スクリプト
  • Gateway を呼び出す CI ジョブ
  • ダッシュボードと管理パネル
  • IDE 拡張機能
  • チャンネル Plugin になる必要がない外部ブリッジ
  • 偽または実際の Gateway トランスポートを使用する統合テスト

コードが OpenClaw 内で実行される場合は Plugin SDK を使用します。

  • プロバイダー Plugin
  • チャンネル Plugin
  • ツールまたはライフサイクルフック
  • エージェントハーネス Plugin
  • 信頼済みのランタイムヘルパー

外部アプリでは openclaw/plugin-sdk/* をインポートしないでください。これらのサブパスは OpenClaw が読み込む Plugin 用です。

関連項目

Was this useful?
On this page

On this page