Skip to main content
このページでは、ゲートウェイサービスの初期起動から日常的な運用（Day-2 ops）について説明します。

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

具体的な症状から原因を特定するための診断手順と、ログの見分け方。

構成設定

目的別のセットアップガイドと、全設定項目の詳細リファレンス。

シークレット管理

SecretRef の仕様、実行時スナップショットの挙動、および移行・リロード操作。

シークレット適用計画の仕様

secrets apply の対象パスに関するルールと、参照限定の認証プロファイルの挙動。

​
5分で完了するローカル起動手順

1

ゲートウェイの起動

2

サービスの健全性確認

正常な状態の目安: Runtime: running および RPC probe: ok。
3

チャネルの準備状況を確認

ゲートウェイの構成リロード機能は、有効な構成ファイルのパス（プロファイルや状態のデフォルト、または OPENCLAW_CONFIG_PATH から解決されたもの）を監視します。デフォルトの動作モードは gateway.reload.mode="hybrid" です。

​
実行モデル

  • ルーティング、コントロールプレーン、およびチャネル接続を担う単一の常駐プロセスです。
  • 1 つのポートで以下の機能をマルチプレクス（多重化）して提供します:
    • WebSocket による制御と RPC
    • HTTP API (OpenAI 互換、Responses API、ツール実行)
    • コントロール UI および Webhook フック
  • デフォルトの待機（bind）モード: loopback (127.0.0.1)。
  • デフォルトで認証が必要です (gateway.auth.token, gateway.auth.password, または環境変数 OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD)。

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

​
ホットリロード（設定の即時反映）モード

​
管理用コマンドセット

​
リモートアクセス

推奨: Tailscale または VPN。 フォールバック: SSH トンネル。
その後、ローカルのクライアントを ws://127.0.0.1:18789 に接続します。
ゲートウェイの認証が設定されている場合、SSH トンネル経由であってもクライアントは認証情報（トークン/パスワード）を送信する必要があります。
参照: リモートゲートウェイ, 認証, Tailscale

​
サービス管理とライフサイクル

安定した運用のために、各 OS のサービス管理ツールを使用することを推奨します。
LaunchAgent のラベルは ai.openclaw.gateway（既定）または ai.openclaw.<profile> です。openclaw doctor でサービス設定の不一致を監査・修復できます。

​
1台のホストで複数のゲートウェイを動かす

通常は 1つ のゲートウェイで十分です。 厳格な分離が必要な場合や、冗長構成（救旧用プロファイルなど）を組む場合にのみ複数起動してください。 各インスタンスで一意にする必要がある項目:
  • gateway.port
  • OPENCLAW_CONFIG_PATH
  • OPENCLAW_STATE_DIR
  • agents.defaults.workspace
実行例:
参照: マルチゲートウェイ

​
開発用（dev）プロファイルのクイックパス

このモードでは、状態・構成が分離され、ポート番号は 19001 がデフォルトとなります。

​
プロトコル早見表 (オペレーター視点)

  • クライアントからの最初のフレームは connect である必要があります。
  • ゲートウェイは hello-ok スナップショット (presence, health, stateVersion, uptimeMs, 各種制限/ポリシー) を返します。
  • リクエスト: req(method, params) → res(ok/payload|error)。
  • 主なイベント: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown。
エージェントの実行は 2 段階で行われます:
  1. 即時の受理確認 (status: "accepted")。
  2. 最終的な完了応答 (status: "ok" | "error")。この間に、ストリーミングされた agent イベントが配信されます。
詳細はプロトコル説明書を参照してください: ゲートウェイプロトコル

​
運用チェック項目

​
生存確認 (Liveness)

  • WebSocket を開き、connect を送信。
  • スナップショットを含む hello-ok が返ってくることを確認。

​
準備状況 (Readiness)

​
通信欠落からの復旧 (Gap recovery)

イベントの再送は行われません。シーケンス番号に飛び（Gap）が生じた場合は、継続する前に状態情報（health, system-presence）をリフレッシュしてください。

​
よくある失敗パターンのシグネチャ

詳細な診断フローは、ゲートウェイのトラブルシューティング を活用してください。

​
安全性の保証

  • ゲートウェイが利用できない場合、プロトコルクライアントは即座にエラーとなります（暗黙的なチャネル直結へのフォールバックは行われません）。
  • 不正なフレームや connect 以外の初回フレームは拒否され、切断されます。
  • 正常なシャットダウン時には、ソケットを閉じる前に shutdown イベントを発行します。
関連項目: