OpenClaw Gateway CLI操作ガイド：コマンドと設定を完全網羅

Gateway CLI の概要

Gateway は OpenClaw の WebSocket サーバーであり、channels、nodes、sessions、hooks を管理する中心的な役割を担っています。この CLI を使用することで、サーバーの起動や状態確認を効率的に行うことが可能です。

このページで紹介するサブコマンドは、すべて openclaw gateway … の形式で使用します。

Gateway サーバーの起動

Gateway サーバーをローカル環境で立ち上げるには、以下のコマンドを実行します。これにより、Node.js 環境上で WebSocket 接続の待受が開始されます。

ターミナルを開き、プロジェクトのルートディレクトリに移動します。
以下のコマンドを実行して Gateway を起動します。

openclaw gateway start

Gateway の設定確認

現在適用されている Gateway の設定内容を JSON 形式で確認することができます。設定ファイルに誤りがないか確認したい場合に非常に便利です。

設定ファイルが正しく配置されていることを確認します。
以下のコマンドを実行して、現在の設定を出力します。

openclaw gateway config

Gateway の接続状況の確認

現在 Gateway に接続されているノードやセッションの情報を一覧で取得できます。システムが正常に稼働しているか監視する際に活用してください。

サーバーが起動している状態で、以下のコマンドを入力します。
出力されたリストから、各ノードのステータスを確認します。

openclaw gateway status

Gateway のデバッグモード

開発中に webhook の動作や通信内容を詳細に追跡したい場合は、デバッグモードを使用します。このモードでは、詳細なログがコンソールに表示されます。

開発環境で Gateway を起動する際に、デバッグフラグを付与します。
以下のコマンドを実行して、詳細なログ出力を有効にします。

openclaw gateway start --debug

Gateway を実行する

ローカル環境で Gateway プロセスを起動する方法を説明します。

openclaw gateway

フォアグラウンドで実行するためのエイリアスは以下の通りです。

openclaw gateway run

注意点は以下の通りです。

デフォルトでは、~/.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 モード入力でラップしている場合は、終了前にターミナルを復元してください。

オプション

Gateway の動作を細かく制御するためのオプションが用意されています。

--port <port>: WebSocket のポート番号を指定します（デフォルトは設定や環境変数から取得され、通常は 18789 です）。
--bind <loopback|lan|tailnet|auto|custom>: リスナーのバインドモードを指定します。
--auth <token|password>: 認証モードを上書きします。
--token <token>: トークンを上書きします（プロセスに対して OPENCLAW_GATEWAY_TOKEN も設定されます）。
--password <password>: パスワードを上書きします。警告：インラインでパスワードを指定すると、ローカルのプロセス一覧に表示される可能性があるため注意してください。
--password-file <path>: Gateway のパスワードをファイルから読み込みます。
--tailscale <off|serve|funnel>: Tailscale を介して Gateway を公開します。
--tailscale-reset-on-exit: 終了時に Tailscale の serve/funnel 設定をリセットします。
--allow-unconfigured: 設定ファイルに gateway.mode=local がなくても Gateway の起動を許可します。これはアドホックや開発時のブートストラップ専用の起動ガード回避であり、設定ファイルの書き込みや修復は行いません。
--dev: 設定ファイルが存在しない場合に、開発用の設定とワークスペースを作成します（BOOTSTRAP.md をスキップします）。
--reset: 開発用の設定、認証情報、セッション、ワークスペースをリセットします（--dev が必要です）。
--force: 起動前に、指定したポートで既存のリスナーを強制終了します。
--verbose: 詳細なログを出力します。
--cli-backend-logs: コンソールに CLI バックエンドのログのみを表示し、stdout/stderr を有効にします。
--ws-log <auto|full|compact>: WebSocket のログスタイルを指定します（デフォルトは auto）。
--compact: --ws-log compact のエイリアスです。
--raw-stream: モデルのストリームイベントを JSONL 形式でログ出力します。
--raw-stream-path <path>: JSONL 形式の生ストリームログの保存先パスを指定します。

