Cursor CLI 上手：安装之后第一件事是把认证和权限理清

2026-08-18

装一个终端里的编码 agent，真正卡住人的往往不是提示词怎么写，而是三件更土的事：命令到底叫什么、认证走哪条路、第一次跑起来的时候它被允许动什么。这三件事在 Cursor 的文档里分散在四五页上，翻的顺序不对就会来回折腾。

先说一个最容易踩的点：Cursor CLI 安装完成后，你在终端里敲的命令名不是 cursor，而是 agent。官方《Installation》页里的验证命令写的就是 agent --version，《Parameters》页的命令表里所有条目也都是 agent login、agent status 这样的形式。如果你按产品名去猜命令名，第一步就会失败。

一、安装：两条路，别混着用

《Installation》页把安装分成两组，按你实际在哪个终端里工作选一组，不要交叉。

macOS、Linux 以及 Windows 上的 WSL，用同一条命令：

curl https://cursor.com/install -fsS | bash

Windows 原生环境（不经过 WSL），文档给的是 PowerShell 命令：

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

装完以后验证：

agent --version

《Installation》页的「Post-installation setup」这一节，给的是把 ~/.local/bin 加进 PATH 的做法，并且分别列了 bash 与 zsh 两种写法：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

这里有个需要如实说明的缺口：这一节的 PATH 设置只覆盖了 bash 和 zsh，Windows 原生环境下 PATH 该怎么配，官方文档在这一页没有说明。所以如果你在 PowerShell 里装完敲 agent 提示找不到命令，不要以为是自己漏了哪一步，这一段本来就没有对应的官方说明。

更新方面，《Installation》页写明 CLI 默认会尝试自动更新，手动更新用 agent update。切换发布通道这件事口径不太一致：cursor.com/help 的 CLI 帮助页里写的是 agent set-channel lab，但《Parameters》页的命令表里并没有列出这个子命令，只在配置文件的可选字段里有一个 channel（描述是 CLI 更新使用的发布通道）。两处对得上的部分是「通道这个概念存在」，具体命令名以官方文档最新内容和 agent --help 的实际输出为准。

二、前置条件：这一段别跳

在敲第一条命令之前，有几件事最好先确认，否则后面排查起来会绕远路。

你在哪个平台上。 这不只影响安装命令。《Configuration》页给出的配置文件位置就是分平台的：

类型	平台	路径
Global	macOS/Linux	`~/.cursor/cli-config.json`
Global	Windows	`$env:USERPROFILE\.cursor\cli-config.json`
Project	All	`<project>/.cursor/cli.json`

同一页还写明了一条约束：只有 permissions 可以在项目级配置，其它 CLI 设置都必须放在全局配置里。有人会想把团队的模型偏好、显示选项之类的东西提交进仓库，按这句话是行不通的。

Windows 用户额外注意一条。 CLI 的 changelog 里写明，Windows 的卸载程序可以选择删除 Cursor 的用户数据，其中包括存放 CLI 凭据的 ~/.cursor 目录。也就是说卸载重装一轮之后需要重新认证，这不是 bug。

你的网络是不是走代理。 《Configuration》页的「Proxy configuration」一节给了环境变量写法：

export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
export NODE_USE_ENV_PROXY=1

如果代理做 SSL 中间人检查，同一节还要求信任组织的 CA 证书：

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca-cert.pem

另外文档写明，有些企业代理不支持 HTTP/2 双向流，可以在配置里把 agent 连接切到 HTTP/1.1（对应字段是 network.useHttp1ForAgent，默认 false），切换后走 HTTP/1.1 加 SSE。

三、认证：两条路径，按用途选

《Authentication》页开门见山写明 Cursor CLI 支持两种认证方式：浏览器登录（官方标注为 recommended）和 API key。

浏览器这条路的三条命令是：

agent login
agent status
agent logout

