> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools invoke API

OpenClaw's Gateway exposes an 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 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/password for this endpoint should be treated like an owner/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/private ingress only; do not expose it directly to the public internet.

Auth matrix:

| Auth mode                                                                               | Behavior                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`. Treats direct tool invokes as owner-sender turns. |
| Trusted identity-bearing HTTP (trusted proxy auth, or `mode="none"` on private ingress) | Authenticates an outer trusted identity or deployment boundary. Honors `x-openclaw-scopes` when present. Falls back to the normal operator default scope set when the header is absent. Only loses owner semantics when the caller explicitly narrows scopes and omits `operator.admin`.                               |

## Request body

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 + 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/hosts).

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

| Tool             | Reason                                                    |
| ---------------- | --------------------------------------------------------- |
| `exec`           | Direct command execution (RCE surface)                    |
| `spawn`          | Arbitrary child process creation (RCE surface)            |
| `shell`          | Shell command execution (RCE surface)                     |
| `fs_write`       | Arbitrary file mutation on the host                       |
| `fs_delete`      | Arbitrary file deletion on the host                       |
| `fs_move`        | Arbitrary file move/rename on the host                    |
| `apply_patch`    | Patch application can rewrite arbitrary files             |
| `sessions_spawn` | Session orchestration; spawning agents remotely is RCE    |
| `sessions_send`  | Cross-session message injection                           |
| `cron`           | Persistent automation control plane                       |
| `gateway`        | Gateway control plane; prevents reconfiguration via HTTP  |
| `nodes`          | Node command relay can reach `system.run` on paired hosts |

`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`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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/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

| Status | Meaning                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------- |
| `200`  | `{ ok: true, result }`                                                                         |
| `400`  | `{ ok: false, error: { type, message } }` (invalid request or tool input error)                |
| `401`  | Unauthorized                                                                                   |
| `403`  | `{ ok: false, error: { type, message, requiresApproval? } }` (tool call blocked by policy)     |
| `404`  | Tool not available (not found or not allowlisted)                                              |
| `405`  | Method not allowed                                                                             |
| `408`  | Request body read timed out                                                                    |
| `413`  | Request body exceeded the max payload size                                                     |
| `429`  | Auth rate-limited (`Retry-After` set)                                                          |
| `500`  | `{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message) |

## Example

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/gateway/protocol)
* [Tools and plugins](/tools)