Tools Invoke（HTTP API）

OpenClaw 的 Gateway 提供了一个简单的 HTTP 端点，可以直接调用单个工具。该端点始终开启，使用 Gateway 认证和工具策略。与 OpenAI 兼容的 /v1/* 接口一样，共享密钥 Bearer 认证被视为对整个 Gateway 的受信任运营者访问。

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

默认最大请求体大小为 2 MB。

小龙虾养好之后，这个接口就是你跟它"发号施令"的快速通道——无需打开整个对话，直接命令它执行工具。

认证

使用 Gateway 认证配置。

常见 HTTP 认证方式：

共享密钥认证（gateway.auth.mode="token" 或 "password"）：Authorization: Bearer <token-or-password>
受信任身份代理认证（gateway.auth.mode="trusted-proxy"）：通过已配置的身份感知代理路由，由代理注入所需的身份头部
私有入口开放认证（gateway.auth.mode="none"）：无需认证头部

说明：

当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
当 gateway.auth.mode="trusted-proxy" 时，HTTP 请求必须来自已配置的非回环受信任代理源；同主机回环代理不满足此模式。
如果配置了 gateway.auth.rateLimit 且认证失败次数过多，端点返回 429，并附带 Retry-After。

安全边界（重要）

将此端点视为该 Gateway 实例的完整运营者访问接口。

此处的 HTTP Bearer 认证不是针对每个用户的窄作用域模型。
适用于此端点的有效 Gateway token/password 应视为所有者/运营者凭据。
对于共享密钥认证模式（token 和 password），即使调用方发送了较窄的 x-openclaw-scopes 头，端点也会恢复完整的默认运营者权限。
共享密钥认证还将此端点上的直接工具调用视为所有者发起的回合。
受信任的身份代理 HTTP 模式（如 trusted-proxy 认证或私有入口上的 gateway.auth.mode="none"）在存在 x-openclaw-scopes 时遵循它，否则回退到默认运营者作用域集。
仅将此端点保持在回环/tailnet/私有入口；不要直接暴露到公网。

认证矩阵：

模式	行为
`token` 或 `password` + `Authorization: Bearer ...`	证明持有共享 Gateway 运营者密钥；忽略较窄的 `x-openclaw-scopes`；恢复完整默认运营者作用域集
受信任身份代理模式（trusted-proxy 或私有入口 `none`）	认证外部受信任身份；存在 `x-openclaw-scopes` 时遵循；不存在时回退到默认作用域集

请求体

json

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

字段说明：

tool（字符串，必填）：要调用的工具名称。
action（字符串，可选）：如果工具 schema 支持 action 且 args 中未包含，则映射到 args。
args（对象，可选）：工具特定参数。
sessionKey（字符串，可选）：目标会话 key。省略或为 "main" 时，Gateway 使用配置的主会话 key（遵循 session.mainKey 和默认 agent，或全局作用域中的 global）。
dryRun（布尔值，可选）：保留字段，当前忽略。

策略与路由行为

工具可用性通过与 Gateway agent 相同的策略链过滤：

tools.profile / tools.byProvider.profile
tools.allow / tools.byProvider.allow
agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
组策略（当会话 key 对应某个组或频道时）
子 agent 策略（使用子 agent 会话 key 调用时）

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

重要边界说明：

Exec 审批是运营者层面的保护机制，并非此 HTTP 端点的独立授权边界。如果工具通过 Gateway 认证 + 工具策略可以访问，/tools/invoke 不会增加额外的逐次审批提示。
请勿将 Gateway Bearer 凭据分享给不受信任的调用方。如需跨信任边界隔离，请运行独立的 Gateway（最好使用独立的 OS 用户/主机）。

Gateway HTTP 默认还有一个硬拒绝列表（即使会话策略允许，也会被拒绝）：

exec — 直接命令执行（RCE 接口）
spawn — 任意子进程创建（RCE 接口）
shell — Shell 命令执行（RCE 接口）
fs_write — 主机上的任意文件写入
fs_delete — 主机上的任意文件删除
fs_move — 主机上的任意文件移动/重命名
apply_patch — 补丁应用可重写任意文件
sessions_spawn — 会话编排；远程启动 Agent 等同于 RCE
sessions_send — 跨会话消息注入
cron — 持久化自动化控制面
gateway — Gateway 控制面；防止通过 HTTP 重新配置
nodes — 节点命令中继可在配对主机上触发 system.run
whatsapp_login — 需要终端 QR 扫描的交互式设置；HTTP 下会挂起

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

json5

{
  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 → 方法不允许
500 → { ok: false, error: { type, message } }（工具执行意外错误；已脱敏处理）

示例

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 API） ​

认证 ​

安全边界（重要） ​

请求体 ​

策略与路由行为 ​

响应 ​

示例 ​

Tools Invoke（HTTP API）

认证

安全边界（重要）

请求体

策略与路由行为

响应

示例