Gateway Tools Invoke HTTP API

Gateway 提供 HTTP 端点直接调用单个工具，始终启用，使用 Gateway 认证 + 工具策略。

• POST /tools/invoke（同 Gateway 端口）
• 默认最大 payload：2 MB

认证

与 gateway-openai-http-api 相同：

• token/password 模式：Authorization: Bearer <token-or-password>
• trusted-proxy 模式：通过身份感知代理
• none 模式：无需 auth

共享密钥认证恢复完整默认 operator scope，不要暴露到公网。

请求体

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

• tool（必填）：工具名称
• action（可选）：映射到 args 的 action 字段
• args（可选）：工具特定参数
• sessionKey（可选）：目标会话 key，默认 "main"

策略与路由

工具可用性通过与 Gateway agent 相同的策略链过滤：tools.profile、tools.allow、agents.<id>.tools.allow 等。工具不在白名单时返回 404。

默认硬拒绝列表

以下工具即使策略允许也被拒绝（RCE/高风险）：

exec、spawn、shell、fs_write、fs_delete、fs_move、apply_patch、sessions_spawn、sessions_send、cron、gateway、nodes、whatsapp_login

可通过 gateway.tools.deny / gateway.tools.allow 自定义：

{ gateway: { tools: { deny: ["browser"], allow: ["gateway"] } } }

响应

• 200：{ ok: true, result }
• 400：无效请求或工具输入错误
• 401：未授权
• 404：工具不可用
• 429：认证限流（含 Retry-After）
• 500：工具执行错误

示例

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-protocol
• gateway-openai-http-api