Gateway

Gateway は OpenClaw の WebSocket サーバー（チャンネル、ノード、セッション、フック）です。このページのサブコマンドは openclaw gateway … 配下にあります。

# Gateway を実行する

ローカル Gateway プロセスを実行します。

openclaw gateway

フォアグラウンドのエイリアス:

openclaw gateway run

# オプション

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> WebSocket ポート（デフォルトは設定/env 由来。通常は 18789）。

"--bind

"--auth

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> トークンの上書き（プロセスに対して OPENCLAW_GATEWAY_TOKEN も設定します）。

"--password

"--tailscale

--tailscale-reset-on-exitboolean

シャットダウン時に Tailscale serve/funnel 設定をリセットします。

--allow-unconfiguredboolean

設定内に gateway.mode=local がなくても Gateway の起動を許可します。アドホック/開発用ブートストラップの場合のみ起動ガードをバイパスします。設定ファイルの書き込みや修復は行いません。

--devboolean

見つからない場合に開発用設定 + ワークスペースを作成します（BOOTSTRAP.md はスキップ）。

--resetboolean

開発用設定 + 認証情報 + セッション + ワークスペースをリセットします（--dev が必要）。

--forceboolean

起動前に、選択されたポート上の既存リスナーをすべて終了します。

--verboseboolean

詳細ログ。

--cli-backend-logsboolean

コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効化します）。

"--ws-log

--compactboolean

--ws-log compact のエイリアス。

--raw-streamboolean

生のモデルストリームイベントを jsonl にログ出力します。

# Gateway を再起動する

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force

openclaw gateway restart --safe は、再起動前に実行中の Gateway にアクティブな OpenClaw 作業の事前確認を要求します。キュー内の操作、返信配信、埋め込み実行、またはタスク実行がアクティブな場合、Gateway はブロッカーを報告し、重複する安全な再起動要求をまとめ、アクティブな作業が排出された後に再起動します。通常の restart は互換性のために既存のサービスマネージャー動作を維持します。即時上書きパスを明示的に必要とする場合にのみ --force を使用してください。

# 起動プロファイリング

• 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 を追加します。
• Gateway 起動をベンチマークするには pnpm test:startup:gateway -- --runs 5 --warmup 1 を実行します。ベンチマークは最初のプロセス出力、/healthz、/readyz、起動トレースタイミング、イベントループ遅延、Plugin ルックアップテーブルタイミングの詳細を記録します。

# 実行中の Gateway を照会する

すべての照会コマンドは WebSocket RPC を使用します。

# gateway health

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

HTTP /healthz エンドポイントは liveness probe です。サーバーが HTTP に応答できるようになると返ります。HTTP /readyz エンドポイントはより厳格で、起動時の Plugin サイドカー、チャンネル、または設定済みフックがまだ落ち着いていない間は赤のままです。ローカルまたは認証済みの詳細な readiness 応答には、イベントループ遅延、イベントループ使用率、CPU コア比率、degraded フラグを含む eventLoop 診断ブロックが含まれます。

# gateway usage-cost

セッションログから usage-cost のサマリーを取得します。

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

"--days

# gateway stability

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

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw 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 などの診断イベントタイプでフィルターします。

"--since-seq

--bundle [path]string

実行中の Gateway を呼び出す代わりに、永続化された安定性バンドルを読み取ります。状態ディレクトリ下の最新バンドルには --bundle latest（または単に --bundle）を使用するか、バンドル JSON パスを直接渡します。

--exportboolean

安定性の詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。

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

# gateway diagnostics export

バグレポートに添付するために設計されたローカル診断 zip を書き込みます。プライバシーモデルとバンドル内容については、診断のエクスポート を参照してください。

openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json

"--log-lines

"--log-bytes

"--url

"--token

"--password

"--timeout

--no-stability-bundleboolean

永続化された安定性バンドルの検索をスキップします。

--jsonboolean

書き込まれたパス、サイズ、マニフェストを JSON として出力します。

エクスポートには、マニフェスト、Markdown サマリー、設定形状、サニタイズ済み設定詳細、サニタイズ済みログサマリー、サニタイズ済み Gateway ステータス/ヘルススナップショット、および存在する場合は最新の安定性バンドルが含まれます。

これは共有されることを想定しています。デバッグに役立つ運用詳細を保持します。たとえば、安全な OpenClaw ログフィールド、サブシステム名、ステータスコード、所要時間、設定済みモード、ポート、Plugin ID、プロバイダー ID、非シークレット機能設定、編集済み運用ログメッセージなどです。チャットテキスト、webhook 本文、ツール出力、認証情報、Cookie、アカウント/メッセージ識別子、プロンプト/指示テキスト、ホスト名、シークレット値は省略または編集されます。LogTape スタイルのメッセージがユーザー/チャット/ツールのペイロードテキストのように見える場合、エクスポートはメッセージが省略されたこととそのバイト数のみを保持します。

# gateway status

gateway status は Gateway サービス（launchd/systemd/schtasks）に加えて、接続性/認証機能の任意のプローブを表示します。

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

"--url

"--token

"--password

"--timeout

--no-probeboolean

接続性プローブをスキップします（サービスのみの表示）。

--deepboolean

システムレベルのサービスもスキャンします。

--require-rpcboolean

既定の接続性プローブを読み取りプローブに昇格し、その読み取りプローブが失敗した場合に 0 以外で終了します。--no-probe と組み合わせることはできません。

# gateway probe

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

• 設定済みのリモート Gateway（設定されている場合）、および
• localhost（loopback）。リモートが設定されている場合でも対象になります。

--url を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では、対象に次のラベルが付きます。

• URL (explicit)
• Remote (configured) または Remote (configured, inactive)
• Local loopback

openclaw gateway probe
openclaw gateway probe --json

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

macOS アプリの「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）。

--ssh-autoboolean

解決済みの検出エンドポイント（local. と、設定済みの広域ドメインがあればそれを加えたもの）から、最初に検出された Gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。

設定（任意、既定値として使用）:

• gateway.remote.sshTarget
• gateway.remote.sshIdentity

# gateway call <method>

低レベル RPC ヘルパー。

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

"--params

"--url

"--token

"--password

"--timeout

--expect-finalboolean

主に、最終ペイロードの前に中間イベントをストリームする agent スタイルの RPC 向けです。

--jsonboolean

機械可読 JSON 出力。

# Gateway サービスを管理する

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

# ラッパー付きでインストールする

管理対象サービスを別の実行可能ファイル経由で開始する必要がある場合、たとえば シークレットマネージャーの shim や run-as ヘルパーを使う場合は --wrapper を使用します。ラッパーは通常の Gateway 引数を受け取り、 最終的にそれらの引数で openclaw または Node を exec する責任があります。

cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart

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

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

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

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw 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）
• sshPort（任意。存在しない場合、クライアントは SSH ターゲットのデフォルトを 22 にします）
• tailnetDns（利用可能な場合は MagicDNS ホスト名）
• gatewayTls / gatewayTlsSha256（TLS 有効 + 証明書フィンガープリント）
• cliPath（ワイドエリアゾーンに書き込まれるリモートインストールのヒント）

# gateway discover

openclaw gateway discover

"--timeout

--jsonboolean

機械可読出力（スタイル/スピナーも無効化します）。

例:

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

# 関連

• CLI リファレンス
• Gateway ランブック