客户端接入指南

在 Cursor 接入 Handsfree Club

30 秒搞定。Cursor 是 AI 原生 IDE,内置 Custom OpenAI Base URL 入口,把 URL 指向我们就完事——Composer / Chat / Cmd-K 全部走我们的中转,2026-04 新王 GPT-5.5 / GPT-5.5 Pro 加 5.4 / 5.3-Codex / 5.4-mini 全系即开即用(Tab 内联补全保留 Cursor 自家小模型)。

想离线阅读? 完整接入手册 PDF · v2

原本

https://api.openai.com/v1

→

改成

https://api.handsfreeclub.com/v1

在 Cursor Settings → Models 里填一次,无需改代码、无需重装

30 秒摘要

Cursor → Settings (Cmd/Ctrl + ,) → Models → 启用 Override OpenAI Base URL,填 https://api.handsfreeclub.com/v1 + 填 OpenAI API Key sk-xxxx → 点 Verify。完事,Composer 立即生效。

注册账号,拿 API Key#

没注册过的话,先注册一个账号,进 Console 创建一把 API Key。Key 长这样:

key

sk-XXXXXXXXXXXXXXXXXXXXXXXX  # 末 4 位会显示在 Console,出问题报这 4 位给客服

Key 不限调用频次,只受套餐月额度 + 每日 cap 约束。同一把 Key 可以同时给 Cursor、Claude Code、Codex、Cline 用,额度合并计算。

在 Cursor Settings 里配置#

Cursor 是 GUI,所有设置都在 Settings 面板里。按下面 6 步走:

打开 Cursor,按 Cmd + ,(macOS)或 Ctrl + ,(Windows / Linux)进入 Settings,也可以菜单栏 Cursor → Settings → Cursor Settings。
左侧导航选 Models。
找到 OpenAI API Key 那一栏,把我们发给你的 Key 粘进去:sk-XXXXXXXXXXXXXXXXXXXXXXXX。
下方有个 Override OpenAI Base URL 开关——打开它,在弹出的输入框填:
base url
```
https://api.handsfreeclub.com/v1
```
点 Verify 按钮——如果显示绿色对勾,说明 key 跟 url 都没填错。
回到 Models 列表,如果 GPT-5.5 / GPT-5.4 / GPT-5.3-Codex / GPT-5.4-mini 已经在列表里就直接打勾;如果没有,点最下方 + Add Model 手动加(模型名填准确的 ID,例如 gpt-5.5),勾上就能在 Chat / Composer 下拉里选到。

Tab 自动补全(Cursor 引以为豪的内联补全)默认走 Cursor 自家的小模型,不会走我们的中转——只有 Composer / Chat / Cmd-K 这些重型对话功能才走 OpenAI Base URL。这是 Cursor 的设计,不是我们的限制。

开启 Override 后,Cursor 自带的免费配额(GPT-4o / Claude Sonnet 月度 quota)不再生效——所有勾选模型的请求都走我们,按 USD 计费。想保留 Cursor 原生 quota?把 Override 关掉就行。

启动验证#

打开任意项目,按 Cmd + L(macOS)或 Ctrl + L 唤出 Chat 面板,模型选 gpt-5.5,问一句:

cursor chat

> 你好,确认下走的是 Handsfree Club 中转?

有响应就说明通了。想再确认一下就去余额查询页输入 Key,看 used 数字有没有跳——跳了就证明请求确实走我们的服务器、计费没问题。

Composer 也试一下:按 Cmd + I 打开 Composer,挑一个文件让它改点什么。这是 Cursor 最重型的 agent 功能,能跑通就说明工具调用 + 文件 patch 都没问题。

模型映射 · 跟官方一一对应#

开了 Override 之后,Cursor Models 列表会显示所有 OpenAI 模型,我们这边都直通官方,不改名、不偷换:

Cursor 选项	实际模型 ID	状态
GPT-5.5(推荐)	`gpt-5.5`	就绪
GPT-5.5 Pro	`gpt-5.5-pro`	就绪
GPT-5.4	`gpt-5.4`	就绪
GPT-5.3 Codex	`gpt-5.3-codex`	就绪
GPT-5.4 mini	`gpt-5.4-mini`	就绪
GPT-5.4 nano	`gpt-5.4-nano`	就绪

切换:Composer / Chat 顶部的模型下拉直接选。计费按官方各自的 token 价格 1:1 折算(GPT-5.5 是 $5 / $30 per 1M tokens、1M context)。

Cursor 的双套模型体系:Cursor 自家(Composer 2 / Auto / Claude Sonnet 4.5 / Opus 4.7 等)走 Cursor 自家 quota,跟我们无关;勾选 GPT-5.x 系列才走 Override 配的我们这边。每功能模型分配:Chat / Inline Edit (Cmd-K) / Composer (Agent) 各自有独立模型设置,要在 Cursor Settings → Models 分别指派。

不知道选哪个?按场景挑就行:

默认 / Composer / Chat

GPT-5.5

