客户端接入指南

在 Claude Code 接入 Handsfree Club

30 秒搞定。Claude Code 是 Anthropic 官方 CLI,我们做的是协议中转,你只需把它指向我们的 API 入口,代码 0 行改动,/agents、/skills、hooks、MCP 全部原版可用。

openai-default 的 GPT 用户：Claude Code 继续走 Anthropic 协议，但模型变量直接填真实 GPT 身份：gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna。日志、用量和计费均显示实际 GPT，不再伪装成 Claude。

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

原本

https://api.anthropic.com

→

改成

https://api.handsfreeclub.com

保留 Anthropic 协议；openai-default 再把 Claude Code 三档角色指向真实 GPT-5.6

30 秒摘要

设 ANTHROPIC_BASE_URL=https://api.handsfreeclub.com（无 /v1）和原 Key。openai-default 用户再设 ANTHROPIC_MODEL=gpt-5.6-terra；旧 claude-* 只作为 legacy alias 保留，实际执行、日志和计费身份仍是 GPT。

⚡ Step 0 · 推荐

一键脚本:跳过下面所有手动配置

非技术用户、嫌麻烦的、一台新电脑想几秒接通的,按系统复制一行命令。连 Node + Claude Code + Codex CLI 都帮你装好,配置自动写好。如果你不用 Codex 加 --only=claude;不希望脚本动你系统就加 --no-install-cli 或 Windows 的 -NoInstallCli(只写配置)。

macOS / Linux terminal

