# QClaw の実装原理：OpenClaw をデスクトップアプリとして製品化する仕組み

製品せいひんとしての形かたちだけを見みると、QClaw は「OpenClaw にデスクトップの殻からをかぶせたもの」と理解りかいされやすい。しかし、現在げんざいの実装じっそうを見みると、QClaw がしていることはそれよりも多おおい。単に Web コンソールを表示ひょうじするのではなく、Electron のメインプロセスで OpenClaw ランタイムをホストし、さらに IPC、設定更新せっていこうしん、ロールバック、ログイン連携れんけいを通つうじて、一般いっぱんユーザーがそのまま使つかえるデスクトップアプリとして構成こうせいしている。

この記事では、抽象的ちゅうしょうてきなスローガンを繰くり返かえすのではなく、各セクションを確認かくにんできる手てがかりに落おとし込こむ。つまり、1つの IPC 名めい、1つの関数名かんすうめい、1つの設定せっていフィールド、または1つの状態遷移じょうたいせんいを基準きじゅんにして説明せつめいする。

一、まず結論を述べる。ただし証明できる部分だけに限る

現在の実装に基づくと、まず3つのことを確認できる。

1. QClaw は、OpenClaw の Web コンソールを単純にデスクトップウィンドウへ埋め込んでいるわけではなく、追加で Electron ホスト層とメインプロセスの制御ロジックを実装している。
2. このプロジェクトにおける OpenClaw は、書き換えられた「バックエンドサービス」ではなく、ホストされるローカル runtime であり、起動、設定、ホット反映はいずれも QClaw のメインプロセスによって調整される。
3. 設定ファイルは QClaw と OpenClaw をつなぐ中核的なインターフェースであり、ログイン、モデル切り替え、環境注入、移行、ロールバックは最終的に設定ライフサイクルへ落ちる。

コード上の事実：ブリッジ層は window.electronAPI.process.start、window.electronAPI.config.updateField、window.electronAPI.instance.getMode のような入口を直接公開している。

私の解釈：これは、QClaw が最初から Web ページを表示するだけのシェルではなく、明確なホスト能力の境界を持つデスクトップ制御面であることを示している。

境界：この節で証明できるのは、まだ「メインプロセスのホスト能力を持つ」という点までであり、これら数個の入口だけで、すべての runtime 挙動が QClaw によって引き受けられていると証明することはできない。

コードの手がかり：window.electronAPI.*（ブリッジ層）

二、QClaw は「OpenClaw を少し調整するもの」ではなく、それをホストしている

実装上の責務から見ると、QClaw が担っているのは runtime host であり、単なるデスクトップシェルではない。

デスクトップホスト側のパス解決と起動モジュールでは、OpenClaw はアプリ自身のパッケージ済みリソースディレクトリに配置され、デフォルト設定テンプレートも同じ内蔵リソース一式から来ている。これは、QClaw がユーザーに OpenClaw CLI を先に別途インストールさせ、それをついでに起動しているのではなく、OpenClaw を自分の bundled runtime として一緒に配布していることを意味する。

さらに OpenClaw のホスト管理ロジックを見ると、そこで行われているのは業務 API ではなく、典型的なランタイム托管作業である。設定の作成、テンプレートへのパッチ適用、旧 provider の移行、環境 URL の注入、OpenClaw プロセスの起動と管理。これはすでに「ガワをかぶせる」範囲を超えている。シェルはこれらを管理しない。ホストが管理する。

コード上の事実：現在の実装には getOpenClawPath()、getDefaultConfigSourcePath()、injectEnvUrls()、migrateLegacyDefaultProvider() といった関数が存在する。

私の解釈：これらの名前は、メインプロセスが OpenClaw の場所を知っているだけでなく、その設定と実行環境を準備する責任も持っていることを示している。これはホスティングであり、単純な呼び出しではない。

境界：これにより QClaw が runtime host の仕事をしていることは証明できるが、関数名だけからパッケージング戦略、インストール手順、アップグレード戦略のすべての詳細まで逆推定することはできない。

コードの手がかり：getOpenClawPath()、injectEnvUrls()（ホストサービス層）

三、実際の起動チェーン：フロントエンドが意図を出し、メインプロセスが runtime を編成する

現在の実装で直接対応づけられる呼び出し関係を図にすると、より近いのは次のような形になる：

