ZEGA AI（外部プロトタイプ）

ZEGA AI は、TypeScript ブリッジパッケージ (@zega/zeroclaw-bridge) を介して ZeroClaw v0.8.x ゲートウェイデーモンに接続する外部のフィンテックプラットフォームです。このブリッジは ZEGA モノレポで保守されている外部プロトタイプであり、ZeroClaw 自体の一部ではありません。

Status: プロトタイプ。ブリッジは、ローカルのヘルパーモジュール（SemVer の解析、エラー階層、オフライン耐性）に対してスモークテスト済みです。稼働中のデーモンとのペアリングやエンドポイントテストは、まだ実行されていません。以下の情報はブリッジの設計意図を説明するものであり、本番環境との互換性が検証済みであることを示すものではありません。

ペアリング

Gateway URL 設定に関する注意: ブリッジクライアントのデフォルトは http://127.0.0.1:4242 ですが、ZeroClaw の正規の GatewayConfig のデフォルトポートは 42617 です。標準のローカル ZeroClaw デーモンに接続する場合は、一致するゲートウェイアドレスをクライアントに設定します:
const client = new ZeroClawGatewayClient({
  gatewayUrl: "http://127.0.0.1:42617",
});
ゲートウェイポートを稼働中の ZeroClaw デーモンに合わせずに接続すると、ペアリングが行われる前にブリッジがオフライン/到達不能状態を報告します。

リモートから到達可能なゲートウェイでは、Authorization ヘッダーで送信されるベアラー認証情報を保護するため、平文の HTTP ではなく HTTPS または認証済みトンネル（WireGuard、Tailscale、SSH トンネルなど）を使用してください。

ブリッジは、ZeroClaw ゲートウェイが公開する 2 つのペアリング契約を実装し、順番に試行します:

拡張されたルート: `POST /api/pair`

JSON 本文を受け付けます:

{
  "code": <6 桁のペアリングコード>,
  "device_name": "ZEGA AI Bridge",
  "device_type": "api-bridge"
}

成功すると、ゲートウェイは { "paired": true, "token": "<bearer>" } を返します。ブリッジは以降の認証済みリクエスト用にトークンを保存します。

上流ハンドラー: api_pairing::submit_pairing_enhanced (crates/zeroclaw-gateway/src/api_pairing.rs)。

レガシールート: `POST /pair`

ペアリングコードを X-Pairing-Code ヘッダーで送信します:

POST /pair
Content-Type: application/json
X-Pairing-Code: <6-digit code>

拡張エンドポイントが利用できない場合、またはレート制限以外の非成功ステータスを返した場合、ブリッジはこのルートにフォールバックします。拡張エンドポイントがレート制限エラー（RateLimitError）を返した場合、ブリッジは従来のフォールバックを試行せず、直ちにエラーを再スローします。

上流ハンドラー: handle_pair (crates/zeroclaw-gateway/src/lib.rs)。

ブリッジアーキテクチャ

コンポーネント	役割
`ZeroClawGatewayClient`	HTTP クライアントは、リクエストおよびヘルスチェックのデフォルトタイムアウトを5秒に設定し、`AbortController` によるキャンセルと指数バックオフによる自動リトライを備えています。デーモンに到達できない場合は、オフラインエラー状態にフォールバックします。
`ZeroClawAuthManager`	ペアリングフロー（拡張 → レガシーフォールバック）を管理し、認証済みエンドポイント用の `Authorization: Bearer <token>` ヘッダーを生成します。
バージョンマトリックス	数値範囲 `>=0.8.0 <0.9.0`（対象 `v0.8.3`）を対象とするクライアント側のバージョンチェック。現在のクライアントヘルパーは比較前にプレリリースサフィックスを除去し、数値コンポーネント（`major.minor.patch`）を評価します。この範囲は設計意図を反映したものであり、稼働中のデーモンに対して検証されていません。

スモークテストの対象範囲

ブリッジにはスモークテスト（pnpm --filter @zega/zeroclaw-bridge test:smoke）が付属しており、18 個のアサーションで、以下の オフライン／ユニットレベル の動作を検証します：

SemVer の解析と比較。
バージョン互換性の境界（互換性あり、古すぎる、最大値超過）。
Auth-manager のトークン保存、Bearer ヘッダーの構築、オフライン時の getState() の動作。
Gateway のエラーコンストラクターとフィールド。

スモークテストは ZeroClaw デーモンを起動したり、ペアリングコードを交換したり、HTTP 経由でゲートウェイエンドポイントを呼び出したり しません。

この処理では、拡張版からレガシー版へのペアリングフォールバックや、レート制限エスカレーションの分岐は実行されません。

外部参照

ソースコードとモノレポの詳細については、ZEGA AI リポジトリを参照するか、レビュー済みコミット f99104367a6b06815cf478120b247d042fa7b1a5のブリッジパッケージを確認してください。

Keyboard shortcuts

ZeroClaw Docs