起動時のプロファイリング

Gateway の起動パフォーマンスを計測するための機能です。

OPENCLAW_GATEWAY_STARTUP_TRACE=1 を設定すると、Gateway 起動時の各フェーズのタイミングがログに記録されます。
以下のコマンドを実行して、Gateway の起動をベンチマークします。このベンチマークは、最初のプロセス出力、/healthz、/readyz、および起動トレースのタイミングを記録します。

pnpm test:startup:gateway -- --runs 5 --warmup 1

AI Setup Assistant

実行中の Gateway をクエリする

すべてのクエリコマンドは WebSocket RPC を使用します。

出力モードは以下の通りです。

デフォルト: 人間が読みやすい形式（TTYで色付けされます）。
--json: 機械可読な JSON 形式（スタイルやスピナーは無効化されます）。
--no-color (または NO_COLOR=1): 人間向けのレイアウトを維持したまま、ANSI カラーを無効にします。

共有オプション（サポートされている場合）は以下の通りです。

--url <url>: Gateway の WebSocket URL。
--token <token>: Gateway のトークン。
--password <password>: Gateway のパスワード。
--timeout <ms>: タイムアウトまたは予算（コマンドによって異なります）。
--expect-final: 「最終」レスポンス（エージェント呼び出し）を待機します。

注意: --url を設定した場合、CLI は設定ファイルや環境変数の認証情報にフォールバックしません。--token または --password を明示的に渡してください。明示的な認証情報がない場合はエラーとなります。

`gateway health`

このコマンドは、Gateway の生存確認を行うためのものです。

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

HTTP の /healthz エンドポイントは生存確認（liveness probe）用で、サーバーが HTTP に応答できるようになった時点で返答します。HTTP の /readyz エンドポイントはより厳格で、スタートアップのサイドカー、チャネル、または設定された webhook 等が準備完了状態になるまで赤色のままとなります。

`gateway usage-cost`

セッションログから利用料金の概要を取得します。

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

オプションは以下の通りです。

--days <days>: 集計対象の日数（デフォルトは 30）。

`gateway status`

gateway status は、Gateway サービス（launchd / systemd / schtasks）の状態に加え、接続性や認証機能のオプションのプローブ結果を表示します。

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

オプションは以下の通りです。

--url <url>: 明示的なプローブ対象を追加します。設定済みのリモートおよびローカルホストも引き続きプローブされます。
--token <token>: プローブ用のトークン認証。
--password <password>: プローブ用のパスワード認証。
--timeout <ms>: プローブのタイムアウト（デフォルトは 10000）。
--no-probe: 接続性プローブをスキップします（サービスの状態のみ表示）。
--deep: システムレベルのサービスもスキャンします。
--require-rpc: デフォルトの接続性プローブを読み取りプローブにアップグレードし、その読み取りプローブが失敗した場合は非ゼロで終了します。--no-probe とは併用できません。

注意点:

gateway status は、ローカルの CLI 設定が欠落しているか無効な場合でも、診断のために利用可能です。
デフォルトの gateway status は、サービスの状態、WebSocket 接続、およびハンドシェイク時に確認可能な認証機能の有効性を証明します。読み取り/書き込み/管理操作を証明するものではありません。
gateway status は、可能な限りプローブ認証のために設定された SecretRefs を解決します。
このコマンドパスで必要な認証 SecretRef が解決できない場合、gateway status --json はプローブの接続や認証が失敗した際に rpc.authWarning を報告します。--token/--password を明示的に渡すか、先にシークレットソースを解決してください。
プローブが成功した場合、誤検知を避けるために未解決の認証参照警告は抑制されます。
リスニングサービスが稼働しているだけでは不十分で、読み取りスコープの RPC 呼び出しが正常であることを確認する必要があるスクリプトや自動化ツールでは、--require-rpc を使用してください。
--deep は、追加の launchd / systemd / schtasks インストールに対するベストエフォート型のスキャンを追加します。複数の Gateway 関連サービスが検出された場合、人間向けの出力にはクリーンアップのヒントが表示され、ほとんどのセットアップでは1台のマシンにつき1つの Gateway を実行すべきである旨が警告されます。
人間向けの出力には、解決されたファイルログパスと、プロファイルや状態ディレクトリのズレを診断するのに役立つ CLI 対サービスの設定パス/有効性スナップショットが含まれます。
Linux の systemd インストールでは、サービス認証のズレチェックはユニットから Environment= および EnvironmentFile= の値の両方を読み取ります（%h、引用符付きパス、複数のファイル、およびオプションの - ファイルを含みます）。
ズレチェックは、マージされたランタイム環境（サービスコマンドの環境が優先され、次にプロセス環境がフォールバック）を使用して gateway.auth.token の SecretRefs を解決します。
トークン認証が有効でない場合（gateway.auth.mode が password / none / trusted-proxy に明示されている、またはモードが未設定でパスワードが優先されトークンの候補がない場合）、トークンのズレチェックは設定トークンの解決をスキップします。

