Windows 上的 Cursor Remote Control

Remote Control

Cursor Remote Control 让你从远程机器控制 Cursor 实例，实现无头服务器、云工作站或辅助机器上的 AI 辅助开发。在 Windows 上，设置涉及 worker 进程、CLI 配置和基于 SQLite 的状态存储。论坛用户经常遇到与 better-sqlite3 和 NODE_MODULE_VERSION 不匹配相关的崩溃。本指南涵盖完整设置，并为最常见的 Windows 特定问题提供经过测试的解决方案。

什么是 Cursor Remote Control？

Remote Control 由两个组件组成：

主机（Host） - 你想要控制的 Cursor 实例（通常在远程或云 Windows 机器上）
控制器（Controller） - 你的本地机器，运行 Cursor CLI 发送命令

主机运行一个 worker 进程，该进程：

监听来自 CLI 的传入命令
在本地 SQLite 数据库（better-sqlite3）中维护状态
执行文件操作、终端命令和 agent 任务
将结果流式传输回控制器

使用场景

场景	优势
云开发工作站	在强大的云机器上使用 AI，从轻量级笔记本电脑操作
无头服务器管理	在没有显示器的情况下在服务器上运行 Cursor agent
多机工作流	从一台机器控制多个 Cursor 实例
CI/CD 集成	从自动化流水线触发 agent 任务

前提条件

在 Windows 上设置 Remote Control 之前：

Cursor 已安装在主机（被控制的机器）上
Node.js 18+ 已安装在主机和控制器上
Windows 10 或 11，配备 PowerShell 5.1+ 或 PowerShell 7
主机和控制器之间的网络访问（直接 TCP 或 SSH 隧道）
主机初始设置的管理员访问权限

设置 Remote Control Worker

worker 是主机机器的核心。它作为后台进程运行，处理所有传入命令。

步骤 1：安装 Worker

在主机 Windows 机器上：

# 全局安装 Cursor Remote Control worker
npm install -g @cursor/remote-worker

# 验证安装
cursor-remote-worker --version

步骤 2：初始化 Worker

# 使用项目路径初始化 worker
cursor-remote-worker init --project "H:\Projects\my-app"

# 这会在以下位置创建配置文件：
# %USERPROFILE%\.cursor-remote\config.json

生成的配置如下：

{
  "workerId": "win-worker-001",
  "projectPath": "H:\\Projects\\my-app",
  "port": 8473,
  "authToken": "auto-generated-token-here",
  "database": {
    "type": "sqlite",
    "path": "%USERPROFILE%\\.cursor-remote\\state.db"
  },
  "logLevel": "info",
  "maxConcurrentTasks": 3
}

提示

记下 authToken 的值。你需要它来配置控制器 CLI。把它当作密码一样对待。如果需要重新生成，运行 cursor-remote-worker regenerate-token。

步骤 3：启动 Worker

# 在前台启动 worker（用于测试）
cursor-remote-worker start

# 将 worker 安装为 Windows 服务（用于生产环境）
cursor-remote-worker install-service
cursor-remote-worker start-service

对于生产环境使用，将其安装为 Windows 服务以便在重启后保留：

# 验证服务是否正在运行
Get-Service -Name "CursorRemoteWorker"

# 预期输出：
# Status   Name               DisplayName
# ------   ----               -----------
# Running  CursorRemoteWorker Cursor Remote Worker

步骤 4：配置防火墙

worker 默认监听端口 8473。打开防火墙：

# 在 Windows 防火墙中开放端口
New-NetFirewallRule -DisplayName "Cursor Remote Worker" -Direction Inbound -Protocol TCP -LocalPort 8473 -Action Allow

# 验证规则是否已创建
Get-NetFirewallRule -DisplayName "Cursor Remote Worker"

注意

不要将端口 8473 暴露给公共互联网。worker 的身份验证是基于令牌的，但不是为不受信任的网络设计的。使用 VPN、SSH 隧道，或将防火墙规则限制为特定 IP 地址。公开暴露端口存在安全风险。

在控制器上配置 CLI

在你的本地机器（控制器）上，安装和配置 CLI 以与主机通信。

步骤 1：安装 CLI

npm install -g @cursor/remote-cli

# 验证
cursor-remote --version

步骤 2：添加远程主机

