客户端接入指南

在 Claude Code 接入 Handsfree Club

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

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

原本

https://api.anthropic.com

→

改成

https://api.handsfreeclub.com

只改 ANTHROPIC_BASE_URL 一个字段,其他配置全部沿用

30 秒摘要

设环境变量:ANTHROPIC_BASE_URL=https://api.handsfreeclub.com + ANTHROPIC_AUTH_TOKEN=sk-xxxx(同时设 ANTHROPIC_API_KEY 同值兼容 OpenClaw 等),然后 claude 启动。完事。模型名、API 协议跟官方完全一致,Claude Code 不会感知到你换了后端。

⚡ 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
curl -fsSL https://handsfreeclub.com/install.sh | bash -s -- --key sk-你的key

Windows PowerShell

# 按 Win 键,输入 PowerShell,普通模式打开后粘贴
$env:HFC_KEY="sk-你的key"; irm https://handsfreeclub.com/install.ps1 | iex

脚本会:① 用 claude-haiku-4-5 探活验证 Key + 链路 ② 写 ~/.zshrc / ~/.bashrc(三个 ANTHROPIC_* + 两个 OPENAI_* 变量,自动备份原文件) ③ Codex 单独写 ~/.codex/config.toml + auth.json(权限 600) ④ 没 Node 自动装 nvm + LTS ⑤ 装好 claude + codex 二进制。 Hermes Agent ☤(NousResearch 出的接班人,读 ANTHROPIC_API_KEY / OPENAI_API_KEY,跑 hermes model 选 provider 即用)和 OpenCode (sst)(读 ANTHROPIC_AUTH_TOKEN)装完同样即用。原 OpenClaw 🦞 用户:跑 hermes claw migrate 一行迁过来。

或者手动配置 ↓

注册账号,拿 API Key#

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

key

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

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

配置 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"
  }
}

项目级覆盖也支持:在项目根目录创建 .claude/settings.json,只对当前项目生效。团队协作时把 base_url 提交,token 走环境变量。

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

macOS / Linux bash / zsh

export ANTHROPIC_BASE_URL="https://api.handsfreeclub.com"
export ANTHROPIC_AUTH_TOKEN="sk-XXXXXXXXXXXXXXXXXXXXXXXX"

Windows PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.handsfreeclub.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-XXXXXXXXXXXXXXXXXXXXXXXX"

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

启动验证#

在任意目录跑:

terminal

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

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

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

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

我们不改模型名、不偷换型号。Claude Code 里 /model 切换的所有选项都直通官方:

Claude Code 选项	实际模型 ID	状态
Default	`claude-sonnet-4-6`	就绪
Opus	`claude-opus-4-7`	就绪
Sonnet	`claude-sonnet-4-6`	就绪
Haiku	`claude-haiku-4-5`	就绪

切换命令: /model opus · /model sonnet · /model haiku。计费按官方各自的 token 价格 1:1 折算,Opus 比 Sonnet 贵约 1.7x,Haiku 比 Sonnet 便宜约 3x,跟官方完全一致。

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

日常写代码

Sonnet

默认就用它。性价比最高,改 bug、加 feature、refactor 全胜任。Claude Code 默认档。

难题 / 架构 / 卡壳

Opus

Sonnet 解不出再切。贵约 1.7x,适合大型重构、调试诡异 bug、设计新系统。/model opus 切换。

简单任务 / 批量处理

Haiku

格式化、提取、文案、批量改名。便宜约 3x,响应也快。/model haiku 切换。

常见错误速查#

401

认证失败

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

404 / ENOTFOUND

地址写错

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

429

本日 cap 已用满

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

402 / quota

月度额度耗尽

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

502 / 503

上游或网关问题

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

invalid model name

模型名拼错

用 /model opus / sonnet / haiku 切换,别手敲完整 ID。如果一定要写完整 ID,参考上面 step 4 的映射表(注意 4-6 不是 3-5)。

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 这些功能能用吗?

全部能用,我们不阉割任何官方功能。因为我们是协议中转——你的请求 → 我们 → Anthropic 官方,官方该返回什么就返回什么。Claude Code 端的 SDK 不知道中间换了后端,所有 client-side 功能(skill 加载、hook 触发、MCP server 通信)都是本地行为,跟我们无关。

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

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

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

Claude Code 的 prompt cache 怎么算钱?

跟官方完全一致。cache write 1.25x、cache hit 0.1x,我们透传计费。Claude Code 自己会大量用 cache(整个项目结构、CLAUDE.md、最近编辑的文件),实际花费比"按 input/output 算"低很多——这是我们便宜的原因之一。

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

Claude Code 的 /usage 是本次会话的 token 统计,我们 Console 是账号维度的累计 USD 消耗。两者口径不同但相互对得上——你可以拿一次会话的 token 数 × 模型单价,跟 Console 这段时间的消耗增量比较,误差不超过 1%(差额来自 cache 和 system prompt)。

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

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

如果你跑超并发 swarm(同时 50+ Claude Code 实例),提前在 Telegram 联系我们,我们走独立 API key shard给你。

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

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

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

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

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

注册账户 → 查看套餐价格