Gateway Runbook（運用ガイド）

Last updated: 2025-12-09

• 単一の Baileys/Telegram 接続と制御/イベント面を持つ常駐プロセスです。
• 旧 gateway コマンドを置き換えます。CLI エントリポイント：openclaw gateway。
• 停止されるまで動作し、致命的エラーでは非ゼロで終了して supervisor に再起動させます。

openclaw gateway --port 18789

openclaw gateway --port 18789 --verbose

openclaw gateway --force

pnpm gateway:watch

• 設定のホットリロードは ~/.openclaw/openclaw.json（または OPENCLAW_CONFIG_PATH）を監視します。
• デフォルト：gateway.reload.mode="hybrid"（安全な変更はホット適用、重要変更は再起動）。
• 必要に応じて SIGUSR1 でプロセス内再起動します。
• gateway.reload.mode="off" で無効化します。
• WebSocket の制御プレーンを 127.0.0.1:<port>（デフォルト 18789）にバインドします。
• 同じポートで HTTP（control UI、hooks、A2UI）も提供します。単一ポート多重化です。
• OpenAI Chat Completions（HTTP）：/v1/chat/completions。
• OpenResponses（HTTP）：/v1/responses。
• ツール呼び出し（HTTP）：/tools/invoke。
• デフォルトで canvasHost.port（既定 18793）に Canvas ファイルサーバーを起動し、~/.openclaw/workspace/canvas から ~/.openclaw/workspace/canvas を提供します。canvasHost.enabled=false または OPENCLAW_SKIP_CANVAS_HOST=1 で無効化。
• stdout にログ出力します。launchd/systemd で常駐とログローテーションを行ってください。
• トラブルシュート時は --verbose を付け、デバッグログ（ハンドシェイク、リクエスト/解析、イベント）を stdio にミラーします。
• --force は lsof でポートのリスナーを探し、SIGTERM を送り、kill した内容をログしてから Gateway を起動します（lsof が無いと即失敗）。
• supervisor（launchd/systemd/mac アプリの子プロセス）配下では stop/restart が SIGTERM になるのが通常です。旧版では pnpm の ELIFECYCLE 終了コード 143（SIGTERM）として見える場合がありますが、正常終了です。
• SIGUSR1 は認可されている場合にプロセス内再起動をトリガーします（gateway tools/config apply/update、または commands.restart による手動再起動）。
• 既定で Gateway 認証が必要です：gateway.auth.token（または OPENCLAW_GATEWAY_TOKEN）か gateway.auth.password を設定します。Tailscale Serve identity を使わない限り、クライアントは connect.params.auth.token/password を送る必要があります。
• ウィザードは loopback でもデフォルトで token を生成します。
• ポート優先順位：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 既定 18789。

Tailscale/VPN を推奨。そうでなければ SSH トンネル：

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

• クライアントはトンネル経由で ws://127.0.0.1:18789 に接続します。
• token を設定している場合、トンネル経由でも connect.params.auth.token に含める必要があります。

通常は不要です。1 つの Gateway が複数のメッセージングチャネルとエージェントに対応できます。複数 Gateway は冗長化や強い分離（例：rescue bot）目的のみ推奨です。

状態/設定を分離し、ユニークなポートを使えばサポートされます。完全版：Multiple Gateways。

サービス名は profile を認識します：

• macOS：bot.molt.<profile>（旧 com.openclaw.* が残っている場合あり）。
• Linux：openclaw-gateway-<profile>.service
• Windows：OpenClaw Gateway (<profile>)

インストールメタデータはサービス設定に埋め込まれます：

• OPENCLAW_SERVICE_MARKER=openclaw
• OPENCLAW_SERVICE_KIND=gateway
• OPENCLAW_SERVICE_VERSION=<version>

Rescue-bot モード：2 つ目の Gateway を profile・state dir・workspace・ベースポート間隔ごとに分離します。完全版：Rescue bot guide。

メイン環境に触れずに、設定/状態/ワークスペースを完全分離した dev インスタンスを起動できます。

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

openclaw --dev status
openclaw --dev health

デフォルト（env/flags/config で上書き可能）：

• OPENCLAW_STATE_DIR=~/.openclaw-dev
• OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
• OPENCLAW_GATEWAY_PORT=19001（Gateway WS + HTTP）
• ブラウザ制御サービス = 19003（派生：gateway.port+2、loopback のみ）
• canvasHost.port=19005 (derived: gateway.port+4)
• --dev で setup/onboard を実行すると、agents.defaults.workspace は ~/.openclaw/workspace-dev がデフォルトになります。

派生ポート（目安）：

• ベースポート = gateway.port（または OPENCLAW_GATEWAY_PORT / --port）
• ブラウザ制御サービス = base + 2（loopback のみ）
• canvasHost.port = base + 4（または OPENCLAW_CANVAS_HOST_PORT / 設定上書き）
• ブラウザ profile の CDP ポートは browser.controlPort + 9 .. + 108 から自動割当（profile ごとに予約）。

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

