34 KiB
34 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Gateway | OpenClaw Gateway CLI (`openclaw gateway`) — Gatewayを実行、照会、検出する | Gateway |
|
Gateway は OpenClaw の WebSocket サーバーです（チャネル、ノード、セッション、フック）。このページのサブコマンドは openclaw gateway … 配下にあります。
Gateway を実行する
ローカル Gateway プロセスを実行します:
openclaw gateway
フォアグラウンドのエイリアス:
openclaw gateway run
オプション
WebSocket ポート（デフォルトは設定/環境変数から取得され、通常は `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
openclaw gateway restart --safe
openclaw gateway restart --force
openclaw gateway restart --safe は、再起動前に実行中の Gateway にアクティブな OpenClaw 作業の事前確認を要求します。キュー済み操作、返信配信、埋め込み実行、またはタスク実行がアクティブな場合、Gateway はブロッカーを報告し、重複する安全な再起動リクエストをまとめ、アクティブな作業がなくなったら再起動します。通常の restart は互換性のため、既存のサービスマネージャー動作を維持します。即時上書きパスを明示的に使いたい場合にのみ --force を使用してください。
起動プロファイリング
OPENCLAW_GATEWAY_STARTUP_TRACE=1を設定すると、Gateway 起動中のフェーズ時間がログに記録されます。これには、フェーズごとのeventLoopMax遅延と、インストール済みインデックス、マニフェストレジストリ、起動計画、owner-map 処理に関する Plugin ルックアップテーブルの時間が含まれます。OPENCLAW_DIAGNOSTICS=timelineとOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>を設定すると、外部 QA ハーネス向けにベストエフォートの JSONL 起動診断タイムラインを書き込みます。設定内のdiagnostics.flags: ["timeline"]でフラグを有効にすることもできますが、パスは引き続き環境変数から指定します。イベントループサンプルを含めるには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 `: Gateway WebSocket URL。 - `--token `: Gateway トークン。 - `--password `: Gateway パスワード。 - `--timeout `: タイムアウト/予算（コマンドごとに異なります）。 - `--expect-final`: 「final」レスポンスを待ちます（エージェント呼び出し）。 `--url` を設定すると、CLI は設定や環境変数の資格情報にフォールバックしません。`--token` または `--password` を明示的に渡してください。明示的な資格情報がない場合はエラーです。gateway health
openclaw gateway health --url ws://127.0.0.1:18789
HTTP /healthz エンドポイントは liveness プローブです。サーバーが HTTP に応答できるようになると返ります。HTTP /readyz エンドポイントはより厳密で、起動時の Plugin サイドカー、チャネル、または設定済みフックがまだ安定していない間は赤のままです。ローカルまたは認証済みの詳細 readiness レスポンスには、イベントループ遅延、イベントループ使用率、CPU コア比率、degraded フラグを含む eventLoop 診断ブロックが含まれます。
gateway usage-cost
セッションログから使用コストの概要を取得します。
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
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
gateway diagnostics export
バグレポートに添付するために設計されたローカル診断 zip を書き込みます。プライバシーモデルとバンドル内容については、診断エクスポート を参照してください。
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --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
gateway probe
gateway probe は「すべてをデバッグする」コマンドです。常に次をプローブします。
- 設定済みのリモート Gateway（設定されている場合）、および
- localhost（ループバック）。リモートが設定されている場合でも対象です。
--url を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では対象に次のラベルが付きます。
URL (explicit)Remote (configured)またはRemote (configured, inactive)Local loopback
openclaw gateway probe
openclaw gateway probe --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 経由のリモート（Mac アプリとの同等性）
macOS アプリの「Remote over SSH」モードはローカルポート転送を使用するため、リモート Gateway（ループバックのみにバインドされている場合があります）に ws://127.0.0.1:<port> で到達できるようになります。
CLI での同等操作:
openclaw gateway probe --ssh user@gateway-host
設定（省略可能、既定値として使用）:
gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
低レベル RPC ヘルパー。
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Gateway サービスを管理する
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
ラッパー付きでインストールする
管理対象サービスを別の実行可能ファイル経由で起動する必要がある場合は、--wrapper を使用します。たとえば、シークレットマネージャーの shim や run-as ヘルパーです。ラッパーは通常の 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）をスキャンします。
- Multicast DNS-SD:
local. - Unicast DNS-SD（Wide-Area Bonjour）: ドメイン（例:
openclaw.internal.）を選択し、分割 DNS + DNS サーバーを設定します。Bonjour を参照してください。
Bonjour 検出が有効（デフォルト）な Gateway だけがビーコンをアドバタイズします。
Wide-Area 検出レコードには以下が含まれます（TXT）:
role（Gateway ロールのヒント）transport（トランスポートのヒント、例:gateway）gatewayPort（WebSocket ポート、通常は18789）sshPort（任意。存在しない場合、クライアントは SSH ターゲットのデフォルトを22にします）tailnetDns（MagicDNS ホスト名、利用可能な場合）gatewayTls/gatewayTlsSha256（TLS 有効 + 証明書フィンガープリント）cliPath（wide-area ゾーンに書き込まれるリモートインストールのヒント）
gateway discover
openclaw gateway discover
例:
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'