Tools Invoke (HTTP)

OpenClaw 的 Gateway 提供了一个简单的 HTTP 端点，可以直接调用单个 Tool。这个功能始终启用，但受 Gateway 认证和 Tool 策略控制。

  • POST /tools/invoke
  • 与 Gateway 使用相同端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/tools/invoke

默认最大请求体大小为 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）。

请求体

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

字段说明：

  • tool（字符串，必填）：要调用的 Tool 名称。
  • action（字符串，可选）：如果 Tool 的 schema 支持 action 参数，且 args 中没有提供，则会映射到 args 中。
  • args（对象，可选）：Tool 特定的参数。
  • sessionKey（字符串，可选）：目标 Session 键。如果省略或为 "main"，Gateway 会使用配置的主 Session 键（遵循 session.mainKey 和默认 Agent，或在全局作用域中使用 global）。
  • dryRun（布尔值，可选）：保留供未来使用，当前会被忽略。

策略和路由行为

Tool 的可用性会通过与 Gateway Agent 相同的策略链进行过滤：

  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • 组策略（如果 Session 键映射到组或 Channel）
  • 子 Agent 策略（使用子 Agent Session 键调用时）

如果策略不允许某个 Tool，端点会返回 404。

为了帮助组策略解析上下文，你可以选择设置：

  • x-openclaw-message-channel: <channel>（例如：slack、telegram）
  • x-openclaw-account-id: <accountId>（当存在多个账户时）

响应

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } }（无效请求或 Tool 错误）
  • 401 → 未授权
  • 404 → Tool 不可用（未找到或不在白名单中）
  • 405 → 方法不允许

示例

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