Gateway は OpenClaw の WebSocket サーバー（チャネル、ノード、セッション、フック）です。このページのサブコマンドはDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw gateway … 配下にあります。
Bonjour 検出
ローカル mDNS + 広域 DNS-SD のセットアップ。
検出の概要
OpenClaw が Gateway をアドバタイズし、見つける仕組み。
設定
トップレベルの Gateway 設定キー。
Gateway を実行する
ローカルの Gateway プロセスを実行します。起動時の動作
起動時の動作
- 既定では、
~/.openclaw/openclaw.jsonにgateway.mode=localが設定されていない限り、Gateway は起動を拒否します。アドホック/開発用の実行には--allow-unconfiguredを使用します。 openclaw onboard --mode localとopenclaw setupはgateway.mode=localを書き込む想定です。ファイルが存在するのにgateway.modeがない場合は、暗黙的にローカルモードとみなすのではなく、破損または上書きされた設定として扱い、修復してください。- ファイルが存在し、
gateway.modeがない場合、Gateway はそれを疑わしい設定破損として扱い、ユーザーの代わりに「ローカルと推測」することを拒否します。 - 認証なしでループバックを越えてバインドすることはブロックされます（安全ガードレール）。
SIGUSR1は、許可されている場合にプロセス内再起動をトリガーします（commands.restartは既定で有効です。手動再起動をブロックするにはcommands.restart: falseを設定しますが、Gateway ツール/設定の適用/更新は引き続き許可されます）。SIGINT/SIGTERMハンドラーは Gateway プロセスを停止しますが、カスタムの端末状態は復元しません。CLI を TUI や raw モード入力でラップする場合は、終了前に端末を復元してください。
オプション
WebSocket ポート（既定値は設定/env から取得されます。通常は
18789）。リスナーのバインドモード。
認証モードの上書き。
トークンの上書き（プロセスの
OPENCLAW_GATEWAY_TOKEN も設定します）。パスワードの上書き。
Gateway パスワードをファイルから読み取ります。
Tailscale 経由で Gateway を公開します。
シャットダウン時に Tailscale serve/funnel 設定をリセットします。
設定内に
gateway.mode=local がなくても Gateway の起動を許可します。アドホック/開発用のブートストラップに限り起動ガードをバイパスします。設定ファイルの書き込みや修復は行いません。存在しない場合に開発用設定 + ワークスペースを作成します（BOOTSTRAP.md をスキップします）。
開発用設定 + 資格情報 + セッション + ワークスペースをリセットします（
--dev が必要）。起動前に、選択されたポート上の既存リスナーをすべて終了します。
詳細ログ。
コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効にします）。
Websocket ログのスタイル。
--ws-log compact のエイリアス。生のモデルストリームイベントを jsonl にログ出力します。
生ストリーム jsonl のパス。
Gateway を再起動する
openclaw gateway restart --safe は、再起動前に実行中の Gateway にアクティブな OpenClaw 作業の事前確認を依頼します。キュー済み操作、返信配信、埋め込み実行、またはタスク実行がアクティブな場合、Gateway はブロッカーを報告し、重複する安全な再起動リクエストをまとめ、アクティブな作業が排出された後に再起動します。プレーンな restart は互換性のために既存のサービスマネージャーの動作を維持します。即時上書きパスを明示的に使いたい場合にのみ --force を使用してください。
openclaw gateway restart --safe --skip-deferral は --safe と同じ OpenClaw 対応の協調再起動を実行しますが、アクティブ作業の延期ゲートをバイパスするため、ブロッカーが報告されていても Gateway はただちに再起動を発行します。タスク実行の停止で延期が固定され、--safe だけでは無期限に待機してしまう場合のオペレーター用エスケープハッチとして使用してください。--skip-deferral には --safe が必要です。
起動プロファイリング
OPENCLAW_GATEWAY_STARTUP_TRACE=1を設定すると、Gateway 起動中のフェーズタイミングをログ出力します。これにはフェーズごとのeventLoopMax遅延と、installed-index、manifest registry、起動計画、owner-map 作業の Plugin ルックアップテーブルタイミングが含まれます。OPENCLAW_DIAGNOSTICS=timelineとOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>を設定すると、外部 QA ハーネス向けにベストエフォートの JSONL 起動診断タイムラインを書き込みます。設定でdiagnostics.flags: ["timeline"]を使ってフラグを有効にすることもできます。この場合もパスは env で指定します。イベントループサンプルを含めるにはOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1を追加します。pnpm test:startup:gateway -- --runs 5 --warmup 1を実行すると、Gateway 起動をベンチマークします。ベンチマークは、最初のプロセス出力、/healthz、/readyz、起動トレースタイミング、イベントループ遅延、Plugin ルックアップテーブルタイミングの詳細を記録します。
実行中の Gateway に問い合わせる
すべてのクエリコマンドは WebSocket RPC を使用します。- 出力モード
- 共有オプション
- 既定: 人間が読める形式（TTY では色付き）。
--json: 機械可読 JSON（スタイル/スピナーなし）。--no-color（またはNO_COLOR=1）: 人間向けレイアウトを維持したまま ANSI を無効化します。
--url を設定すると、CLI は設定や環境の資格情報へフォールバックしません。--token または --password を明示的に渡してください。明示的な資格情報がない場合はエラーです。gateway health
/healthz エンドポイントは liveness プローブです。サーバーが HTTP に応答できるようになると返ります。HTTP /readyz エンドポイントはより厳格で、起動時の Plugin サイドカー、チャネル、または設定済みフックがまだ安定していない間は赤のままです。ローカルまたは認証済みの詳細な readiness レスポンスには、イベントループ遅延、イベントループ使用率、CPU コア比率、degraded フラグを含む eventLoop 診断ブロックが含まれます。
gateway usage-cost
セッションログから使用コストのサマリーを取得します。
含める日数。
gateway stability
実行中の Gateway から最近の診断安定性レコーダーを取得します。
含める最近のイベントの最大数（最大
1000）。payload.large や diagnostic.memory.pressure など、診断イベントタイプでフィルターします。診断シーケンス番号より後のイベントのみを含めます。
実行中の Gateway を呼び出す代わりに、永続化された安定性バンドルを読み取ります。状態ディレクトリ配下の最新バンドルには
--bundle latest（または単に --bundle）を使用するか、バンドル JSON パスを直接渡します。安定性の詳細を表示する代わりに、共有可能なサポート診断 zip を書き込みます。
--export の出力パス。プライバシーとバンドルの動作
プライバシーとバンドルの動作
gateway diagnostics export
バグレポートに添付することを目的としたローカル診断 zip を書き込みます。プライバシーモデルとバンドル内容については、診断エクスポート を参照してください。
出力 zip パス。既定では状態ディレクトリ配下のサポートエクスポートです。
含めるサニタイズ済みログ行の最大数。
検査するログバイト数の最大値。
ヘルススナップショット用の Gateway WebSocket URL。
ヘルススナップショット用の Gateway トークン。
ヘルススナップショット用の Gateway パスワード。
ステータス/ヘルススナップショットのタイムアウト。
永続化された安定性バンドルの検索をスキップします。
書き込まれたパス、サイズ、マニフェストを JSON として出力します。
gateway status
gateway status は Gateway サービス（launchd/systemd/schtasks）と、接続性/認証機能の任意のプローブを表示します。
明示的なプローブ対象を追加します。設定済みのリモートと localhost も引き続きプローブされます。
プローブ用のトークン認証。
プローブ用のパスワード認証。
プローブのタイムアウト。
接続性プローブをスキップします（サービスのみのビュー）。
システムレベルのサービスもスキャンします。
デフォルトの接続性プローブを読み取りプローブに昇格し、その読み取りプローブが失敗した場合は 0 以外で終了します。
--no-probe と組み合わせることはできません。ステータスの意味
ステータスの意味
gateway statusは、ローカル CLI 設定がない場合や無効な場合でも、診断用に引き続き利用できます。- デフォルトの
gateway statusは、サービス状態、WebSocket 接続、ハンドシェイク時に見える認証機能を証明します。読み取り/書き込み/管理操作は証明しません。 - 診断プローブは、初回デバイス認証に対して変更を加えません。既存のキャッシュ済みデバイストークンがある場合はそれを再利用しますが、ステータス確認のためだけに新しい CLI デバイス ID や読み取り専用デバイスのペアリングレコードを作成することはありません。
gateway statusは、可能な場合、プローブ認証用に設定済みの認証 SecretRefs を解決します。- 必須の認証 SecretRef がこのコマンドパスで未解決の場合、プローブの接続性/認証が失敗すると
gateway status --jsonはrpc.authWarningを報告します。--token/--passwordを明示的に渡すか、先にシークレットソースを解決してください。 - プローブが成功した場合、未解決の auth-ref 警告は誤検知を避けるため抑制されます。
- 待ち受け中のサービスだけでは不十分で、読み取りスコープの RPC 呼び出しも正常である必要があるスクリプトや自動化では、
--require-rpcを使用してください。 --deepは、追加の launchd/systemd/schtasks インストールをベストエフォートでスキャンします。複数の Gateway らしきサービスが検出された場合、人間向け出力にはクリーンアップのヒントが表示され、ほとんどのセットアップでは 1 台のマシンにつき 1 つの Gateway を実行すべきだと警告します。--deepは、サービスプロセスが外部 supervisor による再起動のため正常終了した場合に、最近の Gateway supervisor 再起動ハンドオフも報告します。--deepは Plugin 対応モード（pluginValidation: "full"）で設定検証を実行し、設定済み Plugin マニフェストの警告（たとえばチャンネル設定メタデータの欠落）を表示するため、インストールや更新のスモークチェックで検出できます。デフォルトのgateway statusは、Plugin 検証をスキップする高速な読み取り専用パスを維持します。- 人間向け出力には、解決済みのファイルログパスに加えて、CLI とサービスの設定パス/有効性のスナップショットが含まれ、プロファイルや state-dir のずれを診断しやすくします。
Linux systemd の認証ずれチェック
Linux systemd の認証ずれチェック
- Linux systemd インストールでは、サービス認証ずれチェックがユニットから
Environment=とEnvironmentFile=の値の両方を読み取ります（%h、引用符付きパス、複数ファイル、省略可能な-ファイルを含む）。 - ずれチェックは、マージされたランタイム環境（まずサービスコマンド環境、次にプロセス環境のフォールバック）を使用して
gateway.auth.tokenSecretRefs を解決します。 - トークン認証が実質的に有効ではない場合（明示的な
gateway.auth.modeがpassword/none/trusted-proxy、または mode が未設定でパスワードが優先され得るうえ、勝てるトークン候補がない場合）、トークンずれチェックは設定トークンの解決をスキップします。
gateway probe
gateway probe は「すべてをデバッグする」コマンドです。常に次をプローブします。
- 設定済みのリモート Gateway（設定されている場合）、および
- リモートが設定されている場合でも localhost（loopback）。
--url を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では対象に次のラベルが付きます。
URL (explicit)Remote (configured)またはRemote (configured, inactive)Local loopback
複数の Gateway に到達できる場合、それらすべてが表示されます。レスキュー bot など、分離されたプロファイル/ポートを使う場合は複数の Gateway がサポートされますが、ほとんどのインストールでは単一の Gateway を実行します。
解釈
解釈
Reachable: yesは、少なくとも 1 つの対象が WebSocket 接続を受け入れたことを意味します。Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyは、認証についてプローブが証明できた内容を報告します。到達可能性とは別です。Read probe: okは、読み取りスコープの詳細 RPC 呼び出し（health/status/system-presence/config.get）も成功したことを意味します。Read probe: limited - missing scope: operator.readは、接続は成功したが読み取りスコープの RPC が制限されていることを意味します。これは完全な失敗ではなく、劣化した 到達可能性として報告されます。Connect: okの後のRead probe: failedは、Gateway が WebSocket 接続を受け入れたものの、後続の読み取り診断がタイムアウトしたか失敗したことを意味します。これも到達不能な Gateway ではなく、劣化した 到達可能性です。gateway statusと同様に、probe は既存のキャッシュ済みデバイス認証を再利用しますが、初回デバイス ID やペアリング状態は作成しません。- 終了コードが 0 以外になるのは、プローブ対象のどれにも到達できない場合だけです。
JSON 出力
JSON 出力
トップレベル:
ok: 少なくとも 1 つの対象に到達できます。degraded: 少なくとも 1 つの対象が接続を受け入れたものの、完全な詳細 RPC 診断を完了しませんでした。capability: 到達可能な対象全体で見つかった最良の機能（read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope、またはunknown）。primaryTargetId: アクティブな勝者として扱う最良の対象。優先順は、明示的な URL、SSH トンネル、設定済みリモート、local loopback です。warnings[]:code、message、任意のtargetIdsを持つベストエフォートの警告レコード。network: 現在の設定とホストネットワークから導出された local loopback/tailnet URL のヒント。discovery.timeoutMsとdiscovery.count: このプローブパスで使用された実際の検出予算/結果数。
targets[].connect）:ok: 接続後の到達可能性 + 劣化分類。rpcOk: 完全な詳細 RPC の成功。scopeLimited: 必要な operator スコープがないため詳細 RPC が失敗しました。
targets[].auth）:role: 利用可能な場合、hello-okで報告された認証ロール。scopes: 利用可能な場合、hello-okで報告された付与済みスコープ。capability: その対象について表示される認証機能の分類。
一般的な警告コード
一般的な警告コード
ssh_tunnel_failed: SSH トンネルのセットアップに失敗しました。コマンドは直接プローブにフォールバックしました。multiple_gateways: 複数の対象に到達できました。レスキュー bot など、分離されたプロファイルを意図的に実行している場合を除き、これは通常ではありません。auth_secretref_unresolved: 設定済みの認証 SecretRef を、失敗した対象向けに解決できませんでした。probe_scope_limited: WebSocket 接続は成功しましたが、読み取りプローブがoperator.readの欠落により制限されました。
SSH 経由のリモート（Mac アプリとの同等性）
macOS アプリの「Remote over SSH」モードは、ローカルポートフォワードを使用するため、リモート Gateway（loopback のみにバインドされている場合があります）がws://127.0.0.1:<port> で到達可能になります。
CLI での同等操作:
user@host または user@host:port（ポートのデフォルトは 22）。ID ファイル。
解決済みの検出エンドポイント（
local. に設定済みの広域ドメインがあればそれを加えたもの）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
低レベル RPC ヘルパー。
params 用の JSON オブジェクト文字列。
Gateway WebSocket URL。
Gateway トークン。
Gateway パスワード。
タイムアウト予算。
主に、最終ペイロードの前に中間イベントをストリーミングするエージェント風 RPC 向けです。
機械可読な JSON 出力。
--params は有効な JSON である必要があります。Gateway サービスを管理する
wrapper 付きでインストールする
管理対象サービスを別の実行ファイル経由で開始する必要がある場合、たとえば シークレットマネージャー shim や run-as ヘルパーを使う場合は、--wrapper を使用します。wrapper は通常の Gateway 引数を受け取り、
最終的にそれらの引数で openclaw または Node を exec する責任があります。
gateway install はパスが
実行可能ファイルであることを検証し、wrapper をサービスの ProgramArguments に書き込み、
OPENCLAW_WRAPPER をサービス環境に永続化して、以後の強制再インストール、更新、doctor
修復で使用します。
OPENCLAW_WRAPPER をクリアします。
コマンドオプション
コマンドオプション
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>,--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
ライフサイクル動作
ライフサイクル動作
- 管理対象サービスを再起動するには
gateway restartを使用します。再起動の代替としてgateway stopとgateway startを連結しないでください。 - macOS では、
gateway stopはデフォルトでlaunchctl bootoutを使用します。これにより、無効化を永続化せずに現在のブートセッションから LaunchAgent が削除されます。KeepAlive の自動復旧は今後のクラッシュに対して引き続き有効で、gateway startは手動のlaunchctl enableなしで正常に再有効化します。Gateway が次の明示的なgateway startまで再起動しないよう、KeepAlive と RunAtLoad を永続的に抑制するには--disableを渡します。手動停止を再起動やシステム再起動後も維持する必要がある場合に使用してください。 gateway restart --safeは、実行中の Gateway にアクティブな OpenClaw 作業の事前確認を要求し、返信配信、埋め込み実行、タスク実行がドレインされるまで再起動を延期します。--safeは--forceまたは--waitと組み合わせることはできません。gateway restart --wait 30sは、その再起動について設定済みの再起動ドレイン予算を上書きします。単位なしの数値はミリ秒です。s、m、hなどの単位を使用できます。--wait 0は無期限に待機します。gateway restart --safe --skip-deferralは OpenClaw 対応の安全な再起動を実行しますが、延期ゲートをバイパスするため、ブロッカーが報告されても Gateway はただちに再起動を発行します。停止したタスク実行の延期に対するオペレーター用のエスケープハッチです。--safeが必要です。gateway restart --forceはアクティブ作業のドレインをスキップし、ただちに再起動します。オペレーターが一覧表示されたタスクブロッカーをすでに確認しており、Gateway を今すぐ戻したい場合に使用します。- ライフサイクルコマンドはスクリプト用に
--jsonを受け付けます。
インストール時の認証と SecretRefs
インストール時の認証と SecretRefs
- トークン認証でトークンが必要で、
gateway.auth.tokenが SecretRef 管理の場合、gateway installは SecretRef が解決可能であることを検証しますが、解決済みトークンをサービス環境メタデータに永続化しません。 - トークン認証でトークンが必要で、設定済みのトークン SecretRef が未解決の場合、フォールバックのプレーンテキストを永続化するのではなく、インストールは安全側で失敗します。
gateway runのパスワード認証では、インラインの--passwordよりもOPENCLAW_GATEWAY_PASSWORD、--password-file、または SecretRef-backedgateway.auth.passwordを優先してください。- 推論された認証モードでは、シェルだけの
OPENCLAW_GATEWAY_PASSWORDはインストール時のトークン要件を緩和しません。管理対象サービスをインストールする場合は、永続的な設定（gateway.auth.passwordまたは configenv）を使用してください。 gateway.auth.tokenとgateway.auth.passwordの両方が設定され、gateway.auth.modeが未設定の場合、mode が明示的に設定されるまでインストールはブロックされます。
Gateway を検出する（Bonjour）
gateway discover は Gateway ビーコン（_openclaw-gw._tcp）をスキャンします。
- マルチキャスト DNS-SD:
local. - ユニキャスト DNS-SD（Wide-Area Bonjour）: ドメイン（例:
openclaw.internal.）を選択し、split DNS と DNS サーバーを設定します。Bonjour を参照してください。
role（Gateway ロールのヒント）transport（トランスポートのヒント、例:gateway）gatewayPort（WebSocket ポート、通常は18789）sshPort（完全検出モードのみ。存在しない場合、クライアントは SSH ターゲットのデフォルトを22にします）tailnetDns（利用可能な場合の MagicDNS ホスト名）gatewayTls/gatewayTlsSha256（TLS 有効 + 証明書フィンガープリント）cliPath（完全検出モードのみ）
gateway discover
コマンドごとのタイムアウト（参照/解決）。
機械可読出力（スタイルとスピナーも無効化）。
- CLI は
local.に加えて、有効化されている場合は設定済みの広域ドメインをスキャンします。 - JSON 出力の
wsUrlは、lanHostやtailnetDnsなどの TXT のみのヒントではなく、解決済みサービスエンドポイントから派生します。 local.mDNS と広域 DNS-SD では、sshPortとcliPathはdiscovery.mdns.modeがfullの場合にのみ公開されます。