工具调用 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 头部证据都会让请求继续走 trusted-proxy 路径。
• 如果配置了 gateway.auth.rateLimit 且发生了过多认证失败，端点将返回带有 Retry-After 的 429。

​

安全边界（重要）

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

​

请求体

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

• tool / name（字符串，必填）：要调用的工具名称。如果两者都提供，则以 name 为准。
• action（字符串，可选）：如果工具 schema 支持 action 属性，并且 args 中尚未设置该属性，则合并到 args.action 中。
• args（对象，可选）：工具特定参数。
• sessionKey（字符串，可选）：目标会话键。如果省略或为 "main"，Gateway 将使用已配置的主会话键（遵循 session.mainKey 和默认 agent，或在全局会话作用域中使用 global）。
• agentId（字符串，可选）：为该 agent 解析会话键。如果它与一个已显式指定、且已映射到不同 agent 的 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 bearer 凭据分享给不受信任的调用方。如果你需要在不同信任边界之间隔离，请运行独立的 gateways（最好使用不同的 OS 用户/主机）。

{
  gateway: {
    tools: {
      // 通过 HTTP /tools/invoke 额外阻止的工具
      deny: ["browser"],
      // 从默认拒绝列表中移除工具，供 owner/admin 调用
      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": {}
  }'

​

相关内容

• 网关协议
• 工具和插件