> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具调用 API

# 工具调用（HTTP）

OpenClaw 的 Gateway 网关暴露了一个简单的 HTTP 端点用于直接调用单个工具。它始终启用，但受 Gateway 网关认证和工具策略限制。 该端点始终启用，但受 Gateway 认证和工具策略的限制。

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

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

## 认证

使用 Gateway 网关认证配置。发送 bearer 令牌： 发送 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`。

## 请求体

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

字段：

* `tool`（string，必需）：要调用的工具名称。
* `action`（string，可选）：如果工具 schema 支持 `action` 且 args 负载省略了它，则映射到 args。
* `args`（object，可选）：工具特定的参数。
* `sessionKey`（string，可选）：目标会话键。如果省略或为 `"main"`，Gateway 网关使用配置的主会话键（遵循 `session.mainKey` 和默认智能体，或在全局范围中使用 `global`）。 10. 如果省略或为 `"main"`，Gateway 将使用配置的主会话键（遵循 `session.mainKey` 和默认 agent，或在全局作用域中使用 `global`）。
* `dryRun`（boolean，可选）：保留供将来使用；当前忽略。

## 策略 + 路由行为

工具可用性通过 Gateway 网关智能体使用的相同策略链过滤：

* `tools.profile` / `tools.byProvider.profile`
* `tools.allow` / `tools.byProvider.allow`
* `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
* 群组策略（如果会话键映射到群组或渠道）
* 20. 子代理策略（当使用子代理会话键进行调用时）

如果工具不被策略允许，端点返回 **404**。

Gateway HTTP 默认还会应用一个硬性拒绝列表（即使会话策略允许该工具）：

* `sessions_spawn`
* `sessions_send`
* `gateway`
* `whatsapp_login`

你可以通过 `gateway.tools` 自定义此拒绝列表：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    tools: {
      // 通过 HTTP /tools/invoke 额外阻止的工具
      deny: ["browser"],
      // 从默认拒绝列表中移除工具
      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` → 方法不允许
* gateway/tools-invoke-http-api.md

## 示例

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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": {}
  }'
```