openclaw-control-mcp

The OpenClaw control plane MCP server. Operate the gateway's full management surface from Claude Code, Cursor, or any MCP client — list and trigger crons, inspect sessions, configure agents and channels, manage skills and secrets, drive the doctor memory plane, pair devices, approve exec/plugin calls. 143 typed tools covering every JSON-RPC method the gateway publishes.

Different from the upstream openclaw-mcp, which only wraps /v1/chat/completions. This one talks the JSON-RPC protocol used by the OpenClaw Control panel — so you can operate the gateway itself (its crons, sessions, agents, channels, skills, secrets, …), not just chat through it.

Without vs with

Without openclaw-control-mcp — you bounce between the Control panel UI, your terminal, and Claude Code. "List my crons" means opening the SPA. "Tail this agent session" means staying in the panel and refreshing. "Why did this skill fail?" means hunting through logs.tail manually. The assistant can chat through the gateway but it cannot operate it.

With openclaw-control-mcp — the same assistant queries openclaw_cron_list, follows up with openclaw_sessions_tail to watch a turn in flight, asks openclaw_skills_status for diagnostic data, rotates a secret via openclaw_secrets_set, and approves a stuck openclaw_exec_approval — without you ever leaving the chat. The Control panel becomes an audit interface, not a daily-driver.

Quickstart

# Claude Code — registers a stdio server under the default config
claude mcp add openclaw-control -- npx -y openclaw-control-mcp

One-click install from supported clients:

On first start the wrapper generates an Ed25519 device identity and surfaces a pairing request id. Approve it once in the OpenClaw Control panel, the gateway issues a device token, and every subsequent call uses it transparently. Full pairing flow below.

Status

0.8.0 — published on npm, indexed on the official MCP Registry as io.github.smurfy92/openclaw-control-mcp. Multi-instance gateway configs, file-based secrets (.env + store.json mode 0600, no OS keychain access — see ADR-006), 143 typed tools across the 128 published JSON-RPC methods, plus two escape hatches: openclaw_introspect enumerates every method/event the gateway publishes in its hello-ok, and openclaw_call lets you reach any method that doesn't have a typed wrapper yet — so new gateway endpoints are reachable without waiting on a release.

The Ed25519 signed handshake is verified live against gateway 2026.4.12+. On first start, the wrapper generates a long-lived device identity, persists it under ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/store.json (mode 0600), signs the connect frame, and surfaces the resulting pairing request id so you can approve it once via the Control panel. After approval the gateway issues a device token (in hello-ok.auth.deviceToken) which is cached per-gateway and used on subsequent connects to grant scopes.

The wire format (frame types, field names, signing canonicalisation, scopes) was reverse-engineered from the minified Control panel bundle (/api-docs/assets/index-*.js) and cross-checked against openclaw/openclaw/scripts/dev/gateway-smoke.ts. It is not officially documented. Behaviour may change without notice if OpenClaw updates the gateway.

First-run / pairing flow

1. Start the wrapper (Claude Code does this automatically once registered in ~/.claude.json).
2. Ask Claude to run openclaw_device_status. The first call:
   • generates an Ed25519 keypair and persists it to disk,
   • opens a WS to the gateway,
   • sends a signed connect frame,
   • the gateway replies with PAIRING_REQUIRED and a requestId,
   • the tool returns { pendingPairing: { requestId }, nextStep: "approve in Control panel…" }.
3. Open the OpenClaw Control panel → Devices tab → approve the request whose id matches.
4. Ask Claude to run openclaw_device_status again. This time the gateway accepts the connect, returns auth.deviceToken in hello-ok, the wrapper caches it, and paired: true plus the granted scopes appear in the response.
5. From then on, scoped tools (openclaw_cron_list, _status, …) work normally.

Install

From npm (recommended)

claude mcp add openclaw-control -- npx -y openclaw-control-mcp

Restart Claude Code, then jump to Configuration.

From source (for contributors)

git clone https://github.com/smurfy92/openclaw-control-mcp.git
cd openclaw-control-mcp
npm install
npm run build
claude mcp add openclaw-control -- node "$(pwd)/dist/index.js"

Configuration

