Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

ID: ADR-007 タイトル: ゲートウェイを独立したオプションのプロセスとして分離する 日付: 2026-07-18 ステータス: 提案中 関連:

  • ADR-002
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • crates/zeroclaw-gateway
  • crates/zeroclaw-runtime/src/rpc

ADR-007: ゲートウェイを独立したオプションのプロセスとして分離する

コンテキスト

ZeroClaw の HTTP、WebSocket、webhook、およびダッシュボードのサーフェスには、すでに専用の zeroclaw-gateway クレートがあります。メインアプリケーションは引き続き、gateway フィーチャーの背後でそのクレートを同一プロセス内にリンクして起動します。クレート境界によりコードのオーナーシップは向上しますが、プロセス分離は提供されず、オペレーターがエージェントランタイムから独立して Web サーフェスを実行、再起動、アップグレード、または省略できるようにもなりません。

ランタイムには JSON-RPC サーフェスもありますが、外部ゲートウェイに必要な、完全で安定したローカルコントラクト、トランスポート、認証モデル、互換性ポリシー、プロセス監視は、サポート対象の単一の境界としてまだ提供されていません。したがって、現在のクレートと RPC の接合部は、プロセスの切り出しが完了したことの証明ではなく、移行手順として有用です。

代替案は、インプロセスのフィーチャーゲート付きクレートを最終的なアーキテクチャとして扱うこと、またはゲートウェイを明示的なローカル IPC コントラクトを通じてランタイムに接続される別個のオプションプロセスにすることです。

決定

ゲートウェイを独立したオプションの zeroclaw-gw プロセスにする予定です。

エージェントランタイムは、エージェントの実行、セッション、メモリ、構成、ツール、セキュリティポリシー、およびその他のドメイン状態に対する権限を引き続き保持します。ゲートウェイは、外部のHTTPおよびストリーミングプロトコル、ダッシュボードの配信、ペアリングとトランスポート側の関心事、そして汎用的なwebhookイングレスを管理します。ゲートウェイは、プロセスローカルなランタイム状態に直接アクセスするのではなく、サポートされているIPCコントラクトを通じてランタイム操作を要求する必要があります。

ランタイムとゲートウェイ間の IPC 境界は、認証され、バージョン管理され、文書化されている必要があります。トランスポートの選択はプラットフォームによって異なる場合がありますが、デフォルトの接続はローカルのままでなければならず、ランタイムの制御インターフェイスをパブリックインターフェイス上に暗黙的に公開してはなりません。

現在の機能フラグで制御されているインプロセスの zeroclaw-gateway クレートは、中間的な継ぎ目です。IPC の同等性とプロセスライフサイクルのサポートが構築される間は引き続き利用可能な状態を維持できますが、新しいアーキテクチャでは、ランタイム内部への直接アクセスをゲートウェイの永続的な要件にしてはなりません。

運用者は zeroclaw-gw なしでエージェントを実行できなければなりません。ゲートウェイの障害や再起動によって、それ以外は正常なエージェントの実行が終了してはなりません。

この ADR は、以下の条件をすべて満たすまで提案中のままです：

  • サポートされている zeroclaw-gw バイナリは、ドキュメント化されたローカル IPC 契約を通じてランタイムと通信します。
  • IPCバウンダリは、プロセスローカルな状態への直接アクセスなしに、サポートされているダッシュボードおよびAPIエクスペリエンスに必要なゲートウェイ機能をカバーします。
  • 認証、バージョンネゴシエーション、再接続、ヘルスチェック、起動、シャットダウンの動作が実装され、文書化されており、さらに
  • サポートされているランタイムディストリビューションは、ゲートウェイサーバーにリンクしたり、ゲートウェイサーバーを起動したりせずに動作できます。

結果

肯定的な結果:

  • ヘッドレスおよび制約付きデプロイメントでは、ウェブサーフェスを完全に省略できます。
  • ゲートウェイのクラッシュ、再起動、アップグレードはエージェントの実行から分離されています。
  • IPCコントラクトは、デスクトップアプリケーションやその他の信頼されたローカルクライアントに対して、明確な統合境界を提供します。
  • クロス境界アクセスが明示的になるため、ランタイムとゲートウェイの所有権がテストしやすく、把握しやすくなります。

否定的な結果:

  • マルチプロセスでのインストール、起動、認証、ロギング、診断は、プロセス内の関数呼び出しよりも複雑です。
  • ストリーミングと大容量のペイロードは、シリアル化された境界を越える必要があります。
  • ランタイムとゲートウェイのバージョンが異なる可能性がある場合は、常に互換性ポリシーが必要です。
  • 同等性が完全に達成されるまで、メンテナーは現在のインプロセスシームと目標のプロセス境界の両方をサポートする必要があります。

参照