《Cursor文档》-我的机器

“我的机器”是个人版的自托管机器配置。它允许特定用户在自己已使用的机器上运行云端代理的工具调用，例如笔记本电脑、devbox 或远程 VM。当某台机器正是某个仓库所需的执行环境时，就适合使用此功能。

你机器上的一个 worker 会向 Cursor 发起出站连接。智能体循环运行在 Cursor 云中，但终端命令、文件编辑、浏览器操作以及其他工具调用都在你的机器上执行。无需开放入站端口，也无需修改防火墙。

对大多数团队来说，Cursor-managed 云端代理都是推荐方案，包括
需要访问私有网络的团队。你可以使用网络允许列表、
Tailscale 或类似客户端，以及针对受支持源代码
管理路径的私有网络连接，而无需自行运行 worker。请参阅选择云端代理
的运行位置。

如果你想要以下能力，请使用“我的机器”：

使用已具备你的仓库和工具的 devbox 或远程工作站
在某个用户的机器上为特定仓库执行工具调用
复用你不想在云环境中重新创建的机器本地状态
在搭建集中管理的用量池之前，先体验 worker 模式

如需为整个组织管理 worker fleet，请参阅团队用量池。

快速开始¶

1. 安装命令行界面¶

# macOS、Linux 和 WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

确认 CLI 可用：

agent --version

2. 登录¶

对于个人设备，使用浏览器登录最简单：

agent login

3. 启动 worker¶

agent worker start

在你使用这台机器期间，请保持此进程运行。默认情况下，我的机器 worker 是长驻的：它会一直保持连接，直到你手动停止，并且可在后续的云端代理会话中重复使用。

4. 运行智能体¶

前往 cursor.com/agents。
该机器应会显示在“环境”下拉菜单中。
发送任务。

Cursor 的“运行于”菜单，“我的机器”下高亮显示 my-devbox

通用选项¶

为机器命名¶

如果同一仓库有多台机器，请使用便于区分的名称：

agent worker start --name "my-devbox"

在其他仓库目录中运行¶

agent worker start --worker-dir /path/to/repo

重复指定 --worker-dir 可注册多个代码仓库根目录：

agent worker \
  --worker-dir "$HOME/repos/app" \
  --worker-dir "$HOME/repos/infra" \
  start

每个 path 都必须存在。对于每个配置了 git remote 的 root，worker 会注册 routing metadata，以便 Cursor 将 requests 匹配到正确的 checkout。

使用 API 密钥¶

在 devbox 或不便通过浏览器登录的自动化场景中，请使用 Cursor 仪表盘 → API 密钥中的个人用户 API 密钥：

agent worker start --api-key "your-user-api-key"

我的机器 worker 需要个人凭据：浏览器登录、个人用户 API 密钥或用户级 token。服务账户 API
密钥只能启动用量池 worker
(--pool) ，而团队 Admin API 密钥和组织 API 密钥则完全无法启动
worker。如需团队共享的 worker，请参阅自托管用量池。

使用用户级 token¶

对于自行管理的单用户 worker，请先通过 POST /v1/sub-tokens 创建一个短期有效的用户级 token，然后用该 token 启动 worker：

agent worker start --auth-token "your-user-scoped-token"

对于长期运行的 worker，请从文件中读取 token：

agent worker start --auth-token-file /var/run/cursor/token

这在 Kubernetes 中很有用，因为来自 Secrets 的环境变量在 pod 启动时就固定了。Secret 卷会在 pod 运行期间更新，而挂载的 token 路径可以在 pod 内实时更新，因此你可以在 pod 运行时刷新 token。

启用计算机使用¶

在 start 前传入 --computer-use，让智能体能在本机上点击、输入、截取屏幕截图并操作应用：

agent worker --computer-use --name "my-mac" start

在 macOS 上，首次启动会安装 Cursor Computer Use 辅助应用。请在“系统设置 → 隐私与安全性”中为其授予辅助功能和屏幕录制权限，然后用一个需要屏幕截图的任务进行测试。在 Linux 上，请先安装桌面端软件包。有关 macOS 权限设置步骤、MDM 指南以及 Linux 显示选项，参见计算机使用与桌面共享。

通过聊天入口触发这台机器¶

当你希望 Slack、GitHub 或 Linear 中的请求在你已命名的某台机器上运行时，请使用 worker= 或 machine=。这是仅有的以“我的机器”为目标的触发选项。

使用 --name 启动机器，然后在请求中带上该名称：

在 Slack 中，使用 @Cursor worker=my-devbox fix the flaky test 或 @Cursor machine=my-devbox fix the flaky test。
在 GitHub 中，在评论里使用 @cursoragent worker=my-devbox fix the flaky test 或 @cursoragent machine=my-devbox fix the flaky test。你必须是受信任的仓库评论者，并且目标机器必须属于与你的 GitHub 账户关联的 Cursor 账户。
在 Linear 中，将 worker=my-devbox 或 machine=my-devbox 添加到 issue 正文中。你也可以使用名为 worker 或 machine 的父级标签，并搭配名为 my-devbox 的子标签。

Cursor 如何选择你的机器¶

只有当以下三个条件都满足时，worker=<name> 请求才会在某台机器上运行：

该机器属于触发此请求的 Cursor 用户。
该机器的 --name 与请求中的 <name> 匹配。
该机器注册的仓库与触发器的目标仓库匹配。

触发器的目标仓库来自触发界面，而不是机器名称：

Slack 会优先使用你消息中的 repo= (如果有) ，然后依次使用频道默认仓库、你的用户默认仓库，以及团队默认仓库。
Linear 会使用从 issue 或 project 解析出的仓库 (例如 [repo=]、issue labels、project labels 或仪表盘默认值) 。参见 Repository selection。
GitHub 会使用提及 @cursoragent 的 issue、PR 或评审评论所在的仓库。

