Openclaw Control MCP

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.3 — 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…" }.

1. Open the OpenClaw Control panel → Devices tab → approve the request whose id matches.
2. 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.
3. 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"

Releasing (npm + official MCP Registry, both from .github/workflows/publish.yml on a v*.*.* tag) is documented in CONTRIBUTING.md.

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]

1. 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 "

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": " ", "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:

.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

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 } }

Configur