Tools Invoke (HTTP)

Gateway của OpenClaw cung cấp một HTTP endpoint đơn giản để gọi một tool trực tiếp. Endpoint này luôn được bật, nhưng được kiểm soát bởi Gateway auth và tool policy.

  • POST /tools/invoke
  • Cùng port với Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke

Kích thước payload tối đa mặc định là 2 MB.

Xác thực

Sử dụng cấu hình Gateway auth. Gửi bearer token:

  • Authorization: Bearer <token>

Lưu ý:

  • Khi gateway.auth.mode="token", dùng gateway.auth.token (hoặc OPENCLAW_GATEWAY_TOKEN).
  • Khi gateway.auth.mode="password", dùng gateway.auth.password (hoặc OPENCLAW_GATEWAY_PASSWORD).

Request body

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

Các trường:

  • tool (string, bắt buộc): tên tool cần gọi.
  • action (string, tùy chọn): được map vào args nếu tool schema hỗ trợ action và args payload không có trường này.
  • args (object, tùy chọn): các tham số riêng của tool.
  • sessionKey (string, tùy chọn): session key đích. Nếu bỏ qua hoặc là "main", Gateway sẽ dùng main session key đã cấu hình (tuân theo session.mainKey và default agent, hoặc global trong global scope).
  • dryRun (boolean, tùy chọn): dành cho tương lai; hiện tại bị bỏ qua.

Policy + routing behavior

Tool availability được lọc qua cùng policy chain mà Gateway agents sử dụng:

  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • group policies (nếu session key map tới một group hoặc channel)
  • subagent policy (khi gọi với subagent session key)

Nếu một tool không được phép bởi policy, endpoint sẽ trả về 404.

Để giúp group policies xác định context, các bạn có thể set thêm:

  • x-openclaw-message-channel: <channel> (ví dụ: slack, telegram)
  • x-openclaw-account-id: <accountId> (khi có nhiều account)

Responses

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } } (request không hợp lệ hoặc tool error)
  • 401 → unauthorized
  • 404 → tool không khả dụng (không tìm thấy hoặc không có trong allowlist)
  • 405 → method không được phép

Ví dụ

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": {}
  }'