Webhooks（ウェブフック）

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

有効化

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks"
  }
}

注意:

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

認証

すべてのリクエストには Hook トークンを含める必要があります。ヘッダーを優先します:

  • Authorization: Bearer <token>（推奨）
  • x-openclaw-token: <token>
  • ?token=<token>（非推奨。警告をログに記録し、将来のメジャーリリースで削除されます）

エンドポイント

POST /hooks/wake

ペイロード:

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

効果:

  • Main session のシステムイベントをエンキュー
  • mode=now の場合、即座に Heartbeat をトリガー

POST /hooks/agent

ペイロード:

{
  "message": "Run this",
  "name": "Email",
  "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）: Agent が処理するプロンプトまたはメッセージ。
  • name オプション（string）: Hook の人間が読める名前（例: 「GitHub」）。Session の要約でプレフィックスとして使用されます。
  • sessionKey オプション（string）: Agent の Session を識別するために使用されるキー。デフォルトはランダムな hook:<uuid>。一貫したキーを使用すると、Hook コンテキスト内でマルチターン会話が可能になります。
  • wakeMode オプション（now | next-heartbeat）: 即座に Heartbeat をトリガーするか（デフォルト now）、次の定期チェックまで待つか。
  • deliver オプション（boolean）: true の場合、Agent の応答はメッセージング Channel に送信されます。デフォルトは true。Heartbeat 確認のみの応答は自動的にスキップされます。
  • channel オプション（string）: 配信用のメッセージング Channel。次のいずれか: last、whatsapp、telegram、discord、slack、mattermost（プラグイン）、signal、imessage、msteams。デフォルトは last。
  • to オプション（string）: Channel の受信者識別子（例: WhatsApp/Signal の電話番号、Telegram のチャット ID、Discord/Slack/Mattermost（プラグイン）の Channel ID、MS Teams の会話 ID）。デフォルトは Main session の最後の受信者。
  • model オプション（string）: Model オーバーライド（例: anthropic/claude-3-5-sonnet またはエイリアス）。制限されている場合は、許可されたモデルリストに含まれている必要があります。
  • thinking オプション（string）: Thinking レベルオーバーライド（例: low、medium、high）。
  • timeoutSeconds オプション（number）: Agent 実行の最大期間（秒単位）。

効果:

  • Isolated Agent ターンを実行（独自の Session キー）
  • 常に Main session に要約を投稿
  • wakeMode=now の場合、即座に Heartbeat をトリガー

POST /hooks/<name>（マップ済み）

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

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

  • hooks.presets: ["gmail"] は組み込みの Gmail マッピングを有効にします。
  • hooks.mappings を使用すると、設定で match、action、テンプレートを定義できます。
  • hooks.transformsDir + transform.module はカスタムロジック用の JS/TS モジュールをロードします。
  • 一般的な取り込みエンドポイントを維持するには match.source を使用します（ペイロード駆動ルーティング）。
  • TS 変換には TS ローダー（例: bun または tsx）またはランタイムでプリコンパイルされた .js が必要です。
  • マッピングに deliver: true + channel/to を設定して、返信をチャットサーフェスにルーティングします（channel のデフォルトは last で、WhatsApp にフォールバックします）。
  • allowUnsafeExternalContent: true は、その Hook の外部コンテンツ安全ラッパーを無効にします（危険。信頼できる内部ソースのみ）。
  • openclaw webhooks gmail setup は openclaw webhooks gmail run のための hooks.gmail 設定を書き込みます。 完全な Gmail watch フローについては Gmail Pub/Sub を参照してください。

レスポンス

  • /hooks/wake の場合は 200
  • /hooks/agent の場合は 202（非同期実行が開始されました）
  • 認証失敗時は 401
  • 無効なペイロード時は 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"}'

異なるモデルを使用

Agent ペイロード（またはマッピング）に 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 認証トークンを再利用しないでください。
  • Webhook ログに機密の生のペイロードを含めないでください。
  • Hook ペイロードはデフォルトで信頼されないものとして扱われ、安全境界でラップされます。 特定の Hook でこれを無効にする必要がある場合は、その Hook のマッピングで allowUnsafeExternalContent: true を設定してください（危険）。
← ドキュメントに戻る