（4）创建 API 令牌

API 令牌是 CLI、脚本和第三方工具调用模型的唯一凭证。你后续无论使用 Claude Code、Codex、Gemini 还是 CC-Switch，本质上都要先拿到一个正确分组的令牌。

这一页解决 4 个问题：

• 去哪里创建令牌
• 第一次该怎么填，才不容易出错
• 令牌和分组到底是什么关系
• 创建后如何立刻验证它能不能用

令牌创建完成后通常只会完整展示一次，务必在离开页面前保存到密码管理器或安全笔记中。

创建前先确认这 3 件事

1. 你已经可以正常登录控制台。
2. 账户内有可用余额或测试额度。
3. 你知道自己要给哪个工具用令牌。

如果第三条还不确定，先按下面的最稳妥做法处理：

使用场景	建议分组	用途
先测试 Claude Code 是否能通	CC	快速完成首次 CLI 验证
准备接 Codex CLI 或脚本	Codex	走 OpenAI 兼容接口
准备接 Gemini 工具链	Gemini	用于 Gemini 侧工具接入
一台机器上长期正式使用	对应工具的正式分组	便于后续限额、轮换和审计

创建入口

1. 登录控制台首页。
2. 左侧点击“令牌管理”。
3. 点击“添加令牌”进入创建页。

令牌管理入口与添加令牌按钮示意

图示：令牌管理入口与“添加令牌”按钮

首次创建建议按这个顺序做

1. 先创建一个“测试令牌”。
2. 用测试令牌完成本机验证。
3. 验证通过后，再额外创建“正式令牌”。
4. 测试令牌保留较低额度，正式令牌设置更严格权限和更明确的名称。

这样做的好处是：

• 首次排错成本低，不会直接动生产令牌
• 测试和正式环境可以分离
• 后续令牌泄露或轮换时影响面更小

字段填写建议

字段	建议值	说明
令牌名称	工具-环境-设备，如 claude-test-laptop	方便后续定位是哪台设备在用
令牌分组	与工具严格匹配，如 CC / Codex / Gemini	决定能调用哪些模型、走哪种接口和费率
过期时间	首次建议设置 30 天或更短	避免长期闲置令牌忘记回收
额度限制	测试令牌设置较低，正式令牌按实际用量设	防止误调用导致超额扣费
访问限制	先按默认，后续再逐步收紧	初次接入先保证能通，再做最小权限化

创建令牌表单字段示意

图示：创建令牌表单（名称、分组、到期与额度）

一份可直接照抄的首次令牌方案

项目	推荐值
令牌名称	claude-test-laptop
令牌分组	CC
过期时间	7 天或 30 天
额度限制	设置一个测试可接受的上限
用途	仅用于本机首次接入验证

如果你本次不是给 Claude Code 用，而是给 Codex 或 Gemini 用，只需要把名称和分组替换成对应工具即可，其他思路不变。

令牌与分组关系

• 令牌本身只是“身份凭证”，真正决定你能调用什么的是它绑定的分组。
• 同一个账户可以创建多个令牌，但每个令牌都应该明确属于某个用途和某个分组。
• 分组不匹配时，最常见现象不是“令牌格式错误”，而是下面这些业务错误：

现象	常见原因
能连上接口，但看不到目标模型	分组里没有该模型
返回 401 / 403	令牌错误、过期、被删除或权限限制
返回 model_not_found	模型名不在当前分组支持范围
Claude 能用，Codex 不能用	令牌建成了 CC 分组，却去给 Codex 用

不确定怎么选时，先看 令牌分组介绍。

推荐的令牌命名与分层方法

如果你准备长期使用，建议最少分成两层：

层级	建议命名	用途
测试令牌	codex-test-desktop	调试配置、验证新工具
正式令牌	codex-prod-workstation	日常稳定使用

如果你有团队协作或多台机器，再加一层区分：

• 按设备区分：claude-prod-macbook、claude-prod-server
• 按环境区分：codex-dev、codex-prod
• 按人员区分：不要共用一把万能令牌，方便单独吊销和审计

创建完成后一定要做的保存动作

创建成功后，不要直接关闭页面，至少做完下面两步：

1. 复制完整令牌，保存到密码管理器或安全笔记。
2. 顺手记录这把令牌对应的分组、用途和到期时间。

推荐记录格式：

名称：claude-test-laptop
分组：CC
用途：本机首次接入验证
到期：2026-05-14

如果你已经关掉页面且没有保存成功，通常不能再次看到完整令牌，只能删除旧令牌后重新创建。

安全与运维建议

• 不要把令牌写入公开仓库、群聊、工单截图。
• 不要把令牌直接贴给他人远程代配，优先自己粘贴到本机配置中。
• 怀疑泄露时，立即删除旧令牌并重建，不要只改名称继续使用。
• 测试与生产使用不同令牌，便于权限和成本隔离。
• 周期性轮换长期使用的正式令牌。
• 离职设备、废弃脚本、停用服务器对应的令牌要及时清理。

快速验证令牌可用性

创建完成后，先不要急着配置完整 CLI，先验证令牌是否可访问网关。

方式一：检查模型列表

适合判断“令牌是否有效、接口是否可达、分组是否至少能看到可用模型”。

curl -s https://www.yuzhixiaolongxia.com/v1/models \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json"

判断标准：

• 返回模型列表：说明令牌和网关连通正常
• 返回 401 / 403：先检查令牌是否复制完整、是否过期、是否被禁用
• 返回空列表或缺少目标模型：重点检查分组是否选对

方式二：最小化聊天验证

适合判断“除了能列模型外，是否真的能完成一次请求”。

curl https://www.yuzhixiaolongxia.com/v1/chat/completions \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "替换为你分组内可用的模型名",
    "messages": [
      { "role": "user", "content": "回复 OK" }
    ]
  }'

如果能收到正常文本响应，说明这把令牌已经具备“可实际发请求”的条件。

首次验证失败时按这个顺序排查

1. 令牌有没有复制完整，前后是否多了空格或换行。
2. 分组是不是和当前工具一致。
3. 账户是否还有余额或测试额度。
4. 模型名是不是属于当前分组。
5. 是否误把旧令牌、旧环境变量、旧配置文件混在一起。

常见问题可以继续看：常见问题

下一步：（5）配置 CLI 工具