OpenClaw Control UI設定ガイド：ブラウザから即時接続

複雑なバックエンドシステムを構築しているとき、コマンドラインだけで全てを管理するのは少し骨が折れますよね。特にリアルタイムのステータス確認や複雑な設定の変更など、視覚的に操作できれば開発体験はもっとスムーズになるはずです。

OpenClaw の Control UI は、そんな開発者の皆さんのために設計された、軽量で強力な管理画面です。Vite と Lit をベースにしたこのシングルページアプリケーション（SPA）を使えば、ブラウザから直接 Gateway の状態を把握し、操作することができます。

Control UI (browser)

Control UI は、Gateway によって提供される小さな Vite + Lit 製のシングルページアプリです。

デフォルト: http://<host>:18789/
オプションのプレフィックス: gateway.controlUi.basePath で設定可能（例: /openclaw）

この UI は、同じポート上の Gateway WebSocket と直接通信します。

クイックオープン（ローカル）

Gateway が同じコンピュータで動作している場合は、以下を開いてください。

http://127.0.0.1:18789/ (または http://localhost:18789/)

ページが読み込まれない場合は、先に Gateway を起動してください： openclaw gateway。

認証情報は、WebSocket のハンドシェイク時に以下を通じて提供されます。

connect.params.auth.token
connect.params.auth.password

ダッシュボードの設定パネルは、現在のブラウザタブセッションと選択された Gateway URL のトークンを保持します。パスワードは保存されません。オンボーディング時にデフォルトで Gateway トークンが生成されるので、初回接続時にここに貼り付けてください。

デバイスのペアリング（初回接続）

新しいブラウザやデバイスから Control UI に接続する場合、Gateway は一度限りのペアリング承認を要求します。これは、gateway.auth.allowTailscale: true を設定して同じ Tailnet 上にいる場合でも必要です。不正アクセスを防ぐためのセキュリティ対策です。

表示されるメッセージ: “disconnected (1008): pairing required”

デバイスを承認する方法:

# List pending requests
openclaw devices list

# Approve by request ID
openclaw devices approve <requestId>

ブラウザが認証詳細（ロール、スコープ、公開鍵）を変更してペアリングを再試行した場合、以前の保留リクエストは上書きされ、新しい requestId が作成されます。承認前に再度 openclaw devices list を実行してください。

一度承認されるとデバイスは記憶され、openclaw devices revoke --device <id> --role <role> で取り消さない限り、再承認は不要です。トークンのローテーションや失効については、Devices CLI を参照してください。

注意点:

ローカル接続（127.0.0.1）は自動承認されます。
リモート接続（LAN、Tailnet など）は明示的な承認が必要です。
ブラウザのプロファイルごとに一意のデバイス ID が生成されるため、ブラウザを切り替えたりブラウザデータを消去したりすると、再ペアリングが必要になります。

言語サポート

Control UI は、初回の読み込み時にブラウザのロケールに基づいて自動的にローカライズされます。後で Access カードの言語セレクターから変更することも可能です。

サポートされているロケール: en, zh-CN, zh-TW, pt-BR, de, es
英語以外の翻訳は、ブラウザで遅延読み込み（lazy-load）されます。
選択されたロケールはブラウザのストレージに保存され、次回の訪問時にも適用されます。
翻訳キーが見つからない場合は、英語にフォールバックします。

現在できること

