Invoke OpenClaw Tools via HTTP: API Integration Guide

Ever found yourself wanting to trigger a specific tool without going through a full LLM chat loop? Sometimes you just want to hit an endpoint, pass some arguments, and get a result back immediately. OpenClaw’s Gateway makes this easy with a dedicated HTTP surface for direct tool invocation.

OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible /v1/* surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway.

• POST /tools/invoke
• Same port as the Gateway (WS + HTTP multiplex): http://<gateway-host>:<port>/tools/invoke

Default max payload size is 2 MB.

Authentication

The endpoint uses your Gateway auth configuration. You just need to send a bearer token:

• Authorization: Bearer <token>

Keep these points in mind:

• When gateway.auth.mode="token", use gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN).
• When gateway.auth.mode="password", use gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
• If gateway.auth.rateLimit is configured and too many auth failures occur, the endpoint returns 429 with Retry-After.

Security boundary (important)

You should 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 (for example trusted proxy auth or gateway.auth.mode="none" on a private ingress) still honor the declared operator scopes on the request.
• Keep this endpoint on loopback, tailnet, or private ingress only. Do not expose it directly to the public internet.

Auth matrix:

• gateway.auth.mode="token" or "password" + Authorization: Bearer ...
  • proves possession of the shared gateway operator secret
  • ignores narrower x-openclaw-scopes
  • restores the full default operator scope set
  • treats direct tool invokes on this endpoint as owner-sender turns
• trusted identity-bearing HTTP modes (for example trusted proxy auth, or gateway.auth.mode="none" on private ingress)
  • authenticate some outer trusted identity or deployment boundary
  • honor the declared x-openclaw-scopes header
  • only get owner semantics when operator.admin is actually present in those declared scopes

Request body

When you make a request, use this JSON

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

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

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