#How to REST API Endpoints

1 messages · Page 1 of 1 (latest)

chilly hillBOT
#

OpenClaw doesn’t run a separate “REST API server” process — it’s the Gateway. The Gateway multiplexes WebSocket RPC + HTTP endpoints + Control UI on the same port (default 18789).

1) Start the Gateway (this is what exposes the APIs)

openclaw gateway
# or explicitly:
openclaw gateway --port 18789

If you want to reach it from another machine, don’t bind it to the public internet—use Tailscale/SSH:

  • Tailscale Serve: openclaw gateway --tailscale serve
  • Tailnet bind (no HTTPS): openclaw gateway --bind tailnet --token "<token>"

Docs: https://docs.openclaw.ai/cli/gateway

2) HTTP: /tools/invoke (always enabled)

This is the “REST-ish” automation endpoint you’re looking for:

#
  • POST http://<host>:18789/tools/invoke
  • Auth: Authorization: Bearer <gateway-token>

Example (lists sessions via the sessions_list tool):

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"sessions_list","args":{}}'

Docs: https://docs.openclaw.ai/gateway/tools-invoke-http-api

Important nuance about /sessions and /skills

There usually isn’t a nice GET /sessions or GET /skills REST endpoint.

Instead you have two options:

#
  • Use /tools/invoke to call tool-shaped things (like sessions_list, sessions_history, etc.)
  • Use the Gateway WebSocket RPC for control-plane methods (sessions/skills/config/etc.)

3) WebSocket RPC (for “/sessions”, “/skills”-type orchestration)

Sessions + skills live primarily as RPC methods (not REST paths), e.g.:

  • sessions.list
  • skills.status

You can test these without writing a WS client by using:

openclaw gateway call sessions.list --params '{}' --json
openclaw gateway call skills.status --params '{}' --json

4) “API key” = the Gateway auth token (don’t paste it in Discord)

The “API key” you want is the Gateway auth token (or password), from:

  • gateway.auth.token (token mode), or
#
  • OPENCLAW_GATEWAY_TOKEN env var

Get it on the gateway host:

openclaw config get gateway.auth.token

If you don’t have one yet:

openclaw doctor --generate-gateway-token

FAQ section (also covers remote access): https://docs.openclaw.ai/help/faq#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote

If you paste the output of openclaw --version + whether you’re calling this locally or from another machine, I can tell you the safest “bind/auth” combo for your setup.

primal nacelle
#

2026.2.18 i run it in Docker with Clawdock and Tailscale give me exact lines to put in Terminal

chilly hillBOT
#

In the Docker + ClawDock setup, the “API server” is the Gateway container. It exposes HTTP on port 18789 (same port as the dashboard).

1) Start it + make sure the gateway token is set (ClawDock)

Run these on the host:

clawdock-start
clawdock-fix-token   # run once (or anytime you suspect token mismatch)

2) “API key” (gateway token)

The “API key” you want for /tools/invoke is the Gateway auth token.

TOKEN="$(clawdock-token)"
echo "$TOKEN"
#

3) Call POST /tools/invoke (REST)

Example: list sessions (this is the equivalent of “/sessions”, via the sessions_list tool):

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool":"sessions_list","args":{}}'

You can invoke any allowed tool the same way (policy still applies).

4) About /skills and /sessions endpoints

OpenClaw does not expose GET /skills or GET /sessions as simple REST endpoints.

  • Sessions: use /tools/invoke + sessions_list / sessions_history (as above).
  • Skills: use Gateway RPC (WebSocket) or the CLI container, e.g.:
primal nacelle
#

I’m trying to connect OpenClaw to an external dashboard/backend (like APCC or openclaw-mission-control).
My Gateway only runs as WebSocket/CLI, and does not provide any REST API endpoints (e.g. /tools/invoke, /skills, /sessions).
Is there a way to run OpenClaw as a REST API gateway (e.g. with a backend service, Docker image, or special mode) so I can automate agent tasks and skill calls via HTTP?
If not: Is there a roadmap or any workaround for REST API support?

chilly hillBOT
#

OpenClaw already is an HTTP gateway — but it’s not a “REST admin API” with nice resources like GET /sessions or GET /skills.

What you can do today (HTTP)

1) POST /tools/invoke (always enabled)

This is the main “HTTP automation” endpoint:

  • POST http://<gateway-host>:18789/tools/invoke
  • Auth: Authorization: Bearer <gateway.auth.token>

Docs: https://docs.openclaw.ai/gateway/tools-invoke-http-api

Important: there is no separate “API key” for this — it’s the Gateway token:

  • openclaw config get gateway.auth.token
  • (ClawDock) clawdock-token

2) Optional OpenAI-/OpenResponses-compatible HTTP endpoints (agent runs over HTTP)

#

If your external dashboard/backend can talk “OpenAI-style”, OpenClaw can expose:

These run a normal agent turn over HTTP (so they’re often the easiest way to “orchestrate agent tasks via HTTP”).

What you can’t do as simple REST routes (today)

There isn’t a built-in REST surface like:

  • GET /sessions
  • GET /skills
#

Those live primarily on the Gateway WebSocket JSON-RPC API, as methods like:

  • sessions.list
  • skills.status

So dashboards like “mission-control” typically connect to the Gateway via WebSocket RPC, not REST.

Workarounds (if you must have REST)

  1. Use /tools/invoke for anything that maps cleanly to a tool (e.g. sessions_list, sessions_history, etc.).
  2. For skills/sessions/control-plane things: write a tiny adapter service:
    • REST in → WebSocket JSON-RPC out (to the OpenClaw Gateway)
  3. Or, if your dashboard supports it, use /v1/responses / /v1/chat/completions instead of inventing new endpoints.
#

“It doesn’t provide /tools/invoke” — quick sanity checks

Most commonly it’s one of these:

  • You’re hitting the wrong host/port (18789 is default)
  • You can reach the UI via Tailscale Serve identity headers, but HTTP endpoints still require token/password
  • You’re missing the Authorization: Bearer … header, so you see 401 and assume it’s “not there”

If you run:

curl -i http://127.0.0.1:18789/tools/invoke

you should get 401 (no auth) or 405 (wrong method), which confirms the route exists.

Roadmap?

I can’t promise timelines, but if you need first-class REST resources for /sessions + /skills, that’s a legit feature request—best place is a GitHub issue with your dashboard requirements + endpoints you need:
https://github.com/openclaw/openclaw/issues