工具调用 API

OpenClaw 的 Gateway 暴露了一个 HTTP 端点，用于直接调用单个工具。它始终启用，并使用 Gateway 认证和工具策略。与兼容 OpenAI 的 /v1/* 接口一样，共享密钥 Bearer 认证被视为对整个网关的可信操作员访问。

• 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"）：无需认证头

注意事项：

• mode="token" 使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• mode="password" 使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• mode="trusted-proxy" 要求 HTTP 请求来自已配置的可信代理源；同主机回环代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• 绕过代理的内部同主机调用方可以使用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 作为本地直连回退。只要存在 Forwarded、X-Forwarded-* 或 X-Real-IP 头证据，请求就会继续走可信代理路径。
• 如果配置了 gateway.auth.rateLimit 且认证失败次数过多，端点将返回 429 并附带 Retry-After。

安全边界（重要）¶

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

• 此处的 HTTP Bearer 认证不是细粒度的按用户作用域模型。
• 该端点的有效 Gateway token/password 应被视为所有者/操作员凭据。
• 对于共享密钥认证模式（token 和 password），即使调用方发送了更窄的 x-openclaw-scopes 头，端点也会恢复正常的完整操作员默认值。
• 共享密钥认证还会将对此端点的直接工具调用视为所有者发送者的回合。
• 可信身份承载 HTTP 模式（可信代理认证，或私有入口上的 gateway.auth.mode="none"）在存在 x-openclaw-scopes 时会遵循该头，否则回退到正常的操作员默认作用域集合。
• 仅将此端点放在 loopback/tailnet/私有入口上；不要直接暴露到公共互联网。

认证矩阵：

请求体¶

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

字段：

• tool / name（字符串，必填）：要调用的工具名称。如果同时发送，name 优先。
• action（字符串，可选）：如果工具 schema 支持 action 属性且 args 未设置该属性，则合并到 args.action。
• args（对象，可选）：工具特定的参数。
• sessionKey（字符串，可选）：目标会话键。如果省略或为 "main"，Gateway 会解析代理的规范主会话（agent:<agentId>:main，在全局会话作用域中为 global）。自定义的 session.mainKey 值会被忽略。
• agentId（字符串，可选）：为该代理解析会话键。如果与已映射到不同代理的显式 sessionKey 冲突，则返回 400 错误。
• idempotencyKey（字符串，可选）：用于为此次调用派生稳定的工具调用 id。
• dryRun（布尔值，可选）：保留供将来使用；当前忽略。

策略与路由行为¶

对于经过身份认证的调用方，如果其具有命名操作员角色，则该角色的代理允许列表同样适用，即使所选会话没有存储条目。具有 sandbox: "required" 的角色必须指向已记录必需沙箱来源的现有会话；缺失会话（包括省略或解析到该会话的 "main" 目标）将返回 403。请先通过正常会话流程创建会话。WebSocket tools.invoke 方法使用相同的规则。共享密钥和可信系统调用保留其现有权限。

工具可用性通过 Gateway 代理使用的同一策略链进行过滤：

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

如果策略不允许某个工具，端点会返回 404。

重要边界说明：

• Exec 审批是操作员护栏，而不是此 HTTP 端点的独立授权边界。如果某个工具可通过 Gateway 认证 + 工具策略在此处访问，/tools/invoke 不会额外添加每次调用的审批提示。
• 如果 exec 在此处可访问，请将其视为可变更的 Shell 执行面。拒绝 write、edit、apply_patch 或 HTTP 文件系统写入工具并不会使 Shell 执行变为只读。
• 不要与不受信任的调用方共享 Gateway bearer 凭据。如果需要跨信任边界隔离，请运行独立的 Gateway（理想情况下位于不同的操作系统用户/主机上）。

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

cron、gateway 和 nodes 也仅限所有者：即使不在此默认拒绝列表中，非所有者调用方也无法在此接口上调用它们。

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

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      allow: ["gateway"],
    },
  },
}

gateway.tools.allow 是暴露覆盖，而不是权限范围升级。在携带身份的 HTTP 模式下，即使列在 gateway.tools.allow 中，没有所有者/管理员身份（operator.admin）的调用方仍无法使用 cron、gateway 和 nodes。共享密钥 bearer 认证仍遵循上述完整的可信操作员规则。

为了帮助组策略解析上下文，你可以可选地设置：

• x-openclaw-message-channel: <channel>（示例：slack、telegram）
• x-openclaw-account-id: <accountId>（存在多个账户时）
• x-openclaw-message-to: <target>（消息工具策略的投递目标）
• x-openclaw-thread-id: <threadId>（消息工具策略的线程上下文）

响应¶

示例¶

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

相关¶

• Gateway 协议
• 工具和插件