OpenClaw Webhook設定ガイド：外部トリガーを3分で実装

外部のサービスで何かが起きたとき、それをトリガーにして自動化システムを動かしたいと思ったことはありませんか？例えば、新しいメールが届いたときや、特定の通知を受け取ったときに、すぐにエージェントを動かしたいというケースです。

Gateway の Webhooks 機能を使えば、外部からのリクエストを受け付ける小さな HTTP エンドポイントを公開し、エージェントを即座に実行したり、システムイベントを発生させたりすることができます。この記事では、その設定方法と使い方を詳しく解説します。

Webhooks

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

有効化

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // Optional: restrict explicit `agentId` routing to this allowlist.
    // Omit or include "*" to allow any agent.
    // Set [] to deny all explicit `agentId` routing.
    allowedAgentIds: ["hooks", "main"],
  },
}

注意点：

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

認証

すべてのリクエストには hook token を含める必要があります。以下のヘッダーを使用することを推奨します。

Authorization: Bearer <token> （推奨）
x-openclaw-token: <token>
クエリ文字列によるトークン指定は拒否されます（?token=... は 400 を返します）。
hooks.token の保持者は、その Gateway の Webhook イングレス面において完全に信頼された呼び出し元として扱われます。Webhook のペイロード内容は依然として信頼できないものとして扱われますが、これは所有者以外の認証境界を分けるものではありません。

エンドポイント

`POST /hooks/wake`

ペイロード：

{ "text": "System line", "mode": "now" }

text 必須 (string): イベントの説明（例: “New email received”）。
mode 任意 (now | next-heartbeat): 即座に heartbeat をトリガーするか（デフォルトは now）、次回の定期チェックまで待機するか。

効果：

main セッションにシステムイベントをエンキューします。
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): Webhook の人間が読める名前（例: “GitHub”）。セッションの要約のプレフィックスとして使用されます。
agentId 任意 (string): この Webhook を特定の Agent にルーティングします。不明な ID の場合はデフォルトの Agent にフォールバックします。設定された場合、Webhook は解決された Agent のワークスペースと設定を使用して実行されます。
sessionKey 任意 (string): エージェントのセッションを識別するためのキー。デフォルトでは、hooks.allowRequestSessionKey=true でない限り、このフィールドは拒否されます。
wakeMode 任意 (now | next-heartbeat): 即座に heartbeat をトリガーするか（デフォルトは now）、次回の定期チェックまで待機するか。
deliver 任意 (boolean): true の場合、エージェントのレスポンスがメッセージングチャネルに送信されます。デフォルトは true です。heartbeat の確認応答のみのレスポンスは自動的にスキップされます。
channel 任意 (string): 配信用のメッセージングチャネル。last または設定済みのチャネル、あるいはプラグイン ID（例: discord, matrix, telegram, whatsapp）を使用します。デフォルトは last です。
to 任意 (string): チャネルの受信者識別子（例: WhatsApp/Signal の電話番号、Telegram のチャット ID、Discord/Slack/Mattermost のチャネル ID、Microsoft Teams の会話 ID）。デフォルトは main セッションの最後の受信者です。
model 任意 (string): モデルの上書き（例: anthropic/claude-sonnet-4-6 やエイリアス）。制限がある場合は、許可されたモデルリストに含まれている必要があります。
thinking 任意 (string): 思考レベルの上書き（例: low, medium, high）。
timeoutSeconds 任意 (number): エージェント実行の最大時間（秒）。

効果：

独立した エージェントターンを実行します（独自の sessionKey を持ちます）。
常に main セッションに要約を投稿します。
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:"], // strongly recommended
  },
}

`POST /hooks/<name>` (マッピング済み)

カスタム Webhook 名は 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 は Webhook を特定の Agent にルーティングします。不明な ID はデフォルトの Agent にフォールバックします。
hooks.allowedAgentIds は、明示的な agentId ルーティングを制限します。省略するか * を含めると、すべての Agent を許可します。[] を設定すると、明示的な agentId ルーティングをすべて拒否します。
hooks.defaultSessionKey は、明示的なキーが提供されない場合の Webhook エージェント実行のデフォルトセッションを設定します。
hooks.allowRequestSessionKey は、/hooks/agent ペイロードが sessionKey を設定できるかどうかを制御します（デフォルト: false）。
hooks.allowedSessionKeyPrefixes は、リクエストペイロードやマッピングからの明示的な sessionKey の値をオプションで制限します。
allowUnsafeExternalContent: true は、その Webhook の外部コンテンツ安全ラッパーを無効にします（危険です。信頼できる内部ソースのみに使用してください）。
openclaw webhooks gmail setup は、openclaw webhooks gmail run 用の hooks.gmail 設定を書き込みます。Gmail の監視フローの詳細については、Gmail Pub/Sub を参照してください。

レスポンス

/hooks/wake に対しては 200
/hooks/agent に対しては 200（非同期実行の受理）
認証失敗時は 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"}]}'

セキュリティ

Webhook エンドポイントは、ループバック、tailnet、または信頼できるリバースプロキシの背後に配置してください。
専用の hook token を使用してください。Gateway の認証トークンを再利用しないでください。
Webhook イングレスの影響範囲を狭めるため、厳格な tools.profile とサンドボックスを備えた専用の Webhook エージェントを使用することを推奨します。
ブルートフォース攻撃を遅らせるため、認証失敗が繰り返されるとクライアントアドレスごとにレート制限がかかります。
マルチエージェントルーティングを使用する場合は、hooks.allowedAgentIds を設定して、明示的な agentId の選択を制限してください。
呼び出し元が選択したセッションが必要な場合を除き、hooks.allowRequestSessionKey=false を維持してください。
リクエストの sessionKey を有効にする場合は、hooks.allowedSessionKeyPrefixes（例: ["hook:"]）を制限してください。
Webhook のログに機密性の高い生ペイロードを含めないようにしてください。
Webhook のペイロードは信頼できないものとして扱われ、デフォルトで安全境界でラップされます。特定の Webhook でこれを無効にする必要がある場合は、その Webhook のマッピングで allowUnsafeExternalContent: true を設定してください（危険です）。

設定についてさらに詳しく知りたい場合や、具体的なユースケースの相談は、AI Setup Assistant を活用してください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。