5分钟快速上手cursor2api:从安装到跑通Claude Code的保姆级教程

原创2026-10-09 19:22:161,876 阅读
文章标签:后端API网关LLM 网关大模型

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 点:

  1. 端口被占用? 修改 config.yaml 里的 port,同时更新 ANTHROPIC_BASE_URL
  2. Vercel 验证拦截? Cursor 网站启用了安全验证,国内直连一般没问题;如果返回 403,检查是否已启用 stealth 代理(Docker 部署已默认开启)
  3. 工具调用失败? 在 config.yaml 中确认 tools.schema_mode: compact(模板默认值),并重启服务
  4. 响应被截断? 开启防截断配置: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 服务条款,合理控制使用频率,账号风险自行承担。

登录后查看全文
cursor2api