2026-04 frontier 新王,1M context、agentic coding 全面强于 5.4,token 用量更省。Cursor 默认主推这一档。

硬骨头 / Pro

GPT-5.5 Pro / 5.3 Codex

最难的重构、复杂 debug 用 gpt-5.5-pro(更强推理但更贵);专门 coding 长跑用 gpt-5.3-codex。

Inline Edit / 省钱

GPT-5.4 mini

短任务、格式化、批量改写。速度 2 倍、用量 30%,适合 Cmd-K 短编辑长跑。

常见错误速查#

Verify 失败

认证 / 地址有问题

逐项检查:OpenAI API Key 是 sk-…(末 4 位跟 Console 对得上),Base URL 是 https://api.handsfreeclub.com/v1(末尾必须有 /v1),没多空格。

模型不显示

下拉里选不到

开了 Override 后,要回到 Models 列表把 GPT-5.5 / GPT-5.4 / GPT-5.3-Codex 等前面的勾打上,Composer / Chat 的下拉才会出现。如果列表里压根没有这几个 ID,点最下方 + Add Model 手动加上(填 gpt-5.5、gpt-5.3-codex 等)。

429

本日 cap 已用满

套餐有每日 cap(标准版 $50/日)。等次日 0:00(UTC+8)重置,或联系我们升档。

402 / quota

月度额度耗尽

本周期 USD 额度跑光了。续费同档自动叠加,余额半年保留。联系下单 →

502 / 503

上游或网关问题

Anthropic 抖动 or 我方网关重启,通常 30 秒内自动恢复。持续 5 分钟以上看 status page。

Tab 补全没变

这是设计如此

Tab 自动补全走的是 Cursor 自家的小模型,不走 OpenAI Base URL。所以你接入我们后,Tab 补全行为不会变化(也不会消耗你这边的额度)。

Composer 仍走 Cursor

Cursor 自带额度优先

如果 Composer 调用没记到 Console,可能是模型选了 Claude / Composer 2 / Auto 等(那是 Cursor 内置的,走 Cursor 自家 quota)。显式选 gpt-5.5 / gpt-5.3-codex,才会走 Override 配的路。

排查 5 分钟还没解决?把错误码 + Key 末 4 位 + 时间戳发到 Telegram @prosper777888 或 support@handsfreeclub.com,30 分钟内有人回。

FAQ · Cursor 用户常问#

接入后,Cursor 自带的免费 quota 还有吗?

Cursor 的 quota(GPT-4o / Claude Sonnet 月度免费次数)跟 Override 是互斥的:

开 Override → 勾选的模型(如 gpt-5.5 / gpt-5.3-codex)走我们,按 USD 计费,Cursor 自家 quota 不动。

关 Override → 全部走 Cursor 自家,跟开 Override 之前一样。

所以你完全可以需要重型 agent 时打开,日常用 Cursor quota 时关掉,两边互不干扰。

Composer / Cmd-K / Tab 补全分别走谁?

Composer / Chat / Cmd-K → 跟你当时选的模型走。如果选 GPT-5.5 / GPT-5.5-Pro / GPT-5.4 / GPT-5.3-Codex / GPT-5.4-mini 等(Override 启用并勾选后出现),走我们。

Tab 内联补全 → 永远走 Cursor 自家小模型,跟 Override 无关,也不消耗我们的额度。

@docs / @web 索引 → 走 Cursor 后端,跟我们无关。

我能在多台机器、多个项目同时用同一把 Key 吗?

能。Key 没设备绑定,家里 + 公司 + 项目 A + 项目 B 同时跑都行,所有调用合并计入同一个套餐余额。同一把 Key 也能给 Claude Code、Codex、Cline 用——Anthropic 协议走 /、OpenAI 协议走 /v1。

但请不要把 Key 公开(commit 到 git、贴到 issue 里),泄露了 Console 一键作废重发。

prompt cache 怎么算钱?

跟官方完全一致。cached input 0.1x,我们透传。Cursor Composer 在长会话里会大量复用上下文,实际花费比"按 input/output 算"低不少。

能用 Cursor 自带的 Claude 模型走我们吗?

不直接行——Cursor 自带的 Claude 模型走的是 Cursor 自己的 API,不读 OpenAI Base URL。

但可以这么做:用 Claude Code 客户端(我们的另一个接入页)直接连我们,体验更好,工具也更全。Cursor 这边专注用 GPT-5.x 系列。

Composer 跑 long-running agent,会触发限流吗?

正常使用不会。我们没有人工 RPM 限制,只受 OpenAI 上游官方 RPM/TPM 限制——企业账号 quota 远高于个人订阅,大多数情况你打不到。

如果你跑超并发(多窗口 + 多项目同时 Composer),提前在 Telegram 联系我们,我们走独立 API key shard给你。

跑通了?现在就把 Cursor 接上来

注册后按文档接入,选择合适额度或套餐后即可跑完一整套接入测试。

注册账户 → 查看套餐价格