`gateway probe`

gateway probe は「すべてをデバッグする」ためのコマンドです。常に以下の対象をプローブします。

設定済みのリモート Gateway（設定されている場合）
ローカルホスト（ループバック）（リモートが設定されている場合でも）

--url を渡すと、その明示的なターゲットが上記の両方よりも優先して追加されます。人間向けの出力では、ターゲットが以下のようにラベル付けされます。

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

複数の Gateway に到達可能な場合は、すべてが表示されます。複数の Gateway は、分離されたプロファイル/ポート（例: レスキューボット）を使用する場合にサポートされますが、ほとんどのインストールでは単一の Gateway を実行します。

openclaw gateway probe
openclaw gateway probe --json

解釈:

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 が制限されていることを意味します。これは完全な失敗ではなく、degraded（機能低下）した到達可能性として報告されます。
終了コードは、プローブされたターゲットに到達できない場合にのみ非ゼロとなります。

JSON に関する注意点 (--json):

トップレベル:
- ok: 少なくとも1つのターゲットに到達可能。
- degraded: 少なくとも1つのターゲットでスコープ制限された詳細 RPC が発生。
- capability: 到達可能なターゲット全体で確認された最良の機能（read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, または unknown）。
- primaryTargetId: 以下の順序でアクティブな勝者として扱う最良のターゲット（明示的な URL、SSH トンネル、設定済みのリモート、ローカルループバック）。
- warnings[]: code、message、およびオプションの targetIds を含むベストエフォート型の警告レコード。
- network: 現在の設定とホストネットワークから導出されたローカルループバック/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: 複数のターゲットに到達可能でした。これは、レスキューボットなどの分離されたプロファイルを意図的に実行している場合を除き、一般的ではありません。
auth_secretref_unresolved: 失敗したターゲットに対して、設定された認証 SecretRef を解決できませんでした。
probe_scope_limited: WebSocket 接続は成功しましたが、読み取りプローブが operator.read の欠如によって制限されました。

SSH 経由のリモート接続 (Mac アプリとの互換性)

macOS アプリの「SSH 経由のリモート」モードは、ローカルポートフォワードを使用して、リモートの Gateway（ループバックのみにバインドされている可能性がある）に ws://127.0.0.1:<port> で到達できるようにします。

CLI での同等の操作:

openclaw gateway probe --ssh user@gateway-host

オプションは以下の通りです。

--ssh <target>: user@host または user@host:port（ポートのデフォルトは 22）。
--ssh-identity <path>: ID ファイル。
--ssh-auto: 解決された探索エンドポイント（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 <json>: パラメータ用の JSON オブジェクト文字列（デフォルトは {}）。
--url <url>
--token <token>
--password <password>
--timeout <ms>
--expect-final
--json

注意点:

--params は有効な JSON である必要があります。
--expect-final は、主に最終的なペイロードの前に中間イベントをストリーミングするエージェントスタイルの RPC 用です。

AI Setup Assistant

Gateway サービスの管理

