客户端接入指南

在 Codex 接入 Handsfree Club

30 秒搞定。Codex 是 OpenAI 官方 CLI,我们做的是协议中转,改一个 base_url 就能接入,2026-04 新王 GPT-5.5 / GPT-5.5 Pro 加上 GPT-5.4 / GPT-5.3-Codex 全系可用,所有本地能力(slash commands、approval mode、MCP)原版保留。

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

原本

https://api.openai.com/v1

→

改成

https://api.handsfreeclub.com/v1

只改 base_url 一个字段,API key 沿用我们发给你的 sk-…

30 秒摘要

编辑 ~/.codex/config.toml,把 base_url 改成 https://api.handsfreeclub.com/v1,再把 key 写进 ~/.codex/auth.json,跑 codex。完事。Codex 走的是 OpenAI Responses 协议,我们 1:1 透传。

⚡ Step 0 · 推荐

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

非技术用户、嫌烦的、新机器想几秒接通的,按系统复制一行命令。连 Node + Codex CLI + Claude Code 都帮你装好,~/.codex/config.toml + auth.json 自动写好。只想要 Codex 加 --only=codex;不希望脚本动你系统就加 --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

之前用 ChatGPT 账号 OAuth 登录过 Codex 的话,脚本跑完还要手动:codex logout 清掉 OAuth 凭证,否则 Codex 会优先走 OAuth、不读 auth.json。

脚本会:① 用 claude-haiku-4-5 探活验证 Key + 链路 ② 写 ~/.codex/config.toml([model_providers.handsfree] + wire_api = "responses")③ 写 ~/.codex/auth.json(权限 600,内含 OPENAI_API_KEY)④ 同时把 ~/.zshrc 三个 ANTHROPIC_* + 两个 OPENAI_* 变量也写好(Claude Code / Hermes Agent ☤ / OpenCode 通用)⑤ 没 Node 自动装 nvm + LTS ⑥ 装好 codex + claude 二进制。

或者手动配置 ↓

注册账号,拿 API Key#

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

key

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

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

配置 Codex 指向我们#

有两种方式,选一种就行。推荐用 config.toml(持久,Codex 默认会读),临时调试用环境变量。

编辑 Codex 的配置文件,如果没有就新建:

系统	路径
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

把以下内容粘进去(已有就合并 [model_providers.handsfree] 段):

~/.codex/config.toml

model = "gpt-5.5"
model_provider = "handsfree"

[model_providers.handsfree]
name = "Handsfree Club"
base_url = "https://api.handsfreeclub.com/v1"
wire_api = "responses"
requires_openai_auth = true

然后把 API Key 写到 Codex 的本地认证文件:

~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-XXXXXXXXXXXXXXXXXXXXXXXX"
}

项目级覆盖也支持:在项目根目录建 .codex/config.toml,只对当前项目生效。团队协作只提交 config,key 不进仓库。

不改 config.toml,纯 env 也行。Codex 默认读 OPENAI_BASE_URL 和 OPENAI_API_KEY:

macOS / Linux bash / zsh

export OPENAI_BASE_URL="https://api.handsfreeclub.com/v1"
export OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXXXXXXXXXX"

Windows PowerShell

$env:OPENAI_BASE_URL = "https://api.handsfreeclub.com/v1"
$env:OPENAI_API_KEY = "sk-XXXXXXXXXXXXXXXXXXXXXXXX"

已经用 ChatGPT 账号 OAuth 登录过 Codex 的话,先跑 codex logout 清掉旧凭证,否则 Codex 会优先走 OAuth、不读你设的 env。

启动验证#

在项目目录跑:

terminal

$ codex
# 进入交互界面后随便问一句
> 你好,确认下走的是 Handsfree Club 中转?

首次运行会询问 approval mode(suggest / auto-edit / full-auto)、信任当前 workdir,选完才进对话界面。如果你之前用 OAuth 登过,Codex 可能会忽略 env,记得先 codex logout。

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

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

我们不改模型名、不偷换型号。Codex 里 /model 切换或 config.toml 里的 model 字段,所有选项都直通官方:

