Cursor CLI 的 ACP 是什么：接第三方客户端时卡在哪

自建 ACP 客户端最容易撞上的一类麻烦是”卡住”：流程走到某一步就不往下走了。按 Cursor 官方文档的口径，这类停顿并不都意味着协议没跑通——ACP 里有几处是文档明确要求客户端回一条 JSON-RPC 响应的，客户端不回，agent 就会等在那儿。这篇把这几处按文档逐个点出来。

这篇按 Cursor 官方文档《ACP》页（cursor.com/docs/cli/acp）的口径，把 ACP 的用途、接入前置和几个典型卡点过一遍。文档里明确标了”不支持”的地方，我会照实标出来。

ACP 在 Cursor CLI 里是干什么的

官方文档写明：Cursor CLI 支持 ACP（Agent Client Protocol） 用于高级集成，你可以运行 agent acp，然后用自定义客户端通过 stdio 以 JSON-RPC 连上去。文档同时写了一句边界：ACP 面向的是构建自定义客户端与集成；普通终端工作流请用交互式的 agent。这句值得先记住——如果你只是想在终端里用，走 ACP 是绕远路。

传输层的四条，文档是这么列的：

• 传输：stdio
• 协议信封：JSON-RPC 2.0
• 分帧：换行分隔的 JSON（一行一条消息）
• 方向：客户端把请求/通知写到 stdin，Cursor CLI 把响应/通知写到 stdout，日志可能写到 stderr

最后一条值得单拎出来。既然日志可能落在 stderr，而 stdout 上是一行一条的 JSON-RPC 消息，那把两路合并起来按行做 JSON.parse 就不成立——日志行本身不是 JSON-RPC 消息。文档给的最小 Node.js 客户端示例里，spawn 的 stdio 写的是 ["pipe", "pipe", "inherit"]——第三路是 inherit，不是 pipe。

接入前置：先把这几件事对齐

一、命令本身是隐藏的。 参数参考页（cursor.com/docs/cli/reference/parameters）在命令表里把 acp 标注为”advanced, hidden command”，并额外写了一句：agent acp 面向自定义 ACP 客户端与高级集成，不出现在默认的命令帮助输出里。所以你敲 agent --help 翻不到它，不代表你这个版本没有——这是本篇第一个容易误判的点。

二、认证要在启动前搞定。 文档写明 Cursor CLI 对外声明的 ACP 认证方法是 cursor_login；实践上可以在启动前用现有的 CLI 认证路径预先认证：

• agent login
• --api-key（或 CURSOR_API_KEY）
• --auth-token（或 CURSOR_AUTH_TOKEN）

三、MCP 走的是文件配置。 ACP 支持在项目级或用户级 .cursor/mcp.json 里定义的 MCP servers，文档要求从你的项目目录启动 agent，并批准你要用的那些 server。同一段还写了一句硬边界：通过 Cursor dashboard 配置的 team-level MCP servers，在 ACP 模式下不支持（not supported）。团队统一下发的那套在这里不会生效，别按 IDE 里的习惯预期。

四、如果你走的是现成集成。 JetBrains 集成页（cursor.com/docs/integrations/jetbrains）把前置写在了 Prerequisites 一节：需要付费的 Cursor 套餐，以及启用了 AI Assistant 插件的 JetBrains IDE（文档写明 2025.1+）。文档还写明该集成里 IDE 充当 ACP 客户端、Cursor 的 agent 充当服务端。

卡点一：权限请求没人回，工具执行就停在那

文档写明的情形：会话已经建起来、session/update 通知也在往外推流式输出，但一到需要工具批准的动作就不再往下走。文档对这种情形的原话是「工具执行可能会阻塞」，至于阻塞时进程表现成什么样，官方文档没有说明这一点。

怎么确认是这个问题：把收到的每一行原样打一份日志，看里面有没有 method 为 session/request_permission 的消息、以及它带的 id。文档写明：当工具需要批准时，Cursor 会发 session/request_permission。只要你看到了这条却没有回过对应 id 的响应，基本就是它。

