Cursor Agent — OpenClaw Plugin
Invoke the local Cursor Agent CLI directly from OpenClaw chat conversations
English | 中文
---
> The real power of AI coding isn't in a single IDE — it's in connecting AI agents across your workflow.
What is Cursor Agent Plugin?
Cursor Agent is an OpenClaw Gateway plugin that bridges your chat conversations with the Cursor Agent CLI. It allows you to analyze, troubleshoot, and modify project code through simple /cursor commands — with results returned verbatim, no LLM re-summarization.
Tech Stack:
- Runtime: Node.js + TypeScript + ESM
- Build: esbuild (single-file bundle)
- Platform: OpenClaw Gateway Plugin System
- Backend: Cursor Agent CLI (uses your Cursor subscription)
Features
⚡ Direct CLI Invocation
Use the /cursor command to invoke Cursor Agent CLI with zero abstraction overhead.
| Feature | Description | |---------|-------------| | Verbatim Results | CLI output returned directly — no LLM re-summarization | | Three Modes | agent (modify files), ask (read-only), plan (generate plans) | | Project Mapping | Quick project switching by name via mapping table | | Session Management | Continue or resume previous analysis sessions | | Context Loading | Automatically loads .cursor/rules, AGENTS.md, etc. |
🔌 MCP Server Integration
Enable project-configured MCP servers for extended capabilities.
| Feature | Description | |---------|-------------| | Auto-Enable | MCP servers enabled by default (--approve-mcps) | | Flexible Sources | GitLab, databases, monitoring, and more | | Per-Project Config | Each project can have its own MCP configuration |
🤖 Agent Tool (Fallback Invocation)
When users don't use the /cursor command, PI Agent can automatically invoke Cursor CLI.
| Feature | Description | |---------|-------------| | Auto-Detection | PI Agent determines when code analysis is needed | | Safe Default | Defaults to ask mode (read-only) for safety | | Configurable | Enable/disable via enableAgentTool setting |
🛡️ Robust Process Management
Enterprise-grade subprocess management for reliability.
| Feature | Description | |---------|-------------| | Isolated Process Groups | detached: true on Unix prevents accidental signal kills | | Two-Phase Termination | SIGTERM → 5s → SIGKILL for graceful shutdown | | Concurrency Control | Configurable max concurrent CLI processes | | Gateway Exit Cleanup | All subprocesses cleaned up automatically on exit | | No-Output Timeout | Detects hung processes when no output is produced |
Prerequisites
| Dependency | Description | |------------|-------------| | Cursor Agent CLI | Must be installed locally (agent command) | | Cursor Subscription | CLI uses model quota from your Cursor subscription | | OpenClaw Gateway | v2026.2.24+ |
Quick Start
1. Install Cursor Agent CLI
Linux / macOS:
curl https://cursor.com/install -fsSL | bashYou may need to add $HOME/.local/bin to your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcWindows (PowerShell):
irm https://cursor.com/install | iexVerify installation:
agent --version2. Authenticate
agent loginOr set the API key via environment variable:
export CURSOR_API_KEY="your-api-key"3. Install the Plugin
Option A: Source Path Loading (Development)
Add the plugin source path to plugins.load.paths in ~/.openclaw/openclaw.json:
{
"plugins": {
"load": {
"paths": ["/path/to/cursor-agent"]
}
}
}Option B: tgz Package Install
npm ci && npm run build && npm pack
openclaw plugins install cursor-agent-0.1.0.tgz4. Configure
{
"plugins": {
"entries": {
"cursor-agent": {
"enabled": true,
"config": {
"projects": {
"my-project": "/home/user/projects/my-project",
"another-project": "/home/user/projects/another"
},
"defaultTimeoutSec": 600,
"noOutputTimeoutSec": 120,
"enableMcp": true,
"maxConcurrent": 3,
"enableAgentTool": true
}
}
}
}
}5. Configure Command Authorization
The /cursor command requires authorization by default (requireAuth: true). You need to configure commands.allowFrom in OpenClaw before using it. There are two ways:
Option A: Via Control UI (Recommended)
1. Open the OpenClaw Control UI in your browser: http://127.0.0.1:<port>/config?token=<your-gateway-token> 2. Click Commands in the left navigation panel 3. Find the Command Elevated Access Rules section 4. Click + Add Entry to add a rule:
- Set Key to a channel ID (use
*for all channels) - Click + Add below to add allowed sender IDs (use
*for all users)
5. Click Save at the top, then Apply to activate the configuration
!Command Elevated Access Rules UI
Option B: Edit Config File Directly
Add the allowFrom field to the commands section in ~/.openclaw/openclaw.json:
{
"commands": {
"allowFrom": {
"*": ["*"]
}
}
}allowFrom Reference:
| Key (Channel ID) | Value (Sender List) | Effect | |-------------------|---------------------|--------| | "" | [""] | All users on all channels can execute authorized commands | | "*" | ["user1", "admin"] | Only specified users on all channels |
> Production Tip: In production, restrict allowFrom to specific channels and users instead of using the "*" wildcard to ensure only authorized personnel can execute code modification operations.
6. Start Using
/cursor my-project analyze the auth module and find potential security issuesUsage
Command Format
/cursor <project> [options] <prompt>| Parameter | Description | |-----------|-------------| | <project> | Project name (key from mapping table) or absolute path | | <prompt> | Detailed description of the analysis task | | --mode <mode> | Execution mode: agent (default) / ask / plan | | --continue | Continue previous session | | --resume <chatId> | Resume a specific session |
Examples
# Read-only analysis
/cursor my-project --mode ask explain the architecture of src/auth
# Generate a plan
/cursor my-project --mode plan design a new caching layer
# Continue previous session
/cursor my-project --continue are there other security issues?
# Resume a specific session (ID shown in result footer)
/cursor my-project --resume abc123 add unit tests based on this analysisSession History
Each execution result footer displays a session ID (e.g., 💬 97fe5ea8-...). Use it with --resume to continue that session.
To browse sessions in terminal:
cd /path/to/project
agent ls # List sessions
agent resume # Interactive resume
agent --resume <id> # Resume by IDSee the Cursor Agent CLI documentation for more.
Configuration Reference
| Field | Type | Default | Description | |-------|------|---------|-------------| | projects | object | {} | Project name to local absolute path mapping | | agentPath | string | auto-detect | Full path to Cursor Agent CLI | | defaultTimeoutSec | number | 600 | Maximum execution time per invocation (seconds) | | noOutputTimeoutSec | number | 120 | No-output timeout; process considered hung after this duration | | model | string | CLI default | Model for Cursor Agent to use | | enableMcp | boolean | true | Enable MCP servers (--approve-mcps) | | maxConcurrent | number | 3 | Maximum concurrent Cursor CLI processes | | enableAgentTool | boolean | true | Register Agent Tool for PI Agent auto-invocation |
Agent Tool vs /cursor Command
| Feature | /cursor Command | Agent Tool | |---------|-------------------|------------| | Trigger | User explicitly types | PI Agent auto-determines | | Result handling | Returned directly, bypasses LLM | Returned as tool result | | Default mode | agent (can modify files) | ask (read-only analysis) | | Session management | Supports --continue/--resume | Not supported |
To enable Agent Tool:
1. Ensure enableAgentTool is true (default) 2. Add cursor_agent or group:plugins to tools.allow in OpenClaw configuration
If you are using multiple agents:
Please Adding cursor_agent to the global tools.allow in openclaw.json is not sufficient for agents to use the tool. Each agent that needs access you must also have cursor_agent listed in its own tools.alsoAllow array under agents.list[].tools.alsoAllow. Without this, the plugin registers successfully (visible in startup logs), but the agent cannot invoke the cursor_agent tool at runtime.
Architecture
src/
├── index.ts # Plugin entry, registers /cursor command + cursor_agent tool
├── types.ts # Type definitions (config, events, parsed command)
├── parser.ts # Cursor Agent stream-json output parser
├── runner.ts # CLI process management, timeout control, event stream
├── formatter.ts # Event stream formatting to Markdown output
├── process-registry.ts # Global process registry, concurrency control, cleanup
└── tool.ts # Agent Tool factory functionInvocation Paths
User Message
├─ /cursor command ──→ registerCommand handler ──→ runCursorAgent ──→ result returned to user
└─ Regular chat ──→ PI Agent ──→ cursor_agent tool ──→ runCursorAgent ──→ tool resultDevelopment
# Install dependencies
npm install
# Development mode (watch)
npm run dev
# Build
npm run build
# Run tests
npm test
# Pack for distribution
npm pack