• ユニークな gateway.port
• ユニークな OPENCLAW_CONFIG_PATH
• ユニークな OPENCLAW_STATE_DIR
• ユニークな agents.defaults.workspace
• WhatsApp 番号は別途（WA 使用時）

profile ごとのサービスインストール：

openclaw --profile main gateway install
openclaw --profile rescue gateway install

Example:

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 protocol と Bridge protocol（レガシー）。

• クライアント必須の初回フレーム：<code>req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }'</code>。
• Gateway は <code>res {type:"res", id, ok:true, payload:hello-ok }'</code> を返します（または <code>ok:false</code> + error の後に close）。
• ハンドシェイク後：
• リクエスト：<code>'{type:"req", id, method, params}'</code> → <code>'{type:"res", id, ok, payload|error}'</code>
• イベント：<code>'{type:"event", event, payload, seq?, stateVersion?}'</code>
• 構造化 presence：<code>'{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }'</code>（WS クライアントでは <code>instanceId</code> は <code>connect.client.instanceId</code> 由来）。
• <code>agent</code> 応答は 2 段階です。まず <code>res</code> ack <code>'{runId,status:"accepted"}'</code>、終了時に最終 <code>res</code> <code>'{runId,status:"ok"|"error",summary}'</code>。ストリームは <code>event:"agent"</code> で届きます。

• health — フルのヘルススナップショット（openclaw health --json と同形）。
• status — 短い要約。
• system-presence — 現在の presence リスト。
• system-event — 状態/システム注記を publish（構造化）。
• send — アクティブなチャネル経由で送信。
• agent — エージェントターンを実行（同一接続でイベントをストリーム）。
• node.list — ペア済み + 接続中ノード一覧（caps、deviceFamily、modelIdentifier、paired、connected、広告された commands を含む）。
• node.describe — ノードを説明（能力 + 対応 node.invoke；ペア済み/未ペア接続中どちらも可）。
• node.invoke — ノード上でコマンド実行（例：canvas.*、camera.*）。
• node.pair.* — ペアリングライフサイクル（request、list、approve、reject、verify）。

Presence も参照（重複排除と、安定した client.instanceId が重要な理由）。

• agent — エージェント実行のツール/出力のストリームイベント（seq 付き）。
• presence — presence 更新（stateVersion の差分）を全クライアントへ push。
• tick — periodic keepalive/no-op to confirm liveness.
• shutdown — Gateway が終了中。payload に reason と任意の restartExpectedMs。クライアントは再接続します。

• WebChat はネイティブ SwiftUI UI で、Gateway WebSocket と直接やり取りして履歴/送信/中止/イベントを扱います。
• リモート利用は同じ SSH/Tailscale トンネルで可能。token がある場合は connect 時に含めます。
• macOS アプリは単一の共有 WS で接続し、初期スナップショットの presence と presence イベントで UI を更新します。

• サーバーは AJV で、プロトコル定義から出力される JSON Schema により入ってくるフレームを検証します。
• クライアント（TS/Swift）は生成型を使用します（TS 直、Swift はリポジトリ生成器）。
• プロトコル定義が唯一の真実です。再生成コマンド：
• pnpm protocol:gen
• pnpm protocol:gen:swift

• <code>hello-ok</code> には <code>snapshot</code> と <code>presence</code>、<code>health</code>、<code>stateVersion</code>、<code>uptimeMs</code>、<code>policy {maxPayload,maxBufferedBytes,tickIntervalMs}'</code> が含まれ、追加リクエストなしで即描画できます。
• health/system-presence は手動更新に使えますが、接続時には不要です。

エラーは <code>'{ code, message, details?, retryable?, retryAfterMs? }'</code> を使います。

標準コード：

• NOT_LINKED — WhatsApp が未認証。
• AGENT_TIMEOUT — エージェントが期限内に応答しませんでした。
• INVALID_REQUEST — schema/パラメータ検証に失敗。
• UNAVAILABLE — Gateway がシャットダウン中、または依存が利用不可。

• 定期的に tick（または WS ping/pong）を送って、トラフィックがなくても生存を伝えます。
• send/agent の ack は別のレスポンスです。tick に詰め込まないでください。

イベントはリプレイされません。seq のギャップを検出したら、継続前に（health + system-presence）で refresh します。WebChat と macOS はギャップ時に自動 refresh します。

launchd で常駐させます：

• Program：openclaw のパス
• Args：gateway
• KeepAlive：true
• StandardOut/Err：ファイルパスまたは syslog
• 失敗時は launchd が再起動。致命的な設定ミスは exit して運用者に気付かせます。
• LaunchAgents はユーザー単位でログインセッションが必要です。ヘッドレスはカスタム LaunchDaemon（同梱なし）。
• openclaw gateway install は ~/Library/LaunchAgents/bot.molt.gateway.plist（または bot.molt.<profile>.plist）を書きます（旧 com.openclaw.* は整理済み）。
• openclaw doctor が LaunchAgent を監査し、推奨デフォルトへ更新できます。

