Openclaw Control MCP

Send a message into a chat session via the gateway's chat layer. Wire format (verified live against gateway 2026.4.12+): requires `sessionKey` (composite, e.g. 'agent:main:main' from openclaw_sessions_list), `message`, and `idempotencyKey` (auto-generated UUID if omitted). The pre-0.5.x `agentId`/`sessionId`/`text` shape is rejected by the gateway. Destructive — triggers an agent turn.

List the slash-commands registered in the gateway (commands the agent or operator can invoke). Wraps `commands.list`. Read-only.

Apply pending config changes (commit). Wraps `config.apply`. Destructive — propagates buffered config to running components.

Read the gateway's current configuration. Wraps `config.get`. Read-only. The gateway returns the full config; pass `path` to project to a sub-section client-side after fetch (the gateway itself does NOT support a `path` filter — verified live against 2026.4.12+).

Optimistic-locked replace of the FULL gateway config (verified live against 2026.4.12+). Wraps `config.patch`. Wire format: `{ raw: string, baseHash: string }` where `raw` is the full config serialized as JSON and `baseHash` comes from a previous `openclaw_config_get` call. Pass `mergePath` + `mergeValue` for the convenience flow: this tool will fetch the current config, deep-merge your value at the given dotted path, compute the resulting `raw` JSON, and submit it with the freshly-read `baseHash`. Destructive — replaces the entire config atomically.

Get the JSON schema describing the gateway's config structure. Wraps `config.schema`. Read-only — useful before openclaw_config_set/patch to know which paths exist.

Look up the schema description for a specific config path. Wraps `config.schema.lookup`. Read-only.

Replace a config value at a given path. Wraps `config.set`. Destructive — overwrites the previous value. Prefer openclaw_config_patch for partial updates.

Create a new OpenClaw cron job. Wraps `cron.add`. Field names match the gateway wire format (verified by the Control panel SPA + live calls), NOT the README placeholders sometimes seen in the MCP source: schedule uses `expr`/`tz` (cron) or `everyMs` (every) or `at` (exact); payload.agentTurn uses `message` and `timeoutSeconds`. Examples: `{ schedule: { kind: "cron", expr: "0 13 * * 5", tz: "Europe/Paris" }, payload: { kind: "agentTurn", message: "...", timeoutSeconds: 180 } }`.

Create a cron job that fires every day at a fixed local time. Synthesizes the `cron`-kind schedule + `agentTurn` payload. Pass `hour`, `minute`, `tz`, `message`. Optional channel delivery via `channel` + `to`.

Create a cron job that fires every N minutes/hours regardless of clock time. Synthesizes an `every`-kind schedule. Pass either `intervalMinutes` or `intervalHours` (the tool computes `everyMs`). Use for monitoring jobs that don't care about wall-clock alignment.

Create a one-shot reminder/job that fires exactly once at a given absolute timestamp, then auto-deletes. Synthesizes an `exact`-kind schedule with `deleteAfterRun: true`. Pass `at` as RFC3339 (e.g. '2026-05-08T09:00:00+02:00') and a `message`.

Create a cron job that fires once a week at a fixed local time. Synthesizes a `cron`-kind schedule and an `agentTurn` payload, then calls `cron.add`. Pass `dayOfWeek` (mon..sun), `hour` (0-23), `minute` (0-59), `tz` (IANA, defaults to Europe/Paris), and `message`. Optional channel delivery: pass `channel` + `to`.

List configured OpenClaw cron jobs. Wraps the gateway JSON-RPC method `cron.list`. Returns jobs with name, schedule, payload kind, and enabled state.

Delete an OpenClaw cron job by id. Destructive — confirm before calling. Wraps `cron.remove`.

Trigger an immediate run of a specific OpenClaw cron job by id. Wraps `cron.run`.

List recent runs of a specific OpenClaw cron job. Wraps `cron.runs`. Pass `compact: true` to truncate each run's `summary` to 200 chars (saves tokens when scanning many runs); a `summaryTruncated` flag is added per entry. Each entry also gets a `runAtAgo` field (e.g. "3h ago") for readability.

Get the OpenClaw cron scheduler status (enabled flag, next-run timestamp, recent failures). Wraps `cron.status`.

