Tools Invoke（HTTP）

OpenClaw 的 Gateway 提供一个简单的 HTTP 端点，用于直接调用单个 tool。该端点始终启用，但会受 Gateway auth 与 tool policy 限制。

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

默认最大 payload 为 2 MB。

认证

使用 Gateway 的 auth 配置。发送 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）。

请求体

json

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

字段说明：

tool（string，必填）：要调用的 tool 名称。
action（string，可选）：如果 tool schema 支持 action 且 args 里未提供，则会映射进 args。
args（object，可选）：tool 的参数。
sessionKey（string，可选）：目标 session key。如果省略或为 "main"，Gateway 会使用配置的 main session key（遵循 session.mainKey 与默认 agent；或 global scope 的 global）。
dryRun（boolean，可选）：保留字段用于未来；当前会被忽略。

Policy + 路由行为

tool 的可用性会经过与 Gateway agents 相同的 policy 链过滤：

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
group policies（当 session key 映射到 group 或 channel 时）
subagent policy（当以 subagent session key 调用时）

如果某个 tool 不被 policy 允许，该端点会返回 404。

为了帮助 group policies 解析上下文，你还可以选择性地设置：

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

响应

200 → { ok: true, result }
400 → { ok: false, error: { type, message } }（请求无效或 tool 报错）
401 → unauthorized
404 → tool 不可用（not found 或未被 allowlist）
405 → method not allowed

示例

bash

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

Tools Invoke（HTTP） ​

认证 ​

请求体 ​

Policy + 路由行为 ​

响应 ​

示例 ​

Tools Invoke（HTTP）

认证

请求体

Policy + 路由行为

响应

示例