Gateway

Gateway は OpenClaw の WebSocket サーバー（チャンネル、Node、セッション、フック）です。以下のすべてのサブコマンドは openclaw gateway ... の配下にあります。

Gateway を実行する

openclaw gatewayopenclaw gateway run   # 同等の明示的な形式

オプション

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> WebSocket ポート（デフォルトは設定/環境変数から取得。通常は 18789）。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYmluZCA8bW9kZQ " type="string"> バインドモード: loopback（デフォルト）、lan、tailnet、auto、custom。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> connect.params.auth.token 用の共有トークン。設定されている場合、デフォルトは OPENCLAW_GATEWAY_TOKEN です。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYXV0aCA8bW9kZQ " type="string"> 認証モード: none、token、password、trusted-proxy。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcGFzc3dvcmQgPHBhc3N3b3Jk " type="string"> --auth password 用のパスワード。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdGFpbHNjYWxlIDxtb2Rl " type="string"> Tailscale の公開方法: off、serve、funnel。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0td3MtbG9nIDxzdHlsZQ " type="string" default="auto"> WebSocket ログ形式: auto、full、compact。

--claude-cli-logs は --cli-backend-logs の非推奨エイリアスです。

--bind custom の場合、gateway.customBindHost を IPv4 アドレスに設定してください。127.0.0.1 または 0.0.0.0 以外のアドレスでは、同一ホストのクライアント用に、同じポート上の 127.0.0.1 も必要です。いずれかのリスナーをバインドできない場合、起動は失敗します。ワイルドカード 0.0.0.0 では、必須の別エイリアスは追加されません。IPv6 専用の独自ホスト構成では、Gateway の前段に IPv4 サイドカーまたはプロキシが必要です。

Gateway を再起動する

openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --wait 30s

--safe は、実行中の Gateway にアクティブな処理の事前確認を要求し、その処理が完了した後に、集約された 1 回の再起動をスケジュールします。待機時間の上限は 5 分です。この時間を超えると、再起動が強制されます。--safe は --force または --wait と併用できません。

--skip-deferral は安全な再起動時のアクティブ処理の延期ゲートを迂回するため、報告されたブロッカーが存在する場合でも Gateway を直ちに再起動します。--safe が必要です。暴走タスクによって延期が停止している場合に使用してください。

--wait <duration> は、通常の（安全モードではない）再起動時のドレイン時間の上限を上書きします。単位なしのミリ秒、または単位接尾辞 ms、s、m、h、d（例: 30s、5m、1h30m）を指定できます。--wait 0 は無期限に待機します。--force または --safe とは互換性がありません。

--force はアクティブ処理のドレインをスキップし、直ちに再起動します。通常の restart（フラグなし）では、既存のサービスマネージャーによる再起動動作が維持されます。

外部スーパーバイザー

別のプロセスマネージャーが Gateway のライフサイクルを所有する場合にのみ、OPENCLAW_SUPERVISOR_MODE=external を設定してください。このモードでは次のように動作します。

• openclaw gateway restart は、launchd、systemd、または Task Scheduler ではなく、検証済みの実行中 Gateway を対象にしながら、既存の安全な再起動、強制再起動、待機時間制限付き再起動の動作を維持します。
• ネイティブサービスのインストール、起動、停止、アンインストール操作は拒否され、外部スーパーバイザーを使用するよう案内されます。
• スーパーバイザーが Gateway を停止し、ランタイムを置き換えて最終処理を行い、安全に再起動できるように、OpenClaw の自己更新は拒否されます。
• 新しいプロセスでの再起動では、正常終了する前に、上限付きの SQLite ハンドオフを書き込みます。永続化に失敗した場合、利用可能なハンドオフを残さずに終了する代わりに、Gateway はプロセス内再起動へフォールバックします。

OPENCLAW_SERVICE_REPAIR_POLICY=external は、独立した Doctor の修復ポリシーとして維持されます。これはランタイムの所有権を宣言するものではありません。両方の動作が必要なスーパーバイザーでは、両方の変数を設定してください。

外部スーパーバイザーは、非公開のマシン向けコントラクトを通じて、再起動ハンドオフをネゴシエートして取得できます。

openclaw gateway restart-handoff capabilities --jsonopenclaw gateway restart-handoff consume --expected-pid <pid> --json

