Cursor Agent Skill

Two ways to use Cursor Agent from OpenClaw, for different scenarios.

Related

• - OpenClaw Node for VS Code — VS Code/Cursor extension that enables the Node path (install this first for Path 2)
• vscode-node — Standalone skill for the Node path only (if you don't need Cursor CLI)
• Source: github.com/xiaoyaner-home/openclaw-vscode

Path Selection

Scenario	Path	Why
Quick coding task, bug fix, refactor	CLI	Fast, no setup, works anywhere
Generate code, review PR, write tests

CLI | Non-interactive -p mode is perfect | | Fix type errors using real diagnostics | Node | diagnostics.get shows actual TS/lint errors | | Navigate definitions/references first | Node | lang.definition, lang.references | | Run project tests and iterate | Node | test.run + test.results loop | | Debug with breakpoints | Node | Full debug protocol | | Targeted changes to a specific project | Node | IDE workspace context is precise |

Default: CLI. Use Node only when you specifically need IDE intelligence.

---

Path 1: CLI (Local Cursor Agent)

Prerequisites

CODEBLOCK0

Modes

Mode	Flag	Use Case
Agent	(default)	Full coding — reads, writes, runs commands
Plan

--plan or --mode=plan | Design approach first, then choose local or cloud execution | | Ask | --mode=ask | Read-only codebase exploration, no edits |

Interactive Mode

CODEBLOCK1

Non-Interactive Mode (Automation)

CODEBLOCK2

Cloud Agent Handoff

Push work to Cursor's cloud to continue running while you're away:

CODEBLOCK3

Pick up at cursor.com/agents.

Session Management

CODEBLOCK4

Slash Commands (Interactive)

Command	Action
INLINECODE9	Switch to Plan mode / view current plan
INLINECODE10

Switch to Ask mode | | /models | Switch AI model | | /compress | Summarize conversation, free context | | /rules | Create/edit rules | | /commands | Create/edit custom commands | | /mcp enable <name> | Enable MCP server | | /mcp disable <name> | Disable MCP server | | /sandbox | Configure sandbox mode | | /max-mode [on\|off] | Toggle Max Mode | | /resume | Resume previous conversation |

Keyboard Shortcuts

Shortcut	Action
INLINECODE20	Rotate modes (Agent → Plan → Ask)
INLINECODE21

Insert newline (multi-line prompt) | | Ctrl+R | Review changes (i for instructions, arrows to navigate) | | Ctrl+D | Exit (double-press for safety) | | ArrowUp | Cycle previous messages |

Context & Rules

The CLI automatically loads:

• - .cursor/rules directory
• INLINECODE27 at project root
• INLINECODE28 at project root
• MCP servers from INLINECODE29

Use @filename or @directory/ in interactive mode to include context.

⚠️ Using CLI from OpenClaw (PTY Required)

Cursor CLI is an interactive TUI — it needs a real terminal. Use pty:true:

CODEBLOCK5

For long tasks, use background + poll:

CODEBLOCK6

Sandbox Controls

CODEBLOCK7

Sandbox supports granular network access controls — define which domains the agent can reach.

---

Path 2: VS Code / Cursor Node

Remote-control a Cursor/VS Code IDE through the OpenClaw Node protocol. The IDE must have the openclaw-node-vscode extension installed and connected.

Prerequisites

• - Extension installed: VS Code Marketplace
• Node visible in INLINECODE34
• Extension status bar shows 🟢

Invocation Pattern

CODEBLOCK8

Timeout Guide

Operation	invokeTimeoutMs	Notes
File/editor/lang	15000	Fast IDE operations
Git

30000 | May involve disk I/O | | Test | 60000 | Depends on test suite | | Agent plan/ask | 180000 | AI thinking time | | Agent run | 300000 | Full coding task |

Command Reference

Category	Prefix	Key Commands
File	INLINECODE35	read, write, edit, delete
Directory

vscode.dir.* | list | | Language | vscode.lang.* | definition, references, hover, symbols, rename, codeActions, format | | Editor | vscode.editor.* | context, openFiles, selections | | Diagnostics | vscode.diagnostics.* | get (errors/warnings) | | Git | vscode.git.* | status, diff, log, blame, stage, unstage, commit, stash | | Test | vscode.test.* | list, run, results | | Debug | vscode.debug.* | launch, stop, breakpoint, evaluate, stackTrace, variables, status | | Agent | vscode.agent.* | status, run, setup | | Workspace | vscode.workspace.* | info |

Quick Examples

CODEBLOCK9

Node Workflow: Fix → Verify → Commit

The real power of Node path — a closed loop with IDE intelligence:

CODEBLOCK10

No tmux, no TTY hacks — all through VS Code API.

---

Combined Workflow Example

Use CLI for broad tasks, switch to Node for precision:

CODEBLOCK11

---

Error Handling

Error	Cause	Fix
CLI hangs	No PTY	Add pty:true to exec
INLINECODE46

Extension disconnected | Check VS Code status bar |
| command not allowed | Gateway whitelist | Add to gateway.nodes.allowCommands |
| timeout | Operation too long | Increase invokeTimeoutMs |
| path traversal blocked | Absolute path used | Use relative paths for Node |

Security

• - CLI: Respects sandbox mode, command approval, rules
• Node: All paths relative to workspace, Ed25519 device identity, Gateway approval required
• Both: No raw shell access by default