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 token。建議使用 header：

  • Authorization: Bearer <token>（建議做法）
  • x-openclaw-token: <token>
  • 查詢字串 token 會被拒絕（?token=... 回傳 400）。

端點

POST /hooks/wake

Payload：

{ "text": "System line", "mode": "now" }
  • text 必填（string）：事件的描述（例如「收到新郵件」）。
  • mode 選填（now | next-heartbeat）：是否立即觸發 heartbeat（預設 now）或等到下次定期檢查。

效果：

  • 為主要工作階段排入一個系統事件
  • 如果 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）：給代理處理的提示或訊息。
  • 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 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:"], // 強烈建議
  },
}

POST /hooks/<name>（透過對應）

自訂 hook 名稱透過 hooks.mappings 解析（參閱設定）。對應可以將任意 payload 轉換為 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 保留通用的接入端點（依 payload 驅動的路由）。
  • 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 payload 是否可以設定 sessionKey（預設：false）。
  • hooks.allowedSessionKeyPrefixes 選擇性地限制來自請求 payload 和對應的明確 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：無效的 payload
  • 413：payload 過大

範例

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（或對應）中加入 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 token；不要重複使用 Gateway 的驗證 token。
  • 同一用戶端位址的重複驗證失敗會被限速，以減緩暴力破解嘗試。
  • 如果你使用多代理路由，設定 hooks.allowedAgentIds 以限制明確的 agentId 選擇。
  • 除非你需要呼叫者自選工作階段，否則保持 hooks.allowRequestSessionKey=false。
  • 如果你啟用了請求 sessionKey，限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）。
  • 避免在 webhook 日誌中包含敏感的原始 payload。
  • Hook payload 預設視為不受信任，並以安全邊界包裝。 如果你必須為特定 hook 停用此功能，在該 hook 的對應中設定 allowUnsafeExternalContent: true（危險）。
arrow_back
上一頁
Troubleshooting
下一頁
Gmail Pubsub
arrow_forward