Codex 选项	实际模型 ID	状态
Default(推荐)	`gpt-5.5`	就绪
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`	就绪

切换:在 Codex 里输入 /model gpt-5.5 · /model gpt-5.3-codex · /model gpt-5.4-mini,或者改 config.toml 的 model 字段后重启。计费按官方 token 价格 1:1 折算。gpt-5.5-pro 上游账号正在接入中,建议先用 gpt-5.3-codex 跑硬骨头。

GPT-5.5 已是 Codex CLI 当前主推默认(2026-04-24 起 API 全量开放,1M context、$5 / $30 per 1M tokens)。如果你的 Codex CLI 版本太老报错"requires a newer version",升到最新版即可——升级命令:npm i -g @openai/codex@latest。

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

默认 / 主力档

GPT-5.5

2026-04 frontier 新王,Codex CLI 当前默认。1M context、agentic coding 全面强于 5.4,token 用量更省。/model gpt-5.5。

硬骨头 / 长链路 agent

GPT-5.3 Codex

专门为 coding 长跑优化的 frontier 档,最难的重构、复杂 debug、长 agent 链路用它。/model gpt-5.3-codex。

简单任务 / 省钱

GPT-5.4 mini

格式化、提取、子代理(subagent)批量任务。速度 2 倍、用量额度 30%,适合长跑。/model gpt-5.4-mini 切换。

常见错误速查#

401

认证失败

检查 ~/.codex/auth.json 里的 key 末 4 位是否跟 Console 显示一致。常见坑:复制时漏了 sk- 前缀,或者 codex logout 没跑导致还在走 OAuth。

404 / ENOTFOUND

地址写错

检查 base_url 是否为 https://api.handsfreeclub.com/v1(注意末尾有 /v1,这是 OpenAI 协议路径)。

429

本日 cap 已用满

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

402 / quota

月度额度耗尽

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

502 / 503

上游或网关问题

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

model_not_found

模型名拼错

用 /model gpt-5.5 / gpt-5.3-codex / gpt-5.4-mini 切换。如果一定要写完整 ID,参考上面映射表。常见坑:写成 gpt-5、gpt-5-codex(老 ID,2026 已升到 5.5 / 5.3-codex)或 gpt-4(我们 GPT-5.4 起)。报"requires a newer version"就升级 Codex CLI:npm i -g @openai/codex@latest。

OAuth 提示

跳到 ChatGPT 登录页

说明 Codex 在走 OAuth 而不是 env。先 codex logout 清掉,确认 OPENAI_API_KEY 已 export(echo $OPENAI_API_KEY),重启终端。

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

FAQ · Codex 用户常问#

approval mode、slash commands、MCP 这些功能能用吗?

全部能用,我们不阉割任何官方功能。因为我们是协议中转——你的请求 → 我们 → OpenAI 官方,官方该返回什么就返回什么。Codex 端的所有本地能力(approval flow、slash commands、MCP server 通信、文件 patch 应用)都是 client-side 行为,跟我们无关。

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

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

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

Codex 用的 Responses API 你们支持吗?

支持。Codex 默认用 OpenAI 的 Responses API(/v1/responses),我们透传。这就是 config.toml 里 wire_api = "responses" 的作用。

如果你的工作流要用 Chat Completions(/v1/chat/completions),把 wire_api 改成 "chat" 即可。两个都 1:1 透传。

prompt cache、reasoning tokens 怎么算钱?

跟官方完全一致。cached input 0.1x、reasoning tokens 按 output 价计费,我们透传。Codex 在长会话里会大量复用 cache,实际花费比"按 input/output 单价算"低不少。

Codex 跑 agent loop / 高并发,会不会触发限流?

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

如果你跑超并发(50+ Codex 实例 / CI 流水线批跑),提前在 Telegram 联系我们,我们走独立 API key shard给你。

能用 ChatGPT Plus / Pro / Team 的 OAuth 登录吗?

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

这其实是好事——ChatGPT 订阅给 Codex 的额度有"周配额 + 使用上限"等限制,我们的 token 模式纯按 USD 用量计费,用多少花多少。

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

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

注册账户 → 查看套餐价格