Cursor Local Remote：本地Web服务器实现AI编程助手远程控制

1. 项目概述一个让你在沙发上也能“写代码”的本地远程控制台如果你和我一样是个重度依赖 Cursor 的开发者那你肯定经历过这种场景一个复杂的重构或者调试任务跑起来了你正盯着屏幕等结果但突然内急或者咖啡喝完了想去续一杯又或者只是想瘫在沙发上换个姿势。这时候你是选择守在电脑前还是忍痛中断那个可能正在生成关键代码的 Agent 会话“Cursor Local Remote”简称 CLR就是为解决这个“甜蜜的烦恼”而生的。它不是什么复杂的云服务也不是需要配置端口转发的远程桌面。它的核心思路极其简单粗暴在你的本地电脑上启动一个轻量的 Web 服务器然后你手机、平板或者家里任何一台连入同一个 Wi-Fi 的设备打开浏览器就能看到一个专为移动端优化的控制面板。通过这个面板你可以实时监控 Cursor Agent 的工作状态、发送新的指令、查看 Git 变更、甚至操作终端——所有操作都直接发生在你本地主机的 Cursor CLI 上数据不出家门延迟几乎为零。简单来说它把你手机变成了一个 Cursor 的“高级遥控器”。我最初开发它纯粹是因为自己懒不想在厨房盯着锅的时候还得跑回书房看代码生成完了没有。但用了一段时间后发现它的价值远不止于此。在代码评审时我可以把平板支在旁边随时查看不同分支的差异在客厅电视上放电影时也能顺手给跑偏的 Agent 点个“停止”或者“重试”。这种“无感”的、跨设备的开发流一旦习惯就回不去了。注意CLR 设计用于受信任的本地网络环境比如你的家庭或办公室 Wi-Fi。它虽然提供了基础的 Token 认证来防止同一网络内其他设备的误访问但其安全机制并非为对抗恶意攻击而设计。切勿在公共或不安全的网络中使用。2. 核心设计思路为什么是本地 Web 而非其他方案在决定动手造这个轮子之前我其实评估过几种常见的远程控制方案但都觉得不够“优雅”或“顺手”。2.1 方案对比与选型理由传统远程桌面RDP/VNC重量级传输整个桌面图像带宽和延迟在移动网络下体验不佳且无法针对“监控和轻量控制 Cursor Agent”这个特定场景做优化。SSH Tmux极客范十足但移动端 SSH 客户端的操作体验尤其是触屏对多数人不够友好需要记忆命令且无法获得 Cursor Agent 原生的流式输出和结构化会话视图。第三方云中继服务需要公网 IP、配置繁琐且将你的开发会话数据经过第三方服务器有隐私和安全顾虑。本地 Web 服务器CLR 方案零配置几乎开箱即用依赖少只需 Node.js 和 Cursor CLI。最佳体验利用现代 Web 技术Next.js, SSE, PWA可以构建出响应迅速、界面友好的移动端 Web App甚至能安装到手机主屏幕。数据本地化所有通信都在局域网内完成你的代码、会话历史不会离开你的机器。协议复用直接与 Cursor 官方的agentCLI 对话保证了功能的完整性和未来兼容性。2.2 架构拆解数据是如何流动的CLR 的架构非常清晰可以理解为一座连接你移动设备和你本地 Cursor 的“桥梁”。你的手机/平板 (浏览器) │ │ (HTTP/HTTPS, WebSocket/SSE over LAN) ▼ CLR Web 服务器 (运行在你电脑上默认端口 3100) │ │ (子进程调用标准输入输出) ▼ Cursor agent CLI (运行在你电脑上) │ │ (读写本地文件系统) ▼ 你的项目文件 Cursor 会话元数据前端层浏览器一个 React 构建的响应式界面。它通过调用 CLR 服务器提供的 RESTful API 获取数据如会话列表、Git 状态并通过 Server-Sent Events (SSE) 长连接来实时接收agent执行任务时的流式输出。服务层CLR 服务器一个基于 Next.js 的 Node.js 服务器。它是整个系统的中枢负责提供 Web 界面。接收来自前端的指令如“/api/chat” 发送新提示词。管理agent子进程的生命周期启动、停止、流式读取输出。读取 Cursor 在本机存储的会话历史文件位于~/.cursor/projects/从而聚合所有会话无论它们是由 IDE 还是由 CLR 自身启动的。执行层Cursor CLICLR 服务器在需要执行任务时会以“无头”模式启动 Cursor 的agent命令例如agent -p 你的提示词 --output-format stream-json。这个agent进程拥有和你在 Cursor IDE 中启动的 Agent 完全相同的权限和能力可以编辑文件、运行命令、访问网络等。这种分层设计使得关注点分离前端只管展示和交互服务层负责协调和通信最终脏活累活由官方的、最稳定的agentCLI 来完成。这也意味着只要 Cursor 官方 CLI 的功能在更新CLR 就能天然地享受到新能力。3. 从零开始安装、配置与首次启动这部分是实操的开始我会尽量详细确保无论你的环境如何都能顺利跑起来。3.1 前置条件检查在安装 CLR 之前请确保你的“地基”是牢固的。Node.js 20这是运行 CLR 服务器的引擎。打开终端运行node --version确认版本。如果版本低于 20建议通过 nvm Mac/Linux或 nvm-windows 管理工具进行安装和升级这比直接覆盖系统 Node 更安全。Cursor IDE 及有效订阅你需要安装 Cursor 并拥有一个活跃的 Pro 或 Team 订阅。CLR 依赖于 Cursor 的付费功能。Cursor CLI (agent) 已安装并可用这是最关键的一步。打开终端输入agent --version并回车。你应该能看到类似cursor-agent 0.xx.x的版本信息。如果提示“command not found”你需要回到 Cursor IDE 内进行安装在 Cursor 中按下Cmd/Ctrl Shift P打开命令面板。输入 “Install Cursor Agent CLI” 并选择该命令。这通常会在后台下载并将agent命令添加到你的系统 PATH 中。安装完成后关闭并重新打开你的终端再次尝试agent --version。3.2 一键安装与启动条件满足后安装过程简单得令人发指。# 全局安装 CLR npm install -g cursor-local-remote安装完成后你就可以在任何终端中使用clr命令了。最基础的启动方式是进入你的项目目录cd ~/your-awesome-project clr执行这个命令后终端里会发生几件事CLR 会启动一个 Next.js 开发服务器虽然是生产构建版。它会自动在你的默认浏览器中打开一个标签页指向http://localhost:3100如果你没有禁用--no-open选项。同时终端会打印出一个巨大的二维码和一行访问地址例如http://192.168.1.100:3100?tokenalpine-berry。这个地址就是你从其他设备访问的入口。3.3 首次连接与认证拿起你的手机确保它连接的是同一个 Wi-Fi 网络。你有两种方式连接扫码连接推荐直接用手机摄像头扫描终端里显示的二维码。手机会自动跳转到带有 Token 参数的完整 URL。这是最无缝的方式。手动输入在手机浏览器地址栏手动输入终端里显示的那个http://192.168.1.100:3100?token...地址。首次访问时CLR 会通过 URL 中的 Token 为你设置一个为期 7 天的 HTTP-only Cookie。之后在同一设备上访问http://你的电脑IP:3100就会自动登录无需再次输入 Token。实操心得关于 IP 地址和端口192.168.1.100是你电脑在局域网内的私有 IP。如果重启路由器或电脑这个地址可能会变。CLR 每次启动都会打印出当前使用的 IP以它为准。如果端口3100被占用你可以通过clr --port 8080指定其他端口。如果你只想本机访问比如测试可以使用clr --host 127.0.0.1这样服务器只绑定到 localhost局域网其他设备将无法访问。4. 功能深度游不止是“遥控器”成功连接后你会看到一个简洁但功能强大的界面。我们来逐一拆解它的核心模块以及我日常使用中的一些技巧。4.1 会话管理你的跨设备编程记忆这是 CLR 的核心。界面左侧或顶部通常会有一个“Sessions”面板。实时监控所有正在运行的 Agent 会话包括在 Cursor IDE 里启动的都会在这里以列表形式实时显示。你可以看到会话 ID、状态运行中/已完成、使用的模型和简短的提示词开头。点击任何一个会话就能进入详情页看到完整的、实时流式更新的对话记录包括 Agent 的思考过程、调用的工具如编辑了哪个文件、执行的命令等。这比跑回书房看屏幕直观多了。启动新会话点击“New Session”按钮输入你的提示词选择模型如 GPT-4o、Claude 3.5 Sonnet和模式如 Auto, Fast, Chat然后发送。一个新的agent进程就会在你的电脑上启动并将流式结果推送到你的手机屏幕上。历史会话浏览与恢复CLR 会读取~/.cursor/projects/下的所有会话历史文件。这意味着你可以在手机上浏览所有历史会话包括那些很久以前在 IDE 中完成的。你可以搜索、筛选甚至“恢复”一个历史会话——这实际上是以该历史会话的全部上下文作为起点开启一个新的 Agent 对话非常适合继续之前未完成的工作。重要限制与理解由 CLR 远程启动的会话其对话记录不会实时显示在 Cursor IDE 的侧边栏聊天窗口中。这是因为 Cursor IDE 的会话状态管理是内部化的。但是Agent 所做的所有实质性工作修改文件、运行命令都真实地发生在你的项目里。并且这些会话文件最终会被保存之后在 CLR 和 IDE 中都能看到历史记录。所以你可以把 CLR 看作一个独立的、功能完整的 Agent 启动和控制前端。4.2 Git 集成移动端代码版本管理这是我个人非常喜欢的功能。在 CLR 的 Git 面板中你可以查看状态一目了然地看到哪些文件被修改M、新增A或删除D。查看差异点击任一文件可以展开查看具体的代码改动diff绿色是新增红色是删除。执行操作你可以暂存Stage或取消暂存Unstage文件输入提交信息Commit Message后直接提交甚至进行推送Push和拉取Pull操作。你还可以切换分支、查看分支列表。使用场景当你在沙发上用 CLR 让 Agent 写了一段新功能并测试通过后可以直接在手机上完成git add .,git commit -m “feat: add mobile-controlled feature”,git push这一套操作。整个代码提交流程无需触碰电脑。4.3 终端访问CLR 提供了一个简单的 Web 终端。你可以执行一些基础的 shell 命令比如ls,cat,npm run dev来启动开发服务器或者pkill某个进程。这对于快速检查、重启服务非常有用。当然它不是一个功能全备的终端模拟器复杂的交互式操作如vim可能体验不佳但应付大多数检查任务绰绰有余。4.4 通知系统让 Agent “叫你”这是保证你“人机分离”时不错过任务完成的关键。CLR 提供了两套通知机制内置浏览器通知当 Agent 完成任务时即使 CLR 的浏览器标签页在后台标签页标题也会闪烁变成“Done! - CLR”或“Error - CLR”标签页图标favicon会带上一个彩色角标并且会播放一个提示音。当你切回标签页会看到一个结果横幅。这不需要任何配置。Webhook 外发通知强烈推荐配置这可以实现真正的“推送”通知即使手机锁屏、浏览器关闭也能收到。你需要在 CLR 的 Settings 面板中配置一个 Webhook URL。当 Agent 完成时CLR 会向这个 URL 发送一个 POST 请求。配置示例以 Discord 为例在 Discord 服务器中进入频道设置 - 集成 - Webhook创建一个新的 Webhook复制生成的 URL。在 CLR 的 Settings 页面将 URL 粘贴到 “Webhook URL” 字段。点击 “Send test”。如果你的 Discord 频道里立刻收到了一条来自 Webhook 的测试消息说明配置成功。现在每当 Agent 完成任务你的 Discord或 Slack、Telegram 等就会收到一条消息你可以真正地“放下手机安心等通知”。4.5 多项目管理与收藏如果你在多个项目间切换CLR 可以自动发现你机器上所有的 Cursor 项目通过扫描~/.cursor/projects/目录。你可以在项目间快速切换并将常用项目加星标收藏方便快速访问。5. 高级配置与命令行参数详解clr命令提供了丰富的选项来适应不同场景。5.1 常用启动参数参数全称说明使用场景示例[workspace]-指定项目路径。clr ~/projects/my-app直接启动并管理指定项目。-p, --port--port指定服务器端口。clr --port 8080在 8080 端口运行避免与其它服务冲突。--host--host绑定到特定网络接口。clr --host 127.0.0.1仅允许本机访问最安全。clr --host 0.0.0.0允许所有网络接口访问默认。-t, --token--token设置固定的认证 Token。clr --token my-super-secret避免每次启动生成随机 Token方便记忆或脚本化。--no-open--no-open不自动打开浏览器。在无图形界面的服务器或 SSH 会话中启动时使用。--no-qr--no-qr不显示二维码。同上或当你不需要扫码时。--no-trust--no-trust禁用工作区信任。启用后Agent 在执行任何文件编辑或命令前都会请求确认更安全。-l, --list--list列出所有已发现的 Cursor 项目。clr --list快速查看可以管理的项目列表。--status--status检查 CLR 是否已在运行。避免重复启动多个实例。-u, --update--update更新 CLR 到最新版本。替代npm install -g cursor-local-remote的快捷方式。5.2 环境变量配置对于需要固定配置的场景使用环境变量更优雅。你可以在 shell 的配置文件如~/.bashrc,~/.zshrc中设置或者创建一个启动脚本。# 示例在 ~/.zshrc 中设置 export AUTH_TOKENmy-permanent-token export PORT3200 # CURSOR_TRUST1 # 取消注释以默认信任所有操作谨慎使用然后每次启动只需clr就会自动使用这些配置。5.3 作为后台服务运行Linux/macOS如果你希望 CLR 在开机后自动启动或者在后台持续运行可以借助systemd(Linux) 或launchd(macOS)或者更简单点使用pm2这样的进程管理工具。使用pm2的示例# 1. 全局安装 pm2 npm install -g pm2 # 2. 使用 pm2 启动 CLR 并设为后台守护进程 pm2 start clr --name cursor-remote -- ~/my-project --port 3100 --token my-token # 3. 设置 pm2 开机自启 pm2 startup pm2 save这样CLR 就会在后台稳定运行即使你关闭终端也不会停止。通过pm2 logs cursor-remote可以查看日志。6. 常见问题排查与实战技巧在实际使用中你可能会遇到一些小问题。这里我整理了一份“急救手册”。6.1 连接类问题问题手机扫描二维码或输入 IP 后无法连接显示“无法访问此网站”。排查 1检查 IP 地址。确保手机和电脑在同一个子网通常就是同一个 Wi-Fi。在电脑上运行ifconfig(Mac/Linux) 或ipconfig(Windows) 查看正确的局域网 IP通常是 192.168.x.x 或 10.x.x.x。CLR 启动时打印的 IP 应是这个。排查 2检查防火墙。电脑的防火墙可能阻止了 3100 端口的入站连接。你需要添加一条规则允许 TCP 端口 3100 的入站连接。排查 3检查主机绑定。你是否用了clr --host 127.0.0.1这会导致只允许本机访问。请使用clr --host 0.0.0.0默认或直接指定电脑的局域网 IP。问题连接后提示“Unauthorized”或认证失败。排查Token 不匹配。确保你访问的 URL 中包含正确的 Token 参数?tokenxxx。最可靠的方式永远是扫描终端新生成的二维码。如果设置了固定的AUTH_TOKEN环境变量请确认启动时使用了它。6.2 Agent 执行类问题问题通过 CLR 发送提示词后Agent 没有反应或立即失败。排查 1检查 Cursor CLI。在电脑终端直接运行agent -p “test”看是否能正常工作。如果失败可能是 Cursor CLI 未安装或订阅过期。排查 2查看 CLR 服务器日志。启动 CLR 时加上-v(verbose) 标志clr -v。这会在终端打印详细的服务器和 Agent 进程日志从中可以看到错误信息。排查 3工作区路径问题。确保你启动 CLR 时所在目录或指定的[workspace]是一个有效的、包含.cursor配置的项目目录。问题Agent 的任务执行了但我看不到文件被修改排查可能是 Agent 运行在错误的目录下。在 CLR 的界面中确认顶部显示的工作区路径是你的目标项目路径。你也可以在发送提示词时在输入框下方确认或选择正确的工作区。6.3 性能与体验优化技巧 1使用 PWA 安装到手机桌面。在手机浏览器中打开 CLR 界面通常地址栏会有“添加到主屏幕”或“安装应用”的提示。这将创建一个独立的 App 图标启动更快体验更接近原生 App。技巧 2管理长时间运行的任务。对于非常耗时的任务记得在 CLR 中开启通知。你也可以随时在“Active Sessions”列表中点击“Stop”来终止一个正在运行的 Agent。技巧 3清理历史会话。CLR 会加载所有历史会话如果项目很多、历史很久初次加载可能会慢。你可以定期在 Cursor IDE 内或直接删除~/.cursor/projects/下不必要的老项目文件夹来清理。CLR 界面也提供了归档和删除会话的功能。6.4 安全提醒再强调这是一个本地工具安全性建立在你的网络环境可信的基础上。绝对不要在咖啡厅、机场等公共 Wi-Fi 下使用。如果家里有访客网络尽量让访客使用独立的网络段。使用--token设置一个强密码避免使用简单的默认 Token。考虑结合系统防火墙只允许特定设备 IP 访问 3100 端口。7. 开发与贡献如果你也想动手改进CLR 本身是开源的MIT 协议如果你对它的功能有更多想法或者遇到了 Bug欢迎参与贡献。整个项目都是用 Cursor 开发的这本身就是一个有趣的递归。7.1 本地开发环境搭建git clone https://github.com/jon-makinen/cursor-local-remote.git cd cursor-local-remote npm install npm run dev # 启动开发服务器通常在本地的 3000 端口开发服务器运行后你可以像使用生产版本一样通过局域网 IP 和端口如http://192.168.1.100:3000从手机访问并享受代码热重载。7.2 项目结构导读/appNext.js 13 的 App Router 结构包含了所有前端页面和 API 路由。/app/api/所有后端 API 端点如chat,sessions,git的实现都在这里。这是与 Cursor CLI 交互的核心。/app/page.tsx主界面。/lib工具函数和核心逻辑比如与agent进程通信的agent-client读取会话文件的session-loader。/componentsReact UI 组件。cli.js命令行入口点处理clr命令的参数解析和服务器启动。7.3 可能的改进方向从我自己的使用和社区反馈来看有几个方向值得探索更强大的终端集成一个功能更完整的 Web 终端模拟器比如支持分屏、更好的触屏键盘交互。文件浏览器/编辑器在 Web 界面中直接浏览项目树甚至对单个文件进行轻量级的查看和编辑。插件系统允许社区贡献自定义的视图或集成例如直接显示数据库状态、服务器监控图表。更细粒度的权限控制针对“只读监控”和“全权控制”提供不同的 Token 权限。CLR 的初衷是解决一个非常具体、微小的痛点但它的实现方式打开了一扇门让我们看到本地 AI 辅助开发工具与轻量级远程控制结合的巨大潜力。它不试图取代你的 IDE而是作为 IDE 的一个无缝延伸让你在需要离开电脑时依然能保持对编码流程的感知和控制。这种“松弛感”或许才是高效开发的下一个形态。