# 添加远程主机配置
cursor-remote add-host `
  --name "win-cloud-dev" `
  --host "192.168.1.100" `
  --port 8473 `
  --token "auto-generated-token-here" `
  --project "H:\Projects\my-app"

这会将配置存储在 %USERPROFILE%\.cursor-remote\hosts.json：

{
  "hosts": [
    {
      "name": "win-cloud-dev",
      "host": "192.168.1.100",
      "port": 8473,
      "token": "auto-generated-token-here",
      "project": "H:\\Projects\\my-app"
    }
  ]
}

步骤 3：测试连接

# Ping 远程主机
cursor-remote ping --host win-cloud-dev

# 预期输出：
# Connected to win-cloud-dev (192.168.1.100:8473)
# Worker version: 1.2.3
# Project: H:\Projects\my-app
# Status: ready

步骤 4：启动远程会话

# 打开交互式会话
cursor-remote session --host win-cloud-dev

# 你现在处于连接到远程 Cursor 实例的交互式提示符中
# 你输入的命令在主机机器上执行

远程运行 Agent 任务

连接后，你可以在远程主机上运行 agent 任务：

# 运行单个 agent 任务
cursor-remote agent --host win-cloud-dev --prompt "Refactor the authentication module to use JWT"

# 使用特定模型运行
cursor-remote agent --host win-cloud-dev --model claude-sonnet-4-0 --prompt "Add input validation to all API endpoints"

# 使用文件上下文运行
cursor-remote agent --host win-cloud-dev --files "src/auth/auth.ts,src/api/routes.ts" --prompt "Add rate limiting to these routes"

流式输出

默认情况下，agent 输出会实时流式传输到你的终端：

cursor-remote agent --host win-cloud-dev --prompt "Create a test file" --stream

这会显示每一步的执行情况，包括文件差异和工具执行。

提示

对于长时间运行的任务，使用 --detach 标志在主机上以后台方式运行任务。你稍后可以检查它：

# 启动一个分离的任务
cursor-remote agent --host win-cloud-dev --prompt "Write comprehensive test suite" --detach

# 检查任务状态
cursor-remote tasks --host win-cloud-dev --status running

# 获取任务输出
cursor-remote tasks --host win-cloud-dev --id task_abc123 --output

better-sqlite3 NODE_MODULE_VERSION 崩溃

这是 Windows 用户面临的最关键问题。worker 使用 better-sqlite3 作为其状态数据库，当主机上的 Node.js 版本与 better-sqlite3 编译时的版本不匹配时，worker 会崩溃，错误如下：

Error: The module 'H:\Projects\my-app\node_modules\better-sqlite3\build\Release\better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 127. This version of Node.js requires
NODE_MODULE_VERSION 137.

理解错误

better-sqlite3 是一个原生插件。它将 C++ 代码编译为特定于 Node.js ABI 版本的 .node 二进制文件。NODE_MODULE_VERSION 是一个对应于特定 Node.js 主版本的数字：

NODE_MODULE_VERSION	Node.js 版本
115	Node.js 18.x
120	Node.js 20.x
127	Node.js 22.x
137	Node.js 24.x

当 worker 使用 Node.js 22（MODULE_VERSION 127）安装，但你后来升级到 Node.js 24（MODULE_VERSION 137）时，预编译的二进制文件不再匹配。

修复 1：重新编译 better-sqlite3（推荐）

# 导航到 worker 安装目录
cd "$env:APPDATA\npm\node_modules\@cursor\remote-worker"

# 为当前 Node.js 版本重新编译原生模块
npm rebuild better-sqlite3

# 或者强制从源码重新编译
npm rebuild better-sqlite3 --build-from-source

提示

你需要 Visual Studio Build Tools（或带有 C++ 工作负载的完整 Visual Studio）来重新编译原生插件。如果你没有安装：

# 通过 npm 安装构建工具
npm install --global windows-build-tools

# 或者手动安装 Visual Studio Build Tools：
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

安装后，重启终端并重试重新编译。

修复 2：降级 Node.js

如果重新编译不可行，将你的 Node.js 版本匹配到 worker 期望的版本：

# 检查 worker 是用哪个 Node.js 版本构建的
# （查看错误消息中的 NODE_MODULE_VERSION）

# 安装 nvm-windows 进行版本管理
# https://github.com/coreybutler/nvm-windows
nvm install 22.0.0
nvm use 22.0.0

# 验证
node --version
# v22.0.0

# 重启 worker
cursor-remote-worker stop-service
cursor-remote-worker start-service

修复 3：使用预编译二进制文件

某些版本的 better-sqlite3 为常见平台提供了预编译二进制文件。如果你的组合可用：

# 安装一个带有预编译的 better-sqlite3 版本
npm install [email protected] --build-from-source=false

# 或者使用 prebuild-install 获取正确的二进制文件
npx prebuild-install --runtime node --target $(node -v)

修复 4：为 Worker 固定 Node.js 版本

为防止此问题再次出现，固定 worker 使用的 Node.js 版本，独立于你的开发 Node.js：

# 创建一个使用特定 Node.js 版本的包装脚本
# C:\cursor-worker\start-worker.bat
@echo off
set PATH=C:\Program Files\nodejs-v22\;%PATH%
node "C:\Program Files\nodejs-v22\node_modules\@cursor\remote-worker\bin\worker.js" start

然后配置 Windows 服务使用此批处理文件而不是默认入口点。

注意

如果你使用 nvm-windows 切换 Node.js 版本进行开发，每次切换都可能破坏 worker（如果它更改了系统范围的 Node.js 版本）。包装脚本方法（修复 4）是最可靠的长期解决方案，因为它将 worker 的 Node.js 版本与你的开发环境分离。

Worker 故障排查

Worker 无法启动

症状： cursor-remote-worker start 立即退出，没有输出。

诊断：

# 检查 worker 日志
Get-Content "$env:USERPROFILE\.cursor-remote\logs\worker.log" -Tail 50

# 检查端口是否已被占用
netstat -ano | findstr :8473

# 检查是否有另一个 worker 进程在运行
Get-Process -Name "node" | Where-Object { $_.CommandLine -like "*remote-worker*" }

修复：

终止占用端口 8473 的进程：Stop-Process -Id <PID> -Force
删除锁定文件：Remove-Item "$env:USERPROFILE\.cursor-remote\.lock"
使用详细日志启动：cursor-remote-worker start --log-level debug

Worker 启动但数据库已损坏

症状： Worker 启动，但所有操作都因 SQLite 错误而失败。

修复：

# 停止 worker
cursor-remote-worker stop-service

# 备份损坏的数据库
Copy-Item "$env:USERPROFILE\.cursor-remote\state.db" "$env:USERPROFILE\.cursor-remote\state.db.bak"

# 删除损坏的数据库（worker 会重新创建它）
Remove-Item "$env:USERPROFILE\.cursor-remote\state.db"

# 重启 worker
cursor-remote-worker start-service

提示

状态数据库只存储任务历史、worker 状态和会话元数据。删除它不会影响你的项目文件。你会丢失过去远程任务的历史记录，但 worker 在重新创建数据库后会正常运行。

Worker 间歇性断开连接

症状： CLI 有时可以连接但随机失败。

原因和修复：

防火墙规则过于严格 - 确保规则允许控制器的 IP 范围，而不仅仅是单个 IP
NAT/路由器超时 - 如果通过互联网连接，NAT 表条目可能过期。改用 SSH 隧道
电源管理 - Windows 可能使网络适配器进入休眠。禁用此功能：

# 禁用网络适配器上的电源管理
powercfg /devicequery wake_from_any
# 找到你的网络适配器，然后：
powercfg /devicedisablewake "Your Network Adapter Name"

杀毒软件干扰 - 某些杀毒软件会拦截 TCP 连接。将 worker 可执行文件和端口 8473 添加到排除项。

版本兼容性矩阵

确保所有组件之间的版本兼容性对于稳定的 Remote Control 操作至关重要。

组件	最低版本	说明
Cursor（主机）	0.45+	Remote Control 支持从此版本开始
@cursor/remote-worker	1.0.0+	Worker 包
@cursor/remote-cli	1.0.0+	CLI 包
Node.js（主机）	18.x, 20.x, 22.x	在 better-sqlite3 提供 137 构建之前避免使用 24.x
Node.js（控制器）	18.x+	更灵活，没有原生模块
better-sqlite3	11.0.0+	检查你的 Node 版本的预编译可用性
Windows	10 1903+ / 11	最低 PowerShell 5.1

注意

worker 和 CLI 版本必须兼容。运行 v1.0.0 的 worker 可能无法与运行 v1.5.0 的 CLI 一起工作（如果有破坏性协议更改）。升级任一组件时，请始终检查变更日志。如果你升级了一个，请同时升级另一个。

检查版本兼容性

# 在主机上，检查 worker 和数据库版本
cursor-remote-worker --version
cursor-remote-worker --check-deps

# 在控制器上，检查 CLI 版本
cursor-remote --version

# 检查 Node.js ABI 版本
node -e "console.log(process.versions.modules)"

--check-deps 标志运行一个诊断，检查：

Node.js 版本兼容性
better-sqlite3 二进制兼容性
所需的系统依赖
端口可用性
配置目录的写权限

高级配置

SSH 隧道设置

对于通过互联网的安全连接，使用 SSH 隧道：

# 在控制器上，创建到主机的 SSH 隧道
ssh -L 8473:localhost:8473 [email protected] -N

# 然后将 CLI 连接到 localhost
cursor-remote add-host `
  --name "win-tunneled" `
  --host "127.0.0.1" `
  --port 8473 `
  --token "auto-generated-token-here" `
  --project "H:\Projects\my-app"

