Plugin guides

Muse Code agent runtime

The external @openclaw/muse plugin runs embedded agent turns for meta/* models through Muse Code, Meta's coding agent CLI. The plugin starts muse serve and talks to it over the Muse Session Protocol (MSP) with the official @muse-code/sdk client.

Muse Code owns the low-level agent loop: native shell, file read/write/edit tools, its OS sandbox, and its session state. OpenClaw still owns chat channels, model selection, approvals, the visible chat transcript, and the mapping from OpenClaw sessions to Muse sessions.

For the broader model/provider/runtime split, start with Agent runtimes.

Requirements

OpenClaw with the @openclaw/muse plugin installed.
If your config uses plugins.allow, include muse (the manifest id), not the npm package name.
The Muse Code CLI installed separately, with a muse binary on PATH or a configured binaryPath. Install it with Meta's installer:
bash
```
curl -fsSL https://dev.meta.ai/install.sh | shmuse --version
```
A Meta credential: a Muse Code browser sign-in, a stored key, or a meta auth profile in OpenClaw (see Auth).

Install

bash

openclaw plugins install @openclaw/muse

The plugin does not install or update the muse binary. It sets MUSE_NO_AUTO_UPDATE=1 on the processes it starts, so Muse does not update itself in the middle of a Gateway run. Update Muse with its own installer.

Quickstart

Route one Meta model through the Muse runtime:

json5

{  agents: {    defaults: {      model: "meta/muse-spark-1.3",      models: {        "meta/muse-spark-1.3": {          agentRuntime: { id: "muse" },        },      },    },  },}

Set agentRuntime.id on one model entry to route only that model, or on the meta provider to route every Meta model. The runtime is never selected automatically: without agentRuntime.id: "muse", meta/* models use the built-in OpenClaw runtime through the Meta provider.

The harness accepts only the standard meta provider route on Meta's official endpoint (https://api.meta.ai/v1). A meta provider entry with another baseUrl or with request transport overrides is refused, because Muse Code calls Meta itself.

Auth

The usual setup is Muse Code's own sign-in. Run muse once on the Gateway host and sign in with your browser (subscription) or paste an API key, or store a key with muse auth set. The harness then needs no OpenClaw credential.

The harness picks one credential per attempt, in this order:

The API key OpenClaw resolved for the attempt's selected meta auth profile.
The API key from the exact selected meta: auth profile, resolved through the provider auth runtime.
Muse Code's own order: META_API_KEY in the Gateway environment, then a key stored with muse auth set, then a browser sign-in.

When OpenClaw selects a key, the harness gives it to Muse as META_API_KEY. The Meta provider's MODEL_API_KEY is not passed to Muse; Muse does not read it.

Each credential gets its own muse serve process. Changing the key starts a new Muse session instead of resuming one that belongs to another credential.

If Muse rejects the credential, or finds none, the turn fails. Chat shows OpenClaw's generic failure notice; the Gateway log (openclaw logs --follow) carries the actionable cause, for example "Muse Code is not signed in on the Gateway host ... Run muse login there, or set META_API_KEY for the Gateway", plus the last lines of Muse's stderr (an invalid META_API_KEY appears only there).

Configuration

Key	Default	Purpose
`binaryPath`	`muse`	Muse executable path, or a command name resolved on `PATH`.

json5

{  plugins: {    entries: {      muse: {        enabled: true,        config: { binaryPath: "/opt/homebrew/bin/muse" },      },    },  },}

Model choice comes from the OpenClaw model ref. The thinking level maps to Muse's reasoning effort: off becomes minimal (Muse Spark does not accept none), and minimal, low, medium, high, xhigh, max, and ultra pass through. adaptive is refused because Muse has no adaptive mode.

Prepared image attachments are forwarded to Muse as native MSP image input, including their media type and base64 payload.

Approvals and sandbox

The harness resolves tools.exec.mode, legacy security/ask settings, agent-specific settings, and per-session exec overrides in that order. Explicit modes replace legacy fields in the same layer. Host-local exec approval defaults and agent-specific approval settings then apply as stricter security and ask floors; tools.exec.mode: "full" does not bypass them. Only an explicit full-session elevation can bypass those floors while its effective security remains full. The effective policy maps to Muse's approval mode and sandbox posture:

OpenClaw exec policy	Muse behavior
`security: "deny"`	`muse serve --disable-shell --disable-write`, approval mode `denyUnmatched`.
`security: "full"` with `ask: "off"`	Approval mode `allowAll`.
Default and other combinations	Approval mode `promptUnmatched`: Muse applies its own rules and asks OpenClaw about the rest.
`security: "allowlist"`	Refused. Muse cannot enforce OpenClaw's exec allowlist.
`ask: "always"`	Refused. Muse cannot guarantee an approval prompt for every native command.

When Muse asks for approval, OpenClaw shows its normal approval prompt with Allow once and Deny to approval surfaces watching the session, such as the Control UI. The harness answers with a choice that Muse offered. A denied, expired, or cancelled approval sends a deny choice, and so does an approval with no surface to show it. Each approval waits up to two minutes. The harness never grants persistent approvals.

The harness also refuses an attempt when OpenClaw requires an OpenClaw sandbox, workspace-only file access, or a restricted plugin tool policy. Muse runs on the Gateway host and cannot enforce those boundaries. Select the openclaw runtime for those agents or sessions.

A refused attempt fails before any muse process starts, with an error that names the setting.

Sessions

The plugin stores one binding per OpenClaw session in its plugin state: the Muse session id plus a fingerprint of the workspace, model, credential, read-only posture, and approval mode. The binding is saved only after Muse accepts the turn. The next turn resumes that Muse session when the fingerprint matches. If any of those inputs changed, or the previous transcript was marked unsafe to replay, the next turn starts a new Muse session. Changes to Muse's own MCP configuration do not start a new session.

If Muse refuses to resume the stored session, the harness starts a new Muse session and logs why. Muse runs nothing when it refuses a resume, and the OpenClaw transcript keeps the conversation. This covers a session that no longer exists and a retained session Muse can no longer open (for example, one created with a permission profile that needs the subscription's automated reviewer after muse logout). Transport failures, and sessions Muse reports as in use or overloaded, fail the turn instead, so a turn that may still be running is never repeated.

Every fresh Muse session receives the retained OpenClaw conversation branch before the current prompt, including after a model change, a refused resume, or a committed history reset. This transfer is bounded by OpenClaw's model-context reader. If the retained context cannot be read safely within that bound, the turn fails instead of silently starting without its history; compact the session or switch to the openclaw runtime.

Fresh sessions also receive OpenClaw workspace bootstrap context, such as SOUL.md, USER.md, and MEMORY.md, with the normal session, channel, and bootstrap-mode filters. MSP has no system-message or history-import field, so the harness prefixes this context to the first native user input. Resumed sessions do not repeat that prefix.

/new and /reset stop an active Muse turn and delete the binding. Rewinding or switching branches within the same OpenClaw session also invalidates the binding, but only after the history change commits.

Stopping a turn waits for Muse's terminal event, not just its interrupt acknowledgement. If Muse does not settle within five seconds, the harness closes the host before releasing the attempt.

muse serve processes are pooled per workspace, credential, and read-only posture, and shut down after five idle minutes.

Transcript

Each completed Muse item (assistant text, reasoning, tool calls, and tool results) is written to the OpenClaw session transcript as soon as Muse finishes it, keyed by the Muse session and item id so a retried write cannot duplicate entries. A transcript write failure stops the turn.

MCP servers

Muse owns its MCP configuration. Add MCP servers in Muse itself; OpenClaw's mcp.servers are not passed to Muse sessions.

Limitations

OpenClaw's own agent tools (messaging, sessions_spawn, browser, and other OpenClaw tools) are not available to Muse. MSP has no client-tool contract. Muse uses its native tools and its own MCP servers. Replies go back to the channel from the final turn text.
No live steering: a message sent during an active turn waits for the turn to finish.
No native compaction, isolated completions, or /btw side questions through Muse. /btw uses the configured model provider directly, as on other non-Codex runtimes.
No ask_user-style questions from Muse.
MSP has no system-instruction field. OpenClaw's extra system prompt is prepended to the user message of each turn.
Muse runs on the Gateway host only. It is not available with OpenClaw sandboxes or remote node execution.
Muse's built-in echo provider is not available over muse serve, so the runtime always needs a working Meta credential.
Model Setup checks a new meta sign-in with a short tool-restricted probe turn. Muse cannot enforce that restriction, so while meta/* models are routed to muse, activating a new meta API key in Model Setup fails with "Muse Code cannot enforce this conversation's tool policy". Use Muse's own sign-in instead (see Auth).

Live tests

bash

# Real `muse` binary, no credentials: handshake, start/resume, auth error, interrupt, exitOPENCLAW_MUSE_LIVE_HOST=1 node scripts/run-vitest.mjs \  --config test/vitest/vitest.live.config.ts extensions/muse/src/runtime.live.test.ts # Docker, offline after setup: fake MSP host behind a real Gatewaypnpm test:docker:muse-runtime # Docker, real Muse: approve the printed MUSE_DEVICE_CODE in the browser,# or pass OPENCLAW_MUSE_LIVE_KEY=<key> instead of device authOPENCLAW_MUSE_LIVE_AUTH=device pnpm test:docker:live-muse

The Docker lanes use disposable Gateways; credentials live only in the container. The live lane is opt-in and checks a real reply, recall after a Gateway restart, an allow-once shell approval, and the sign-in error after muse logout.

Was this useful?