Tools Invoke（HTTP）

OpenClaw 的 Gateway 提供一個簡單的 HTTP 端點，用來直接呼叫單一工具。此端點始終啟用，但受 Gateway 認證和工具策略管控。

POST /tools/invoke
與 Gateway 共用相同連接埠（WS + HTTP 多工）：http://<gateway-host>:<port>/tools/invoke

預設最大 payload 大小為 2 MB。

認證

使用 Gateway 的認證設定。發送 bearer token：

Authorization: Bearer <token>

注意事項：

當 gateway.auth.mode="token" 時，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
當 gateway.auth.mode="password" 時，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
如果設定了 gateway.auth.rateLimit 且認證失敗次數過多，端點會回傳 429 並帶有 Retry-After 標頭。

請求內容

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

欄位說明：

tool（字串，必要）：要呼叫的工具名稱。
action（字串，選用）：當工具 schema 支援 action 且 args payload 中省略時，會映射到 args。
args（物件，選用）：工具專屬的參數。
sessionKey（字串，選用）：目標 session key。省略或為 "main" 時，Gateway 使用設定的 main session key（遵循 session.mainKey 和預設代理，或在全域範圍中使用 global）。
dryRun（布林，選用）：保留供未來使用，目前會被忽略。

策略 + 路由行為

工具可用性會通過與 Gateway 代理相同的策略鏈過濾：

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
群組策略（當 session key 對應到群組或頻道時）
子代理策略（以子代理 session key 呼叫時）

如果工具不被策略允許，端點回傳 404。

Gateway HTTP 預設也會套用一個硬性拒絕清單（即使 session 策略允許該工具）：

sessions_spawn
sessions_send
gateway
whatsapp_login

你可以透過 gateway.tools 自訂此拒絕清單：

{
  gateway: {
    tools: {
      // 額外封鎖的 HTTP /tools/invoke 工具
      deny: ["browser"],
      // 從預設拒絕清單中移除的工具
      allow: ["gateway"],
    },
  },
}

為了協助群組策略解析上下文，你可以選擇性地設定：

x-openclaw-message-channel: <channel>（例如：slack、telegram）
x-openclaw-account-id: <accountId>（當有多個帳號時）

回應

200 → { ok: true, result }
400 → { ok: false, error: { type, message } }（無效請求或工具輸入錯誤）
401 → 未授權
429 → 認證速率限制（已設定 Retry-After）
404 → 工具不可用（找不到或未在白名單中）
405 → 不允許的 HTTP 方法
500 → { ok: false, error: { type, message } }（非預期的工具執行錯誤；訊息已脫敏）

範例

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'