メインコンテンツへスキップ

​
Gatewayランブック

このページは、Gatewayサービスの初日セットアップと継続運用のために使用します。

詳細なトラブルシューティング

症状から始める診断と、正確なコマンド手順およびログシグネチャ。

設定

タスク指向のセットアップガイドと完全な設定リファレンス。

シークレット管理

SecretRefの契約、ランタイムスナップショットの挙動、移行/再読み込み操作。

シークレットプラン契約

正確なsecrets applyのターゲット/パスルールと、ref専用認証プロファイルの挙動。

​
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がある場合、これはアカウントごとのライブチャネルプローブと任意の監査を実行します。 Gatewayに到達できない場合、CLIはライブプローブ出力の代わりに、設定のみのチャネルサマリーへフォールバックします。
Gateway設定の再読み込みは、アクティブな設定ファイルパスを監視します（プロファイル/状態のデフォルトから解決されるか、設定されている場合はOPENCLAW_CONFIG_PATH）。 デフォルトモードはgateway.reload.mode="hybrid"です。 最初の読み込みが成功した後、実行中のプロセスはアクティブなインメモリ設定スナップショットを提供し、再読み込みに成功するとそのスナップショットをアトミックに入れ替えます。

​
ランタイムモデル

  • ルーティング、コントロールプレーン、チャネル接続のための常時稼働プロセスが1つ。
  • 以下のための単一の多重化ポート:
    • WebSocket control/RPC
    • HTTP APIs、OpenAI互換（/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke）
    • Control UI とフック
  • デフォルトのバインドモード: loopback。
  • デフォルトで認証が必要です。共有シークレット構成では gateway.auth.token / gateway.auth.password（または OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）を使用し、非loopbackの リバースプロキシ構成ではgateway.auth.mode: "trusted-proxy"を使用できます。

​
OpenAI互換エンドポイント

OpenClawの現在最も効果の高い互換サーフェスは次のとおりです。
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
このセットが重要な理由:
  • ほとんどのOpen WebUI、LobeChat、LibreChat連携は最初に/v1/modelsをプローブします。
  • 多くのRAGおよびメモリパイプラインは/v1/embeddingsを想定しています。
  • エージェントネイティブのクライアントはますます/v1/responsesを好むようになっています。
計画メモ:
  • /v1/modelsはagent-firstです。openclaw、openclaw/default、openclaw/<agentId>を返します。
  • openclaw/defaultは、常に設定済みのデフォルトエージェントにマップされる安定したエイリアスです。
  • バックエンドのプロバイダー/モデルオーバーライドを行いたい場合はx-openclaw-modelを使用してください。それ以外では、選択されたエージェントの通常のモデルと埋め込み設定がそのまま制御を保持します。
これらはすべてメインのGatewayポートで動作し、Gateway HTTP APIの他の部分と同じ信頼されたオペレーター認証境界を使用します。

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

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

​
ホットリロードモード

gateway.reload.mode挙動
off設定の再読み込みなし
hotホットセーフな変更のみ適用
restart再読み込みが必要な変更時に再起動
hybrid (default)安全ならホット適用し、必要なら再起動

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

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
gateway status --deepは追加のサービス検出（LaunchDaemons/systemd system units/schtasks）のためのものであり、より深いRPCヘルスプローブではありません。

​
複数のGateway（同一ホスト）

ほとんどのインストールでは、マシンごとにGatewayは1つで十分です。1つのGatewayで複数の agentsとchannelsをホストできます。 複数のGatewayが必要なのは、意図的に分離またはレスキューボットを使いたい場合だけです。 便利な確認: 
openclaw gateway status --deep
openclaw gateway probe
期待されること:
  • gateway status --deepはOther gateway-like services detected (best effort)を報告し、 古いlaunchd/systemd/schtasksインストールがまだ残っている場合にクリーンアップのヒントを表示することがあります。
  • gateway probeは、複数のターゲットが応答した場合にmultiple reachable gatewaysを警告することがあります。
  • それが意図的な場合は、Gatewayごとにポート、設定/状態、ワークスペースルートを分離してください。
詳細なセットアップ: /gateway/multiple-gateways。

​
リモートアクセス

推奨: Tailscale/VPN。 代替: SSHトンネル。 
ssh -N -L 18789:127.0.0.1:18789 user@host
その後、クライアントをローカルでws://127.0.0.1:18789に接続します。
SSHトンネルはGateway認証を回避しません。共有シークレット認証では、クライアントは トンネル経由でも引き続きtoken/passwordを送る必要があります。IDを伴うモードでは、 リクエストは引き続きその認証パスを満たす必要があります。
参照: Remote Gateway, Authentication, Tailscale。

​
監督実行とサービスライフサイクル

本番に近い信頼性のためには、監督付き実行を使用してください。 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
LaunchAgentラベルはai.openclaw.gateway（デフォルト）またはai.openclaw.<profile>（名前付きプロファイル）です。openclaw doctorはサービス設定のドリフトを監査および修復します。

​
1台のホスト上での複数のGateway

ほとんどの構成ではGatewayは1つで十分です。 複数使うのは、厳格な分離/冗長化のためだけにしてください（たとえばレスキュープロファイル）。 インスタンスごとのチェックリスト:
  • 一意の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
参照: Multiple gateways。

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

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
デフォルトでは、分離された状態/設定とベースGatewayポート19001が含まれます。

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

  • 最初のクライアントフレームはconnectでなければなりません。
  • Gatewayはhello-okスナップショット（presence, health, stateVersion, uptimeMs, limits/policy）を返します。
  • hello-ok.features.methods / eventsは保守的な検出リストであり、 呼び出し可能なすべてのヘルパールートの自動生成ダンプではありません。
  • リクエスト: req(method, params) → res(ok/payload|error)。
  • 一般的なイベントにはconnect.challenge、agent、chat、 session.message、session.tool、sessions.changed、presence、tick、 health、heartbeat、pairing/approvalライフサイクルイベント、およびshutdownが含まれます。
agent実行は2段階です。
  1. 即時の受理ack（status:"accepted"）
  2. 最終完了レスポンス（status:"ok"|"error"）。その間にagentイベントがストリームされます。
完全なプロトコルドキュメント: Gateway Protocol。

​
運用チェック

​
ライブネス

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

​
レディネス

openclaw gateway status
openclaw channels status --probe
openclaw health

​
ギャップ回復

イベントは再送されません。シーケンスギャップがある場合は、続行前に状態（health, system-presence）を更新してください。

​
一般的な障害シグネチャ

シグネチャ想定される問題
refusing to bind gateway ... without auth有効なGateway認証パスなしでの非loopbackバインド
another gateway instance is already listening / EADDRINUSEポート競合
Gateway start blocked: set gateway.mode=local設定がremote modeになっている、または破損した設定からlocal-modeスタンプが欠落している
unauthorized during connectクライアントとGatewayの間の認証不一致
完全な診断手順については、Gateway Troubleshootingを使用してください。

​
安全性の保証

  • Gatewayプロトコルクライアントは、Gatewayが利用できない場合に即座に失敗します（暗黙の直接チャネルフォールバックはありません）。
  • 無効な/connectでない最初のフレームは拒否され、接続が閉じられます。
  • 正常なシャットダウンでは、ソケットを閉じる前にshutdownイベントが発行されます。
関連: