常见问题

当前购买口径

渠道	计费口径	适合谁	说明
Anthropic 官方	官方订阅 / 官方 API 美元账单	有海外支付、合规或官方销售需求	自己维护账号、付款和限额
Handsfree Club	$30 / $100 / $500 通用余额	Claude Code、Codex、Cursor、Cline 等统一 Key 场景	按真实调用扣额度，余额页可查流水和剩余额度；其他金额可人工充值

稳定性怎么保证

• 不卖“无限量”:按额度结算,避免多人挤同一批共享账号导致一限流就集体受影响
• 出问题能定位:余额页看消耗流水,status page 看服务状态,客服能按时间查错误记录
• 短暂失败会重试:网络抖动或上游瞬断时自动重试,重复请求会智能去重,不双扣
• 持续异常会处理:连续 30 分钟不可用 → 主动补 1 天时长(故障补偿)

什么时候建议直接用官方

• 企业有 SOC2 / BAA / GDPR 等合规硬要求,我们当前提供不了正式合规协议
• 需要官方账号权益或超大账单额度,例如团队统一合同、发票、企业审计和专属限额
• 需要 Anthropic 销售直接对接(SO 价、专属客户成功)

还不行?

价格 / 稳定性细节疑问，请联系管理员或客服。我们直接按余额页流水、错误记录和 status page 历史记录解释,不让你靠猜。

差异点对比

维度	我们	大平台(CloseAI / OpenRouter)	低价拼车
定位	个人开发者 + 小团队	企业级 / 大流量	极致便宜 / 多人分摊
价格	统一按额度充值,按余额页展示	官方折扣区间	极低价但链路不透明
接入门槛	5 分钟,3 行 env	需注册 / 充值 / 学 SDK	群里发 key,无文档
客服	管理员或客服 30 分钟首响	工单 / Discord 24h+	不一定有
稳定	主动监控 + 失败重试	多渠道 + 企业 SLA	看运气
是否「掺水」	不掺,链路透明	不掺(头部)	大概率掺
开票	暂无(Phase 2 起电子凭证)	境外 Invoice / 部分国内	无
跑路风险	团队实名,支持直接联系管理员或客服	低(公司运营)	高

什么时候选我们

• 主用 Claude Code / Cursor / Cline 写代码,不用复杂 SDK
• 价格敏感但不接受「拼车 / 共享号 / 抢号」
• 需要中文人工支持(不想发工单等 24 小时)
• 个人 / 小团队(3 人以内),不需要 SAML / SSO 等企业功能

什么时候选大平台

• 需要当前 HFC 尚未开放的第三方模型或企业级合规能力
• 企业 ≥ 10 人 + 需要 SSO / SAML / 部门额度池
• 需要正式国内增值税发票 + 对公转账

还不行?

对比某家具体平台，请联系管理员或客服，我们给你拉一份逐条对比表(诚实版,该输的我们认)。

行业现实(我们诚实告诉你)

这两年中转跑路确实不少,主要原因:

• 独立站长一人作战,断号 / 政策变 / 个人原因都可能停服
• 预收年费 → 急用钱跑了
• 违规拉客 / 拼车被官方封 → 链路彻底断

我们做了哪些保险

1. 团队实名:3 人小团队,Ethan(创始人,与 Mark 共同负责技术)+ Mark(联合技术)+ 1 客服
2. 人工支持:需要时可直接联系管理员或客服，按公开服务承诺响应
3. 按需充值:提供 $30 / $100 / $500 固定档位，也支持人工自定义金额，建议用多少充多少
4. 30 天滚动退款:任何时间想退,按余量计算(我方原因全额 / 主观不满意半退),原路返还
5. 预案透明:我们公开承诺如服务下线,主动按余量全额退,不让你追讨

你应该怎么做(自我保护)

1. 先充 $30 固定额度跑通，验证客服响应速度和实际可用性
2. 确认适合后再按实际用量选择 $100 / $500 或人工自定义金额，避免一次充值过多
3. 每周看一眼 status page,有连续 1 天异常的迹象提前找客服
4. 重要项目同时备一个官方账号或第二家中转作 fallback,不把所有鸡蛋放一个篮子

还不行?

对我们团队还有疑虑，请联系管理员或客服申请进一步核验,信任建立是双向的,我们欢迎尽调。

额度怎么买

• 固定档位：$30 / $100 / $500 通用余额
• 在充值页面选择档位，跳转链动小铺完成付款并获取兑换码
• 回到个人中心的兑换页面提交兑换码，成功后额度进入账户
• 需要其他金额时，联系管理员或客服人工自定义充值，管理员在后台入账

怎么扣费

• 文本模型按请求产生的实际 token 和请求时的价格快照扣费
• 生图按图片档位和成功生成张数扣费，失败请求不计费
• 同一账户使用同一个余额池，不需要为 GPT 和 Claude 分开购买
• 余额、扣费明细和当前模型价格以 Console 实际展示为准

为什么价格有优势

低价来自上游资源池、批量采购和官方 Prompt Caching 复用，不是把请求偷换成其他模型。响应链路和模型能力可按官方协议自行核验。

相关：充值怎么选 · Token 怎么算

注册不再自动发放体验额度；请先在充值页面选择额度并完成兑换。

