設定 OpenClaw Webhooks：串接外部事件與自動化觸發

在開發自動化流程時，最讓人頭痛的就是如何讓外部系統與你的 AI 機器人溝通。你可能不希望為了接收一個簡單的通知就去寫複雜的輪詢邏輯，或者去維護一個沉重的中間層。

Gateway 提供的 Webhooks 功能就是為了解決這個問題。它讓你透過簡單的 HTTP 請求，就能直接觸發外部動作或叫醒你的 agent，讓整個自動化流程變得直覺且高效。

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。建議優先使用 headers：

• Authorization: Bearer <token>（推薦使用）
• x-openclaw-token: <token>
• 請求會拒絕 Query-string 中的 token（使用 ?token=... 會回傳 400）。
• 持有 hooks.token 的調用者將被視為該 gateway 上 hook 入口點的完全信任對象。雖然 hook payload 的內容仍被視為不可信，但這並非一個獨立的非擁有者驗證邊界。

端點

POST /hooks/wake

Payload:

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

• text 必填 (string)：事件的描述（例如：“收到新郵件”）。
• mode 選填 (now | next-heartbeat)：決定是立即觸發 heartbeat（預設為 now），還是等待下一次定期檢查。

效果：

• 為 main session 排入一個系統事件。
• 如果 mode=now，則會立即觸發一次 heartbeat。

POST /hooks/agent

Payload:

{
  "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)：交給 agent 處理的 prompt 或訊息。
• name 選填 (string)：該 hook 的易讀名稱（例如：“GitHub”），會作為 session 摘要的前綴。
• agentId 選填 (string)：將此 hook 路由到特定的 agent。若 ID 未知則回退到預設 agent。設定後，hook 將使用該 agent 的 workspace 和配置執行。
• sessionKey 選填 (string)：用來識別 agent session 的 key。除非 hooks.allowRequestSessionKey=true，否則此欄位預設會被拒絕。
• wakeMode 選填 (now | next-heartbeat)：決定是立即觸發 heartbeat（預設為 now），還是等待下一次定期檢查。
• deliver 選填 (boolean)：若為 true，agent 的回應將被發送到訊息 channel。預設為 true。僅包含 heartbeat 確認的回應會被自動跳過。
• channel 選填 (string)：發送訊息的 channel。可以使用 last 或任何已配置的 channel 或 plugin id，例如 discord, matrix, telegram 或 whatsapp。預設為 last。
• to 選填 (string)：該 channel 的接收者識別碼（例如 WhatsApp/Signal 的電話號碼、Telegram 的 chat ID、Discord/Slack/Mattermost 的 channel ID、Microsoft Teams 的 conversation ID）。預設為 main session 中的最後一個接收者。
• model 選填 (string)：覆蓋使用的模型（例如 anthropic/claude-sonnet-4-6 或別名）。若有模型限制，則必須在允許清單中。
• thinking 選填 (string)：覆蓋思考層級（例如 low, medium, high）。
• timeoutSeconds 選填 (number)：agent 執行的最大秒數。

效果：

• 執行一個 獨立 的 agent turn（擁有自己的 session key）並將摘要發送到 main session。
• 如果 wakeMode=now，則會立即觸發一次 heartbeat。

Session key 策略（重大變更）

/hooks/agent payload 中的 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> (mapped)

自定義的 hook 名稱會透過 hooks.mappings 進行解析（詳見配置）。Mapping 可以將任意 payload 轉換為 wake 或 agent 動作，並支援選填的模板或代碼轉換。

Mapping 選項摘要：

• hooks.presets: ["gmail"] 可啟用內建的 Gmail mapping。
• hooks.mappings 讓你可以在配置中定義 match、action 和模板。
• hooks.transformsDir + transform.module 可載入 JS/TS 模組來處理自定義邏輯。
  • hooks.transformsDir（若有設定）必須位於 OpenClaw 配置目錄下的 transforms 根目錄（通常是 ~/.openclaw/hooks/transforms）。
  • transform.module 必須在有效的 transforms 目錄內解析（拒絕路徑遍歷或逃逸）。
• 使用 match.source 來保持通用的接收端點（由 payload 驅動路由）。
• TS 轉換在執行時需要 TS 載入器（例如 bun 或 tsx）或預編譯的 .js。
• 在 mapping 上設定 deliver: true + channel/to 可將回覆路由到聊天介面（channel 預設為 last，若無則回退到 WhatsApp）。
• agentId 將 hook 路由到特定 agent；未知 ID 會回退到預設 agent。
• hooks.allowedAgentIds 限制顯式的 agentId 路由。省略此項（或包含 *）則允許任何 agent。設定為 [] 則拒絕顯式路由。
• hooks.defaultSessionKey 設定未提供顯式 key 時，hook agent 執行的預設 session。
• hooks.allowRequestSessionKey 控制 /hooks/agent payload 是否可以設定 sessionKey（預設：false）。
• hooks.allowedSessionKeyPrefixes 可選擇性地限制請求 payload 和 mapping 中顯式的 sessionKey 值。
• allowUnsafeExternalContent: true 會停用該 hook 的外部內容安全包裝（具危險性；僅限信任的內部來源）。
• openclaw webhooks gmail setup 會為 openclaw webhooks gmail run 寫入 hooks.gmail 配置。完整流程請參考 Gmail Pub/Sub。

回應

• /hooks/wake 回傳 200
• /hooks/agent 回傳 200（已接受非同步執行）
• 驗證失敗回傳 401
• 來自同一客戶端的重複驗證失敗回傳 429（請檢查 Retry-After）
• Payload 無效回傳 400
• Payload 過大回傳 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 payload（或 mapping）中加入 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 端點放在 loopback、tailnet 或信任的反向代理之後。
• 使用專用的 hook token；不要重複使用 gateway 的驗證 token。
• 建議使用具備嚴格 tools.profile 和沙盒機制的專用 hook agent，以縮小 hook 入口的受攻擊面。
• 針對同一客戶端地址的重複驗證失敗會進行速率限制，以減緩暴力破解。
• 如果你使用多 agent 路由，請設定 hooks.allowedAgentIds 來限制顯式的 agentId 選擇。
• 除非你需要由調用者選擇 session，否則請保持 hooks.allowRequestSessionKey=false。
• 如果啟用了請求 sessionKey，請限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）。
• 避免在 webhook 日誌中包含敏感的原始 payload。
• 預設情況下，hook payload 被視為不可信，並會被安全邊界包裝。
• 若必須針對特定 hook 停用此功能，請在該 hook 的 mapping 中設定 allowUnsafeExternalContent: true（此操作具危險性）。

---

下一步：

• Gmail Pub/Sub 整合
• 配置 Agent 權限

想了解更多？試試我們的 AI Setup Assistant