flowchart LR
    UI[Renderer UI] --> PRELOAD[Preload bridge\nwindow.electronAPI]
    PRELOAD --> IPC[Main IPC handlers]
    IPC --> PM[Process manager]
    IPC --> CM[Config manager]
    PM --> HOST[OpenClaw host service]
    HOST --> GW[Bundled OpenClaw gateway process]
    CM --> CFG[openclaw.json]
    GW -.reads / reloads.- CFG

この図の要点は「階層がきれい」なことではなく、異なる責任を持つ二つのチェーンを分けていることにある：

• 一つは プロセスホスティングチェーン：メインプロセスがどのように OpenClaw を起動し監視するか
• もう一つは 設定反映チェーン：設定更新が最終的に gateway runtime にどう影響するか

preload ブリッジ層でフロントエンドが受け取るのは、明示的に列挙された管理対象 API 群であり、たとえばプロセス制御、設定アクセス、アプリ機能、インスタンス管理などである。これは、レンダリング層がファイルを直接読んだりプロセスを起動したりするのではなく、このホワイトリスト化された能力だけを経由できることを意味する。

一方、メインプロセスの IPC 登録層では、処理入口が一通り対応づけられる。プロセス起動、プロセス再起動、設定更新、マシン識別子の読み取り、ウィンドウ制御などは、すべてメインプロセスが一元的に引き受けている。ここで最も重要なのは「プロジェクトが IPC を使っている」ことではなく、QClaw が OpenClaw のライフサイクル、設定反映、ヘルスチェックをすべてメインプロセスに集約していることである。

コードの事実：process:start、process:restart、config:updateField、app:get-machine-id という IPC が存在する。

私の解釈：これらの IPC だけでも、レンダリング層は意図を出すだけで、実際のプロセス、設定、システム能力はメインプロセス側で実行されることを十分に示している。

境界：この節ではまだ完全な状態機械を展開していないため、「責任分離」は証明できるが、「すべての例外経路がメインプロセスに集約されている」ことまでは完全には証明できない。

コードの手がかり：process:start、config:updateField（IPC 登録層）

最短呼び出しチェーン：Renderer -> window.electronAPI.config.updateField() -> invoke('config:updateField') -> ConfigManager.updateField() -> willTriggerRestart() -> pauseHealthCheck()/resumeHealthCheck()。

四、設定はついでに JSON に保存するものではなく、ランタイム制御インターフェイスである

最も重要な技術点を一つだけ選ぶなら、私は設定ライフサイクルを選ぶ。

現在の実装では、設定は普通のフロントエンド永続化状態ではなく、OpenClaw runtime を駆動する制御面プロトコルである。設定管理ロジックにおいて、updateField() は単にオブジェクトをマージするだけではなく、現在の設定の読み取り、partial config の深いマージ、schema 検証、書き込み前の自動バックアップ、書き込み失敗時のロールバック、サービス実行中の再起動とヘルスチェック、必要に応じた旧設定へのロールバックを順番に実行する。

これは QClaw において、設定が「フォーム状態の保存場所」ではなく、ランタイム全体の制御インターフェイスであることを示している。

sequenceDiagram
    participant UI as Renderer UI
    participant Bridge as Preload bridge
    participant IPC as Main IPC
    participant CM as Config manager
    participant PM as Process manager
    participant GW as OpenClaw gateway

    UI->>Bridge: config.updateField(partialConfig)
    Bridge->>IPC: invoke config:updateField
    IPC->>CM: merge + validate + backup + write
    alt 変更が reload / restart を引き起こす
        IPC->>PM: pause health check
        PM->>GW: restart or wait for in-process reload
        GW-->>PM: healthy
        IPC->>PM: resume health check
    end
    IPC-->>Bridge: ConfigUpdateResult
    Bridge-->>UI: success / rollback / error

この図は、漠然とした大枠図よりも有用である。なぜなら、見落とされやすい三つの点を示しているからだ。

• 設定更新は直接ディスクへ書き込むのではなく、まず設定管理モジュールを通る
• メインプロセスは、どの変更が reload または restart を引き起こすかを知っている
• ヘルスチェックと設定更新は連動しており、互いに無関係な二つの機能ではない

コード上の事実：updateField()、willTriggerRestart()、ConfigUpdateResult という名前に加えて、channels.wechat-access.token、models.providers.qclaw.apiKey、agents.defaults.model.primary といった保護フィールドも、直接対応している。

私の解釈：これは、ここで設定が担っている役割が「ランタイム制御インターフェイス」であり、「ついでにローカル JSON を書く」ことではない、ということを示している。

