ゲートウェイ HTTP API

ゲートウェイは、ローカルの CLI に加えて REST インターフェースを公開します。zeroclaw config get/set/list/init/migrate で設定できるものはすべて HTTP 経由でもアクセス可能であり、ダッシュボード、サードパーティ製ツール、CLI のいずれもが同一の基盤となる Config ミューテーションコアを操作します。

このページは概要レベルの説明です。現在ドキュメント化されている OpenAPI サブセットのフィールド単位の定義、リクエストとレスポンスの形式、および「Try it out」フォームは、稼働中のゲートウェイの /api/docs にあります。これらのスキーマはランタイム型から生成されますが、ルート一覧は別途構成されており、ゲートウェイに登録されているすべてのルートをまだ網羅していません。crates/zeroclaw-gateway/src/lib.rs のルーターが、実際に提供される全体の正式な情報源です。

Issue #6175 で追跡されています。

認証

このページで説明する構成値の読み取りと変更は、既存のペアリング認証およびベアラー認証によって保護されています。/api/docs、/api/openapi.json、および設定の OPTIONS を通じた API の形状確認は公開されています。初回実行時のペアリングコードはデーモンの起動時に出力されます。その後の認証済みリクエストでは、導出されたベアラートークンを Authorization ヘッダーで送信します。/api/docs の Scalar エクスプローラーには "Authentication" パネルがあり、認証済みリクエストを発行する前にトークンを貼り付けます。

デフォルトではローカルバインドされます。ネットワーク経由のアクセスには、ゲートウェイまたはその前段での TLS 終端が必要です。プロパティ単位のエンドポイントと PATCH エンドポイントは、TLS の構成状況にかかわらず、認証なしで公開するのは安全ではありません。

チャネルプラグインの Webhook 受信

WASMプラグインサポート付きのビルドでは、実行中かつ明示的に設定されたチャネルプラグインがそのパスを要求すると、GETとPOST /plugin/{path}が公開されます。これは生のトランスポート境界です。ゲートウェイはHTTPメソッド、生のクエリ、ボディのバイト列、小文字化されたUTF-8ヘッダーを保持し、型付きリクエストとしてコンポーネントのparse-webhookエクスポートに渡します。コンポーネントはスコープ付きのシークレットでプラットフォームからのリクエストを検証し、正規化されたメッセージか、明示的なチャレンジ応答のいずれかを返します。このリクエストがエージェントのターンをインラインで実行することはなく、応答がエージェントキューに入ることもありません。

請求されるパスは、1～64 文字の ASCII 英字、数字、ハイフン、アンダースコアで構成されなければなりません。重複した請求者や無効な請求者は、デーモンがランタイムのルーティングマップをアトミックに公開する前に拒否されます。

の処理がタイムアウトしました|十秒のリクエスト有効期間により、解析または配信がキャンセルされました。|

ゲートウェイは、この認証不要のサーフェスで、ゲスト、Wasmtime、シークレット、設定、ダウンストリームのエラー詳細を返すことはありません。これらの詳細は上限付きで記録され、プラグインの帰属情報とともにログに残されます。標準の64 KiBのゲートウェイボディ上限が適用されます。ゲストの認証後、ホストは冪等性予約と配信の前に、plugin.<alias> に対する現在のピアグループを適用します。安定したメッセージIDには、ルート名前空間付きの所有権安全な予約を使用します。処理中の重複リクエストは、早期に確認応答されることなく、コミットまたはロールバックを待機します。

サーフェスの探索

ここでは「何ができるのか」という疑問に2つのエンドポイントが答えます。

• OPTIONS /api/config は whole-config 型の JSON Schema を返します。ビルドごとに静的です。クライアントは ETag ヘッダーに基づいてキャッシュする必要があります。現在の Allow ヘッダーには、ルーターが登録していないレガシーの PUT がまだ列挙されています。
• OPTIONS /api/config/prop?path=<dotted> は、特定のパスに対応するスキーマフラグメントを Allow: GET, PUT, DELETE, OPTIONS とともに返します。パスがスキーマ内に存在しない場合は 404 を返します。

OPTIONS は機能を返します。GET /api/config/prop と GET /api/config/list はユーザーの現在値を返します。ダッシュボードのフォームは、読み込み時に一度 OPTIONS を発行して型と制約を把握し、次に GET でフィールドを設定し、その後 PUT/PATCH で書き込みます。互換性のための GET /api/config も、シークレットをマスクした構成全体のスナップショットを返すため、古いバンドル済みダッシュボードページが新しいゲートウェイに対して失敗することはありません。新しいクライアントは、フィールドのメタデータと明示的なシークレット処理を伴うため、プロパティ単位のサーフェスを優先すべきです。

CORSプリフライトリクエスト（Access-Control-Request-Method を含むもの）は、標準のプリフライトレスポンスを受け取り、スキーマ本体が返される前にショートサーキットされます。

GET /api/plugins は、ダッシュボードで使用される、認証済みかつ読み取り専用のパッケージカタログを返します。ホストが許可したインストール済みマニフェストと、既にキャッシュされているレジストリから、パッケージ名ごとに 1 行を生成し、その際には plugin install と同じ、ピン留めされていないレジストリ選択ルールを使用します。インストール済みの情報とレジストリの情報は分離されたままなので、クライアントはアップグレードが存在すると推測することなく、両方のバージョンを表示できます。このエンドポイントはレジストリへの取得も、いかなる変更も行いません。

