在 Cursor 接入 Handsfree Club
30 秒搞定。Cursor 是 AI 原生 IDE,内置 Custom OpenAI Base URL 入口。GPT-5.6 Sol / Terra / Luna 三档已上线，Composer / Chat / Cmd-K 可用；Tab 内联补全仍走 Cursor 自家模型。
openai-default 专用：原 Key 和 https://api.handsfreeclub.com/v1 不变，手动添加 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna；不要填写裸 gpt-5.6。
想离线阅读? 完整接入手册 PDF · v2.3
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 长这样:
sk-XXXXXXXXXXXXXXXXXXXXXXXX # 末 4 位会显示在 Console,出问题报这 4 位给客服
在 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.6 Terra / GPT-5.4 / GPT-5.3-Codex / GPT-5.6 Luna 已经在列表里就直接打勾;如果没有,点最下方 + Add Model 手动加(模型名填准确的 ID,例如
gpt-5.6-terra),勾上就能在 Chat / Composer 下拉里选到。
启动验证#
打开任意项目,按 Cmd + L(macOS)或 Ctrl + L 唤出 Chat 面板,模型选 gpt-5.6-terra,问一句:
> 你好,确认下走的是 Handsfree Club 中转?
有响应就说明通了。想再确认一下就去 余额查询页输入 Key,看 used 数字有没有跳——跳了就证明请求确实走我们的服务器、计费没问题。
当前开放模型 · 按真实执行身份展示#
仅使用 Console 或 /v1/models 当前列出的模型。GPT-5.6 需精确选择 Sol / Terra / Luna，并以实际执行/上游身份和用量记录为准:
| Cursor 选项 | 实际模型 ID | 状态 |
|---|---|---|
| GPT-5.6 Terra(推荐) | gpt-5.6-terra |
就绪 |
| GPT-5.6 Sol | gpt-5.6-sol |
就绪 |
| GPT-5.4 | gpt-5.4 |
就绪 |
| GPT-5.3 Codex | gpt-5.3-codex |
就绪 |
| GPT-5.6 Luna | gpt-5.6-luna |
就绪 |
切换:Composer / Chat 顶部的模型下拉直接选。Terra 默认推荐，Sol 用于难题，Luna 用于轻量任务；计费按真实执行模型和请求时价格快照结算。
不知道选哪个?按场景挑就行:
gpt-5.6-sol(更强推理但更贵);专门 coding 长跑用 gpt-5.3-codex。常见错误速查#
认证 / 地址有问题
逐项检查:OpenAI API Key 是 sk-…(末 4 位跟 Console 对得上),Base URL 是 https://api.handsfreeclub.com/v1(末尾必须有 /v1),没多空格。
下拉里选不到
开了 Override 后,要回到 Models 列表把 GPT-5.6 Terra / GPT-5.4 / GPT-5.3-Codex 等前面的勾打上,Composer / Chat 的下拉才会出现。如果列表里压根没有这几个 ID,点最下方 + Add Model 手动加上(填 gpt-5.6-terra、gpt-5.3-codex 等)。
请求被限流
短时限流请稍后重试；若持续出现，请保留时间戳和错误码联系管理员核查上游通道。
这是设计如此
Tab 自动补全走的是 Cursor 自家的小模型,不走 OpenAI Base URL。所以你接入我们后,Tab 补全行为不会变化(也不会消耗你这边的额度)。
Cursor 自带额度优先
如果 Composer 调用没记到 Console,可能是模型选了 Claude / Composer 2 / Auto 等(那是 Cursor 内置的,走 Cursor 自家 quota)。显式选 gpt-5.6-terra / gpt-5.3-codex,才会走 Override 配的路。
@prosper777888 或 support@handsfreeclub.com,30 分钟内有人回。FAQ · Cursor 用户常问#
接入后,Cursor 自带的免费 quota 还有吗?
Cursor 的 quota(GPT-4o / Claude Sonnet 月度免费次数)跟 Override 是互斥的:
开 Override → 勾选的模型(如 gpt-5.6-terra / gpt-5.3-codex)走我们,按 USD 计费,Cursor 自家 quota 不动。
关 Override → 全部走 Cursor 自家,跟开 Override 之前一样。
所以你完全可以需要重型 agent 时打开,日常用 Cursor quota 时关掉,两边互不干扰。
Composer / Cmd-K / Tab 补全分别走谁?
Composer / Chat / Cmd-K → 跟你当时选的模型走。如果选 GPT-5.6 Terra / GPT-5.6 Sol / GPT-5.4 / GPT-5.3-Codex / GPT-5.6 Luna 等(Override 启用并勾选后出现),走我们。
Tab 内联补全 → 永远走 Cursor 自家小模型,跟 Override 无关,也不消耗我们的额度。
@docs / @web 索引 → 走 Cursor 后端,跟我们无关。
我能在多台机器、多个项目同时用同一把 Key 吗?
能。Key 没设备绑定，多台机器的用量合并计算。只有属于 openai-default 且已开放 Messages 调度的 Key，才能同时用于 Claude Code 与 OpenAI 客户端。
但请不要把 Key 公开(commit 到 git、贴到 issue 里),泄露了 Console 一键作废重发。
prompt cache 怎么算钱?
缓存 token 以实际上游 usage 和 Console 账单记录为准。不同 GPT tier 与价格 revision 可能不同，本教程不承诺固定倍率。
能用 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 接上来
注册不再自动发放体验额度。需要先验证链路时，可充值 $30 固定额度；也可联系管理员或客服人工自定义充值。