ZCF 快速接入

ZCF 是 Claude Code 配置初始化工具，适合快速安装 Claude Code 并写入自定义 API 配置。

统一接入信息

• 平台名称：FreeDom API
• 控制台 / API Base URL：https://api.yonghu.shop
• 鉴权方式：API Key
• API Key 获取：登录控制台 → 令牌 / API Key 页面创建

一、适用场景

• 想把 ZCF 快速接入 的模型请求接到 FreeDom API
• 已经有平台 API Key
• 需要统一使用平台里的 Claude、GPT、Gemini 或图像模型

二、安装 / 准备

确保已安装 Node.js：

node -v
npm -v

然后运行：

npx zcf

三、配置接入

按交互提示选择：

1. 显示语言：简体中文
2. 初始化方式：完整初始化
3. API 配置模式：自定义 API 配置
4. API 供应商：自定义配置
5. 认证类型：API Key
6. API 基础 URL：https://api.yonghu.shop
7. API 密钥：填写你的 FreeDom API Key
8. 模型相关配置：不确定可先回车跳过
9. 返回主菜单后输入 q 退出

四、启动验证

运行：

claude

首次进入项目目录时选择信任当前目录，然后发起最小测试。

五、推荐模型填写方式

优先使用控制台里真实展示的模型名。常见可尝试：

• Claude：claude-sonnet-4-5-20250929、claude-opus-4-8、claude-opus-4-8-thinking
• Gemini：gemini-2.5-pro、gemini-2.5-flash
• OpenAI 兼容工具：按平台模型广场/控制台展示为准

六、常见问题

401 Unauthorized

API Key 错误、没保存成功，或请求头没有带上密钥。

403 Forbidden

通常是余额不足、Key 没有权限、模型未开放，或服务返回拒绝。

404 Model Not Found

模型名写错，或者当前 Key 没有这个模型权限。

429 Too Many Requests

请求过快或服务繁忙。降低并发、稍后重试，或切换模型或稍后重试。

七、实用建议

ZCF 适合新机器初始化。如果已有 Claude Code 环境，修改环境变量通常更快。

配置前检查

配置客户端前，先确认平台在线：

curl https://api.yonghu.shop/api/status

看到 success: true 或 HTTP 200，说明平台主入口正常。

如果客户端配置失败，优先按这个顺序排查：

1. API Key 是否复制完整，没有多余空格。
2. Base URL 是否该带 /v1。
3. 模型名是否与平台模型广场完全一致。
4. 当前 API Key 是否有该模型权限。
5. 余额是否充足。

成功后建议到 FreeDom API 控制台查看日志，确认请求确实打到了平台。

ZCF 成功判据

ZCF 接入时重点确认三个字段：

Base URL: https://api.yonghu.shop
API Key: 你的 FreeDom API Key
Model: 平台模型名

如果 ZCF 按 OpenAI 兼容路径拼接，必要时改成：

Base URL: https://api.yonghu.shop/v1

成功判据：ZCF 能完成一次最小对话，且 FreeDom API 控制台日志出现对应消耗。