文档给出的处置：客户端应当返回三者之一——allow-once、allow-always、reject-once。文档在这一节后面直接写了后果：如果你的客户端不回应权限请求，工具执行可能会阻塞。

这里有一处口径需要你自己核：文档正文列的是上面三个字符串，而同一页最小 Node.js 客户端示例里的回法是这样的结构：

if (msg.method === "session/request_permission") {
  respond(msg.id, { outcome: { outcome: "selected", optionId: "allow-once" } });
}

正文的三个取值和示例里的 { outcome: "selected", optionId } 包装层是两处并存的表述，文档没有进一步说明二者的关系。接入时以你手上版本的实际交互为准，别只照正文那三个裸字符串去拼。

处置后怎么验证：发一个必然触发工具批准的 prompt，确认收到 session/request_permission 之后你确实回了同 id 的 JSON-RPC 响应，且 session/prompt 最终能返回带 stopReason 的结果（示例代码打印的就是 result.stopReason）。

什么情况说明不是这个原因：如果整个会话里你压根没收到过 session/request_permission，那就跟权限无关，往上一步查——session/new 有没有拿到 sessionId、authenticate 有没有成功。另外，如果卡住时你收的是 cursor/ask_question 或 cursor/create_plan，那是下面卡点三的事。

卡点二：认证与端点，几处文档对不上的地方

对应的情形：initialize 之后的 authenticate 或后续调用没有按预期返回。这一步失败会报成什么样，官方文档没有说明，所以下面只给能回源核对的检查项。

怎么确认：先脱开 ACP，用 CLI 自己的方式验一遍。认证参考页（cursor.com/docs/cli/reference/authentication）写明 agent status 会显示是否已认证、账号信息与当前端点配置；该页的 Troubleshooting 里对”Not authenticated”给的处置就是运行 agent login 或确认 API key 设置正确。CLI 侧登录不通，ACP 侧不会自己好。

文档给出的处置：ACP 页写明可以从根命令传端点与 TLS 选项，示例是：

agent --api-key "$CURSOR_API_KEY" acp
agent -e https://api2.cursor.sh acp
agent -k acp

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

需要提醒两处不一致：-e 与 -k 这两个短选项只在 ACP 这一页的示例里出现，参数参考页的全局选项表里我们没有找到对应条目；--auth-token / CURSOR_AUTH_TOKEN 也是同样情况——认证参考页开篇写的是”Cursor CLI 支持两种认证方式：浏览器登录与 API keys”，并没有列这一路。两页并存，文档没有解释差异，所以真要用，以 --help 的实际输出为准。

处置后怎么验证：agent status 显示已认证之后，再跑一次你的客户端，看 authenticate 带 methodId: "cursor_login" 的请求是否正常返回。

什么情况说明不是这个原因：如果 agent status 明确显示已认证、端点也是你要的那个，问题却依旧，那就别在认证上继续耗，回去核你的分帧是否符合文档写明的约定——换行分隔的 JSON，一行一条消息。少写行尾换行符，就不满足文档给的这条分帧要求。

卡点三：blocking 扩展方法没人应

Cursor 在 ACP 之上加了扩展方法，文档把它们分成两类，表里一共五个：

方法	类型	用途（文档口径）
cursor/ask_question	Blocking	向用户提多选问题
cursor/create_plan	Blocking	请求对计划的显式批准
cursor/update_todos	Notification	通知客户端 todo 状态更新
cursor/task	Notification	通知客户端 subagent 任务完成
cursor/generate_image	Notification	通知客户端生成的图片输出

分界很清楚：Blocking 的两个，agent 会等你的 JSON-RPC 响应才继续；Notification 的三个是 fire-and-forget，客户端可以显示但不必回。所以如果你的客户端只处理了 session/update 和 session/request_permission，一旦 agent 发出问答或计划批准这两类请求，按文档它就会等在那里——而你在日志里能抓到的线索，就是一条没有被你的分发逻辑识别的 method。

