2026 Linux クラウド VPS マルチエージェント：LangGraph オーケストレーション vs OpenClaw Gateway 実行層・systemd 常駐と段階的トラブルシュート FAQ

先週、ある開発チームが マルチエージェント・パイプライン構成の記事 を参考に、Supervisor + Worker 構成を Linux VPS へそのまま移植しました。平日中は順調で、Slack 連携も問題なく見えました。ところが週末の再起動後、承認待ちタスクは復元されず、古い checkpoint を基準に Worker が二重実行され、チャンネル通知だけが生き残るという典型的な事故が発生しました。原因はモデル性能ではなく、LangGraph と OpenClaw Gateway を同じ一時セッションで運用したことです。

本番運用で重要なのは、「エージェントを増やすこと」ではなく責務を分けることです。LangGraph は状態遷移、ノード分岐、checkpoint、interrupt の再開を担当し、OpenClaw Gateway はチャネル入口、Cron、運用可観測性、実行境界を担当します。本稿は理論紹介ではなく、Linux VPS で再現可能な実装手順に絞っています。Gateway 常駐とログ運用は OpenClaw Linux 常駐 FAQ、コスト管理は AI エージェント費用の記事 と併読すると全体像がつかみやすくなります。

なぜ VPS で「編成」と「実行」を分離するべきか

ローカル検証では Planner -> Coder -> Reviewer を 1 プロセスで回しても動きます。しかし Linux VPS を実サービスで使うと、次の4点で破綻しやすくなります。

• 入口が多様：Slack コマンド、Webhook、DM、定期実行など、流入経路ごとの制御が必要になります。
• 待機時間が長い：人の承認を数時間待つケースでは、再起動後も checkpoint が必ず復元できることが前提です。
• 権限分離が必須：外部入力を受ける Gateway が本番書き込み権限を持つ設計は、監査上も運用上も危険です。
• 障害領域を分けたい：TLS や 403 は Gateway 側、ノード循環や状態競合は LangGraph 側。混在ログでは復旧時間が伸びます。

そこで推奨する基本形は、LangGraph を内部ポートで常駐し、OpenClaw Gateway を別ユニットで入口制御に集中させる構成です。Gateway はイベントを整理して thread_id 単位で graph run を起動し、LangGraph は状態と遷移に専念します。CI における scheduler と runner の分担に近く、責任の所在が明確になります。

トポロジー選定マトリクス：VPS の代表3パターン

Linux VPS で多い構成は次の3つです。選定軸は「チャネル常時接続」「interrupt 永続化」「重い処理の配置先」です。

A は最短で立ち上がりますが、checkpoint を永続化しないと再起動で簡単に破綻します。B は重い Worker を cloud Mac に逃がせるため、VPS 側の安定性が高くなります。C は要件が単純なうちは合理的です。重要なのは「図を使うべき場所」と「入口で完結させるべき場所」を混同しないことです。

LangGraph のマルチエージェント設計は 公式 multi-agent 概念ページ、Gateway 側の設計要件は OpenClaw Gateway 設定ガイド を参照してください。

最小再現トポロジー（形態A）

初回導入で再現性が高かった最小手順です。TLS と基本反向プロキシ設定が済んでいる前提です。

1. LangGraph API：FastAPI で薄くラップし、127.0.0.1:8123 で待受。checkpoint は永続ボリュームへ保存。
2. OpenClaw Gateway：OpenClaw CLI ドキュメント に従い導入し、公開面はプロキシで制御。
3. 橋渡しルール：チャネルイベントを Gateway で正規化し、意図を固定 enum 化したうえで graph run を起動。
4. systemd 分離：langgraph-api.service と openclaw.service を別ユニットで管理し、失敗時の再起動条件を個別設定。

# /etc/systemd/system/langgraph-api.service
                [Unit]
                Description=LangGraph multi-agent API
                After=network-online.target

                [Service]
                User=deploy
                WorkingDirectory=/opt/langgraph-app
                Environment=CHECKPOINT_DIR=/var/lib/langgraph-checkpoints
                ExecStart=/opt/langgraph-app/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8123
                Restart=on-failure
                RestartSec=5

                [Install]
                WantedBy=multi-user.target

有効化後は ss -lntp で公開ポートを確認し、443 以外の不要公開を潰してください。入口は Gateway だけに寄せ、オーケストレーション API は内部通信に限定するのが基本です。この一点を守るだけで、障害切り分けとセキュリティ監査の負担が大幅に減ります。

引き渡し契約：Gateway から graph へ何を渡すか

分離構成で壊れやすいのはデータ契約です。JSON schema を固定し、バージョン管理してください。

• thread_id：チャネルスレッドと graph 状態を一対一で対応させる安定キー。
• intent：new_task / approve / cancel / status のように明示的列挙。
• payload：repo URL、対象パス、追加指示など構造化情報。大容量は外部参照に分離。
• caller_scope：チャネルIDとユーザー範囲。Gateway で通しても graph 側で再検証する。

LangGraph の memory / checkpoint モデル は長寿命ワークフローに適しています。Gateway が別セッション状態を持ち始めると、二重状態機による不整合が起こりやすく、運用者が「どちらを正」とみなすか判断できなくなります。

L0-L3 階層トラブルシュート

「ボットが反応しない」と言われたときは、慌てて設定変更せず、層ごとに証拠を積みます。

L0：systemd とポート

systemctl status openclaw langgraph-api を確認し、両サービスの稼働状態を先に確定します。片方だけ落ちている場合、見える症状は別層に出ることがあります。

L1：OpenClaw チャネルと橋渡しログ

openclaw logs でイベント受信、署名検証、転送先 URL を検証します。403、TLS、Webhook 再試行はこの層で対処します。

L2：LangGraph trace と checkpoint

同一 thread_id でどのノードで停止したか確認します。checkpoint 権限やマウント不備があると毎回新規会話のように振る舞います。

L3：外部 Worker と MCP

形態Bでは重処理が外部 host 側なので、NO_PROXY、資格情報期限、ネットワーク到達性を確認します。Gateway 再インストールで直る問題は多くありません。

本番前チェックリスト（30分）

• LangGraph は内部待受のみ。公開入口は Gateway に一本化。
• checkpoint は永続ストレージとバックアップ対象に含める。
• Gateway -> graph タイムアウトをチャネル再試行窓より短く設定。
• ノード別ツール権限を明示し、Reviewer に書き込み権限を渡さない。
• 再起動テストで interrupt 復帰と Cron 非重複実行を確認。
• trace id を入口から Worker ログまで通して追跡可能にする。

FAQ