Webhooks

Gateway は外部トリガー用の小さな HTTP Webhook エンドポイントを公開できます。

有効化

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // オプション: 明示的な `agentId` ルーティングをこの許可リストに制限。
    // 省略するか "*" を含めると任意のエージェントを許可。
    // [] に設定するとすべての明示的 `agentId` ルーティングを拒否。
    allowedAgentIds: ["hooks", "main"],
  },
}

補足:

  • hooks.enabled=true の場合、hooks.token は必須です。
  • hooks.path のデフォルトは /hooks。

認証

すべてのリクエストに hook トークンを含める必要があります。ヘッダーでの指定を推奨:

  • Authorization: Bearer <token>（推奨）
  • x-openclaw-token: <token>
  • クエリ文字列のトークンは拒否されます（?token=... は 400 を返します）。

エンドポイント

POST /hooks/wake

ペイロード:

{ "text": "System line", "mode": "now" }
  • text 必須（string）: イベントの説明（例: “New email received”）。
  • mode オプション（now | next-heartbeat）: 即座に Heartbeat をトリガーするか（デフォルト now）、次の定期チェックまで待つか。

効果:

  • メインセッションにシステムイベントをキュー
  • mode=now の場合、即座に Heartbeat をトリガー

POST /hooks/agent

ペイロード:

{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
  • message 必須（string）: エージェントが処理するプロンプトまたはメッセージ。
  • name オプション（string）: hook の人間向け名称（例: “GitHub”）。セッションサマリーのプレフィックスとして使用。
  • agentId オプション（string）: この hook を特定のエージェントにルーティング。不明な ID はデフォルトのエージェントにフォールバック。設定時、hook は解決されたエージェントのワークスペースと設定を使用して実行。
  • sessionKey オプション（string）: エージェントのセッションを識別するキー。hooks.allowRequestSessionKey=true でなければこのフィールドは拒否されます。
  • wakeMode オプション（now | next-heartbeat）: 即座に Heartbeat をトリガーするか（デフォルト now）、次の定期チェックまで待つか。
  • deliver オプション（boolean）: true の場合、エージェントの応答をメッセージングチャネルに送信。デフォルトは true。Heartbeat の確認応答のみの場合は自動スキップ。
  • channel オプション（string）: 配信用のメッセージングチャネル。last、whatsapp、telegram、discord、slack、mattermost（プラグイン）、signal、imessage、msteams のいずれか。デフォルトは last。
  • to オプション（string）: チャネルの受信者識別子（WhatsApp/Signal は電話番号、Telegram はチャット ID、Discord/Slack/Mattermost（プラグイン）はチャネル ID、MS Teams は会話 ID）。デフォルトはメインセッションの最後の受信者。
  • model オプション（string）: モデルオーバーライド（例: anthropic/claude-3-5-sonnet またはエイリアス）。制限されている場合は許可モデルリストに含まれている必要あり。
  • thinking オプション（string）: 思考レベルオーバーライド（例: low、medium、high）。
  • timeoutSeconds オプション（number）: エージェント実行の最大時間（秒）。

効果:

  • 分離されたエージェントターンを実行（独自のセッションキー）
  • 常にメインセッションにサマリーを投稿
  • wakeMode=now の場合、即座に Heartbeat をトリガー

セッションキーポリシー（破壊的変更）

/hooks/agent ペイロードの sessionKey オーバーライドはデフォルトで無効です。

  • 推奨: 固定の hooks.defaultSessionKey を設定し、リクエストによるオーバーライドはオフのまま。
  • オプション: 必要な場合のみリクエストによるオーバーライドを許可し、プレフィックスを制限。

推奨設定:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

互換性設定（レガシー動作）:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // 強く推奨
  },
}

POST /hooks/<name>（マッピング済み）

カスタム hook 名は hooks.mappings で解決されます（設定を参照）。マッピングにより、任意のペイロードを wake または agent アクションに変換でき、テンプレートやコード変換もオプションで利用可能です。

マッピングオプション（概要）:

  • hooks.presets: ["gmail"] で組み込みの Gmail マッピングを有効化。
  • hooks.mappings で設定内に match、action、テンプレートを定義。
  • hooks.transformsDir + transform.module でカスタムロジック用の JS/TS モジュールを読み込み。
    • hooks.transformsDir（設定時）は OpenClaw 設定ディレクトリ配下の transforms ルート内に留まる必要があります（通常 ~/.openclaw/hooks/transforms）。
    • transform.module は有効な transforms ディレクトリ内で解決される必要があります（トラバーサル/エスケープパスは拒否）。
  • match.source を使って汎用的なインジェストエンドポイント（ペイロード駆動のルーティング）を維持。
  • TS 変換にはランタイムで TS ローダー（例: bun や tsx）またはプリコンパイルされた .js が必要。
  • マッピングに deliver: true + channel/to を設定して返信をチャットにルーティング（channel のデフォルトは last で WhatsApp にフォールバック）。
  • agentId で hook を特定のエージェントにルーティング。不明な ID はデフォルトのエージェントにフォールバック。
  • hooks.allowedAgentIds で明示的な agentId ルーティングを制限。省略（または * を含む）で任意のエージェントを許可。[] で明示的な agentId ルーティングを拒否。
  • hooks.defaultSessionKey で明示的なキーが提供されない場合の hook エージェント実行のデフォルトセッションを設定。
  • hooks.allowRequestSessionKey で /hooks/agent ペイロードが sessionKey を設定できるか制御（デフォルト: false）。
  • hooks.allowedSessionKeyPrefixes でリクエストペイロードやマッピングからの明示的な sessionKey 値をオプションで制限。
  • allowUnsafeExternalContent: true でその hook の外部コンテンツ安全ラッパーを無効化（危険。信頼できる内部ソースのみ）。
  • openclaw webhooks gmail setup は openclaw webhooks gmail run 用の hooks.gmail 設定を書き込み。 Gmail watch の完全なフローについては Gmail Pub/Sub を参照。

レスポンス

  • 200: /hooks/wake
  • 200: /hooks/agent（非同期実行を受付）
  • 401: 認証失敗
  • 429: 同一クライアントからの認証失敗の繰り返し後（Retry-After を確認）
  • 400: 無効なペイロード
  • 413: ペイロードサイズ超過

例

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

異なるモデルの使用

エージェントペイロード（またはマッピング）に model を追加して、その実行のモデルをオーバーライドします:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

agents.defaults.models を強制している場合は、オーバーライドモデルがそこに含まれていることを確認してください。

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

セキュリティ

  • hook エンドポイントはループバック、tailnet、または信頼できるリバースプロキシの背後に配置してください。
  • 専用の hook トークンを使用し、Gateway の認証トークンを再利用しないでください。
  • 認証失敗の繰り返しはクライアントアドレスごとにレート制限され、ブルートフォース攻撃を減速させます。
  • マルチエージェントルーティングを使用する場合は、hooks.allowedAgentIds で明示的な agentId の選択を制限してください。
  • 呼び出し元によるセッション選択が不要であれば hooks.allowRequestSessionKey=false を維持してください。
  • リクエストの sessionKey を有効にする場合は、hooks.allowedSessionKeyPrefixes を制限してください（例: ["hook:"]）。
  • Webhook ログにセンシティブな生のペイロードを含めないようにしてください。
  • hook ペイロードは信頼できないものとして扱われ、デフォルトで安全境界でラップされます。 特定の hook でこれを無効にする必要がある場合は、そのマッピングで allowUnsafeExternalContent: true を設定してください（危険）。
arrow_back
前へ
Troubleshooting
次へ
Gmail Pubsub
arrow_forward