The wrapper requires the WebSocket URL of your OpenClaw gateway. The public Hostinger HTTPS hostname does not expose the WS endpoint — you need the URL the Control panel itself uses internally.

Find it from your browser:

1. Open the Control panel and log in.
2. In the DevTools console run:

   Object.entries(localStorage).find(([k]) => k.startsWith("openclaw.control.settings.v1"))?.[1]
   

3. Copy the gatewayUrl field (typically ws://127.0.0.1:18789, a Tailscale ws://100.x.y.z:18789, or a dedicated wss://… host).

Use with Claude Code

Recommended: register, then configure in chat

The slickest path — no ~/.claude.json editing, no env vars. After installing (npx or from source), in chat:

"Configure OpenClaw with gateway wss://your-gateway.example.com and token <your-token>"

Claude calls openclaw_setup({ gatewayUrl, gatewayToken }), the values get persisted to ~/.config/openclaw-control-mcp/store.json (mode 0600). The next call to openclaw_device_status triggers the WS handshake and pairing flow.

openclaw_setup_show reports the effective configuration, openclaw_setup_clear wipes the persisted config (without touching the device identity / token).

Alternative: env-var-driven

If you prefer env vars (they take precedence over the stored config), edit ~/.claude.json:

"openclaw-control": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "openclaw-control-mcp"],
  "env": {
    "OPENCLAW_GATEWAY_URL": "wss://your-gateway.example.com",
    "OPENCLAW_GATEWAY_TOKEN": "<your-token>",
    "OPENCLAW_TIMEOUT_MS": "30000"
  }
}

Restart Claude Code — openclaw_cron_list and friends will be available.

Secrets & the .env file

The server never touches your OS keychain — no security / secret-tool call, no permission prompt, nothing to approve. Since 0.8.0 secrets resolve from exactly two places, in this order:

#	Source	Notes
1	Real environment variables	Always win. OPENCLAW_GATEWAY_TOKEN=… npx -y openclaw-control-mcp is a valid one-shot override.
2	A .env file	Loaded into the environment at startup. Never overwrites a variable that is already set.
3	store.json (mode 0600)	What openclaw_setup and the pairing flow write. Plain JSON, in your config dir.

.env candidates, highest precedence first:

1. $OPENCLAW_ENV_FILE — explicit path
2. ./.env — the directory the server is started from
3. ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/.env

Copy .env.example, fill it in, then chmod 600 .env. The server warns on stderr if the file is readable by other users. The parser is deliberately minimal — KEY=value, export KEY=value, "quoted", '''raw''', # comments — with no variable interpolation, so a secret is never expanded or reinterpreted.

Want the server to never write a secret to disk? Put OPENCLAW_DEVICE_PRIVATE_KEY + OPENCLAW_DEVICE_TOKEN in the .env (get them from an already-paired install with npx tsx scripts/export-ci-secrets.ts). Env-supplied identity short-circuits the store entirely.

--health reports which .env files were loaded and which variables they supplied.

Upgrading from 0.5.0 – 0.7.0 (keychain removal)

Those versions kept secrets in the OS keychain and left blank fields in store.json. Run the one-shot import once, before your next session:

npx -y openclaw-control-mcp --migrate-from-keychain

It reads the keychain, writes the values into store.json (mode 0600), and prints the security delete-generic-password … / secret-tool clear … commands for the now-unused items — it never deletes anything from your keychain itself. Running it twice is a no-op. This is the only code path in the package that reads a keychain at all; it is dynamically imported behind that flag and never runs on normal startup.

If you'd rather not migrate, openclaw_device_repair wipes the orphaned device and the next connect re-pairs from scratch.

Environment variables

