macOS companion app

WebChat（macOS）

macOS メニューバーアプリは、WebChat UI をネイティブの SwiftUI ビューとして組み込んでいます。Gateway に接続し、選択したエージェントのプライマリセッション（main、または session.scope が global の場合は global）をデフォルトで使用します。

完全なチャットウィンドウは、ネイティブの分割ビューです。

セッションサイドバー：検索可能なセッション一覧で、ピン留め、Gateway ベースのグループ、最近の項目の各セクションがあります。生成された子セッションは、各セクション内で親の下にネストされます。折りたたまれた親には、実行中、失敗、未読の子孫の概要が表示されます。コンテキストメニューでは、セッション情報、名前変更、ピン留め、フォーク、既読／未読、アーカイブ／復元、セッションキーのコピー、削除を操作できます。メインの新規セッションアクション（または Shift-Cmd-N）は、sessions.create を介して即座に作成します。隣接するオプションポップオーバーでは、エージェントを選択し、任意のベース ref を指定して管理対象ワークツリーを要求できます。
ウィンドウツールバー：コンテキスト使用量リング（トークンとセッションコスト、コンパクトなアクション付き）、モデルコントロール、セッションアクションメニューがあります。モデルはプロバイダーごとにグループ化され、デフォルトのプロバイダーが最初に表示されます。ピン留めしたモデルと最近使用したモデルは上部に残ります。コントロールでは、モデルの思考レベルを継承または上書きし、ツール呼び出しの詳細度を選択し、高速応答を切り替えられます。メニューでは、現在のセッションの名前変更やフォークを行い、ピン留め、既読、アーカイブの状態を更新できます。セッション…（Shift-Cmd-S）を選択すると、Gateway 検索、グループ管理、セッションの確認、名前変更、ピン留め、アーカイブ、復元を行うためのアクティブ／アーカイブ済みマネージャーが開きます。選択モードでは、個々の失敗を表示したまま、複数のアクティブなセッションにピン留め、ピン留め解除、アーカイブ、削除を適用できます。個別のメニューチェックマークで、アシスタントの推論とツールアクティビティの表示／非表示を切り替えられます。どちらもデフォルトでオンになっており、起動をまたいで記憶されます。
トランスクリプトとコンポーザー：アシスタントのメッセージはアバター付きのプレーンテキストとして、ユーザーのメッセージはアクセントカラーの吹き出しとして表示されます。保留中のエージェントからの質問は、単一選択または複数選択のオプション、自由入力の その他 の回答、有効期限のカウントダウン、共有された終了状態を備えたネイティブカードとして表示されます。空のチャットには、デスクトップ用の開始プロンプトが表示されます。/ を入力すると、commands.list に基づくスラッシュコマンドのオートコンプリートが開き、矢印キー／Tab／Return／Escape で操作できます。メッセージを右クリックすると、非表示の推論を含めず、表示されている Markdown をコピーできます。省略されたアシスタントメッセージには メッセージ全体を開く も表示され、選択可能な Markdown リーダーが読み込まれます。Gateway TTS を使用するには 読み上げる を使用します。利用できない場合はローカル音声にフォールバックします。
音声コントロール：コンポーザーから、既存の macOS Talk Mode のメニューバーオーバーレイを置き換えることなく、開始または停止できます。Talk Mode がアクティブな間、コンポーザーにはリスニング／思考中／発話中の状態、リアルタイムの音声アクティビティ、展開可能な逐次トランスクリプトが表示されます。Talk ボタンを右クリックすると、System Default または接続済みのマイクを選択できます。これは Voice Wake とプッシュツートークでも使用されるマイク選択です。選択したマイクが切断された場合、アクティブな Talk セッションはシステムデフォルトにフォールバックし、次回 Talk Mode を開始したときに選択したマイクを再試行します。Talk Mode が音声キャプチャを使用していない場合は、別のマイクアクションでボイスメモを録音できます。

メニューバーから開く固定式のコンパクトチャットパネルは、同じモデル、思考、詳細度、高速コントロールをインラインで備えたコンパクトな単一カラムレイアウトを維持し、開始プロンプト、Talk Mode、ボイスメモ、読み上げも利用できます。このコンパクト画面では、アシスタントの推論とツールアクティビティは引き続き非表示です。

複数の Gateway ウィンドウ

