前のページ
Openclaw-Series

04. OpenClaw Gateway コアコンセプト解説

OpenClaw Gateway のコアアーキテクチャを深く理解します。本記事では Session セッションモデル、Message Router メッセージルーティング、Tool Registry ツール登録、Skills スキルシステム、WebSocket プロトコルなどの重要コンセプトを詳しく解説し、開発者が高度な設定とトラブルシューティング能力を習得できるようサポートします。

OpenClaw v2026.2 対応 | 基礎設定を完了し、アーキテクチャを深く理解したいユーザー向け。まず前 3 回のチュートリアルを完了することを推奨します。

TL;DR: Gateway は OpenClaw のコア制御プレーンです。Session は会話コンテキストのコンテナ（main/channel/group）、Message Router がメッセージルーティングを決定、Tool Registry がツール権限を管理、Skills は事前パッケージされた機能拡張です。WebSocket エンドポイント ws://127.0.0.1:18789/ws、よく使うコマンド openclaw gateway/doctor/config。これらのコンセプトを理解することが高度な設定の基礎です。

アーキテクチャ概要

全体アーキテクチャ

flowchart TB
    subgraph Clients["クライアント層"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Gateway 層"]
        WS[WebSocket Server]
        HTTP[HTTP Server]
        MR[Message Router]
        SM[Session Manager]
        TR[Tool Registry]
        EM[Event Manager]
        CFG[Config Store]
    end
    
    subgraph Agent["Agent 層"]
        PI[Pi Agent]
        PROMPT[Prompt Engine]
        TOOLS[Tool Executor]
        SKILLS[Skills Manager]
    end
    
    subgraph External["外部サービス"]
        FS[ファイルシステム]
        BR[ブラウザ]
        API[API サービス]
        DB[データベース]
        CAL[Cron スケジューラ]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

コンポーネントの役割

コンポーネント 役割 主要機能
WebSocket Server クライアント接続管理 接続維持、ハートビート、メッセージ送受信
HTTP Server REST API と静的リソース Web UI、ヘルスチェック、設定インターフェース
Message Router メッセージルーティング配信 チャネル識別、セッションマッピング、メッセージ転送
Session Manager セッションライフサイクル管理 作成、復元、圧縮、クリーンアップ
Tool Registry ツール登録と呼び出し ツール発見、権限制御、実行サンドボックス
Event Manager イベント配信と購読 Webhook、Cron、内部イベント
Config Store 設定の永続化 ホットアップデート、バージョン管理、バックアップ復元

データフロー

sequenceDiagram
    participant U as ユーザー
    participant C as Channel
    participant WS as WebSocket
    participant MR as Router
    participant SM as Session
    participant A as Agent
    participant T as Tools
    
    U->>C: メッセージ送信
    C->>WS: メッセージをプッシュ
    WS->>MR: ルーティングリクエスト
    MR->>SM: セッションを検索/作成
    SM-->>MR: セッションを返す
    MR->>A: メッセージを配信
    A->>A: メッセージを処理
    A->>T: ツールを呼び出し（オプション）
    T-->>A: 結果を返す
    A-->>MR: 応答を生成
    MR->>WS: 応答を送信
    WS->>C: 応答をプッシュ
    C-->>U: メッセージを表示

Session セッションモデル

Session とは？

Session は OpenClaw の最も重要なコンセプトの一つです。各 Session は独立した会話コンテキストを表し、以下を含みます：

構成要素 説明
メッセージ履歴 完全な会話記録
コンテキスト状態 現在のタスク、一時変数
設定 モデル、思考レベル、サンドボックス設定
メタデータ 作成日時、Token 統計、関連チャネル

Session タイプ

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}
タイプ Session ID 形式 説明
main main デフォルトのメインセッション、CLI と WebChat で使用
channel {channel}:user:{senderId} プライベートセッション、チャネルとユーザーで分離
group {channel}:group:{groupId} グループセッション、グループで分離

Session ライフサイクル

stateDiagram-v2
    [*] --> Created: メッセージ到着
    Created --> Active: 初回応答
    Active --> Active: メッセージやり取り
    Active --> Idle: 無活動
    Idle --> Active: 新規メッセージ
    Idle --> Compacted: 自動圧縮
    Compacted --> Active: 会話継続
    Active --> Reset: /reset コマンド
    Reset --> Created: 再開
    Active --> Pruned: セッションクリーンアップ
    Idle --> Pruned: タイムアウトクリーンアップ
    Pruned --> [*]

Session コマンド

チャットで以下のコマンドを送信してセッションを管理：

コマンド 機能 例
/status セッション状態を表示 モデル、Token、コストを表示
/new または /reset セッションをリセット 履歴をクリア、新規会話開始
/compact コンテキストを圧縮 履歴を要約、Token を解放
/think <level> 思考レベルを設定 /think high
/verbose on/off 詳細モードのオン/オフ ツール呼び出しの表示/非表示
/usage off/tokens/full 使用量表示 /usage full

