API 密钥创建与安全

创建密钥

1. 登录控制台并打开 API 密钥。
2. 点击创建密钥按钮。
3. 填写名称并选择可用分组。
4. 按用途设置额度和有效期。
5. 创建后安全保存完整密钥。

建议每个设备、客户端和环境单独创建一把密钥，例如：

• Windows-Codex
• Mac-Claude-Code
• Server-Production
• Local-Test

这样可以单独停用、轮换和审计，不会因一把密钥泄露而影响所有客户端。

字段怎么填

字段	建议	原因
名称	写清设备、客户端和环境	便于在使用记录中定位来源
分组	选择与客户端协议、目标模型匹配的可用分组	分组决定可见模型、协议和计费
额度	测试或个人设备设置合理上限	限制误调用和密钥泄露损失
有效期	临时任务设置到期时间	到期后自动失效，减少遗忘风险

界面未显示某个字段时，以当前控制台实际能力为准，不要通过修改请求参数绕过限制。

“使用密钥”里的信息

密钥列表中的“使用密钥”入口会提供当前 Key 对应的接入信息。配置客户端时重点 核对：

配置项	FreedomZ AI
OpenAI 兼容 Base URL	https://freedomz.cn/v1
自动拼接 /v1 的客户端	https://freedomz.cn
Anthropic Messages 网关地址	https://freedomz.cn
API Key	当前创建的完整密钥
模型	以该 Key 调用 /v1/models 的结果为准

控制台支持的客户端模板或一键导入应优先使用，因为它会按当前 Key 和分组生成 匹配配置。

CCSwitch 一键导入

1. 安装并启动 CCSwitch。
2. 在浏览器打开 API 密钥。
3. 找到目标 Key，点击导入到 CCSwitch 的按钮。
4. 允许浏览器打开 ccswitch:// 链接。
5. 回到 CCSwitch，确认新配置已经“启用”或显示“使用中”。

导入成功不代表已经启用。完整步骤见 CCSwitch 接入。

安全存储

• 服务端应用使用环境变量、系统凭据库或专用密钥管理服务。
• 本地 .env 文件必须加入 .gitignore，权限仅授予运行账户。
• 不要把密钥写入前端 JavaScript、移动端安装包或公开配置接口。
• 为不同应用、环境和成员创建独立密钥，不要多人共用。
• 日志只记录密钥指纹或脱敏形式，例如 sk-abcd…wxyz。

不要在网页前端、浏览器扩展公开配置或移动端安装包中放置可长期使用的服务端密钥。

轮换密钥

生产密钥应定期轮换；人员离开、设备丢失、仓库误提交或出现异常流量时必须立即 轮换。轮换流程：

1. 创建新密钥并更新受控运行环境。
2. 验证新密钥调用正常。
3. 删除旧密钥。
4. 检查旧密钥最近使用记录和账单。

泄露处置

1. 立即在控制台禁用或删除旧密钥。
2. 停止使用该密钥的自动任务。
3. 创建新密钥并更新受控环境。
4. 检查 使用记录 中的异常时间、模型和费用。
5. 必要时联系支持并提供脱敏后的密钥指纹。

不要只删除聊天消息或 Git 提交，因为历史记录可能已经被复制。

客户端应用

浏览器、桌面软件和移动端无法可靠保密长期 API 密钥。需要向最终用户提供能力 时，应由自己的后端保存密钥，并向客户端签发短时、最小权限的业务凭证。

常见问题

现象	处理
创建后看不到完整密钥	删除并重新创建，立即安全保存新值
客户端报 401	检查是否复制完整、有无空格或换行；停止连续重试
模型列表为空或 model not found	检查 Key 分组并重新调用 /v1/models
多个设备共用一把 Key	为每台设备新建独立 Key，再撤销共享 Key
怀疑被盗用	先撤销，再检查使用记录和费用，不要等待确认