vscode-node

通过作为 OpenClaw 节点连接的 VS Code/Cursor IDE 对代码进行操作。提供 40 多个命令，用于文件操作、语言智能、git、测试、调试和 Cursor Agent CLI 集成。当您需要读取/写入/编辑代码、导航定义/引用、运行测试、调试或将编码任务委托给光标代理时使用。

# VS Code / Cursor Node Skill

Control a VS Code or Cursor IDE remotely through the OpenClaw Node protocol.

## Related

- **[OpenClaw Node for VS Code](https://marketplace.visualstudio.com/items?itemName=xiaoyaner.openclaw-node-vscode)** — The VS Code/Cursor extension you need to install (required)
- **[cursor-ide-agent](https://clawhub.ai/xiaoyaner0201/cursor-ide-agent)** — Combined skill with both CLI and Node paths (install this instead if you also use Cursor CLI)
- **Source**: [github.com/xiaoyaner-home/openclaw-vscode](https://github.com/xiaoyaner-home/openclaw-vscode)

## Prerequisites

- Extension `openclaw-node-vscode` installed and connected (status bar 🟢)
- Node visible in `nodes status`
- Commands in Gateway's `allowCommands` whitelist

## Invocation Pattern

```
nodes invoke --node "<name>" --invokeCommand "<cmd>" --invokeParamsJson '{"key":"val"}'
```

Both `invokeTimeoutMs` (Gateway internal) and `timeoutMs` (HTTP layer, must be larger) are required for long operations.

**Timeout guide:**

| Type | invokeTimeoutMs | timeoutMs |
|------|----------------|-----------|
| File/editor/lang | 15000 | 20000 |
| Git | 30000 | 35000 |
| Test | 60000 | 65000 |
| Agent plan/ask | 180000 | 185000 |
| Agent run | 300000 | 305000 |

## Command Categories

| Category | Prefix | Key Commands | Reference |
|----------|--------|-------------|-----------|
| **File** | `vscode.file.*` | read, write, edit, delete | [commands/file.md](references/commands/file.md) |
| **Directory** | `vscode.dir.*` | list | [commands/file.md](references/commands/file.md) |
| **Language** | `vscode.lang.*` | definition, references, hover, symbols, rename, codeActions, format | [commands/language.md](references/commands/language.md) |
| **Editor** | `vscode.editor.*` | active, openFiles, selections | [commands/editor.md](references/commands/editor.md) |
| **Diagnostics** | `vscode.diagnostics.*` | get | [commands/editor.md](references/commands/editor.md) |
| **Git** | `vscode.git.*` | status, diff, log, blame, stage, commit, stash | [commands/git.md](references/commands/git.md) |
| **Test** | `vscode.test.*` | list, run, results | [commands/test-debug.md](references/commands/test-debug.md) |
| **Debug** | `vscode.debug.*` | launch, stop, breakpoint, evaluate, stackTrace, variables | [commands/test-debug.md](references/commands/test-debug.md) |
| **Terminal** | `vscode.terminal.*` | run (disabled by default) | [commands/terminal.md](references/commands/terminal.md) |
| **Agent** | `vscode.agent.*` | status, run, setup (Cursor only) | [commands/agent.md](references/commands/agent.md) |
| **Workspace** | `vscode.workspace.*` | info | [commands/editor.md](references/commands/editor.md) |

## Quick Examples

### Read a file
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.file.read" --invokeParamsJson '{"path":"src/main.ts"}'
→ { content, totalLines, language }
```

### Find all references
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.lang.references" --invokeParamsJson '{"path":"src/main.ts","line":10,"character":5}'
→ { locations: [{ path, line, character }] }
```

### Git status + commit
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.git.status"
→ { branch, staged, modified, untracked, ahead, behind }

nodes invoke --node "my-vscode" --invokeCommand "vscode.git.stage" --invokeParamsJson '{"paths":["src/main.ts"]}'
nodes invoke --node "my-vscode" --invokeCommand "vscode.git.commit" --invokeParamsJson '{"message":"fix: resolve type error"}'
```

### Delegate to Cursor Agent
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.agent.run" --invokeParamsJson '{"prompt":"Add error handling to all API endpoints","mode":"plan"}' --invokeTimeoutMs 180000 --timeoutMs 185000
→ { output, exitCode }
```

## Common Workflows

See [references/workflows.md](references/workflows.md) for detailed step-by-step workflows:
- Fix a type error
- Safe cross-file refactor
- Delegate complex task to Cursor Agent

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `node command not allowed` | Not in Gateway whitelist | Add to `gateway.nodes.allowCommands` |
| `node not found` | Extension not connected | Check extension status bar |
| `timeout` | Operation too long | Increase both timeout params |
| `path traversal blocked` | Path outside workspace | Use relative paths only |
| `read-only mode` | Extension in read-only | Disable `openclaw.readOnly` setting |

## Security

- All paths are **relative to workspace root** — absolute paths and `../` blocked
- Writes respect `readOnly` and `confirmWrites` extension settings
- Terminal disabled by default, whitelist-only when enabled
- Each device has unique Ed25519 identity, must be approved by Gateway

---

## 中文说明

# VS Code / Cursor Node Skill

通过 OpenClaw Node 协议远程控制 VS Code 或 Cursor IDE。

## 相关

- **[OpenClaw Node for VS Code](https://marketplace.visualstudio.com/items?itemName=xiaoyaner.openclaw-node-vscode)** — 你需要安装的 VS Code/Cursor 扩展（必需）
- **[cursor-ide-agent](https://clawhub.ai/xiaoyaner0201/cursor-ide-agent)** — 同时包含 CLI 和 Node 两种路径的组合技能（如果你也使用 Cursor CLI，请改装此技能）
- **来源**：[github.com/xiaoyaner-home/openclaw-vscode](https://github.com/xiaoyaner-home/openclaw-vscode)

## 先决条件

- 已安装并连接扩展 `openclaw-node-vscode`（状态栏 🟢）
- 节点在 `nodes status` 中可见
- 命令在 Gateway 的 `allowCommands` 白名单中

## 调用模式

```
nodes invoke --node "<name>" --invokeCommand "<cmd>" --invokeParamsJson '{"key":"val"}'
```

对于长时间操作，`invokeTimeoutMs`（Gateway 内部）和 `timeoutMs`（HTTP 层，必须更大）都是必需的。

**超时指南：**

| 类型 | invokeTimeoutMs | timeoutMs |
|------|----------------|-----------|
| 文件/编辑器/语言 | 15000 | 20000 |
| Git | 30000 | 35000 |
| 测试 | 60000 | 65000 |
| Agent plan/ask | 180000 | 185000 |
| Agent run | 300000 | 305000 |

## 命令类别

| 类别 | 前缀 | 关键命令 | 参考 |
|----------|--------|-------------|-----------|
| **文件** | `vscode.file.*` | read, write, edit, delete | [commands/file.md](references/commands/file.md) |
| **目录** | `vscode.dir.*` | list | [commands/file.md](references/commands/file.md) |
| **语言** | `vscode.lang.*` | definition, references, hover, symbols, rename, codeActions, format | [commands/language.md](references/commands/language.md) |
| **编辑器** | `vscode.editor.*` | active, openFiles, selections | [commands/editor.md](references/commands/editor.md) |
| **诊断** | `vscode.diagnostics.*` | get | [commands/editor.md](references/commands/editor.md) |
| **Git** | `vscode.git.*` | status, diff, log, blame, stage, commit, stash | [commands/git.md](references/commands/git.md) |
| **测试** | `vscode.test.*` | list, run, results | [commands/test-debug.md](references/commands/test-debug.md) |
| **调试** | `vscode.debug.*` | launch, stop, breakpoint, evaluate, stackTrace, variables | [commands/test-debug.md](references/commands/test-debug.md) |
| **终端** | `vscode.terminal.*` | run（默认禁用） | [commands/terminal.md](references/commands/terminal.md) |
| **Agent** | `vscode.agent.*` | status, run, setup（仅限 Cursor） | [commands/agent.md](references/commands/agent.md) |
| **工作区** | `vscode.workspace.*` | info | [commands/editor.md](references/commands/editor.md) |

## 快速示例

### 读取文件
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.file.read" --invokeParamsJson '{"path":"src/main.ts"}'
→ { content, totalLines, language }
```

### 查找所有引用
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.lang.references" --invokeParamsJson '{"path":"src/main.ts","line":10,"character":5}'
→ { locations: [{ path, line, character }] }
```

### Git status + commit
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.git.status"
→ { branch, staged, modified, untracked, ahead, behind }

nodes invoke --node "my-vscode" --invokeCommand "vscode.git.stage" --invokeParamsJson '{"paths":["src/main.ts"]}'
nodes invoke --node "my-vscode" --invokeCommand "vscode.git.commit" --invokeParamsJson '{"message":"fix: resolve type error"}'
```

### 委托给 Cursor Agent
```
nodes invoke --node "my-vscode" --invokeCommand "vscode.agent.run" --invokeParamsJso