ZCF
使用 ZCF 为 Claude Code 和 Codex 配置 CoffeeRouter。
接入前准备
开始前请准备：
- Node.js 22 或更高版本，以及可用的
npm/npx。 - 一个 CoffeeRouter 令牌。建议为 ZCF 单独创建令牌，便于后续撤销和审计。
- 当前令牌允许使用的准确模型 ID。
- 需要使用的目标工具：Claude Code 或 Codex。ZCF 可以在初始化过程中协助安装目标 CLI。
可以先阅读 ZCF 官方文档 或查看 ZCF 官方仓库。ZCF 是第三方社区工具，其菜单名称可能随版本更新；本文按当前官方版本编写。
地址与协议对照
ZCF 会根据目标工具生成不同格式的配置，不要混用以下地址：
| 目标工具 | ZCF 配置项 | 填写内容 | 协议 |
|---|---|---|---|
| Claude Code | API 基础 URL | https://www.coffeerouter.ai | Anthropic Messages |
| Codex | 基础 URL | https://www.coffeerouter.ai/v1 | OpenAI Responses |
Claude Code 的地址不带 /v1，因为客户端会在基础地址后拼接 Messages 请求路径。Codex 的自定义 Provider 接收 OpenAI API Base URL，因此需要保留一个 /v1。
启动 ZCF
在 PowerShell、终端或 WSL 中运行：
npx zcf
首次运行时，按提示选择界面语言和 AI 输出语言。如果 ZCF 当前管理的工具不是你需要的工具，在主菜单选择 切换工具，再选择 Claude Code 或 Codex。
如果尚未配置目标工具，可以选择 完整初始化；如果只需要修改 API 服务商，则选择 配置 API。ZCF 检测到已有配置时会提供备份、合并或保留选项，请先确认现有配置再继续。
接入 Claude Code
1. 选择自定义服务商
将当前工具切换为 Claude Code，进入 配置 API，选择 自定义 API 配置。在服务商列表中选择 自定义配置；如果已经存在 ZCF 管理的配置，则选择添加新配置。
2. 填写 CoffeeRouter 配置
按提示填写：
| 配置项 | 填写内容 |
|---|---|
| 配置名称 | CoffeeRouter |
| 认证类型 | API Key |
| API 基础 URL | https://www.coffeerouter.ai |
| API Key | CoffeeRouter 令牌，例如 sk-your-api-key |
不要把 API 基础 URL 写成 https://www.coffeerouter.ai/v1，否则 Claude Code 可能生成重复路径。
3. 配置模型映射
ZCF 会继续询问主模型以及 Haiku、Sonnet、Opus 映射。请使用 CoffeeRouter 令牌管理页中显示的完整模型 ID：
- 主模型：填写日常默认使用的 Claude / Anthropic 兼容模型 ID。
- Haiku、Sonnet、Opus 模型：按需填写对应模型 ID；不需要单独映射时可留空。
- 如果令牌只有一个可用 Claude 模型，可先只填写主模型。
不要凭空缩写或改写模型名。模型 ID 必须与 CoffeeRouter 中显示的名称完全一致。
4. 保存并验证
按需将该配置设为默认配置。ZCF 会把所选配置应用到 ~/.claude/settings.json；随后运行：
claude
在 Claude Code 中发送一条简单测试消息。如果出现 401，请检查令牌；如果出现模型不可用提示，请检查令牌权限和模型 ID。
接入 Codex
1. 切换到 Codex
在 ZCF 主菜单选择 切换工具 → Codex，再进入 配置 API → 自定义 API 配置 → 自定义配置。
2. 填写自定义 Provider
按提示填写：
| 配置项 | 填写内容 |
|---|---|
| 提供商名称 | CoffeeRouter |
| 基础 URL | https://www.coffeerouter.ai/v1 |
| API Key | CoffeeRouter 令牌，例如 sk-your-api-key |
| 模型名称 | 当前令牌允许使用的模型 ID |
| 协议（自动写入） | Responses |
当前 ZCF 会自动把自定义 Codex Provider 写为 Responses 协议，无需手动填写协议。基础 URL 只保留一个 /v1。
完成后不再添加其他 Provider，并将 CoffeeRouter 设为默认 Provider。ZCF 会更新 ~/.codex/config.toml 和 ~/.codex/auth.json。随后运行：
codex
发送一条简单的代码任务，确认模型可以正常回复和调用基础工具。
可选：使用命令行自动配置
交互式配置更适合个人电脑，因为不会把真实令牌直接写入命令历史。以下命令只用于展示当前 ZCF 参数格式，请先替换模型 ID，并在实际执行时妥善保护令牌。
Claude Code
npx zcf i -s -T claude-code -p custom -t api_key -k "sk-your-api-key" -u "https://www.coffeerouter.ai" --api-model "your-claude-model-id"
Codex
npx zcf i -s -T codex -p custom -t api_key -k "sk-your-api-key" -u "https://www.coffeerouter.ai/v1" --api-model "your-model-id"
命令参数可能随 ZCF 版本变化。自动化部署前，请使用 npx zcf --help 核对当前版本。
配置文件与安全
ZCF 当前使用以下本地路径：
| 内容 | 默认路径 |
|---|---|
| ZCF 全局配置 | ~/.ufomiao/zcf/config.toml |
| Claude Code 配置 | ~/.claude/settings.json |
| Codex Provider | ~/.codex/config.toml |
| Codex 凭证 | ~/.codex/auth.json |
切换或撤销配置
需要切换已保存的配置时，可以运行：
npx zcf config-switch -T claude-code
或：
npx zcf config-switch -T codex
要撤销接入，请先在 CoffeeRouter 令牌管理页禁用或删除对应令牌，再通过 ZCF 删除该配置，或手动清理目标工具配置文件中的 CoffeeRouter Provider。仅删除本地配置不会使已泄露的令牌失效。
常见问题
为什么 Claude Code 地址不带 /v1，而 Codex 要带
两款工具拼接请求路径的规则不同。Claude Code 使用 Anthropic Messages 基础地址，填写站点根地址；Codex 使用 OpenAI Responses Base URL，填写带一个 /v1 的地址。
ZCF 会把请求转发到自己的服务器吗
不会。ZCF 负责生成和切换本地配置，实际模型请求由 Claude Code 或 Codex 直接发往你配置的 CoffeeRouter 地址。
提示 401 或 API Key 无效
确认令牌复制完整、尚未过期、未被禁用且有可用额度；同时检查令牌的 IP 白名单等限制是否允许当前设备访问。
提示 404 或路径不存在
检查地址是否与目标工具对应：Claude Code 使用 https://www.coffeerouter.ai，Codex 使用 https://www.coffeerouter.ai/v1。不要重复添加 /v1。
模型无法使用
返回 CoffeeRouter 令牌管理页，确认令牌允许使用该模型，并将模型 ID 原样填入 ZCF。Claude Code 应优先选择 Claude / Anthropic 兼容的聊天模型；Codex 应选择支持 OpenAI Responses 的模型。