你的情况	建议
第一次充值 / 轻量使用	$30 通用余额
日常开发 / 持续调用	$100 通用余额
团队 / Agent / 高强度调用	$500 通用余额
需要其他金额	联系管理员或客服人工自定义充值

自助充值流程

1. 在充值页面选择额度
2. 跳转链动小铺下单并付款
3. 在链动小铺获取兑换码
4. 回个人中心兑换，确认余额到账

三档怎么选

档位	用途	价格	¥10 能跑
1K	缩略图 / 草图 / 批量预览	¥0.05	200 张
2K(默认)	公众号配图 / PPT 插图 / 自媒体素材	¥0.10	100 张
4K	海报 / 印刷 / 商品图	¥0.20	50 张

"我就想生图,不跑代码可以吗?"

可以。注册后选择「按额度充值」，完成兑换后即可使用。Console 显示余额和每次扣费流水；固定档位以充值页面为准，需要其他金额可联系人工处理。

失败会扣费吗

不会。只有 200 OK 且实际拿到图片字节才扣费。被 OpenAI 内容政策拦掉(真人脸 / 暴力 / 政治人物)、超时 504、地址 / 模型名错都不算钱,Console 也不会出现这条记录。

图生图 / variations 什么时候开?

/v1/images/edits(图生图)和 /v1/images/variations(变体)本季度内开放内测。需要的同学发 TG @prosper777888 报名,内测开放时优先发邀请。

→ 完整接入示例(curl / Python / Node 三方式 + 错误码 + 8 条 FAQ): /docs/image

行业里「降智」怎么发生的

常见 3 种降智手段(我们都不做):

• 模型替换:你以为在用 Claude Sonnet,实际后台路由到 GLM-4 / Qwen / DeepSeek(便宜很多)
• 上下文截断:你以为有 200K context,实际服务端偷偷裁到 8K(省成本)
• System prompt 注入:服务端在你不知道的情况下加 "回答简短一些" 等限制(节省 output token)

怎么自己验证

1. 挑战 1 — 长 context:发一段 5000 行的 markdown 让模型总结(GLM 撑不住)
2. 挑战 2 — 自家术语:问「Constitutional AI 是什么 / 为什么 Claude 用」(只有 Claude 会用 Anthropic 自家术语解释)
3. 挑战 3 — 模型自报家门:发「你是哪个模型?给我精确版本号」
   我们透传,Claude 会真实说「Claude Sonnet 4.6 by Anthropic」
   掺水中转可能说「我是一个 AI 助手」(不敢说名字)
4. 挑战 4 — Tool Use:发一个标准 Anthropic tools 字段调用,看 tool_use 块格式是否完全合规
5. 挑战 5 — 看 response header:curl -i 调用,看是否有 anthropic-ratelimit-* 字段(我们透传上游 header)

我们的承诺

• 所有请求原封不动转发给 Anthropic Pro / Plus 真实订阅,不改任何字段
• 响应也原封不动转回客户端,不删 / 不改 / 不裁 token
• 我们没有「省钱模式」「fast 模式」「降智档位」(这种通常就是掺水)
• 我们不是「2API 渠道」(逆向 ChatGPT 网页版),是真的订阅 + 真的 API 链路

还不行?

跑挑战 1-5 你怀疑结果不对，请把结果发给管理员或客服，我们当场对照官方调一次给你看。

链动小铺自助充值

1. 登录 Console，进入「充值额度」页面
2. 选择 $30、$100 或 $500，跳转链动小铺完成下单
3. 付款完成后，在链动小铺订单中获取兑换码
4. 回到个人中心「兑换」页面，输入兑换码并提交
5. 看到兑换成功后，到余额页确认新额度和入账流水

人工自定义充值

1. 联系管理员或客服，说明充值金额和注册邮箱
2. 按客服确认的方式完成转账
3. 管理员核对收款后，在网站后台为对应账户增加额度
4. 用户回余额页确认到账；若金额不一致，立即联系客服核查

常见问题

情况	怎么办
付款后没有看到兑换码	先检查链动小铺订单详情，再携带订单截图联系客服
兑换码提示无效或已使用	不要重复尝试，提交订单号和提示截图给客服核查
兑换成功但余额未变化	刷新余额页；仍未到账时提供兑换时间和注册邮箱
需要非固定金额	联系管理员或客服人工自定义充值，不要拆分多笔错误档位

第 1 步:env 是否生效?

# 在你跑 claude / cursor 的同一个终端窗口里
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_MODEL

正确输出:

https://api.handsfreeclub.com
gpt-5.6-terra