Update an existing OpenClaw cron job in place. Wraps `cron.update`. Avoids the remove + re-add dance when you just want to change schedule, timeout, payload, or delivery. Wire format (verified live against gateway 2026.4.12+): `{ id|jobId: string, patch: object }` — pass the job id and a `patch` object containing only the fields you want to change. Older shape `{ job: { id, ...fields } }` is auto-translated for backward compat with pre-0.5.1 callers.

Approve a pending device pairing request. Requires operator.write scope. Wraps `device.pair.approve`.

List pending and paired devices known to the gateway. Useful for confirming that this MCP's device shows up in 'pending' before approval. Wraps `device.pair.list` (operator scope).

Reject a pending device pairing request. Wraps `device.pair.reject`.

Remove a paired device from the gateway. Wraps `device.pair.remove`. Destructive — the device will need to re-pair to reconnect.

Recover from the `expected Uint8Array of length 32, got length=0` failure mode (empty `device.privateKey`). Backs up `store.json` to `store.json.bak.<ts>`, and wipes the broken device + cached tokens (keeps gateway URL + token configs). The next call to any scoped tool regenerates a fresh Ed25519 keypair and surfaces a new `pendingPairing.requestId` to approve in the Control panel. The `instance` arg is accepted but currently no-op — the local Store is shared across all instances. **Destructive — run only when openclaw_device_status reports the empty-private-key failure mode.**

Show this MCP's local device identity, pairing status, current scopes (if any), and any pending pairing requestId. Triggers a fresh connect attempt, so it doubles as a 'retry pairing' command after approval. Use when scoped methods fail with 'missing scope: operator.read'.

Revoke a device's authentication token. Wraps `device.token.revoke`. Destructive — the device must re-pair (or use a freshly issued token).

Rotate a device's authentication token (issues a new one, invalidates the old). Wraps `device.token.rotate`. Destructive — the device's currently cached token stops working.

Backfill the dream diary from past sessions (re-runs dreaming on history). Wraps `doctor.memory.backfillDreamDiary`. Mutates — can be expensive in tokens.

Deduplicate dream diary entries. Wraps `doctor.memory.dedupeDreamDiary`. Mutates.

