Tools invoke API

Tools Invoke (HTTP)

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

surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway.

• text

  Copy

  POST /tools/invoke
• Same port as the Gateway (WS + HTTP multiplex):
  text

  Copy

  http://<gateway-host>:<port>/tools/invoke

Default max payload size is 2 MB.

Authentication

Uses the Gateway auth configuration.

Common HTTP auth paths:

• shared-secret auth (
  text

  Copy

  gateway.auth.mode="token"
  or
  text

  Copy

  "password"
  ):
  text

  Copy

  Authorization: Bearer <token-or-password>
• trusted identity-bearing HTTP auth (
  text

  Copy

  gateway.auth.mode="trusted-proxy"
  ): route through the configured identity-aware proxy and let it inject the required identity headers
• private-ingress open auth (
  text

  Copy

  gateway.auth.mode="none"
  ): no auth header required

Notes:

• When
  text

  Copy

  gateway.auth.mode="token"
  , use
  text

  Copy

  gateway.auth.token
  (or
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  ).
• When
  text

  Copy

  gateway.auth.mode="password"
  , use
  text

  Copy

  gateway.auth.password
  (or
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  ).
• When
  text

  Copy

  gateway.auth.mode="trusted-proxy"
  , the HTTP request must come from a configured trusted proxy source; same-host loopback proxies require explicit
  text

  Copy

  gateway.auth.trustedProxy.allowLoopback = true
  .
• If
  text

  Copy

  gateway.auth.rateLimit
  is configured and too many auth failures occur, the endpoint returns
  text

  Copy

  429
  with
  text

  Copy

  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/password for this endpoint should be treated like an owner/operator credential.
• For shared-secret auth modes (
  text

  Copy

  token
  and
  text

  Copy

  password
  ), the endpoint restores the normal full operator defaults even if the caller sends a narrower
  text

  Copy

  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
  text

  Copy

  gateway.auth.mode="none"
  on a private ingress) honor
  text

  Copy

  x-openclaw-scopes
  when present and otherwise fall back to the normal operator default scope set.
• Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.

Auth matrix:

• text

  Copy

  gateway.auth.mode="token"
  or
  text

  Copy

  "password"
  +
  text

  Copy

  Authorization: Bearer ...
  • proves possession of the shared gateway operator secret
  • ignores narrower
    text

    Copy

    x-openclaw-scopes
  • restores the full default operator scope set:
    text

    Copy

    operator.admin
    ,
    text

    Copy

    operator.approvals
    ,
    text

    Copy

    operator.pairing
    ,
    text

    Copy

    operator.read
    ,
    text

    Copy

    operator.talk.secrets
    ,
    text

    Copy

    operator.write
  • treats direct tool invokes on this endpoint as owner-sender turns
• trusted identity-bearing HTTP modes (for example trusted proxy auth, or
  text

  Copy

  gateway.auth.mode="none"
  on private ingress)
  • authenticate some outer trusted identity or deployment boundary
  • honor
    text

    Copy

    x-openclaw-scopes
    when the header is present
  • fall back to the normal operator default scope set when the header is absent
  • only lose owner semantics when the caller explicitly narrows scopes and omits
    text

    Copy

    operator.admin

Request body

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

Fields:

• text

  Copy

  tool
  (string, required): tool name to invoke.
• text

  Copy

  action
  (string, optional): mapped into args if the tool schema supports
  text

  Copy

  action
  and the args payload omitted it.
• text

  Copy

  args
  (object, optional): tool-specific arguments.
• text

  Copy

  sessionKey
  (string, optional): target session key. If omitted or
  text

  Copy

  "main"
  , the Gateway uses the configured main session key (honors
  text

  Copy

  session.mainKey
  and default agent, or
  text

  Copy

  global
  in global scope).
• text

  Copy

  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:

• text

  Copy

  tools.profile
  /
  text

  Copy

  tools.byProvider.profile
• text

  Copy

  tools.allow
  /
  text

  Copy

  tools.byProvider.allow
• text

  Copy

  agents.<id>.tools.allow
  /
  text

  Copy

  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 + tool policy,
  text

  Copy

  /tools/invoke
  does not add an extra per-call approval prompt.
• Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (and ideally separate OS users/hosts).

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

• text

  Copy

  exec
  — direct command execution (RCE surface)
• text

  Copy

  spawn
  — arbitrary child process creation (RCE surface)
• text

  Copy

  shell
  — shell command execution (RCE surface)
• text

  Copy

  fs_write
  — arbitrary file mutation on the host
• text

  Copy

  fs_delete
  — arbitrary file deletion on the host
• text

  Copy

  fs_move
  — arbitrary file move/rename on the host
• text

  Copy

  apply_patch
  — patch application can rewrite arbitrary files
• text

  Copy

  sessions_spawn
  — session orchestration; spawning agents remotely is RCE
• text

  Copy

  sessions_send
  — cross-session message injection
• text

  Copy

  cron
  — persistent automation control plane
• text

  Copy

  gateway
  — gateway control plane; prevents reconfiguration via HTTP
• text

  Copy

  nodes
  — node command relay can reach system.run on paired hosts
• text

  Copy

  whatsapp_login
  — interactive setup requiring terminal QR scan; hangs on HTTP

You can customize this deny list via

:

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

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

• text

  Copy

  x-openclaw-message-channel: <channel>
  (example:
  text

  Copy

  slack
  ,
  text

  Copy

  telegram
  )
• text

  Copy

  x-openclaw-account-id: <accountId>
  (when multiple accounts exist)

Responses

• text

  Copy

  200
  →
  text

  Copy

  { ok: true, result }
• text

  Copy

  400
  →
  text

  Copy

  { ok: false, error: { type, message } }
  (invalid request or tool input error)
• text

  Copy

  401
  → unauthorized
• text

  Copy

  429
  → auth rate-limited (
  text

  Copy

  Retry-After
  set)
• text

  Copy

  404
  → tool not available (not found or not allowlisted)
• text

  Copy

  405
  → method not allowed
• text

  Copy

  500
  →
  text

  Copy

  { ok: false, error: { type, message } }
  (unexpected tool execution error; sanitized message)

Example

bash
Copy
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