# 创建 API 密钥

密钥是工具访问 Clomio 网关的凭证。所有工具都需要先有一个密钥。密钥同时绑定**分组、额度、有效期、IP 规则和限速规则**；建议按工具、项目、环境拆分多个 Key，方便隔离风险和对账。这里说的是公开模型网关 API Key;登录控制台、工单、支付、AI Studio 等网页功能使用账号会话,不是把 API Key 填进网页登录。

---

## 步骤

1. 打开控制台 **[https://api.clomio.ai](https://api.clomio.ai)** 并登录
2. 进入「API 密钥」页面，点击「创建密钥」；列表支持按名称、状态、分组筛选和排序
3. 填写信息：
   - **名称**：随便起，用来区分用途，比如 `claude-prod` / `codex-dev` / `grok-video`
   - **分组**：**最关键的一项**，按要用的工具和模型选（见下表）
   - **高级字段**：需要精细控制时再填；新手可保持默认
4. 点击「创建」，在列表里点「复制」拿到完整密钥

---

## 分组怎么选

| 你要用的工具 | 选择的分组 |
|--------------|-----------|
| Claude Code | Claude 对应分组 |
| Codex / GPT | Codex / GPT 对应分组 |
| Grok 对话/代码 | Grok 对应分组 |
| Grok Videos / 视频生成 | **Grok Videos 可用的 Grok 分组** |

> 分组决定了**可用模型**和**计费倍率**。具体有哪些分组、各自倍率和支持模型，以 `/groups/available`、`/groups/rates` 以及可用渠道页 `/channels/available` 的实时结果为准。倍率的含义见 [常见问题](#/faq)。

如果调用视频接口，请确认 Key 所在分组支持 Grok 视频模型；Videos 端点不要拿非 Grok 分组的 Key 调用。网关同时提供带 `/v1` 和省略 `/v1` 的兼容路径，客户端只需保持 Base URL 与 endpoint 拼接一致，并确认返回的是 API 响应。

---

## 高级字段说明

| 字段 | 用途 | 常见用法 |
|------|------|----------|
| `group_id` | 绑定 Key 所属分组 | 后续可编辑 Key 换分组，用来切换可用模型/倍率 |
| `custom_key` | 自定义完整 Key 值 | 迁移旧系统或希望固定密钥字符串时使用；保持唯一且足够长 |
| `ip_whitelist` | IP 白名单 | 只允许公司出口、服务器出口、固定代理 CIDR 调用 |
| `ip_blacklist` | IP 黑名单 | 临时封禁异常来源 IP/CIDR |
| `quota` | Key 总额度上限（USD 口径） | 给项目/员工/自动化任务设预算；`0` 表示不限制 |
| `expires_in_days` | 有效期天数 | 给临时测试、外包、CI 临时凭证设置自动过期 |
| `rate_limit_5h` | 5 小时窗口限额 | 防止短时间异常消耗 |
| `rate_limit_1d` | 1 天窗口限额 | 控制每日预算 |
| `rate_limit_7d` | 7 天窗口限额 | 控制每周预算 |

说明：

- 额度和限速字段按**金额消耗**计算，不是按请求数计算；填 `0` 或留空表示不限制。
- `quota` 是这个 Key 的累计预算；5h/1d/7d 是滚动/周期窗口预算，到窗口重置后可继续使用。
- IP 规则支持单个 IP 或 CIDR（如 `203.0.113.10`、`10.0.0.0/8`）。白名单非空时，只允许白名单内来源；黑名单命中时会拒绝。
- 如果同时配置白名单和黑名单，建议把白名单作为主要准入规则，黑名单只用于临时排除异常来源。
- 名称最长约 100 字符；自定义 Key 最长约 128 字符。自定义 Key 请使用随机长字符串,不要使用短口令或可猜测文本。
- 自定义 Key 至少 16 个字符,只允许字母、数字、下划线和连字符；重复、过短、含非法字符或短时间失败尝试过多会返回 `API_KEY_EXISTS`、`API_KEY_TOO_SHORT`、`API_KEY_INVALID_CHARS`、`API_KEY_RATE_LIMITED`。
- Key 有 `active`、`inactive`、`quota_exhausted`、`expired` 等状态；用户侧启停实际是 `PUT /keys/{id}` 更新 `status` 为 `active`/`inactive`。删除走 `DELETE /keys/{id}`，后端 schema 带软删除字段，旧 Key 不应再用于客户端配置。

---

## 用户 API Key 接口速查

控制台页面使用 JWT 调 `/api/v1/keys` 系列接口；这和模型网关的 `/v1/...` API Key 鉴权不是同一种入口。

| 接口 | 主要参数 / 字段 | 说明 |
|------|-----------------|------|
| `GET /api/v1/keys` | query:`page`、`page_size`、`search`、`status`、`group_id`、`sort_by`、`sort_order` | 返回 `{items,total,page,page_size,pages}`；列表项会带 `last_used_at`、`quota_used`、`usage_5h`、`usage_1d`、`usage_7d`、`window_5h_start`、`reset_5h_at`、`reset_1d_at`、`reset_7d_at` 等排查字段 |
| `POST /api/v1/keys` | `name` 必填；可选 `group_id`、`custom_key`、`ip_whitelist`、`ip_blacklist`、`quota`、`expires_in_days`、`rate_limit_5h`、`rate_limit_1d`、`rate_limit_7d` | 创建新 Key；自定义 Key 失败次数过多会触发限流 |
| `PUT /api/v1/keys/{id}` | `name`、`group_id`、`status`、`ip_whitelist`、`ip_blacklist`、`quota`、`expires_at`、`reset_quota`、`rate_limit_5h`、`rate_limit_1d`、`rate_limit_7d`、`reset_rate_limit_usage` | 编辑 Key；`expires_at:""` 表示清除过期时间；`reset_quota` 重置累计额度用量,`reset_rate_limit_usage` 重置 5h/1d/7d 窗口用量 |
| `DELETE /api/v1/keys/{id}` | path id | 删除后返回 `API key deleted successfully`，旧 Key 不应继续用于客户端 |
| `GET /api/v1/groups/available` / `GET /api/v1/groups/rates` | 无 | 创建 Key 时查看当前用户可用分组、平台、倍率、订阅类型和 image/video/messages dispatch 等能力 |

`group_id` 不是任意分组 ID 都能绑定。标准分组要看用户 allowed groups / exclusive 规则;订阅型分组要有该用户的有效订阅。无权绑定时会返回 `GROUP_NOT_ALLOWED`,请先到控制台确认「可用分组 / 订阅」,不要反复改同一把 Key。

常见创建/更新错误还包括 `INVALID_IP_PATTERN`、`GROUP_NOT_ALLOWED`、`API_KEY_EXPIRED`、`API_KEY_QUOTA_EXHAUSTED`、`API_KEY_RATE_5H_EXCEEDED`、`API_KEY_RATE_1D_EXCEEDED`、`API_KEY_RATE_7D_EXCEEDED`。

---

## 复制 / 使用 Key：自动生成客户端配置

API Key 列表里的「使用 / 复制配置」弹窗会根据 Key 绑定分组的平台生成模板。它只是**按当前分组能力生成配置片段**，不代表所有端点都可用；最终仍以端点 × 分组矩阵和最小 curl 为准。

| Key 分组平台 | 弹窗常见 tab / 配置 | 生成逻辑 |
|---|---|---|
| Claude/Anthropic | Claude Code、opencode | Base URL 用 `https://api.clomio.ai`；Claude Code 走 `/v1/messages` |
| OpenAI/Codex | Codex、Codex WS、opencode；若分组开放 Messages 兼容能力，也可能出现 Claude Code | Base URL 用 `https://api.clomio.ai/v1`；Codex 模板使用 Responses；WS tab 会开启 `responses_websockets_v2` |
| Gemini | Gemini CLI、opencode | 原生 Gemini 走根地址 `https://api.clomio.ai` 或 `/v1beta` 由客户端拼接 |
| Antigravity | Claude Code、Gemini CLI、opencode | Antigravity 专用路径从根地址拼 `/antigravity/...`，不要把 OpenAI `/v1` 套到 Antigravity 前缀 |
| Grok | Grok CLI env + `~/.grok/config.toml` | 使用 `GROK_MODELS_BASE_URL=https://api.clomio.ai/v1` 和 `XAI_API_KEY`；不会给 Grok 生成 Claude/opencode 通用 tab |

OpenAI/Codex 的 Codex 示例为了方便复制，可能把 `experimental_bearer_token` 直接写入 `~/.codex/config.toml`,并配 `requires_openai_auth = true`；长期使用建议改成 `env_key = "CLOMIO_API_KEY"` 的环境变量方式，避免把 Key 写进可同步的配置仓库。两种方式不要混用:如果改用环境变量,删除 `experimental_bearer_token` 和 `requires_openai_auth` 后再重启 Codex。Codex WS tab 会额外写 `supports_websockets = true` 和 `[features].responses_websockets_v2 = true`。Claude Code 优先使用 Claude 分组；只有当前 OpenAI 分组明确开放 Messages 兼容能力时，才把它用于 `/v1/messages`。

Grok tab 不等于 Videos 已开通。视频仍需 Key 绑定**已启用视频能力的 Grok 分组**，并用 `/v1/videos/generations` 最小 curl 验证。Images 可用 OpenAI 或 Grok；Web Search 和 Videos 只用 Grok。

---

## 模型网关鉴权方式

模型网关 API 支持三种 header 传 Key：

```http
Authorization: Bearer sk-...
x-api-key: sk-...
x-goog-api-key: sk-...
```

普通 Claude/OpenAI/Grok 网关路径不要把 Key 放在 query string 里：`?key=` 或 `?api_key=` 会直接返回 400 `api_key_in_query_deprecated`。Gemini 原生 `/v1beta` 路径兼容 Google 风格 `key=` query,但 `api_key=` 仍会返回废弃错误；能用 header 时仍优先用 `Authorization` 或 `x-goog-api-key`。如果触发 IP ACL,错误会带 `ACCESS_DENIED` 和网关识别到的当前出口 IP,用它来核对你的代理、Cloudflare 或服务器 NAT 出口。

---

## 额度、限速和过期怎么排查

当 Key 触发限制时,常见现象是接口返回 429/403 或用量页显示额度耗尽。处理顺序:

1. 在「API 密钥」列表查看 Key 是否已过期、禁用、删除、`quota_used` 是否接近 `quota`,以及 `usage_5h`/`usage_1d`/`usage_7d` 是否接近对应窗口限额。
2. 打开 Key 详情或用量统计,看 5h/1d/7d 窗口是否已经用满;Key 日用量来自 `/user/api-keys/{id}/usage/daily`,会按天展示 requests、token、cache、`cost`、`actual_cost`。
3. 如果只是临时测试,编辑 Key 时可使用 `reset_quota` 或 `reset_rate_limit_usage` 重置对应累计/窗口用量;生产 Key 建议先确认是否有异常流量。
4. 如果是 IP 拦截,确认请求的真实出口 IP;通过 Cloudflare、公司代理或服务器 NAT 后,看到的来源 IP 可能不是本机 IP。

`reset_quota: true` 会把这把 Key 的 `quota_used` 清零;如果 Key 因 `quota_exhausted` 停用,且额度上限仍大于已用量,会恢复为 active。`reset_rate_limit_usage: true` 会清零 `usage_5h`、`usage_1d`、`usage_7d` 并清空对应窗口开始时间,下一次请求会重新开启窗口。两者只影响当前 Key,不会退费用量日志、不会重置账户余额/订阅额度,也不会改变模型分组。

> Key 本身看起来没超限时，还要检查账户余额、订阅额度、平台额度、IP 规则和站点风控提示；可参考 [故障排查](#/troubleshooting) 中的 quota/rate limit 条目。

---

## 换分组与多 Key 策略

每个密钥最多绑定一个分组（`group_id` 可为空,但生产不建议空分组）。你可以在 Key 编辑页调整分组，用同一个 Key 切换到新的模型/倍率；但生产环境更推荐：

- **一个工具一个 Key**：Claude Code、Codex、Grok 分开建。
- **一个项目一个 Key**：方便在用量明细里按 Key 查成本。
- **一个环境一个 Key**：开发、测试、生产分开设置额度和 IP。
- **视频单独 Key**：Grok Videos 消耗和调用模式不同，建议单独建 Grok 视频分组 Key。

所有密钥共享同一个账户余额，但各自的分组、额度、有效期、IP 规则和限速规则互不影响。若分组是订阅型,还要看 `/subscriptions/active` 和 `/subscriptions/progress` 中该分组是否有有效套餐与剩余额度。

---

## 安全提示

> API 密钥等同于账户凭证。请妥善保管：**不要**提交到代码仓库、不要发到群里或公开分享。一旦泄露，及时在控制台删除并重建。

建议给长期运行的服务配置 IP 白名单，并给高风险 Key 设置 `quota`、`rate_limit_1d` 或 `expires_in_days`。

**推荐环境变量命名:**

```bash
# OpenAI-compatible / Codex / Grok / Node.js SDK
export CLOMIO_API_KEY="sk-..."

# Claude Code / Anthropic-compatible 客户端
export ANTHROPIC_AUTH_TOKEN="sk-..."
```

不要把同一个 Key 混用到所有工具。分组不同会直接影响可用端点:Claude Key 主要给 `/v1/messages`;OpenAI/Codex Key 给 `/v1/responses`、`/v1/chat/completions`、`/v1/images/*`、`/v1/embeddings`;Grok Key 给 `/v1/responses`、`/v1/images/*`、`/v1/web_search` 和 Grok-only `/v1/videos/*`。

---

## 为什么同一把 Key 可用能力会不同

Key 绑定的分组会决定平台、可见模型、图片/视频/搜索能力、倍率和限速。控制台“复制配置”只按当前 Key 的分组生成模板，不代表所有端点都可用。遇到同一把 Key 在某个工具能用、另一个工具不能用时，先核对：

- 工具协议是否匹配：Claude Code 用 `/v1/messages`，Codex/OpenAI 用 `/v1/responses` 或 OpenAI-compatible 端点，Grok Videos 只用 Grok 分组。
- 控制台里该 Key 当前是否能看到目标分组、模型和能力。
- 最小 curl 是否能打通目标端点；失败时保存 HTTP 状态、响应体和 `x-request-id`。

---

## 下一步

拿到密钥后，去对应工具页完成配置：

- [Claude Code 接入](#/claude-code)
- [Codex 接入](#/codex)
- [Grok 接入](#/grok)