Gateway

Gateway クライアントの構築

公開済みの Gateway パッケージを使用して、オペレーターダッシュボード、WebChat クライアント、その他のサードパーティアプリケーションを構築します。このガイドでは、通信プロトコルに関するクライアントのライフサイクル（認証、機能、再接続からの復旧、履歴、サブスクリプション、バージョンアップ）について説明します。

フレーム形式、ハンドシェイク、エラー、完全なメソッド一覧については、 Gateway プロトコル仕様を参照してください。

パッケージのインストール

bash

npm install @openclaw/gateway-client @openclaw/gateway-protocol

@openclaw/gateway-protocol は、スキーマ、ランタイムバリデーター、TypeScript 型、クライアント ID と機能のレジストリ、構造化エラーの読み取り機能、プロトコルバージョン定数を提供します。 npm tarball には、生成済みの機械可読コントラクトである protocol.schema.json も含まれます。
@openclaw/gateway-client は、リファレンス接続実装です。Node クライアントにはパッケージルートを、ブラウザーで安全に使用できるプロトコル、デバイス認証、再接続ヘルパーには @openclaw/gateway-client/browser をインポートしてください。

Node エントリは自身の WebSocket トランスポートを管理します。ブラウザーホストは、 WebSocket アダプターに加えて、デバイス ID とデバイストークン用の永続ストレージおよび署名コールバックを提供します。

スコープの選択とデバイスのペアリング

承認プロンプトも表示する完全な対話型チャットクライアントでは、次のスコープを指定して role: "operator" を要求する必要があります。

スコープ	用途
`operator.read`	`chat.history`、`sessions.list`、`sessions.subscribe`、モデルステータス、読み取り専用イベント
`operator.write`	`chat.send` と通常のセッション変更
`operator.approvals`	exec または Plugin の承認の一覧表示、表示、解決

クライアントが対話型の質問を処理する場合にのみ operator.questions を、ペアリング済みデバイスまたは Node を管理する場合にのみ operator.pairing を、 config.patch などの管理操作を行う場合にのみ operator.admin を追加してください。オペレータースコープのリファレンスでは、メソッドと承認時のルールがすべて定義されています。

openclaw.json を手動編集してクライアントごとのベアラートークンを作成しないでください。 openclaw configure --section gateway または openclaw onboard --gateway-auth ... オプションを使用して Gateway の共有ブートストラップ認証を設定し、デバイスのペアリングによってクライアントトークンを発行させます。

Ed25519 デバイス ID をクライアントに永続化します。
connect.challenge を待ち、チャレンジに紐付けられたデバイスペイロードに署名して、要求するオペレーターのロールとスコープ、およびブートストラップ認証用の共有 Gateway トークンまたはパスワードを指定して connect を送信します。
Gateway が構造化された PAIRING_REQUIRED の詳細を返した場合は、リクエスト ID を表示し、error.details.recommendedNextStep に従って一時停止または再試行します。
Gateway ホスト上で openclaw devices list を使用してリクエストを確認し、 openclaw devices approve <requestId> を使用して、その時点の該当リクエストのみを承認します。
再接続し、ネゴシエートされたロールとスコープとともに hello-ok.auth.deviceToken を永続化します。以降の接続では、そのデバイストークンを使用します。

スコープまたはロールをアップグレードすると、新しい保留中のペアリングリクエストが作成されます。トークンをローテーションしても、承認済みのペアリングコントラクトを拡張することはできません。承認、ローテーション、失効のコマンドについては、デバイス CLIを参照してください。

クライアント機能の通知

connect.params.caps は、クライアントが利用できるオプション動作を記述します。認可を付与するものではありません。文字列リテラルを重複して記述せず、 GATEWAY_CLIENT_CAPS から名前をインポートしてください。

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

現在のレジストリには、approvals、exec-approvals、inline-widgets、 run-tool-bindings、session-scoped-events、plugin-approvals、 task-suggestions、terminal-offset-seq、tool-events、ui-commands が含まれます。クライアントが実際に実装している機能のみを通知してください。

機能によって制限されるエージェントツールは、同じ宣言を別の目的で使用するものです。エージェントツールがクライアント機能を必要とする場合、接続元クライアントが必要なすべての機能を通知していなければ、Gateway はそのツールを省略します。

再接続後の状態復旧

成功した再接続はすべて、永続履歴と現在のメモリ内実行状態に基づく新しいプロジェクションとして扱います。

