【最新版】OpenClawのGatewayアーキテクチャとは？初心者向けにやさしく解説

Gatewayアーキテクチャって何？

OpenClawは「AIに仕事を任せる」だけでなく、DiscordやSlackなど複数の場所から指示が来たり、端末（Mac/スマホ/サーバー）側で処理したりします。 その交通整理をしているのがGateway（ゲートウェイ）です。

ここはこういう意味: Gatewayは「アプリの中にある設定画面」ではなく、ずっと動き続ける司令塔（デーモン）です。 だから「Gatewayが落ちる＝全部の入口が止まる」になります。

イメージ: Gatewayは空港の管制塔。Client（アプリ/CLI）は管制官に「次これやって」と依頼し、Node（端末機能）は現場作業員として「カメラ撮影/画面録画/位置情報取得」などを実行します。

登場人物（Gateway / Client / Node / WebChat）

1) Gateway（常駐プロセス）

• Discord/Slack/Telegram/WhatsAppなどの接続を保持します。
• 操作用のAPI（WebSocket）を提供し、イベント（agent/chat/health/cronなど）を配信します。
• 受け取ったデータをスキーマで検証して、安全に処理します。

2) Client（操作する側：macアプリ/CLI/Web管理）

ClientはGatewayにWebSocketでつながり、「状態を見たい」「メッセージ送りたい」「エージェントを実行したい」などのリクエストを送ります。

3) Node（実行する側：端末機能）

Nodeは同じWebSocketサーバーにつながりますが、役割（role）がnodeとして宣言されます。 そして「この端末は何ができるか（例：カメラ、画面録画、位置情報）」をCapabilitiesとして出します。

4) WebChat（ブラウザUI）

WebChatは、GatewayのAPIを使ってチャット履歴の表示や送信をする軽量なWeb UIです。 リモート運用では、SSHトンネルやVPN（例：Tailscale）でGatewayへ到達させます。

接続の流れ（最初にconnectが必須）

Gatewayとの通信はWebSocketで行い、最初の1発目は必ずconnectで始まります。 これは「こんにちは、私はこの端末です」という自己紹介＋認証の握手です。

• connect → ok: 接続が確立し、健康状態（health）や存在状態（presence）などのスナップショットが返ります。
• その後: Clientは「agent実行」などのリクエストを送り、Gatewayは途中経過をイベントとしてストリーミングします。

ここはこういう意味: connectを省略していきなり命令を送ると、Gatewayは「ルール違反」として切断します。最初の握手で安全性を担保しているからです。

通信プロトコルの考え方（超ざっくり）

GatewayのWebSocketは、主に「リクエスト（req）/レスポンス（res）/イベント（event）」の3種類で動きます。

• req: 依頼（例：send, agent, status）
• res: 返事（成功/失敗、結果）
• event: サーバーからの通知（例：tick, presence, agentの進捗）

さらに、送信やエージェント実行など「やり直しが起きやすい操作」にはidempotency key（重複防止キー）が使われます。イメージ: 「同じ注文を2回送っちゃった」事故を防ぐ、注文番号みたいなものです。

ペアリング（許可）とローカル信頼

OpenClawは「どの端末が接続しているか」を重要視します。初めて見る端末IDは、ペアリング承認が必要です。

• 承認されると、次回以降はデバイストークンでスムーズに接続できるようになります。
• ローカル接続（例：同じマシンの127.0.0.1）では、UXのために自動承認が効く場合があります。
• それでも、Gateway自体の認証（トークン設定など）はローカル/リモート問わず適用されます。

ここはこういう意味: 「家の中だから鍵いらない」ではなく、家の中でも玄関の鍵はかける、みたいな発想です。

リモートから使うには？（VPN推奨、SSHトンネルも可）

基本はVPN（例：Tailscale）などで安全なネットワークを作るのが推奨です。 ただ「とりあえず試したい」ならSSHトンネルでGatewayのポートを手元に転送する方法もあります。

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

イメージ: 手元PCの localhost:18789 を、遠隔のGatewayへ「秘密の通路」でつないでいる感じです。

運用の最小セット（まずここだけ覚える）

• 起動: openclaw gateway（フォアグラウンドで起動し、ログが見える）
• 状態確認: クライアントからhealth/statusを取得（接続直後のスナップショットでも見える）
• 常駐化: macOSならlaunchd、Linuxならsystemdで自動再起動させる

覚えておくと事故が減る「不変条件（Invariants）」

• 1台のホストに対して、基本はGatewayは1つ（特にWhatsAppセッションは重複させない）
• 最初のフレームはconnect。守らない接続は切断される
• イベントは巻き戻し（リプレイ）されないので、取りこぼしたらクライアント側で再取得が必要

まとめ

Gatewayアーキテクチャを一言で言うと、OpenClawを「チャット・アプリ・端末機能」へ広げるための中心ハブ設計です。 まずはGatewayを安定稼働させ、次にClientで操作し、必要に応じてNodeで端末機能を足す——この順番で考えると混乱しません。

参考

• https://docs.openclaw.ai/concepts/architecture.md