Read the dream diary (the gateway's REM/light dream artifacts that promote into MEMORY.md). Wraps `doctor.memory.dreamDiary`. Read-only.

Repair corrupted dreaming artifacts (e.g. orphan files, broken JSON). Wraps `doctor.memory.repairDreamingArtifacts`. Mutates.

Wipe the dream diary entirely. Wraps `doctor.memory.resetDreamDiary`. DESTRUCTIVE — confirm before calling. Loses all promoted-into-memory candidates.

Wipe the grounded short-term memory store. Wraps `doctor.memory.resetGroundedShortTerm`. DESTRUCTIVE — agents lose their recent recall.

Get the memory subsystem health (short-term store, dream diary, grounding state). Wraps `doctor.memory.status`. Read-only.

Get details of a specific exec approval request (command, args, agent, status). Wraps `exec.approval.get`. Read-only.

List pending and recent exec approvals (commands the agent wants to run that need a human OK). Wraps `exec.approval.list`. Read-only.

Submit a new exec approval request (programmatic; normally agents do this themselves). Wraps `exec.approval.request`.

Resolve (approve / reject) a pending exec approval. Wraps `exec.approval.resolve`. Mutates — the agent will proceed (or not) based on this decision.

Block until an exec approval gets a decision (or timeout). Wraps `exec.approval.waitDecision`. Long-running — bounded by the request timeout.

Get the global exec approvals policy (auto-allow rules, defaults). Wraps `exec.approvals.get`. Read-only.

Get the per-node exec approvals policy override. Wraps `exec.approvals.node.get`. Read-only.

Set the exec approvals policy for a specific node. Wraps `exec.approvals.node.set`. Destructive.

Set / replace the global exec approvals policy. Wraps `exec.approvals.set`. Destructive — overwrites the existing policy.

Get the gateway's own identity (id, version, owner, region). Wraps `gateway.identity.get`. Read-only.

Combined health probe — server-side `health` JSON-RPC plus client-side metadata (MCP version, device pairing state, gateway URL, last successful call). Read-only. Use this for a one-shot 'is everything OK?' check.

Inspect the OpenClaw gateway capabilities. Triggers a connect (if not already), returns the server version, this device's role/scopes, the full list of JSON-RPC `methods` and `events` the gateway publishes, and a coverage report comparing those methods to the typed wrappers this MCP exposes. Use to discover what methods you can call via `openclaw_call` and to spot endpoints that still need a typed wrapper after a gateway upgrade.

Get the last heartbeat info (latest tick processed by the gateway). Wraps `last-heartbeat`. Read-only.

Tail recent gateway logs. Wraps `logs.tail`. Read-only. The gateway only forwards `limit` to the wire; `sinceMs`, `level`, and `component` are applied client-side AFTER fetch (verified live: the gateway rejects them with `unexpected property` against 2026.4.12+). For wide tails, raise `limit` and the client filters on the way back. Use this for debug — e.g. tracing why a cron job failed, why a session aborted, or what an agent emitted.

Trigger a message-level action (e.g. retry, mark-as-handled, attach to a session). Wraps `message.action`. Mutates gateway state.

List models available to the gateway (Anthropic, OpenAI, etc.) with their IDs and any provider metadata. Wraps `models.list`. Read-only.

Refresh the canvas capability map for nodes (re-registers what each canvas node can do). Wraps `node.canvas.capability.refresh`.

Describe a specific node — capabilities, host, version, last heartbeat. Wraps `node.describe`. Read-only.

Emit an event toward a node (or the gateway-side node bus). Wraps `node.event`.

Invoke a method on a specific node (RPC routed through the gateway). Wraps `node.invoke`. Mutates depending on the target method.

Fetch the result of a previously-issued node invocation. Wraps `node.invoke.result`. Read-only.

List nodes registered with this gateway (worker / canvas / sub-gateway nodes). Wraps `node.list`. Read-only.

Approve a pending node pairing request. Wraps `node.pair.approve`. Mutates — node gains gateway access.

List node pairing requests (pending and resolved). Wraps `node.pair.list`. Read-only.

Reject a pending node pairing request. Wraps `node.pair.reject`.

Request pairing for a new node. Wraps `node.pair.request`.

Verify a node pairing handshake. Wraps `node.pair.verify`.

Acknowledge / commit completion of a pending work item. Wraps `node.pending.ack`.

Drain (clear) all pending work items for a node. Wraps `node.pending.drain`. Destructive — discards queued work.

Enqueue a new work item for a node. Wraps `node.pending.enqueue`. Mutates.

Pull pending work items destined for a node (queue drain). Wraps `node.pending.pull`. Read-and-mutate (work items leave the pending queue).

Rename a node (display name / id). Wraps `node.rename`. Mutates.

List pending and recent plugin approval requests (a skill / plugin asking for permission to do X). Wraps `plugin.approval.list`. Read-only.

Submit a plugin approval request (programmatic). Wraps `plugin.approval.request`.

Resolve a pending plugin approval (approve / reject). Wraps `plugin.approval.resolve`. Mutates.

Block until a plugin approval gets a decision. Wraps `plugin.approval.waitDecision`. Long-running.

Reload the gateway's secret store from disk. Wraps `secrets.reload`. Use after editing the secrets file out-of-band so the gateway picks up new values without a restart.

Resolve a command-scoped secret. Wraps `secrets.resolve`. Wire format (verified live against gateway 2026.4.12+): `{ commandName: string }` — the gateway secrets subsystem is COMMAND-scoped, not arbitrary key/value. SENSITIVE — returns secret material; only use for debugging missing/wrong-values issues. For arbitrary API keys consumed by skills, use `openclaw_secrets_set` (which writes to the config tree, not the command-scoped secret store).

Store an arbitrary secret (API key, third-party token, etc.) in the gateway's config tree where skills can consume it. Internally calls `config.patch` with a `mergePath` so the value lands at `config.<scope>.<name>`. Default scope is `secrets` (creates `config.secrets.<name>`); override with `scope` for skill-scoped secrets like `tools.linkedin-outreach.proxycurlApiKey`. Note: this writes to the CONFIG tree, not the gateway's `secrets.resolve` command-scoped store (which has no public write API). After this call, restart-free — the next agent run sees the updated config.

Channel-routed `send` — pushes a message via the gateway's delivery layer. Wire format (verified live against gateway 2026.4.12+): requires `to` (channel-specific recipient) + `idempotencyKey` (auto-generated if omitted). Prefer the typed `openclaw_chat_send` or `openclaw_sessions_send` when you want session context.

Abort the in-flight agent turn for a session (cancels the current LLM call / tool loop). Wraps `sessions.abort`. Destructive — interrupts running work.

Trigger a compaction of a session's history (creates a new compaction snapshot, keeps the session live). Wraps `sessions.compact`.

Create a NEW session that starts from a previous compaction snapshot of an existing session. Wraps `sessions.compaction.branch`. Use this when you want to explore an alternative continuation without losing the current session state.

Fetch a specific compaction snapshot by id. Wraps `sessions.compaction.get`. Read-only.

List compaction snapshots for a session. Wraps `sessions.compaction.list`. Read-only.

Restore a session to a previous compaction snapshot. Wraps `sessions.compaction.restore`. Destructive — overwrites current session state with the snapshot. The current state is lost unless you branched first.

Create a new agent session. Wraps `sessions.create`. The default agent id is typically 'main'. Pass an optional `title` to set the human-readable label shown in the Control panel.

Delete a session permanently. Wraps `sessions.delete`. Destructive — confirm before calling.

List active OpenClaw agentic sessions. Wraps `sessions.list`. Each session has both a `sessionId` (UUID) and a `key` (composite, e.g. 'agent:main:main', 'agent:main:cron:<id>', 'agent:main:telegram:group:<chat-id>', 'agent:main:subagent:<uuid>'). Use to find a session before preview/patch/abort/compact/reset. The `status` filter is applied client-side after fetch (verified live: the gateway itself rejects a `status` param with `unexpected property 'status'` against 2026.4.12+).

Subscribe to streaming session messages (session.message events). Wraps `sessions.messages.subscribe`. Note: MCP stdio cannot stream events to Claude Code — server-side subscription only.

Unsubscribe from session message stream. Wraps `sessions.messages.unsubscribe`.

Update session metadata (title, displayName, tags, etc.). Wraps `sessions.patch`. Pass id + only the fields you want to change. Schema is intentionally permissive — gateway accepts any subset of session fields.

Preview one or more sessions without subscribing — returns recent messages, status, and metadata for each key. Wraps `sessions.preview`. Read-only. Pass `keys` (array of full session keys like 'agent:main:cron:<id>' from openclaw_sessions_list).

Reset a session (clears working state, keeps session id). Wraps `sessions.reset`. Destructive — confirm before calling.

Send a user message into an existing session. Wraps `sessions.send`. The agent processes async and streams the reply via session.message events; call openclaw_sessions_preview afterwards (with the session's composite key) to see the result. Use either `text` or `message` — gateway accepts both names depending on version.

Subscribe to session lifecycle events (sessions.changed). Wraps `sessions.subscribe`. Note: the MCP runs over stdio and cannot stream events back to the client — this tool registers the subscription server-side but you won't receive deltas in Claude Code. Useful mainly to confirm the subscription was accepted.

Watch a session by polling `sessions.preview` and return only the NEW messages that appeared during the tail window. Workaround for the stdio MCP not being able to stream `sessions.subscribe` / `session.message` events to Claude Code. Polls every `intervalMs` (default 2000ms) for up to `durationMs` (default 30000ms, max 300000ms), or until `maxMessages` new messages are collected, or until the session reaches a terminal status ('done', 'error', 'aborted', 'timeout', 'completed'). The first poll seeds the 'already-seen' set so existing messages are NOT returned — only what arrives after the too…

Unsubscribe from session lifecycle events. Wraps `sessions.unsubscribe`.

Toggle / configure heartbeat emission from the gateway. Wraps `set-heartbeats`. Pass `enabled` and any cadence params.

Persist a named OpenClaw gateway config (URL + token) to local store. Default instance name is 'default'. Pass `instance` to manage multiple gateways (e.g. 'perso', 'work') from the same MCP. Env vars (OPENCLAW_GATEWAY_URL/TOKEN) still override everything stored here — leave them unset to use named instances. After saving, the matching client connection is closed so the next tool call re-handshakes with the new credentials.

Clear a persisted gateway config. By default clears every instance; pass `instance` to clear just one. Does NOT touch the device identity or device tokens. After this, the MCP falls back to env vars or errors with 'configure first'.

List every persisted gateway instance (name + URL + whether token/password are set, never the values). Plus the active default instance and where secrets come from (env vars / `.env` vs `store.json`).

Switch the active default instance — every subsequent tool call (cron.list, sessions.list, etc.) will route to this instance unless an env var overrides. Closes existing client connections so they re-handshake with the new instance's credentials.

Show the currently resolved gateway configuration for an instance (default 'default' or whichever instance is the active default). Does NOT print tokens. Pass `instance` to inspect a non-default one.

List the binaries / executables exposed by installed skills. Wraps `skills.bins`. Read-only.

Get detailed info on a specific skill (manifest, version, dependencies, install state). Wraps `skills.detail`. Read-only.

Install a skill (or a specific version). Wraps `skills.install`. Mutates the gateway's skill set — confirm before calling.

Search the available skill catalog (installed and remote). Wraps `skills.search`. Read-only.

Get the skills subsystem status (which skills are installed, enabled, recently updated). Wraps `skills.status`. Read-only.

Update an installed skill to its latest (or a specified) version. Wraps `skills.update`. Mutates the gateway state.

Get overall gateway status (uptime, agents, sessions, queues). Wraps the root-level `status` JSON-RPC method. Read-only.

Emit a custom system event onto the gateway bus. Wraps `system-event`. Mostly used for tooling / debug — operators rarely call this directly.

Get presence info (which devices are connected, when they last spoke). Wraps `system-presence`. Read-only.

Get / set the talk-mode config (push-to-talk, hold-to-listen, voice activity detection). Wraps `talk.config`.

Toggle talk mode on/off. Wraps `talk.mode`. Wire format (verified live against gateway 2026.4.12+): requires `enabled: boolean` — this is a SETTER, not a getter. Use `openclaw_talk_config` to read the current state.

Make the agent speak a piece of text out loud (synthesizes + plays). Wraps `talk.speak`.

List the catalog of agent-facing tools available to OpenClaw agents (i.e. what `main` and other agents can call from inside a session). Wraps `tools.catalog`. Read-only.

Get the effective (merged) tool set for an agent — base catalog + skill-provided + per-agent overrides. Wraps `tools.effective`. Read-only.

Synthesize a piece of text to audio. Wraps `tts.convert`. Returns audio / a download URL depending on the gateway config.

Disable text-to-speech output. Wraps `tts.disable`.

Enable text-to-speech output. Wraps `tts.enable`.

List available TTS providers (and their voices / models). Wraps `tts.providers`. Read-only.

Switch the active TTS provider / voice. Wraps `tts.setProvider`.

Get the TTS subsystem status (enabled, current provider, voice). Wraps `tts.status`. Read-only.

Trigger an update of the gateway itself (pull latest version, restart components). Wraps `update.run`. DESTRUCTIVE — may briefly interrupt running sessions. Confirm before calling.

Get usage cost breakdown (per agent, per model, per period). Wraps `usage.cost`. Read-only. Pass period/agent filters if supported.

Get usage status (token counts, current period, quotas). Wraps `usage.status`. Read-only.

Get the voice-wake configuration (wake word, sensitivity, enabled). Wraps `voicewake.get`. Read-only.

Update the voice-wake configuration. Wraps `voicewake.set`.

Wake an agent / session out of idle. Wraps the root-level `wake` method. Pass agentId/sessionId.

Cancel the active wizard flow without applying its changes. Wraps `wizard.cancel`.

Advance the active wizard to its next step (with the user's answer to the current step). Wraps `wizard.next`.

Start a setup wizard flow (e.g. agent onboarding, channel pairing). Wraps `wizard.start`. Pass the wizard id / kind.

Get the wizard's current step and pending input for a specific session. Wraps `wizard.status`. Wire format (verified live against gateway 2026.4.12+): requires `sessionId`. Read-only.