Gateway WS を介したモデルとのチャット（chat.history, chat.send, chat.abort, chat.inject）
チャット内でのツール呼び出しのストリーミングとライブツール出力カード（エージェントイベント）
チャンネル: WhatsApp/Telegram/Discord/Slack + プラグインチャンネル（Mattermost など）のステータス、QR ログイン、チャンネルごとの設定（channels.status, web.login.*, config.patch）
インスタンス: プレゼンスリストとリフレッシュ（system-presence）
セッション: リスト表示、セッションごとの thinking/fast/verbose/reasoning のオーバーライド（sessions.list, sessions.patch）
Cron ジョブ: リスト表示、追加、編集、実行、有効化/無効化、実行履歴（cron.*）
Skills: ステータス、有効化/無効化、インストール、API キーの更新（skills.*）
Nodes: リスト表示と caps（node.list）
Exec 承認: Gateway または Node の許可リストの編集、exec host=gateway/node のポリシー確認（exec.approvals.*）
設定: ~/.openclaw/openclaw.json の表示と編集（config.get, config.set）
設定: バリデーションを伴う適用と再起動（config.apply）、および最後のアクティブセッションのウェイクアップ
設定の書き込みには、同時編集による上書きを防ぐための base-hash ガードが含まれています。
設定の書き込み（config.set/config.apply/config.patch）では、送信された設定ペイロード内の SecretRef 解決のプリフライトチェックも行われます。未解決のアクティブな参照が含まれる場合は、書き込み前に拒否されます。
設定スキーマとフォームレンダリング（プラグインやチャンネルのスキーマを含む config.schema）。Raw JSON エディタは、スナップショットが安全に round-trip できる場合にのみ利用可能です。
スナップショットが Raw テキストを安全に round-trip できない場合、Control UI は強制的にフォームモードになり、そのスナップショットの Raw モードを無効にします。
構造化された SecretRef オブジェクトの値は、誤ってオブジェクトから文字列へ破損するのを防ぐため、フォームのテキスト入力では読み取り専用としてレンダリングされます。
デバッグ: ステータス、ヘルス、モデルのスナップショット、イベントログ、手動 RPC 呼び出し（status, health, models.list）
ログ: フィルタリングとエクスポート機能を備えた Gateway ファイルログのライブテイル（logs.tail）
アップデート: パッケージまたは git のアップデート実行と再起動（update.run）、および再起動レポート

Cron ジョブパネルの注意点:

隔離されたジョブの場合、配信のデフォルトは概要の通知（announce summary）です。内部実行のみにしたい場合は「none」に切り替えられます。
announce が選択されると、チャンネル/ターゲットフィールドが表示されます。
Webhook モードは、delivery.mode = "webhook" を使用し、delivery.to に有効な HTTP(S) Webhook URL を設定します。
メインセッションのジョブでは、webhook と none の配信モードが利用可能です。
高度な編集コントロールには、実行後の削除、エージェントのオーバーライド解除、cron の exact/stagger オプション、エージェントモデル/thinking のオーバーライド、ベストエフォート配信の切り替えが含まれます。
フォームのバリデーションはインラインで行われ、フィールドレベルのエラーが表示されます。無効な値がある場合、修正されるまで保存ボタンは無効化されます。
専用のベアラートークンを送信するには cron.webhookToken を設定してください。省略した場合、Webhook は認証ヘッダーなしで送信されます。
非推奨のフォールバック: notify: true を持つ古い保存済みジョブは、移行されるまで引き続き cron.webhook を使用できます。

チャットの動作

chat.send は非ブロッキングです。すぐに { runId, status: "started" } を返し、レスポンスは chat イベントを介してストリーミングされます。
同じ idempotencyKey で再送信すると、実行中は { status: "in_flight" }、完了後は { status: "ok" } が返されます。
chat.history のレスポンスは、UI の安全性のためにサイズ制限されています。履歴のエントリが大きすぎる場合、Gateway は長いテキストフィールドを切り詰めたり、重いメタデータブロックを省略したり、大きすぎるメッセージをプレースホルダー（[chat.history omitted: message too large]）に置き換えたりすることがあります。
chat.inject はセッション履歴にアシスタントのノートを追加し、UI 更新のみの chat イベントをブロードキャストします（エージェントの実行やチャンネルへの配信は行われません）。
停止方法:
- Stop をクリック（chat.abort を呼び出し）
- /stop と入力（または stop, stop action, stop run, stop openclaw, please stop などの単独の停止フレーズを使用）してアウトオブバンドで中断
- chat.abort は { sessionKey } をサポートしており（runId なし）、そのセッションのすべてのアクティブな実行を中断できます。
中断時の部分保持:
- 実行が中断された場合でも、アシスタントのテキストの一部が UI に表示されることがあります。
- バッファリングされた出力が存在する場合、Gateway は中断されたアシスタントの部分テキストを履歴に保存します。
- 保存されたエントリには中断メタデータが含まれるため、履歴の利用者はそれが通常の完了出力か中断による部分出力かを判別できます。

Tailnet アクセス（推奨）

統合された Tailscale Serve（推奨）

Gateway をループバックで実行し、Tailscale Serve に HTTPS プロキシを任せる方法です。

openclaw gateway --tailscale serve

アクセス先:

https://<magicdns>/ (または設定した gateway.controlUi.basePath)