这通过 SSH 加密隧道传输所有流量，比直接暴露端口安全得多。

多主机配置

你可以从一个控制器控制多台主机：

{
  "hosts": [
    {
      "name": "win-cloud-dev",
      "host": "192.168.1.100",
      "port": 8473,
      "token": "token-1",
      "project": "H:\\Projects\\my-app"
    },
    {
      "name": "win-build-server",
      "host": "192.168.1.101",
      "port": 8473,
      "token": "token-2",
      "project": "C:\\Builds\\ci-pipeline"
    }
  ]
}

在主机之间切换：

# 在特定主机上运行任务
cursor-remote agent --host win-build-server --prompt "Fix the failing CI pipeline test"

# 列出所有主机及其状态
cursor-remote hosts --status

环境变量注入

将环境变量传递给 worker 以用于 agent 任务：

cursor-remote agent `
  --host win-cloud-dev `
  --env "DATABASE_URL=Server=prod;Database=myapp;User=admin;Password=secret" `
  --env "NODE_ENV=production" `
  --prompt "Run the database migration and report results"

注意

通过 CLI 传递的环境变量在控制器和主机机器上的进程列表中可见。切勿通过这种方式传递真实的生产密钥。改用密钥管理器或具有受限权限的环境变量文件。

安全最佳实践