agent login 会打开默认浏览器让你用 Cursor 账号认证，完成后凭据存在本地。这里有个对远程开发很关键的开关：设置 NO_OPEN_BROWSER=1 可以只打印登录 URL 而不打开浏览器。SSH 进服务器、或者在容器里操作时，这一条基本是必须的，文档的 Troubleshooting 一节也把 NO_OPEN_BROWSER=1 agent login 列为「浏览器打不开」的处置办法。

API key 这条路是给自动化、脚本、CI 环境用的。文档写明先在 Cursor Dashboard 的 API Keys 页生成一个 user API key，然后有两种提供方式，官方把环境变量标为 recommended：

export CURSOR_API_KEY=<YOUR_API_KEY>
agent "implement user authentication"

另一种是命令行参数 --api-key。从安全角度说，命令行参数会进入 shell 历史与进程列表，这属于通用运维常识、不是 Cursor 官方文档的内容，你自己按环境评估。

还有一条藏在 changelog 里、但对容器场景很有用：文档写明设置 AGENT_CLI_CREDENTIAL_STORE=file 可以把凭据以未加密的形式存在一个仅属主可读的文件里，用于没有 macOS Keychain 的沙箱环境，并要求使用能跨运行保留的私有存储。「未加密」这三个字是文档自己写的，用不用你自己判断。

最后一个坑来自 cursor.com/help 的 CLI 帮助页：如果 DNS 解析失败或者连不上 Cursor 的服务器，错误信息可能显示成「invalid API key」而不是网络错误。这一页给的排查方向是先查网络，如果在 VPN 或防火墙后面，确认 *.cursor.sh 与 *.cursorapi.com 可达。另外要提一句，同一页在「How do I authenticate the CLI?」下写的是 agent auth，而《Authentication》页与《Parameters》页写的都是 agent login，两处对不上，以官方文档最新内容为准。

四、第一次跑起来之前，先把权限面想清楚

认证过了，agent 就能起交互会话了。但在真让它动你的仓库之前，有三层东西值得先看一眼。

第一层是模式。 《Overview》与《Using Agent in CLI》两页都写明 CLI 支持与编辑器相同的三档模式：Agent（默认，可用全部工具）、Plan（Shift+Tab、/plan、--plan、--mode=plan）、Ask（/ask、--mode=ask，只读探索不改文件）。想先摸清一个陌生仓库，Ask 模式是文档明确写了「不编辑文件」的那一档。

第二层是权限 token。 《Permissions》页把可配置的权限分成五类，格式各自固定：Shell(commandBase)、Read(pathOrGlob)、Write(pathOrGlob)、WebFetch(domainOrPattern)、Mcp(server:tool)。写进配置文件长这样：

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(git)",
      "Read(src/**/*.ts)",
      "Write(package.json)",
      "WebFetch(docs.github.com)",
      "Mcp(datadog:*)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)"
    ]
  }
}

这一页里有几条读表时容易忽略的规则：Shell 匹配的是命令行里的第一个 token，支持 glob 和 command:args 这种更细的写法（例如 curl:*）；相对路径按当前 workspace 解析，绝对路径可以指向项目外的文件；deny 规则优先于 allow 规则；WebFetch 如果没有 allowlist 条目，每次抓取都会要求批准。

《Configuration》页还写明配置文件的四个必填字段是 version、editor.vimMode、permissions.allow、permissions.deny，最小可用配置是这样：

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": { "allow": ["Shell(ls)"], "deny": [] }
}

第三层是 run mode。 《Run Modes》页列了三档：Auto-review（allowlist 内的调用直接跑，其余 shell 命令尽量放进 sandbox，剩下的交给分类器）、Allowlist（只有 allowlist 里的动作免批准）、Run Everything（所有工具调用自动执行）。CLI 配置文件里对应的字段在《Configuration》页的可选字段表里：approvalMode，取值是 allowlist、auto-review、unrestricted。