再利用可能な Gateway プロファイルを追加または削除するには、Settings → Gateways を開きます。各プロファイルには、プライベートネットワークの ws:// またはセキュアな wss:// エンドポイントと、任意のトークンまたはパスワードが含まれます。認証情報は macOS Keychain に保存されます。セキュアなプロファイルは、システムの信頼によって保護された独自の初回使用時証明書ピンを維持し、プライマリ Gateway の gateway.remote.tlsFingerprint を継承しません。プロファイルを削除すると、開いているそのプロファイルのウィンドウも閉じられ、セカンダリ接続も終了します。

File → New Gateway Window… を選択するか Cmd-N を押してから、保存済みのプロファイルを選択します。ピッカーは、最後に使用したプロファイルを記憶します。選択するたびに新しい独立したウィンドウが作成されるため、同じ Gateway を異なるアクティブセッションとナビゲーション状態で複数のウィンドウに表示できます。

保存済みの各プロファイルは、1 つの共有 Gateway 接続、デバイス認証スコープ、トランスクリプトキャッシュ、オフライン送信トレイ、ルートリースを所有します。そのプロファイルのウィンドウは、独立して移動できる状態を維持しながら、これらのリソースを再利用します。異なるプロファイルのウィンドウは接続を維持し、同時にチャットを実行します。

メニューバーアプリに設定された Gateway は、Mac Node の機能と Talk Mode の所有者であり続けます。追加の Gateway ウィンドウはオペレーター専用であるため、 2 番目の Gateway がグローバルなマイクやデバイスのコントロール先を暗黙に変更することはできません。読み上げ／TTS と通常のチャットアクションは、ウィンドウ独自の Gateway 接続を使用します。

Quick Chat バー

Option-Space（⌥Space）を押すか、メニューバーメニューから Quick Chat を選択すると、メインセッション用のフローティングコンポーザーが開きます。グローバルショートカットは、Settings → General → Quick Chat shortcut のレコーダーで変更できます。

Quick Chat には対象のエージェント（アバターまたは絵文字。プレースホルダーにはエージェント名を表示）が表示され、そのエージェントのメインセッションに送信します。Return で送信を確定した後もバーは開いたままで、下方向に展開し、ストリーミングされた Markdown の応答と最近のトランスクリプトが表示されます。バーの入力欄は引き続きコンポーザーとして機能します。Command-Return を押すと送信し、同じ対象を完全なチャットウィンドウで開きます。Shift-Return で改行し、Escape でバー全体と応答領域を閉じます。外側をクリックしても閉じます。必要な macOS 権限がない場合は、付属のストリップに Grant と Not now のアクションが表示されます。

マイクボタンを使用して、コンポーザーに音声入力できます。音声認識途中の結果は、コンポーザーにすでに入力されていたテキストを保持しながら、音声入力部分をリアルタイムで置き換えます。停止するには、ボタンをもう一度押すか、Return または Escape を押します。Quick Chat の送信、非表示、フォーカス解除でもマイクが解放されます。初回使用時には、macOS の Microphone と Speech Recognition へのアクセスが求められます。Quick Chat は Apple Speech を使用し、そのネットワークサービスを使用する場合があります。オンデバイス認識が必要なのは、パッシブな Voice Wake のみです。

コンパクトなモデルコントロールには、対象セッションの現在のモデルと推論レベルが表示されます。モデルの選択はそのセッションを更新するため、そのセッションに永続化されます。一方、推論の選択は、現在表示されている Quick Chat から送信される各メッセージにのみ適用されます。ローカルの選択内容は、バーが非表示になるとリセットされます。エージェントを切り替えたり、最近のセッションを選択したりすると、明示的な選択内容は維持されますが、新たに対象となったセッションの基礎となるモデル状態が再読み込みされます。

履歴ボタンをクリックすると、更新日時が新しい順に 5 件のセッションから選択するか、<agent> への新規メッセージ に戻れます。最近のセッションを選択すると、そのセッションに正確に送信され、プレースホルダーが <session> で返信 に変わります。Quick Chat を非表示にすると、この一時的な対象は選択したエージェントのメインセッションにリセットされます。アバターメニューからエージェントを切り替えた場合もリセットされます。

Command-Return は、セッションスコープがグローバルの場合も含め、送信を受け取ったエージェントの会話を開きます。