プロトコルバージョン 1 は consume 操作をサポートします。取得時には、1 回の即時 SQLite トランザクション内で、想定 PID と上限付きハンドオフフィールドを検証します。受理されたハンドオフは成功を返す前に削除されるため、並行するコンシューマーや再実行されたコンシューマーが両方とも受理することはできません。PID が一致しない場合は、対応する所有者のために保持されます。欠落、期限切れ、無効な行によって再起動が許可されることはありません。

有効なマシン要求は、再起動しない結果も含め、終了コード 0 で JSON を返します。無効な引数は、終了コード 2 で reason: "invalid-expected-pid" を返します。状態ストアの障害は、終了コード 1 で reason: "store-unavailable" を返します。スーパーバイザーは、OpenClaw のバージョン文字列からサポート状況を推測したり、非公開の SQLite スキーマを直接読み取ったりせず、実際に使用するランタイムまたはランチャー上で capabilities をプローブしてください。

Gateway のプロファイリング

• OPENCLAW_GATEWAY_STARTUP_TRACE=1 は起動中の各フェーズの所要時間を記録します。これには、フェーズごとの eventLoopMax 遅延と、Plugin ルックアップテーブルの所要時間（インストール済みインデックス、マニフェストレジストリ、起動計画、所有者マップ処理）が含まれます。
• OPENCLAW_GATEWAY_RESTART_TRACE=1 は、再起動単位の restart trace: 行を記録します。シグナル処理、アクティブ処理のドレイン、シャットダウンフェーズ、次回起動、準備完了までの時間、メモリメトリクスが含まれます。
• OPENCLAW_DIAGNOSTICS=timeline と OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> を併用すると、外部 QA ハーネス向けに、ベストエフォートの JSONL 起動診断タイムラインを書き込みます（設定の diagnostics.flags: ["timeline"] と同等ですが、パスは引き続き環境変数でのみ指定できます）。イベントループのサンプルを含めるには、OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 を追加してください。
• pnpm build の後に pnpm test:startup:gateway -- --runs 5 --warmup 1 を実行すると、ビルド済み CLI エントリを基準に Gateway の起動をベンチマークします。最初のプロセス出力、/healthz、/readyz、起動トレースの所要時間、イベントループ遅延、Plugin ルックアップテーブルの所要時間が対象です。
• pnpm build の後に pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 を実行すると、macOS または Linux 上でプロセス内再起動をベンチマークします（Windows ではサポートされていません。再起動には SIGUSR1 が必要です）。SIGUSR1 を使用し、子プロセスで両方のトレースを有効にして、次回の /healthz、次回の /readyz、ダウンタイム、準備完了までの時間、CPU、RSS、再起動トレースのメトリクスを記録します。
• /healthz は生存性、/readyz は利用可能な準備完了状態を表します。トレース行とベンチマーク出力は、単一の期間やサンプルから導く完全なパフォーマンス結論ではなく、所有者への帰属を判断するシグナルとして扱ってください。

実行中の Gateway に問い合わせる

すべての問い合わせコマンドは WebSocket RPC を使用します。

gateway health

openclaw gateway health --url ws://127.0.0.1:18789openclaw gateway health --port 18789

/healthz は稼働性プローブです。サーバーが HTTP に応答できるようになると、すぐに結果を返します。/readyz はより厳格で、起動中の Plugin サイドカー、チャンネル、または設定済みフックが安定するまでは異常状態のままです。ローカルまたは認証済みの詳細な /readyz レスポンスには、eventLoop 診断ブロック（遅延、使用率、CPU コア比率、degraded フラグ）が含まれます。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> このポート上の local loopback Gateway を対象にします。この呼び出しでは OPENCLAW_GATEWAY_URL と OPENCLAW_GATEWAY_PORT を上書きします。

gateway usage-cost

セッションログから使用コストの概要を取得します。

openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --agent work --jsonopenclaw gateway usage-cost --all-agentsopenclaw gateway usage-cost --json

gateway stability

実行中の Gateway から最近の診断安定性レコーダーを取得します。

openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> 対象に含める最近のイベントの最大数（最大 1000）。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> 診断イベントタイプ（例: payload.large または diagnostic.memory.pressure）で絞り込みます。

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="string"> --export の出力パス。

gateway diagnostics export

バグ報告用に設計されたローカル診断 zip を書き出します。プライバシーモデルとバンドル内容については、診断エクスポートを参照してください。

openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --json

