透過 OpenClaw HTTP API 快速呼叫工具：完整整合指南

有時候你只是想快速執行一個特定的工具，而不想繞一大圈去建立 WebSocket 連線或啟動完整的 Agent 對話。無論是為了自動化腳本還是整合到現有的工作流中，直接透過 HTTP 呼叫工具通常是最直覺的做法。

OpenClaw 的 Gateway 提供了一個簡單的 HTTP 端點，讓你直接呼叫單個工具。這個功能預設是開啟的，並使用 Gateway 的驗證機制與工具政策。就像 OpenAI 相容的 /v1/* 介面一樣，shared-secret bearer 驗證會被視為對整個 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。

安全邊界（重要）

請將此端點視為 Gateway 實例的完整操作者存取介面。

這裡的 HTTP bearer 驗證並非針對單一使用者的細粒度權限模型。
針對此端點的有效 Gateway token/password 應被視為擁有者/操作者憑證。
對於共用金鑰驗證模式（token 和 password），即使呼叫者傳送了較窄的 x-openclaw-scopes 標頭，端點也會恢復正常的完整操作者預設權限。
共用金鑰驗證也會將此端點上的直接工具呼叫視為擁有者發送的 turn。
信任身份的 HTTP 模式（例如信任的代理驗證或在私有進入點使用 gateway.auth.mode="none"）仍會遵循請求上宣告的操作者範圍。
請將此端點僅保留在 loopback/tailnet/私有進入點；不要將其直接暴露在公開網路。

驗證矩陣：

gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
- 證明持有共用的 Gateway 操作者金鑰
- 忽略較窄的 x-openclaw-scopes
- 恢復完整的預設操作者範圍集
- 將此端點上的直接工具呼叫視為擁有者發送的 turn
信任身份的 HTTP 模式（例如信任的代理驗證，或在私有進入點使用 gateway.auth.mode="none"）
- 驗證某些外部信任身份或部署邊界
- 遵循宣告的 x-openclaw-scopes 標頭
- 僅在宣告的範圍中確實存在 operator.admin 時才獲得擁有者語義

請求主體 (Request Body)

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

欄位說明：

tool (string, 必填): 要呼叫的工具名稱。
action (string, 選填): 如果工具 schema 支援 action 且 args payload 中省略了它，則會映射到 args 中。
args (object, 選填): 工具特定的參數。
sessionKey (string, 選填): 目標 session key。如果省略或為 "main"，Gateway 會使用設定的主 session key（遵循 session.mainKey 和預設 agent，或全域範圍內的 global）。
dryRun (boolean, 選填): 保留供未來使用；目前會被忽略。

政策與路由行為

工具的可用性會透過與 Gateway agent 相同的政策鏈進行過濾：

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
群組政策（如果 session key 映射到群組或頻道）
子 agent 政策（使用子 agent session key 呼叫時）

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

重要的邊界注意事項：

執行核准（Exec approvals）是操作者的防護欄，而不是此 HTTP 端點的獨立授權邊界。如果工具可以透過 Gateway 驗證 + 工具政策在此處存取，/tools/invoke 不會增加額外的逐次呼叫核准提示。
不要與不信任的呼叫者分享 Gateway bearer 憑證。如果你需要在信任邊界之間進行隔離，請執行獨立的 Gateway（理想情況下使用獨立的作業系統使用者/主機）。

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

exec — 直接指令執行 (RCE 風險)
spawn — 任意子程序建立 (RCE 風險)
shell — shell 指令執行 (RCE 風險)
fs_write — 主機上的任意檔案修改
fs_delete — 主機上的任意檔案刪除
fs_move — 主機上的任意檔案移動/重新命名
apply_patch — 補丁套用可能會重寫任意檔案
sessions_spawn — session 編排；遠端啟動 agent 屬於 RCE
sessions_send — 跨 session 訊息注入
cron — 持久化自動化控制平面
gateway — Gateway 控制平面；防止透過 HTTP 重新設定
nodes — Node 指令轉發可以觸及配對主機上的 system.run
whatsapp_login — 需要終端機 QR code 掃描的互動式設定；會在 HTTP 上掛起

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

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      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 → 方法不允許
500 → { ok: false, error: { type, message } } (非預期的工具執行錯誤；訊息已過濾)

範例

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

想要更輕鬆地設定你的開發環境嗎？試試我們的 AI Setup Assistant。

下一步

瞭解更多關於 Gateway 身份驗證的細節
探索如何設定工具政策 (Tool Policies)
查看完整的工具列表

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。