Session 設定

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}
設定項目 説明 デフォルト
maxAge セッション最大生存時間（ミリ秒） 24 時間
maxSize 最大メッセージ数 100 件
threshold 圧縮閾値（Token） 50000
targetRatio 圧縮目標比率 30%

Message Router メッセージルーティング

ルーティングルール

Message Router は受信したメッセージを正しい Session にルーティングします：

flowchart TB
    MSG[メッセージ到着] --> CH{チャネルタイプ?}
    CH -->|プライベート| DM[送信者 ID を抽出]
    CH -->|グループ| GRP[グループ ID を抽出]
    CH -->|WebChat/CLI| MAIN[main セッションを使用]
    
    DM --> SID[Session: channel:user:id]
    GRP --> GID[Session: channel:group:id]
    
    SID --> EXISTS{セッション存在?}
    GID --> EXISTS
    
    EXISTS -->|はい| LOAD[セッションをロード]
    EXISTS -->|いいえ| CREATE[新規セッション作成]
    
    CREATE --> LOAD
    LOAD --> AGENT[Agent に配信]

ルーティング設定

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

グループアクティベーション戦略

モード 説明 適用シーン
mention @メンションが必要 活発なグループ、干渉を減らす
always 全メッセージに応答 専用作業グループ
keyword キーワード含む時に応答 特定トピックのグループ 
{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Tool Registry ツール登録

組み込みツール

OpenClaw には豊富なツールが組み込まれています：

ツールカテゴリ ツール名 機能
ファイル操作 read ファイルを読み込む
write ファイルに書き込む
edit ファイルを編集
コマンド実行 bash Shell コマンドを実行
process プロセスを管理
ブラウザ browser ブラウザを制御
検索 web_search ウェブ検索
ノード camera カメラ操作
screen_record 画面録画
notify 通知を送信
セッション sessions_list セッション一覧
sessions_history セッション履歴
sessions_send クロスセッションメッセージ
キャンバス canvas キャンバス操作

ツール権限制御

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}
サンドボックスモード 説明
off 全ツール利用可能（main セッションのみ）
non-main main 以外のセッションでサンドボックス有効
always 全セッションでサンドボックス有効

サンドボックス設定詳細

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

Skills スキルシステム

Skills アーキテクチャ

flowchart LR
    subgraph Skills["Skills ディレクトリ"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Skills Manager"]
        DISC[発見]
        LOAD[ロード]
        EXEC[実行]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Prompt 注入]
        TOOLS[Tools 登録]
        RES[結果を返す]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Skills ディレクトリ構造

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # スキル定義
│   ├── package.json      # 依存関係（オプション）
│   └── src/
│       └── index.js      # 実装（オプション）
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

SKILL.md の構造

# Gmail Skill

## Description
OpenClaw を通じて Gmail メッセージの送受信

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
ユーザーがメールを送りたい場合：
1. 宛先、件名、本文を確認
2. gmail_send ツールを使用
3. 送信完了を確認

ユーザーがメールを確認したい場合：
1. gmail_list ツールを使用
2. 結果を要約

## Tools
- gmail_list: 最近のメール一覧
- gmail_send: メールを送信
- gmail_read: 特定のメールを読む

## Examples
User: "Check my email"
Action: gmail_list ツールを使用

User: "Send an email to [email protected]"
Action: 件名と本文を確認し、gmail_send を使用

Skills のインストール方法

# ClawHub からインストール
openclaw skill install gmail

# GitHub からインストール
openclaw skill install github:user/repo/skill-name

# 手動インストール
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Skills 設定

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}
設定項目 説明
bundled 組み込みスキルを有効化
managed ClawHub 管理スキルを有効化
workspace ローカルワークスペーススキルを有効化
installGating インストール前に確認が必要

WebSocket プロトコル

接続エンドポイント

ws://127.0.0.1:18789/ws

メッセージ形式

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // メッセージ内容
  }
}

クライアントメッセージタイプ

タイプ 説明 例
agent.send メッセージ送信 Agent と対話
session.list セッション一覧 セッション管理
session.get セッション詳細取得 セッション確認
session.patch セッション設定変更 モデル変更
config.get 設定取得 設定読み取り
config.set 設定更新 設定変更

サーバーメッセージタイプ

タイプ 説明
agent.response Agent 応答
agent.thinking 思考過程（ストリーミング）
tool.invoked ツール呼び出し
tool.result ツール結果
session.created セッション作成
session.reset セッションリセット
error エラー情報

例：メッセージ送信

// WebSocket に接続
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// メッセージ送信
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'こんにちは、自己紹介してください'
  }
}));

// 応答を受信
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // 出力例：
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: 'こんにちは！私はあなたの OpenClaw アシスタントです...',
  //     session: 'main'
  //   }
  // }
};

Event System イベントシステム

組み込みイベント

