工具调用（HTTP）

Moltbot 网关暴露一个简单的 HTTP 接口，用于直接调用单个工具。该接口始终启用，但受网关认证和工具策略控制。

• POST /tools/invoke
• 与网关同端口（WebSocket + HTTP 复用）：http://<gateway-host>:<port>/tools/invoke

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

认证

使用网关的认证配置。发送 Bearer token：

• Authorization: Bearer <token>

说明：

• 当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 CLAWDBOT_GATEWAY_TOKEN）。
• 当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 CLAWDBOT_GATEWAY_PASSWORD）。

请求体

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

字段说明：

• tool（字符串，必填）：要调用的工具名。
• action（字符串，可选）：若工具 schema 支持 action 且 args 中未提供，会映射到 args。
• args（对象，可选）：工具专用参数。
• sessionKey（字符串，可选）：目标会话键。省略或为 "main" 时，网关使用配置的主会话键（遵循 session.mainKey 与默认 agent，或全局作用域下的 global）。
• dryRun（布尔，可选）：保留给后续使用；当前忽略。

策略与路由行为

工具可用性经过与网关 agent 相同的策略链过滤：

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

若策略不允许某工具，接口返回 404。为便于群组策略解析上下文，可选择性设置：

• x-moltbot-message-channel: <channel>（例如 slack、telegram）
• x-moltbot-account-id: <accountId>（存在多账号时）

响应

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } }（请求无效或工具报错）
• 401 → 未认证
• 404 → 工具不可用（未找到或未放行）
• 405 → 方法不允许

示例

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