# 默认装 Claude Code + Codex CLI;只装一个用 --only=claude 或 --only=codex
bash <(curl -fsSL https://handsfreeclub.com/install.sh)

Windows PowerShell

# 按 Win 键,输入 PowerShell,普通模式打开后粘贴
& ([scriptblock]::Create((irm https://handsfreeclub.com/install.ps1)))

脚本会:① 在写文件前调用 /v1/responses 验证 Key 对 gpt-5.6-terra 的实际权限 ② Mac/Linux 将 Key 写入权限 600 的 ~/.config/handsfreeclub/env，shell rc 只保存 source 引用；Windows 写当前用户环境 ③ Codex 单独原子写入 ~/.codex/config.toml + auth.json（owner-only）④ 按需安装 CLI。若 Key 未授权或安装失败，脚本明确退出，不报告假成功。脚本只自动完成 Claude Code 和 Codex CLI，并准备标准的 OPENAI_API_KEY / OPENAI_BASE_URL。Hermes、OpenClaw、OpenCode 都必须按各自专项页注册 Handsfree OpenAI provider；脚本不会覆盖它们现有配置，也不要用 Anthropic 变量猜测 provider。

或者手动配置 ↓

注册账号,拿 API Key#

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

key

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

openai-default Key 已开放 Messages 调度时，可同时给 Claude Code 与 OpenAI 客户端使用；否则请按 Key 所属分组使用对应协议。

配置 Claude Code 指向我们#

有两种方式,选一种就行。推荐用 settings.json(持久,跨终端共享),临时调试用环境变量。

编辑 Claude Code 的全局配置文件,如果没有就新建:

系统	路径
macOS / Linux	`~/.claude/settings.json`
Windows	`%USERPROFILE%\.claude\settings.json`

把以下内容粘进去(已有 settings.json 就把 env 字段合并进去):

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.handsfreeclub.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-XXXXXXXXXXXXXXXXXXXXXXXX",
    "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"
  }
}

macOS/Linux 保存全局文件后执行 chmod 600 ~/.claude/settings.json；Windows 确认 owner-only。项目级文件只提交 base_url，不要把 token 提交到团队仓库。

临时用,关掉终端就失效。要永久生效写到 ~/.zshrc / ~/.bashrc。

macOS / Linux bash / zsh

export ANTHROPIC_BASE_URL="https://api.handsfreeclub.com"
read -rsp "HFC API Key: " ANTHROPIC_AUTH_TOKEN; printf "\n"; export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_MODEL="gpt-5.6-terra"
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5.6-sol"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-terra"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"

Windows PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.handsfreeclub.com"
$secureKey = Read-Host "HFC API Key" -AsSecureString
$env:ANTHROPIC_AUTH_TOKEN = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:ANTHROPIC_MODEL = "gpt-5.6-terra"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "gpt-5.6-sol"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "gpt-5.6-terra"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "gpt-5.6-luna"

已经登录过官方 Anthropic 账号的话,先跑 claude /logout 清掉旧凭证,否则 token 会被官方 OAuth 覆盖。

启动验证#

在任意目录跑:

terminal

$ claude
# 看到 "Welcome to Claude Code" 后随便问一句
> 你好,确认下走的是 Handsfree Club 中转?

首次运行会先让你选主题(Dark/Light)、信任当前文件夹、接受用户协议——全部按回车走默认就行,过完才进对话界面。不是卡住,是 onboarding。

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

Claude Code 角色与真实 GPT 身份#

Claude Code 仍发送 Anthropic Messages 请求，但 openai-default 的三档角色直接绑定精确 GPT-5.6 tier；日志、用量和计费显示实际 GPT:

Claude Code 角色	实际模型 ID	状态
Default	`gpt-5.6-terra`	就绪
Opus	`gpt-5.6-sol`	就绪
Sonnet	`gpt-5.6-terra`	就绪
Haiku	`gpt-5.6-luna`	就绪

切换命令仍是 /model opus · /model sonnet · /model haiku，但三档执行身份分别为 Sol、Terra、Luna。费用按实际执行模型和已验证价格计算，以 Console 用量记录为准。旧 claude-* 仅作 legacy alias，不建议新配置继续使用。

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

日常写代码

Terra

默认就用它，适合改 bug、加 feature、refactor 和日常 Claude Code agent 流程。

难题 / 架构 / 卡壳

Sol

Terra 解不出再切，适合大型重构、复杂调试和系统设计。用 /model opus 切换角色。

简单任务 / 批量处理

Luna

格式化、提取、文案和批量改名等轻量任务。用 /model haiku 切换角色。

常见错误速查#

401

认证失败

检查 ANTHROPIC_AUTH_TOKEN 末 4 位是否跟 Console 显示一致。常见坑:复制时漏了 sk- 前缀。

404 / ENOTFOUND

地址写错

检查 ANTHROPIC_BASE_URL 是否为 https://api.handsfreeclub.com(注意是 api. 前缀,不是裸域名)。

429

请求被限流

短时限流请稍后重试；若持续出现，请保留时间戳和错误码联系管理员核查上游通道。

402 / quota

账户额度耗尽

账户额度已用完。请到充值页面选择额度，链动小铺付款后获取兑换码，再回个人中心兑换；需要其他金额时，可联系管理员或客服人工自定义充值。去充值 →

502 / 503

上游或网关问题

上游或我方网关异常时可能出现。先保留错误码和时间戳；持续 5 分钟以上查看 status page。模型或权限问题应返回明确 4xx，不应反复重试成 503。

400 / 403

模型或分组未通过预检

裸 gpt-5.6 返回 400，请用 Sol / Terra / Luna 精确 ID；Key 不属于 openai-default 或未开放 GPT-5.6 时返回 403。升级 Claude Code 不能替代模型配置与权限开通。

OAuth 提示

跳到官方登录页

说明 Claude Code 没读到 ANTHROPIC_AUTH_TOKEN。先 claude /logout,确认环境变量已 export,重启终端。

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

FAQ · Claude Code 用户常问#

/agents、/skills、hooks、MCP 这些功能能用吗?

Skill 加载、hook 触发和 MCP server 通信属于 Claude Code 本地能力，通常不受模型名称影响；模型侧的具体工具调用能力仍以当前 Claude Code 版本、所选 GPT tier 和实际响应为准。

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

能。Key 没设备绑定,家里 + 公司 + 项目 A + 项目 B 同时跑都行,所有调用合并计入同一个账户余额。

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

Claude Code 的 prompt cache 怎么算钱?

缓存 token 以实际上游 usage 和 Console 账单记录为准。不同 GPT tier、请求形态和上游价格 revision 可能不同，本教程不承诺固定缓存倍率。

我用 /usage 看到的额度跟你们 Console 对得上吗?

Claude Code 的 /usage 与 Console 统计维度可能不同。对账以 Console 中记录的实际执行模型、token、价格 revision 和费用结果为准；不要用 Claude alias 的公开价格自行估算 GPT 费用。

我用 Claude Code 跑 long-running agent loop,会不会触发限流?

是否触发限流取决于账户配置、Key、并发、请求 token 和上游容量。遇到 429 请按响应提示降低并发或等待重试；大规模并发前先在 Telegram 联系我们确认容量。

能用官方订阅(Claude Pro / Max)的 OAuth 登录吗?

不行。我们走的是 API token 模式,不是 OAuth。如果你之前登过官方账号,先 claude /logout 清掉,然后按本页 Step 2 的方式配 token 即可。

这其实是好事——官方 OAuth 走 Pro/Max 订阅的额度有"5 小时 session 重置"等限制,我们的 token 模式没这些坑,纯按 USD 用量计费,用多少花多少。

跑通了?现在就把 Claude Code 接上来

注册不再自动发放体验额度。需要先验证链路时，可充值 $30 固定额度；也可联系管理员或客服人工自定义充值。

去充值额度 → 查看额度档位