カメラボタンを押すと、Capture Window… または Capture Area… のメニューが開きます。ウィンドウキャプチャでは、表示中のすべてのウィンドウにラベルが付けられます。範囲キャプチャでは、領域をドラッグしている間、各ディスプレイが暗くなり、その領域のサイズがリアルタイムで表示されます。選択したスクリーンショットは、入力済みのテキストをキャプションとして、選択したエージェントに送信されます。初回使用時には、macOS の Screen Recording へのアクセスが求められます。Escape、空白部分のクリック、または有意な領域をドラッグせずにクリックするとキャンセルされます。

ドキュメントテキストボタンを使用すると、フォーカス中のアプリのフォーカス中のウィンドウからテキストを添付できます。Quick Chat は、取得したテキストをコンポーザーに配置せず、削除可能なコンテキストチップとして表示します。送信時にチップのテキストが送信メッセージに追加され、その後クリアされます。これには macOS の Accessibility 権限が必要です。添付テキストは Quick Chat を閉じた場合にもクリアされるため、ある表示時のコンテキストが後の送信に漏れることはありません。

応答が完了したら、<app> にペースト を選択すると、非表示の推論を除く表示中のアシスタントテキストが一般ペーストボードにコピーされ、直前まで最前面にあったアプリにペーストされます。これには macOS の Accessibility 権限が必要です。このアクションは現在のペーストボードの内容を置き換え、その後 Quick Chat を非表示にします。

この機能を完全に無効にするには、Settings → General → Quick Chat を使用します。同じセクションにショートカットレコーダーもあります。

ローカルモード：ローカル Gateway WebSocket に直接接続します。
リモートモード：設定された直接 ws:///wss:// ルートまたはアプリ管理の SSH トンネルをデータプレーンとして使用します。

起動とデバッグ

手動：Lobster メニュー -> 「Open Chat」。
テスト用の自動起動：
bash
```
dist/OpenClaw.app/Contents/MacOS/OpenClaw --chat
```
（--webchat は従来のエイリアスとして受け付けられます。）
ログ：./scripts/clawlog.sh（サブシステム ai.openclaw、カテゴリ WebChatSwiftUI）。

接続の仕組み

データプレーン：Gateway WS メソッド chat.history、chat.message.get、chat.send、chat.abort、chat.inject、および question.list と question.resolve、さらにイベント chat、agent、presence、tick、health。質問カードは question.requested および question.resolved イベントに従い、再接続後に question.list から更新されます。
chat.history は表示用に正規化されたトランスクリプトを返します。インラインディレクティブタグは表示テキストから削除され、プレーンテキストのツール呼び出し XML ペイロード（<tool_call>、<function_call>、<tool_calls>、<function_calls>。省略されたブロックを含む）と漏出したモデル制御トークンも削除されます。正確に NO_REPLY/no_reply のような、サイレントトークンのみで構成されるアシスタント行は省略され、サイズが大きすぎる行は省略を示すプレースホルダーに置き換えられる場合があります。
セッション：上記のとおり、デフォルトではプライマリセッションを使用します。UI ではセッションを切り替えられます。
セッショングループ：sessions.groups.list、sessions.groups.put、sessions.groups.rename、sessions.groups.delete がグループカタログを所有します。メンバーシップはセッションの category であり、sessions.patch を介して更新されます。
未読状態：セッションがアクティブになり、ライブ履歴が正常に読み込まれた後、アプリはそのセッションの未読マーカーをクリアします。履歴の読み込みに失敗した場合はクリアしません。一時的なパッチ失敗は、次回のアクティブ化時に再試行されます。
オンボーディングでは、初回セットアップを分離するために専用セッションを使用します。
オフラインキャッシュ：アプリは Gateway ごとに、最近のチャットセッションとトランスクリプトの小規模な読み取り専用キャッシュ（~/Library/Application Support/OpenClaw/chat-cache.sqlite）を保持します。コールド起動時には最後に確認されたトランスクリプトがすぐに描画され、Gateway が応答すると更新されます。また、切断中も最近のチャットを閲覧できます（接続が復旧するまで送信は無効です）。

セキュリティ範囲

リモートモードでは、Gateway WebSocket の制御ポートのみを SSH 経由で転送します。

既知の制限事項

UI はチャットセッション向けに最適化されており、完全なブラウザサンドボックスではありません。