イベント トリガー時機
message.received ユーザーメッセージ受信
message.sent 返信メッセージ送信
session.created 新規セッション作成
session.reset セッションリセット
tool.invoked ツール呼び出し
tool.completed ツール実行完了
agent.thinking Agent 思考中
error.occurred エラー発生

Webhook 設定

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Webhook ペイロード

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "こんにちは",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Cron スケジュールタスク

設定例

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "今日のスケジュールを教えてください",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "今週の仕事のまとめを生成",
      "enabled": true
    }
  ]
}

Cron 式

┌───────────── 分 (0 - 59)
│ ┌───────────── 時 (0 - 23)
│ │ ┌───────────── 日 (1 - 31)
│ │ │ ┌───────────── 月 (1 - 12)
│ │ │ │ ┌───────────── 曜日 (0 - 6, 0 = 日曜)
│ │ │ │ │
* * * * *

よく使う例

式 説明
0 9 * * * 毎日 9:00
0 18 * * 1-5 平日 18:00
*/30 * * * * 30 分ごと
0 0 1 * * 毎月 1 日 0:00

設定階層と優先順位

優先順位

CLI パラメータ > 環境変数 > 設定ファイル > デフォルト値

設定ソース

ソース 場所 優先度
CLI パラメータ コマンドライン引数 最高
環境変数 OPENCLAW_* 高
設定ファイル ~/.openclaw/openclaw.json 中
デフォルト値 コード内蔵 最低

設定マージ例

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# 環境変数で上書き
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# CLI パラメータで上書き（最高優先度）
openclaw gateway --model "anthropic/claude-opus-4"

設定のホットアップデート

# 設定を更新（再起動不要）
openclaw config set agent.model "anthropic/claude-sonnet-4"

# 設定ファイルを再読み込み
openclaw config reload

# 設定を検証
openclaw config get agent.model

よく使うコマンド早見表

Gateway 管理

# Gateway を起動
openclaw gateway

# ポート指定
openclaw gateway --port 18790

# バックグラウンド実行
openclaw gateway --daemon

# 詳細ログ
openclaw gateway --verbose

# ヘルスチェック
openclaw health

セッション管理

# 全セッションを一覧
openclaw session list

# セッション詳細を表示
openclaw session show main
openclaw session show telegram:user:123456789

# セッションをリセット
openclaw session reset main

# セッションを削除
openclaw session delete telegram:user:123456789

設定管理

# 設定を表示
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# 設定を更新
openclaw config set agent.thinkingLevel high

# 全設定を一覧
openclaw config list

# 設定を検証
openclaw config validate

診断ツール

# 完全診断
openclaw doctor

# 特定項目をチェック
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# ログを表示
openclaw logs
openclaw logs --follow
openclaw logs --level error

トラブルシューティング

Gateway が起動しない

# ポート使用を確認
lsof -i :18789
netstat -tlnp | grep 18789

# 設定の構文を確認
openclaw config validate

# 詳細エラーを確認
openclaw gateway --verbose 2>&1 | tee gateway.log

セッションが消失

# セッションディレクトリを確認
ls -la ~/.openclaw/sessions/

# クリーンアップ設定を確認
openclaw config get sessionPruning

# 自動クリーンアップを無効化
openclaw config set sessionPruning.enabled false

ツール呼び出しが失敗

# サンドボックス設定を確認
openclaw config get agents.defaults.sandbox

# 一時的にサンドボックスを無効化
openclaw config set agents.defaults.sandbox.mode off

# ツールログを確認
openclaw logs --filter tool

WebSocket 接続失敗

# Gateway 状態を確認
curl http://127.0.0.1:18789/health

# WebSocket エンドポイントを確認
wscat -c ws://127.0.0.1:18789/ws

# ファイアウォールを確認
sudo ufw status
sudo iptables -L -n | grep 18789

まとめ

Gateway のコアコンセプトを理解することが OpenClaw を習得する鍵です：

  • Session：会話コンテキストのコンテナ、タイプ分離をサポート
  • Message Router：メッセージルーティングの中心、メッセージの行き先を決定
  • Tool Registry：ツール登録センター、Agent の能力を制御
  • Skills：スキル拡張システム、機能を迅速に強化
  • WebSocket：リアルタイム通信プロトコル、カスタムクライアントをサポート
  • Event System：イベント配信機構、Webhook と Cron をサポート

これらのコンセプトは今後の記事で繰り返し登場します。深く理解することで、OpenClaw の設定と利用がより効果的になります。

本記事のまとめ：

  • Gateway の全体アーキテクチャとコンポーネントの役割を習得
  • Session セッションモデルとライフサイクルを理解
  • メッセージルーティングとグループアクティベーション戦略を学習
  • ツール権限とサンドボックス設定を理解
  • WebSocket プロトコルとイベントシステムを習得

更新履歴：

  • 2026-02-26：初版公開、OpenClaw v2026.2 ベース

シリーズナビゲーション：