Tools Invoke（HTTP API）

OpenClaw 的 Gateway 提供了一个简单的 HTTP 端点，可以直接调用单个工具。该端点始终开启，使用 Gateway 认证和工具策略，持有 Gateway Bearer 认证的调用方在该 Gateway 范围内被视为受信任的运营者。

• POST /tools/invoke
• 与 Gateway 共用同一端口（WS + HTTP 多路复用）：http://<gateway-host>:<port>/tools/invoke

默认最大请求体大小为 2 MB。

小龙虾养好之后，这个接口就是你跟它"发号施令"的快速通道——无需打开整个对话，直接命令它执行工具。

认证

使用 Gateway 认证配置，发送 Bearer token：

• Authorization: Bearer <token>

说明：

• 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 如果配置了 gateway.auth.rateLimit 且认证失败次数过多，端点返回 429，并附带 Retry-After。
• 请将此凭据视为该 Gateway 的完整运营者密钥，而非针对 /tools/invoke 的范围受限 API token。

请求体

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

字段说明：

• tool（字符串，必填）：要调用的工具名称。
• action（字符串，可选）：如果工具 schema 支持 action 且 args 中未包含，则映射到 args。
• args（对象，可选）：工具特定参数。
• sessionKey（字符串，可选）：目标会话 key。省略或为 "main" 时，Gateway 使用配置的主会话 key（遵循 session.mainKey 和默认 agent，或全局作用域中的 global）。
• dryRun（布尔值，可选）：保留字段，当前忽略。

策略与路由行为

工具可用性通过与 Gateway agent 相同的策略链过滤：

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• 组策略（当会话 key 对应某个组或频道时）
• 子 agent 策略（使用子 agent 会话 key 调用时）

如果工具未被策略允许，端点返回 404。

重要边界说明：

• POST /tools/invoke 与其他 Gateway HTTP API（如 /v1/chat/completions、/v1/responses、/api/channels/*）属于同一个受信任运营者范围。
• Exec 审批是运营者层面的保护机制，并非此 HTTP 端点的独立授权边界。如果工具通过 Gateway 认证 + 工具策略可以访问，/tools/invoke 不会增加额外的逐次审批提示。
• 请勿将 Gateway Bearer 凭据分享给不受信任的调用方。如需跨信任边界隔离，请运行独立的 Gateway（最好使用独立的 OS 用户/主机）。

Gateway HTTP 默认还有一个硬拒绝列表（即使会话策略允许，也会被拒绝）：

• cron
• sessions_spawn
• sessions_send
• gateway
• whatsapp_login

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

{
  gateway: {
    tools: {
      // 通过 HTTP /tools/invoke 额外屏蔽的工具
      deny: ["browser"],
      // 从默认拒绝列表中移除工具
      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 YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'