境界：現在の記事で証明できるのは、設定更新チェーンとロールバック機構が存在することまでであり、完全な schema、デフォルト値、すべてのホット反映ルールを項目ごとに展開しているわけではない。

コードの手がかり：updateField()、PROTECTED_CONFIG_PATHS（設定管理層）

最小の例は gateway.port の更新である。フロントエンドが次を送信した場合：

{
  "gateway": {
    "port": 28790
  }
}

その最短チェーンは、window.electronAPI.config.updateField() -> config:updateField -> updateField() -> willTriggerRestart() -> ヘルスチェック -> 成功すれば新しいポートを保持し、失敗すれば旧設定へロールバック、となる。この例だけでは、すべてのフィールドが同じ規則で処理されることまでは証明できないが、ここでの「設定更新」が静的なアーカイブではなくランタイム動作であることを示すには十分である。

五、QClaw はネイティブの OpenClaw に対して何を一層補っているのか

「QClaw 独自の増分」を明確にしなければ、読者は当然こう疑問に思うだろう：これは結局「もう一枚ラップしただけ」と何が違うのか？

以下の表が、現在の実装についてより正確な言い方である：

したがって、より正確な言い方は「QClaw が OpenClaw を書き直した」ではなく、次のようになる：

QClaw は、開発者利用寄りのローカル runtime だった OpenClaw を、一般ユーザー向けに提供できるデスクトップ製品として包装した。

コード上の事実：デスクトップブリッジ層は process:* と config:* に加えて、window:minimize、window:maximize、app:downloadFile、instance:setMode といった、ネイティブの OpenClaw では提供されないデスクトップ能力も公開している。

私の解釈：QClaw の増分は「Gateway も呼べる」という点ではなく、デスクトップホストとしての責務を一層追加している点にある。

境界：この表を完全に裏付けるには、OpenClaw ネイティブ側のベースライン能力もあわせて引用する必要がある。この記事が現時点で主に証明しているのは、QClaw が何を追加で行っているかであり、OpenClaw のすべてのネイティブ境界を完全に列挙することではない。

コードの手がかり：app:downloadFile、instance:setMode（ブリッジ層 / IPC 登録層）

六、WeChat 接続経路：ここは推測ではなく、入口と着地点が対応している

WeChat は QClaw の重要なプロダクト差分の一つだ。現在の実装では、この経路は少なくとも 3 つの実ロジックに対応して確認できる。

フロントエンドには独立した WeChat ログイン経路があり、ログインページでも完全なインタラクションを確認できる。WeChat QR コードログインコンポーネントを作成し、WeChat から返される code を処理し、ログイン API を呼び出して業務 token に交換し、さらに electronAPI.config.updateField() を通じて結果をローカル設定に書き戻す。これは WeChat 接続が「公式サイト上の売り文句」ではなく、フロントエンドのプロダクト経路に実在する一環であることを示している。

同時に、UI 側の API ラッパー層にもテスト環境と本番環境の 2 系統の環境パラメータが定義されており、モデルサービスアドレス、WeChat WebSocket アドレス、WeChat ログイン appid、コールバックアドレスが含まれている。同じ層では、ログイン、ログアウト、ログイン状態取得、API Key 作成、channel token 更新など、WeChat 関連のインターフェース入口も確認できる。

ログイン成功後、現在の実装は次の 2 つの重要な処理を行う。

1. jwt_token、openclaw_channel_token、userInfo をローカル状態に保存する
2. 設定更新インターフェースを呼び出し、ランタイム資格情報を設定に書き込む

ここには単独で説明する価値のある細部もある。メインプロセスと OpenClaw 側には依然として channels.wechat-access.token と channels.wechat-access.wsUrl という手がかりが残っている。一方で、復元後のフロントエンド説明には、現在の互換パッチでは channels.wechat-access を隔離設定に直接書き込まず、別のプラグイン設定フィールドに書き換える、と明記されている。これは WeChat token の着地点が現在、互換状態の一段階にあることを示している。

flowchart TD
    CODE[wx code\nWeChat からの返却] --> API[wxLogin / getWxLoginState\n環境 API ラッパー層]
    API --> LS[ローカル状態\njwt_token / openclaw_channel_token / userInfo]
    API --> CFGWRITE[config.updateField\n設定書き込み経路]
    CFGWRITE --> CFG1[runtime config\nchannels.wechat-access.token]
    CFGWRITE --> CFG2[runtime config\nplugins.entries.content-security.config.token]
    CFGWRITE --> CFG3[runtime config\nmodels.providers.qclaw.apiKey]

