openclaw-cursor-agent

An OpenClaw plugin that runs the Cursor CLI (cursor-agent) as a CLI backend, the same way OpenClaw wraps Claude Code and Gemini CLI.

Models are addressed as cursor-agent/<model-id>, for example:

• cursor-agent/composer-2.5
• cursor-agent/grok-4.5-fast-xhigh
• cursor-agent/gpt-5.5-high

Run cursor-agent models to see the model ids available to your Cursor account. Short aliases are built in: composer, grok, gpt, opus, fable, sonnet.

Features

• Full OpenClaw tool bridge (MCP). Cursor turns get all OpenClaw dynamic tools (messaging, memory, sessions, canvas, web search, ...) via OpenClaw's loopback MCP server. The plugin translates OpenClaw's Claude-style --mcp-config injection into a workspace .cursor/mcp.json and passes --approve-mcps.
• System prompt injection. The Cursor CLI has no system-prompt flag, so the plugin writes OpenClaw's system prompt to .cursor/rules/openclaw.mdc (alwaysApply: true) in the agent workspace, which headless Cursor runs honor.
• Thinking-level mapping. OpenClaw --thinking off|low|medium|high|xhigh rewrites the model id's effort suffix (e.g. grok-4.5-fast-xhigh + --thinking medium runs grok-4.5-fast-medium). Rewrites are validated against the live cursor-agent models list (cached, with a static fallback) and fall back to the original id when no variant exists.
• Session continuity. Captures session_id from stream-json output and resumes with --resume <id>, so conversations keep native context across turns.
• Safety-aligned permissions. Adds --force (run everything) only when OpenClaw's exec tool policy is already full access with approvals off (configurable, see below). Side questions (/btw) run read-only via --mode ask.
• Env hygiene. Clears CURSOR_API_KEY from the child env so an ambient key can't silently switch the CLI to another account.
• /cursor chat command. /cursor status, /cursor models, and /cursor doctor inspect the backend from any OpenClaw chat surface.
• Model catalog. All known Cursor model ids are published to OpenClaw's model catalog (openclaw models list --all), with live rows from cursor-agent models where supported.
• Behavior overlay. A short backend contract is appended to the workspace rule so Cursor-served models don't hallucinate about their environment (who sends channel messages, model switching, foreign plugin-* MCP tools).
• Plugin MCP deny rule. Writes Mcp(plugin-*:*) into the workspace .cursor/cli.json so Claude-marketplace MCP servers auto-imported by the Cursor CLI can't hijack OpenClaw turns (holds under --force).
• Media understanding provider. OpenClaw's bounded image describe/extract calls can run through the CLI: a one-shot read-only turn in an isolated temp workspace (default model gemini-3.5-flash), with JSON-schema extraction support.

Requirements

• OpenClaw >= 2026.5.12
• The Cursor CLI installed and logged in (cursor-agent on your PATH, cursor-agent login)

Install

git clone https://github.com/davidgeorgehope/openclaw-cursor-agent
openclaw plugins install --link ./openclaw-cursor-agent
openclaw gateway restart

Then allow the models you want on your agent in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "models": {
        "cursor-agent/composer-2.5": {},
        "cursor-agent/grok-4.5-fast-xhigh": {}
      }
    }
  }
}

Switch to it in any chat with /model cursor-agent/composer-2.5, or verify from the shell:

openclaw agent --agent main --message "reply exactly: backend ok" --model cursor-agent/grok-4.5-fast-xhigh
openclaw agent --agent main --message "call the session_status MCP tool and summarize it" --model cursor-agent/composer-2.5

Configuration

Optional plugin config in ~/.openclaw/openclaw.json under plugins.entries.cursor-agent.config (resolved live; no restart needed):

{
  "command": "/path/to/cursor-agent",
  "force": "auto",
  "denyPluginMcps": true,
  "modelAliases": { "grok": "grok-4.5-xhigh" },
  "extraArgs": []
}

• command — CLI binary path (default cursor-agent; agents.defaults.cliBackends.cursor-agent.command still wins).
• force — auto (mirror OpenClaw exec policy), always, or never.
• denyPluginMcps — write the Mcp(plugin-*:*) deny rule (default true).
• modelAliases — extra aliases merged over the built-ins.
• extraArgs — appended to every run.

Development

npm test    # unit tests (node:test, no network)
npm run smoke   # live smoke: fresh/resume/image turns + deny rule, needs cursor-agent login

How it works

• Runs cursor-agent -p --output-format stream-json --trust with the prompt on stdin. Cursor's stream-json output is close enough to Claude Code's that OpenClaw's existing claude-stream-json parser handles it.
• Declares bundleMcp with the claude-config-file mode, then intercepts the injected --strict-mcp-config --mcp-config <path> args in resolveExecutionArgs: the generated config (including the OpenClaw loopback server with ${ENV_VAR} header placeholders, which the Cursor CLI interpolates from the child env) is rewritten into <workspace>/.cursor/mcp.json, and the Claude-only flags are replaced with --approve-mcps.
• Delivers the OpenClaw system prompt through transformSystemPrompt, which writes .cursor/rules/openclaw.mdc before each run.
• Owns the --model flag so it can apply aliases and thinking-level effort rewrites; a models subprocess call in prepareExecution keeps the valid-id cache warm.
• Declares ownsNativeCompaction since the Cursor agent manages its own context window.
• Images attached in OpenClaw are staged into the workspace and referenced as @<path> in the prompt, which headless Cursor reads natively.

Limitations

• .cursor/mcp.json, .cursor/rules/openclaw.mdc, and the deny rule in .cursor/cli.json are managed files inside the OpenClaw agent workspace and are overwritten on each run.
• Side questions run via --mode ask, which is read-only rather than fully tool-less — the Cursor agent can still read workspace files during /btw turns. The CLI has no true no-tools flag today.
• On OpenClaw 2026.6.10, changing the system prompt (new skill, config change) invalidates the native Cursor session and starts a fresh chat. Newer OpenClaw treats prompt drift as reuse-with-drift, which this backend benefits from automatically once released.