20 KiB
ClawXのアーキテクチャ
このドキュメントは、READMEの「アーキテクチャ」セクションの詳細版です。
ClawXは 統合Host APIレイヤーを備えたデュアルプロセスアーキテクチャを採用しています。Rendererは単一のクライアント抽象を呼び出し、プロトコル選択とプロセスライフサイクルはElectron Mainが管理します。
OpenClawの設定配信もElectron Mainが管理します。Gateway実行中はconfig.getが返す権威あるスナップショットを基準にし、変更をconfig.setでコミットします。Gatewayが停止中または起動中の場合は、同じコーディネーターが解決済みJSON5設定ファイルを更新しますが、これを理由にGatewayを起動することはありません。そのため、通常のプロバイダー、Agent、チャネル、バインディング、スキル、モデルの変更ではGatewayプロセスを置き換えません。完全な再起動は、プロキシなどのプロセス起動環境の変更と、ユーザーによる明示的な操作に限られます。確認済みのプロセス終了とWebSocket切断では、既存の自動再接続経路が引き続き使用されます。WebSocketハートビートの連続3回までの欠落は診断のみとし、短いpong遅延で長時間実行中の処理を中断しません。pongまたは任意の受信メッセージでカウントをリセットし、4回連続で欠落した場合に、ライフサイクルが自動復旧可能なrunning状態であれば、保護されたGateway自動復旧を要求します。認証設定をSQLiteへ書き込んだ後はOpenClawのsecrets.reloadを呼び出し、実行中のAgentがプロセス再起動なしで新しい認証情報を読み取れるようにします。
ChatはElectron Mainが所有するACP stdio bridgeを使用します。Mainはアプリが管理するGateway tokenをプライベートなプロセス環境経由でローカルの子プロセスへ渡すため、ランタイム設定の再読み込み後もACP履歴リプレイの認証が維持されます。保護されたGateway復旧が受理済みのメインセッションrunを中断した場合、パッチ済みOpenClawランタイムは別の復旧runを開始し、中断されたrun idを明示的なlineageとして保持します。Chat eventとagent eventはそのlineageを維持し、再接続したACP bridgeはpending promptを新しいrunへ引き継ぎ、run単位のストリームカーソルをリセットしてセッション単位のtool eventを購読します。RendererはGatewayランタイムの識別子を認識せず、型付きhost eventから同じメモリ内ACP timelineを描画し続けます。Gatewayはproviders、models、skills、workspace、settings、diagnostics、media configurationなどの非Chat機能を引き続き担当します。
ACPのセマンティック権威
ACPが提供するすべてのChatの意味とコンテキストでは、session/load履歴だけでなくACPを優先的なセマンティック権威として扱います。該当する場合のセッションIDとルーティング、ワークスペースと実行cwd、promptとtimelineの状態、標準resourceや添付ファイルのセマンティクスが含まれます。ACPが値やイベントを提供する場合、MainとRendererはGatewayスナップショット、transcriptからの推論、ローカル設定、別の並列投影で置き換えず、ACPの結果を使用します。
上流ACPに相当する機能がない場合に限り、ACPを迂回できます。その互換性パスは狭く有界で、sessionとgenerationに紐付ける必要があります。また、理由、情報源、制限、調整方法、削除条件を該当するHarness referenceまたはruleに記録し、競合する権威へ暗黙に発展させてはいけません。
ACP履歴の権威と有界なtranscript補足
ACP session/load のリプレイがChat履歴の主要な権威です。ClawXは第二のACP ledger、縮約timeline、リプレイキャッシュ、再構成したツール履歴を永続化しません。OpenClawの構造化ACP event ledgerが利用できない場合、そのACP adapterは永続化済みtranscriptのtoolCallとtoolResultを順番どおりにネイティブなtool updateへ再構成し、text-tool-textの境界を維持します。ClawX自身はこれらの記録を推論しません。OpenClawの一部の機能にはまだ完全に対応するACP実装がありません。たとえば、assistantメディアがACPから省略されたり、Gateway処理によってassistantのMEDIA:ディレクティブが表示中のライブ返信から削除されたりする場合があります。そのため、ClawXは有界で印付き、メモリのみの互換性補足だけを保持します。
- 非同期の画像生成完了は、同じセッションに確認済みの
image_generateコンテキストがあり、完了の証拠が信頼できるか、承認済みのtranscript証拠である場合に限り復元できます。 - 一般の添付ファイルは、永続化されたassistantの
__openclaw.media事実、または行頭にある明示的なassistantMEDIA:ディレクティブから復元できます。復元されるのは添付ファイルの参照と宣言されたメタデータだけで、周囲のassistantメッセージは復元しません。 - ACPリプレイには元のイベントタイムスタンプがないため、Mainは有界のtranscript JSONLレコードからメタデータのみのターン全体の時間を追加できます。これはACPですでに復元されたターンにだけ付与できます。
- cronセッションのACPリプレイが完全に空の場合、Mainの型付きcron履歴APIがスケジュール済みプロンプトと完了サマリーを提供できます。識別された実行サマリーにOpenClawの切り詰めマーカーがある場合、対応するrunのtranscriptがより長く、永続化されたサマリーの完全な接頭辞を共有するときに限り、Mainは最終assistantテキストを復元できます。
履歴の読み取りは最新のtranscriptメッセージ1000件に制限されます。成功したライブpromptでは直ちに1回読み取り、1500ms後に1回だけ再試行します。すべての補足は、正確なsession、ACP generation、操作、必要に応じてライブユーザーターンに紐付けられます。古い、欠落した、重複した、または曖昧な一致は破棄されます。これらの経路で通常のassistantメッセージ、thought、tool、plan、permission、ファイルアクティビティ、欠落したターン、別のChat履歴を再構成してはいけません。Mainはtranscriptの証拠からネイティブACPイベントを生成しません。標準ACP resourceが優先され、上流が同等の内容を提供した場合はこれらの互換性例外を削除します。
別の会話やページを開いても、未完了のACP応答はストリーミングを継続します。完了前に戻ると最新のメモリ内timelineを復元し、ライブ応答の表示を続けます。完了後は通常のACP履歴リプレイが正の情報源です。
ACPのassistantターンにはターン全体の所要時間が表示されます。ライブ計時はクライアントが観測したpromptライフサイクルに従い、アプリ内の移動後も継続します。履歴の所要時間はElectron Mainが有界のOpenClaw transcriptタイムスタンプから算出し、ACPリプレイですでに復元されたターンにだけ付与します。
ACP Chatは標準ACP resourceを添付ファイルとして描画します。ユーザーが選択した画像はファイル名をホバーオーバーレイに表示するサムネイルになり、その他の利用可能な添付カードにはファイル名と淡色で省略可能なソースパスが表示されます。現在のOpenClaw ACP adapterがassistantメディアを省略した場合、正規化された永続OpenClawメディア情報と明示的なassistant MEDIA:ディレクティブを、transcript専用メタデータを表示せずに添付カードとして復元できます。
既存のローカルファイル参照は、アクティブなworkspace外のパスを含め、プレビューやオープンのたびにElectron Mainが正確なsessionとgenerationについて再検証します。AIが生成したプレビュー可能なローカル添付（20 MB以下の.docxと.pptxを含む）は、読み取り専用のアプリ内プレビューを主操作として保持し、対応アプリで開く操作やFinder、エクスプローラー、システムのファイルマネージャーで表示する操作を副次メニューから選べます。ローカルHTML添付では、そのメニューの先頭項目から右側のPreviewタブでファイルを開けます。
Officeプレビューには同じ制限があります。.docと.pptはシステムアプリで開き、DOCXのページ区切りはMicrosoft Wordと異なる場合があり、PPTXのアニメーション、画面切り替え、メディア再生はサポートされません。対応アプリの検出はmacOSとWindowsでのみ利用でき、Linuxまたは検出失敗時は通知なしにファイル位置の表示だけへ切り替わります。その他のローカルファイル（20 MBを超えるOfficeファイルを含む）は、クリック後にシステムアプリで開きます。ユーザーが選択したフォルダー添付は送信後も利用でき、クリックするとシステムのファイルマネージャーで開きます。ClawXはその内容を読み取ったりプレビューしたりしません。リモートHTTP/HTTPS添付はクリック後に外部で開きます。正規のメディア情報を伴わない通常の文章中のパスは添付として扱われません。
ACP Chatは、ランタイムが画像生成メディアを信頼できる構造化メディアとして配信した場合、生成画像のプレビューも表示できます。信頼できるOpenClaw internal-UI配信と画像生成タスクに紐付いた最終返信では、テキストだけの失敗説明を含む元のユーザー向け完了テキストを保持し、汎用画像キャプションに置き換えません。OpenClawの履歴リプレイ中、assistant画像のMEDIA:マーカーは、同じセッションで画像生成タスクの開始が記録されている場合に限りインライン画像へ昇格します。プレビューは任意のRendererファイルシステムアクセスではなく、Electron Mainのホストメディア処理で読み込みます。標準ACPの画像とresourceコンテンツが引き続き優先され、そのまま描画されます。
ACPファイルアクティビティのセマンティクス
- ファイルアクティビティは、成功して完了したOpenClawの
write、edit、apply_patch呼び出しから投影されます。ツール認識は公式OpenClaw Chat UIに従い、完了した呼び出しだけに絞る処理はClawX固有です。 - 作成・変更された行は、プレビュー可能なassistant添付と同じファイルカードとOpen withメニューを使い、状態と任意の
+/-概要を保持します。HTMLではメニューの先頭項目が右側のPreviewタブでファイルを開きます。削除行には Changes 操作だけを残します。アプリ一覧、選択アプリで開く操作、表示位置の要求は、workspaceルートと相対パスからElectron Mainが個別に再検証します。ツール由来のパスは添付にならず、Rendererへ正規化済みのネイティブパスも公開されません。 writeはツールの宣言どおり、対象パスがすでに存在する可能性があっても、作成および全行追加の差分として表示されます。- Changes はツールが宣言したアクティビティを時系列に記録するセッション単位の記録です。Gitの出力でも、検証済みソースベースラインとの差分でもありません。
- 各ファイルについて、Changesはassistantの各ターンに最大1つのdiffエディターを表示します。安全に連結できる断片は合成し、独立した断片は1つのエディターに連結しますが、完全なファイルベースラインとの差分とはみなしません。
- シェルコマンド、スクリプト、ユーザー、IDEによる副作用は検出されません。
- 完全なACPリプレイから記録済みのファイルアクティビティを復元できます。リプレイが不完全でも、ClawXはフォールバック推論で欠落を補いません。
┌──────────────────────────────────────────────────────────────────┐
│ ClawX デスクトップアプリ │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Electron メインプロセス │ │
│ │ • ウィンドウとアプリケーションのライフサイクル管理 │ │
│ │ • Gatewayプロセスの監視 │ │
│ │ • システム統合（トレイ、通知、キーチェーン） │ │
│ │ • 自動更新のオーケストレーション │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬───────────────────────────────────┘
│
│ IPC（権威ある制御プレーン）
▼
┌──────────────────────────────────────────────────────────────────┐
│ React Rendererプロセス │
│ • モダンなコンポーネントベースUI（React 19） │
│ • Zustandによる状態管理 │
│ • 統一host-api/api-client呼び出し │
│ • assistant返信はMarkdown、ユーザー入力はプレーンテキスト │
└──────────────────────────────┬───────────────────────────────────┘
│
│ 型付きIPCリクエスト
▼
┌──────────────────────────────────────────────────────────────────┐
│ Main Host ServicesとGateway Manager │
│ • host:invoke型付きサービスディスパッチ │
│ • 設定、ファイル、セッション、スキル、プロバイダー、診断 │
│ • Main所有のGateway WebSocketとプロセス監視 │
└──────────────────────────────┬───────────────────────────────────┘
│
│ Main所有WebSocket
▼
┌──────────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ • AIエージェントランタイムとオーケストレーション │
│ • メッセージチャネル管理 │
│ • スキル/プラグイン実行環境 │
│ • プロバイダー抽象化レイヤー │
└──────────────────────────────────────────────────────────────────┘
設計原則
- プロセス分離：AIランタイムは別プロセスで動作し、重い計算中もUIの応答性を保ちます。
- フロントエンド呼び出しの単一入口：Rendererのリクエストは
host-api/api-clientを経由し、プロトコルの詳細は安定したインターフェースの背後に隠されます。 - Mainプロセスによるトランスポート管理：Electron MainがACP Chat stdio bridgeとGatewayトランスポートを所有し、Rendererは型付きIPCでMainと通信します。
- 拡張IPCの貢献点：Mainプロセス拡張はHTTP routeではなく、型付きIPCレジストリを通じてhost-api actionを提供します。
- グレースフルリカバリ：再接続、タイムアウト、バックオフを内蔵し、一時的な障害を自動処理します。
- セキュアストレージ：APIキーや機密データにはOSのネイティブな安全な保存機構を使用します。
- CORSセーフ設計：RendererはローカルGatewayやHost API HTTPエンドポイントを直接呼び出しません。
プロセスモデルとGatewayのトラブルシューティング
- ClawXはElectronアプリのため、1つのアプリインスタンスでも複数のOSプロセスが表示される（main/renderer/zygote/utility）のは正常です。
- 単一起動保護にはElectronのロックに加えてローカルのプロセスファイルロックのフォールバックを使用し、デスクトップIPCやセッションバスが不安定な環境での二重起動を防ぎます。
- ローリングアップグレード中に旧版と新版が混在すると、単一起動保護が非対称になる場合があります。安定性のため、すべてのデスクトップクライアントを同じバージョンへ更新してください。
- OpenClaw Gatewayのリスナーは単一所有者である必要があります。
127.0.0.1:18789をListenするプロセスは1つだけにしてください。 - Gatewayのreadinessは
system-presence、health、statusなどOpenClawのコア信号を基準にします。メモリまたはチャネルの失敗は、Gateway全体の障害ではなく機能低下として表示されます。 - アクティブなリスナーは次のコマンドで確認できます。
- macOS/Linux：
lsof -nP -iTCP:18789 -sTCP:LISTEN - Windows（PowerShell）：
Get-NetTCPConnection -LocalPort 18789 -State Listen
- macOS/Linux：
- ウィンドウの閉じるボタン（
X）はClawXをトレイに隠すだけで、完全終了ではありません。完全終了にはトレイメニューの Quit ClawX を使用してください。