- name
- cursor-agent
- description
- >-
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
SKILL=~/.openclaw/workspace/skills/cursor-agent/scripts/cursor_bga.py
# First-time setup: get your API key
python3 $SKILL setup
# Launch an agent and wait for it to finish
python3 $SKILL create \
--repo owner/repo-name \
--prompt "Add unit tests for the auth module, run tests, submit PR" \
--auto-pr --wait
# Launch without waiting (returns immediately)
python3 $SKILL create \
--repo owner/repo-name \
--prompt "Refactor utils module" \
--auto-pr
# List recent agents
python3 $SKILL list
# Check agent details (one-time query)
python3 $SKILL get --agent-id <ID>
# Poll agent until finished (blocks, prints summary when done)
python3 $SKILL check --agent-id <ID> --interval 15 --timeout 600
# Send follow-up instructions
python3 $SKILL followup --agent-id <ID> --message "Also add integration tests"
# Stop a running agent
python3 $SKILL stop --agent-id <ID>
# List available models
python3 $SKILL models
# List accessible repos
python3 $SKILL reposAuthentication
API key is read from (in priority order):
--api-key KEYargumentCURSOR_API_KEYenvironment variable~/.cursor_api_keyfile (recommended)
# Save API key
echo 'your_api_key_here' > ~/.cursor_api_key
chmod 600 ~/.cursor_api_keyGet your key at: https://cursor.com/dashboard → Integrations → Generate API Key
Commands
| Command | Description |
|---|---|
create | Launch a new Cloud Agent (--wait to block until done, --no-direct to skip auto-execute hint) |
list | 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:
https://api.cursor.com/v0 - 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:
- API Key — Validates key by calling
/modelsendpoint - Repo Access — Verifies the repo is in Cursor's accessible repo list
- PR Permissions (when
--auto-pr) — Checks GitHub push/admin access viaghCLI
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
- Run
create --wait --auto-prwith the confirmed repo and prompt - The script auto-appends a "execute directly" instruction to prevent agent from asking for confirmation (use
--no-directto disable) --waitblocks until agent finishes and prints a full summary including conversation excerpt
Phase 3: Post-check
- If
checkreports--auto-prwas set but no PR URL, it will print thegh pr createcommand as fallback — run it - Use
followupto refine instructions if agent output needs adjustment - Report results back to user
Agent Status Values
CREATING— Agent is being set upRUNNING— Agent is actively workingFINISHED— Agent has completed the taskFAILED/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)
[ERROR] Authentication failed (401). Check your API key.原因：API Key 无效、过期或格式错误
解决：
- 检查
~/.cursor_api_key文件内容是否以crsr_开头，无多余空格或换行 - 到 https://cursor.com/dashboard → Integrations 重新生成 Key
python3 $SKILL models验证新 Key 是否生效
2. 权限不足 (403)
[ERROR] Forbidden (403). Your plan may not support this feature.原因：当前 Cursor 计划不支持 Cloud Agent API，或未开启 Usage-based pricing
解决：到 Cursor Dashboard 确认计划类型，确保已开启 Usage-based pricing
3. 仓库未找到 (404)
[ERROR] Not found (404): /agents原因：仓库名格式错误，或 Cursor GitHub App 未授权该仓库
解决：
- 确认
--repo为owner/repo格式（如siaslfs/ai-xxx） - 到 GitHub → Settings → Applications → Cursor 检查仓库授权
4. 请求限流 (429)
[ERROR] Rate limited (429). Please wait and try again.原因：短时间内请求过多
解决：等待 1-2 分钟后重试。避免频繁调用 create 或短间隔轮询（check --interval 建议 ≥ 10 秒）
5. Agent 空转（只输出方案不执行）
现象：Agent 状态 FINISHED，但 filesChanged 为 0，对话记录显示 Agent 在等待确认
原因：Prompt 被 Agent 理解为需要先确认再执行
解决：
- 默认已自动追加"直接执行"指令，正常情况不会发生
- 如果使用了
--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