每台机器注册的仓库来自其 worker 目录中的 git remote。若要让一台机器为多个仓库提供服务，可为每个 checkout 分别传入一次 --worker-dir，或在每个仓库的 checkout 中分别启动一个 worker。

当 `worker=` 请求无法运行时¶

如果你有一台同名机器，但它注册的是另一个仓库，Cursor 会拒绝该请求，而不是让它在错误的 checkout 上运行：

worker=<name> 已注册到你的机器上，但对应的是另一个代码仓库。请先在目标仓库的 checkout 中启动 worker。

这个错误会显示为 Slack 中的临时回复、Linear 中的智能体活动错误，以及 GitHub 上给受信任评论者的 @cursoragent 回复。这是有意设计的行为：针对仓库 A 的请求绝不应该在仓库 B 的机器 checkout 上运行。

如果没有机器同时匹配已关联的用户和目标仓库，该请求会直接失败，而不会回退到其他环境。请确认机器名称、你的 Cursor 账户关联状态，以及 worker 目录的 git remote。

单独使用 self_hosted、pool= 和 repo= 并不会将目标指向我的机器。请将它们与团队用量池 worker 一起使用。当你将 repo= 与 worker= 搭配使用时，它会指定 Cursor 用来与你的机器匹配的仓库。

钩子¶

我的机器 worker 与其他自托管机器 worker 运行相同的钩子：即你启动 worker 所在工作区中 .cursor/hooks.json 里基于命令的钩子。在企业版中，它还会运行团队钩子和企业托管钩子。

用量池上的钩子介绍了在 worker 上生效的内容，包括 session 占用和释放机器时触发的 sessionStart 与 sessionEnd。钩子参考介绍了 schema、事件和示例。

制品¶

制品在自托管 workers 和 Cursor 托管的智能体上的行为完全一致。智能体在 worker 内生成制品，再由 worker 通过 HTTPS 上传到 Cursor 管理的存储中。所有后续环节 (PR 嵌入、仪表盘预览、通知附件) 都由 Cursor 的后端处理，不取决于 worker 在何处运行。

制品默认启用。有关它们在 UI 中的显示方式，请参阅能力。

要禁用制品上传，请阻止发往 cloud-agent-artifacts.s3.us-east-1.amazonaws.com 的出站流量。智能体会话仍会继续运行；但会话期间生成的制品将无法上传。

网络¶

worker 需要能够通过出站 HTTPS 访问：

api2.cursor.sh 和 api2direct.cursor.sh，用于智能体会话
downloads.cursor.com，用于命令行界面更新以及在 macOS 上首次安装 Cursor Computer Use
cloud-agent-artifacts.s3.us-east-1.amazonaws.com，用于上传制品

如果你的防火墙只能匹配通配符，*.s3.us-east-1.amazonaws.com 可以覆盖制品主机，但也会同时放开该区域内的所有其他 bucket。防火墙支持时，优先使用精确匹配主机的规则。

不需要入站端口、公开 IP 或 VPN 隧道。如果你使用代理，请在 worker 环境中设置 HTTPS_PROXY 或 https_proxy。

故障模式¶

如果你屏蔽…	影响
`api2.cursor.sh` or `api2direct.cursor.sh`	worker 将无法启动或继续智能体会话。
`downloads.cursor.com`	命令行界面更新以及在 macOS 上首次安装 Cursor Computer Use 会失败。已安装两者的 worker 仍可继续运行。
`cloud-agent-artifacts.s3.us-east-1.amazonaws.com`	制品上传会失败。依赖制品的 PR 嵌入、仪表盘预览和通知附件将会缺失。智能体会话和其他工具调用仍可继续工作。
特定工具或集成所需的某个出站主机	只有该工具或集成会失效。智能体会继续运行。

MCP 服务器¶

MCP 服务器按传输类型路由：

Transport	Runs on	Use case
Command (stdio)	你的机器	MCP 进程会在你的机器上启动，因此可以访问私有网络、内部 API 和本地服务。
HTTP / SSE (url)	Cursor backend	对于基于 HTTP 的 MCP 服务器，Cursor 会在后端处理 OAuth、会话缓存和认证。

如果你的 MCP 服务器需要访问私有网络中的端点，请使用 Command (stdio) 传输。该进程会直接在你的机器上运行，并使用你机器所在的网络。对于基于 HTTP 的 MCP 服务器，连接由 Cursor 后端管理。

疑难排查¶

运行预检调试报告：

agent worker debug

这会检查身份验证、隐私路由、仓库标签，以及 Cursor 能否找到匹配的 worker。若要在启动 worker 前打印同样的诊断信息，请使用 agent worker start --debug。

如果机器未出现在选择器中：

确认 worker 进程仍在运行。
确认 Cursor 应用和命令行界面使用的是同一账户。
检查 worker 目录是否配置了预期的 Git remote。
检查是否能出站访问网络中列出的主机。

如果在 Mac 上计算机使用失败，该报告只能确认是否已安装 Cursor Computer Use，而无法确认其权限是否已授予。请在“系统设置 → 隐私与安全性”中为 Cursor Computer Use 授予 辅助功能 和 屏幕录制 权限，然后重试一个屏幕截图任务。参见 macOS。

后续步骤¶

计算机使用：让 agents 在你的机器上操作桌面和浏览器，并在 Cursor 中查看或控制智能体桌面。
API 参考文档：worker、用量池、待处理请求队列以及 worker token 相关的端点。