コード事実：wxLogin、getWxLoginState、refreshChannelToken、createApiKey というインターフェース名に加えて、openclaw_channel_token、plugins.entries.content-security.config.token、channels.wechat-access.token というフィールド名は、いずれも現在の実装内で対応を確認できる。

私の解釈：これは WeChat 経路が UI 層のログイン状態にとどまらず、最終的に OpenClaw のランタイム設定面へ入っていくことを示している。

境界：現在の実装から証明できるのは「ログイン資格情報がローカル状態と設定経路に落ちる」ことだが、互換パッチが存在するため、ある単一の token 着地点を唯一の最終設計と見なすことはできない。

コードの手がかり：wxLogin、openclaw_channel_token（WeChat ログインページ / 環境 API ラッパー層）

最短呼び出しチェーン：wx code -> wxLogin() -> openclaw_channel_token -> electronAPI.config.updateField() -> config:updateField -> runtime config。

七、本当に難しいのは図を描くことではなく、システムをどう転ばせないか

この種のアーキテクチャで最も問題が起きやすい箇所は、「起動できるか」ではなく、「状態がずっと正しく保てるか」だ。現在の実装からは、開発者がこれらの問題に対処してきたことがすでに見て取れる。

まず、設定更新に失敗したとき、単にエラーを出すのではなくロールバックする。設定管理の経路では、サービス稼働中の設定更新によってヘルスチェックが失敗した場合、システムは旧設定へロールバックし、再度起動して復旧する。これは QClaw が「設定を変更する -> 効いたと盲信する」という粗い作りではなく、last-known-good 型の復旧を行っていることを示している。

次に、メインプロセスはどの変更が OpenClaw restart を引き起こすかを知っている。設定更新処理の中で、ある設定変更が OpenClaw の in-process restart を引き起こす場合、メインプロセスは先にヘルスチェックを一時停止し、サービス復旧後に監視を再開する。これは「自分で引き起こした再起動を、supervisor に異常として扱わせない」という典型的な問題をすでに考慮していることを示している。

さらに見ていくと、現在の実装には、いかにも落とし穴を踏んだ後に補われたようなロジックが二種類含まれている。一つは、ユーザーディレクトリ内にあるプリインストール拡張と同名のコピーを削除し、duplicate plugin id を避ける処理。もう一つは、shared / isolated モードを切り替えるとき、外部 OpenClaw 設定内の重要フィールドを QClaw 自身の隔離設定へ移す処理だ。前者はプラグイン複製の衝突を処理し、後者はインスタンスモード切り替えによって生じる設定分岐を処理している。

コード事実：pauseHealthCheck()、checkHealthWithRetry()、cleanupDuplicateExtensions()、migrateConfigFromExternal() という関数名はいずれも実際に存在する。

私の解釈：これは作者が、「状態の揺れ、重複 reload、モード切り替え、旧ディレクトリの衝突」といった、実運用で転倒につながる問題を考慮に入れていることを示している。

境界：これによって「失敗復旧を考慮している」ことは証明できるが、関数名だけで全ての例外分岐が完全に覆われていると証明することはできない。

コードの手がかり：pauseHealthCheck()、cleanupDuplicateExtensions()（プロセス管理層 / 設定パッチ層）

八、安全境界：現在の実装から何が証明でき、何が証明できないか

安全性は、この種のプロダクトでごまかして通れる場所ではない。

現在の実装の中で、私が証明できると考えている安全境界は三層だけだ。

1. レンダリング層はシステム権限を直接持たず、preload が公開するホワイトリスト API を経由している。
2. 設定の書き込みはフロントエンドがファイルを直接変更するのではなく、メインプロセスの設定管理経路を通っている。
3. 重要な token と apiKey のパスは、テンプレート統合時に保護フィールドとして列挙されており、テンプレート更新によって直接上書きされない。

ただし、正直に言わなければならない。現在の実装だけでは、QClaw の secrets 保存戦略、skills の隔離レベル、プラグインの信頼境界、更新時の署名検証機構、リモート制御の認可モデルを完全に証明することはまだできない。

これらの問題は重要だが、証拠が足りないのであれば、記事の中で答えをすでに知っているかのように装うべきではない。

コード事実：contextBridge.exposeInMainWorld(...)、PROTECTED_CONFIG_PATHS、models.providers.qclaw.apiKey という点はいずれも直接対応している。

