Invoke a Tool Directly via Gateway HTTP Endpoint

OpenClaw's Gateway provides an HTTP endpoint for directly invoking a single tool. This endpoint is always active and relies on Gateway authentication along with tool policy. Similar to the OpenAI compatible /v1/* interface, shared secret bearer authentication is considered trusted operator access for the entire gateway.

• POST /tools/invoke
• Same port as the Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke
• Default max request body size: 2 MB

Authentication

Uses the Gateway auth configuration.

Common HTTP auth paths:

• shared secret auth (gateway.auth.mode="token" or "password"): Authorization: Bearer <token-or-password>
• trusted identity bearing HTTP auth (gateway.auth.mode="trusted-proxy"): route through the configured identity aware proxy and let it inject the required identity headers
• private ingress open auth (gateway.auth.mode="none"): no auth header required

Notes:

• mode="token" uses gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN).
• mode="password" uses gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" requires the HTTP request to come from a configured trusted proxy source; same host loopback proxies require explicit gateway.auth.trustedProxy.allowLoopback = true.
• Internal same host callers that bypass the proxy can use gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD as a local direct fallback. Any Forwarded, X-Forwarded-*, or X-Real-IP header evidence keeps the request on the trusted proxy path instead.
• If gateway.auth.rateLimit is configured and too many auth failures occur, the endpoint returns 429 with Retry-After.

Security boundary (important)

Treat this endpoint as a full operator access surface for the gateway instance.

• HTTP bearer auth here is not a narrow per user scope model.
• A valid Gateway token or password for this endpoint should be treated like an owner or operator credential.
• For shared secret auth modes (token and password), the endpoint restores the normal full operator defaults even if the caller sends a narrower x-openclaw-scopes header.
• Shared secret auth also treats direct tool invokes on this endpoint as owner sender turns.
• Trusted identity bearing HTTP modes (trusted proxy auth, or gateway.auth.mode="none" on a private ingress) honor x-openclaw-scopes when present and otherwise fall back to the normal operator default scope set.
• Keep this endpoint on loopback, tailnet, or private ingress only; do not expose it directly to the public internet.

Auth matrix:

Request body

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

Fields:

• tool / name (string, required): tool name to invoke. name takes precedence if both are sent.
• action (string, optional): merged into args.action if the tool schema supports an action property and args did not already set one.
• args (object, optional): tool specific arguments.
• sessionKey (string, optional): target session key. If omitted or "main", the Gateway uses the configured main session key (honors session.mainKey and the default agent, or global in global session scope).
• agentId (string, optional): resolves the session key for that agent. Errors with 400 if it conflicts with an explicit sessionKey that already maps to a different agent.
• idempotencyKey (string, optional): used to derive a stable tool call id for the invocation.
• dryRun (boolean, optional): reserved for future use; currently ignored.

Policy + routing behavior

Tool availability is filtered through the same policy chain used by Gateway agents:

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• group policies (if the session key maps to a group or channel)
• subagent policy (when invoking with a subagent session key)

If a tool is not allowed by policy, the endpoint returns 404.

Important boundary notes:

• Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth plus tool policy, /tools/invoke does not add an extra per call approval prompt.
• If exec is reachable here, treat it as a mutating shell surface. Denying write, edit, apply_patch, or HTTP filesystem write tools does not make shell execution read only.
• Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (ideally on separate OS users or hosts).

Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):

cron, gateway, and nodes are also owner only: even outside this default deny list, non owner callers cannot invoke them on this surface.

Customize the general deny list via gateway.tools:

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      allow: ["gateway"],
    },
  },
}

gateway.tools.allow is an exposure override, not a scope upgrade. In identity bearing HTTP modes, cron, gateway, and nodes remain unavailable to callers without owner or admin identity (operator.admin) even when listed in gateway.tools.allow. Shared secret bearer auth still follows the full trusted operator rule above.

To help group policies resolve context, you can optionally set:

• x-openclaw-message-channel: <channel> (example: slack, telegram)
• x-openclaw-account-id: <accountId> (when multiple accounts exist)
• x-openclaw-message-to: <target> (delivery target for message tool policy)
• x-openclaw-thread-id: <threadId> (thread context for message tool policy)

Responses

Example

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

Related

• Gateway protocol
• Tools and plugins