6.12 工具调用API

工具调用 (HTTP)

OpenClaw的网关提供了一个简单的HTTP端点,用于直接调用单个工具。该端点始终启用,但受网关身份验证和工具策略的控制。

• POST /tools/invoke
• 与网关相同的端口(WebSocket + HTTP多路复用):http://<host>:<port>/tools/invoke

默认最大有效负载大小为 2 MB。

身份验证

使用网关身份验证配置。发送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 (string, 必需): 要调用的工具名称。
• action (string, 可选): 如果工具架构支持 action 且参数有效负载中省略了它,则映射到 args 中。
• args (object, 可选): 工具特定的参数。
• sessionKey (string, 可选): 目标会话键。如果省略或为 "main",网关将使用配置的主会话键(遵循 session.mainKey 和默认代理,或在全局作用域中使用 global)。
• dryRun (boolean, 可选): 为将来使用保留;当前被忽略。

策略和路由行为

工具可用性通过与网关代理使用的相同策略链进行过滤:

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<agent>.tools.allow / agents.<agent>.tools.byProvider.allow
• 组策略(如果会话键映射到组或频道)
• 子代理策略(当使用子代理会话键调用时)

如果策略不允许使用某个工具,端点将返回 404。

为了帮助组策略解析上下文,您可以选择性地设置:

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

响应

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (无效请求或工具错误)
• 401 → 未授权
• 404 → 工具不可用(未找到或未列入允许列表)
• 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": {} }'