工具调用 API

• POST /tools/invoke
• 与 Gateway 网关使用相同端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/tools/invoke
• 默认最大请求正文大小：2 MB

​

身份验证

• 共享密钥身份验证（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 承载令牌身份验证并非范围狭窄的按用户权限范围模型。
• 此端点的有效 Gateway 网关令牌/密码应被视为所有者/操作员凭据。
• 对于共享密钥身份验证模式（token 和 password），即使调用方发送了权限范围更窄的 x-openclaw-scopes 标头，该端点也会恢复常规的完整操作员默认权限。
• 共享密钥身份验证还会将此端点上的直接工具调用视为所有者发送方轮次。
• 携带可信身份的 HTTP 模式（可信代理身份验证，或私有入口上的 gateway.auth.mode="none"）会在存在 x-openclaw-scopes 时遵循该标头，否则回退到常规操作员默认权限范围集。
• 仅在回环网络、tailnet 或私有入口上提供此端点；不要将其直接暴露到公共互联网。

​

请求正文

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

• tool / name（字符串，必填）：要调用的工具名称。如果同时发送两者，则 name 优先。
• action（字符串，可选）：如果工具架构支持 action 属性，且 args 尚未设置该属性，则将其合并到 args.action 中。
• args（对象，可选）：工具专用参数。
• sessionKey（字符串，可选）：目标会话键。如果省略或为 "main"，Gateway 网关将使用已配置的主会话键（遵循 session.mainKey 和默认智能体；在全局会话范围中则使用 global）。
• agentId（字符串，可选）：为该智能体解析会话键。如果它与已显式映射到其他智能体的 sessionKey 冲突，则返回 400 错误。
• idempotencyKey（字符串，可选）：用于为此次调用派生稳定的工具调用 ID。
• dryRun（布尔值，可选）：保留供将来使用；目前会被忽略。

​

策略和路由行为

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• 群组策略（如果会话键映射到群组或渠道）
• 子智能体策略（使用子智能体会话键调用时）

• Exec 审批是操作员防护措施，而不是此 HTTP 端点的独立授权边界。如果可通过 Gateway 网关身份验证 + 工具策略访问某个工具，/tools/invoke 不会额外添加按调用审批提示。
• 如果可通过此处访问 exec，应将其视为可修改内容的 Shell 接口。拒绝 write、edit、apply_patch 或 HTTP 文件系统写入工具，并不会使 Shell 执行变为只读。
• 不要与不可信调用方共享 Gateway 网关承载令牌凭据。如果需要跨信任边界进行隔离，请运行独立的 Gateway 网关（最好使用独立的操作系统用户/主机）。

{
  gateway: {
    tools: {
      // 通过 HTTP /tools/invoke 额外屏蔽的工具
      deny: ["browser"],
      // 从所有者/管理员调用方的默认拒绝列表中移除工具
      allow: ["gateway"],
    },
  },
}

• 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 网关协议
• 工具和插件