客户端接入指南

在 Codex 接入 Handsfree Club

30 秒搞定。Codex 是 OpenAI 官方 CLI，我们做协议中转，改一个 base_url 即可接入。GPT-5.6 Sol / Terra / Luna 三档已就绪，所有本地能力（slash commands、approval mode、MCP）原版保留。

GPT-5.6 仅限 openai-default 分组：原 Key 和 Base URL 不变；精确选择 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna。裸的 gpt-5.6 会返回 400，未授权分组返回 403。

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

原本

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
bash <(curl -fsSL https://handsfreeclub.com/install.sh)

Windows PowerShell

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

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

脚本会在写文件前用 gpt-5.6-terra 调用 /v1/responses 验证 openai-default 权限，再写 ~/.codex/config.toml 与权限收紧的 auth.json，并同步 Claude Code 的 GPT-5.6 角色变量。403 会明确退出且不写配置；随后按需安装 Node LTS、Codex 和 Claude Code。

或者手动配置 ↓

注册账号,拿 API Key#

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

key

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

GPT-5.6 仅限 openai-default。该 Key 已开放 Messages 调度时，才可同时给 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.6-terra"
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"
}

不要把 provider 配置放到项目级 .codex/config.toml。Key 只写入用户级 auth.json，macOS/Linux 保存后执行 chmod 600 ~/.codex/auth.json；Windows 收紧为当前用户 owner-only。权限失败不要继续，也不要提交到仓库。

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

macOS / Linux bash / zsh

export OPENAI_BASE_URL="https://api.handsfreeclub.com/v1"
read -rsp "HFC API Key: " OPENAI_API_KEY; printf "\n"; export OPENAI_API_KEY

Windows PowerShell

$env:OPENAI_BASE_URL = "https://api.handsfreeclub.com/v1"
$secureKey = Read-Host "HFC API Key" -AsSecureString
$env:OPENAI_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password

已经用 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 字段使用真实执行 ID；GPT-5.6 必须精确选择 Sol / Terra / Luna:

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

切换:在 Codex 里输入 /model gpt-5.6-sol · /model gpt-5.6-terra · /model gpt-5.6-luna,或者改 config.toml 的 model 字段后重启。三档都已就绪，计费按真实执行模型和请求时价格快照结算。

建议先升级，但不能只升级 Codex。先运行 codex update（或 npm i -g @openai/codex@latest），再把用户级配置中的模型显式改成精确档位；升级客户端不会自动切换到 GPT-5.6。

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

默认 / 主力档

GPT-5.6 Terra

日常工程默认推荐，质量、速度和成本更均衡。/model gpt-5.6-terra。

硬骨头 / 长链路 agent

GPT-5.3 Codex

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

简单任务 / 省钱

GPT-5.6 Luna

格式化、提取、子代理批量任务，优先速度与成本。/model gpt-5.6-luna 切换。

常见错误速查#

401

认证失败

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

404 / ENOTFOUND

地址写错

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

429

请求被限流

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

402 / quota

账户额度耗尽

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

502 / 503

上游或网关问题

上游或我方网关异常时可能出现。持续 5 分钟以上查看 status page；权限或模型问题应返回明确 4xx。

model_not_found

模型名拼错

用 /model gpt-5.6-terra / gpt-5.3-codex / gpt-5.6-luna 切换。如果一定要写完整 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 清掉，运行 test -n "$OPENAI_API_KEY" && echo KEY_SET 确认变量已设置（不要输出完整 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 没设备绑定，多台机器的用量合并计算。只有属于 openai-default 且已开放 Messages 调度的 Key，才能同时用于 Claude Code 与 OpenAI 客户端。

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

Codex 用的 Responses API 你们支持吗?

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

Codex 自定义 provider 的 wire_api 保持 "responses"；不要改成 "chat"。GPT-5.6 当前使用 HTTP Responses，WebSocket 模板仍保留在已验证的 GPT-5.4 边界。

prompt cache、reasoning tokens 怎么算钱?

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

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 接上来

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

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