ゲートウェイ 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 の構成状況にかかわらず、認証なしで公開するのは安全ではありません。
サーフェスの探索
ここでは「何ができるのか」という疑問に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 を含むもの）は、標準のプリフライトレスポンスを受け取り、スキーマ本体が返される前にショートサーキットされます。
プロパティ単位のCRUD
| 方法 | パス | 目的 |
|---|---|---|
GET | /api/config | 互換性のためのシークレットをマスクした設定全体のスナップショット。新しいクライアントはプロパティごとのサーフェスを優先してください。 |
PATCH | /api/config | JSON Patch (RFC 6902) ドキュメントをアトミックに適用します。 |
OPTIONS | /api/config | 設定全体の JSON スキーマ（値ではなく機能）。 |
GET | /api/config/prop?path=... | 1 つのフィールドを読み取ります。シークレットは {path, populated} のみを返します。 |
PUT | /api/config/prop | 1つのフィールドを書き込みます。本文: {path, value, comment?}。シークレットは {path, populated: true} のみを返します。 |
DELETE | /api/config/prop?path=... | 1 つのフィールドをデフォルトにリセットします。シークレットは {path, populated: false} を返します。 |
OPTIONS | /api/config/prop?path=... | フィールドごとのスキーマフラグメント。 |
GET | /api/config/list?prefix=... | 型とカテゴリを含む、到達可能なすべてのパスを列挙します。シークレットのエントリは {path, populated, is_secret: true} を持ち、値は含まれません。 |
POST | /api/config/init?section=... | デフォルト値で None のネストされたセクションをインスタンス化します。動的マップのエイリアスはここでは作成されません。POST /api/config/map-key を使用してください。 |
POST | /api/config/migrate | オンディスクのスキーマ移行をその場で適用します。zeroclaw config migrate をミラーリングします。 |
アトミックなバッチ書き込み: 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 で照合します。
| コード | ステータス | 意味 |
|---|---|---|
path_not_found | 404 | 要求されたプロパティはスキーマに存在しません。 |
validation_failed | 400 | 設定全体のバリデーターが、提案された状態を拒否しました。 |
dangling_reference | 400 | 設定されたエイリアス参照（例: agents.<x>.model_provider）が存在しないターゲット（例: providers.models.<type>.<alias>）を指定しています。 |
value_type_mismatch | 400 | 送信された JSON 値を対象の型に変換できません。 |
op_not_supported | 400 | JSON Patch の op が move / copy / 不明です。 |
secret_test_forbidden | 400 | JSON Patch の test 操作がシークレットパスを対象にしました。 |
config_changed_externally | 409 | ディスク上の設定がメモリ上のコピーから乖離しました。（ドリフト検出を参照してください。） |
reload_failed | 500 | 保存は成功しましたが、デーモンのリロードで新しい状態を読み込めませんでした。ディスク上の状態を元に戻しました。 |
internal_error | 500 | サーバー側で分類されていないエラーが発生しました。 |
ライブ探索
ゲートウェイが稼働したら、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 は、同じバッファに保持されている最近のイベントを古いものから順に再生します。これはサブスクライバーの再接続用ウィンドウであり、独立した正規のライフサイクルストアではありません。