OpenClaw Gateway の運用において、サービスのライフサイクル管理は非常に重要です。以下のコマンドを使用して、サービスのインストールから起動、停止までを効率的に実行できます。

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

コマンドのオプションについては、以下の詳細を確認してください。

gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
gateway install: --port, --runtime <node|bun>, --token, --force, --json
gateway uninstall|start|stop|restart: --json

Gateway サービスに関する注意点

Gateway サービスを適切に設定し、安全に運用するための重要なポイントをまとめました。設定時にはこれらの仕様を考慮してください。

gateway install コマンドは、--port、--runtime、--token、--force、--json の各オプションをサポートしています。
トークン認証が必要な環境で gateway.auth.token が SecretRef によって管理されている場合、gateway install はその SecretRef が解決可能であることを検証しますが、解決されたトークンをサービス環境のメタデータとして永続化することはありません。
トークン認証が必要な状況で、設定されたトークンの SecretRef が解決できない場合、インストールは失敗します。プレーンテキストのフォールバックを永続化することはありません。
gateway run でパスワード認証を行う際は、インラインの --password よりも、OPENCLAW_GATEWAY_PASSWORD、--password-file、または SecretRef でバックアップされた gateway.auth.password を使用することを推奨します。
推論認証モードにおいて、シェルのみで設定された OPENCLAW_GATEWAY_PASSWORD は、インストールのトークン要件を緩和しません。管理対象サービスをインストールする際は、永続的な設定（gateway.auth.password または設定ファイル内の env）を使用してください。
gateway.auth.token と gateway.auth.password の両方が設定されており、かつ gateway.auth.mode が未設定の場合、モードが明示的に指定されるまでインストールはブロックされます。
ライフサイクル管理コマンドは、スクリプト作成用に --json オプションを受け付けます。

AI Setup Assistant

Gateway の検出 (Bonjour)

OpenClaw を使用してネットワーク上の Gateway を検出するには、gateway discover コマンドを実行します。このコマンドは、_openclaw-gw._tcp という名前の Gateway ビーコンをスキャンします。

Multicast DNS-SD: local. ドメインを対象とします。
Unicast DNS-SD (Wide-Area Bonjour): 任意のドメイン（例: openclaw.internal.）を選択し、split DNS と DNS サーバーを設定します。詳細については /gateway/bonjour を参照してください。

Bonjour による検出が有効（デフォルト設定）になっている Gateway のみが、ビーコンをアドバタイズします。

Wide-Area 検出レコードには、以下の情報（TXT）が含まれます。

role (Gateway の役割のヒント)
transport (トランスポートのヒント、例: gateway)
gatewayPort (WebSocket ポート、通常は 18789)
sshPort (オプション。指定がない場合、クライアントはデフォルトで 22 を対象とします)
tailnetDns (利用可能な場合の MagicDNS ホスト名)
gatewayTls / gatewayTlsSha256 (TLS が有効な場合の証明書フィンガープリント)
cliPath (Wide-Area ゾーンに書き込まれるリモートインストールのヒント)

gateway discover コマンドの実行

OpenClaw の CLI を使用して、ネットワーク内の Gateway を素早く見つけることができます。

openclaw gateway discover

オプションは以下の通りです。

--timeout <ms>: コマンドごとのタイムアウト時間（ブラウズ/解決）。デフォルトは 2000 です。
--json: 機械可読な形式で出力します（スタイリングやスピナー表示は無効になります）。

実行例は以下の通りです。

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

注意点として、以下の事項を確認してください。

CLI は local. ドメインに加え、Wide-Area ドメインが有効な場合はその設定ドメインもスキャンします。
JSON 出力に含まれる wsUrl は、解決されたサービスエンドポイントから導出されます。lanHost や tailnetDns といった TXT レコードのみのヒントからは導出されません。
local. mDNS において、sshPort および cliPath は discovery.mdns.mode が full に設定されている場合のみブロードキャストされます。Wide-Area DNS-SD では引き続き cliPath が書き込まれますが、sshPort はオプションのままとなります。

AI Setup Assistant

OpenClaw Expert

まだ解決しませんか？

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