• 3 个都空 → 你 export 在了别的终端,或写错 ~/.zshrc 没 source
• BASE_URL 末尾不要带 /(https://api.handsfreeclub.com 不是 .../)
• 不要在截图或群聊中输出完整 AUTH_TOKEN；只在 Console 对照 Key 末 4 位

第 2 步:链路通不通?

curl -i https://api.handsfreeclub.com/v1/responses \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.6-terra","input":"Reply with OK only","max_output_tokens":8}'

看返回:

• 200 OK + JSON content → 链路通,问题在客户端配置
• 401 → key 错(对照第 1 步检查)
• 403 → Key 不属于 openai-default 或未开放 GPT-5.6
• 400 → 模型名或请求格式错误；不要使用裸 gpt-5.6
• 429 → 你被限流(等 1 分钟再试)
• 5xx → 上游故障,看 状态页
• curl: timeout → 网络不通(看下面 FAQ 17 跨境网络)

第 3 步:客户端读到了吗?

关键:新开一个终端窗口(老窗口 env 是旧的)。

• Claude Code:跑 claude --debug,看启动日志里 base_url 是不是我们的
• Cursor:Settings → Models → 看 Override Base URL 是不是 https://api.handsfreeclub.com/v1
• Cline / Continue:VS Code 命令面板搜 "settings",看插件配置里的 endpoint

还不行?

3 步都过了还跑不通,把以下信息发客服:

• 你的客户端 + 版本(Claude Code 1.x / Cursor 0.x)
• 第 2 步 curl 完整截图(注意挡住 sk-key 中间部分,只露末 4 位)
• 客户端报错原文截图

5-10 分钟客服远程指导。

相关错误码:AUTH01 · NET01 · REQ01

最简单:跑一键脚本

Mac / Linux 用户复制这一行:

bash <(curl -fsSL https://handsfreeclub.com/install.sh)

Windows 用户按 Win 键,输入 PowerShell,打开后复制这一行:

& ([scriptblock]::Create((irm https://handsfreeclub.com/install.ps1)))

脚本自动:检测系统 → 校验 Key 格式 → 探活 1 次 → 写好 Claude Code / Codex 配置 → 没装 Node 自动装 Node LTS → 装好 claude + codex 二进制。跑完新开终端,直接 claude 或 codex 启动即可。不希望脚本动你系统就加 --no-install-cli 或 Windows 的 -NoInstallCli(只写配置)。

Claude Code(Anthropic 协议使用 GPT-5.6)

claude
# 进去后:
/model sonnet

或写进 ~/.claude/settings.json 永久生效:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.handsfreeclub.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的key",
    "ANTHROPIC_MODEL": "gpt-5.6-terra",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.6-sol",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.6-terra",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.6-luna",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Cursor

设置 → Models → Anthropic API Key:

• 勾选 Override OpenAI Base URL
• Base URL: https://api.handsfreeclub.com/v1
• API Key: sk-你的key
• 模型:精确填写 gpt-5.6-terra（或 Sol / Luna，仅 openai-default）

Cline(VS Code 插件)

• API Provider: OpenAI Compatible
• Base URL: https://api.handsfreeclub.com/v1
• API Key: sk-你的key
• 模型:精确填写 gpt-5.6-terra（或 Sol / Luna）

Hermes Agent

在 ~/.hermes/config.yaml 注册 custom:handsfree，Base URL 使用 https://api.handsfreeclub.com/v1，api_mode 设为 chat_completions。查看完整教程。

OpenClaw

在 models.providers 注册 openai-responses provider，模型使用 handsfree/gpt-5.6-terra 形式。查看完整配置与安全边界。

OpenCode

在 opencode.json 中显式配置 @ai-sdk/openai、Base URL 与模型表；不能只靠环境变量自动接入。查看完整教程。

还不行?

报「无法连接」(代码 NET01)→ 走 FAQ 7 三步排查。Aider、Continue、Roo、Kilo、Zed、Cherry、Chatbox、Jan、OpenWebUI、LibreChat、NextChat、LobeHub、Open Interpreter 见 更多客户端专项页。

Aider(终端 AI pair programming)

read -rsp 'HandsfreeClub API Key: ' OPENAI_API_KEY; echo
export OPENAI_API_KEY
export OPENAI_API_BASE=https://api.handsfreeclub.com/v1
aider --model openai/gpt-5.6-terra

Continue(VS Code / JetBrains 插件)

在本机 Models 配置里使用 provider: openai、model: gpt-5.6-terra、apiBase: https://api.handsfreeclub.com/v1。Key 只放 Continue 本机 Secret / apiKey，不要提交到项目。完整 YAML 见 /docs/openai-compatible/。

Roo Code(VS Code 插件)

• 设置 → API Provider: OpenAI Compatible
• API Key: sk-你的key
• Base URL: https://api.handsfreeclub.com/v1
• Model: gpt-5.6-terra（也可精确选择 Sol / Luna）

Cherry Studio(桌面 GUI)

Provider 选 OpenAI Compatible，Base URL 填 https://api.handsfreeclub.com/v1，模型手动填 gpt-5.6-terra；Sol / Luna 同样可用。

Kilo Code / Zed / Chatbox / Jan / OpenWebUI

Kilo 选 OpenAI Compatible；Zed 在 AI 的 LLM Providers 里 Add Provider；Chatbox 选 OpenAI API Compatible；Jan 选 OpenAI-compatible；OpenWebUI 由管理员在 Connections 新增 OpenAI 连接。这五个都填带 /v1 的 Base URL，Key 放客户端凭据存储，再添加三个精确模型。

LibreChat(自托管)

需要在 librechat.yaml 配 baseURL 和模型表，Key 用 ${HFC_API_KEY} 从 .env 读取；Docker 还要挂载 YAML 并重启应用容器。不是在普通用户 Connections 页随手改一项。

NextChat / LobeHub(自托管)

NextChat 用部署变量 OPENAI_API_KEY、BASE_URL=https://api.handsfreeclub.com、CUSTOM_MODELS；注意它的 Base URL 不带 /v1。LobeHub 用 OPENAI_API_KEY、OPENAI_PROXY_URL=https://api.handsfreeclub.com/v1、OPENAI_MODEL_LIST。两者都要修改部署 Secret 后重新部署。

Open Interpreter

先通过隐藏输入设置 OPENAI_API_KEY，再用 interpreter --api_base https://api.handsfreeclub.com/v1 --model openai/gpt-5.6-terra。

n8n / Zapier / 自建 Agent 工作流

用 HTTP Request 节点调 POST https://api.handsfreeclub.com/v1/responses，模型填 gpt-5.6-terra。Key 必须放进 n8n / Zapier 的 Credentials 或 Secret Vault，再由 Authorization Bearer 凭据引用；不要把真实 Key 写进工作流正文、截图或导出文件。

还不行?

客户端不在上面?请把客户端名字和配置页截图发给管理员或客服,我们 5-10 分钟内告诉你怎么配 / 是否兼容。

模型对比

模型	速度	能力	适合
gpt-5.6-luna	快	轻量	短问题、补全、批量调用
gpt-5.6-terra	中等	主力	默认，日常工程任务
gpt-5.6-sol	中等	高难	大型重构、深度分析、复杂调试

怎么切换

Claude Code 里:

/model haiku      # 执行 gpt-5.6-luna
/model sonnet     # 执行 gpt-5.6-terra（默认）
/model opus       # 执行 gpt-5.6-sol

Cursor / Cline / Continue:在 OpenAI Compatible provider 中手动填写精确 GPT-5.6 ID；模型列表见 https://api.handsfreeclub.com/v1/models。

改 Claude Code 默认模型:export ANTHROPIC_MODEL="gpt-5.6-terra"，并同步设置 Opus / Sonnet / Haiku 三档角色变量。

什么时候用哪个

• Luna / Haiku 角色:跑测试 / 批量翻译 / 简单脚本生成 / 快速 Q&A
• Terra / Sonnet 角色(默认):日常写代码 / 改 bug / 解释 / 重构小模块
• Sol / Opus 角色:架构设计 / 跨大量文件分析 / 复杂调试

OpenAI / GPT 当前状态

• OpenAI Responses 已上线；GPT-5.6 仅限 openai-default，使用 Sol / Terra / Luna 三个精确档位。
• Gemini 2.5 Pro(用户呼声高再上)
• DeepSeek-R1 / Qwen3-Max(用户呼声高再上)

还不行?

/model xxx 报「模型不存在」(代码 REQ02 / MODEL01):

• 检查模型名拼写，必须是 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna 之一
• 裸 gpt-5.6 会返回 400；未授权分组返回 403
• 看到曾支持但现在不在的模型可能是上游已下线 — 请联系管理员或客服确认

发生了什么

额度按「请求次数」计,但一次任务在 Claude Code / Cursor 里其实包含多次请求:

• 你说「帮我改这个文件」→ AI 先读文件(1 次)→ 思考(1 次)→ 写代码(1 次)→ 运行测试(1 次)→ 修 bug(1 次)→ 共 5 次
• 复杂多文件改动 30-50 次很正常,这都是 AI 在帮你干活
• 余额页(/balance)显示累计请求次数,不是任务次数

你应该做什么

1. 打开 余额查询页 paste 你的 sk-key 看实时用量(7 天图表)
2. 看 7 天图表是否有异常突刺(被盗用 Key 的征兆),如有立刻去 FAQ 24 重置 Key
3. 想省额度:
   • 短问题用 gpt-5.6-luna
   • 日常任务用 gpt-5.6-terra(默认)
   • 大型重构用 gpt-5.6-sol
4. Token 计费原理见 FAQ 13(怎么省 token)

异常突刺怎么判断

正常	异常
白天 9:00-22:00 高,夜里低	夜里 2-5 点突然有大量调用
每天总量在 ±50% 范围波动	某天暴涨 5 倍以上
每次任务 5-50 次请求	持续 30 分钟单分钟 60 次撞限流

还不行?

把以下信息发客服:

• Key 末 4 位
• 当前用量 / 总额度
• 怀疑被多扣的时间段(精确到小时)
• 那段时间你在干什么

我们后台能查到每一次请求的时间戳,多扣的部分按 [我方原因](#faq-19) 全额退款到额度。

相关错误码:BILL01 · BILL02

发生了什么

先按实际现象判断:

• 首字延迟 1-5 秒:正常,符合预期
• 首字延迟 5-15 秒:正常上限,正在排队
• 首字延迟 > 30 秒:异常,大概率上游某账号被限流

不要用 Claude alias 推断上游；Console 中的 upstream / billing model 才是实际身份。

你应该做什么

优先级从高到低:

1. 轻量任务切换到 gpt-5.6-luna；Claude Code 中用 /model haiku 切换对应角色
2. 检查本机网络 — ping api.handsfreeclub.com,> 200ms 建议开 VPN / 换网络(详见 FAQ 17 跨境网络)
3. 看 实时状态页 — 全绿就是上游问题,等高峰过
4. 保留错误码和时间戳，便于判断模型、网络还是上游问题
5. 判断锅在哪 — 看 FAQ 18 是你们的问题还是上游?

还不行?

状态页全绿但你这边持续慢 > 5 分钟:

• 发给管理员或客服:Key 末 4 位 + traceroute api.handsfreeclub.com 截图 + 你跑的具体命令
• 30 分钟内必回

相关错误码:SVR05 · RL01 · STREAM02

Token 怎么数

• 英文:1 word ≈ 1 token,标点 + 空格也算
• 中文:1 字 ≈ 1.5-2 tokens(古文 / 生僻字更多)
• 代码:每行 ≈ 5-15 tokens(取决于变量名 / 缩进 / 复杂度)
• example:5000 行 markdown ≈ 80,000-150,000 tokens

额度计费

维度	当前规则
余额单位	USD 通用余额
固定档位	$30 / $100 / $500
扣费规则	按余额页当前展示的模型价格与实际 usage 扣费
自定义金额	联系管理员或客服人工充值，由管理员核对后入账
核对方式	以 Console 的余额和扣费流水为准

怎么省 token

1. 批量提问:5 个相关问题合并成 1 个 prompt
2. 关闭非必要工具:Claude Code 里 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 关掉 telemetry
3. 明确任务边界:「读这个文件 → 改 X 函数 → 跑测试」一次说清,避免 AI 来回 ping pong
4. 用 /clear 切话题:换任务前 clear,避免拖着旧 context 反复发
5. 用好 Prompt Caching(下一条 FAQ)

还不行?

觉得用量明显比预期高:

• 看 余额页 7 天分布,锁定哪天 / 哪小时暴涨
• 那天具体在跑什么任务?发客服判断是否正常
• 怀疑被多扣 → 走 FAQ 11

缓存怎么生效

• Anthropic 原生:client 在 system 或 messages 块加 cache_control: {"type":"ephemeral"} 标记
• OpenAI 原生:GPT-5.6 Terra / 4.x 自动缓存 ≥1024 token 的 prefix,无需标记
• 缓存阈值、有效期和计价可能随模型及价格 revision 变化，以当前上游响应为准

能省多少

没有跨模型统一答案。请按 request_id 对比 cache token、价格 revision/hash、账户有效倍率与最终费用；不要用旧公开单价或 Claude alias 手算。

客户端默认配置

• 不同客户端与版本的缓存行为不同；升级客户端不能保证命中
• GPT-5.6 的实际缓存结果看 OpenAI usage 字段，Claude-native 看 Anthropic usage 字段

怎么验证命中了

1. 看响应 usage.cache_read_input_tokens(Anthropic)或 usage.prompt_tokens_details.cached_tokens(OpenAI)字段 > 0
2. 用 Console 的 request_id 明细核对实际执行模型、cached tokens、价格快照和费用
3. 没命中?多半是 prompt 前缀变了(每次都加时间戳 / 随机 ID 会破坏缓存)

还不行?

明显该命中却没命中,把请求 ID 发客服,我们查上游缓存状态。

限流规则

维度	阈值	触发后
每分钟请求数	60 req/min	429 + Retry-After header
瞬时突发	20 req(令牌桶)	429,等令牌恢复
单调用 input	200K tokens	413 Payload Too Large
单调用 output	8K tokens	响应被截断 + stop_reason: max_tokens

我们做了什么自动重试

• 客户端层:Claude Code / Cursor 等内置 3 次指数退避(1s / 2s / 4s)
• 我们的中转层:撞上游限流 → 自动重试或切换可用通道(对你完全透明)
• 客户感知:你看到的 429 只在「连续 3 次重试都失败」后才返回

你应该做什么

1. 看到 429 → 等 30-60 秒再发(客户端通常会自动 retry,你也可以手动重发)
2. 如果是批量调用(脚本一次发 100 个) → 在你的脚本里加 sleep 1 让 QPS 控制在 1/秒
3. 持续撞 429 → 降低并发和单请求 token；不要依赖切换 alias 绕过限流
4. 常态高频用户 → 联系管理员或客服申请升级配额

还不行?

• 持续超 5 分钟 429 → 联系管理员或客服并提供 Key 末 4 位 + 触发时间
• 30 分钟内调阈值 / 临时给你切独立通道

相关错误码:RL01 · RL02

什么是流式输出

Anthropic 协议默认流式(stream: true):AI 边生成边发回,你看到字一个个蹦出来。优点:首字延迟低、可中断。

常见中断原因

现象	原因	怎么办
生成到一半突然停	客户端连接被网络中断(WiFi 切换 / VPN 抖动)	重发,Claude Code 会接着写
第一个字出来后断	上游通道在你说话期间被限流或连接抖动	我们自动重试或切换通道,你重发 1 次
大段输出 30s 后断	nginx 连接超时(默认 60s 心跳)	我们已加心跳,如重现告诉我们
固定在某个字断	你的网关 / 防火墙过滤特定字符 (罕见)	关闭特殊代理 / VPN 测试

你应该做什么

1. 先重发 — 客户端通常自动 retry,实在不行手动重发
2. 检查网络稳定性 — ping api.handsfreeclub.com 持续 30 秒,看丢包率
3. 关流式试试(只在调试时用) — 大多数客户端不直接暴露,可以告诉客服切非流式渠道排查
4. 切 haiku — 短输出更不易断

还不行?

1 小时内多次中断 → 联系管理员或客服:

• Key 末 4 位
• 中断时间(精确到分钟)
• 客户端 + 网络环境(WiFi / 4G / 公司网)
• 有没有开 VPN(VPN 类型)

相关错误码:STREAM01 · STREAM02 · NET02

错误码 8 大类

前缀	含义	责任	动作
AUTH	Key 鉴权	通常你	检查 Key 完整 / 有效 / 未过期
RL	限流	上游高峰	等 30-60 秒或换 haiku
SVR	服务端故障	我们	已自动重试,看状态页
REQ	请求格式	通常你	模型名 / 参数范围
BILL	计费 / 额度	通常你	余额页 + 充值
STREAM	流式中断	网络	重发或关流式
MODEL	模型限制	通常你	max_tokens / 模型已下线
NET	网络层	本地	检查 BASE_URL 拼写

常见错误 Top 6 速查

代码	触发	解
AUTH01	key 错或过期	检查 sk- 开头 + 完整复制;dashboard 验证
AUTH02	key 被作废(泄露)	找客服重新发(FAQ 24)
RL01	每分钟超 60 次	等 1 分钟(FAQ 14)
SVR04	上游 5xx	等 30s 重试,持续 2 分钟找客服
NET01	无法连接	BASE_URL 拼写 + ping
REQ02	模型名错	4-6 不是 4.6

找客服必带 4 项

我的 Key 末 4 位 abcd
报错代码 AUTH01
完整报错截图(整个红字面板)
我刚才在干什么(关键!)

带齐这 4 项,90% 客服 5 分钟内能给出明确解决方案。

还不行?

错误码不在表里 → 直接发完整截图,我们对照内部错误库给翻译。

第 1 步:基础连通性

# 测延迟
ping api.handsfreeclub.com
# 正常:50-200ms
# 不通:跳到第 2 步

# 测 DNS
nslookup api.handsfreeclub.com
# 应返回 1.x.x.x 或 104.x.x.x (Cloudflare)

第 2 步:HTTPS 通不通

curl -v https://api.handsfreeclub.com/v1/models
# 看是否能拿到 JSON 模型列表
# 卡在 SSL handshake → 中间网关有 TLS 拦截
# 401 → 通了,只是没带 key,正常

不通常见原因 + 解

现象	原因	解
DNS 解析失败	本地 DNS 缓存 / 公司 DNS 拦截	切 1.1.1.1 / 8.8.8.8;手机热点测试对比
ping 通但 https 不通	公司网关 SSL 检测	问 IT 加白名单 *.handsfreeclub.com,或换网络
延迟 > 500ms	运营商绕路 / 高峰	晚上换 4G 测对比
校园网完全不通	校园 NAT 限制境外	开学校 VPN / 换手机热点

VPN 推荐?

• 大部分用户不需要 VPN,直连香港 / 新加坡延迟 50-200ms 够用
• 如确实卡,推荐 Clash / Surge 设规则:只有 api.handsfreeclub.com 走代理,其他直连(避免被代理误伤)
• 不要用免费 VPN(可能截获你的 sk-key)

还不行?

把以下信息发客服:

• traceroute api.handsfreeclub.com 截图(macOS / Linux)或 tracert(Windows)
• 所在地区 + 运营商(电信 / 联通 / 移动)
• 是否在公司 / 学校特殊网络

30 分钟内排查并提供方案(可能需要切第二个域名 backup)。

相关错误码:NET01 · NET02 · NET03

5 分钟自检流程

1. 看我们的实时状态:https://status.handsfreeclub.com
   • 全绿 + 历史 7 天可用率 ≥ 99.9% → 我们正常
   • 有红 → 我们承认,等公告
2. 看 OpenAI 官方:https://status.openai.com
   • 有红 → 上游故障,跟我们无关,等他们修
   • 全绿 → 排除上游
3. curl 直测我们端点:

   curl -i https://api.handsfreeclub.com/v1/responses \
     -H "Authorization: Bearer $OPENAI_API_KEY" \
     -H "content-type: application/json" \
     -d '{"model":"gpt-5.6-terra","input":"Reply with OK only","max_output_tokens":8}'

   • 200 OK → 我们正常,问题在你的客户端 / 配置
   • 5xx → 我们或上游(对照状态页判断)
   • 429 → 你被限流
   • 403 → Key 未开放 GPT-5.6 或不属于 openai-default
   • 400 → 模型名或请求格式错误
   • 401 → key 错

常见组合

状态页	curl	结论
全绿	200	你的客户端 / 网络问题
全绿	5xx	状态页有延迟,我们刚出问题,等 5 分钟看公告
我们红	5xx	我们的问题,看公告 ETR
Anthropic 红	5xx	上游问题,我们也没办法,等
全绿	timeout	你的本地网络(FAQ 17)

我们的承诺

• 我们的故障会在 status page 5-7 分钟内触发监控告警，管理员或客服同步进度
• 连续 30 分钟不可用 → 主动补 1 天时长 / 走 [我方退款](#faq-19)
• 上游故障我们不甩锅,会同步原因 + 切换备用账号

还不行?

判断不出哪一边，请联系管理员或客服并带上面 3 个截图,我们当场对账。

退款政策(2026-05-02 Ethan 拍板)

原因分类	判定	金额
我方原因	主路径不可用 ≥30 分钟 / 服务下线 / 扣错钱 / 给错档位	全额按余量退(剩余天数 / 总天数 × 售价)
非我方原因	Claude 写错代码 / 觉得卡 / 客户网络 / 觉得不好用 / 跟同行比贵	剩余金额半退(余量 × 50%)

举例:账户还剩 $20 未使用额度:
· 我方原因 → 按规则退还全部 $20 对应实付金额
· 非我方原因 → 按规则退还其中 50% 对应实付金额

怎么申请

1. 联系管理员或客服，发送以下 4 项 + 退款理由:
   • 付款时间(精确到天)
   • 付款金额
   • 付款渠道(微信 / 支付宝)
   • 付款单号(订单页可复制)
   • 退款理由(我们据此判定我方/非我方)
2. 30 分钟内客服首响,确认金额
3. 1-3 个工作日原路退回(微信付的退微信、支付宝付的退支付宝)
4. 后台:立即停用你的 sk-key，避免后续继续产生请求

什么是「我方原因」(明文清单)

✓ 是我方

• 主路径不可用连续 ≥30 分钟(对照 status page 历史)
• 服务下线 / 跑路
• 计费 bug 多扣额度
• 给错额度(例如购买 $100，但实际只入账 $30)

✗ 非我方

• Claude 写错代码 / 答得不好(模型本身问题,Anthropic 也一样)
• 客户本地网络问题(不通 / 慢)
• 客户主观觉得「卡」「不好用」「跟同行比贵」

还不行?

我方/非我方判定有争议:

• 客服会主动调出 status page 历史 + 你的调用日志判断
• 双方分歧大 → 主动让你 2-3 句话陈述,我们倾向客户(初创品牌口碑 > 单笔利润)
• 明确属于灰色地带的(故障时间 25 分钟接近 30 分钟阈值)→ 直接按我方处理

详细政策:CUSTOMER_JOURNEY_SPEC §1 决策 ②③

自助追加

1. 进入充值页面，选择 $30、$100 或 $500
2. 在链动小铺完成付款并获取兑换码
3. 回个人中心兑换，确认余额增加

自定义金额

需要固定档位以外的金额时，联系管理员或客服，提供注册邮箱和充值金额。管理员核对转账后在后台入账，请在余额页核对最终结果。

• 下单前请核对档位、付款金额和到账额度
• 页面价格发生变化时，只影响之后的新订单
• 人工自定义充值以客服确认的金额和到账额度为准
• 对订单或入账有疑问时，提交订单号、注册邮箱和余额截图核查

当前阶段(Phase 1)

个人收款(微信 / 支付宝)无法开发票:

• 客户付款是个人对个人转账性质
• 我们提供付款记录截图 + 服务说明 word 文档,部分公司可作为内部报销凭证
• 需要发票的客户建议等 Phase 2再买,或同时考虑直接 Anthropic 官方

Phase 2(¥5k 流水后,预计 1-2 月内)

切换链动小铺平台:

• 链动小铺支持个人服务发票(电子版),客户在链动小铺后台自助申请,2-5 工作日 PDF 邮件发到注册邮箱
• 金额 = 实付金额(含平台手续费)
• 抬头 = 个人姓名 / 公司全称都可以
• 票面项目:「信息技术服务费」

Phase 3(注册公司后,3-6 月内)

注册个体工商户 / 有限公司,接微信支付商户号:

• 普通增值税电子发票:免费、所有客户均可、税率 6%(信息技术服务)
• 专用发票:需企业一般纳税人资质、税率 6%、邮寄纸质或电子均可
• 合并开票:同一抬头一年内的多笔订单可合并开一张大票

需要发票的临时方案

1. 找客服说明用途 → 我们出具「服务说明 + 付款确认函」(word + 盖创始人电子签),部分小公司可入账
2. 同时建议你直接走 Anthropic 官方(他们有正式境外 invoice,部分公司接受)
3. 等待 Phase 2 上线 → 老客户可补开历史订单的电子凭证(从 Phase 1 起算,但需要补充资料)

还不行?

大额度团队 / 企业(单笔 ≥ ¥2000)有强发票需求:

• 联系管理员或客服说明「企业方案」，确认当前可用的开票流程
• 价格 + 发票挂钩,会有 5% 手续费,提前商量

相关错误码:无

共用单 Key 的问题

• 限流互踩:同时 3 人发请求,60 req/min 限流共享,容易撞 RL01
• 账目不清:谁用了多少看不到,内部对账难
• 泄露风险放大:任何一人电脑丢了 / 离职没回收,全员的 Key 都得换
• 额度配额耗得快:人均算下来比单人买进阶包更贵

当前阶段方案

方案 A:每人各自注册(推荐 ≤ 3 人)

• 每人分别购买所需的固定额度，各自按公司流程报销
• 规模 ≤ 2 人或不需要管理视角
• 缺点:对账靠每人提供

方案 B(过渡):暂时共用(只适合 ≤ 2 人 / 临时项目)

• 按团队预计用量充值，额度不足时继续按需充值
• 注意:务必只在受信任同事之间
• 限流大概率撞,做好心理准备

团队额度包(规划中,Phase 2 上线)

• 1 个主 Key(管理员)+ N 个副 Key(团队成员各 1 个)
• 主 Key 后台能看每个副 Key 用量、独立设上限、随时禁用某个
• 所有副 Key 共享主 Key 的总额度池
• 团队方案按实际用量和所需并发评估，请联系管理员或客服确认
• 感兴趣的请提前联系管理员或客服，功能上线后优先通知

企业方案(≥ 10 人 / 跨地域)

• 联系管理员或客服开 定制方案:
  • 企业域邮箱登录 / SAML SSO
  • 按部门 / 项目分组的额度池
  • 专属客户成功经理 + 1 小时响应
• 价格视规模,≥ ¥2000 / 月起,签年度合同打 8 折

还不行?

团队场景特殊(跨国 / 多分公司 / 需 SOC2)，请联系管理员或客服详谈，我们会明确当前能提供的范围。

相关错误码:RL01(共用导致限流)

常见泄露场景

• Key 写到 GitHub 公开仓库被爬走(GitHub Secret Scanning 会通知,但已被爬到)
• 截图发群忘记打码
• 共用电脑没退账号
• 钓鱼邮件 / 钓鱼网站骗你输 Key
• 公共 WiFi 被中间人攻击(罕见,因为是 HTTPS)

泄露的征兆

看 余额页 7 天图表:

• 夜里突然有异常用量(凌晨 2-5 点你没在工作但有大量请求)
• 陌生 IP 段(我们后台日志可查,客服能告诉你来源国)
• 额度断崖下跌(几小时跑掉 50% 以上)

应急流程(分钟级)

1. 立刻联系管理员或客服:报「Key 泄露」+ 注册邮箱，并按要求完成身份验证
2. 客服5 分钟内后台:
   • 找到你的 user
   • 旧 sk-key 状态改 revoked(立即生效,旧 key 调用立即返 401)
   • 同 user 创建新 sk-key(余额 / validity 不变)
3. 客服通过确认的安全渠道发送新 sk-key
4. 系统自动发事务邮件「您的 API Key 已重置」到 user.email(防止恶意操作)
5. 你改客户端 settings.json / env 里的 key,重启即恢复
6. 如确认有被盗用扣量,告诉客服时间段 + 你那段时间在哪 / 在干什么(证明不是你)→ 后台调日志确认非本人 IP / 异常 pattern,被盗用部分全额退回额度

预防(永远胜于补救)

• 永远不要把 Key 提交到 git。用 .env + .gitignore,或者用 direnv
• 群聊截图先打码后端 4 位
• 每月在 余额页扫一眼图表,看有没有突刺
• 开启余额预警邮件(默认 75% / 90% / 100% / 到期 3 天前自动发邮件)
• 如多人共用想分账,等 [团队额度包](#faq-23)(Phase 2 上线)

还不行?

怀疑严重盗刷(已经掉 80% 以上余额):

• 客服优先级提到 P0,3 分钟内响应
• 同步给 Ethan(创始人)亲自跟进
• 必要时配合你提供 IP 取证(报警材料)

相关错误码:AUTH01 · AUTH02

数据流(诚实版)

HTTPS 加密只保护「客户端 ↔ 我们服务器」和「我们服务器 ↔ 上游模型服务」两段,我们中间这一跳必然能看到明文(任何中转服务都一样,不可避免)。

我们做了哪些(技术 + 法务双层)

• 不存:nginx access log 只记 HTTP method / 路径 / 状态码 / token 数,请求 body 直接丢弃不写盘
• 失败请求例外:5xx / 限流等失败请求会临时保留请求 body 用于排错,30 天自动 cron 清理(OpsCleanupService 已上线生产)
• 不读:运营人员无业务需要不会看你的请求,有需要(故障排查)会先脱敏
• 不训练:我们不是模型公司,我们没有训练任何 AI
• 不商用 / 不外发:任何形式的数据外流都不会发生
• 上游模型服务的数据处理政策以官方条款为准,我们侧不额外存储或训练你的内容

合规现状

项	当前(Phase 1)	Phase 3 目标
ICP 备案	暂无(域名走境外 Cloudflare)	注册公司后申请
营业执照	暂无(个人副业阶段)	个体工商户 / 有限公司
用户协议	本 FAQ 即简版条款	正式版上线
隐私政策	本 FAQ §25 即简版	正式版上线
SOC2 / GDPR	无	视客户需求评估

你应该怎么做

1. 一般工作 / 学习内容:不必担心,正常用
2. 商业敏感 / 法律 / 医疗等高敏感:
   • 建议用 Anthropic 官方企业版(他们和你签 BAA / SOC2 等正式协议)
   • 或本地部署开源模型(Qwen / DeepSeek 等)
3. 身份证 / 银行卡 / 私钥:任何 AI 服务都不要发,包括 Anthropic 官方,这是基本操作

NDA / DPA

需要书面隐私保密协议:

• 联系管理员或客服说明用途,我们提供 v1 模板,双方电子签
• 企业客户 100% 提供,个人客户根据情况
• 违约赔偿条款 = 退还历年付款的 5 倍封顶
• Phase 3(公司化后)起可签更严格的 DPA

还不行?

具体合规问题(GDPR / SOC2 / 等保 / HIPAA)，请联系管理员或客服详谈，我们能做的会照实说明。

相关错误码:无 · 详见 隐私政策全文(Phase 3 上线)