私の解釈：少なくとも「ブリッジ層の隔離 + 重要フィールドの保護」という二層の境界は存在しており、これは多くのデスクトップツールよりかなり真面目だ。

境界：現在の分析範囲では、デバイス認証、allowed origins、署名付き更新経路、プラグイン認可モデルについて完全な証拠を直接確認できていないため、この節はここまでしか書けない。

コードの手がかり：contextBridge.exposeInMainWorld(...)、PROTECTED_CONFIG_PATHS（ブリッジ層 / 設定定数層）

九、この記事が本当に言いたいこと

この記事全体をより正確な一文に圧縮するなら、私はこう言う。

QClaw の核心は「デスクトップ UI を追加したこと」ではなく、OpenClaw を Electron のメインプロセスにホストされ、設定可能で、ロールバック可能で、一般ユーザー向けに配布できるローカル runtime に変えたことだ。

これは「もう一枚シェルをかぶせる」のとはかなり違う。

シェルは次のことをしない。

• bundled runtime の配布
• 設定アップグレードとフィールド保護
• 実行中設定のロールバック
• restart の分類とヘルスチェックの協調
• WeChat ログインからローカル設定チェーンへのブリッジ
• shared / isolated モード移行

そしてこれらこそ、現在の実装からすでに確認できるものだ。

十、OpenClaw ネイティブ機能の公開ベースライン

「OpenClaw にもともとある機能」を QClaw 独自の実装として誤って書かないように、前の比較表の左列にあるベースラインを、OpenClaw 公式がすでに公開している 4 つの入口に収束させておく。

1. Dashboard / Control UI
   公式ドキュメントには、ブラウザコンソールはデフォルトで Gateway によって / で提供され、ローカルのデフォルトアドレスは http://127.0.0.1:18789/ であり、openclaw dashboard によって再度開けると明記されている。
   参考：Dashboard - OpenClaw

2. Onboarding Wizard
   公式ドキュメントには、openclaw onboard がガイド付きフローの中で、ローカルまたはリモート Gateway、channels、skills、workspace のデフォルト項目を設定すると明記されている。
   参考：Onboarding Wizard (CLI) - OpenClaw

3. Quickstart
   公式のクイックスタート文書では、「onboard -> gateway status -> dashboard」がデフォルトの利用経路としてつながれており、ウィザードが auth、gateway、optional channels を設定することも説明されている。
   参考：Getting Started - OpenClaw

4. Configuration
   公式の設定ドキュメントには、設定ファイルが ~/.openclaw/openclaw.json にあり、onboarding、configure、Control UI、または直接編集によって設定を変更できると明記されている。
   参考：Configuration - OpenClaw

コード上の事実：これらのベースライン機能は、私が QClaw のコードから逆算したものではなく、OpenClaw の公式公開ドキュメントですでに個別に説明されている内容だ。

私の解釈：こうすることで、本文中の「QClaw はネイティブ OpenClaw より何を多くしているのか」は、著者が自分で定義したベースラインに落ちるのではなく、公開されている土台機能の上に立ち、そのうえでデスクトップホスト、IPC ブリッジ、WeChat ログイン入口、設定の永続化連動、ローカルプロセスホスティングといった増分を議論できる。

境界：これらの公開ドキュメントが証明できるのは、OpenClaw ネイティブがすでに Gateway + Control UI + Onboarding + Config というベースライン機能を備えていることだけであり、QClaw の増分実装そのものに対するソースコード分析の代わりにはならない。

コード上の手がかり：OpenClaw 公式ドキュメント Dashboard / Wizard / Quickstart / Configuration（公開ベースライン）

証拠索引

本文を読み終えて、「これらの判断はそれぞれ何を手がかりにしているのか」を知りたい場合は、以下の表で振り返ることができる。

結び

なので、もしこの文章にもう少し厳密な副題を付け直すなら、私はこう書く。

これは QClaw の製品紹介ではなく、現在の実装に基づく連結分析である。

そこから得られる最も重要な結論は、複雑なものではない。

• OpenClaw は低レベル runtime を担当する
• QClaw はデスクトップホストと製品化されたコントロールプレーンを担当する
• 両者は IPC、設定ライフサイクル、プロセス托管によって接続されている

この構図を本当に成立させているのは、「コントロールプレーン / 実行プレーン」といった気の利いた決め台詞ではなく、具体的な関数名、IPC 名、設定フィールド、移行ロジック、ロールバック戦略、失敗処理である。

それこそが、この文章が今「実装原理」と呼ぶによりふさわしい内容だ。