五、边界：这些地方文档说得很明白，别自己加戏

Auto-review 官方明说不是安全边界。 《Run Modes》页有一个独立小节，原话意思是分类器会出错，既可能放行你本想拦下的调用，也可能拦下你本想放行的。这句是文档自述，别把它当成「有审查所以安全」。
有一档模式已经废弃。 同一页的 changelog 写明 Ask Every Time 已 deprecated，新用户无法选择，建议用「allowlist 为空的 Allowlist」达到同样效果；Run in Sandbox 也被并进了开启 sandboxing 的 Allowlist。
sandbox 的平台说明只覆盖了两个平台。 《Run Modes》页「How sandboxing works on your platform」下只给了 macOS（Seatbelt / sandbox-exec）与 Linux（Landlock + seccomp，要求内核 6.2 或更高且启用 unprivileged user namespaces，不满足则回退为逐条询问批准）两个平台，Windows 侧我们在这一页没有找到对应说明。紧接着的 AppArmor 一节还写明，远程环境与独立 CLI 不附带该 profile，某些发行版需要另行安装。
有两个命令是隐藏命令。 《Parameters》页明确标注 acp（ACP server 模式）与 sandbox 属于 hidden，默认不出现在帮助输出里。
非交互模式的写权限，两页口径不一致。 《Using Agent in CLI》页写的是「Cursor has full write access in non-interactive mode」，而《Headless CLI》页的示例注释写的是不加 --force 时「changes are only proposed, not applied」。《Parameters》页对 -p, --print 的描述是可以访问包括 write 和 shell 在内的全部工具。这两处并列在这里，不做调和——真要在 CI 里跑，请以 agent --help 的实际输出和你自己的验证为准。
团队与管理员策略优先。 《Run Modes》页写明团队设置优先于个人与项目配置；Shell Mode 那一页也写明管理员策略可能屏蔽某些命令。你本地配了不等于跑得起来。
官方文档没有说明的部分：CLI 的最低操作系统版本要求、Windows 原生环境下 sandbox 是否可用，我们在上述页面里都没有找到对应说明。

六、怎么确认自己配对了

按文档能核到的检查动作有这么几个，从轻到重：

agent --version
agent status
agent status --format json
agent about --format json

《Authentication》页写明 agent status 会显示三项内容：是否已认证、账号信息、当前 endpoint 配置。《Parameters》页写明 status（别名 whoami）和 about 都支持 --format，取值 text 或 json，默认 text。要在脚本里判断认证状态，json 这一档是文档明确给出的。

MCP 侧的配置是否被读到，《Parameters》页给了对应的子命令：

agent mcp list
agent mcp list-tools <identifier>

《Using Agent in CLI》页写明 CLI 会自动检测并遵循你的 mcp.json 配置，与编辑器共用同一套 MCP server；同一页也写明 CLI 会读取项目根目录下的 AGENTS.md 和 CLAUDE.md，和 .cursor/rules 一起作为规则应用。如果你之前给别的工具写过 CLAUDE.md，它在这里是会生效的，这一点值得先知道再动手。

配置文件本身出问题时，《Configuration》页给的处置是把文件挪开重启：

mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad

同页的 Notes 还写明几条行为：配置是纯 JSON 不支持注释；CLI 会对缺失字段做自我修复；损坏的文件会被备份为 .bad 并重建；权限条目是精确字符串。所以如果你发现自己写的某个字段莫名其妙没了，先想想是不是撞上了「部分字段由 CLI 托管、可能被覆盖」这条。

以上命令均按官方文档中的参数语义组合，未经实测，以官方文档与 --help 的实际输出为准。

最后一句实在话：这套东西的命令表、配置字段和模式档位都在持续变动，changelog 里同一年内就有过模式合并与废弃。把本文当成「该去翻哪几页」的地图，具体值以你手上那个版本的 agent --help 为准，比背下来更划算。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。