Variable	Required	Description
OPENCLAW_GATEWAY_URL	yes	WebSocket URL of the gateway (ws:// or wss://)
OPENCLAW_GATEWAY_TOKEN	recommended	Gateway login token
OPENCLAW_GATEWAY_PASSWORD	optional	Extra password (some gateway configs require it)
OPENCLAW_TIMEOUT_MS	optional	Connect / request timeout (default 30000)
OPENCLAW_DEBUG	optional	Set to 1 to log every WS frame to stderr
OPENCLAW_CONTROL_HOME	optional	Override the directory used to persist store.json (defaults to ${XDG_CONFIG_HOME:-~/.config}/openclaw-control-mcp/). The legacy OPENCLAW_CLAW_HOME is still read as a fallback.
OPENCLAW_ENV_FILE	optional	Explicit path to a .env file. Loaded before anything else reads the environment; takes precedence over ./.env and <configDir>/.env. See Secrets & the .env file.
OPENCLAW_HTTP	optional	Set to 1 to expose the MCP over Streamable HTTP at /mcp instead of stdio. Equivalent to passing --http.
OPENCLAW_HTTP_PORT	optional	HTTP port (default 3333). Equivalent to --http-port=N.
OPENCLAW_HTTP_HOST	optional	HTTP host (default 127.0.0.1). Equivalent to --http-host=H.
OPENCLAW_MOCK	optional	Set to 1 (or pass --mock) to swap the WebSocket gateway for an in-memory MockGateway. Lets you exercise the MCP without provisioning a real gateway — for CI, demos, or dry-runs. State is kept in-process and discarded on exit.

Multi-instance: per-call instance parameter

Every tool accepts an optional instance field so a single MCP can target several gateways without flipping the active default first:

// route this one call to the 'work' gateway, regardless of the active default
{ "name": "openclaw_cron_list", "arguments": { "instance": "work", "limit": 10 } }

Configure each gateway with openclaw_setup({ instance: "work", gatewayUrl, gatewayToken }), list them with openclaw_setup_list, switch the active default with openclaw_setup_select_default. When OPENCLAW_GATEWAY_URL is set in the env, it overrides everything (including a instance arg) — the env-var path always wins.

HTTP mode

For clients that don't speak stdio (Cursor, Continue, Cline, Zed, browser), run the MCP as a Streamable HTTP server:

# Loopback (default 127.0.0.1:3333), no bearer — fine for local trust
npx -y openclaw-control-mcp --http --http-port=3333

# Same, but with bearer auth on (recommended even on loopback)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

# Bound to a public interface — bearer is REQUIRED (server refuses to start without)
OPENCLAW_HTTP=1 OPENCLAW_HTTP_HOST=0.0.0.0 OPENCLAW_HTTP_PORT=3333 \
  OPENCLAW_HTTP_BEARER="$(openssl rand -hex 32)" \
  npx -y openclaw-control-mcp

Endpoint: POST/GET http://<host>:<port>/mcp (MCP Streamable HTTP, stateful — each client gets its own session id). Stdio remains the default; the HTTP server only starts when explicitly enabled.

Auth behaviour:

• OPENCLAW_HTTP_BEARER set → every /mcp request must include Authorization: Bearer <token>. Mismatched / missing tokens get 401 Unauthorized with a WWW-Authenticate: Bearer realm="openclaw-control-mcp" header. Comparison is constant-time.
• OPENCLAW_HTTP_BEARER unset + bound to loopback → starts with a stderr warning. Anyone with local shell access can invoke every tool.
• OPENCLAW_HTTP_BEARER unset + bound to a non-loopback host (0.0.0.0, public IP, etc.) → the server refuses to start. Public binding without auth is a takeover risk and not negotiable.

For long-lived deployments behind a reverse proxy, terminate TLS at the proxy (nginx, Caddy, Traefik) and forward to 127.0.0.1:3333/mcp — the bearer protects the proxy → MCP hop too.

Mock mode (no gateway required)

Set OPENCLAW_MOCK=1 (or pass --mock) to swap the WebSocket client for an in-memory mock. Useful for:

• CI — run tests / demos without a live gateway.
• Workflow rehearsals — dry-run a sequence of cron.add / cron.update / config.patch calls before pointing at prod.
• Onboarding — try the MCP without provisioning a gateway instance.

# stdio
OPENCLAW_MOCK=1 npx -y openclaw-control-mcp
# or HTTP
OPENCLAW_MOCK=1 OPENCLAW_HTTP=1 npx -y openclaw-control-mcp

State (cron jobs added, config patches, sessions) is kept in-process and discarded on exit. The mock seeds one cron job (sample-weekly) and one session so list calls return non-empty. Methods without a canned handler return { mock: true, ok: true } so nothing crashes — extend src/gateway/mock.ts to specialise additional methods.

Cron templates (no schedule syntax to remember)

Four wrappers on top of cron.add synthesize the wire format for the most common cases:

// every Friday at 09:00 Paris, send a weekly digest to a Telegram channel
{ "name": "openclaw_cron_add_weekly", "arguments": {
    "name": "weekly-digest", "dayOfWeek": "fri", "hour": 9, "minute": 0,
    "tz": "Europe/Paris", "message": "Compose the weekly digest …",
    "channel": "telegram", "to": "-1001234567890"
}}

// every day at 07:00 UTC
{ "name": "openclaw_cron_add_daily", "arguments": {
    "name": "morning-check", "hour": 7, "tz": "UTC", "message": "Run the morning checks."
}}

// every 15 minutes (clock-agnostic)
{ "name": "openclaw_cron_add_every", "arguments": {
    "name": "ping", "intervalMinutes": 15, "message": "ping the upstream"
}}

// one-shot reminder, auto-deletes after firing
{ "name": "openclaw_cron_add_once", "arguments": {
    "name": "remind-meeting", "at": "2026-12-25T09:00:00+01:00",
    "message": "Don't forget the holiday call."
}}

All four take the standard knobs: agentId?, model?, timeoutSeconds? (default 900), channel? + to?, deliveryMode? (announce | direct | none), instance?.

Tools

143 typed tools wrapping the 128 JSON-RPC methods the gateway publishes (and 2 standalone introspection tools). Run openclaw_introspect once paired to see the live list of methods + events on your specific gateway.

Introspection (no scopes required)

Tool	Notes
openclaw_introspect	Returns server version, your role/scopes, and the full methods[] / events[] list the gateway publishes in its hello-ok.
openclaw_call	Escape hatch — call any JSON-RPC method with arbitrary params. Useful when the gateway adds new methods between releases. Prefer typed wrappers when they exist.

Setup (no scopes required)

Tool	Notes
openclaw_setup	Persist { gatewayUrl, gatewayToken, gatewayPassword? } to local config.
openclaw_setup_show	Report effective config (env vs store), without printing tokens.
openclaw_setup_clear	Wipe persisted gateway config. Device identity + tokens are kept.

Device & pairing (device.pair.*, device.token.*)

openclaw_device_status / openclaw_device_pair_list / _pair_approve / _pair_reject / _pair_remove / openclaw_device_token_revoke / _token_rotate. Manages your local Ed25519 identity and the per-gateway tokens it's been issued.

Coverage by domain (require operator.read / operator.write / operator.admin)

Domain	Tools	JSON-RPC methods wrapped
cron	7	list status run runs add update remove
sessions	17	list preview create patch send abort reset delete compact compaction.{list,get,restore,branch} subscribe/unsubscribe messages.subscribe/unsubscribe
agents	7	list create update delete files.{list,get,set}
chat	3	send history abort
channels	2	status logout
logs	1	tail
models	1	list
usage	2	status cost
Root status	12	status health last-heartbeat set-heartbeats system-presence system-event wake send agent agent.identity.get agent.wait gateway.identity.get
config	6	get set patch apply schema schema.lookup
secrets	2	reload resolve
skills	6	status search detail install update bins
tools	2	tools.catalog tools.effective
exec.approval	9	list get request resolve waitDecision + global / per-node policy get/set
plugin.approval	4	list request resolve waitDecision
wizard	4	start next cancel status
doctor.memory	7	status dreamDiary backfillDreamDiary dedupeDreamDiary repairDreamingArtifacts resetDreamDiary resetGroundedShortTerm
node	16	list describe invoke + invoke.result event rename pair.{request,verify,approve,reject,list} pending.{ack,drain,enqueue,pull} canvas.capability.refresh
tts	6	status enable disable providers setProvider convert
talk	3	config mode speak
voicewake	2	get set
Misc	3	update.run commands.list message.action

Tool names follow openclaw_<domain>_<method>. Method-name dots become underscores: cron.list → openclaw_cron_list, sessions.compaction.restore → openclaw_sessions_compaction_restore.

Destructive tools

These carry destructive side effects (data loss, service interruption, revoked access). Their description is marked accordingly so Claude Code's confirmation gate prompts before each call:

• Cron: cron_remove, cron_run (real execution), cron_update
• Sessions: sessions_{abort,reset,delete,compaction_restore}
• Agents: agents_{delete,files_set}
• Chat: chat_abort
• Channels: channels_logout
• Device: device_{pair_remove,token_revoke,token_rotate}
• Config: config_{set,patch,apply}
• Secrets: secrets_resolve (returns secret material)
• Doctor memory: doctor_memory_{resetDreamDiary,resetGroundedShortTerm,repairDreamingArtifacts,backfillDreamDiary,dedupeDreamDiary}
• Node: node_{invoke,rename,pending_drain,pending_enqueue,pending_ack,pair_approve,pair_reject}
• Skills: skills_{install,update}
• Approvals: exec_approval_resolve, exec_approvals_{set,node_set}, plugin_approval_resolve
• Self-update: update_run (gateway-wide, may interrupt sessions)

Examples

Copy-paste prompts you can drop into Claude after the MCP is paired. Each one targets the corresponding tool and shows the kind of natural-language phrasing that resolves to a concrete call.

Health & sanity

> Run a full openclaw health check.

→ Calls openclaw_health, reports MCP version, gateway server version, paired device fingerprint, granted scopes, and how recently the last successful call ran.

> What gateway methods do I have access to right now?

→ Calls openclaw_introspect, returns the 128 JSON-RPC methods + 24 events the gateway publishes in its hello-ok.

Cron

> List all openclaw cron jobs, including disabled ones.

→ openclaw_cron_list({ enabled: "all" }).

> Show me the last 5 runs of cron job <id> — compact mode, just the summaries.

→ openclaw_cron_runs({ id: "<job-id>", limit: 5, compact: true }) — summaries truncated to 200 chars, each entry gets a runAtAgo: "3d ago" field.

> Create a cron that runs every Friday at 1pm Paris and posts a summary to Telegram group -1001234567890.

→ Generates an openclaw_cron_add payload with the right schedule.kind: "cron", expr: "0 13 * * 5", tz: "Europe/Paris", and delivery.mode: "announce".

Sessions

> List the 10 most recent active openclaw sessions, ranked by last activity.

→ openclaw_sessions_list({ limit: 10, sortBy: "updatedAt", sortDir: "desc" }).

> Show me the last 8 messages of session agent:main:cron:<id>.

→ openclaw_sessions_preview({ keys: ["agent:main:cron:<id>"] }) — returns role/text turns straight from the gateway.

Agents & channels

> List the agents configured on this gateway and which model they use.

→ openclaw_agents_list.

> What's the connection state of my Telegram channel?

→ openclaw_channels_status.

Escape hatch

> Use openclaw_call to invoke "config.schema" with no params and return the keys it exposes.

→ Useful when a gateway-side method doesn't yet have a typed wrapper, or you want to inspect a feature still in beta.

Resilience

request() retries transient errors (network drop, ws close, timeout, DNS) with exponential backoff: defaults to 1s → 2s → 4s, max 4 attempts. Non-retryable errors (PAIRING_REQUIRED, INVALID, MISSING_SCOPE, etc.) fail fast — no point retrying a permission issue. Tune via:

• OPENCLAW_RETRY_ATTEMPTS — total attempts (default 4, range 1–10)
• OPENCLAW_RETRY_BASE_MS — initial backoff in ms (default 1000, range 100–60000)
• OPENCLAW_DEBUG=1 — prints every retry decision to stderr

When a request gives up, the thrown error carries gateway request '<method>' failed (attempt N/M): as a prefix and the original error is preserved as cause for inspection. GatewayError code / details / retryable flags are propagated through the wrap.

The client tracks lastSuccessAtMs for openclaw_health's lastSuccessAgo field — useful for "is the gateway still talking to me?" debug.

Diagnostic CLI

For one-shot health checks without wiring the MCP into a client:

npx -y openclaw-control-mcp --health

Prints a JSON report (MCP version, gateway URL, paired state, scopes, server version, last-success age, error if any) and exits non-zero on failure. Handy in CI / scripts.

Schema looseness