Gatewayランブック

Gatewayサービスの初日セットアップと運用管理にこのページを活用してください。

5分でローカル起動

ステップ1：Gatewayを起動

openclaw gateway --port 18789
# debug/traceをstdioにミラー
openclaw gateway --port 18789 --verbose
# 選択したポートのリスナーを強制終了してから起動
openclaw gateway --force

ステップ2：サービスの健全性を確認

openclaw gateway status
openclaw status
openclaw logs --follow

正常なベースライン：Runtime: runningおよびRPC probe: ok。

ステップ3：チャンネルの準備状態を検証

openclaw channels status --probe

注意： Gatewayの設定リロードはアクティブな設定ファイルパス（プロファイル/ステートのデフォルト、またはOPENCLAW_CONFIG_PATHが設定されている場合はそこから解決）を監視します。 デフォルトモードはgateway.reload.mode="hybrid"です。

ランタイムモデル

  • ルーティング、コントロールプレーン、チャンネル接続のための常時稼働プロセス。
  • 単一の多重化ポート：
    • WebSocketコントロール/RPC
    • HTTP API（OpenAI互換、Responses、ツールの呼び出し）
    • コントロールUIとフック
  • デフォルトバインドモード：loopback。
  • 認証はデフォルトで必須（gateway.auth.token / gateway.auth.password、またはOPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。

ポートとバインドの優先順位

設定解決順序
Gatewayポート--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
バインドモードCLI/override → gateway.bind → loopback

ホットリロードモード

gateway.reload.mode動作
off設定リロードなし
hotホットセーフな変更のみ適用
restartリロード必須の変更で再起動
hybrid（デフォルト）セーフならホット適用、必須なら再起動

オペレーターコマンドセット

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

リモートアクセス

推奨：Tailscale/VPN。 フォールバック：SSHトンネル。

ssh -N -L 18789:127.0.0.1:18789 user@host

ローカルでws://127.0.0.1:18789にクライアントを接続します。

警告： ゲートウェイ認証が設定されている場合、SSHトンネル経由でもクライアントは認証（token/password）を送信する必要があります。

参照：リモートGateway、認証、Tailscale。

スーパーバイザーとサービスライフサイクル

本番環境に近い信頼性のために、監視付き実行を使用してください。

macOS（launchd）

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgentラベルはai.openclaw.gateway（デフォルト）またはai.openclaw.<profile>（名前付きプロファイル）。openclaw doctorがサービス設定のドリフトを監査・修復します。

Linux（systemdユーザー）

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

ログアウト後の持続性のために、lingeringを有効にしてください：

sudo loginctl enable-linger <user>

Linux（システムサービス）

マルチユーザー/常時稼働ホストにはシステムユニットを使用してください。

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

1台のホストで複数のGateway

ほとんどのセットアップでは1つのGatewayを実行するべきです。 複数を使用するのは、厳密な分離/冗長性が必要な場合のみです（例：レスキュープロファイル）。

インスタンスごとのチェックリスト：

  • 一意のgateway.port
  • 一意のOPENCLAW_CONFIG_PATH
  • 一意のOPENCLAW_STATE_DIR
  • 一意のagents.defaults.workspace

例：

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

参照：複数のGateway。

開発プロファイルのクイックパス

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

デフォルトには分離されたstate/configとベースゲートウェイポート19001が含まれます。

プロトコルクイックリファレンス（オペレータービュー）

  • 最初のクライアントフレームはconnectでなければならない。
  • Gatewayはhello-okスナップショット（presence、health、stateVersion、uptimeMs、limits/policy）を返す。
  • リクエスト：req(method, params) → res(ok/payload|error)。
  • 一般的なイベント：connect.challenge、agent、chat、presence、tick、health、heartbeat、shutdown。

エージェント実行は2段階：

  1. 即時の受理ack（status:"accepted"）
  2. 最終完了レスポンス（status:"ok"|"error"）、間にストリーミングagentイベント。

完全なプロトコルドキュメント：Gatewayプロトコル。

運用チェック

ライブネス

  • WSを開いてconnectを送信。
  • スナップショット付きのhello-okレスポンスを期待。

レディネス

openclaw gateway status
openclaw channels status --probe
openclaw health

ギャップリカバリー

イベントはリプレイされません。シーケンスギャップが発生した場合、続行前にステート（health、system-presence）をリフレッシュしてください。

よくある障害シグネチャ

シグネチャ考えられる原因
refusing to bind gateway ... without auth非ループバックバインドでトークン/パスワードなし
another gateway instance is already listening / EADDRINUSEポート競合
Gateway start blocked: set gateway.mode=local設定がリモートモードになっている
unauthorized during connectクライアントとゲートウェイ間の認証不一致

完全な診断手順についてはGatewayトラブルシューティングを使用してください。

安全性の保証

  • Gatewayプロトコルクライアントは、Gatewayが利用不可の場合に即座に失敗します（暗黙的なダイレクトチャンネルフォールバックなし）。
  • 無効/非connectの最初のフレームは拒否されて切断されます。
  • グレースフルシャットダウンではソケットクローズ前にshutdownイベントを発行します。

関連：

arrow_back
前へ
Peekaboo
次へ
Configuration
arrow_forward