工具调用 %%PH:GLOSSARY:92:46ca4df%%

OpenClaw 的 Gateway(网关) 公开了一个简单的 HTTP 端点，用于直接调用单个工具。它始终启用，并使用 Gateway(网关) 身份验证以及工具策略。与 OpenAI 兼容的 /v1/* 表面类似，共享密钥持有者身份验证被视为整个网关的可信操作员访问权限。

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>
可信的承载身份的 HTTP 身份验证（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.trustedProxy.allowLoopback = true。
绕过代理的内部同主机调用者可以使用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 作为本地直接回退方案。任何 Forwarded、X-Forwarded-* 或 X-Real-IP 标头证据都会将请求保持在受信任代理路径上。
如果配置了 gateway.auth.rateLimit 并且发生了过多的身份验证失败，端点将返回带有 Retry-After 的 429。

安全边界（重要）

将此端点视为网关实例的完全操作员访问表面。

此处的 HTTP 持有者认证并非狭义的每用户范围模型。
此端点的有效 Gateway(网关) 令牌/密码应被视为所有者/操作员凭据。
对于共享密钥身份验证模式（token 和 password），即使调用方发送了更窄的 x-openclaw-scopes 标头，端点也会恢复正常完整的操作员默认值。
共享密钥认证还将此端点上的直接工具调用视为所有者发送方轮次。
受信任的承载身份的 HTTP 模式（例如受信任的代理身份验证或私有入口上的 gateway.auth.mode="none"）在存在 x-openclaw-scopes 时会遵守它，否则回退到正常的操作员默认范围集。
请将此端点仅保留在本地/tailnet/私有入口上；不要将其直接暴露给公共互联网。

认证矩阵：

gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
- 证明持有共享网关操作员机密
- 忽略更窄的 x-openclaw-scopes
- 恢复完整的默认操作员范围集： operator.admin、operator.approvals、operator.pairing、 operator.read、operator.talk.secrets、operator.write
- 将此端点上的直接工具调用视为所有者发送方轮次
受信任的承载身份的 HTTP 模式（例如受信任的代理身份验证，或私有入口上的 gateway.auth.mode="none"）
- 对外部某些可信身份或部署边界进行身份验证
- 当标头存在时遵守 x-openclaw-scopes
- 当标头不存在时，回退到正常的操作员默认范围集
- 仅当调用方明确缩小范围并省略 operator.admin 时，才会失去所有者语义

请求体

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

字段：

tool（字符串，必需）：要调用的工具名称。
action（字符串，可选）：如果工具架构支持 action 且 args 负载中省略了它，则会将其映射到 args 中。
args（对象，可选）：特定于工具的参数。
sessionKey (字符串，可选)：目标会话密钥。如果省略或为 "main"Gateway(网关)，Gateway(网关) 将使用配置的主会话密钥（遵守 session.mainKey 和默认代理，或全局作用域中的 global）。
dryRun (布尔值，可选)：保留供将来使用；当前被忽略。

策略 + 路由行为

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

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

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

重要的边界说明：

Exec 批准是操作员护栏，而不是此 HTTP 端点的单独授权边界。如果工具在此处可通过 Gateway(网关) 身份验证 + 工具策略访问，Gateway(网关)/tools/invoke 不会添加额外的每次调用批准提示。
如果 exec 在此处可访问，请将其视为可变的 shell 接口。拒绝 write、edit、apply_patch 或 HTTP 文件系统写入工具不会使 shell 执行变为只读。
请勿与不受信任的调用者共享 Gateway(网关) 持有者凭据。如果您需要跨信任边界的隔离，请运行单独的网关（理想情况下使用单独的操作系统用户/主机）。

Gateway(网关) HTTP 默认也会应用硬拒绝列表（即使会话策略允许该工具）：

exec - 直接命令执行（RCE 接口）
spawn - 任意子进程创建（RCE 接口）
shell - Shell 命令执行（RCE 接口）
fs_write - 主机上的任意文件更改
fs_delete - 主机上的任意文件删除
fs_move - 主机上的任意文件移动/重命名
apply_patch - 补丁应用程序可以重写任意文件
sessions_spawn - 会话编排；远程生成代理是 RCE
sessions_send - 跨会话消息注入
cron - 持久化自动化控制平面
gateway - Gateway 控制平面；防止通过 HTTP 重新配置
nodes - 节点命令中继可以到达配对主机上的 system.run
whatsapp_login - 需要终端二维码扫描的交互式设置；在 HTTP 上挂起

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

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list
      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 } } （意外的工具执行错误；已清理的消息）

示例

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

工具调用 %%PH:GLOSSARY:92:46ca4df%%

身份验证

安全边界（重要）

请求体

策略 + 路由行为

响应

示例

相关