sessions.subscribe と、選択したセッションの sessions.messages.subscribe サブスクリプションを再確立します。
選択した sessionKey に対して chat.history を呼び出し、ローカルに永続化された行を、返された messages プロジェクションで置き換えます。
inFlightRun が存在する場合は、その runId、バッファー済みの text、および任意の plan を採用します。 text が空の場合でも、その実行を採用します。
sessionInfo.hasActiveRun と sessionInfo.activeRunIds を読み取ります。保持された実行が引き続きストリーミング UI を所有しているかを判断する際は、activeRunIds への完全一致を優先してください。ID が列挙されていない状態で hasActiveRun が true の場合、別のアクティブなランタイムプロジェクションを表すことがあります。
以降の agent イベントを、payload.runId と payload.seq に基づいて整合させます。実行ごとに、受け入れた最大シーケンスを個別に保持し、確認済みまたはそれ以下のシーケンスを無視し、前方の欠落がある場合は正規の履歴を再読み込みします。

外側のイベントフレームにも任意の seq があり、現在の WebSocket 接続上のイベント順序を示します。新しい接続になるとリセットされます。agent イベントのペイロード内にある seq は実行ごとに割り当てられ、その実行のライフサイクル、アシスタント、計画、ツール、その他のストリームイベントの順序を示します。

履歴メタデータと安定したアンカーの使用

chat.history が返す行には、__openclaw メタデータエンベロープが含まれる場合があります。

id はトランスクリプトエントリの ID です。アンカー付き履歴リクエストに使用しますが、一意な表示行キーとしては使用しないでください。
seq は正のトランスクリプトレコードシーケンスです。1 件の保存レコードが複数の表示行に投影される場合があるため、同じ id とシーケンスを持つ兄弟行をまとめて保持してください。
kind は合成行を識別します。Compaction 境界では kind: "compaction" が使用され、一致するチェックポイントにそれらのメトリクスが記録されている場合は、 tokensBefore と tokensAfter が含まれることがあります。

レスポンスの hasMore と nextOffset の値を使用して、過去方向にページングします。数値オフセットは現在のトランスクリプトプロジェクションを表すため、リセットや Compaction をまたぐ長期的なブックマークとして永続化しないでください。代わりに __openclaw.id を永続化します。既知の行の周辺を復元するには、messageId と、それを返した sessionId を指定して chat.history を呼び出します。Gateway はリセットアーカイブ履歴からそのアンカーを解決できます。アンカー付きレスポンスでは、意図的に数値ページングメタデータが省略されます。

ポーリングではなくサブスクリプションによる使用量の取得

sessions.list を使用して初期カタログを読み込み、接続ごとに sessions.subscribe を 1 回呼び出します。sessions.changed イベントを sessionKey に基づいてマージします。セッション変更ペイロードには、ライブの inputTokens、outputTokens、 totalTokens、totalTokensFresh、contextTokens、estimatedCostUsd、レスポンス使用量設定、アクティブな実行状態が含まれる場合があります。

一部の変更通知は無効化シグナルにすぎません。イベントでビューに必要な行フィールドが省略されている場合は、 sessions.list を更新してください。ライブセッションリストを最新に保つ目的で usage.cost または sessions.usage をポーリングしないでください。これらのメソッドは、オンデマンドの集計レポートまたは詳細レポートにのみ使用してください。

exec 承認のバックフィル

operator.approvals を持つクライアントは、hello-ok が完了したら直ちにイベントリスナーを登録し、その後 exec.approval.list を呼び出して、接続前から存在するリクエストをバックフィルする必要があります。リストとライブの exec.approval.requested / exec.approval.resolved イベントを承認 ID に基づいて整合させ、リストリクエストと競合する遷移が失われたり復活したりしないようにします。

プロトコルバージョンの追跡

現在の通信バージョンは 4 です。一般的なオペレータークライアントおよび WebChat クライアントは、minProtocol: 4 と maxProtocol: 4 を使用して、現在のバージョンと完全に一致するようネゴシエートする必要があります。 N-1 の許容範囲があるのは、認証済み Node クライアントと軽量プローブのみであり、現在はプロトコル 3 から 4 までです。

プロトコルの変更は、まず追加的に行われます。protocol.schema.json には、 since のリリース時期メタデータとコアメソッドに必要なスコープメタデータが含まれますが、通信バージョンの更新は、サードパーティクライアントにとって依然として明示的な破壊的変更です。テストしたパッケージバージョンを固定し、通信バージョンが変更された場合はクライアントと Gateway を同時にアップグレードし、アップグレードのたびに OpenClaw の変更履歴を確認してください。