エクスポートには、manifest.json（ファイル一覧）、summary.md（Markdown 概要）、diagnostics.json（最上位の設定／ログ／検出／安定性／ステータス／ヘルス概要）、config/sanitized.json、status/gateway-status.json、health/gateway-health.json、logs/openclaw-sanitized.jsonl、およびバンドルが存在する場合は stability/latest.json が含まれます。

このエクスポートは共有を前提に設計されています。安全なログフィールド、サブシステム名、ステータスコード、所要時間、設定済みモード、ポート、Plugin／プロバイダー ID、シークレットではない機能設定、秘匿化された運用ログメッセージなど、デバッグに役立つ運用詳細は保持されます。一方で、チャットテキスト、Webhook 本文、ツール出力、認証情報、Cookie、アカウント／メッセージ識別子、プロンプト／指示テキスト、ホスト名、シークレット値は省略または秘匿化されます。ログメッセージがユーザー／チャット／ツールのペイロードテキスト（例: 「user said」、「chat text」、「tool output」、「webhook body」）に見える場合、エクスポートにはメッセージが省略されたという事実とそのバイト数のみが保持されます。

gateway status

Gateway サービス（launchd/systemd/schtasks）と、任意の接続性／認証プローブを表示します。

openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpc

gateway probe

「すべてをデバッグ」するコマンドです。常に次をプローブします。

• 設定済みのリモート Gateway（設定されている場合）、および
• localhost（ループバック）。リモートが設定されている場合でもプローブします。

--url を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では、対象に URL (explicit)、Remote (configured) / Remote (configured, inactive)、Local loopback というラベルが付けられます。

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --port 18789

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> local loopback プローブ対象と SSH トンネルのリモートポートにこのポートを使用します。--url を指定しない場合、設定済みの Gateway 環境 URL、環境ポート、またはリモート対象の代わりに、local loopback 対象のみが選択されます。

SSH 経由のリモート（Mac アプリと同等）

macOS アプリの「Remote over SSH」モードではローカルポートフォワーディングを使用し、loopback のみに制限されたリモート Gateway を ws://127.0.0.1:<port> で到達可能にします。

同等の CLI コマンド:

openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host または user@host:port（ポートのデフォルトは 22）。

設定のデフォルト（任意）: gateway.remote.sshTarget、gateway.remote.sshIdentity。

gateway call <method>

低レベル RPC ヘルパー。

openclaw gateway call statusopenclaw gateway call logs.tail --params '{"limit": 200}'

Gateway サービスの管理

openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

ラッパーを使用したインストール

管理対象サービスを別の実行ファイル（シークレットマネージャーのシムや run-as ヘルパーなど）経由で起動する必要がある場合は、--wrapper を使用します。ラッパーは通常の Gateway 引数を受け取り、最終的にその引数を指定して openclaw または Node を exec する役割を担います。

cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

環境を通じてラッパーを設定することもできます。gateway install は、パスが実行可能ファイルであることを検証し、ラッパーをサービスの ProgramArguments に書き込み、その後の強制再インストール、更新、doctor による修復に使用できるよう、サービス環境に OPENCLAW_WRAPPER を永続化します。

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctor

永続化されたラッパーを削除するには、再インストール時に OPENCLAW_WRAPPER を空にします。

OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart

Gateway の検出（Bonjour）

gateway discover は Gateway ビーコン（_openclaw-gw._tcp）をスキャンします。

• マルチキャスト DNS-SD: local.
• ユニキャスト DNS-SD（広域 Bonjour）: ドメイン（例: openclaw.internal.）を選択し、スプリット DNS と DNS サーバーを設定します。詳細は Bonjour を参照してください。

Bonjour 検出が有効（デフォルト）な Gateway のみがビーコンをアドバタイズします。

各ビーコンの TXT ヒント: role（Gateway ロールのヒント）、transport（トランスポートのヒント、例: gateway）、gatewayPort（WebSocket ポート、通常は 18789）、tailnetDns（利用可能な場合は MagicDNS ホスト名）、gatewayTls / gatewayTlsSha256（TLS の有効化状態 + 証明書フィンガープリント）。sshPort と cliPath は、完全検出モード（discovery.mdns.mode: "full"）でのみ公開されます。デフォルトは "minimal" で、これらは省略されます。この場合、クライアントは SSH ターゲットのデフォルトポートとして 22 を使用します。

gateway discover

openclaw gateway discover

例:

openclaw gateway discover --timeout 4000openclaw gateway discover --json | jq '.beacons[].wsUrl'

関連項目

• CLI リファレンス
• Gateway 運用手順書