Gateway CLI で install/start/stop/restart/status：

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

Notes:

• gateway status はサービスの解決済み port/config で RPC probe（--url で上書き）。
• gateway status --deep はシステムレベルスキャンを追加（LaunchDaemons/system units）。
• gateway status --no-probe は RPC probe をスキップ（ネットワーク断に有用）。
• gateway status --json はスクリプト向けに安定。
• gateway status は supervisor の稼働（launchd/systemd）と RPC 到達性（WS connect + status RPC）を分けて報告します。
• <code>gateway status</code> は config path と probe 対象を表示し、“localhost vs LAN bind”や profile 不一致の混乱を避けます。
• サービスが動いているように見えてもポートが閉じている場合、最後の <code>gateway status</code> エラー行を含めます。
• logs は RPC 経由で Gateway のファイルログを follow（手動 tail/grep 不要）。
• 他の gateway 風サービスを検出すると、OpenClaw の profile サービスでない限り警告します。
• 多くの構成では 1台につき1 Gateway を推奨。冗長化や rescue bot には profile/port を分離。Multiple Gateways を参照。
• クリーンアップ：openclaw gateway uninstall（現行）と openclaw doctor（旧移行）。
• gateway install は通常は no-op。profile/env/path が変わったら openclaw gateway install --force で再インストール。

同梱 Mac アプリ：

• OpenClaw.app は node ベースの Gateway relay を同梱し、per-user LaunchAgent（bot.molt.gateway または bot.molt.<profile>）をインストールできます（旧 com.openclaw.* もアンインストール可能）。
• 完全停止：openclaw gateway stop（または launchctl bootout gui/$UID/bot.molt.gateway）。
• 再起動：openclaw gateway restart（または launchctl kickstart -k gui/$UID/bot.molt.gateway）。
• launchctl は LaunchAgent が入っている場合のみ有効。未インストールなら先に openclaw gateway install。
• 名前付き profile ではラベルを bot.molt.<profile> に置き換えます。

Linux/WSL2 ではデフォルトで systemd user service をインストールします。単一ユーザー機では user service（環境が簡単、ユーザー別設定）を推奨。多ユーザー/常時稼働サーバーは system service（linger 不要、共有監督）を推奨。

openclaw gateway install が user unit を書きます。openclaw doctor は unit を監査し、推奨デフォルトへ更新できます。

~/.config/systemd/user/openclaw-gateway[-<profile>].service を作成：

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=OPENCLAW_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target

linger を有効化（ログアウト/アイドルでも user service を生かすために必要）：

sudo loginctl enable-linger youruser

Onboarding は Linux/WSL2 でこれを実行します（sudo を求める場合あり。/var/lib/systemd/linger に書き込み）。

その後サービスを有効化：

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

代替（system service）：常時稼働/多ユーザーサーバーでは systemd の system unit をインストール（linger 不要）。

/etc/systemd/system/openclaw-gateway[-<profile>].service を作成（上の unit をコピーし、WantedBy=multi-user.target に変更、User= + WorkingDirectory= を設定）してから：

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

Windows では WSL2 を使い、上の Linux systemd セクションに従ってください。

• Liveness：WS を開いて req:connect → payload.type="hello-ok"（snapshot 付き）の res を期待。
• Readiness：health → ok: true と linkChannel にリンク済みチャネル（該当時）を期待。
• Debug：tick/presence を購読し、status の link/auth age と、presence の Gateway host / 接続クライアントを確認。

• デフォルトではホストあたり 1 Gateway を前提。複数 profile を動かす場合は port/state を分離し、正しいインスタンスを指定。
• 直接 Baileys 接続へのフォールバックはありません。Gateway が落ちていれば送信はすぐ失敗します。
• 未接続の初回フレームや不正 JSON を拒否してソケットを閉じます。
• Graceful shutdown：close 前に shutdown を送出。クライアントは close + reconnect を処理します。

• openclaw gateway health|status — Gateway WS 経由で health/status を取得。
• openclaw message send --target <num> --message "hi" [--media ...] — Gateway 経由で送信（WhatsApp は冪等）。
• openclaw agent --message "hi" --to <num> — エージェントターン実行（既定で最終まで待機）。
• openclaw gateway call <method> --params {"k":"v"} — デバッグ用の生メソッド呼び出し。
• openclaw gateway stop|restart — 監督下の Gateway サービスを stop/restart（launchd/systemd）。
• Gateway ヘルパーは --url 上で稼働している前提で、自動起動はしません。

• 旧 openclaw gateway と旧 TCP control port の利用をやめます。
• 必須 connect と構造化 presence を持つ WS プロトコルへクライアントを更新します。