OpenClaw WebChat設定ガイド：macOS/iOSでネイティブ接続

チャットインターフェースの開発において、UIの構築や接続設定に手間取った経験はありませんか？特にGatewayとの連携をテストする際、わざわざブラウザを立ち上げたり、ローカルサーバーを準備したりするのは少し面倒なものです。

WebChatは、こうした開発者の手間を減らし、スムーズなインタラクションを実現するために設計されました。この記事では、WebChatの概要から具体的な動作の仕組みまで詳しく解説します。

WebChatとは

WebChatは、Gateway専用のネイティブなチャットUIです。macOSおよびiOS向けのSwiftUIで構築されており、以下のような特徴があります。

• ブラウザを埋め込んだり、ローカルに静的サーバーを立てたりする必要がないネイティブUIです。
• 他のチャネルと同じセッションおよびルーティングルールを使用します。
• 決定論的なルーティングを採用しており、返答は常にWebChatへ戻ります。

クイックスタート

1. Gatewayを開始します。
2. WebChat UI（macOS/iOSアプリ）またはControl UIのチャットタブを開きます。
3. Gatewayの認証（auth）が設定されていることを確認してください。これはループバック接続であっても、デフォルトで必要となります。

動作の仕組み

WebChatの挙動や内部の仕組みについて説明します。

• UIはGatewayのWebSocketに接続し、chat.history、chat.send、chat.injectを使用します。
• chat.historyは安定性のために制限が設けられています。Gatewayは長いテキストフィールドを切り詰めたり、重いメタデータを省略したりすることがあります。サイズが大きすぎるエントリは [chat.history omitted: message too large] というプレースホルダーに置き換えられます。
• chat.injectは、Agentを実行せずにアシスタントのメモを直接トランスクリプトに追加し、UIにブロードキャストします。
• 実行が中断された場合でも、バッファリングされた出力がある場合は、アシスタントの出力の一部がUIに表示され続けることがあります。
• Gatewayは、中断された際の部分的なテキストを履歴に保存し、それらのエントリに中断を示すメタデータを付与します。
• 履歴は常にGatewayから取得されます。ローカルファイルを監視することはありません。
• Gatewayに接続できない場合、WebChatは読み取り専用モードになります。

Control UIのAgentツールパネル

Control UIの /agents にあるツールパネルには、2つの独立したビューが用意されています。

• Available Right Now: tools.effective(sessionKey=...) を使用します。コアツール、プラグイン、チャネル固有のツールなど、現在のセッションで実際に実行時に使用可能なツールを表示します。
• Tool Configuration: tools.catalog を使用します。プロファイル、オーバーライド、カタログの定義に焦点を当てたビューです。

実行時のツールの可用性はセッションごとにスコープされます。そのため、同じAgentであってもセッションを切り替えると、Available Right Now のリストが変化することがあります。また、設定エディタで設定したからといって、必ずしも実行時に利用できるとは限りません。実際のアクセス権は、ポリシーの優先順位（allow/deny、Agentごと、プロバイダー/チャネルごとのオーバーライド）に従って決定されます。

リモートでの利用

リモートモードでは、SSHやTailscaleを介してGatewayのWebSocketをトンネリングして利用します。この際、別途WebChatサーバーを起動する必要はありません。

設定リファレンス (WebChat)

詳細な設定については、Configuration を参照してください。

WebChatに関する主なオプションは以下の通りです。

• gateway.webchat.chatHistoryMaxChars: chat.history レスポンス内のテキストフィールドの最大文字数です。トランスクリプトのエントリがこの制限を超えると、Gatewayはテキストを切り詰め、プレースホルダーに置き換えることがあります。クライアント側からリクエストごとに maxChars を送信して、このデフォルト値を上書きすることも可能です。

関連するグローバルオプション：

• gateway.port, gateway.bind: WebSocketのホストとポート。
• gateway.auth.mode, gateway.auth.token, gateway.auth.password: WebSocketの認証（トークン/パスワード）。
• gateway.auth.mode: "trusted-proxy": ブラウザクライアント向けの逆プロキシ認証（詳細は Trusted Proxy Auth を参照）。
• gateway.remote.url, gateway.remote.token, gateway.remote.password: リモートGatewayのターゲット設定。
• session.*: セッションストレージおよびメインキーのデフォルト設定。

次のステップ

• Configuration
• Trusted Proxy Auth

AI Setup Assistant