5分钟快速上手cursor2api:从安装到跑通Claude Code的保姆级教程
5分钟快速上手cursor2api:从安装到跑通Claude Code的保姆级教程
cursor2api 是一个免费的 Cursor API 代理工具,它把 Cursor 文档页的 AI 对话接口转换成 OpenAI / Anthropic 兼容的 API,让你可以零成本把 Cursor 免费模型接入 Claude Code、Cursor IDE 和 ChatBox 等客户端。本教程带你 5 分钟完成从安装、配置到跑通 Claude Code 的全过程,新手也能一次成功。
一、cursor2api 是什么?为什么需要它?
如果你用过 Cursor IDE,一定知道它的 AI 对话能力很强,但官方并没有开放免费 API 给第三方客户端。cursor2api 做的事情就是"协议翻译":
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Claude Code │────▶│ │────▶│ │
│ (Anthropic) │ │ cursor2api │ │ Cursor API │
│ │◀────│ (代理+转换) │◀────│ /api/chat │
└─────────────┘ └──────────────┘ └──────────────┘
▲ ▲
│ │
┌──────┴──────┐ ┌──────┴──────┐
│ Cursor IDE │ │ OpenAI 兼容 │
│ (/v1/responses│ │ (/v1/chat/ │
│ + Agent模式) │ │ completions)│
└─────────────┘ └─────────────┘
简单说,它就是一个 AI API 代理服务器:
- 🎯 Anthropic Messages API 完整兼容:
/v1/messages端点,直接对接 Claude Code - 🎯 OpenAI Chat Completions 兼容:
/v1/chat/completions,可接入 ChatBox / LobeChat 等客户端 - 🎯 Cursor IDE Agent 模式适配:
/v1/responses端点 - 🆕 Web 日志查看器:浏览器实时查看每次请求的完整过程
- 🆕 图片支持(Vision):内置本地 OCR,图片内容自动转文字发给大模型
- 🆕 工具参数自动修复:字段名映射、智能引号替换,大幅提升 Claude Code 工具调用成功率
核心协议转换逻辑在 src/converter.ts,请求处理入口在 src/index.ts,感兴趣可以深入了解。
二、安装前的准备
只需要一个环境:Node.js 20 或更高版本。
检查方法:
node -v
💡 如果提示找不到命令,请先安装 Node.js LTS 版本。
三、一键安装步骤(3分钟)
第 1 步:克隆仓库
git clone https://gitcode.com/gh_mirrors/curs/cursor2api
cd cursor2api
第 2 步:安装依赖
npm install
⚠️ 注意:
npm install会自动安装 stealth-proxy 所需的 Playwright Chromium 浏览器(用于绕过 Vercel 安全验证),首次安装需要几分钟,请耐心等待。
第 3 步:创建配置文件
cp config.yaml.example config.yaml
这个 config.yaml.example 就是项目的配置模板,里面每个参数都有详细中文注释。新手不用改任何配置也能直接跑起来,默认模型是 google/gemini-3-flash。
几个新手常用的关键配置项:
| 配置项 | 说明 | 默认值 |
|---|---|---|
port |
服务端口 | 3010 |
cursor_model |
使用的模型 | google/gemini-3-flash |
auth_tokens |
API 鉴权(公网部署必配) | 不配置则全部放行 |
compression.enabled |
历史消息自动压缩 | true |
vision.enabled |
图片 OCR 拦截 | true |
第 4 步:启动服务
开发模式(改代码自动重启,适合折腾):
npm run dev
生产模式(推荐日常使用):
npm run build && npm start
看到终端输出服务启动信息、监听 3010 端口,就说明跑起来了 ✅
四、跑通 Claude Code(2分钟)
服务启动后,打开另一个终端,执行:
export ANTHROPIC_BASE_URL=http://localhost:3010
claude
在 Claude Code 里输入一句话测试:
帮我创建一个 hello.py,打印 "hello cursor2api"
如果 Claude Code 成功执行了写文件、跑代码这些工具调用,恭喜你——cursor2api 代理已完全跑通!🎉
如果你配置了 auth_tokens 鉴权,还需要额外设置 API Key:
export ANTHROPIC_BASE_URL=http://localhost:3010
export ANTHROPIC_API_KEY=sk-your-secret-token-1
claude
五、Docker 一键部署(更省事)
如果你不想折腾 Node 环境,直接用 Docker 部署更省心:
git clone https://gitcode.com/gh_mirrors/curs/cursor2api
cd cursor2api
cp config.yaml.example config.yaml
docker compose up -d
项目的 docker-compose.yml 已经预配置好端口映射、日志目录挂载和 stealth 代理,默认开启 ENABLE_STEALTH=true 自动绕过 Vercel 安全验证。Dockerfile 采用多阶段构建,镜像体积也控制得很好。
部署完成后同样访问 http://你的IP:3010 验证即可。
六、用日志查看器确认一切正常
打开浏览器访问:
http://localhost:3010/logs
这就是 cursor2api 的全链路日志查看器(源码在 src/log-viewer.ts):
- 📋 左侧是所有请求列表,以你的提问作为标题
- 🔍 支持关键字搜索和时间范围过滤
- 📊 点击请求可看到完整请求参数、提示词、响应内容和各阶段耗时
- 🌙 支持明暗主题一键切换
如果你刚发了测试请求,这里应该能看到一条"成功"状态的记录。看到它,就代表整条链路:Claude Code → cursor2api → Cursor API → 流式返回,全部打通了。
七、常见问题排查清单
遇到不响应?按顺序检查这 4 点:
- 端口被占用? 修改
config.yaml里的port,同时更新ANTHROPIC_BASE_URL - Vercel 验证拦截? Cursor 网站启用了安全验证,国内直连一般没问题;如果返回 403,检查是否已启用 stealth 代理(Docker 部署已默认开启)
- 工具调用失败? 在
config.yaml中确认tools.schema_mode: compact(模板默认值),并重启服务 - 响应被截断? 开启防截断配置:
context_pressure: 1.35,可参考 config.yaml.example 中的注释说明
八、写在最后
回顾一下你刚才完成的完整链路:
克隆仓库 → npm install → 复制配置文件 → npm run dev → 设置环境变量 → claude 对话成功
整个流程不到 5 分钟。现在你拥有一个免费的 AI API 代理,它不仅能驱动 Claude Code,还能被 Cursor IDE 和任何 OpenAI 兼容客户端复用。
📌 接下来可以探索的方向:
- 在 config.yaml 中开启
logging.db_enabled: true,让日志持久化到 SQLite,重启后仍可回看历史请求 - 配置
auth_tokens后部署到公网,多台设备共享这个免费的 AI API - 阅读 README.md 了解 Thinking 支持、拒绝拦截、截断续写等高级特性
祝你使用愉快!
⚠️ 免责声明:本项目仅供学习和研究使用,与 Cursor 官方无关。使用前请确认已阅读并同意 Cursor 服务条款,合理控制使用频率,账号风险自行承担。