判定动作还是那一条：把未识别的 method 打出来，看是不是 cursor/ask_question 或 cursor/create_plan。处置是按文档给的响应结构回话，cursor/ask_question 的响应 outcome 有 answered / skipped / cancelled 三种形态，cursor/create_plan 的是 accepted / rejected / cancelled。验证方式是让 agent 再走一次同样的路径，确认它在你回复后继续往下跑。

反过来，如果卡住时最后一条是 cursor/update_todos 这类通知方法，那就不是这个原因——按文档，那几个本来就不需要你回。

会话与模式：起手别选错

文档写明用 session/new 建会话、用 session/load 恢复已有对话；ACP 会话支持与 CLI 相同的三种核心模式：agent（完整工具访问）、plan（规划，只读行为）、ask（问答/只读行为）。

这跟卡点一是连着的：你在只读的 plan 或 ask 下期待它改文件，它不会改；而在 agent 下，权限请求就必然会来找你。文档给的最小示例里 session/new 传的是 { cwd: process.cwd(), mcpServers: [] }，mcpServers 给的是空数组。这是文档示例里 MCP servers 的传入位置；至于留空时具体会发生什么，官方文档没有说明这一点，需要 MCP 的集成要连着上一节那条一起看——文档要求从项目目录启动 agent 并批准要用的 server。

Windows 侧要单独说一句

安装页（cursor.com/docs/cli/installation）把安装分成两路写：macOS、Linux 和 Windows（WSL）走 curl https://cursor.com/install -fsS | bash；**Windows（原生）**走 PowerShell 的 irm 'https://cursor.com/install?win32=true' | iex。安装后的验证命令文档写的是 agent --version。

ACP 页里给出的两个可执行文件路径线索都是类 Unix 形态：Neovim（avante.nvim）配置示例里 command 用的是 os.getenv("HOME") .. "/.local/bin/agent"，文档并说明”默认安装路径是 ~/.local/bin/agent，装到别处请自行调整”。Windows 原生安装之后 agent 落在哪个目录，官方文档没有说明这一点，那段 Neovim 配置里的 HOME、PATH 环境变量传法也是按类 Unix 环境写的。

所以在 Windows 上接 ACP，稳妥的顺序是：先在你的终端里确认 agent --version 能跑通（这一步是文档写明的验证方式），再在客户端里决定是给绝对路径还是靠 PATH 解析——最小示例里 spawn 的是裸名 agent，它依赖 PATH 能解析到。以上属于通用工程做法，不是 Cursor 官方文档的内容。

最后：什么情况说明问题不在 ACP

三条对照着看就行。其一，同样的任务你用交互式 agent 在终端里跑也一样不动——那是 CLI 侧的问题，跟协议无关，ACP 只是换了个入口。其二，你要用的是 dashboard 上配置的 team-level MCP——文档白纸黑字写了 ACP 模式下不支持，再怎么调客户端也不会出现。其三，你在 JetBrains 这类现成集成里遇到问题，先回去核集成页写明的前置（付费套餐、AI Assistant 插件版本），那一层不满足时，自建客户端的排查经验套不上去。

一句实在话：ACP 这套东西的排查重点，与其说在协议本身，不如说在”谁在等谁”。文档把需要客户端回话的位置写得很明白——session/request_permission 一处，cursor/ask_question 与 cursor/create_plan 两处。把收到的每一行原样落盘，再把带 id 的请求和你回过的响应逐条对上号，就能把停顿落到某一个具体的 id 上，而不是笼统地怀疑”协议没跑通”。

顺带说一句读文档的方法。这一页里真正带约束力的表述，是”必须回响应""不支持”这类；而示例代码里的取值、路径与短选项，属于文档当时给出的样例，不等于完整的能力清单。上面几处对不上的地方之所以要单独点出来，不是要挑文档的毛病，而是提醒你：接入时凡是文档只在示例里出现过一次的东西，都值得用 --help 或实际交互再确认一遍，别当成稳定契约来写死。

---

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

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。