定期轮换认证令牌：cursor-remote-worker regenerate-token
使用 SSH 隧道用于任何穿越不受信任网络的连接
将防火墙规则限制为特定 IP 地址，而不是"任何"
尽可能以非管理员用户身份运行 worker
启用 worker 日志记录并每周审查日志以发现异常访问模式
在共享或云机器上不使用时禁用 worker
保持 worker 和 CLI 更新以获取安全补丁

总结

Windows 上的 Cursor Remote Control 是一项强大的功能，将 AI 辅助开发扩展到远程和无头机器。设置涉及主机上的 worker 进程和控制器上的 CLI，通过 TCP 通信。最常见的崩溃——better-sqlite3 NODE_MODULE_VERSION 127 vs 137——是由 Node.js 版本不匹配引起的，可以通过为当前 Node.js 版本重新编译原生插件或将 worker 固定为特定 Node.js 安装来解决。通过遵循本指南中的版本兼容性指导和安全最佳实践，你可以在 Windows 上维护稳定、安全的 Remote Control 设置。

什么是 Cursor Remote Control？​

使用场景​

前提条件​

设置 Remote Control Worker​

步骤 1：安装 Worker​

步骤 2：初始化 Worker​

步骤 3：启动 Worker​

步骤 4：配置防火墙​

在控制器上配置 CLI​

步骤 1：安装 CLI​

步骤 2：添加远程主机​

步骤 3：测试连接​

步骤 4：启动远程会话​

远程运行 Agent 任务​

流式输出​

better-sqlite3 NODE_MODULE_VERSION 崩溃​

理解错误​

修复 1：重新编译 better-sqlite3（推荐）​

修复 2：降级 Node.js​

修复 3：使用预编译二进制文件​

修复 4：为 Worker 固定 Node.js 版本​

Worker 故障排查​

Worker 无法启动​

Worker 启动但数据库已损坏​

Worker 间歇性断开连接​

版本兼容性矩阵​

检查版本兼容性​

高级配置​

SSH 隧道设置​

多主机配置​

环境变量注入​

安全最佳实践​

总结​