このルートはすべてのゲートウェイビルドに存在します。WASMプラグインサポートがない場合は、404ではなく wasm_plugins_available: false と空のパッケージソースを返します。[plugins].enabled は実行時の状態ではなく、設定上の意図として報告されます。安定した issues コードにより、ソースの障害と有効な空のカタログを区別できます。詳細な診断情報はゲートウェイのログに残ります。レジストリのダウンロードURLおよびキャッシュされたレジストリURLは決して返されません。利用可能なレコードが公開するのは、無害な name@version のインストール識別子のみです。

Catalog discovery runs on a blocking worker because host admission reads and verifies installed WASM payloads. Only one scan runs at a time; a concurrent request receives 503 Service Unavailable and may retry. The endpoint does not cache admitted package state between requests.

Translated to Japanese:

カタログ探索は、ホストによる受け入れ処理がインストール済みの WASM ペイロードを読み取って検証するため、ブロッキングワーカー上で実行されます。スキャンは一度に 1 つだけ実行されます。同時リクエストには 503 Service Unavailable が返され、再試行することができます。このエンドポイントは、リクエスト間で受け入れ済みパッケージの状態をキャッシュしません。

プロパティ単位のCRUD

アトミックなバッチ書き込み: JSON Patch

PATCH /api/config は JSON Patch ドキュメント（RFC 6902）を受け付けます。サポートされている config 操作は add、replace、remove、test です。ZeroClaw はさらに config アノテーション用の comment 拡張も受け付けます。config 操作はインメモリコピーに対して実行され、すべての操作が適用された後、結果に対して Config::validate() が一度だけ実行されます。検証が通過した場合、新しい状態が永続化されてスワップインされます。いずれかの操作または最終検証が失敗した場合、ディスク上およびインメモリの状態はいずれも変更されません。comment アノテーションは保存後に非致命的なベストエフォートベースで適用されます。

move と copy は 400 op_not_supported を返します。これは安全な参照グラフの書き換えがこのサーフェスの対象外であるためです。#[secret] パスに対する test は secret_test_forbidden で拒否されます。差分的な結果がクライアントの読み取れる唯一のシグナルとなり、それが値を漏洩させてしまうためです。

パス構文: JSON Pointer (/agents/researcher/model_provider) またはドット形式 (agents.researcher.model_provider)。どちらも使用でき、サーバー側で正規化されます。

CLI に対応するのは zeroclaw config patch <file-or-stdin> で、ローカルの Config に対して同じ op セットを適用し、同じ構造化レスポンス形式を返します（スクリプト向けには --json）。

シークレット: HTTP経由の書き込み専用

プロパティ単位の読み取りでは、シークレットフィールド（スキーマで #[secret] または #[derived_from_secret] とマークされたもの）が公開されることはありません。そのレスポンスには {populated: bool} のみが含まれ、値、長さ、マスクされた代替表現、ハッシュは含まれません。互換性用の GET /api/config は代わりに、MaskSecrets を適用した後で設定全体をシリアライズするため、そこにシークレットフィールドが現れる場合も、マスクされたプレースホルダーとしてのみです。いずれの設定読み取りサーフェスも、基になるシークレット値を返しません。

PUT と PATCH は新しいシークレット値を書き込み、{populated: true} を返します。DELETE はそれをクリアし、{populated: false} を返します。いかなる方法でもシークレットを取得する HTTP パスはありません。

安定したエラーコード

エラーは安定した code フィールドと人間が読める message を含む JSON を返します。フロントエンドやスクリプトは code で照合し、UI は path で照合します。

ライブ探索

ゲートウェイが稼働したら、Scalar API エクスプローラーを開くには http://<gateway-host>:<port>/api/docs にアクセスしてください。未加工の仕様は、他の互換ビューア向けに /api/openapi.json で利用できます。

エクスプローラーの認証パネルは、仕様で宣言された bearerAuth スキームにバインドされます。ライブ呼び出しを実行する前に、ペアリングで取得したベアラートークンをそこに貼り付けてください。URL を開く CLI ショートカットは zeroclaw config docs です。

Scalarバンドルが CDN から読み込めない場合（オフライン／エアギャップ環境でのインストール）、ページは適切にデグレードし、/api/openapi.json の生の仕様を案内します。これにより、互換性のある任意のビューア（Insomnia、Postman、Swagger UI など）を使用できます。

イベントストリーム契約

GET /api/events は、観測可能なランタイムイベントの生の Server-Sent Events ストリームです。重複が排除された 1 ターンにつき 1 行のライフサイクルタイムラインではありません。

ゲートウェイハンドラ、Webhook処理、cron/ハートビート処理、エージェントループのオブザーバーはいずれも、ライフサイクル形式のイベントを同じブロードキャストパスに発行できます。クライアントは、このストリームを追記専用の観測ログとして扱うべきです。ダッシュボードでコンパクトなターンのタイムラインを表示したい場合は、各 agent_start、llm_request、agent_end フレームが一度だけ出現すると想定するのではなく、イベントペイロードに含まれる識別子でグループ化または重複排除すべきです。

GET /api/events/history は、同じバッファに保持されている最近のイベントを古いものから順に再生します。これはサブスクライバーの再接続用ウィンドウであり、独立した正規のライフサイクルストアではありません。