{
  "title": "Tools Invoke (HTTP)",
  "content": "OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.\n\n* `POST /tools/invoke`\n* Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/tools/invoke`\n\nDefault max payload size is 2 MB.\n\nUses the Gateway auth configuration. Send a bearer token:\n\n* `Authorization: Bearer <token>`\n\n* When `gateway.auth.mode=\"token\"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).\n* When `gateway.auth.mode=\"password\"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).\n\n* `tool` (string, required): tool name to invoke.\n* `action` (string, optional): mapped into args if the tool schema supports `action` and the args payload omitted it.\n* `args` (object, optional): tool-specific arguments.\n* `sessionKey` (string, optional): target session key. If omitted or `\"main\"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).\n* `dryRun` (boolean, optional): reserved for future use; currently ignored.\n\n## Policy + routing behavior\n\nTool availability is filtered through the same policy chain used by Gateway agents:\n\n* `tools.profile` / `tools.byProvider.profile`\n* `tools.allow` / `tools.byProvider.allow`\n* `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`\n* group policies (if the session key maps to a group or channel)\n* subagent policy (when invoking with a subagent session key)\n\nIf a tool is not allowed by policy, the endpoint returns **404**.\n\nTo help group policies resolve context, you can optionally set:\n\n* `x-openclaw-message-channel: <channel>` (example: `slack`, `telegram`)\n* `x-openclaw-account-id: <accountId>` (when multiple accounts exist)\n\n* `200` → `{ ok: true, result }`\n* `400` → `{ ok: false, error: { type, message } }` (invalid request or tool error)\n* `401` → unauthorized\n* `404` → tool not available (not found or not allowlisted)\n* `405` → method not allowed",
  "code_samples": [
    {
      "code": "Fields:\n\n* `tool` (string, required): tool name to invoke.\n* `action` (string, optional): mapped into args if the tool schema supports `action` and the args payload omitted it.\n* `args` (object, optional): tool-specific arguments.\n* `sessionKey` (string, optional): target session key. If omitted or `\"main\"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).\n* `dryRun` (boolean, optional): reserved for future use; currently ignored.\n\n## Policy + routing behavior\n\nTool availability is filtered through the same policy chain used by Gateway agents:\n\n* `tools.profile` / `tools.byProvider.profile`\n* `tools.allow` / `tools.byProvider.allow`\n* `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`\n* group policies (if the session key maps to a group or channel)\n* subagent policy (when invoking with a subagent session key)\n\nIf a tool is not allowed by policy, the endpoint returns **404**.\n\nTo help group policies resolve context, you can optionally set:\n\n* `x-openclaw-message-channel: <channel>` (example: `slack`, `telegram`)\n* `x-openclaw-account-id: <accountId>` (when multiple accounts exist)\n\n## Responses\n\n* `200` → `{ ok: true, result }`\n* `400` → `{ ok: false, error: { type, message } }` (invalid request or tool error)\n* `401` → unauthorized\n* `404` → tool not available (not found or not allowlisted)\n* `405` → method not allowed\n\n## Example",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Authentication",
      "id": "authentication"
    },
    {
      "level": "h2",
      "text": "Request body",
      "id": "request-body"
    },
    {
      "level": "h2",
      "text": "Policy + routing behavior",
      "id": "policy-+-routing-behavior"
    },
    {
      "level": "h2",
      "text": "Responses",
      "id": "responses"
    },
    {
      "level": "h2",
      "text": "Example",
      "id": "example"
    }
  ],
  "url": "llms-txt#tools-invoke-(http)",
  "links": []
}