Cursor Cloud Agent Skill
Manages Cursor Cloud Agents via the official API v0 (api.cursor.com). Cloud Agents run in isolated cloud VMs, onboard to your codebase, write code, test it, and deliver merge-ready PRs.
Quick Start
CODEBLOCK0
Authentication
API key is read from (in priority order):
- 1.
--api-key KEY argument - INLINECODE2 environment variable
- INLINECODE3 file (recommended)
CODEBLOCK1
Get your key at: https://cursor.com/dashboard → Integrations → Generate API Key
Commands
| Command | Description |
|---|
| INLINECODE4 | Launch a new Cloud Agent (--wait to block until done, --no-direct to skip auto-execute hint) |
| INLINECODE7 |
List recent agents (filter by PR URL, limit) |
|
get | Get agent details (status, summary, PR info) |
|
check | Poll agent until finished, print final summary |
|
conversation | View full agent conversation history |
|
followup | Send additional instructions to a running agent |
|
stop | Pause a running agent |
|
delete | Permanently remove an agent |
|
models | List available LLM models |
|
repos | List accessible GitHub repositories (outputs owner/repo format for
--repo) |
|
setup | Print API key setup instructions |
API Details
- - Base URL: INLINECODE18
- Auth: Basic Authentication (API key as username, empty password)
- Docs: https://cursor.com/docs/cloud-agent/api/endpoints
Workflow
When user asks to delegate a task to Cursor Cloud Agent:
Phase 1: Pre-flight Check (automatic)
The create command now runs automatic pre-flight checks before launching an agent:
- 1. API Key — Validates key by calling
/models endpoint - Repo Access — Verifies the repo is in Cursor's accessible repo list
- PR Permissions (when
--auto-pr) — Checks GitHub push/admin access via gh CLI
If any check fails, the script exits with a clear error message before incurring API costs.
Use --skip-preflight to bypass these checks if needed.
You still need to confirm with the user:
- - Task Prompt — Must be clear and specific enough for an agent to execute independently
- Branch/Ref — If user wants changes on a specific branch (not default)
Phase 2: Execute
- 5. Run
create --wait --auto-pr with the confirmed repo and prompt - The script auto-appends a "execute directly" instruction to prevent agent from asking for confirmation (use
--no-direct to disable) - INLINECODE26 blocks until agent finishes and prints a full summary including conversation excerpt
Phase 3: Post-check
- 8. If
check reports --auto-pr was set but no PR URL, it will print the gh pr create command as fallback — run it - Use
followup to refine instructions if agent output needs adjustment - Report results back to user
Agent Status Values
- -
CREATING — Agent is being set up - INLINECODE32 — Agent is actively working
- INLINECODE33 — Agent has completed the task
- INLINECODE34 /
STOPPED — Agent terminated abnormally
Constraints
- - Repo 格式 —
--repo 必须为 owner/repo 格式，不支持完整 URL 或纯仓库名 - Repo 权限 — 只能操作 Cursor GitHub App 已授权的仓库，未授权仓库会返回 404
- 并发限制 — 同一账号同时运行的 Agent 数量受 Cursor 计划限制（Trial 通常为 1 个）
- 执行时长 — 单个 Agent 任务通常在 2-5 分钟完成，复杂任务可能更长；
check 默认超时 600 秒 - 用量计费 — 每次
create 都会产生 API 用量费用，请勿重复创建相同任务 - Prompt 语言 — Agent 支持中英文 prompt，但代码注释和 commit message 默认跟随 prompt 语言
- Auto-PR 不保证 —
--auto-pr 依赖 Cursor GitHub App 权限，可能静默失败（无报错），需在 Post-check 阶段处理
Troubleshooting
1. 认证失败 (401)
CODEBLOCK2
原因：API Key 无效、过期或格式错误
解决：
- 1. 检查
~/.cursor_api_key 文件内容是否以 crsr_ 开头，无多余空格或换行 - 到 https://cursor.com/dashboard → Integrations 重新生成 Key
- INLINECODE43 验证新 Key 是否生效
2. 权限不足 (403)
CODEBLOCK3
原因：当前 Cursor 计划不支持 Cloud Agent API，或未开启 Usage-based pricing
解决：到 Cursor Dashboard 确认计划类型，确保已开启 Usage-based pricing
3. 仓库未找到 (404)
CODEBLOCK4
原因：仓库名格式错误，或 Cursor GitHub App 未授权该仓库
解决：
- 1. 确认
--repo 为 owner/repo 格式（如 siaslfs/ai-xxx） - 到 GitHub → Settings → Applications → Cursor 检查仓库授权
4. 请求限流 (429)
CODEBLOCK5
原因：短时间内请求过多
解决：等待 1-2 分钟后重试。避免频繁调用 create 或短间隔轮询（check --interval 建议 ≥ 10 秒）
5. Agent 空转（只输出方案不执行）
现象：Agent 状态 FINISHED，但 filesChanged 为 0，对话记录显示 Agent 在等待确认
原因：Prompt 被 Agent 理解为需要先确认再执行
解决：
- 1. 默认已自动追加"直接执行"指令，正常情况不会发生
- 如果使用了
--no-direct，去掉该参数重试 - 也可以用
followup --message "直接执行，不需要确认" 追加指令
6. Auto-PR 未生效
现象：Agent FINISHED，有代码变更，但无 PR URL
原因：Cursor GitHub App 缺少创建 PR 的权限
解决：check 会自动输出 gh pr create 回退命令，直接执行即可。或到 GitHub 手动创建 PR
Requirements
- - Active Cursor account with Trial or Paid plan
- Usage-based pricing enabled
- GitHub account connected with repository permissions
Cursor Cloud Agent 技能
通过官方 API v0（api.cursor.com）管理 Cursor Cloud Agent。Cloud Agent 在隔离的云虚拟机中运行，接入你的代码库，编写代码、测试代码，并交付可直接合并的 PR。
快速开始
bash
SKILL=~/.openclaw/workspace/skills/cursor-agent/scripts/cursor_bga.py
首次设置：获取 API 密钥
python3 $SKILL setup
启动 Agent 并等待其完成
python3 $SKILL create \
--repo owner/repo-name \
--prompt 为 auth 模块添加单元测试，运行测试，提交 PR \
--auto-pr --wait
启动但不等待（立即返回）
python3 $SKILL create \
--repo owner/repo-name \
--prompt 重构 utils 模块 \
--auto-pr
列出最近的 Agent
python3 $SKILL list
查看 Agent 详情（一次性查询）
python3 $SKILL get --agent-id
轮询 Agent 直至完成（阻塞，完成后打印摘要）
python3 $SKILL check --agent-id --interval 15 --timeout 600
发送后续指令
python3 $SKILL followup --agent-id --message 同时添加集成测试
停止正在运行的 Agent
python3 $SKILL stop --agent-id
列出可用模型
python3 $SKILL models
列出可访问的仓库
python3 $SKILL repos
身份认证
API 密钥按以下优先级读取：
- 1. --api-key KEY 参数
- CURSORAPIKEY 环境变量
- ~/.cursorapikey 文件（推荐）
bash
保存 API 密钥
echo yourapikeyhere > ~/.cursorapi_key
chmod 600 ~/.cursorapikey
获取密钥：https://cursor.com/dashboard → 集成 → 生成 API 密钥
命令
| 命令 | 描述 |
|---|
| create | 启动新的 Cloud Agent（--wait 阻塞直至完成，--no-direct 跳过自动执行提示） |
| list |
列出最近的 Agent（按 PR URL 过滤，限制数量） |
| get | 获取 Agent 详情（状态、摘要、PR 信息） |
| check | 轮询 Agent 直至完成，打印最终摘要 |
| conversation | 查看完整的 Agent 对话历史 |
| followup | 向正在运行的 Agent 发送额外指令 |
| stop | 暂停正在运行的 Agent |
| delete | 永久删除 Agent |
| models | 列出可用的 LLM 模型 |
| repos | 列出可访问的 GitHub 仓库（输出 owner/repo 格式，用于 --repo） |
| setup | 打印 API 密钥设置说明 |
API 详情
- - 基础 URL：https://api.cursor.com/v0
- 认证：基本认证（API 密钥作为用户名，密码为空）
- 文档：https://cursor.com/docs/cloud-agent/api/endpoints
工作流程
当用户要求将任务委托给 Cursor Cloud Agent 时：
阶段 1：飞行前检查（自动）
create 命令现在在启动 Agent 前自动运行飞行前检查：
- 1. API 密钥 — 通过调用 /models 端点验证密钥
- 仓库访问权限 — 验证仓库是否在 Cursor 的可访问仓库列表中
- PR 权限（使用 --auto-pr 时）— 通过 gh CLI 检查 GitHub 推送/管理员权限
如果任何检查失败，脚本会在产生 API 费用前退出并显示清晰的错误信息。
如有需要，可使用 --skip-preflight 跳过这些检查。
你仍需与用户确认：
- - 任务提示 — 必须清晰具体，足以让 Agent 独立执行
- 分支/引用 — 如果用户希望在特定分支（而非默认分支）上进行更改
阶段 2：执行
- 5. 使用确认的仓库和提示运行 create --wait --auto-pr
- 脚本会自动追加直接执行指令，防止 Agent 请求确认（使用 --no-direct 禁用）
- --wait 会阻塞直至 Agent 完成，并打印包含对话摘录的完整摘要
阶段 3：事后检查
- 8. 如果 check 报告设置了 --auto-pr 但没有 PR URL，它会打印 gh pr create 命令作为回退方案——运行该命令
- 如果 Agent 输出需要调整，使用 followup 优化指令
- 将结果报告给用户
Agent 状态值
- - CREATING — Agent 正在设置中
- RUNNING — Agent 正在积极工作
- FINISHED — Agent 已完成任务
- FAILED / STOPPED — Agent 异常终止
约束条件
- - 仓库格式 — --repo 必须为 owner/repo 格式，不支持完整 URL 或纯仓库名
- 仓库权限 — 只能操作 Cursor GitHub App 已授权的仓库，未授权仓库会返回 404
- 并发限制 — 同一账号同时运行的 Agent 数量受 Cursor 计划限制（试用版通常为 1 个）
- 执行时长 — 单个 Agent 任务通常在 2-5 分钟完成，复杂任务可能更长；check 默认超时 600 秒
- 用量计费 — 每次 create 都会产生 API 用量费用，请勿重复创建相同任务
- 提示语言 — Agent 支持中英文提示，但代码注释和提交消息默认跟随提示语言
- 自动 PR 不保证 — --auto-pr 依赖 Cursor GitHub App 权限，可能静默失败（无报错），需在事后检查阶段处理
故障排除
1. 认证失败 (401)
[ERROR] 认证失败 (401)。请检查你的 API 密钥。
原因：API 密钥无效、过期或格式错误
解决：
- 1. 检查 ~/.cursorapikey 文件内容是否以 crsr_ 开头，无多余空格或换行
- 到 https://cursor.com/dashboard → 集成 重新生成密钥
- python3 $SKILL models 验证新密钥是否生效
2. 权限不足 (403)
[ERROR] 禁止访问 (403)。你的计划可能不支持此功能。
原因：当前 Cursor 计划不支持 Cloud Agent API，或未开启按用量计费
解决：到 Cursor Dashboard 确认计划类型，确保已开启按用量计费
3. 仓库未找到 (404)
[ERROR] 未找到 (404)：/agents
原因：仓库名格式错误，或 Cursor GitHub App 未授权该仓库
解决：
- 1. 确认 --repo 为 owner/repo 格式（如 siaslfs/ai-xxx）
- 到 GitHub → 设置 → 应用程序 → Cursor 检查仓库授权
4. 请求限流 (429)
[ERROR] 请求限流 (429)。请等待后重试。
原因：短时间内请求过多
解决：等待 1-2 分钟后重试。避免频繁调用 create 或短间隔轮询（check --interval 建议 ≥ 10 秒）
5. Agent 空转（只输出方案不执行）
现象：Agent 状态为 FINISHED，但 filesChanged 为 0，对话记录显示 Agent 在等待确认
原因：提示被 Agent 理解为需要先确认再执行
解决：
- 1. 默认已自动追加直接执行指令，正常情况不会发生
- 如果使用了 --no-direct，去掉该参数重试
- 也可以用 followup --message 直接执行，不需要确认 追加指令
6. 自动 PR 未生效
现象：Agent 状态为 FINISHED，有代码变更，但无 PR URL
原因：Cursor GitHub App 缺少创建 PR 的权限
解决：check 会自动输出 gh pr create 回退命令，直接执行即可。或到 GitHub 手动创建 PR
要求
- - 拥有试用版或付费版的有效 Cursor 账户
- 已启用按用量计费
- 已连接具有仓库权限的 GitHub 账户
