Gateway 運用手順書

このページは、Gatewayサービスの1日目の起動と2日目以降の運用に使用します。

5分のローカル起動

OmeniaClaw gateway --port 18789# debug/trace mirrored to stdioOmeniaClaw gateway --port 18789 --verbose# force-kill listener on selected port, then startOmeniaClaw gateway --force

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --follow

OmeniaClaw channels status --probe

ランタイムモデル

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

OpenAI互換エンドポイント

OmeniaClawの最も効果の高い互換サーフェスは現在、次のとおりです。

• 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はエージェント優先です。OmeniaClaw、OmeniaClaw/default、OmeniaClaw/<agentId>を返します。
• OmeniaClaw/defaultは、常に設定済みのデフォルトエージェントにマップされる安定したエイリアスです。
• バックエンドプロバイダー/モデルを上書きしたい場合はx-OmeniaClaw-modelを使用します。それ以外の場合は、選択されたエージェントの通常のモデルと埋め込み設定が制御を維持します。

これらはすべてメインのGatewayポートで実行され、Gateway HTTP APIの他の部分と同じ信頼されたオペレーター認証境界を使用します。

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

インストール済みGatewayサービスは、解決済みの--portをスーパーバイザーメタデータに記録します。gateway.portを変更した後は、launchd/systemd/schtasksが新しいポートでプロセスを起動するように、OmeniaClaw doctor --fixまたはOmeniaClaw gateway install --forceを実行します。

Gateway起動では、非loopbackバインド用のローカル コントロールUIオリジンをシードするときに、同じ有効ポートとバインドを使用します。たとえば、--bind lan --port 3000はランタイム 検証の実行前にhttp://localhost:3000とhttp://127.0.0.1:3000をシードします。HTTPSプロキシURLなどのリモートブラウザーオリジンは、 gateway.controlUi.allowedOriginsに明示的に追加してください。

ホットリロードモード

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

OmeniaClaw gateway statusOmeniaClaw gateway status --deep   # adds a system-level service scanOmeniaClaw gateway status --jsonOmeniaClaw gateway installOmeniaClaw gateway restartOmeniaClaw gateway stopOmeniaClaw secrets reloadOmeniaClaw logs --followOmeniaClaw doctor

gateway status --deepは追加のサービス検出（LaunchDaemons/systemdシステム ユニット/schtasks）のためのものであり、より深いRPC健全性プローブではありません。

複数のGateway（同一ホスト）

ほとんどのインストールでは、1台のマシンにつき1つのGatewayを実行するべきです。単一のGatewayで複数の エージェントとチャネルをホストできます。

意図的に分離やレスキューボットが必要な場合にのみ、複数のGatewayが必要です。

有用な確認:

OmeniaClaw gateway status --deepOmeniaClaw gateway probe

想定される内容:

• gateway status --deepは、古いlaunchd/systemd/schtasksインストールがまだ残っている場合に Other gateway-like services detected (best effort)を報告し、クリーンアップのヒントを出力できます。
• 複数のターゲットが応答する場合、gateway probeはmultiple reachable gatewaysについて警告できます。
• それが意図したものである場合は、Gatewayごとにポート、設定/状態、ワークスペースルートを分離してください。

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

• 一意のgateway.port
• 一意のOmeniaClaw_CONFIG_PATH
• 一意のOmeniaClaw_STATE_DIR
• 一意のagents.defaults.workspace

例:

OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/a.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-a OmeniaClaw gateway --port 19001OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/b.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-b OmeniaClaw gateway --port 19002

詳細なセットアップ: /gateway/multiple-gateways。

リモートアクセス

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

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

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

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

監視とサービスライフサイクル

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

OmeniaClaw gateway installOmeniaClaw gateway statusOmeniaClaw gateway restartOmeniaClaw gateway stop

OmeniaClaw gateway installsystemctl --user enable --now OmeniaClaw-gateway[-<profile>].serviceOmeniaClaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OmeniaClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/OmeniaClaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

OmeniaClaw gateway installOmeniaClaw gateway status --jsonOmeniaClaw gateway restartOmeniaClaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now OmeniaClaw-gateway[-<profile>].service

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

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --dev status

デフォルトには、分離された状態/設定とベースGatewayポート19001が含まれます。

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

• 最初のクライアントフレームはconnectである必要があります。
• Gatewayはhello-okスナップショット（presence、health、stateVersion、uptimeMs、制限/ポリシー）を返します。
• 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、ペアリング/承認ライフサイクルイベント、shutdownが含まれます。

エージェント実行は2段階です。

1. 即時の受理確認（status:"accepted"）
2. 最終完了レスポンス（status:"ok"|"error"）。その間にagentイベントがストリーミングされます。

完全なプロトコルドキュメントを参照: Gatewayプロトコル。

運用チェック

Liveness

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

Readiness

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

ギャップ復旧

イベントは再生されません。シーケンスギャップが発生した場合は、続行する前に状態（health、system-presence）を更新します。

一般的な失敗シグネチャ

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

安全性の保証

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

関連:

• トラブルシューティング
• バックグラウンドプロセス
• 設定
• 健全性
• Doctor
• 認証

関連

• 設定
• Gateway のトラブルシューティング
• リモートアクセス
• シークレット管理