デフォルトでは、gateway.auth.allowTailscale が true の場合、Control UI/WebSocket の Serve リクエストは Tailscale のアイデンティティヘッダー（tailscale-user-login）を介して認証できます。OpenClaw は、x-forwarded-for アドレスを tailscale whois で解決してヘッダーと照合することでアイデンティティを検証します。これは、リクエストが Tailscale の x-forwarded-* ヘッダーを伴ってループバックに到達した場合にのみ受け入れられます。Serve 経由のトラフィックでもトークンやパスワードを要求したい場合は、gateway.auth.allowTailscale: false を設定するか、gateway.auth.mode: "password" を強制してください。トークンなしの Serve 認証は、Gateway ホストが信頼されていることを前提としています。信頼できないローカルコードがそのホストで実行される可能性がある場合は、トークンまたはパスワード認証を要求してください。

Tailnet へのバインド + トークン

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

アクセス先:

http://<tailscale-ip>:18789/ (または設定した gateway.controlUi.basePath)

UI の設定にトークンを貼り付けてください（connect.params.auth.token として送信されます）。

安全でない HTTP

プレーンな HTTP（http://<lan-ip> や http://<tailscale-ip>）でダッシュボードを開くと、ブラウザはセキュアでないコンテキストで動作し、WebCrypto をブロックします。デフォルトでは、OpenClaw はデバイスアイデンティティのない Control UI 接続をブロックします。

推奨される修正方法: HTTPS（Tailscale Serve）を使用するか、UI をローカルで開いてください。

https://<magicdns>/ (Serve)
http://127.0.0.1:18789/ (Gateway ホスト上)

安全でない認証（Insecure-auth）の切り替え動作:

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth はローカルの互換性のための切り替えのみを目的としています。

セキュアでない HTTP コンテキストにおいて、localhost の Control UI セッションがデバイスアイデンティティなしで続行することを許可します。
ペアリングチェックをバイパスするものではありません。
リモート（localhost 以外）のデバイスアイデンティティ要件を緩和するものではありません。

緊急時のみ（Break-glass）:

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

dangerouslyDisableDeviceAuth は Control UI のデバイスアイデンティティチェックを無効にします。これは重大なセキュリティの低下を招くため、緊急使用後はすぐに元に戻してください。

HTTPS のセットアップガイドについては Tailscale を参照してください。

UI のビルド

Gateway は dist/control-ui から静的ファイルを提供します。以下のコマンドでビルドしてください。

pnpm ui:build # auto-installs UI deps on first run

オプションの絶対パスベース（アセット URL を固定したい場合）:

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

ローカル開発用（独立した開発サーバー）:

pnpm ui:dev # auto-installs UI deps on first run

その後、UI から Gateway の WS URL（例: ws://127.0.0.1:18789）を指定してください。

デバッグとテスト：開発サーバーとリモート Gateway

Control UI は静的ファイルで構成されています。WebSocket のターゲットは設定可能で、HTTP のオリジンと異なっていても構いません。これは、Vite 開発サーバーをローカルで動かしつつ、Gateway を別の場所で動かしたい場合に便利です。

UI 開発サーバーを起動: pnpm ui:dev
以下のような URL を開く:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

オプションの一時的な認証（必要な場合）:

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

注意点:

gatewayUrl は読み込み後に localStorage に保存され、URL からは削除されます。
token は可能な限り URL フラグメント（#token=...）経由で渡してください。フラグメントはサーバーに送信されないため、リクエストログや Referer への漏洩を防げます。レガシーな ?token= クエリパラメータも互換性のために一度だけインポートされますが、フォールバックとしてのみ機能し、ブートストラップ直後に削除されます。
password はメモリ内のみに保持されます。
gatewayUrl が設定されている場合、UI は設定ファイルや環境変数の認証情報にフォールバックしません。token（または password）を明示的に提供してください。明示的な認証情報がない場合はエラーになります。
Gateway が TLS（Tailscale Serve、HTTPS プロキシなど）の背後にある場合は、wss:// を使用してください。
クリックジャッキング防止のため、gatewayUrl はトップレベルウィンドウでのみ受け入れられます（埋め込み不可）。
ループバック以外での Control UI デプロイメントでは、gateway.controlUi.allowedOrigins を明示的に（完全なオリジンで）設定する必要があります。これにはリモート開発環境も含まれます。
厳密に管理されたローカルテスト以外では、gateway.controlUi.allowedOrigins: ["*"] を使用しないでください。これは「使用しているホストに合わせる」という意味ではなく、「あらゆるブラウザオリジンを許可する」という意味になります。
gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true は Host ヘッダーによるオリジンフォールバックモードを有効にしますが、これは危険なセキュリティモードです。

設定例:

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

リモートアクセスのセットアップ詳細は Remote access を参照してください。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。