# Clomio 完整文档包 生成日期: 2026-06-30 这个文件把 Clomio 公开帮助文档按导航顺序合并为一个 Markdown 包，方便 Claude Code、Codex、Cursor、浏览器 AI 助手或企业知识库直接读取。 ## 关键入口 - 文档首页: https://help.clomio.ai/docs/ - 搜索索引: https://help.clomio.ai/docs/search-index.json - OpenAPI: https://help.clomio.ai/openapi.json - 精简 llms: https://help.clomio.ai/llms.txt ## 开始使用 # 简介 **Clomio 让你在国内更轻松地用上主流 AI 编程工具。** 如果你想用 Claude Code、Codex、Grok 这类终端 AI 编程助手,通常会遇到几道坎:需要科学上网、官方订阅不便宜、按量计费容易超支、账号还有风控风险。Clomio 把这些麻烦收敛成两件简单的事: - **API 网关**(`api.clomio.ai`):用一个密钥,按更低的成本调用 Claude、Codex(GPT)、Grok 等模型,无需自备海外账号。 - **CLI 镜像**(`help.clomio.ai`):在国内直连下载 Claude Code、Codex、Grok 的安装包,一条命令装好,无需翻墙。 两者配合,你只需要:**装好工具 → 拿一个密钥 → 把工具指向 Clomio**,就能开始用。 --- ## 你现在想做什么 | 目标 | 直接看这里 | 你会得到什么 | |---|---|---| | 先把 Claude Code / Codex / Grok 装起来 | [CLI 镜像下载](#/cli-mirror) | 一条命令安装、更新、确认版本、查看脚本内容 | | 5 分钟跑通一个工具 | [5 分钟快速开始](#/quickstart) | 按 Claude / Codex / Grok 分别配置 Key 和 Base URL | | 用 SDK 或 curl 调 API | [API 概述](#/api-usage) | 端点、鉴权、分组能力、错误格式和最小请求 | | 不确定 `/v1` 要不要带 | [Base URL 与 /v1 规则](#/base-url-matrix) | 按协议判断 Base URL 应该写到哪一级 | | 已经报错了 | [故障排查](#/troubleshooting) | 先拿 request_id，再按状态码、分组、模型、endpoint 定位 | | 想查最近改了什么 | [更新记录](#/changelog) | 文档、镜像、公开网关说明的用户可见变更 | | 想确认入口和自查方式 | [服务状态](#/status) | 公开入口、最小健康检查和工单信息清单 | --- ## 这些工具是什么 | 工具 | 来自 | 形态 | 擅长 | |------|------|------|------| | **Claude Code** | Anthropic | 终端 CLI | 理解需求、规划思路、写改代码 | | **Codex** | OpenAI | 终端 CLI | 执行任务、排查问题、动手解决 | | **Grok** | xAI | 终端 CLI | 快速代码任务与对话 | 它们和网页版聊天框(ChatGPT、Claude.ai)最大的不同在于:**能直接读写你电脑上的文件、在终端里替你干活**——是"工作助手",不只是"问答助手"。 --- ## 什么是"终端" 终端就是电脑里一个**用文字命令操作的窗口**,常被叫作"黑框框"。上面这些工具都运行在终端里。 - **Windows**:按 `Win` 键 → 输入 `Terminal` 或 `PowerShell` → 打开 - **macOS**:按 `Command + 空格` → 输入 `终端` → 回车 第一次接触终端不用紧张,照着文档一步步做、能跑起来最重要。 --- ## 它怎么工作 ```text 你的电脑(终端 + 工具) ⇄ Clomio 网关(api.clomio.ai) ⇄ 云端模型 ``` 你在本地终端输入指令,工具通过 Clomio 网关把请求发给云端模型,再把结果返回到你的终端。因此使用时需要联网,但**不需要翻墙**。 --- ## 5 分钟选型:按工具选 Key / 分组 / Base URL / 端点 先按你手里的工具或要调用的能力选**密钥分组**,再复制对应 **Base URL**。模型名不要猜,以控制台当前开放模型列表为准。 | 你要用的工具/能力 | 应选 Key/分组 | Base URL 填什么 | 客户端最终会请求的端点 | 能力边界 | |------|------|------|------|------| | Claude Code | Claude / Anthropic 分组 Key | `https://api.clomio.ai` | `/v1/messages` | Anthropic-compatible;不要在 Base URL 后加 `/v1` | | Anthropic SDK / Claude Messages | Claude / Anthropic 分组 Key | `https://api.clomio.ai` | `/v1/messages`, `/v1/messages/count_tokens` | 同 Claude Code 规则 | | Codex CLI | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `POST /v1/responses`;Codex WS 入口 `GET /v1/responses` | `wire_api = "responses"`;模型用控制台开放名 | | OpenAI SDK: Responses / Chat | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `/v1/responses`, `/v1/chat/completions` | OpenAI-compatible;不要填成完整端点 | | OpenAI SDK: Images | OpenAI 或 Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/images/*` | Images 支持 OpenAI/Grok,按模型列表选择 | | OpenAI SDK: Embeddings | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `/v1/embeddings` | Embeddings 仅 OpenAI 侧能力 | | Grok 对话 / CLI | Grok 分组 Key | `https://api.clomio.ai/v1` | `POST /v1/responses` | Grok 不走 Claude `/v1/messages`;也不走 Chat Completions | | Grok Web Search | Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/web_search` | Web Search 仅 Grok | | Grok Videos | Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/videos/*` | Videos 仅 Grok;OpenAI/Claude Key 调不通 | | Hermes / OpenClaw: Responses | OpenAI/Codex 或 Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/responses` | 对应 `codex_responses` / `openai-responses`;Grok 对话用这一类 | | Hermes / OpenClaw: Chat Completions | OpenAI/Codex 分组 Key | `https://api.clomio.ai/v1` | `/v1/chat/completions` | 对应 `chat_completions` / `openai-completions`;不要用于 Grok | | Hermes / OpenClaw: Anthropic-compatible | Claude / Anthropic 分组 Key | `https://api.clomio.ai` | `/v1/messages` | Base URL 不带 `/v1` | | 只安装 Claude/Codex/Grok CLI | 暂不需要 Key | CLI 镜像 `https://help.clomio.ai` | 只下载/更新工具 | 安装镜像不是 API Base URL | 常见错法可以直接按下面改: - 看到 `.../v1/v1/...`:Base URL 和客户端重复拼了 `/v1`,删掉一层。 - Claude Code 配成 `https://api.clomio.ai/v1`:改成 `https://api.clomio.ai`。 - Codex/OpenAI SDK 配成 `https://api.clomio.ai`:改成 `https://api.clomio.ai/v1`。 - 拿 Claude Key 调 OpenAI Responses/Chat 端点:换 OpenAI/Codex 分组 Key,或改回 Claude `/v1/messages`。 - 拿 Grok Key 调 Chat Completions:改走 Grok `POST /v1/responses`。 - 拿 OpenAI/Claude Key 调 videos:换 Grok 分组 Key;Videos 仅 Grok。 - 模型名不在控制台列表里:不要猜别名,先查 `GET /v1/models` 或看控制台开放模型。 --- ## 适合谁 - 想体验先进 AI 编程工具,但不想折腾海外账号和网络的人 - Windows 或 macOS 用户,想在本地用上终端 AI 助手 - 做代码辅助、文档整理、信息处理,希望成本可控的人 - 对 Claude Code / Codex / Grok 感兴趣、但基础还薄的新手 > **下一步:** 跟着 [5 分钟快速开始](#/quickstart) 跑通第一次使用,或先了解 [常见问题](#/faq)。 --- # 5 分钟快速开始 跑通第一次使用,只需三步:**装工具 → 拿密钥 → 按工具接上 Clomio**。 > 先记一个规则:OpenAI-compatible 客户端通常填 `https://api.clomio.ai/v1`,Claude/Anthropic-compatible 客户端通常填 `https://api.clomio.ai`。CLI 安装镜像用 `https://help.clomio.ai`。不确定时先看 [Base URL 与 /v1 规则](#/base-url-matrix)。 ## 先选对场景 | 你要做什么 | 用哪个 Key/分组 | Base URL | 端点/能力 | |------|------|------|------| | Claude Code 写代码 | Claude 分组 Key | `https://api.clomio.ai` | 工具自动请求 `/v1/messages` | | Codex CLI / Codex Responses | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `POST /v1/responses`;WS 入口 `GET /v1/responses` | | OpenAI SDK 普通对话 | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `/v1/responses` 或 `/v1/chat/completions` | | OpenAI SDK 图片 | OpenAI 或 Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/images/*`;Images 支持 OpenAI/Grok | | OpenAI SDK Embeddings | OpenAI 或 Codex/GPT 分组 Key | `https://api.clomio.ai/v1` | `/v1/embeddings`;Embeddings 走 OpenAI 侧 | | Grok CLI / Grok 对话 | Grok 分组 Key | `https://api.clomio.ai/v1` | `POST /v1/responses`;不走 Chat Completions | | Grok 搜索 / 图片 / 视频 | Grok 分组 Key | `https://api.clomio.ai/v1` | `/v1/web_search`、`/v1/images/*`、`/v1/videos/*`;Videos 仅 Grok | | Gemini 原生 SDK/CLI | Gemini 分组 Key | `https://api.clomio.ai` | `/v1beta/models...`;不要在 Base URL 加 `/v1` | | Antigravity 客户端 | Antigravity 分组 Key | `https://api.clomio.ai` | `/antigravity/v1...` 或 `/antigravity/v1beta...` | | Hermes / OpenClaw Responses | OpenAI/Codex 或 Grok 分组 Key | `https://api.clomio.ai/v1` | `codex_responses` / `openai-responses`;Grok 用这一类 | | Hermes / OpenClaw Chat Completions | OpenAI/Codex 分组 Key | `https://api.clomio.ai/v1` | `chat_completions` / `openai-completions`;不要用于 Grok | | Hermes / OpenClaw Anthropic-compatible | Claude 分组 Key | `https://api.clomio.ai` | `/v1/messages` | | Node.js 环境准备 | 暂不需要 Key | 安装 Node.js 后再按 SDK/工具选择 | Node.js 不改变 Base URL 规则 | 记住两条红线:Claude/Anthropic-compatible Base URL 不带 `/v1`;OpenAI-compatible / Codex / Grok Base URL 带 `/v1`。视频请求只用 Grok 分组 Key。 --- ## 第 1 步:安装工具(国内直连) 打开终端,粘贴对应命令回车。安装包从 `help.clomio.ai` 镜像直连下载,**无需翻墙、无需 Node.js**。 ```bash # Claude Code curl -fsSL https://help.clomio.ai/claude/install.sh | bash # Codex curl -fsSL https://help.clomio.ai/codex/install.sh | bash # Grok curl -fsSL https://help.clomio.ai/grok/install.sh | bash ``` Windows PowerShell: ```powershell # Claude Code irm https://help.clomio.ai/claude/install.ps1 | iex # Codex irm https://help.clomio.ai/codex/install.ps1 | iex # Grok irm https://help.clomio.ai/grok/install.ps1 | iex ``` 装完后重开终端,执行 `claude --version` / `codex --version` / `grok --version` 能看到版本号即成功。 --- ## 第 2 步:创建 API 密钥 1. 打开控制台 **[https://api.clomio.ai](https://api.clomio.ai)** 并登录 2. 进入「API 密钥」页面,点击「创建密钥」 3. 按工具选择分组: - **Claude Code** → Claude 分组 - **Codex** → Codex / GPT 分组 - **Grok** → Grok 分组 - **Hermes / OpenClaw** → 看你选择 OpenAI-compatible 还是 Anthropic-compatible - **图片 / embeddings / OpenAI SDK** → OpenAI 或 Codex/GPT 分组 - **Grok videos only** → Grok 分组 4. 创建后点「复制」拿到完整密钥(形如 `sk-...`) 想同时用多个工具?建议分别创建对应分组的密钥,所有密钥共享同一个账户余额。详见 [创建 API 密钥](#/api-key)。 --- ## 第 3 步:按工具接上 Clomio ### Claude Code ```bash export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的密钥" claude ``` 进 Claude 后运行 `/status`,确认 `Anthropic base URL` 和 `Auth token` 指向 Clomio。永久配置见 [Claude Code](#/claude-code)。 ### Codex 推荐把密钥放环境变量,把 provider 写进 `~/.codex/config.toml`: ```bash export CLOMIO_API_KEY="你的密钥" mkdir -p ~/.codex cat > ~/.codex/config.toml <<'TOML' model_provider = "clomio" model = "gpt-5.4" [model_providers.clomio] name = "Clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" TOML codex ``` 把 `model` 改成你分组实际开放的模型。完整配置见 [Codex](#/codex)。 ### Grok ```bash export GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" export XAI_API_KEY="你的Grok分组密钥" mkdir -p ~/.grok cat > ~/.grok/config.toml <<'TOML' [endpoints] models_base_url = "https://api.clomio.ai/v1" [model.grok-build] model_name = "控制台里的 Grok 对话模型名" env_key = "XAI_API_KEY" TOML grok --model grok-build ``` 旧包装器可能仍读取 `GROK_BASE_URL` / `GROK_API_KEY` / `GROK_MODEL`，但当前控制台生成配置优先用 `GROK_MODELS_BASE_URL`、`XAI_API_KEY` 和 `~/.grok/config.toml` 的 `[endpoints].models_base_url`。 Grok 分组主要走 `POST /v1/responses`,还支持图像、视频、联网搜索。`GET /v1/responses` 是 Codex/OpenAI WS 入口,不是 Grok 入口。**视频只在 Grok 分组开放**,见 [Videos](#/api-videos)。详见 [Grok](#/grok)。 ### OpenAI SDK / Node.js Node.js 项目里安装官方 SDK 后,把 `baseURL` 指到带 `/v1` 的网关: ```bash npm install openai ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.CLOMIO_API_KEY, baseURL: "https://api.clomio.ai/v1", }); const resp = await client.responses.create({ model: "控制台里的 OpenAI/Codex 模型名", input: "用一句话解释 Clomio", }); console.log(resp.output_text); ``` Python 也是同一规则:`OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1")`。 ### Hermes ```bash hermes model ``` 选择 Custom endpoint: - OpenAI-compatible → `https://api.clomio.ai/v1` - Anthropic-compatible → `https://api.clomio.ai` 填入密钥和模型名后,先发一条最短消息验证。详见 [Hermes 接入](#/hermes)。 ### OpenClaw ```bash openclaw onboard ``` 选择 Custom provider: - `openai-completions` / `openai-responses` → `https://api.clomio.ai/v1` - `anthropic-messages` → `https://api.clomio.ai` 默认模型通常写成 `服务商ID/模型名`,例如 `clomio/gpt-5.4`。详见 [OpenClaw 接入](#/openclaw)。 --- ## 控制台里能直接做什么(入口可见时) 除了接入 CLI/API,控制台本身也可能提供一些内置入口。不同租户、套餐或灰度批次展示可能不同,**以你登录后实际可见的菜单为准**: - **AI 聊天 / 图片**:如果看到 AI 聊天或图片生成入口,可先在控制台用同一个分组和模型发最小请求,确认模型名、余额和权限没问题,再搬到 CLI 或 SDK。 - **画廊 / Prompt 模板**:如果入口可见,可把常用提示词、图片结果或示例保存下来,新手可直接从模板改写,不用从空白提示词开始。 - **用量 / 错误详情**:如果使用记录里有错误详情,优先复制 `request_id`、状态码、模型名和响应摘要;排查比只贴截图更快。 - **兑换码 / 订阅**:如果账户页展示兑换码或订阅入口,按页面提示兑换或开通;余额、套餐剩余和 Key 限额仍以控制台展示为准。 - **工单附件**:如果工单支持上传附件,可附上终端截图、curl 输出、配置截图,同时写明 Base URL、Key 分组和发生时间。 - **2FA/TOTP**:如果安全设置里有两步验证入口,可用认证器 App 绑定;保存好恢复码后再开启。 - **邀请返利**:如果账户里有邀请/返利入口,按页面规则生成邀请链接;返利比例、结算方式以该入口当前说明为准。 这些入口是“辅助你确认和管理”的控制台能力,不改变 API 规则:Claude/Anthropic-compatible 仍用 `https://api.clomio.ai`,OpenAI-compatible / Codex / Grok 仍用 `https://api.clomio.ai/v1`。 --- ## 网络不稳?换条线路 Clomio 有三条网关线路(直连 / CF 优化 / 三网优化)。国内直连 `api.clomio.ai` 卡顿时,可把地址换成: - `https://sub.qazwc.com` - `https://crs.qazwc.com` OpenAI-compatible 场景同样在后面加 `/v1`。详见 [网关线路](#/gateway-lines)。 --- ## 遇到报错了? 先看 [故障排查](#/troubleshooting)。九成问题集中在:代理环境、命令找不到、Base URL 少/多 `/v1`、模型名与分组不匹配、密钥分组选错。想确认 Key 状态、余额、限速窗口,可请求 `GET /v1/usage`;想确认模型列表,只用 `GET /v1/models` 列表,不要自行拼模型详情查询路径。 --- # 常见问题 ## 分组卡片上的"倍率"是什么意思? 倍率是该分组的**计费系数**:你的实际扣费 = 模型官方价格 × 分组倍率。 倍率越低越省钱。不同分组对应不同的上游来源,因此价格、可用模型、稳定性各有差异。 > 举例:某次调用官方计价 1 美元,分组倍率 0.5x,则实际扣费相当于 0.5 美元等值的余额。 各分组的当前倍率、支持的模型和价格,以控制台 **[api.clomio.ai](https://api.clomio.ai)** 实时显示为准。 --- ## 实际扣费怎么算? ```text 实际扣费 = 模型官方价格 × 分组倍率 ``` 费用按 **token** 计量:你发出去的内容算"输入 token",模型返回的内容算"输出 token",两者分别计价。可以在控制台的「使用记录」里查看每一次调用的明细。 简单记一句:**说得越长、回得越长、轮次越多,token 越多,费用越高。** 命中缓存的部分会更便宜。 --- ## 分组怎么选? 挑选时主要看三点: - **倍率**:越低越省 - **支持的模型**:部分分组只支持特定模型 - **稳定性 / 速度**:不同分组的并发与响应表现不同 一般建议:**按你要用的工具选对应分组**(Claude Code 选 Claude 分组、Codex 选 GPT 分组、Grok 选 Grok 分组);日常用推荐分组,追求稳定可选更高规格的分组。用着卡顿时可以换个分组/节点再试。 --- ## 可以创建多个密钥吗? 可以。在「API 密钥」页面想建几个建几个,用来区分不同项目或工具。**每个密钥独立管理,但共享同一个账户余额。** 想同时用 Claude Code 和 Codex,就分别建两个对应分组的密钥。 --- ## 一个密钥能同时用于所有工具吗? 不建议。密钥是和**分组**绑定的,而不同工具走不同分组。最稳妥的做法是:**一个工具一个密钥,各选对应分组**。 --- ## Base URL 到底要不要加 `/v1`? 看工具怎么要求: - **OpenAI 兼容 Base URL**:通常填到 `/v1`,例如 `https://api.clomio.ai/v1`、`https://sub.qazwc.com/v1`。 - **只要求域名/网关地址**、另外有 Path/Endpoint 配置:通常不要加 `/v1`,填 `https://api.clomio.ai`。 - 如果报错路径里出现 `.../v1/v1/...`,就是 `/v1` 写重复了。 - 如果报 `404` 且请求路径没有 `/v1`,通常是少写了 `/v1`。 不确定时,把工具名称和当前 Base URL 截图发工单。 --- ## 新手最常见的 5 类错误怎么改? | 现象/报错 | 多半原因 | 直接改法 | |------|------|------| | 请求地址里出现 `/v1/v1` | Base URL 已经写了 `/v1`,工具又自动拼了一次 | OpenAI-compatible 保留一个 `/v1`;不要把 Base URL 填成完整端点 | | Claude Code 404、认证测试怪异或真实调用失败 | Claude Base URL 写成了 `https://api.clomio.ai/v1` | 改成 `https://api.clomio.ai`,让 Claude 自己拼 `/v1/messages` | | OpenAI SDK / Codex 404 | Base URL 少了 `/v1` | 改成 `https://api.clomio.ai/v1`;线路域名同理加 `/v1` | | `model_not_found` / `unsupported model` | 模型名不是控制台开放模型,或 Key 分组不支持该模型 | 先看控制台模型列表或 `GET /v1/models`,按列表里的名字填 | | Claude Key 调 `/v1/responses` / `/v1/chat/completions` 失败 | Claude/Anthropic 分组主协议是 Messages | Claude Code/Anthropic SDK 用 `/v1/messages`;要调 OpenAI Responses/Chat 就换 OpenAI/Codex 分组 Key | | Grok Key 调 `/v1/chat/completions` 失败 | Grok 对话走 Responses,不走 Chat Completions | Grok 用 `POST /v1/responses`;不要把 Grok 配成 Chat Completions 客户端 | | 非 Grok Key 调 videos 失败 | Videos 仅 Grok | 换已开通视频能力的 Grok 分组 Key 和 Grok 视频模型 | 如果已经换过线路,仍然同样失败,说明问题通常不是网络,而是 Key 分组、Base URL、端点或模型名不匹配。 --- ## 一个 key 能跨 Claude Code、Codex、Grok 等工具共用吗? 技术上同一个 key 可以被多个客户端拿去请求,但**不推荐**。原因是 key 绑定分组,而分组通常绑定协议和上游能力: - Claude Code:优先用 Claude 分组,走 `/v1/messages`; - Codex / OpenAI SDK:用 GPT/OpenAI 分组,走 `/v1/responses` 或 `/v1/chat/completions`; - Grok:用 Grok 分组;视频生成也用 Grok 视频分组。 最稳妥做法仍是:**一个工具一个 key,各选对应分组**。这样用量、报错和工单也更好定位。 --- ## 怎么判断 `No available accounts` 是模型不支持,还是临时没账号? 看报错关键词: - `The current group does not support the requested model ... Available models: ...`:分组明确不支持,按列表换模型或换分组。 - `model_not_found` / `Model "xxx" is not supported by any configured account in this group`:组里有账号,但没有任何已配置账号支持这个模型,多半是模型名或模型映射问题。 - 只有 `No available accounts` / `Service temporarily unavailable`:更像临时容量、429、账号冷却、并发槽位或上游波动,稍后重试或换分组。 - `No available accounts supporting model: xxx`:介于两者之间,可能是模型支持问题,也可能是支持账号被临时排除。先核对模型名和分组支持列表;持续出现带 request_id 工单。 --- ## 控制台里的 AI 聊天、图片、画廊和 Prompt 模板怎么用? 如果你登录后能看到这些入口,可以把它们当成“控制台内置试验场”: - **AI 聊天**:用来快速验证某个 Key 分组、模型名、余额和权限是否正常。 - **图片**:入口可见且分组已开放时,可先在控制台试图片模型;Images 可用 OpenAI 分组或 Grok 分组。视频能力单独只走 Grok 分组。 - **画廊**:如果入口可见,可查看或管理已生成内容,适合复用提示词和结果。 - **Prompt 模板**:如果入口可见,可从模板改写需求,再复制到 Claude Code、Codex、Grok 或 SDK。 这些是控制台功能入口，不是公开网关 API：终端或 SDK 不能把 `/user/ai/*`、`/user/skills/*` 当成 OpenAI/Claude/Grok 兼容端点调用。不是所有租户都会展示；是否可用以当前页面、站点开关和套餐/权限为准。 --- ## 使用记录里的错误详情和 request_id 有什么用? 如果控制台「用量 / 使用记录」里能点开错误详情,优先保存: - `request_id` 或 `x-request-id` - HTTP 状态码和错误摘要 - 模型名、端点、Base URL、Key 分组 - 发生时间和是否换过线路 带 `request_id` 工单排查会更快。没有 request_id 时,先到错误请求页按时间、模型、状态码、分类和 Key 过滤,复制错误 `id`、`message`、`error_body`、`upstream_status_code`;仍找不到时,至少提供时间、Key 名称/后几位、模型名、端点和完整响应体。 它不是完整请求归档。用量记录主要证明计费和模型/Key/分组事实；错误详情主要证明失败阶段和上游错误。若只看到 `Recovered upstream error` 且最终请求成功，通常是自动容灾记录，不代表最终失败。 --- ## 兑换码、订阅、2FA、邀请返利在哪里? 如果账户页或安全页展示对应入口,按页面说明操作即可: - **兑换码**:入口可见时输入兑换码,兑换后看余额或套餐是否变化。 - **订阅**:入口可见时按套餐说明开通/续费;生效范围、额度和到期时间以控制台为准。 - **2FA/TOTP**:安全设置入口可见时,用认证器 App 扫码绑定,确认恢复码已保存后再开启。 - **邀请返利**:邀请入口可见时,复制你的邀请链接;返利比例、有效期和结算规则以入口当前说明为准。 如果某个入口不可见,通常表示当前租户、账号权限、套餐或灰度批次暂未开放,不影响按 API 文档正常调用已开放模型。 --- ## 工单可以上传什么附件? 如果工单入口支持附件,建议上传和问题直接相关的材料:终端报错截图、curl `-i` 输出、工具配置截图、控制台用量/错误详情截图、订单或支付凭证。注意同时在文字里写清 Base URL、端点、模型名、Key 名称/分组、发生时间、request_id 或错误请求 `id`;附件只作为补充,不要只发图片不写关键信息。 --- ## 怎么充值? 登录控制台 → 点「充值 / 现在充值」→ 按页面提示完成支付,余额会自动到账,无需手动兑换。具体起充金额和支付方式以充值页为准。 --- ## 服务稳定吗?用着卡顿怎么办? 国内访问卡顿,最先该试的是**换一条网关线路**。Clomio 提供三条线路,共用同一密钥: - `https://api.clomio.ai` —— 默认直连(国外服务器最佳) - `https://sub.qazwc.com` —— Cloudflare 优化 - `https://crs.qazwc.com` —— 三网优化(国内通常最稳) 把工具配置里的地址换成更稳的一条即可,详见 [网关线路](#/gateway-lines)。 如果换线路仍不理想,再试**切换分组/节点**: 1. 在控制台「API 密钥」里给密钥切换到另一个可用分组/节点 2. 刷新页面确认生效 3. 回到工具里重新发一条消息验证 > 注意区分三件事:**换线路**改 Base URL(治网络卡顿)、**换分组**在控制台选(改模型与倍率)、**换模型**用 `/model`(改本次对话的模型)。 --- ## 登录鉴权会经过 Clomio 吗? Clomio 网关只负责**转发你的模型请求并计费**。工具本身的安装走 `help.clomio.ai` 镜像,模型调用走 `api.clomio.ai` 网关并用你的 Clomio 密钥鉴权——你**不需要**再登录任何海外账号。 --- ## 装好工具后第一次用就报错? 这是最常见的情况,绝大多数是**代理(翻墙)环境**或**命令找不到 / 权限**问题。请直接看 [故障排查](#/troubleshooting),里面按报错类型给了对应解法。 --- ## 为什么使用记录里有 `Recovered upstream error`? 这通常表示请求过程中某次上游调用返回了 5xx/429/限速等错误，但网关自动切换或重试后成功了。它和最终成功请求通过同一个 `request_id` / `client_request_id` 关联，方便排障时看到中间发生过什么。 如果最终状态是成功、你也收到了正常回复,一般**不用处理**。只有当同一工具频繁卡顿、费用异常或最终请求失败时,再带 `request_id` 联系支持。 --- ## Videos 为什么只能用 Grok? 当前网关把视频端点按分组平台和视频权限控制。非 Grok 分组请求 `/v1/videos`、`/v1/videos/generations` 会返回类似 `Videos API is not supported for this platform`;分组没开视频权限会返回 `Video generation is not enabled for this group`。新接入请使用 `/v1/videos...`,不要使用不带 `/v1` 的 `/videos...`。 所以视频生成请使用**已开通视频的 Grok 分组**。文本、图片、Claude Code 建议分别使用对应分组和独立 key。 --- ## 为什么 `GET /v1/responses/{id}` 或 `GET /v1/models/{id}` 会 404? 因为这两个 REST 查询路由当前不存在: - Responses 多轮续接不是靠 `GET /v1/responses/{id}` 查历史,而是在下一次 `POST /v1/responses` 中传 `previous_response_id`,或交给 Codex/SDK 维护会话。`GET /v1/responses` 只用于 Codex/Responses WebSocket v2 流入口。 - Models 只提供 `GET /v1/models` 列表。要确认某个模型是否可用,请看列表返回值,或对目标端点发一次最小请求。 如果你只是想排查模型不可用,优先看 `The current group does not support...`、`model_not_found`、`No available accounts supporting model...` 这些关键词,见 [故障排查](#/troubleshooting)。 --- ## `actual_cost` 和 `cost` / `total_cost` 有什么区别? 简单理解: - `total_cost` / `cost`:按模型官方基础价格算出的原始成本参考; - `actual_cost`:实际从余额或套餐里扣除/统计的费用,会应用分组倍率、用户专属倍率、服务档位、图片/视频等计费规则。 所以你看到 `actual_cost` 和 `total_cost` 不一样是正常的。判断实际扣费看 `actual_cost`;想理解模型原始计价参考看 `total_cost`。 --- ## 控制台 # 控制台总览 控制台 **[api.clomio.ai](https://api.clomio.ai)** 是你管理密钥、查用量、充值、提工单的地方。本页总览各功能,详细的另有分页。 --- ## 核心功能 | 功能 | 作用 | 详情 | |------|------|------| | **仪表盘** | 登录首页,概览钱包余额、近期用量、公告 | [用量明细 · Dashboard](#/console-usage) | | **API 密钥** | 创建/管理密钥,设分组、额度、速率、IP、有效期 | [创建 API 密钥](#/api-key) | | **用量明细** | 看每次调用的模型、token、扣费 | [用量明细](#/console-usage) | | **订阅与余额** | 两种计费模式、充值、订单、退款、开票 | [订阅与余额](#/console-billing) | | **邀请·工单·账号** | 邀请返利、提工单、第三方授权绑定 | [邀请、工单与账号](#/console-account) | ### 功能入口覆盖表 | 控制台/用户入口 | 文档位置 | 说明 | |------|------|------| | 登录、注册、找回密码、第三方登录/绑定 | [邀请、工单与账号](#/console-account) | 控制台账号认证,不是模型网关 API Key 鉴权 | | API Key 列表、创建、编辑、删除、分组倍率 | [创建 API 密钥](#/api-key) | 用户侧 `/keys`、`/groups/*`;决定工具能调用哪些公开网关端点 | | 用量明细、仪表盘趋势、模型统计、错误请求 | [用量明细](#/console-usage) | 控制台查询/排障入口;公开自助对账另见 `GET /v1/usage` | | 余额充值、订阅套餐、订单恢复、退款、发票 | [订阅与余额](#/console-billing) 与 [计费与额度](#/billing) | 支付/账单控制台功能,以当前支付渠道开关为准 | | 兑换码、订阅进度、平台额度 | [订阅与余额](#/console-billing) / [计费与额度](#/billing) | 入口可见时使用,额度最终看控制台实时值 | | 邀请返利、工单、通知邮箱、2FA/TOTP | [邀请、工单与账号](#/console-account) | 如果入口可见,按页面流程操作 | | 可用渠道、渠道状态/监控、公告 | 本页与 [用量明细](#/console-usage) | 辅助判断线路/模型/维护状态,不是公开模型调用端点 | | 网页端 AI Studio、图库、提示词 | [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio) | **控制台功能**,不是 OpenAI/Claude/Grok 公开网关 API | | 技能市场、安装、创作者版本和收益 | [技能市场与创作者中心](#/console-skills) | 控制台网页端技能系统,不要和本地 Codex/Claude Skill 混淆 | --- ## 其他常用入口 - **可用分组 / 分组倍率**:来自用户侧 `/groups/available` 与 `/groups/rates`,用于确认你能把 Key 绑定到哪些分组、平台、倍率和订阅类型。创建 Key 前先确认分组平台是 Claude/OpenAI/Grok/OpenAI-compatible 等。 - **可用渠道**:来自 `/channels/available`,按渠道聚合展示当前可访问分组、支持模型和定价模式。 - **服务状态 / 渠道监控**:来自 `/channel-monitors` 与 `/channel-monitors/{id}/status`,展示当前用户可见渠道的主模型状态、延迟、7/15/30 天可用率和附加模型状态。**用着卡顿时,先看状态、再换[网关线路](#/gateway-lines)或分组。** - **公告**:来自 `/announcements`,重要变更、维护通知会发在公告区；可标记已读,建议常看。 - **网页端 AI**:若入口可见,控制台内置网页版 AI 对话、绘图、图库、图片编辑和提示词库,详见 [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio)。 - **技能市场**:浏览、安装、创建、发布和运行网页端技能,详见 [技能市场与创作者中心](#/console-skills)。 - **媒体/附件**:控制台上传能力,用于工单附件、网页端 AI 图片等浏览器功能;它不是 OpenAI Files API,也不会让模型网关多出不存在的端点。 > 要在终端用 Claude Code / Codex,仍走 [命令行工具接入](#/claude-code)。 部分功能会受站点开关影响:例如工单、邀请返利、支付渠道、发票、退款、错误请求页、渠道监控、网页端 AI、技能市场等。如果你在文档里看到某入口,但控制台当前没有显示,以控制台实际开放状态为准。 --- ## 出问题时先带哪些信息 提交工单或找支持时,优先附上这些信息: - **Request ID / 错误详情 ID**:成功或计费记录看用量明细里的 `request_id`;用户侧错误请求页是脱敏视图,列表/详情使用错误记录 `id`、`status_code`、`category`、`message`、`key_name` 等字段。 - **Key 名称 / 分组名 / 模型名**:不要直接发送完整密钥。 - **客户端与 Base URL**:例如 Claude Code 使用 `https://api.clomio.ai`,Codex 使用 `https://api.clomio.ai/v1`。 - **时间范围和截图**:方便在用量明细、错误请求、订单、发票、渠道监控或工单记录中定位。 - **控制台问题可附字段**:支付问题带 `out_trade_no`/订单 ID/支付渠道;工单并发编辑问题带 `expected_revision_no` 或 `If-Match`;AI Studio/技能市场问题带页面路由、运行记录 ID、`error_message`。 错误类问题先看 [故障排查](#/troubleshooting);扣费类问题先看 [用量明细](#/console-usage) 和 [计费与额度](#/billing)。 --- ## 新手路径 1. [创建 API 密钥](#/api-key)(选对分组) 2. [充值](#/console-billing)(先小额测试) 3. [5 分钟快速开始](#/quickstart)(接上工具) 4. 用着卡顿?换 [网关线路](#/gateway-lines);报错?查 [故障排查](#/troubleshooting) --- # AI Studio：网页 AI、图片图库与 Prompt 模板 AI Studio 是控制台内置的网页端 AI 体验,用于在浏览器里聊天、生成/编辑图片、管理图库和 Prompt 模板。它不是公开模型网关 API:终端、SDK、Claude Code、Codex、Grok 仍使用你创建的 API Key 和 [API 参考](#/api-usage) 里的端点。 > AI Studio 受站点开关控制。关闭时用户侧功能不可用,常见错误为 `AI_STUDIO_DISABLED` / `ai studio feature is disabled`。 --- ## 页面入口 | 页面 | 路由 | 用途 | |---|---|---| | AI Studio 首页 | `/ai` | 重定向到 `/ai/chat` | | 网页 AI 对话 | `/ai/chat` | 浏览器内对话、会话管理、Prompt 模板复用 | | 图片生成/编辑 | `/ai/image` | 文生图、图像编辑、尺寸/风格配置 | | 图片图库 | `/ai/gallery` | 查看历史作品、复制 prompt、公开/私有管理 | | Prompt 模板库 | `/ai/prompts` | 创建、编辑、克隆、复用 Prompt | 入口不可见通常表示当前站点未开启、你的账号无权限,或站点临时关闭了 AI Studio。 --- ## 运行时能力 `/user/ai/runtime` 进入 AI Studio 后,前端会先请求 `/user/ai/runtime` 判断可用能力。重点字段: | 字段 | 说明 | |---|---| | `source_domain` | 当前控制台来源域 | | `lines[]` | 可选线路/分组列表 | | `lines[].group_id` / `label` / `platform` | 线路 ID、显示名、平台类型 | | `lines[].keys[]` / `key_ids[]` / `key_count` / `default_key_id` | 可用 Key 和默认 Key | | `lines[].default_mapped_model` | 默认映射模型 | | `default_line` | 默认线路 | | `models[]` | 可见模型列表 | | `media.enabled` | 媒体存储是否开启 | | `media.public_base_url` | 公开资源基址 | | `media.max_upload_size_bytes` | 最大上传大小 | | `media.default_visibility` | 默认公开/私有 | | `media.upload_endpoint` | 上传入口 | | `media.download_endpoint_template` / `thumbnail_download_template` | 私有下载/缩略图下载模板 | | `image_edit.enabled` | 图片编辑是否开启 | | `chat.supported_entries` / `forced_entry` | 聊天可用入口:Responses 或 Chat Completions | 如果你能打开页面但发送失败,先刷新 runtime:Key、线路、媒体能力或聊天入口可能已经变化。 `forced_entry` 不为空时,前端应按服务端指定入口发送,不要根据浏览器缓存或旧开关自行改成另一条路径。常见情况是强制走 Responses,以便使用工具、多模态或统一用量记录；手工重放请求时,请保留 `use_responses` 与 runtime 展示一致。 --- ## 网页 AI 对话 相关端点: | 方法 | 端点 | 用途 | |---|---|---| | `GET` | `/user/ai/sessions` | 会话列表 | | `POST` | `/user/ai/sessions` | 创建会话 | | `GET` | `/user/ai/sessions/:id` | 会话详情 | | `PUT` | `/user/ai/sessions/:id` | 更新标题/状态/system prompt | | `DELETE` | `/user/ai/sessions/:id` | 删除会话 | | `GET` | `/user/ai/sessions/:id/messages` | 消息列表 | | `POST` | `/user/ai/sessions/:id/messages` | 写入消息 | | `POST` | `/user/ai/chat` | 发起一次实际聊天 | `POST /user/ai/chat` 请求体示例: ```json { "session_id": 123, "prompt": "帮我总结这段代码", "line_id": 10, "key_id": 99, "prompt_template_id": 5, "history": [ { "role": "user", "content": "上一轮问题" }, { "role": "assistant", "content": "上一轮回答" } ], "use_responses": true } ``` 后端会按 `use_responses` 与 runtime 配置桥接到 OpenAI-compatible `/openai/v1/responses` 或 `/openai/v1/chat/completions`,并把 user/assistant 消息保存回会话。`prompt` 为空会返回 `Prompt is required` 或 `AI_MESSAGE_INPUT_REQUIRED`。 --- ## Prompt 模板 新版模板接口和兼容旧入口同时存在: | 方法 | 端点 | 用途 | |---|---|---| | `GET` | `/user/ai/prompt-templates` | 新版模板列表 | | `POST` | `/user/ai/prompt-templates` | 创建新版模板 | | `GET` | `/user/ai/prompt-templates/:id` | 模板详情 | | `PUT` | `/user/ai/prompt-templates/:id` | 更新模板 | | `DELETE` | `/user/ai/prompt-templates/:id` | 删除模板 | | `GET` | `/user/ai/prompts` | 兼容/个人 Prompt 列表 | | `POST` | `/user/ai/prompts` | 创建个人 Prompt | | `PUT` | `/user/ai/prompts/:id` | 编辑 Prompt | | `DELETE` | `/user/ai/prompts/:id` | 删除 Prompt | | `POST` | `/user/ai/prompts/:id/clone` | 克隆公开模板 | 列表常用 query:`page`、`page_size`、`scope=mine|library|all`、`visibility=public|private`、`status`、`moderation_state`、`search`、`group_id`/`line_id`。 创建字段: ```json { "title": "代码审查模板", "content": "请审查以下 diff,指出风险和可改进点...", "description": "用于 PR review", "tags": ["code", "review"], "visibility": "private", "status": "draft", "line_id": 10 } ``` 常见状态包括 `draft`、`published`、`archived`、`hidden`;可见性为 `public` 或 `private`。标题或内容缺失会返回 `AI_PROMPT_TEMPLATE_TITLE_REQUIRED`、`AI_PROMPT_TEMPLATE_INPUT_REQUIRED` 或 `Invalid request body`。 --- ## 图片生成、编辑与图库 | 方法 | 端点 | 用途 | |---|---|---| | `GET` | `/user/ai/generation-jobs` | 生成任务列表 | | `POST` | `/user/ai/generation-jobs` | 创建生成任务记录 | | `GET` | `/user/ai/generation-jobs/:id` | 生成任务详情 | | `GET` | `/user/ai/gallery` | 图库列表 | | `GET` | `/user/ai/artworks` | 图库别名/作品列表 | | `POST` | `/user/ai/artworks` | 文生图 | | `POST` | `/user/ai/artworks/edit` | 图片编辑 | | `PUT` | `/user/ai/artworks/:id` | 更新作品信息 | | `DELETE` | `/user/ai/artworks/:id` | 软删除作品 | | `GET` | `/user/ai/assets/:id` | 媒体资源详情 | 普通用户前端常用图库筛选是 `page`、`page_size`、`search`、`visibility`、`status`、`line_id`;前端会把 `line_id` 归一化为后端查询的 `group_id`,并把图库筛选里的 `succeeded` 归一化为 `ready`。后端图库高级筛选还支持 `moderation_state`、`generation_job_id`、`session_id`、`prompt_template_id`、`group_id`;普通 `/user/ai/generation-jobs` 列表只支持 `status`、`session_id`、`prompt_template_id`、`group_id`。`featured` 属于旧元数据或高级筛选,普通用户侧页面不要当成稳定筛选承诺。Prompt library 场景会把 `scope=library` 固定成 `visibility=public`。看不到某张图时,先确认它是 public 还是 private、asset status 是否 `pending/ready/hidden/deleted`、任务 status 是否 `queued/running/succeeded/failed/canceled`、当前 Key/线路是否属于你。 生成任务和资源 ID 要区分:`/user/ai/generation-jobs/:id` 查的是异步任务;`/user/ai/assets/:id` 查的是最终媒体资源。图库 `/user/ai/gallery`/`/user/ai/artworks` 展示的是 asset/artwork 视图,可能来自已完成任务,也可能来自旧桥接路径。排查“任务完成但图库没有”时,同时保留 job id、asset id、request_id、line_id/group_id 和 status。 文生图请求示例: ```json { "title": "产品宣传图", "prompt": "一个极简风格的 SaaS 控制台截图海报", "negative_prompt": "不要杂乱背景", "visibility": "private", "mode": "generate", "line_id": 10, "key_id": 99, "size": "1024x1024", "style": "product", "tags": ["product", "banner"], "prompt_template_id": 5 } ``` 图片编辑额外需要 `source_image`,可选 `mask_image`: ```json { "mode": "edit", "prompt": "把背景换成深色科技风", "source_image": "https://example.com/source.png", "mask_image": "https://example.com/mask.png" } ``` 内部会桥接到 OpenAI Images 形态的 `/openai/v1/images/generations` 或 `/openai/v1/images/edits`,并把生成结果保存为 asset/artwork。公开图可返回 public URL;私有图通常通过签名下载 URL 访问。公开 API 的 Images 用法见 [Images](#/api-images),Codex 生图见 [Codex 生图](#/codex-image)。 --- ## 常见报错 | 报错 / 现象 | 常见原因 | 处理 | |---|---|---| | `AI_STUDIO_DISABLED` | AI Studio 未开放 | 以控制台当前开放状态为准 | | `User not authenticated` | 登录失效 | 重新登录控制台 | | `Invalid request body` | JSON 不合法或字段缺失 | 检查必填字段 | | `Prompt is required` | `/user/ai/chat` 的 `prompt` 为空 | 输入内容后再发送 | | `Invalid session ID` / `Invalid template ID` / `Invalid artwork ID` / `Invalid asset ID` | URL ID 不是正整数或记录不可见 | 刷新列表,确认权限 | | `AI_KEY_NOT_FOUND` | 当前线路没有可用 Key | 创建/启用 Key 或切换线路 | | `AI_KEY_FORBIDDEN` | 选择了不属于当前用户的 Key | 切回自己的 Key | | `AI_KEY_GROUP_INVALID` | Key 未绑定有效分组 | 检查 Key 绑定分组 | | `AI_LINE_MISMATCH` | `key_id` 不属于所选 `line_id` | 同时切换线路和 Key,清掉旧 URL query | | `AI_GATEWAY_EMPTY_CHAT_RESPONSE` | 上游成功但没有可提取文本 | 换模型/线路,带 request_id 提工单 | | `AI_ARTWORK_SOURCE_IMAGE_REQUIRED` | 编辑模式缺少原图 | 上传或填写 `source_image` | | `AI_GATEWAY_IMAGE_DATA_MISSING` / `AI_GATEWAY_IMAGE_URL_MISSING` | 上游图片响应无法解析 | 换模型/线路,保留 request_id | | `MEDIA_STORAGE_DISABLED` | 媒体存储关闭 | 图库/私有下载能力受限 | | `MEDIA_FILE_TOO_LARGE` | 图片超过限制 | 压缩图片,参考 runtime 的 `max_upload_size_bytes` | | `MEDIA_VISIBILITY_INVALID` | visibility 非 `public/private` | 改成 `public` 或 `private` | --- ## 实用场景 1. **新手先在网页端验证模型**:打开 `/ai/chat`,选择线路和 Key,发送 `ping`,再到 [用量明细](#/console-usage) 核对模型和扣费。 2. **把常用 Prompt 做成模板**:在 `/ai/prompts` 创建私有模板,后续聊天或 CLI 里复制复用。 3. **先在控制台试图,再迁移到 API**:在 `/ai/image` 调好 prompt/size/style,再迁移到 [Images](#/api-images)。 4. **用图库沉淀素材**:在 `/ai/gallery` 找历史图,复用 prompt、尺寸、风格作为下一次生成参考。 5. **编辑已有图片**:切到编辑模式,上传 `source_image`,可选 `mask_image`,输入编辑描述,结果会进入图库。 --- # 技能市场与创作者中心 技能市场是控制台里的网页端技能系统,用于浏览、安装、创建、发布、运行和结算 AI 技能。它和本地 Claude/Codex 的 Skill / Plugin 不是同一件事:本地 Skill/Plugin 改变客户端工作流,控制台技能市场则运行在 Clomio 网页端和服务端。 > 技能入口受 AI Studio/控制台开关和登录状态影响。入口不可见时,以控制台当前开放状态为准。 --- ## 页面入口与生命周期 | 页面 | 路由 | 用途 | |---|---|---| | 技能市场 | `/skills/market` | 浏览公开/可见技能、搜索、筛选、查看详情 | | 已安装 | `/skills/installed` | 管理自己安装的技能 | | 我的技能 | `/skills/mine` | 创作者管理自己创建的技能 | | 新建技能 | `/skills/new` | 创建技能草稿 | | 编辑技能 | `/skills/:id/edit` | 编辑基础信息、内容、变量、价格 | | 版本管理 | `/skills/:id/versions` | 创建版本、提交审核、发布已审核版本 | | 运行记录 | `/skills/:id/runs` | owner 查看运行历史和失败原因 | | 收益 | `/skills/:id/revenue` | owner 查看收益汇总、趋势、订单 | | 技能详情 | `/skills/:id` | 查看说明、安装、测试/使用 | 典型生命周期: 1. **发现**:进入市场,按类型、分类、价格、安装状态筛选。 2. **安装**:详情页确认价格和说明后安装,到「已安装」使用。 3. **创建**:进入「我的技能」→ 新建,填写名称、类型、变量、内容、价格。 4. **编辑**:owner 在编辑页调整元信息和内容。 5. **发版本**:在版本管理里创建版本,保存 draft 或提交 review。 6. **发布**:版本审核通过后调用 publish,把该版本设为 current/published。 7. **运行**:用户 test/use,生成 run 记录。 8. **收益**:付费运行产生结算记录,owner 在 revenue 页查看。 --- ## 用户端点 所有 `/user/skills` 路由都要求已登录。 | 功能 | 方法与路径 | |---|---| | 列表/市场/我的 | `GET /user/skills` | | 创建技能 | `POST /user/skills` | | 技能详情 | `GET /user/skills/:id` | | 更新技能 | `PUT /user/skills/:id` | | 安装 | `POST /user/skills/:id/install` | | 卸载 | `POST /user/skills/:id/uninstall` | | 版本列表 | `GET /user/skills/:id/versions` | | 创建版本 | `POST /user/skills/:id/versions` | | 更新版本 | `PUT /user/skills/:id/versions/:versionId` | | 提交审核 | `POST /user/skills/:id/versions/:versionId/submit` | | 发布版本 | `POST /user/skills/versions/:versionId/publish` | | 运行列表 | `GET /user/skills/:id/runs` | | 通用运行 | `POST /user/skills/:id/runs` | | 测试 | `POST /user/skills/:id/test` | | 使用 | `POST /user/skills/:id/use` | | 收益 | `GET /user/skills/:id/revenue` | 安装/卸载返回一般包含 `skill_id`、`installed`、`install_count` 和提示消息；连续点击安装/卸载时以前一次返回为准。付费技能请先确认 `pricing.mode`、`amount`、`currency` 和安装后的运行扣费说明。 列表常用 query: - 通用:`page`、`page_size`、`scope`、`search`、`type`、`category`、`sort` - 市场:`scope=market`,可加 `price_mode`、`installed` - 我的:`scope=mine`,可加 `status`、`visibility` - 运行记录:`status`、`version_id`、`search` `scope=market` 在后端会进入公开/市场库视图；用户侧 `visibility` 只按 `public` / `private` 归一化。`installed` 支持 `installed|true|1|yes` 和 `not_installed|false|0|no`。用户侧技能 `status` 常见为 `draft`、`published`、`archived`、`hidden`；版本展示状态常见为 `draft`、`published`、`deprecated`、`archived`，未知/被拒绝版本通常按 draft 展示。`price_mode=free|paid` 是列表筛选和展示口径。 市场列表返回项通常会被前端归一化为 `id`、`slug`、`name`、`type`、`category`、`visibility`、`status`、`pricing`、`installed`、`install_count`、`current_version`、`owner` 等字段；不同后端版本可能把 `latest_version`、`published_version`、`owner_name`、`publisher_name` 作为兼容字段返回。版本 DTO 当前不保证直接给顶层 `review_status`，前端会从 metadata、状态和发布时间推导展示。 市场列表的筛选规则比较严格：`scope=market` 只列已公开且已发布的技能；`installed` 只显示你已安装的技能。排序里 `popular` 通常按 like/install 相关热度，`runs` 按运行数；当前 `sort=revenue` 也按运行数排序，不等于真实收益额排序。排查市场排序/筛选异常时,先复制筛选条件和列表响应里的字段。 --- ## 创建 / 更新技能 支持类型: | 类型 | 用途 | 当前限制 | |---|---|---| | `prompt_chat` | 提示词聊天技能 | 可由用户创建 | | `prompt_image` | 图片生成技能 | 可由用户创建 | | `script` | 脚本技能 | 当前普通用户创建会返回 `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` | 脚本技能还没对普通用户完整开放：创建会被阻断，运行时网关当前 fail-closed；即使旧版本曾经审核通过，若没有审核时固化的 artifact digest，也需要重新提交审核后才能执行。 基础请求体示例: ```json { "slug": "daily-report", "name": "日报生成器", "tagline": "把要点整理成日报", "description": "适合团队日报/周报", "type": "prompt_chat", "visibility": "public", "status": "draft", "category": "writing", "cover_image_url": null, "tags": ["office", "report"], "pricing": { "mode": "free", "amount": 0, "currency": "CNY", "settlement_ratio": null }, "source_locked": false, "variable_schema": [], "content": { "type": "prompt_chat", "system_prompt": "你是严谨的日报助手", "user_prompt_template": "请根据以下要点生成日报: {{items}}", "temperature": 0.7, "max_tokens": 1200 }, "readme": "使用说明", "install_note": "安装后在详情页使用" } ``` `variable_schema` 可定义用户运行时填写的变量,常见类型有 `string`、`text`、`number`、`boolean`、`select`、`json`、`image`、`file`。 图片技能内容示例: ```json { "type": "prompt_image", "prompt_template": "一张 {{style}} 风格的 {{subject}} 海报", "negative_prompt_template": "低清晰度,杂乱背景", "style": "product", "size": "1024x1024", "quality": "high", "image_count": 1 } ``` --- ## 版本、审核与发布 创建/更新版本字段: ```json { "version": "v1.0.0", "status": "draft", "changelog": "首次发布", "source_locked": false, "variable_schema": [], "content": { "type": "prompt_chat" } } ``` 状态关系有多层，不要只看一个字段: | 层级 | 状态 | 说明 | |---|---|---| | 技能状态/展示状态 | `draft` / `published` / `archived` / `hidden` | 控制技能整体可见性；用户侧 `visibility` 仍只归一化为 `public/private` | | 版本展示状态 | `draft` / `published` / `deprecated` / `archived` | 控制页面展示；disabled override 可能显示为 archived | | 审核核心状态 | `draft` → `pending` → `approved`;`pending` → `rejected` | 只有 approved 版本才能 publish/test/use | | service 内部版本状态 | `draft` / `submitted` / `approved` / `rejected` / `disabled` | `submitted` 会映射到审核 pending；不是直接给用户看的最终展示词 | 注意: - `submit` 只是进入审核 pending,不等于对市场用户发布。 - 用户端 `publish` 是把已 approved 的版本设为 current/published。 - 创建/更新版本时若 `status` 传 `published`,服务端会尝试自动提交审核;真正发布仍要通过审核后 publish。不要把请求体里的 `published` 理解成立刻上架。 - 非 owner 只能运行已发布版本;请求其他版本会被拒绝。 --- ## 运行、测试与收益 通用运行请求体: ```json { "version_id": 123, "mode": "use", "parameters": { "topic": "本周销售数据" }, "attachments": [], "idempotency_key": "client-generated-key" } ``` 通用 `POST /user/skills/:id/runs` 读取 body 中的 `version_id`、`mode`、`parameters`、`attachments`、`idempotency_key`。快捷 `POST /user/skills/:id/test` 和 `/use` 则使用固定 mode，`version_id` 主要走 query 参数，幂等键从 `Idempotency-Key` header 读取；当前网页前端通常不向 test/use 传附件 body。运行状态面向用户可理解为: | 状态 | 含义 | |---|---| | `queued` / `prepared` | 等待中 | | `running` / `dispatched` | 执行中 | | `succeeded` | 成功 | | `failed` | 失败,查看 `error_message` | | `cancelled` / `canceled` | 已取消 | 收益页 `GET /user/skills/:id/revenue` 只对 owner 可见,会展示 total revenue、sales、runs、pending/settled/refunded 等汇总和订单。创建/编辑页的 `pricing.mode=free|paid` 是前端展示口径；运行结算底层会转换为 `free` 或 `per_run`。`amount>0` 表示每次运行价格，`settlement_ratio` 是创作者分成比例；付费但金额为 0、负价格、分成比例不在 0..1 都可能触发 `AI_SKILL_BILLING_POLICY_INVALID`。 结算状态底层常见为 `skipped`、`pending`、`settled`、`failed`；页面或旧接口可能映射为 `pending`、`settled`、`rejected`、`refunded` 等展示词。用户收益汇总通常只把 transferred/settled 类记录计入 settled/total，pending 只进待结算；订单原始状态可能再被前端映射为 paid/cancelled。免费运行通常不会产生创作者收益，可能表现为 skipped/无结算记录；付费运行失败时请同时保留 run id、settlement/order id 和错误信息。 源码可见性和安装状态是两件事。owner 通常可看源码；非 owner 必须先有读取权限，并且 effective source visibility 为 public 才能看到 `content`、`metadata`、`examples` 等源码/配置。公开付费技能默认可能隐藏源码；安装付费技能不等于一定能看到源码。 --- ## 权限与常见错误 下面是用户侧常见错误码，不是全集；持续异常请带运行记录或订单信息提交工单。 | 报错 / 现象 | 常见原因 | 处理 | |---|---|---| | 入口不可见 | AI Studio/技能功能未开放 | 以控制台当前开放状态为准 | | 401 / `User not authenticated` | 未登录或登录过期 | 重新登录 | | `AI_SKILL_ACCESS_DENIED` | 私有技能、未发布技能或非 owner 访问 owner-only 页面 | 确认技能可见性和权限 | | `AI_SKILL_NOT_FOUND` | 技能不存在、已隐藏或无权访问 | 刷新列表,确认链接 | | `AI_SKILL_VERSION_NOT_FOUND` / `AI_SKILL_REVIEW_NOT_FOUND` / `AI_SKILL_RUN_NOT_FOUND` / `AI_SKILL_SETTLEMENT_NOT_FOUND` | 版本、审核单、运行记录或结算记录不存在或不可见 | 回到对应列表确认 ID 和权限 | | `AI_SKILL_NAME_REQUIRED` | 创建/更新时名称缺失 | 填写技能名称 | | `AI_SKILL_TYPE_INVALID` / `AI_SKILL_VISIBILITY_INVALID` / `AI_SKILL_BILLING_MODE_INVALID` / `AI_SKILL_PRICE_MODE_INVALID` / `AI_SKILL_SOURCE_VISIBILITY_INVALID` | 类型、可见性、计费模式、价格模式或源码可见性非法 | 使用页面提供的下拉值，不要手改接口参数 | | `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` | 普通用户创建脚本技能 | 改用 prompt 类型或等待开放 | | `AI_SKILL_SCRIPT_EXECUTION_UNAVAILABLE` | 脚本执行器未接入 | 脚本技能运行不可用,等待站点开放 runtime | | `AI_SKILL_SCRIPT_NOT_APPROVED` | 脚本版本没有审核时固化的 artifact digest | 重新提交审核并等待通过 | | `AI_SKILL_SCRIPT_ARTIFACT_MISMATCH` | 运行时脚本包与审核通过的 digest 不一致 | 不要绕过版本发布;重新上传/审核 | | `AI_SKILL_SCRIPT_ARCHIVE_PATH_INVALID` | 脚本归档路径不在允许根目录或格式不合法 | 使用平台上传/生成的归档 | | `AI_SKILL_VERSION_NOT_APPROVED` | 版本未审核通过就 test/use/publish | 先提交审核并等待 approved | | `AI_SKILL_VERSION_TRANSITION_INVALID` | 版本状态流转不合法 | 按 draft → pending → approved → publish 流程操作 | | `AI_SKILL_VERSION_NOT_EDITABLE` | 已发布/归档版本不能直接编辑 | 新建修复版本 | | `AI_SKILL_RUN_MODE_INVALID` | 运行模式非法 | 使用 `test` 或 `use` | | `AI_SKILL_RUN_INPUT_REQUIRED` | 运行输入为空 | 填写输入后再 test/use | | `AI_SKILL_EXECUTION_SPEC_INVALID` / `AI_SKILL_BILLING_POLICY_INVALID` | 技能执行/计费配置非法 | 检查版本 content 与 pricing | | `AI_SKILL_SERVICE_UNAVAILABLE` / `AI_SKILL_INPUT_REQUIRED` / `AI_SKILL_VERSION_INPUT_REQUIRED` | 技能模块或请求输入缺失 | 刷新页面后补齐技能/版本/输入；持续出现提交工单 | | `AI_SKILL_VERSION_STATUS_INVALID` / `AI_SKILL_REVIEW_STATUS_INVALID` / `AI_SKILL_RUN_STATUS_INVALID` / `AI_SKILL_SETTLEMENT_STATUS_INVALID` / `AI_SKILL_REVIEWER_INVALID` | 版本、审核、运行、结算状态或审核人不合法 | 按页面流程提交审核；持续异常提交工单 | | `AI_SKILL_SETTLEMENT_INPUT_INVALID` / `AI_SKILL_PRICE_INVALID` / `AI_SKILL_VERSION_NUMBER_INVALID` / `AI_SKILL_REVIEW_ALREADY_PENDING` / `AI_SKILL_REVIEW_TRANSITION_INVALID` / `AI_SKILL_VERSION_IN_USE` / `AI_SKILL_VERSION_ALREADY_EXISTS` / `AI_SKILL_SETTLEMENT_ALREADY_EXISTS` / `AI_SKILL_BALANCE_UNAVAILABLE` / `AI_SKILL_EXECUTION_FAILED` | 结算输入、价格、版本号、审核流转、版本占用/重复或运行执行失败 | 保留 run id、版本 id、订单/结算 id 后提交工单 | | `AI_SKILL_SETTLEMENT_UNAVAILABLE` | 收益结算服务不可用 | 稍后重试或提交工单 | | `AI_SKILL_CREATOR_EARNINGS_UNAVAILABLE` / `AI_SKILL_CREATOR_EARNINGS_MISMATCH` | 创作者收益结算异常 | 保留 run/order id 提交工单 | 创建、更新、提交、发布、运行都带幂等包装;页面卡顿时不要连续重复点击。付费技能的源码可见性由 `source_visibility`、价格、发布状态和 owner 身份共同决定,安装后不保证一定能看到源码。 媒体字段可能是 `cover_image_url`、`avatar_url`、`media_id` 或迁移后的媒体 asset。旧版本返回 URL、新版本返回媒体对象时,前端会做兼容归一化;如果封面丢失,先检查媒体服务是否开启、对应 asset 是否被删除,再看技能 metadata 里的旧 URL 是否还能访问。 --- ## 实用场景 ### 安装一个市场技能 1. 进入 `/skills/market`。 2. 搜索“日报”或按类型/价格筛选。 3. 打开详情,确认价格、说明、变量和示例。 4. 点击安装。 5. 到 `/skills/installed` 找到它并使用。 ### 创建提示词聊天技能 1. 进入 `/skills/mine` → 新建。 2. 类型选 `prompt_chat`。 3. 填写系统提示词、用户模板、变量 schema。 4. 保存草稿。 5. 创建 `v1.0.0` 版本并提交审核。 6. 审核通过后 publish。 ### 发布修复版本 1. 在版本页新建 `v1.1.0`。 2. 写清 changelog。 3. 提交审核。 4. approved 后 publish。 5. 未 publish 前,市场用户仍使用旧 current/published version。 ### 查看运行失败与收益 - owner 进入 `/skills/:id/runs`,按 `failed` 筛选,查看 `error_message`、输入/输出摘要、成本。 - owner 进入 `/skills/:id/revenue`,核对 buyer、version、amount、status,再和订单/用量截图一起提交工单。 --- ## 不要和本地 Skill / Plugin 混淆 本页是 Clomio 控制台技能市场。Claude/Codex 本地 Skill、Plugin、MCP 安装见 [必装 Skill 与插件](#/skills-plugins)。本地 skill 不能让网关多出不存在的 API;例如视频端点仍然只支持 Grok 分组。 --- # 用量明细 想知道钱花在哪、每次调用扣了多少，就看用量明细（使用记录）。这里能看到请求模型、上游模型、缓存、错误、扣费和 CSV 导出。 --- ## 在哪看 控制台 [api.clomio.ai](https://api.clomio.ai) →「**用量明细**」/「**使用记录**」。仪表盘首页也有用量概览和**模型用量统计**。这些数据来自 `/usage/dashboard/stats`、`/usage/dashboard/trend`、`/usage/dashboard/models` 和批量 Key 统计接口。 --- ## 每条记录有什么 成功计费请求通常会留用量记录；部分鉴权、路由或早期失败可能只有错误记录。每条用量记录通常包含： | 字段 | 含义 | |------|------| | 时间 / Request ID | 调用发生的时刻和排障用 `request_id` | | 请求模型 | 你在请求里传入的模型名（`requested_model`） | | 实际/上游模型 | 模型映射后真正发给上游的模型（`upstream_model`），详情中可能展示映射链 | | 密钥 / 分组 | 哪个 Key、哪个分组发起的 | | 输入 token | 你发出去的内容（含历史、文件） | | 输出 token | 模型返回的内容 | | 缓存写入 / 命中缓存 | 写入缓存与复用缓存的 token，命中缓存通常更省钱 | | `cost` / `total_cost` | 标准费用口径：按模型基础价格算出的费用 | | `actual_cost` | 用户实际扣费口径：标准费用乘分组/用户倍率后的结果 | | 耗时 | `duration_ms`、首 token 时间 `first_token_ms`，流式/慢请求排查很有用 | | 端点 | `inbound_endpoint` 与 `upstream_endpoint`，用于确认客户端 Base URL/端点是否写错 | | 错误信息 | 失败请求的状态码、错误类型或失败原因（若有） | > 对用户对账，优先看 `actual_cost`；`cost` / `total_cost` 更适合理解基础模型成本或平台内部口径。 --- ## 扣费口径：cost / total_cost vs actual_cost - **`cost` / `total_cost`**：标准费用。通常等于输入、输出、缓存写入、缓存读取等分项费用相加，不含用户分组倍率。 - **`actual_cost`**：实际扣费。会应用 Key 所在分组倍率、用户专属倍率等用户侧规则，是余额/订阅额度实际减少的金额。 如果你看到 `total_cost` 和 `actual_cost` 不同，通常是因为分组倍率、用户专属倍率或订阅/余额计费规则不同。 --- ## Dashboard、趋势和模型统计 用户首页的仪表盘不是只看余额,还会汇总: - **总览卡片**:`total_api_keys`、`active_api_keys`、累计/今日请求数、输入/输出/cache token、`total_actual_cost`、`today_actual_cost`、平均响应耗时、近 5 分钟 `rpm`/`tpm`。 - **平台拆分**:`by_platform` 会按平台展示总请求、总 token、累计/今日实际扣费。 - **趋势图**:`/usage/dashboard/trend` 支持 `start_date`、`end_date` 和 `granularity=day|hour`,每个点包含 requests、各类 token、`cost`、`actual_cost`。 - **模型统计**:`/usage/dashboard/models` 按模型聚合 requests、token、cache、`cost`、`actual_cost`。 - **Key 日用量**:API Key 列表/详情可调用 `/user/api-keys/{id}/usage/daily`,按天返回某个 Key 的 requests、token、cache、`cost`、`actual_cost`;批量卡片使用 `/usage/dashboard/api-keys-usage` 返回每个 Key 的今日/累计 `actual_cost`。 趋势和模型统计默认查最近 7 天,`end_date` 按包含当天处理；dashboard 日期解析失败时会回退默认范围,不一定直接报 400。Key 日用量的 `days` 默认 30,允许 1-90；访问不属于自己的 Key 会返回无权限。 --- ## 缓存、模型映射与错误请求 - **缓存**：`cache_read_tokens` 表示命中的缓存 token，`cache_creation_tokens` 表示本次写入缓存的 token。命中缓存时输入上下文可能很长，但实际费用会低于全量重算。 - **模型映射**：列表里可能同时展示「请求模型」和「上游模型」。例如你请求一个兼容别名，网关根据渠道/平台/分组规则映射到上游真实模型；排查模型表现时要看上游模型。 - **错误请求**：失败请求也可能出现在用量明细里。一般不会产生输出 token；是否有费用取决于请求是否已到达上游并产生可计费用量。排障时请提供 Request ID。 错误请求页来自 `/usage/errors` 与 `/usage/errors/{id}`。它是面向用户的脱敏视图；如果站点未开放该视图会返回 `Error requests view is disabled`，服务暂不可用时会返回 `Ops service not available`。列表 `page_size` 最大 100。接口支持按 `start_date`、`end_date`、`timezone`、`model`、`status_code`、`category`、`api_key_id` 过滤；当前页面 UI 的筛选项以实际版本为准，例如 status code 可能只在接口层可用。 | 字段 | 排查价值 | |------|----------| | `id` / `created_at` | 错误记录编号和发生时间;提交工单时可附这个 `id` | | `model` / `inbound_endpoint` | 判断模型名或 Claude/Codex/Grok 端点是否写错 | | `status_code` | 区分 400 参数错误、401/403 鉴权/额度、429 限速、5xx 上游/平台异常 | | `category` | 稳定分类码: `auth`、`quota`、`rate_limit`、`invalid_request`、`upstream`、`service_unavailable`、`internal`、`cyber`、`other` | | `platform` / `key_name` / `key_deleted` | 判断 Key 所属平台、是否已删除或用错 Key | | `message` / `error_body` / `upstream_status_code` | 详情页会展示标准化错误描述、上游错误体和上游状态码（如有） | 注意:用户侧错误请求详情不会暴露 `client_ip`、`user_agent`、账号、Key 前缀、上游端点、用户邮箱等内部字段。要追完整链路,仍优先提供用量记录里的 `request_id`;若只有错误请求页,提供错误 `id`、时间、模型、Key 名称即可。 如果是流式请求,HTTP 状态码可能已经是 200,但 SSE 里随后出现 `response.failed` 或 `response.cancelled`;这类问题要看错误详情里的事件文本和 Request ID,不能只看 HTTP 200。 ### 用量记录与错误详情的区别 排障时经常同时看到「用量记录」和「错误记录」。两者用途不同： | 页面口径 | 主要回答 | 常见字段 | |---|---|---| | 用量明细 | 这次请求是否计费、按哪个模型/Key/分组、用了多少 token 或媒体量、扣了多少 | `request_id`、`requested_model`、`upstream_model`、token、cache、`billing_type`、`billing_mode`、`request_type`、`actual_cost`、WS/image/video 字段 | | 错误请求 | 失败发生在哪个阶段、错误来源、上游返回了什么、是否有关联错误 | 错误分类、状态码、上游状态、错误描述和脱敏后的错误体 | 用量明细是计费/用量事实；错误请求是诊断视图。成功请求也可能伴随一条 `Recovered upstream error ...` 类型的上游容灾记录：它说明中间某次上游调用失败过，但最终请求可能已经恢复成功，不一定代表用户最终失败。 用户侧错误详情是脱敏视图，主要展示错误体、上游状态和标准化摘要；不要期待它能还原完整原始请求体、全部请求头、账号、Key 前缀或内部上游 URL。要闭环排查，优先提供 `request_id`，其次才是错误记录 `id` 与发生时间。 --- ### request_id / usage errors / 工单闭环 1. **先找 `request_id`**:优先从客户端响应头、错误体、控制台用量详情里复制 `request_id` 或 `x-request-id`;它能把网关日志、用量记录和上游响应串起来。 2. **再看错误请求页**:如果本次失败没有完整用量记录,切到错误请求页,用时间范围、模型、状态码、分类、Key 过滤,打开详情复制错误 `id`、`message`、`error_body`、`upstream_status_code`。 3. **最后提工单**:在工单中写明 `request_id`/错误 `id`、发生时间和时区、Base URL、端点、模型、Key 名称/分组、是否流式、是否换过线路;把终端 `curl -i` 输出、工具报错截图、用量/错误详情截图作为私有附件上传。 如果没有 `request_id`,不要只发“失败了”:至少提供精确时间范围、Key 名称、模型、端点、完整错误文本和截图。 --- ## 渠道监控和公告如何辅助排查 如果“同一个 Key 突然变慢/失败”,先不要只看余额。控制台如果开放了渠道监控,`/channel-monitors` 会列出可见线路的 `primary_status`、`primary_latency_ms`、`primary_ping_latency_ms`、`availability_7d`、`extra_models` 和近期 `timeline`;点详情后 `/channel-monitors/{id}/status` 会显示各模型 7/15/30 天可用率与平均延迟。 渠道监控功能关闭时,列表会返回空 `items: []`,详情可能返回 `CHANNEL_MONITOR_NOT_FOUND`;这不等于某个模型必然故障,只是当前用户不可见或功能未开放。维护、模型切换或价格变动通常会通过 `/announcements` 公告发布并可标记已读。公告列表支持 `read_status=all|read|unread`,也兼容 `unread_only=true|1|yes|y|on`;公告 ID 错误会返回 `Invalid announcement ID`。 --- ## 筛选与 CSV - **按密钥/模型/时间筛选**：快速定位某段时间、某个项目的消耗。用户列表接口支持 `api_key_id`、`model`、`request_type`、`stream`、`billing_type`、`start_date`、`end_date`、`timezone`、`sort_by`、`sort_order` 等参数。 - **按请求状态筛选**：区分成功、失败、取消或超时请求；布尔值和日期格式错误会返回明确错误,如 `Invalid stream value, use true or false`、`Invalid start_date format, use YYYY-MM-DD`。 - **导出 CSV**：在页面使用导出功能，把当前筛选条件下的明细下载到本地，适合团队报销、项目分摊或二次分析。CSV 字段包括 Time、API Key Name、Model、Reasoning Effort、Inbound Endpoint、Type、Billing Mode、Token、Rate Multiplier、Billed Cost、Original Cost、First Token、Duration,并会做防公式注入处理。 - **给不同项目建不同密钥**：账单天然按 Key 区分，便于分摊成本（建密钥见 [创建 API 密钥](#/api-key)）。 导出前建议先固定时间范围和 Key 过滤条件。当前 CSV 没有单独的服务端导出任务；前端会按当前筛选条件循环调用 `/usage`（通常每页 100 条）,在浏览器本地生成 Blob 下载。如果数据量太大导致失败,缩短时间范围或增加 Key/模型筛选后重试。 `request_type` 是比旧 `stream=true/false` 更稳定的分类。当前前端识别这些值: | request_type | 含义 | |---|---| | `sync` | 普通非流式文本请求 | | `stream` | SSE 流式文本请求 | | `ws_v2` | Responses WebSocket v2 / Codex WS 请求 | | `image` | 原生 Images API 请求 | | `image_web_bridge` | Web/Responses 图片桥接请求 | | `video` | Grok Videos 请求 | | `cyber` | 上游/网关安全策略相关记录,可能与原始 `stream` 维度正交 | | `unknown` | 旧数据或无法归类的请求 | 筛选视频或图片用 `request_type=video|image|image_web_bridge` 更准确；旧 `stream=false` 不能区分普通同步文本、图片和视频。若同时传 `request_type` 和旧 `stream` 参数，后端以 `request_type` 为准；只有没传 `request_type` 时才用 `stream=true|false` 作为兼容筛选。非法 `request_type` 会返回 `invalid request_type, allowed values: unknown, sync, stream, ws_v2, image, image_web_bridge, cyber, video`。 `billing_type` 用来区分扣费来源：`0` 表示钱包余额扣费，`1` 表示订阅/套餐扣费。`billing_mode` 是更细的计费模式；空值通常按 token 计费理解。 | billing_mode | 含义 | 对账重点 | |---|---|---| | `token` | 常规 token 区间计费 | 输入、输出、cache token 与模型价格 | | `per_request` | 按次/按上下文窗口分层 | 请求次数、`billing_tier`、模型/渠道定价 | | `image` | 图片计费 | `image_count`、`image_size`、输入/输出尺寸、图片输出 token/成本 | | `video` | Grok Videos 计费 | 分辨率 tier、duration/seconds、视频数量 | | `search` | 搜索/工具调用计费 | 通常按每 1k calls 的价格折算 | | `audio` | 音频计费 | realtime 分钟、TTS 字符数、STT 小时等模式 | 注意：展示/理解成本时，空 `billing_mode` 通常可按 token 口径理解；筛选历史数据时以页面实际结果为准。 图片/视频排账时优先看 `request_type`、`billing_mode`、`image_count`、`image_size`、`image_input_size`、`image_output_size`、`image_size_source`、`image_size_breakdown`、`image_output_tokens`、`image_output_cost` 等字段。`media_type` 可能作为兼容输出字段出现，但当前不是可靠持久化排账字段，通常不要把它作为唯一筛选或对账依据。Codex/Responses WS 排障时重点看 `openai_ws_mode`、`openai_ws_profile`、`openai_ws_conn_reused`、`service_tier`、`reasoning_effort` 和 `billed_by_higher_priced_upstream`。 --- ## 用 API 自助对账 除了网页，也可以用 `GET /v1/usage` 拉取当前密钥的用量数据，接进自己的脚本/看板： ```bash curl https://api.clomio.ai/v1/usage \ -H "Authorization: Bearer 你的密钥" ``` `GET /v1/usage` 有两种返回模式： | 模式 | 何时出现 | 你会看到什么 | |------|----------|--------------| | `quota_limited` | 当前 API Key 设置了 `quota`、有效期或 5h/1d/7d 限速 | Key 总额度、剩余额度、过期时间、各窗口用量和重置时间 | | `unrestricted` | Key 本身未设置额度/限速 | 账户余额或订阅信息、今日/累计用量、模型统计、每日用量 | 两种模式都会尽量返回 token、缓存和 `actual_cost` 口径，便于和控制台页面对账。 --- > 想省钱？见 [计费与额度 · 省钱技巧](#/billing)；余额/充值见 [订阅与余额](#/console-billing)。 --- # 订阅与余额 平台有**两种计费模式**，搞清楚区别，才知道钱怎么花、怎么续。控制台还提供订单恢复/验证、退款预览、发票下载/取消和订阅额度进度。 --- ## 两种计费模式 ### 1. 钱包余额（按量计费） **用多少付多少。** 你充值进钱包，每次调用按 token 实时扣费，余额实时显示。 - 适合：用量不固定、想灵活控制成本的人 - 可设**额度上限**（给密钥设额度限制），防止失控 - 余额为 0 时调用会报“余额不足” ### 2. 订阅 / 套餐 按**周期**（如包月）提供配额的套餐。控制台会显示**订阅类型**、**订阅到期**和额度进度；用户侧订阅数据来自 `/subscriptions`、`/subscriptions/active`、`/subscriptions/progress`、`/subscriptions/summary`。 - 适合：用量稳定、想要固定成本的人 - 部分分组**以套餐形式提供**；如果调用报 `No active subscription found for this group`，说明该分组需要先开通/续订套餐 - 到期后需续订才能继续用该分组 - 订阅额度进度会显示日/周/月已用比例、重置倒计时、到期时间和剩余天数，用来判断是否需要升级或续订 > 简单说：**钱包余额 = 按量付费，订阅 = 按周期包量。** 不同分组可能采用不同模式，以控制台显示为准。 真实边界：订阅分组命中有效订阅时，通常扣订阅 usage，不扣钱包余额；余额/标准分组会在请求前检查余额，成功后按 `actual_cost` 扣余额。用户级 platform quota 在订阅模式通常豁免。API Key quota、API Key 金额限速、RPM 是额外限制，不等同于钱包余额或订阅余额。余额没有逐请求冻结；高并发下可能先通过预检，结束后统一按用量扣费并刷新缓存。 --- ## 充值与支付中恢复 入口：控制台「**充值 / 订阅**」（或仪表盘「现在充值」）。页面主入口读取 `/payment/checkout-info`，该接口会聚合当前可用支付方式、全局/单笔金额上下限、套餐、余额充值倍率、手续费率、帮助文案/图片、Stripe publishable key、支付宝是否强制二维码等信息。`/payment/limits`、`/payment/plans`、`/payment/channels` 是独立接口，不要把它们理解成当前页面一定会首批全部请求。 - 按页面提示扫码/在线支付，**余额自动到账**，无需手动兑换 - **建议先小额测试**：确认速度、模型表现满意后再追加 - 有**兑换码**时，在兑换页通过 `/redeem` 核销；兑换历史可通过 `/redeem/history` 或分页 `/redeem/history-page` 查看 `code`、`type`、`value`、`status`、`used_at`，订阅兑换还会显示 `group_id`、有效天数和分组信息。兑换请求字段是 `code`;历史分页支持 `type`、`page`、`page_size`;输错/过期/重复使用会返回 `REDEEM_CODE_NOT_FOUND`、`REDEEM_CODE_USED`、`REDEEM_CODE_EXPIRED`、`REDEEM_RATE_LIMITED`、`REDEEM_CODE_LOCKED` - 如果付款页关闭、网络中断或状态一直停在“支付中”，回到「订单」页点击恢复/验证；已登录场景使用 `/payment/orders/verify`,公开恢复页可用 `/payment/public/orders/resolve` 的签名 `resume_token` 解析订单,或旧版 `/payment/public/orders/verify` 的 `out_trade_no` verify - 创建订单时页面会提交 `amount`、`payment_type`、`openid`、`wechat_resume_token`、`return_url`、`payment_source`、`order_type`、`plan_id`、`is_mobile` 等字段。`payment_source` 常见为普通托管/跳转支付的 `hosted_redirect`，以及微信内浏览器恢复支付的 `wechat_in_app_resume`。创建订单响应可能包含 `result_type`、`out_trade_no`、`pay_url`、`qr_code`、`client_secret`、`intent_id`、`currency`、`country_code`、`payment_env`、`payment_mode`、`resume_token`、`oauth`、`jsapi`/`jsapi_payload`；`result_type` 常见为 `order_created`、`oauth_required`、`jsapi_ready`。微信恢复场景若 token 缺失/不匹配,可能返回 `INVALID_WECHAT_PAYMENT_RESUME_TOKEN`、`wechat payment resume context is missing`、`wechat payment resume token missing openid`、`wechat payment resume token payment type mismatch`。 - Stripe/弹窗/扫码恢复支付会使用 signed `resume_token` 公开查询订单，推荐接口是 `POST /payment/public/orders/resolve`。普通 `resume_token` 默认约 24 小时有效；微信内恢复 token 默认约 15 分钟有效。未配置签名 key 时会返回 `PAYMENT_RESUME_NOT_CONFIGURED`；普通 token 解析、过期、签名或订单/用户/provider/支付类型不匹配时统一返回 `INVALID_RESUME_TOKEN`;订单不存在返回 `NOT_FOUND`。不要把旧订单或另一渠道的 resume token 复制到新订单继续支付。 - `return_url` 必须是绝对 `http/https` URL，路径必须是 `/payment/result`，host 必须等于当前请求 host 或 Referer host。后端会去掉 fragment，并追加 `order_id`、`out_trade_no`、`resume_token`、`status=success`。只有 `return_url` 合法且支付恢复签名已配置时才会返回 `resume_token`。 - 微信内没有 `openid` 时，创建订单可能返回 `result_type=oauth_required` 和 `oauth.authorize_url`，前端跳转微信 OAuth；回调回到前端 URL fragment，带 `wechat_resume_token` 和 `redirect`。再次创建订单时提交该 token，后端会使用 token 里的 `openid/payment_type/amount/order_type/plan_id` 等值。 - 不同支付渠道可能有单笔金额、每日金额、退款和发票开关限制。页面只展示当前可用渠道,以控制台实时配置为准；退款入口还会受 `/payment/orders/refund-eligible-providers` 限制,发票入口会受 `/payment/orders/invoice-eligible-providers` 限制。 创建订单常见错误: 系统生成的订单号通常类似 `sub2_YYYYMMDDxxxxxxxx`，非空订单号有唯一约束。公开恢复页的旧版 `/payment/public/orders/verify` 使用 `out_trade_no` 主动查单并可能触发上游对账补记。`out_trade_no` 为空、超过 64 字符，或包含字母/数字/下划线/连字符以外字符时，会返回 `INVALID_OUT_TRADE_NO`。 | 错误 | 含义 | |---|---| | `BALANCE_PAYMENT_DISABLED` / `balance recharge has been disabled` | 余额充值关闭 | | `PAYMENT_METHOD_DISABLED` / `method_not_configured` | 支付方式关闭或未配置 | | `INVALID_AMOUNT` / `amount must be a positive number` / `amount out of range` | 金额为空、非正数或超出范围 | | `INVALID_INPUT` / `subscription order requires a plan` | 订阅订单缺套餐 | | `PLAN_NOT_AVAILABLE` | 套餐不可用 | | `GROUP_NOT_FOUND` / `GROUP_TYPE_MISMATCH` | 套餐/分组不匹配 | | `INVALID_RETURN_URL` | 回跳地址不允许或格式错误 | | `INVALID_WECHAT_PAYMENT_RESUME_TOKEN` | 微信支付恢复 token 缺失、过期、payload 非法、支付类型/金额不匹配 | | `PAYMENT_DISABLED` / `USER_INACTIVE` | 支付系统关闭或用户状态不可支付 | | `TOO_MANY_PENDING` / `DAILY_LIMIT_EXCEEDED` | 待支付订单过多或当日金额限制 | | `NO_AVAILABLE_INSTANCE` / `PAYMENT_GATEWAY_ERROR` / `PAYMENT_PROVIDER_MISCONFIGURED` | 当前支付实例/通道不可用或服务商配置异常 | | `WECHAT_PAYMENT_MP_NOT_CONFIGURED` / `WECHAT_H5_NOT_AUTHORIZED` | 微信 JSAPI/MP 配置缺失或商户未开通 H5 支付 | --- ## 订单状态 「**订单**」页可查历史充值记录：`amount`、实际支付 `pay_amount`、`fee_rate`、`payment_type`、`out_trade_no`、`order_type`、创建/过期/支付/完成时间、失败原因、退款金额与发票关联状态。列表来自 `GET /payment/orders/my`,支持 `page`、`page_size`、`status`、`order_type`、`payment_type` 过滤;返回中还可能看到 `provider_instance_id`、`invoice_status`、`invoice_id`。对账或售后时，提供 `out_trade_no`、订单 ID、支付渠道和付款时间能更快定位。 未支付订单可在详情页取消，页面会调用 `POST /payment/orders/{id}/cancel`。取消只允许 `PENDING` 订单；如果支付已经完成或订单已过期/已取消，请重新下单或走退款/工单流程。站点可能配置取消频率限制，短时间反复创建/取消订单会被限制。 取消订单常见错误:`FORBIDDEN` 表示不是你的订单,`NOT_FOUND` 表示订单不存在,`INVALID_STATUS` 表示当前状态不能取消,`ORDER_ALREADY_PAID` 表示取消前与上游对账发现已付款。用户取消频率超限会返回 `CANCEL_RATE_LIMITED`,metadata 会带 `max`、`window`、`unit`。 常见状态： | 状态 | 含义 | 你可以做什么 | |------|------|--------------| | `PENDING` | 已创建，等待支付 | 继续支付或取消 | | `COMPLETED` / `PAID` | 支付完成并已入账/开通 | 查看明细、申请发票或退款 | | `RECHARGING` | 支付已确认，正在入账或开通中 | 等待最终完成；不要重复付款 | | `FAILED` | 支付失败或验签失败 | 重新下单；必要时提交工单 | | `CANCELLED` / `EXPIRED` | 已取消或超时 | 重新创建订单 | | `REFUND_REQUESTED` | 已提交退款申请 | 等待处理 | | `REFUNDING` | 正在退款 | 等待支付渠道回调 | | `REFUNDED` | 已全额退款 | 查看退款金额和时间 | | `PARTIALLY_REFUNDED` | 已部分退款 | 查看剩余可退金额 | | `REFUND_FAILED` | 退款失败 | 提交工单或重试 | --- ## 主动验证与支付结果页 `/payment/orders/verify` 会按 `out_trade_no` 查找当前登录用户的订单；当订单处于 `PENDING`、`EXPIRED`、`FAILED`、`CANCELLED` 等可恢复状态时，会主动调用上游 `QueryOrder`，如果上游显示已支付，会走本地入账/开通流程并重新加载订单。公开旧接口 `/payment/public/orders/verify` 是兼容路径，主要用于带 `out_trade_no` 的老结果页，公开恢复范围更窄，主要覆盖 `EXPIRED`、`FAILED`、`CANCELLED` 等状态；推荐恢复路径仍是 signed `resume_token` + `/payment/public/orders/resolve`。 支付结果页通常优先用 `resume_token` 恢复；失败时在有订单号上下文时回退到订单轮询或 `out_trade_no` 验证。微信扫码待支付时，前端会有限次数主动触发验证，以弥补支付回调延迟。 --- ## 退款与退款预览 如需退款，可在控制台自助申请（或通过工单）。发起前先看 `/payment/orders/{id}/refund-preview` 的**退款预览**：它会展示 `max_refund_amount`、`already_refunded`、`refund_enabled`、`auto_refund`、余额可用额或订阅已用折算等信息。提交退款时常见字段是 `reason` 和可选 `amount`;订单号不合法会返回 `Invalid order ID`,重复申请可能显示 `refund requested`。 - 已消耗部分通常不能按原额退款。 - 已开票或有发票申请的订单，退款入口可能隐藏、被阻止，或需要人工确认。 - 只有支持用户自助退款的支付渠道才会显示退款入口；否则请提交工单并附订单号。 - 已经提交退款申请后,订单会进入退款申请/退款中状态,请不要重复创建多张工单催同一笔订单;如确需补充材料,在同一工单里追加支付截图、订单号和退款原因。 - 用户自助退款只允许已完成订单；存在 `APPLIED`/`ISSUED` 等 active 发票时会被拦截。若已开票后需要退款，通常要先按页面提示或工单流程处理发票作废/红冲。 订阅订单退款预览会把已用订阅额度按退款倍率折算，常见理解是： ```text 订阅折算已使用金额 = usage_amount / subscription_rate_multiplier * refund_rate_multiplier 最大可退 = 订单剩余可退金额 - 折算已使用金额 ``` 预览里可能出现 `usage_amount`、`subscription_rate_multiplier`、`refund_rate_multiplier`、`used_refund_value`。`refund_rate_multiplier <= 0` 会归一为 1。余额订单退款上限通常取“订单剩余可退金额”和“当前可用余额”的较小值。 退款被阻止时，常见错误包括 `INVALID_STATUS` / `only completed orders can request refund`、`REFUND_DISABLED` / `refund is not available for this order`、`refund is not enabled for this provider`、`INVOICE_STATE_UNAVAILABLE`、`INVOICE_ACTIVE` / `order has an active invoice application`、`REFUND_AMOUNT_EXCEEDED`。看到发票相关错误时，先处理发票申请或提交工单，不要重复提交退款。 > **税费提示：** 如果是**因你一方原因**（例如已开票后又申请退款）需要承担税费，通常 **5% 的税费由你承担**；因平台原因导致的退款，税费与你无关。简单说：**没开票、未消耗时退款最省事。** 详见 [常见问题](#/faq)。 --- ## 开具发票 「**发票**」页可申请开票，列表 `GET /payment/invoices` 支持 `page`、`page_size`、`status`、`keyword`。创建发票时选择 1 个或多个符合条件的已完成订单，并填写 `order_ids`(至少 1 个)、`title`、`tax_number`、`email`、`contact_name`、`contact_phone`、`request_note`。 常见发票状态： | 状态 | 含义 | 可操作 | |------|------|--------| | `APPLIED` | 已提交申请，等待开票 | 可取消申请 | | `ISSUED` | 已开票 | 可下载发票文件 | | `CANCELLED` | 已取消 | 可重新按符合条件的订单申请 | 订单详情和发票详情页会显示关联状态；发票详情可返回关联订单列表。详情字段包括 `id`、`user_id`、`user_email`、`status`、`invoice_amount`、`order_count`、`title`、`tax_number`、`email`、`contact_name`、`contact_phone`、`request_note`、`file_media_id`、`file_name`、`file_mime_type`、`file_size_bytes`、`applied_at`、`cancelled_at`、`issued_at`、`created_at`、`updated_at` 和 `orders[]`；`orders[]` 每项通常有 `order_id`、`out_trade_no`、`pay_amount_snapshot`、`payment_type`、`created_at`。`APPLIED` 可取消，`ISSUED` 才可通过 `/payment/invoices/{id}/download` 获取签名下载链接；已开票订单退款前请先确认税费与作废规则。 发票列表 `page_size` 服务端最大 100；`keyword` 会匹配发票抬头、邮箱、用户邮箱、税号，也会通过关联订单号 `out_trade_no` 查找发票。单张发票最多 100 个订单；重复 `order_ids` 会去重；发票金额按所选订单 `pay_amount` 求和并保留 2 位。按订单号搜不到时，先确认订单是否已经关联到该发票申请。 用户侧申请按钮要求订单已完成、有 provider instance、provider 出现在 `/payment/orders/invoice-eligible-providers` 返回列表中，且没有 active 发票。active 发票通常指 `APPLIED` 或 `ISSUED`；`CANCELLED` 发票会释放订单，可重新申请。订单列表/详情里的 `invoice_status`、`invoice_id` 是通过发票关联表和 active 发票状态计算出来的，不要把它理解为订单表里永远固定的字段。 发票相关常见错误: | 错误码 | 含义与处理 | |---|---| | `INVOICE_ORDER_IDS_REQUIRED` | 创建发票未传 `order_ids` | | `INVOICE_BATCH_TOO_MANY` | 单次申请订单数超过上限 | | `INVOICE_TITLE_REQUIRED` / `INVOICE_TAX_NUMBER_REQUIRED` / `INVOICE_EMAIL_REQUIRED` | 抬头、税号或收票邮箱缺失 | | `INVOICE_ORDER_INELIGIBLE` | 订单不是 completed 状态 | | `INVOICE_DISABLED` | 该支付渠道未开启发票 | | `INVOICE_ALREADY_INVOICED` | 订单已有有效发票申请/已开票 | | `INVOICE_CANNOT_CANCEL` | 只有 `APPLIED` 状态可取消 | | `INVOICE_CANNOT_UPLOAD` | 当前发票状态不允许上传文件 | | `INVOICE_NOT_ISSUED` | 发票未开具或没有文件,不能下载/重发邮件 | | `INVOICE_FILE_STORAGE_UNAVAILABLE` / `INVOICE_FILE_REQUIRED` | 发票文件存储未配置或上传文件为空 | | `INVOICE_EMAIL_DISABLED` | 发票邮件服务未配置 | | `INVOICE_NOT_FOUND` / `FORBIDDEN` | 发票不存在或无权访问 | | `INVOICE_SERVICE_UNAVAILABLE` / `Invalid id` / `Invalid request: ...` | 发票服务未初始化、ID 或请求体格式错误 | | `INVALID_USER` / `NOT_FOUND` / `INVOICE_EMAIL_REQUIRED` | 用户、订单/发票不存在或重发邮件缺邮箱 | 刷新列表后重试,必要时提交工单 | 发票申请一般需要选择符合条件的已支付订单;已退款、退款中、已关联其他有效发票申请或渠道未开启发票能力的订单可能不会出现在可选列表。若发票服务未开启或配置异常,页面可能显示 `INVOICE_SERVICE_UNAVAILABLE` / `invoice service unavailable`。 > **建议余额消耗完后再开票。** 一旦开票即视同确认收入完成报税；若充值后未消耗就提前开票再退款，可能产生税费问题。详见 [常见问题](#/faq)。 --- ## 用量日志排账提示 文本 token 为 0 不代表一定免费；图片、视频、搜索、音频可能走非 token 的 `billing_mode`。看用户扣费优先看 `actual_cost`；理解基础成本看 `total_cost`。图片排账要结合 `image_count`、`image_size`、`image_input_size`、`image_output_size`、`image_size_source`、`image_size_breakdown`、`image_output_tokens`、`image_output_cost`。导出或提交工单时保留 `request_id`，便于对账留档。 > 看每笔消耗见 [用量明细](#/console-usage)；计费原理与省钱见 [计费与额度](#/billing)。 --- # 邀请、工单与账号 控制台里和账号相关的功能：登录注册、会话安全、邀请返利、提交工单、个人资料、通知邮箱、密码修改、TOTP 双因素认证、第三方 OAuth 授权绑定。网页端 AI 与技能市场已拆到 [AI Studio](#/console-ai-studio) 和 [技能市场与创作者中心](#/console-skills)。这些都是控制台用户功能,不要和公开模型网关 API 混淆。 --- ## 登录、注册与会话安全 控制台登录注册走用户认证接口,不是网关 API Key 接口: - 邮箱密码登录: `/auth/login`;如果返回 `requires_2fa`,页面会继续调用 `/auth/login/2fa` 输入 TOTP 动态码。 - 注册: `/auth/register`;如果站点开启邮箱验证或邀请码/推广码校验,页面会先调用 `/auth/send-verify-code`、`/auth/validate-invitation-code` 或 `/auth/validate-promo-code`。 - 当前用户: `/auth/me`,可带 `touch_active=true` 刷新活跃时间。 - 退出登录: `/auth/logout`;如果请求带 refresh token,服务端会撤销当前 token,前端无论撤销是否成功都会清理本地 `auth_token`、`refresh_token`、`token_expires_at`、`auth_user`。 - Token 刷新: `/auth/refresh`;refresh token 会轮换,过期、不存在、疑似复用/重放或 backend mode 禁止普通用户刷新时,页面会要求重新登录。安全页的“退出所有设备/吊销全部会话”走 `/auth/revoke-all-sessions`,会撤销当前用户全部 token。 - 忘记/重置密码: `/auth/forgot-password` 发送重置流程,`/auth/reset-password` 提交邮箱、token 和新密码。 密码重置功能可被站点关闭。关闭时 `/auth/forgot-password` 和 `/auth/reset-password` 都会返回 `PASSWORD_RESET_DISABLED`;功能开启时,为了防止枚举用户,不存在的邮箱、邮件队列异常或发送失败通常会静默成功,页面只提示“如果邮箱存在将收到邮件”。因此“忘记密码页面显示成功但没收到邮件”要同时检查垃圾箱、邮箱拼写、邮件配置和站点开关。 第三方登录/绑定可能进入 pending 流程:例如 OAuth 返回后需要补邮箱验证码、确认创建新账号、绑定到当前账号或采用第三方头像/昵称时,前端会使用 `/auth/oauth/pending/send-verify-code`、`/auth/oauth/pending/exchange`、`/auth/oauth/pending/create-account`、`/auth/oauth/pending/bind-login`。这些步骤只在对应入口和站点配置开启时出现。 OAuth pending 关键字段与真实错误: | 流程 | 端点 | 主要字段 | 常见错误 | |---|---|---|---| | pending 新账号 | `/auth/oauth/pending/create-account` | `email`、`verify_code`、`password`、`invitation_code`、`aff_code`、`adopt_display_name`、`adopt_avatar` | `PENDING_AUTH_NOT_READY`、`SERVICE_UNAVAILABLE`、`PENDING_AUTH_ACCOUNT_ROLLBACK_FAILED`、`Pending oauth session provider mismatch` | | pending 绑定已有账号 | `/auth/oauth/pending/bind-login` | `email`、`password`、`adopt_display_name`、`adopt_avatar` | `PENDING_AUTH_TARGET_USER_MISMATCH`、`Failed to create 2FA session`;若目标账号启用 2FA,响应可能带 `requires_2fa`、`temp_token`、`user_email_masked` | | GitHub/Google 补注册 | `/auth/oauth/{github|google}/complete-registration` | `password`、`invitation_code`、`aff_code` | `Invalid request: ...`、`Pending oauth session provider mismatch` | | LinuxDo/Wechat/OIDC/DingTalk 旧路径 | `/auth/oauth/{provider}/complete-registration` 或 `/bind-login` | 复用 pending create/bind 字段 | provider mismatch 或 pending session 过期 | 常见请求字段和限流口径: | 场景 | 主要字段 | 限流参考 | |------|----------|----------| | 注册 `/auth/register` | `email`、`password`(至少 6 位)、`verify_code`、`turnstile_token`、`promo_code`、`invitation_code`、`aff_code` | 约 5 次/分钟 | | 登录 `/auth/login` | `email`、`password`、`turnstile_token`;若返回 `requires_2fa` 再调 `/auth/login/2fa` | 约 20 次/分钟 | | 发送验证码 `/auth/send-verify-code` | `email`、`turnstile_token` | 约 5 次/分钟 | | 忘记/重置密码 | `/auth/forgot-password`、`/auth/reset-password` | 约 5/10 次/分钟 | | 刷新 token `/auth/refresh` | refresh token | 约 30 次/分钟 | `/auth/me?touch_active=true` 会刷新 last active,响应里还会带 `run_mode`。如果看到“登录态还在但刷新失败”,优先清理本地 token 后重新登录,不要把控制台 JWT 当模型 API Key 使用。 邀请码/推广码验证会返回更细的 `error_code`,例如 `PROMO_CODE_DISABLED`、`PROMO_CODE_NOT_FOUND`、`PROMO_CODE_EXPIRED`、`PROMO_CODE_MAX_USED`、`PROMO_CODE_ALREADY_USED`、`PROMO_CODE_INVALID`、`INVITATION_CODE_DISABLED`、`INVITATION_CODE_NOT_FOUND`、`INVITATION_CODE_INVALID`、`INVITATION_CODE_USED`。 注册邮箱后缀白名单开启时,不在允许范围内会返回 `EMAIL_SUFFIX_NOT_ALLOWED`。错误 metadata 里会带 `allowed_suffixes` 和 `allowed_suffix_count`;前端可直接提示允许的域名后缀,不要把它当成验证码或密码错误。 认证接口限流依赖 Redis;若 Redis 异常,服务按 fail-close 处理,可能表现为验证码/登录/重置被临时限制。常见错误包括 `Invalid request: ...`、`Failed to generate token`、`登录暂不可用`。 --- ## 邀请返利 通过你的专属**邀请链接**邀请他人注册使用，可获得返利。该页来自 `/user/aff`,明细 ledger 来自 `/user/aff/invitees/{id}/ledger`,转余额走 `/user/aff/transfer`。 - 在「**邀请**」页拿到你的专属链接或邀请码，分享出去 - 页面会显示**邀请人数**、**累计返利**和可转余额 - 被邀请人充值/消费后，按规则给你返利（具体比例、冻结期、上限以页面说明为准） - 可把已解冻返利**转入账户余额**，转入后就能像普通余额一样用于 API 调用 邀请功能可能受站点开关控制。如果页面没有「邀请」入口,说明当前站点未开放或你的账号暂不可用。 ### 邀请明细与 ledger 邀请页可查看每个被邀请人的明细：注册时间、充值/消费、返利记录、冻结/解冻状态、转余额记录等。遇到“为什么这笔还没到账”时，先看对应 invitee 的 ledger；如果仍不清楚，提交工单并附上被邀请人、时间和记录截图。 --- ## 工单 遇到账户、充值、退款、报错等问题，提交**工单**联系支持。 - 入口：控制台「**工单**」→ 新建；列表来自 `/tickets`,详情来自 `/tickets/{id}` - 工单支持咨询、退款、并发/限速、倍率/计费、其他问题等类型；创建/编辑会提交 `title`、`category`、`form_payload`、`expected_revision_no` - 可上传附件：截图、日志、CSV、报错文本等；附件上传走 `/media/upload`,并带 `biz_type=ticket`、`biz_id`、`visibility=private`,回复时用 `attachments: [{ media_id }]` 关联 - 提交后可在工单列表查看回复与状态流转；回复走 `/tickets/{id}/messages`,草稿提交走 `/tickets/{id}/submit`,撤回/关闭分别走 `/withdraw`、`/close` - 草稿/待提交工单可继续编辑、提交或撤回;已关闭工单如问题复现,建议新建工单并引用旧工单号。 工单功能也可能受站点开关控制;入口不可见时可使用站点提供的其他联系方式。 列表筛选支持 `page`、`page_size`、`status`、`category`、`search`、`start_date`、`end_date`、`timezone`、`sort_by`、`sort_order`。日期格式不合法会返回 `invalid start_date` / `invalid end_date`;开始时间晚于结束时间会返回 `invalid date range`。 编辑和提交草稿使用乐观锁:请求体可带 `expected_revision_no`,也可用 `If-Match` header。多人或多标签页同时编辑时,可能返回 `TICKET_REVISION_REQUIRED`、`TICKET_REVISION_CONFLICT`、`TICKET_NOT_EDITABLE`;处理方式是刷新详情,基于最新 revision 重新编辑。回复正文为空或过大会返回 `TICKET_MESSAGE_REQUIRED` / `TICKET_MESSAGE_TOO_LARGE`;附件上传若媒体服务关闭会返回 `MEDIA_STORAGE_DISABLED`,工单被锁定时回复会返回 `TICKET_REPLY_LOCKED`。 ### 附件与媒体上传 用户媒体接口包括 `/media/upload`、`/media/{id}`、删除、可见性更新、预签名下载和缩略图下载；公开访问/签名下载有独立路由。工单附件一般使用 `biz_type=ticket`、`visibility=private`;`visibility` 只接受 `private` 或 `public`,默认 `private`,空 `biz_id` 会归到 `unassigned`。默认单文件大小约 64MB。常见媒体错误码:`MEDIA_FILE_REQUIRED`、`MEDIA_FILE_TOO_LARGE`、`MEDIA_BIZ_TYPE_INVALID`、`MEDIA_VISIBILITY_INVALID`、`MEDIA_SIGNATURE_INVALID`、`MEDIA_SIGNATURE_EXPIRED`、`MEDIA_FORBIDDEN`、`MEDIA_NOT_FOUND`。 常见状态： | 状态 | 含义 | |------|------| | 待处理 / Open | 已提交，等待支持查看 | | 处理中 / In Progress | 支持正在排查或等待外部结果 | | 等待用户 / Waiting User | 需要你补充截图、订单号、Request ID 等信息 | | 已解决 / Resolved | 已给出处理结果 | | 已关闭 / Closed | 工单结束；如问题复现可重新提交 | **怎么提问效率高：** - 带上**完整报错截图**（别只截一部分） - 说明你的密钥**分组名**和用的**工具/模型** - 提供 Request ID、错误请求 `id`、订单号、发票号或时间范围 - 描述复现步骤：什么命令、Base URL/端点、模型、Key 名称/分组、是否流式、是否换过线路、出现什么 - 附件只做补充:请在正文里写出关键字段,再上传终端 `curl -i` 输出、工具配置截图、用量/错误详情截图或支付凭证 > 报错类问题，先对照 [故障排查](#/troubleshooting) 自助排查——大部分（分组不匹配、余额不足、网络/代理）都能自己解决，省去等待。 --- ## 个人资料与通知邮箱 「**个人中心**」可管理账号信息： - 查看资料：`/user/profile` - 编辑资料：`PUT /user` 支持 `username`、`avatar_url`、余额通知开关与阈值、额外通知邮箱列表；头像支持 http(s) URL 或有效 image data URL,内联头像最大约 100KB - 修改密码：`PUT /user/password`,提交 `old_password` 和 `new_password` - 设置**通知邮箱**：用于余额提醒、账号通知、工单/发票/支付相关通知 - 查看**平台额度**：`/user/platform-quotas` 会返回当前用户各平台额度与已用量（入口可见时显示） 资料响应可能展示 `avatar_source`、`username_source`、`display_name_source`、`nickname_source`、`profile_sources`,用于说明资料来自本地还是第三方 OAuth。用户对象还可能含 `last_login_at`、`last_active_at`、余额通知字段和订阅摘要。 通知邮箱通过 `/user/notify-email/send-code` 发送验证码,再用 `/user/notify-email/verify` 添加；之后可用 `/user/notify-email/toggle` 启停某个邮箱,或 `DELETE /user/notify-email` 移除。额外通知邮箱最多 3 个；验证码 15 分钟有效,同邮箱 1 分钟冷却,最多 5 次尝试,用户级发送限制约 10 分钟 5 次。`NotifyEmailEntry` 包含 `email`、`disabled`、`verified`。常见错误:`VERIFY_CODE_TOO_FREQUENT`、`VERIFY_CODE_MAX_ATTEMPTS`、`NOTIFY_CODE_USER_RATE_LIMIT`、`TOO_MANY_NOTIFY_EMAILS`、`EMAIL_NOT_FOUND`。 --- ## TOTP 双因素认证 TOTP（2FA）可用 Google Authenticator、1Password、Microsoft Authenticator 等动态验证码 App 提升登录安全。 基本流程： 1. 进入「个人中心」→「双因素认证」；页面先用 `/user/totp/status` 判断功能是否开启、当前账号是否已启用 2. 页面会先请求 `/user/totp/verification-method`,按返回结果用邮箱验证码或密码验证身份 3. 如验证方式需要邮箱码,先调用 `/user/totp/send-code`;验证通过后 `/user/totp/setup` 返回二维码、密钥和 `setup_token`,再扫描二维码或复制密钥到验证器 App 4. 输入 6 位动态验证码和 `setup_token`,调用 `/user/totp/enable` 完成启用 关闭 TOTP 走 `/user/totp/disable`,也需要再次验证身份。启用后请妥善保存恢复方式，避免换手机后无法登录。 字段细节: - `/user/totp/setup` 可提交 `email_code`、`password` 做身份确认;成功返回 `secret`、`qr_code_url`、`setup_token`、`countdown`。 - `/user/totp/enable` 要提交 6 位 `totp_code` 和 `setup_token`。 - `/user/totp/disable` 可提交 `email_code`、`password`。未登录会返回 `User not authenticated`,字段不对会返回 `Invalid request: ...`。 - 身份确认方式由 `/user/totp/verification-method` 决定:返回 `email` 时需要先 `/user/totp/send-code`,再带 `email_code`;返回 `password` 时带当前密码。若邮箱验证未开启却调用发送验证码,会返回 `EMAIL_VERIFY_NOT_ENABLED`;缺字段会返回 `VERIFY_CODE_REQUIRED` 或 `PASSWORD_REQUIRED`。 - 常见 TOTP 错误码:`TOTP_NOT_ENABLED`、`TOTP_ALREADY_ENABLED`、`TOTP_NOT_SETUP`、`TOTP_INVALID_CODE`、`TOTP_SETUP_EXPIRED`、`TOTP_TOO_MANY_ATTEMPTS`。短时间多次输错动态码后,先等冷却再试。 --- ## 绑定 / 解绑第三方授权 支持把账号与多种登录方式绑定，绑定后即可用对应方式快捷登录。具体可见方式取决于 `/settings/public` 和站点开关： | 方式 | 说明 | |------|------| | 邮箱 | 基础登录，用于找回与通知 | | LinuxDo | 社区账号登录 | | GitHub | 开发者常用 | | Google | 谷歌账号 | | 微信 | 扫码登录 | | 钉钉 | 企业场景 | | OIDC | 企业统一身份 | 在「个人中心」找到对应入口，前端会先请求 `/auth/oauth/bind-token`,再跳转到 `/auth/oauth/{provider}/bind/start?intent=bind_current_user` 完成绑定；不再使用时可调用 `/user/account-bindings/{provider}` 解绑。邮箱绑定单独走 `/user/account-bindings/email/send-code` 和 `/user/account-bindings/email`,需要邮箱验证码和当前密码。第三方绑定 start 可带 `provider`、`redirect_to`;邮箱绑定提交 `email`、`verify_code`、`password`。解绑第三方身份成功后会撤销当前用户全部 token,页面可能要求重新登录。建议至少保留一种稳定可用的登录方式，避免误解绑导致无法登录。 补注册差异要注意:GitHub/Google 的 `/complete-registration` 只补 `password`、`invitation_code`、`aff_code`;LinuxDo/Wechat/OIDC/DingTalk 等旧路径会复用 pending create/bind 流程,可能要求邮箱、验证码、密码以及是否采用第三方昵称/头像。看到 `Pending oauth session provider mismatch` 时,通常是授权入口和补注册入口的 provider 不一致或旧 pending session 被复用。 > **绑定/登录时遇到 OAuth 验证错误？** 多为代理环境所致——请先**完全关闭翻墙/代理软件**再授权；若浏览器没自动跳转，可复制终端/页面里的链接手动打开完成验证。详见 [故障排查](#/troubleshooting)。 如果绑定邮箱或通知邮箱时收不到验证码,先检查垃圾箱、邮箱拼写和发送频率限制;短时间内多次点击发送可能触发冷却,等待几分钟再试。 --- ## 网页端 AI 与技能市场入口 网页端 AI、提示词、图库、图片编辑详见 [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio)。技能市场、安装、版本审核、运行记录和收益详见 [技能市场与创作者中心](#/console-skills)。 > 这些入口服务的是浏览器内体验;终端、SDK 和 Claude Code/Codex/Grok 的模型调用仍使用你创建的 API Key 和公开网关端点。充值与发票见 [订阅与余额](#/console-billing)；用量见 [用量明细](#/console-usage)。 --- ## 环境准备 # Node.js 环境 部分安装方式(npm 全局安装)需要 Node.js。 > **可以跳过吗?** 如果你用 [CLI 镜像](#/cli-mirror) 的 `install.sh` 一键安装(快速开始里用的方式),装的是**独立二进制,不依赖 Node.js**,可以直接跳过本页。只有当你打算用 `npm install -g` 安装,或工具明确要求 Node 时,才需要装它。 下面以安装 **LTS(长期支持)** 版本为准。 --- ## Windows **推荐:winget 一键安装。** 打开 PowerShell,执行: ```powershell winget install OpenJS.NodeJS.LTS ``` 过程中若提示确认,输入 `Y`。也可以前往 [Node.js 官网](https://nodejs.org/zh-cn/download/) 下载安装包,双击一路下一步。 --- ## macOS **推荐:Homebrew。** ```bash brew install node ``` 没有 Homebrew 的话,到 [Node.js 官网](https://nodejs.org/zh-cn/download/) 下载 macOS 安装包安装即可。 --- ## Linux **Ubuntu / Debian:** ```bash curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs ``` --- ## 验证安装 ```bash node -v npm -v ``` 两个命令都输出版本号,即安装成功。 如果是为了安装 `claude` / `codex` / 相关 VS Code 扩展 CLI,再确认 npm 全局命令目录可执行: ```bash npm bin -g 2>/dev/null || npm prefix -g ``` Node.js 只影响 npm 安装和本地 CLI 是否能启动,**不决定 Base URL 规则**:Claude Code 仍用不带 `/v1` 的 Anthropic 根地址;Codex/OpenAI-compatible 仍用带 `/v1` 的地址。 --- ## 用 Node.js 调 OpenAI SDK Node.js 不是 Base URL 规则的一部分。只有当你在项目里用 npm 包或 SDK 时才需要它。OpenAI SDK 接 Clomio 的最小示例: ```bash npm install openai export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥" ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.CLOMIO_API_KEY, baseURL: "https://api.clomio.ai/v1", }); const result = await client.responses.create({ model: "控制台里的 OpenAI/Codex 模型名", input: "ping", max_output_tokens: 16, }); console.log(result.output_text); ``` 建议把 `baseURL` 显式写出来，不要依赖 SDK 默认值或项目里残留的 `OPENAI_BASE_URL`： ```javascript const client = new OpenAI({ apiKey: process.env.CLOMIO_API_KEY, baseURL: process.env.OPENAI_BASE_URL ?? "https://api.clomio.ai/v1", }); ``` SDK 会自己在 `baseURL` 后拼 `/responses`、`/images/*` 等具体路径，所以这里写到 `/v1` 即止；不要写成 `https://api.clomio.ai/v1/responses`。Responses 流式事件以 `response.completed` / `response.failed` / `response.cancelled` 判断结束；只有 Chat Completions SSE 才沿用 `data: [DONE]` 习惯。 排障时不要只打印 `err.message`。OpenAI SDK 错误对象通常带 `status`、`headers`、`request_id` / `_request_id` 等字段；把它们打出来，工单才能和网关 `request_id` 对上： ```javascript try { const resp = await client.responses.create({ model: "控制台里的 OpenAI/Codex 模型名", input: "ping", }); console.log(resp.output_text); } catch (err) { console.error("status:", err.status); console.error("request_id:", err.request_id ?? err._request_id ?? err.headers?.["x-request-id"]); console.error("body:", err.error ?? err.message); throw err; } ``` 如果要调用图片,仍用同一个 `baseURL: "https://api.clomio.ai/v1"`,但 Key 和模型要属于 OpenAI 图片能力或 Grok 图片能力。Embeddings 只用 OpenAI/Codex 分组；视频能力单独只走 Grok 分组 Key。 --- ## 用 Node.js 调 Claude / Gemini REST 不想引入额外 SDK 时,Node 18+ 的 `fetch` 就能做最小验证。Claude / Anthropic-compatible 的配置根地址不带 `/v1`,但实际 HTTP 路径仍是 `/v1/messages`: ```bash export CLOMIO_CLAUDE_KEY="你的Claude分组密钥" ``` ```javascript const resp = await fetch("https://api.clomio.ai/v1/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.CLOMIO_CLAUDE_KEY}`, "anthropic-version": "2023-06-01", "content-type": "application/json", }, body: JSON.stringify({ model: "claude-sonnet-4-6", max_tokens: 16, messages: [{ role: "user", content: "ping" }], }), }); console.log(resp.status, resp.headers.get("x-request-id")); console.log(await resp.text()); ``` Gemini 原生入口用根地址 + `/v1beta/...`,可用 `x-goog-api-key`: ```bash export CLOMIO_GEMINI_KEY="你的Gemini分组密钥" ``` ```javascript const resp = await fetch("https://api.clomio.ai/v1beta/models", { headers: { "x-goog-api-key": process.env.CLOMIO_GEMINI_KEY }, }); console.log(resp.status); console.log(await resp.text()); ``` 如果你使用对应厂商 SDK,规则仍相同:Claude/Anthropic-compatible 的 base URL 写 `https://api.clomio.ai`;OpenAI-compatible/Codex/Grok 写 `https://api.clomio.ai/v1`;Gemini 原生不要写成 OpenAI `/v1/models`。 --- ## 国内加速:切换 npm 镜像源 如果用 `npm install` 装依赖时很慢或超时,切到国内镜像源: ```bash npm config set registry https://registry.npmmirror.com ``` 验证: ```bash npm config get registry ``` 输出 `https://registry.npmmirror.com` 即生效。想切回官方源,把地址换成 `https://registry.npmjs.org` 再执行一次即可。 --- > 装 Node 过程中遇到报错?多半和代理环境有关,见 [故障排查](#/troubleshooting)。 --- # 创建 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) --- # 网关线路 Clomio 网关提供**三条线路**,内容完全一致、共用同一个 API 密钥,区别只在网络优化方向。哪条快、哪条稳,取决于你的网络环境——**选一条体验最好的用即可,随时可换。** --- ## 三条线路 | 线路地址 | 优化方向 | 适合 | |----------|----------|------| | `https://api.clomio.ai` | **默认直连** | 国外服务器、或本身能直连国外的网络,延迟最低 | | `https://sub.qazwc.com` | **Cloudflare 优化** | 走 CF CDN,国内多数家庭宽带较稳 | | `https://crs.qazwc.com` | **三网优化** | 针对电信 / 联通 / 移动优化,国内访问更快更稳 | > 三条线路接受相同的密钥、相同的协议。本文档其他页面的配置示例默认用 `api.clomio.ai`,你可以**直接替换成任意一条**。 > > 替换时只换域名,不要改协议规则:OpenAI-compatible / Codex / Grok / Hermes/OpenClaw OpenAI-compatible用 `线路 + /v1`;Claude Code / Anthropic-compatible 用不带 `/v1` 的线路根地址。 --- ## 怎么选 1. 先用默认的 `api.clomio.ai` 试。 2. 如果在国内直连不稳(卡顿、超时、偶发失败),换成 `crs.qazwc.com`(三网优化)通常最稳。 3. 仍不理想,再试 `sub.qazwc.com`(CF 优化)。 哪条延迟低、掉线少,就长期用哪条。不同地区、不同运营商的最优线路可能不同,多试一下即可。 --- ## 换线路时 Base URL 怎么写 | 场景 | `api.clomio.ai` | `sub.qazwc.com` | `crs.qazwc.com` | |------|------|------|------| | Claude Code / Anthropic-compatible | `https://api.clomio.ai` | `https://sub.qazwc.com` | `https://crs.qazwc.com` | | OpenAI-compatible / Codex / Grok | `https://api.clomio.ai/v1` | `https://sub.qazwc.com/v1` | `https://crs.qazwc.com/v1` | | Hermes/OpenClaw Anthropic-compatible | `https://api.clomio.ai` | `https://sub.qazwc.com` | `https://crs.qazwc.com` | | Hermes/OpenClaw OpenAI-compatible | `https://api.clomio.ai/v1` | `https://sub.qazwc.com/v1` | `https://crs.qazwc.com/v1` | | Gemini 原生 | `https://api.clomio.ai` + `/v1beta/...` | `https://sub.qazwc.com` + `/v1beta/...` | `https://crs.qazwc.com` + `/v1beta/...` | | Antigravity | `https://api.clomio.ai` + `/antigravity/...` | `https://sub.qazwc.com` + `/antigravity/...` | `https://crs.qazwc.com` + `/antigravity/...` | 换线路不等于换协议:不要因为换了域名就增删 `/v1`。Key 分组和模型名也不会因为换线路而改变。 线路只影响**域名和网络路径**,不改变 API 前缀:模型网关按协议走 `/v1`、`/v1beta` 或 `/antigravity/...`;控制台网页自己的用户 API 仍是前端访问 `/api/v1/...`。不要把控制台 JWT 接口和模型网关 API Key 接口混在一起。 ## 怎么换线路 换线路 = 把工具配置里的**地址(Base URL)**换成另一条,密钥不用动。 **Claude Code** —— 改 `ANTHROPIC_BASE_URL`: ```bash export ANTHROPIC_BASE_URL="https://crs.qazwc.com" ``` 或写进 `~/.claude/settings.json` 的 `env.ANTHROPIC_BASE_URL`。 **Codex** —— 改 `~/.codex/config.toml` 里 provider 的 `base_url`: ```toml [model_providers.clomio] base_url = "https://crs.qazwc.com/v1" ``` **Grok / OpenAI-compatible 客户端** —— 把 Base URL 换成对应线路(OpenAI-compatible 接口在末尾加 `/v1`,如 `https://crs.qazwc.com/v1`)。 **Hermes / OpenClaw** —— 看你选择的协议模式: - OpenAI-compatible / `openai-responses` / `openai-completions`: `https://crs.qazwc.com/v1` - Anthropic-compatible / `anthropic-messages`: `https://crs.qazwc.com` 改完重开终端(或重启工具)生效。 ## curl 快速测线路 只测网络和鉴权可先拉模型列表(OpenAI-compatible,带 `/v1`): ```bash for base in https://api.clomio.ai https://sub.qazwc.com https://crs.qazwc.com; do echo "== $base" curl -sS -o /dev/null -w "%{http_code} %{time_connect}s %{time_starttransfer}s\n" \ "$base/v1/models" \ -H "Authorization: Bearer 你的密钥" done ``` 同一把 Key 也可以用 `/v1/usage` 快速看网关鉴权、额度和限速状态；这个端点用于自助对账,不会触发模型调用计费： ```bash curl https://crs.qazwc.com/v1/usage \ -H "Authorization: Bearer 你的密钥" ``` 不用 Key 时,`GET /v1/models` 返回 **401 JSON** 也代表已经打到模型网关,不是线路坏: ```bash curl -i https://api.clomio.ai/v1/models curl -i https://sub.qazwc.com/v1/models curl -i https://crs.qazwc.com/v1/models ``` 当前可用的识别方式: - `api.clomio.ai`:直连网关,响应常见 `server: nginx`。 - `sub.qazwc.com`:Cloudflare 线路,响应常见 `server: cloudflare`、`cf-ray`。 - `crs.qazwc.com`:三网优化线路,以 `GET /v1/models` 的 401/JSON 和 `x-request-id` 判断是否到达网关。 不要用 `HEAD /v1/models` 或 `/nginx-health` 泛化判断线路可用性;不同线路和代理层对 HEAD/健康检查路径的处理可能不同。排障时记录 HTTP 状态码、响应体、`x-request-id` / `x-client-request-id`;Cloudflare 线路再记录 `cf-ray`。 测 Claude/Anthropic 协议时,配置里的 Base URL 虽然不带 `/v1`,curl 仍要请求真实端点 `/v1/messages`: ```bash curl https://crs.qazwc.com/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' ``` 测 Gemini 原生和 Antigravity 时,Base URL 填线路根地址,请求路径自带 `/v1beta` 或 `/antigravity/...`: ```bash curl https://crs.qazwc.com/v1beta/models \ -H "Authorization: Bearer 你的密钥" curl https://crs.qazwc.com/antigravity/v1/models \ -H "Authorization: Bearer 你的密钥" ``` --- ## 和"切换分组"的区别 - **换线路**:解决网络层面的卡顿 / 不稳定,改的是 **Base URL**。 - **换分组**:改变可用模型与计费倍率,在控制台给密钥重新选分组。 - **换模型**:在工具里用 `/model`,改的是这次对话用哪个模型。 三者互不影响。卡顿先换线路;想要更便宜或不同模型才动分组 / `/model`。不要用 Claude 分组 Key 调 OpenAI `/v1/responses`;Claude Code 推荐使用 Claude/Anthropic 分组 Key。OpenAI/Grok 分组在当前分组开放 Messages 兼容能力时也可走兼容桥。这类错误通常表现为 401、404、`model not found` 或“当前平台不支持该端点”。 --- > 线路状态可在控制台 [api.clomio.ai](https://api.clomio.ai) 查看;若某条线路集体异常,换另一条即可。 ## 相关文档 - [Base URL 与 /v1 规则](#/base-url-matrix)：确认每类客户端该填根地址还是 `/v1` 地址。 - [Claude Code](#/claude-code)：`ANTHROPIC_BASE_URL` 使用不带 `/v1` 的线路根地址。 - [Codex 配置详解](#/codex-config)：Codex provider 的 `base_url` 使用带 `/v1` 的 OpenAI-compatible 地址。 - [故障排查](#/troubleshooting)：区分线路问题、分组问题、模型问题和上游限速。 --- # Base URL 与 /v1 规则 不同工具的“Base URL”含义不完全一样。最常见的错误就是把 `/v1` 多加或少加一层,导致 404、401、模型不存在或工具测试通过但真实调用失败。 --- ## 先看结论 | 场景 | Base URL 填法 | 密钥字段 | 说明 | |------|------|------|------| | OpenAI SDK / Cherry Studio(OpenAI-compatible) | `https://api.clomio.ai/v1` | `Authorization: Bearer sk-...` | SDK 会继续拼 `/chat/completions`、`/responses`、`/images/*` | | Claude Code / Anthropic SDK | `https://api.clomio.ai` | `ANTHROPIC_AUTH_TOKEN=sk-...` | Claude 会请求 `/v1/messages`；不要在 base 后再加 `/v1` | | Codex 自定义 provider | `https://api.clomio.ai/v1` | `env_key = "CLOMIO_API_KEY"` | Codex 走 Responses wire API，最终请求 `/v1/responses` | | Grok CLI(xAI 兼容) | `https://api.clomio.ai/v1` | `XAI_API_KEY=sk-...` / `GROK_MODELS_BASE_URL` | 当前镜像优先使用 `GROK_MODELS_BASE_URL` 与 `~/.grok/config.toml` 的 `models_base_url`;旧包装器可能用 `GROK_BASE_URL/GROK_API_KEY` | | Hermes OpenAI-compatible | `https://api.clomio.ai/v1` | `key_env` / `.env` | `api_mode: chat_completions` 或 `codex_responses`;同一槽位写 `base_url` 会覆盖 provider 内置地址 | | Hermes Anthropic-compatible | `https://api.clomio.ai` | `key_env` / `.env` | `api_mode: anthropic_messages` | | OpenClaw OpenAI-compatible | `https://api.clomio.ai/v1` | `apiKey` | `api: "openai-completions"` 或 `openai-responses` | | OpenClaw Anthropic-compatible | `https://api.clomio.ai` | `apiKey` | `api: "anthropic-messages"` | | Gemini SDK/CLI 原生兼容 | `https://api.clomio.ai` | `Authorization: Bearer sk-...` | 客户端会请求 `/v1beta/models...`;需要 Google/Gemini 分组;详见 [Gemini 原生兼容](#/api-gemini) | | Antigravity 专用入口 | `https://api.clomio.ai` | `Authorization: Bearer sk-...` | 请求路径自带 `/antigravity/v1...` 或 `/antigravity/v1beta...`;详见 [Antigravity 接入](#/antigravity) | 线路域名可替换为 `https://sub.qazwc.com` 或 `https://crs.qazwc.com`；规则相同:OpenAI-compatible / Codex / Grok / Hermes/OpenClaw OpenAI-compatible 加 `/v1`,Claude Code / Anthropic-compatible 不加。Gemini 原生兼容和 Antigravity 专用入口的路径本身已经包含 `/v1beta` 或 `/antigravity/v1...`,Base URL 填线路根地址即可。 --- ## 为什么会这样 - **OpenAI-compatible 客户端**通常把 base URL 当成 API 版本根,例如 `https://api.clomio.ai/v1`,再自动拼 `/responses` 或 `/chat/completions`。 - **Anthropic / Claude Code**通常把 base URL 当成服务根,自己拼 `/v1/messages`。 - **Codex**当前自定义 provider 面向 Responses API,建议按 OpenAI-compatible 写 `.../v1`。 网关同时支持带 `/v1` 的规范路径和省略 `/v1` 的兼容形式。文档统一展示 `/v1/...` 便于跨客户端对照；使用根路径兼容形式时，必须确认返回的是 API 响应而不是站点 HTML，且不要把同一层 `/v1` 重复拼接，例如 Base URL 已是 `.../v1` 时不要再把 endpoint 写成 `/v1/v1/responses`。 ## Base URL、完整端点、Full URL 模式不要混用 常规 Base URL 是“让客户端继续拼路径”的地址:OpenAI-compatible 填 `https://api.clomio.ai/v1`,客户端再拼 `/responses` 或 `/chat/completions`;Anthropic-compatible 填 `https://api.clomio.ai`,客户端再拼 `/v1/messages`。完整端点则已经包含最终路径,例如 `https://api.clomio.ai/v1/messages` 或 `https://api.clomio.ai/v1/responses`。 只有工具明确提供 Full URL / 完整端点模式时才填完整端点。Clomio 常规接入不推荐 Full URL 模式；如果普通 Base URL 和 Full URL 模式混用,最容易出现 `/v1/v1/...`、少 `/v1`、或工具检测路径与真实调用路径不同。 - Hermes:看当前槽位的 `provider + model + base_url + api_mode`;写了 `base_url` 就按该 URL 直连。 - OpenClaw:完整 `api` 枚举很多,但 Clomio 常用只选 `anthropic-messages`、`openai-completions`、`openai-responses`;`provider/model` 的 provider 前缀参与 OpenClaw 路由,不一定原样发给上游。 - CC Switch:Full URL / 完整 URL 是高级例外；Clomio 常规 Claude 填服务根,OpenAI/Codex/Grok 填版本根。 --- ## Key 分组与端点匹配 Clomio 的路由会按 API Key 绑定的分组判断平台能力。先选 Key/分组,再选 Base URL 和端点: | Key 分组 / 平台 | 可用客户端协议 | Base URL | 典型端点 | 注意 | |---|---|---|---|---| | Claude / Anthropic | Claude Code、Anthropic-compatible | `https://api.clomio.ai` | `/v1/messages`, `/v1/messages/count_tokens` | Base URL 不带 `/v1`;模型名用 Claude 分组开放列表。 | | OpenAI / Codex | OpenAI-compatible、Codex Responses | `https://api.clomio.ai/v1` | `/v1/responses`, `/v1/chat/completions`, `/v1/images/*`, `/v1/embeddings` | Images 支持 OpenAI;Embeddings 走 OpenAI;Messages 只有当前分组开放兼容能力时才可走兼容桥。 | | Grok / xAI | Grok CLI、Grok Responses/Chat、Web Search、Images、Videos、Voice | `https://api.clomio.ai/v1` | `/v1/responses`, `/v1/chat/completions`, `/v1/messages`, `/v1/web_search`, `/v1/images/*`, `/v1/videos/*`, `/v1/tts`, `/v1/stt`, `/v1/realtime` | Voice、Web Search、Videos 仅 Grok；Messages 需要分组开放 ingress 能力。 | | Gemini | Gemini SDK/CLI 原生兼容 | `https://api.clomio.ai` | `/v1beta/models`, `/v1beta/models/{model}`, `/v1beta/models/{model}:generateContent` | 不带 `/v1`;Google 风格鉴权和错误体。 | | Antigravity | Antigravity 专用 Anthropic/Gemini 形态 | `https://api.clomio.ai` | `/antigravity/v1/messages`, `/antigravity/v1beta/models...` | 强制 Antigravity 分组和账户。 | 能力边界按实际场景记: - **Videos 仅 Grok**:OpenAI/Claude Key 调 `/v1/videos/*` 会被拒绝。 - **Images 支持 OpenAI/Grok**:用控制台开放的图片模型名,不要拿 Claude Key 调图片端点。 - **Embeddings 走 OpenAI**:用 OpenAI/Codex 分组 Key。 - **Web Search 仅 Grok**:用 Grok 分组 Key。 - **Messages 是 Claude 主协议**:Claude 分组直接支持;OpenAI/Grok 分组只有当前分组开放兼容能力时才可走兼容桥。 常见反例: - `https://api.clomio.ai/v1/v1/models`:Base URL 已带 `/v1`,客户端又拼了一次,删掉其中一层。 - Claude Code 配 `https://api.clomio.ai/v1`:错误;应填 `https://api.clomio.ai`。 - OpenAI SDK / Codex 配 `https://api.clomio.ai`:通常错误;应填 `https://api.clomio.ai/v1`。 - 用 Claude 分组 Key 调 `/v1/responses`:换 OpenAI/Codex/Grok 分组 Key。Claude Code 推荐 Claude/Anthropic 分组;OpenAI/Grok 分组只有在允许 Messages ingress 时才可走 `/v1/messages`。 - 非 Grok 分组调 `/v1/videos`:会被网关拒绝,Videos 仅 Grok。 ## 快速自检 ### OpenAI-compatible / Codex / Grok ```bash curl https://api.clomio.ai/v1/models \ -H "Authorization: Bearer 你的密钥" ``` Responses 快测: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.5","input":"ping","max_output_tokens":1}' ``` Grok Videos 只用 Grok 分组 Key 和控制台显示的视频模型 ID 测;非 Grok 分组会被网关拒绝: ```bash curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的Grok分组密钥" \ -H "content-type: application/json" \ -d '{"model":"控制台显示的视频模型ID","prompt":"one second test"}' ``` ### Anthropic-compatible ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}' ``` ### Gemini 原生兼容 ```bash curl https://api.clomio.ai/v1beta/models \ -H "Authorization: Bearer 你的Gemini分组密钥" ``` ### Antigravity 专用入口 ```bash curl https://api.clomio.ai/antigravity/v1/models \ -H "Authorization: Bearer 你的Antigravity分组密钥" ``` 如果 curl 能通,但工具仍报错,优先检查工具实际读取的配置文件和环境变量,不要只看第三方工具 UI 的“测试通过”。测试按钮只代表它测的那条路径:通过不代表所有端点能力可用,失败也不代表目标协议不可用。排查时同时记录 HTTP 状态码、响应体、`x-request-id` / `x-client-request-id`(如有),方便支持按请求定位。 --- ## 命令行工具接入 # Claude Code Anthropic 的终端编程助手,擅长理解需求、规划与改写代码。本页带你从安装到接上 Clomio。Claude Code 接网关时走 **Anthropic Messages API**:客户端把请求发到 `ANTHROPIC_BASE_URL + /v1/messages`,不是 OpenAI `/v1/responses`。 > 关键点: `ANTHROPIC_BASE_URL` 只填域名根地址,不要带 `/v1`。例如填 `https://api.clomio.ai`,不要填 `https://api.clomio.ai/v1`。 --- ## 一、安装 Claude Code ### 方式 A:镜像一键安装(推荐,无需 Node.js) 从 `help.clomio.ai` 镜像直连下载独立二进制,国内直连、不依赖 Node。 ```bash curl -fsSL https://help.clomio.ai/claude/install.sh | bash ``` Windows PowerShell: ```powershell irm https://help.clomio.ai/claude/install.ps1 | iex ``` ### 方式 B:npm 全局安装 需要先装好 [Node.js 环境](#/nodejs)。 ```bash npm install -g @anthropic-ai/claude-code ``` macOS / Linux 遇权限问题加 `sudo`。 ### 验证与更新 ```bash claude --version claude doctor claude update ``` 输出版本号即安装成功。`claude update` 会自行检查并更新到最新版;镜像安装也可以按当前系统重跑 `install.sh` 或 `install.ps1`,npm 安装也可以 `npm install -g @anthropic-ai/claude-code@latest`。 --- ## 二、获取密钥 在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个可用于 Claude Code 的 API Key。建议选择 **Claude/Anthropic 平台分组**；如果使用 OpenAI 平台分组，只有该分组明确开放 `/v1/messages` 兼容能力时才适合 Claude Code，否则会被网关拒绝。 注意两类常见限制: - **未分组 Key**：生产使用不建议空分组；如果 Key 未绑定分组，常见表现是 403 或 key 未分配分组提示。 - **Claude Code only 分组**：这类分组只适合真实 Claude Code 客户端；非 Claude Code 请求可能会被拒绝。 详见 [创建 API 密钥](#/api-key)。 --- ## 三、接上 Clomio Claude Code 通过 `ANTHROPIC_BASE_URL` 指向网关,通过凭据变量带上你的 key。 | 设置项 | 推荐值 | 说明 | |--------|--------|------| | `ANTHROPIC_BASE_URL` | `https://api.clomio.ai` | 只填根地址,不带 `/v1` | | `ANTHROPIC_AUTH_TOKEN` | 你的 Clomio 密钥 | 发送为 `Authorization: Bearer ...`,Clomio 推荐用这个 | | `ANTHROPIC_API_KEY` | 仅在网关要求 `x-api-key` 时使用 | 发送为 `x-api-key: ...`,不要和 `ANTHROPIC_AUTH_TOKEN` 混用 | > 地址可换成另外两条线路(`https://sub.qazwc.com` 或 `https://crs.qazwc.com`),国内通常更稳。见 [网关线路](#/gateway-lines)。 ### 方式 A:写入配置文件(推荐,重启不丢) 把下面内容写进 `~/.claude/settings.json`(Windows 为 `%USERPROFILE%\.claude\settings.json`): ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.clomio.ai", "ANTHROPIC_AUTH_TOKEN": "你的密钥", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" } } ``` 如果是项目专用密钥,放在 `<项目>/.claude/settings.local.json`,并确认该文件已加入 `.gitignore`。 如果“改了配置但仍走旧地址/旧 key”,不要只看一个文件。按这个顺序查实际来源: ```bash # Claude Code 会话里先看 /status,确认 base URL 与凭据来源 claude # 进入后输入: /status # 如果发现仍在用旧 claude.ai 登录或旧网关,可先 /logout 再重新启动 # 退出后在同一个终端查环境与配置文件 env | grep -E 'ANTHROPIC|CLAUDE' cat ~/.claude/settings.json cat .claude/settings.local.json 2>/dev/null ``` 用户级、项目级、本地 `settings.local.json`、企业托管设置、shell `export`、CC Switch 写入都可能参与最终环境。最终以 `/status` 显示的 Anthropic base URL、Auth token/API key 来源为准。 ### 方式 B:环境变量 **临时(仅当前终端):** ```bash export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的密钥" ``` **永久(macOS / zsh):** ```bash echo 'export ANTHROPIC_BASE_URL="https://api.clomio.ai"' >> ~/.zshrc echo 'export ANTHROPIC_AUTH_TOKEN="你的密钥"' >> ~/.zshrc source ~/.zshrc ``` **永久(Windows / PowerShell):** ```powershell [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.clomio.ai", "User") [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "你的密钥", "User") ``` ### 方式 C:CC Switch 图形化 [CC Switch](https://github.com/farion1231/cc-switch) 是一个开源的供应商切换工具。安装后新增一个「自定义」供应商,请求地址填 `https://api.clomio.ai`、API Key 填你的密钥,启用即可。确认它最终写入的是根地址,不要额外拼 `/v1`。 ### Base URL 写错 `/v1` 的典型症状 Claude Code 官方网关变量是 `ANTHROPIC_BASE_URL`,客户端会在这个值后面自己拼 `/v1/messages`。如果误写成 `https://api.clomio.ai/v1`,实际请求会变成 `/v1/v1/messages`,常见表现是 404、`Cannot POST /v1/v1/messages`、`/status` 里 base URL 带着 `/v1`,或 curl 手测根本打不到 `msg_` 响应。修正后重开终端/重启 Claude Code,再运行 `/status` 确认。 快速自检: ```bash printf '%s ' "$ANTHROPIC_BASE_URL" # 正确: https://api.clomio.ai # 错误: https://api.clomio.ai/v1 ``` 若怀疑旧 shell 或脚本污染,先清掉再只设置本次要用的两项: ```bash unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的密钥" ``` 如果 `/status` 仍显示旧登录方式,在 Claude Code 内执行 `/logout`,退出后重新打开终端再启动。`ANTHROPIC_AUTH_TOKEN` 会走 `Authorization: Bearer ...`;`ANTHROPIC_API_KEY` 会走 `x-api-key: ...`。Clomio 常规网关 Key 推荐只保留 `ANTHROPIC_AUTH_TOKEN`,不要两种凭据长期同时存在。 --- ## 四、先用 curl 验证网关 在打开 Claude Code 前先测一次 Anthropic Messages API。成功能把网络、base URL、key、分组问题先排掉。 ```bash curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` 看到 `id` 以 `msg_` 开头、并有 `content` 字段,说明网关可达且鉴权通过。若你的网关/工具要求 `ANTHROPIC_API_KEY`,把请求头换成: ```bash -H "x-api-key: $ANTHROPIC_API_KEY" ``` --- ## 五、开始使用 进入任意项目目录,运行: ```bash claude ``` 第一次有初始化引导,一路回车用默认即可。进去后输入: ```text 你现在用的是什么模型? 请只回答模型名。 ``` 再运行 `/status`,确认能看到 `Anthropic base URL: https://api.clomio.ai` 以及 `Auth token` 或 `API key` 来源。 --- ## 常见问题 **`claude` 提示命令找不到?** npm 全局目录可能没在 `PATH` 里,或需重开终端。见 [故障排查](#/troubleshooting)。 **报 401 / 鉴权失败?** 先确认 `ANTHROPIC_BASE_URL` 没带 `/v1`;再确认使用的是 `ANTHROPIC_AUTH_TOKEN` 还是 `ANTHROPIC_API_KEY`。Clomio 常规 key 推荐放 `ANTHROPIC_AUTH_TOKEN`,对应 `Authorization: Bearer`。 **`/status` 显示的凭据不是你刚设置的?** 先 `env | grep ANTHROPIC`,再查 `~/.claude/settings.json`、项目 `.claude/settings.local.json` 和 CC Switch 写入项。必要时 `/logout` 清旧登录,并只保留 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`。 **报 403 且提示 key 未分组?** 去控制台把 API Key 绑定到可用分组；生产环境不建议使用未分组 Key。 **报 `This group does not allow /v1/messages dispatch`?** 你的 Key 绑定到了 OpenAI 平台分组,但该分组未开放 Claude Code 所需的 `/v1/messages` 兼容能力。换 Claude/Anthropic 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组。 **Claude Code 主路径是哪条?** Claude Code 主对话是 `POST /v1/messages`;`POST /v1/messages/count_tokens` 只是 token 估算。Codex/OpenAI 的 `POST /v1/responses` 不要写成 Claude Code 主路径。 **`count_tokens` 404?** Claude Code 会请求 `/v1/messages/count_tokens` 做上下文估算。sub2api 对 OpenAI/Grok 分组会返回 404;对不支持 count_tokens 的上游也会返回 404 让客户端本地估算。只要 `/v1/messages` 正常,通常不影响主对话。 **MCP 工具很多但 tool search 不工作?** 官方 Claude Code 在自定义 `ANTHROPIC_BASE_URL` 下默认会关闭 MCP tool search。若你的网关能透传 `tool_reference` beta 块,可设置 `ENABLE_TOOL_SEARCH=true`;否则保持默认或设 `ENABLE_TOOL_SEARCH=false/auto` 更稳。见 [Claude Code 进阶](#/claude-advanced)。 **卡顿或偶发不可用?** 去控制台给密钥换一个分组/节点,或换 [网关线路](#/gateway-lines) 后重试。 **GitHub Action/CI 里接网关不生效?** 先确认 action/runner 版本是否支持传入 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 或等价环境变量。社区里有 claude-code-action 通过 LLM Gateway 的讨论,不同版本支持面可能不同;把它当作版本排查项,不要假定所有 action 都会读取你本机的 `~/.claude/settings.json`。如果主对话走了网关,但评论分类、安全指导、advisor 或 VS Code 扩展仍直连官方/报 403,优先升级相关组件并检查该路径是否转发了同一组 env。 --- ## 官方/社区经验来源 - [Anthropic: Other LLM gateways](https://docs.anthropic.com/en/docs/claude-code/llm-gateway):网关要暴露 Anthropic-format endpoint,且只设置 `ANTHROPIC_BASE_URL` 不等于替换登录凭据。 - [Anthropic: Settings](https://docs.anthropic.com/en/docs/claude-code/settings):用户/项目/本地/托管设置的层级与 `/status` 校验方式。 - [Anthropic: Corporate proxy](https://docs.anthropic.com/en/docs/claude-code/corporate-proxy):企业代理与 LLM Gateway 可以同时存在,代理变量会影响所有出站请求。 - [claude-code-action LLM Gateway discussion](https://github.com/anthropics/claude-code-action/discussions/272):CI/Action 接网关时优先核对 action 版本和 env 传递,作为版本相关排查项。 - [claude-code-action issue #1418](https://github.com/anthropics/claude-code-action/issues/1418):某些 action 辅助路径曾出现硬编码官方 URL 的版本相关问题;若只有部分 CI 步骤绕过网关,先升级并查该 issue 类似症状。 - [Claude Code issue #9010](https://github.com/anthropics/claude-code/issues/9010):VS Code 扩展曾有不继承自定义 LLM Gateway 配置的报告;CLI 正常而扩展异常时,按扩展版本/设置来源排查。 - [@rauchg 的 Vercel AI Gateway 示例](https://x.com/rauchg/status/2007556249437778419):公开社区经验也采用 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` 的网关接法;迁移到 Clomio 时仍按本文的“不带 `/v1` 根地址”规则。 - [MLflow Gateway + Claude Code 公开示例](https://x.com/MLflow/status/2057915356950172076):把 Claude Code 指向 Anthropic-format gateway/proxy;若 CLI 正常但辅助路径异常,继续按 env 继承与版本差异排查。 --- # Claude Code 配置详解 Claude Code 的行为由 `settings.json`、环境变量和登录凭据共同决定。本页解释接入 Clomio 最常用的字段。你不需要全配,挑需要的加即可。 --- ## 配置文件在哪、谁优先 `settings.json` 会从多个位置读取并合并,常见优先级从低到高: | 位置 | 作用域 | 说明 | |------|--------|------| | `~/.claude/settings.json` | 用户级 | 你的个人默认,所有项目生效 | | `<项目>/.claude/settings.json` | 项目级 | 该项目专属,可随仓库共享,不要放密钥 | | `<项目>/.claude/settings.local.json` | 本地 | 个人本地覆盖,放密钥用这个,记得加进 `.gitignore` | | 托管设置(企业) | 最高 | 企业策略强制,用户/项目都改不了 | > 用 `/config` 命令可在界面里查看和改设置;新版也支持 `/config verbose=true` 这类单项修改。实际生效的 base URL 和凭据来源请用 `/status` 看。 --- ### 设置与 shell 环境谁覆盖谁 官方配置层级里,托管设置最高,然后是命令行、本地、项目、用户设置;权限规则会合并,普通标量设置按高优先级覆盖低优先级。`settings.json` 的 `env` 会注入 Claude Code 会话和它启动的子进程,但你从某个 shell 直接启动 `claude` 时,本机 shell 里已有的 `ANTHROPIC_*` 也会参与最终环境。排障时不要只看文件,要同时看当前进程环境和 `/status`。 建议顺序: 1. 团队共享值放 `<项目>/.claude/settings.json`,不要放密钥。 2. 个人密钥放 `<项目>/.claude/settings.local.json` 或用户级 `~/.claude/settings.json`。 3. 临时排障用 shell `export`,结束后 `unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY` 避免覆盖文件配置。 4. 最终以 Claude Code 内 `/status` 显示的 base URL 与凭据来源为准。 ## 核心字段 ### `env` —— 环境变量(接入 Clomio 就在这里) `env` 里的变量会注入 Claude Code 进程,也是配置网关的地方。Clomio 推荐最小配置: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.clomio.ai", "ANTHROPIC_AUTH_TOKEN": "你的密钥", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" } } ``` 重点规则: - `ANTHROPIC_BASE_URL` 只填根地址,例如 `https://api.clomio.ai`;Claude Code 会自己请求 `/v1/messages` 和 `/v1/messages/count_tokens`。 - `ANTHROPIC_AUTH_TOKEN` 会发送为 `Authorization: Bearer `,适合大多数 Clomio/网关 key。 - `ANTHROPIC_API_KEY` 会发送为 `x-api-key: `,适合明确要求 Anthropic Console key 或 `x-api-key` 的网关。 - 两者同时存在时,官方认证链路会按活跃登录/网关 token/API key 规则选择;为减少误判,日常只保留一种网关凭据,并用 `/status` 确认。 - 只有 `ANTHROPIC_BASE_URL` 而没有网关凭据时,已保存的 claude.ai 登录仍可能成为活跃凭据。用 `/status` 确认当前是否真的在用 Clomio key。 常用环境变量: | 变量 | 作用 | |------|------| | `ANTHROPIC_BASE_URL` | 网关根地址,指向 Clomio(可换[线路](#/gateway-lines)),不要带 `/v1` | | `ANTHROPIC_AUTH_TOKEN` | Clomio key 推荐放这里,走 `Authorization: Bearer` | | `ANTHROPIC_API_KEY` | 直连 Anthropic Console 或网关要求 `x-api-key` 时使用 | | `ANTHROPIC_CUSTOM_HEADERS` | 给网关追加自定义头,多行用 `\n` 分隔 | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设 `1` 关闭非必要的遥测/辅助请求,更干净也更省流量 | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设 `1` 后从网关 `/v1/models` 补充 `/model` 选择器 | | `ENABLE_TOOL_SEARCH` | 控制 MCP tool search;自定义 base URL 下默认会退回非 tool-search 模式 | | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 网关/上游不兼容新版 beta 字段时报错时可设 `1` 降低请求复杂度 | | `CLAUDE_CODE_SUBAGENT_MODEL` | 子代理使用的模型(可与主模型不同) | | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 设 `1` 开启实验性的代理团队能力 | ### `model` —— 默认模型 ```json { "model": "claude-sonnet-4-6" } ``` 填模型 ID 或官方 alias。`ANTHROPIC_BASE_URL` 只改变请求发往哪里,不改变模型名本身。可用模型以 Clomio 分组/账号实际开放为准;会话里也可随时用 `/model` 切换。 如果你希望 `/model` 面板显示网关返回的模型,可以加: ```json { "env": { "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" } } ``` ### `permissions` —— 权限护栏 控制哪些工具调用需要确认。三个数组 `deny` / `ask` / `allow`,按 deny → ask → allow 顺序匹配,先命中者生效: ```json { "permissions": { "allow": ["Bash(git*)", "Read"], "ask": ["Bash(rm*)"], "deny": ["Read(./.env)", "Read(./secrets/**)"], "additionalDirectories": ["../shared-lib"] } } ``` - `allow`:跳过确认直接执行(配好常用命令能少弹很多次授权) - `ask`:每次询问,适合删除、部署、数据库修改 - `deny`:直接拒绝,从不执行(护住密钥文件、敏感目录) - `additionalDirectories`:授予项目根目录以外的访问权(monorepo 常用) ### `apiKeyHelper` —— 动态取 key 如果网关 key 会轮换,可以用脚本输出凭据: ```json { "apiKeyHelper": "~/bin/get-clomio-key.sh" } ``` Claude Code 会调用脚本取 key,默认缓存一段时间并在 401 后重试获取。helper 输出的值会同时适配常见 key/token 场景,适合企业内部分发。 --- ## 一份 Clomio 推荐配置 ```json { "$schema": "https://json.schemastore.org/claude-code-settings.json", "env": { "ANTHROPIC_BASE_URL": "https://api.clomio.ai", "ANTHROPIC_AUTH_TOKEN": "你的密钥", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "ENABLE_TOOL_SEARCH": "auto", "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6" }, "model": "claude-sonnet-4-6", "language": "chinese", "theme": "dark-daltonized", "verbose": true, "autoUpdatesChannel": "stable", "cleanupPeriodDays": 30 } ``` > 把密钥写进会进 git 的文件有泄露风险,个人密钥建议放 `settings.local.json` 或 shell secret 管理器。完整且最新字段以 [官方 settings 文档](https://docs.anthropic.com/en/docs/claude-code/settings) 和 [LLM gateway 文档](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) 为准。 --- ## 体验类字段 下面这些控制交互体验,按喜好配: ```json { "language": "chinese", "theme": "dark-daltonized", "alwaysThinkingEnabled": true, "showThinkingSummaries": true, "effortLevel": "high", "verbose": true, "showTurnDuration": true, "spinnerTipsEnabled": false, "feedbackSurveyRate": 0, "autoUpdatesChannel": "stable", "skipDangerousModePermissionPrompt": true, "teammateMode": "auto", "cleanupPeriodDays": 30, "attribution": { "commit": "", "pr": "" } } ``` 字段会随 Claude Code 版本增减。如果编辑器支持 schema,在文件顶部加: ```json "$schema": "https://json.schemastore.org/claude-code-settings.json" ``` 即可获得自动补全与校验。 --- ## `count_tokens` 与分组兼容 Claude Code 会把主请求发到 `/v1/messages`,并可能额外调用 `/v1/messages/count_tokens` 估算上下文。Clomio/sub2api 的当前行为是: - Claude/Anthropic 分组:转发或按上游能力处理 `count_tokens`。 - OpenAI 分组:只有当前分组开放 Messages 兼容能力时才能兼容 `/v1/messages`;`count_tokens` 返回 404,客户端本地估算。 - Grok 分组:是否支持 Messages 由分组能力决定；`count_tokens` 固定返回 404，主请求仍可正常使用。 因此只要 `/v1/messages` 能正常对话,单独的 `count_tokens` 404 通常可以忽略；如果主对话也失败，再检查 Key 分组是否支持 Messages。 ## 配置排障顺序 1. `echo $ANTHROPIC_BASE_URL` 确认是 `https://api.clomio.ai`,没有 `/v1`。 2. `env | grep ANTHROPIC_` 确认只保留一种凭据变量。 3. 用 `curl "$ANTHROPIC_BASE_URL/v1/messages" ...` 验证网关与 key。 4. 启动 `claude`,运行 `/status`,看 `Anthropic base URL` 与 `Auth token/API key` 来源。 5. 若 MCP 工具异常,先设 `ENABLE_TOOL_SEARCH=false` 或 `auto`;确认网关支持 `tool_reference` 后再设 `true`。 ### 官方经验转成的配置检查表 - `ANTHROPIC_BASE_URL` 只负责把请求送到网关;没有 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 时,本机保存的 claude.ai 登录仍可能是活跃凭据。 - 托管设置高于命令行、本地、项目和用户设置;如果企业/MDM 下发了 `managed-settings.json`,用户侧改文件不会生效。 - `HTTPS_PROXY`、`HTTP_PROXY`、`SSL_CERT_FILE`、`NODE_EXTRA_CA_CERTS` 这类企业代理/证书变量会影响 Claude Code 访问网关、MCP 和更新检查;排障时与 `ANTHROPIC_*` 一起核对。 - GitHub Action、VS Code 扩展、advisor/security hooks 这类辅助路径不一定和 CLI 主会话使用同一套环境。若 `claude` 主会话正常但 CI/扩展/辅助审查直连官方或报 403,先检查版本、action `settings.env`、runner env 是否把 `ANTHROPIC_BASE_URL` 和凭据都传进去。 - `ANTHROPIC_AUTH_TOKEN` 与 `ANTHROPIC_API_KEY` 不要长期同时保留。Clomio 推荐 bearer token 形态就放 `ANTHROPIC_AUTH_TOKEN`;要求 `x-api-key` 的 Anthropic-compatible 网关才用 `ANTHROPIC_API_KEY`。 - 模型名、子代理模型和 `/model` 候选以 Clomio 控制台分组实际开放为准;网关 base URL 不会自动把 GPT/Grok 模型变成 Claude 模型。 ## 参考资料 - [Anthropic Claude Code Settings](https://docs.anthropic.com/en/docs/claude-code/settings) - [Anthropic Other LLM gateways](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) - [Anthropic Corporate proxy](https://docs.anthropic.com/en/docs/claude-code/corporate-proxy) - [claude-code-action hardcoded base URL issue](https://github.com/anthropics/claude-code-action/issues/1418) - [Claude Code VS Code custom gateway issue](https://github.com/anthropics/claude-code/issues/9010) 更多用法见 [Claude Code 进阶](#/claude-advanced)。 --- # Codex OpenAI 的终端编程助手,擅长执行任务、排查问题、动手解决。 --- ## 一、安装 Codex ### 方式 A:镜像一键安装(推荐,无需 Node.js) ```bash curl -fsSL https://help.clomio.ai/codex/install.sh | bash ``` Windows PowerShell: ```powershell irm https://help.clomio.ai/codex/install.ps1 | iex ``` ### 方式 B:npm 全局安装 需要先装好 [Node.js 环境](#/nodejs)。 ```bash npm install -g @openai/codex@latest ``` macOS / Linux 遇权限问题加 `sudo`。 ### 验证 ```bash codex --version ``` 输出版本号即安装成功。 ### 更新到最新版 ```bash # 镜像安装的:重跑一次安装命令即更新 curl -fsSL https://help.clomio.ai/codex/install.sh | bash # npm 安装的:重装 @latest npm install -g @openai/codex@latest ``` Windows 镜像安装的更新命令: ```powershell irm https://help.clomio.ai/codex/install.ps1 | iex ``` --- ## 二、获取密钥 在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个 **Codex / GPT 分组** 的密钥,详见 [创建 API 密钥](#/api-key)。 --- ## 三、接上 Clomio Codex 推荐用 `~/.codex/config.toml` 指向网关,密钥放在本机环境变量里。配置目录在 `~/.codex/`(Windows 为 `%USERPROFILE%\.codex\`)。 ### `~/.codex/config.toml` ```toml model_provider = "clomio" model = "gpt-5.4" model_reasoning_effort = "high" preferred_auth_method = "apikey" [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` > `model` 填你的分组实际开放的模型名,以控制台显示为准。`base_url` 需要带 `/v1`;`wire_api = "responses"` 是 Codex 接入网关的关键项,不要改。 > `base_url` 也可换成另外两条线路(`https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1`),国内通常更稳。见 [网关线路](#/gateway-lines)。 > 如果 Codex 出现 `Reconnecting...`、企业代理拦截 WebSocket Upgrade、或 WS 不稳定，先加 `supports_websockets = false` 回落 HTTP/SSE 验证；不要把 `base_url` 改成 `/v1/responses`。 > 如果你把 provider/base URL 复制到项目里的 `.codex/config.toml` 后不生效,请先移到用户级 `~/.codex/config.toml` 或 profile 文件；Codex 会忽略 project config 里的 provider/auth 类键。详见 [Codex 配置详解](#/codex-config)。 > 控制台「使用 Key」弹窗为了复制即用,可能给出 `experimental_bearer_token` + `requires_openai_auth = true` 的自包含模板。长期推荐仍是本页的 `env_key = "CLOMIO_API_KEY"` 环境变量写法。两种认证方式不要混用:如果从弹窗模板切到环境变量,请删除 `experimental_bearer_token` 和 `requires_openai_auth`。 ### 设置密钥环境变量 把 `你的密钥` 换成控制台复制的密钥。Codex 会按上面配置的 `env_key = "CLOMIO_API_KEY"` 读取这个变量。 **macOS / Linux:** ```bash export CLOMIO_API_KEY="你的密钥" # 想长期生效可写入 ~/.zshrc 或 ~/.bashrc ``` **Windows(PowerShell):** ```powershell $env:CLOMIO_API_KEY = "你的密钥" # 想长期生效: [Environment]::SetEnvironmentVariable("CLOMIO_API_KEY", "你的密钥", "User") ``` ### 用命令快速创建配置目录 **macOS / Linux:** ```bash mkdir -p ~/.codex ``` **Windows(PowerShell):** ```powershell mkdir "$env:USERPROFILE\.codex" -Force ``` 然后用编辑器把上面的 `config.toml` 放进去,并设置好 `CLOMIO_API_KEY` 环境变量即可。 ### 先用 curl 验证 Responses 在打开 Codex 前,先用同一把 key 和同一个模型测网关。这样可以把“网关/key/model 问题”和“Codex 配置读取问题”分开: ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer $CLOMIO_API_KEY" -H "content-type: application/json" -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` 看到 `id`、`output` 或流式事件结构,说明网关和 Key 可用;如果这里已经 401/404/`model_not_found`,先改 Key 分组、模型名或 Base URL,不要继续排 Codex 本地配置。 如果要确认 `GET /v1/responses` 不是 REST 查询接口,可以普通 GET 一次。支持 Responses WebSocket 的 OpenAI/Grok 分组预期结果是 426,表示“必须 WebSocket Upgrade”;未开放该能力的分组才会返回 404: ```bash curl -i https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $CLOMIO_API_KEY" # OpenAI/Codex 分组预期: 426 WebSocket upgrade required # 未开放 WS 的分组预期: 404 Responses WebSocket API is not supported for this platform ``` ### 或者:CC Switch 图形化 和 Claude Code 一样,[CC Switch](https://github.com/farion1231/cc-switch) 也能一键管理 Codex 的配置,把请求地址设为 `https://api.clomio.ai/v1`、填入密钥并启用即可。 --- ## 四、开始使用 进入任意项目目录,运行: ```bash codex ``` 第一次有初始化引导,一路回车用默认即可。进去后试几句: ```text 你现在用的是什么模型? ``` ```text 帮我看看当前文件夹里有什么 ``` 能正常进入交互界面、没有报错,就说明可以用了。 --- ## Codex 在 Clomio 上实际打哪些路径 Codex/OpenAI-compatible 接入的 base URL 必须是 `https://api.clomio.ai/v1`。Codex CLI 使用 Responses wire API,主请求是 `POST /v1/responses`;流式可以是 SSE,支持 WebSocket 的 provider 也可能升级到 `GET /v1/responses` 的 WS 入口。不要把 base URL 写成 `/v1/responses`,也不要写“按 response id 发 GET 查询历史”的路径。 如果你同时在用 Claude Code,注意两者不同: | 工具 | Base URL | 主路径 | |------|----------|--------| | Claude Code | `https://api.clomio.ai` | `POST /v1/messages` | | Codex | `https://api.clomio.ai/v1` | `POST /v1/responses` | ### 启用 Codex WS profile 只有确认客户端版本和当前网络都支持 Responses WebSocket v2 时才启用。控制台「Codex WS」模板会同时写两处开关:provider 下的 `supports_websockets = true`,以及 `[features].responses_websockets_v2 = true`。只写其中一个时,客户端可能仍走 HTTP/SSE。 ```toml model_provider = "clomio_ws" model = "gpt-5.4" preferred_auth_method = "apikey" [model_providers.clomio_ws] name = "clomio_ws" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" supports_websockets = true [features] responses_websockets_v2 = true ``` ### WS 不稳定时的 HTTP/SSE 回落 profile 如果终端反复 `Reconnecting...`，或公司网络/代理不允许 WebSocket Upgrade，先用这个配置确认普通 Responses/SSE 链路是否正常： ```toml model_provider = "clomio" model = "gpt-5.4" preferred_auth_method = "apikey" [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" supports_websockets = false ``` 确认 HTTP/SSE 正常后，再按网络环境决定是否恢复 WebSocket。无论是否启用 WS，`base_url` 都只写到 `/v1`。 ## 常见问题 **`codex` 提示命令找不到?** 见 [故障排查](#/troubleshooting)。 **连接失败 / 401?** 检查 `config.toml` 里 `base_url` 是否为 `https://api.clomio.ai/v1`、`CLOMIO_API_KEY` 环境变量里的密钥是否正确未过期、分组是否为 Codex/GPT。 **提示模型不存在?** `config.toml` 里的 `model` 必须是该分组实际开放的模型名,以控制台为准。 **改了配置但 Codex 还连旧地址?** 命令行 `-c key=value` / `--config`、`--profile`、受信任项目里的 `.codex/config.toml`、旧 `OPENAI_API_KEY` / `auth.json` 都可能覆盖你的用户级配置。按下面查: ```bash codex -c model_provider=clomio env | grep -E 'CLOMIO|OPENAI' find . -path '*/.codex/config.toml' -print grep -R "base_url\|model_provider\|env_key\|requires_openai_auth" ~/.codex ./.codex 2>/dev/null ``` Clomio 推荐 `env_key = "CLOMIO_API_KEY"`。如果用了 `requires_openai_auth = true`,Codex 可能改走 OpenAI 认证链路或旧 `auth.json`;不要和 `env_key` 长期混用。 **能否把 Grok/Claude 当 fallback 写进同一个 Codex provider?** 不建议。Codex provider 走 OpenAI-compatible Responses wire API;Claude/Anthropic Messages 是另一套协议。fallback 只在同协议、同 base URL 规则内切换,跨协议请新建对应工具配置。 **控制台里 OpenAI Key 出现 Claude Code tab 是不是 Codex fallback?** 不是。那表示该 OpenAI/Codex 分组额外开放 Claude Code 风格 `/v1/messages` 兼容入口。Codex CLI 自身仍应走 `/v1/responses`。 --- ## 官方参考资料 - [OpenAI Codex Config basics](https://developers.openai.com/codex/config-basic):用户级与受信任项目级配置、默认模型/provider 的基础写法。 - [OpenAI Codex Configuration reference](https://developers.openai.com/codex/config-reference):`model_provider`、`model_providers.*`、`env_key`、`wire_api` 等字段以这里为准。 - [OpenAI Codex Advanced config](https://developers.openai.com/codex/config-advanced):profile 文件和一次性 CLI 覆盖的推荐方式。 - [OpenAI Codex CLI reference](https://developers.openai.com/codex/cli/reference):命令行 `-c` 覆盖优先级和运行参数。 - [Codex 社区配置经验(X)](https://x.com/canghe/article/2060376680896799094):中转站/代理接入时,`base_url` 写到 `/v1` 即止,不要写成 `/v1/responses`。 - [Codex WS 排障经验(X)](https://x.com/mylifcc/status/2057308552738505031):出现 `Reconnecting...` 一类症状时,社区常用 `supports_websockets = false` 回落 HTTP/SSE;Clomio 上是否启用 WS 以 provider 配置和当前分组能力为准。 --- # Codex 配置详解 Codex 的行为由 `~/.codex/config.toml` 控制(Windows 为 `%USERPROFILE%\.codex\config.toml`)。本页解释常用字段——按需配置即可。 --- ## 配置在哪、谁优先 优先级从高到低:**命令行参数/`--config` 覆盖 → 项目级 `.codex/config.toml`(仅受信任项目,从项目根到当前目录逐层加载,越近越优先)→ profile 文件 → 用户级 `~/.codex/config.toml` → 系统配置 → 内置默认值**。 > 项目级配置只有在项目被 Codex 标记为 trusted 后才会加载;如果项目不受信任,项目内 `.codex/` 层、hooks、rules 都会跳过。团队仓库里不要提交密钥。项目级 `.codex/config.toml` 适合提交不含凭据、且不会被 Codex 忽略的项目规则/沙箱/权限类配置；`model_provider`、`[model_providers.*]`、`openai_base_url`、`base_url`、`env_key` 等 provider/auth 配置请放用户级 `~/.codex/config.toml` 或 profile 文件,不要指望团队仓库里的 project config 覆盖 provider/base URL。受管机器还可能用 `requirements.toml` 禁止 `approval_policy = "never"` 或 `sandbox_mode = "danger-full-access"`。 高频误判：把 Clomio provider 片段复制到仓库里的 `.codex/config.toml` 后仍直连官方或仍用旧模型，并不代表网关不可用。先把 provider/auth 放进用户级 `~/.codex/config.toml`，再运行 `codex --config model_provider=clomio` 或最小 `POST /v1/responses` curl 验证；项目级文件只保留团队规则、沙箱、MCP、hooks 等不含密钥的内容。 --- ## 接入 Clomio 的基础块 ```toml model_provider = "clomio" model = "gpt-5.4" model_reasoning_effort = "high" preferred_auth_method = "apikey" [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` 控制台「使用 Key」弹窗可能输出另一种自包含模板:直接写 `experimental_bearer_token = "sk-..."` 并配 `requires_openai_auth = true`。那种模板方便复制即用,但不适合提交或同步;长期推荐仍是上面的 `env_key` 模式。两种模式不要同时写。 密钥放在环境变量,不要写进项目仓库: **macOS / Linux:** ```bash export CLOMIO_API_KEY="你的密钥" # 想长期生效可写入 ~/.zshrc 或 ~/.bashrc ``` **Windows(PowerShell):** ```powershell $env:CLOMIO_API_KEY = "你的密钥" # 想长期生效: [Environment]::SetEnvironmentVariable("CLOMIO_API_KEY", "你的密钥", "User") ``` > `base_url` 可换成另外两条[线路](#/gateway-lines),例如 `https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1`。 --- ## 模型与推理 | 字段 | 取值 | 含义 | |------|------|------| | `model` | 模型名 | 用哪个模型,以控制台分组为准 | | `model_reasoning_effort` | `minimal`/`low`/`medium`/`high`/`xhigh` | 推理投入,越高越细致越慢越费 token | | `model_reasoning_summary` | `auto`/`concise`/`detailed`/`none` | 推理摘要详略 | | `model_verbosity` | `low`/`medium`/`high` | 输出详细程度(仅 Responses API 生效) | | `plan_mode_reasoning_effort` | 同 effort | 仅 `/plan` 模式下的推理强度覆盖 | | `hide_agent_reasoning` | `true`/`false` | 隐藏推理过程(截图/CI 日志更干净) | | `show_raw_agent_reasoning` | `true`/`false` | 显示原始推理内容 | --- ## 审批与沙箱(安全相关) 控制 Codex 执行命令的自由度: ```toml approval_policy = "on-request" sandbox_mode = "workspace-write" [sandbox_workspace_write] network_access = false writable_roots = ["~/work/scratch"] ``` | 字段 | 取值 | 含义 | |------|------|------| | `approval_policy` | `untrusted` / `on-request` / `on-failure` / `never` | 何时停下来问你再执行命令 | | `sandbox_mode` | `read-only` / `workspace-write` / `danger-full-access` | 文件/网络访问范围 | | `[sandbox_workspace_write].network_access` | `true`/`false` | 写模式下是否允许联网 | | `[sandbox_workspace_write].writable_roots` | 路径数组 | 额外可写目录 | > `workspace-write` 下,`.git/` 等目录有时仍只读,所以 `git commit` 可能仍需确认。日常用 `on-request` + `workspace-write` 比较稳妥;别轻易用 `danger-full-access`。 --- ### 审批/沙箱常见误区 - `approval_policy = "never"` 只是不再向你要授权,不是“自动获得更多权限”;如果沙箱仍是 `read-only` 或 `workspace-write`,越界写文件/联网仍会失败。 - `sandbox_mode = "danger-full-access"` 才是放开文件系统沙箱;不要为了让一个额外目录可写就全放开,优先用 `--add-dir` 或 `[sandbox_workspace_write].writable_roots`。 - `network_access = true` 只影响 `workspace-write` 沙箱下的联网;如果外层系统/代理不通,它不能修复网络。 - CI 或旁路 worker 推荐固定 `--sandbox workspace-write --approval on-request` 或对应配置,避免误改仓库外文件。 ## 你给的这些字段怎么理解 你列出的配置混了"Codex 风格"与若干自定义键。Codex 原生用 TOML,部分字段对应如下: ```toml # 语言、更新通道 # (Codex 用 AGENTS.md 控制回复语言;更新通道见各客户端设置) # 推理强度 —— 对应 effortLevel = high model_reasoning_effort = "high" # 始终思考 / 显示思考摘要 model_reasoning_summary = "detailed" # 详细输出 hide_agent_reasoning = false # 署名:留空即不在 commit / PR 里加署名 [attribution] commit = "" pr = "" ``` 下面几个是分组化的高级表: ```toml # 子代理:并行线程数与递归深度 [agents] max_threads = 10 max_depth = 2 # 记忆(留空表示使用默认) [memories] # 功能开关(留空接受默认,或显式开关单项) [features] # multi_agent = true # fast_mode = true ``` | 表 / 字段 | 含义 | |-----------|------| | `[agents].max_threads` | 子代理最大并行数 | | `[agents].max_depth` | 子代理最大递归深度 | | `[memories]` | 记忆相关配置(留空用默认) | | `[features]` | 功能开关表,如 `multi_agent`、`fast_mode`、`hooks` 等 | --- ## Profile:多套配置一键切 Codex 0.134.0 起,`--profile crs` 不再读取 `~/.codex/config.toml` 里的 `[profiles.crs]`。要给不同[线路](#/gateway-lines)或场景建 profile,请新建独立文件 `~/.codex/crs.config.toml`,里面直接写顶层配置键: ```toml # ~/.codex/crs.config.toml model_provider = "clomio_crs" model = "gpt-5.4" [model_providers.clomio_crs] name = "clomio_crs" base_url = "https://crs.qazwc.com/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` ```bash codex --profile crs ``` > 不要再写 `[profiles.crs]` 或 `profile = "crs"`;新版 Codex 不会用这些旧写法。 ## Provider 与认证放哪里 `model_provider`、`[model_providers.*]`、`base_url`、`env_key`、`wire_api` 等决定 Codex 如何连到供应商。provider/auth 相关键请放用户级或 profile 文件；项目级 `.codex/config.toml` 里出现这些键时可能被 Codex 忽略并给出启动警告。若 provider/base URL 配在项目目录后没有生效,先移到用户级 `~/.codex/config.toml` 或 `~/.codex/.config.toml`,再确认该项目是否 trusted,以及启动时是否被 `--profile`、`--config` 或受管 `requirements.toml` 覆盖。 认证方式二选一: - 推荐:`env_key = "CLOMIO_API_KEY"`,密钥来自本机环境变量。 - 复制即用/不推荐长期保存:`experimental_bearer_token = "sk-..."` 配合 `requires_openai_auth = true`,控制台弹窗可能这样生成。 - 兼容/不推荐:`requires_openai_auth = true`,使用 Codex 的 OpenAI 认证链路,例如旧版 `~/.codex/auth.json` 里的 `OPENAI_API_KEY`。启用后 Codex 会忽略 `env_key`,所以不要和 `env_key` 混用。 如果你从控制台模板切换到环境变量模式,删除 `experimental_bearer_token` 和 `requires_openai_auth`,再确认 `codex /status` 或启动日志里实际 provider/base URL 已变更。 旧配置如需临时兼容可保留: ```toml [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" requires_openai_auth = true ``` ```json { "OPENAI_API_KEY": "你的密钥" } ``` --- ## Responses wire API 与 WebSocket 选项 Clomio 的 Codex provider 固定按 OpenAI-compatible Responses 使用: ```toml [model_providers.clomio] base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" # 如客户端版本支持且网关账号允许,可启用 Responses WebSocket: # supports_websockets = true # # [features] # responses_websockets_v2 = true ``` 官方配置参考里 `wire_api` 当前只支持 `responses`;`supports_websockets` 表示该 provider 是否支持 Responses API WebSocket transport。Codex WS v2 实际还需要 `[features].responses_websockets_v2 = true`;控制台「Codex WS」tab 会同时生成这两个开关。不开 WS 时仍可用普通 `POST /v1/responses` / SSE 流式。Codex wire API 只覆盖 Responses 对话链路;其他能力请按对应工具页配置。 普通 `GET /v1/responses` 不是健康检查 REST API。OpenAI/Grok 分组过鉴权后返回 426 才说明命中了 WS 入口；不支持该能力的分组才会返回 404。Grok 分组是否开放 WS 以当前分组能力为准。 ### Provider 绑定与环境污染排查 - `model_provider = "clomio"` 必须能对应到 `[model_providers.clomio]`;改 provider 名时两处一起改。 - `env_key = "CLOMIO_API_KEY"` 只读取这个变量;如果同时保留 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 或旧 `auth.json`,旧版/兼容写法可能让你误以为新 key 已生效。 - `requires_openai_auth = true` 与 `env_key` 二选一;前者走 Codex/OpenAI 认证链路,后者走指定环境变量。Clomio 网关推荐 `env_key`。 - OpenAI-compatible base URL 写到 `/v1` 即止:`https://api.clomio.ai/v1`;不要写 `/v1/responses`、`/v1/chat/completions` 或不带 `/v1`。 - 模型名只按当前 Clomio 分组开放列表填写;本地 alias、OpenAI 官网模型名和控制台展示不一致时,以控制台为准。 ## MCP:接外部工具 ```toml [mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] ``` 会话里 `/mcp` 查看已连接工具。更多见 [Codex 进阶](#/codex-advanced)。 --- ## 参考资料 - [OpenAI Codex Config basics](https://developers.openai.com/codex/config-basic) - [OpenAI Codex Configuration reference](https://developers.openai.com/codex/config-reference) - [OpenAI Codex Advanced config](https://developers.openai.com/codex/config-advanced) - [OpenAI Codex CLI reference](https://developers.openai.com/codex/cli/reference) - [Codex 社区配置经验(X)](https://x.com/canghe/article/2060376680896799094):公开中转站教程反复强调 `base_url` 只写到 `/v1`,并保留 `wire_api = "responses"`。 - [Codex WS 排障经验(X)](https://x.com/mylifcc/status/2057308552738505031):WS 不稳定时可尝试禁用 `supports_websockets`,但不要把这个当成所有环境的默认值。 > 字段会随版本变化,完整列表以 [官方配置参考](https://developers.openai.com/codex/config-reference) 为准。生图功能见 [Codex 生图](#/codex-image)。 --- # Grok xAI/Grok 模型与兼容客户端配置说明,覆盖 Responses、Images、Videos 与 Web Search。 --- ## 一、安装 Grok 从 `help.clomio.ai` 镜像一键安装,国内直连、无需翻墙: ```bash curl -fsSL https://help.clomio.ai/grok/install.sh | bash ``` Windows PowerShell: ```powershell irm https://help.clomio.ai/grok/install.ps1 | iex ``` 镜像同时提供 macOS、Linux、Windows 三平台的独立二进制(x86_64 与 ARM64),装好后: ```bash grok --version ``` 输出版本号即成功。 > Windows 安装脚本会自动识别 x86_64 / ARM64,并把命令目录加入当前用户的 PATH。 --- ## 二、通过 Clomio 网关使用 Grok 模型由 Clomio 网关(`api.clomio.ai`)统一分发。使用前: 1. 在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个 **Grok 分组** 的密钥(见 [创建 API 密钥](#/api-key)) 2. 让客户端把请求指向网关地址 `https://api.clomio.ai/v1`,并带上该密钥 当前 Clomio 控制台生成的 Grok CLI 配置优先使用 `GROK_MODELS_BASE_URL` + `XAI_API_KEY`: ```bash export GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" export XAI_API_KEY="你的 Grok 分组密钥" ``` 也可以写入 `~/.grok/config.toml`: ```toml [endpoints] models_base_url = "https://api.clomio.ai/v1" [model.grok-build] model = "控制台中该分组开放的 Grok 对话模型" env_key = "XAI_API_KEY" ``` 控制台「使用 Key」弹窗生成的是当前模板,可能包含 `grok-build`、`grok-4.20-reasoning`、`grok-latest` 这类示例模型名。真实可用模型仍以这把 Key 所在 Grok 分组的模型列表为准;如果 `grok-build` 或 `grok-4.20-*` 返回 `model not found`,先换成控制台显示的对话模型。 不同 Grok CLI 包装器的变量名可能略有差异。旧包装器可能仍使用 `GROK_BASE_URL` / `GROK_API_KEY` / `GROK_MODEL`,也可能兼容 `XAI_BASE_URL`、`OPENAI_API_KEY`、`OPENAI_BASE_URL` 和 `OPENAI_MODEL`。如果当前版本说明自己走 OpenAI SDK,就把 OpenAI SDK 的 `base_url` / `baseURL` 指到 `https://api.clomio.ai/v1`,并使用 Grok 分组 Key;不要同时保留一套旧的 `OPENAI_*` 指向 OpenAI 分组。 如果怀疑旧环境变量污染,先隔离启动一次: ```bash env -i \ PATH="$PATH" \ GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" \ XAI_API_KEY="你的 Grok 分组密钥" \ grok --model "控制台中该分组开放的 Grok 模型" ``` 或先清掉常见冲突变量再重开终端: ```bash unset OPENAI_API_KEY OPENAI_BASE_URL OPENAI_MODEL XAI_API_KEY XAI_BASE_URL GROK_BASE_URL GROK_API_KEY GROK_MODELS_BASE_URL ``` 执行 unset 后必须重新 export `GROK_MODELS_BASE_URL` 与 `XAI_API_KEY`;否则后续 curl/CLI 会变成空密钥或默认地址。也可以写入 shell 配置文件,例如 `~/.zshrc` 或 `~/.bashrc`。如需走备用线路: ```bash export GROK_MODELS_BASE_URL="https://sub.qazwc.com/v1" # 或 export GROK_MODELS_BASE_URL="https://crs.qazwc.com/v1" ``` | 设置项 | 值 | |--------|-----| | Base URL | `https://api.clomio.ai/v1` | | API Key | 你的 Grok 分组密钥 | | 模型名 | 控制台中该分组开放的 Grok 模型 | > OpenAI/xAI-compatible base URL 通常要带 `/v1`。Clomio 的 Grok 分组也是带 `/v1` 后再访问 `/responses`、`/images/*` 等端点。 **注意 Grok 分组的端点与其他分组不同:** - 对话走 **Responses** 端点 `POST /v1/responses`,**不支持** `/v1/chat/completions` 与 `/v1/messages` - `GET /v1/responses` 是 Responses WebSocket 入口;Grok 分组是否开放以当前分组能力为准 - 支持 **图像** `/v1/images/*` - 支持 **视频** `/v1/videos/*`(**Videos 目前仅 Grok 分组可用**) - 支持 **联网搜索**:推荐在 `/v1/responses` 里带 `tools: [{"type":"web_search"}]`;Clomio 也提供简化 `/v1/web_search` sources-list 入口 - 不支持 **Embeddings**;`/v1/embeddings` 仅 OpenAI 分组可用 各端点的完整文档见 [API 参考](#/api-usage):[Responses](#/api-responses)、[Images](#/api-images)、[Videos](#/api-videos)、[Web Search](#/api-websearch)。 --- ## 三、验证网关 先用 `curl` 验证密钥、分组、模型和 Base URL,再启动 CLI。本节 curl 统一使用 `XAI_API_KEY` 和显式模型变量；如果你的旧包装器只读取 `GROK_API_KEY` / `GROK_MODEL`,可额外设置别名,但不要把 OpenAI 分组 Key 混进来。 ```bash export GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" export XAI_API_KEY="你的 Grok 分组密钥" export GROK_MODEL="控制台中该分组开放的 Grok 对话模型" export GROK_IMAGE_MODEL="控制台中该分组开放的 Grok 图像模型" export GROK_VIDEO_MODEL="控制台中该分组开放的 Grok 视频模型" # 兼容旧包装器时可选: export GROK_API_KEY="$XAI_API_KEY" ``` ### Responses 对话 ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$GROK_MODEL"'", "input": "用一句话说明 Grok 分组已经接通。" }' ``` 能返回文本内容即表示对话链路可用。隐私/无状态调用可显式加 `store:false`;长推理模型建议 curl 加 `-m 3600`,OpenAI SDK 设置更长 timeout。Grok 分组同时支持 `/v1/responses` 和 `/v1/chat/completions`;需要 Claude Messages 形状时，使用已开放 Messages ingress 的分组。 无状态最小请求: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -m 3600 \ -d '{ "model": "'"$GROK_MODEL"'", "input": "ping", "store": false, "max_output_tokens": 64 }' ``` 连续对话用上一轮返回的 `id` 作为下一轮 `previous_response_id`: ```bash FIRST_ID=$(curl -s https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"'"$GROK_MODEL"'","input":"用一句话介绍你自己"}' | jq -r '.id') curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"'"$GROK_MODEL"'","previous_response_id":"'"$FIRST_ID"'","input":"继续上一句,再补一个使用场景"}' ``` ### Images 图像 ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$GROK_IMAGE_MODEL"'", "prompt": "a small robot reading documentation, clean icon style" }' ``` 图像模型和对话模型通常分开展示；请用控制台标注的 `grok-imagine-*` 或其它 Grok 图像模型。Grok Imagine 默认通常返回 `data[0].url` 临时链接；在 Clomio 当前本地校验里不要显式传 `response_format:"url"`，想要 URL 就省略该字段，想要内联图片再传 `response_format:"b64_json"`。 xAI/Grok Imagine 官方风格常用 `n`、`aspect_ratio`、`resolution` 等字段,而不是只用 OpenAI 图片的 `size`: ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$GROK_IMAGE_MODEL"'", "prompt": "A futuristic city skyline at night", "n": 1, "aspect_ratio": "16:9" }' ``` ### Videos 视频(仅 Grok) ```bash curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$GROK_VIDEO_MODEL"'", "prompt": "A cinematic 5-second shot of clouds moving over a city skyline", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p" }' ``` Videos 是 Grok 分组能力,不要拿 GPT、Claude、Anthropic 分组密钥测试 `/v1/videos/*`。提交后按返回的 `request_id` 轮询 `GET /v1/videos/{request_id}`；常见状态是 `pending`、`done`、`expired`、`failed`。 ### Web Search 联网搜索 推荐主路径是直接走 xAI/OpenAI-compatible Responses tool： ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$GROK_MODEL"'", "input": "检索今天 xAI API 文档里 Grok 的模型能力摘要", "tools": [{"type": "web_search"}], "store": false }' ``` xAI 官方工具会在服务端自动执行；流式模式下可以观察工具调用，最终响应通常带 citations/annotations。工具调用按 xAI 规则计费。 Clomio 还提供独立 `/v1/web_search` 简化端点，只读取 `query` 和 `max_results`，返回 sources-list，不返回模型总结；它不是官方 `tools[].filters` 参数透传入口。 ```bash curl https://api.clomio.ai/v1/web_search \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Clomio Grok Responses API", "max_results": 5 }' ``` 如果独立端点报 `scheduling_error` 或 `web_search_error`，先用上面的 `/v1/responses` + `web_search` 验证 Grok 搜索主链路，再带请求 ID 排查独立 sources-list 入口。 --- ## 四、开始使用 配置完成后运行: ```bash grok ``` 进入交互界面、能正常对话即表示打通。脚本或 CI 场景可先用 headless prompt 验证: ```bash grok --prompt "请返回当前项目的一句话摘要" ``` --- ## 常见问题 **只想本地装好 Grok,不接网关?** 上面第一步的安装命令即可独立完成安装,镜像本身不涉及鉴权。 **Base URL 怎么填?** 填 `https://api.clomio.ai/v1`、`https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1`。OpenAI/xAI-compatible base 通常带 `/v1`;不要写成 `https://api.clomio.ai/v1/responses`,客户端会自己拼端点。 **报 404 / endpoint not found?** 多半是端点、分组或模型不匹配。Grok 分组可用 `POST /v1/responses` 或 `/v1/chat/completions` 验证；`/v1/messages` 和 Responses WebSocket 需看分组能力，`/v1/embeddings` 仍只支持 OpenAI 分组。如果 GUI 只会测某一条路径，检测结果不代表其他能力不可用。 快速判定: | 现象 | 优先判断 | |---|---| | `404 endpoint not found` | Base URL 应是 `https://api.clomio.ai/v1`,不要填完整 `/v1/responses` | | 出现 `/v1/v1/...` | 客户端和你都加了 `/v1`,删一层 | | `/v1/chat/completions` 404/unsupported | 当前 Grok 分组未开放 Chat 或模型不匹配；改用 Responses 或换已开放 Chat 的分组 | | `/v1/messages` 404/unsupported | Grok Key 被 Claude/Anthropic 客户端使用 | | `/v1/videos/*` 404 | 非 Grok 分组、视频能力未开或 legacy 不带 `/v1` 路径写错 | | `429` | 先降并发/轮询；按 `Retry-After` 和 rate-limit headers 做 backoff；持续异常带 `x-request-id` 提交工单 | **报 unauthorized / forbidden?** 确认密钥来自 **Grok 分组**,不是 GPT、Claude、Anthropic 或其他分组;确认密钥未过期、未复制多余空格。 **报 model not found / no available model?** 模型名必须使用控制台中 Grok 分组开放的模型。不同分组的同名/别名不一定互通。控制台模板里的 `grok-build` 只是 CLI/agent 示例;如果该别名不可用,换控制台模型列表中的 Grok 对话模型。 **Images / Videos / Web Search 不通?** 先确认分组开通了对应能力: - Images:可用 OpenAI 分组或 Grok 分组。 - Videos:`/v1/videos/*` 仅 Grok 分组可用。 - Web Search:仅 Grok 分组可用。 **OPENAI_* 环境变量会干扰吗?** 当前推荐优先使用 `GROK_MODELS_BASE_URL` + `XAI_API_KEY`。仅旧包装器可能读取 `GROK_BASE_URL`、`GROK_API_KEY`、`GROK_MODEL`。如果本机同时设置了 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 等变量,建议在测试 Grok 时临时 `env -i` 隔离启动,或先清掉冲突变量后重新导出 `GROK_MODELS_BASE_URL` 与 `XAI_API_KEY`,避免客户端版本或包装脚本误读旧配置。 **Web Search 没返回实时信息?** xAI 官方把 Web Search/X Search 作为 server-side tools 启用;只发普通 `/v1/responses` 不等于自动联网。确认请求里带 `tools: [{"type":"web_search"}]`。如果只是想拿 sources-list,再用 Clomio `/v1/web_search` 简化端点；该端点异常时以 Responses tool 的结果作为主链路判断。 **报 `Embeddings API is not supported for this platform`?** 说明客户端把 Grok Key 拿去调 `/v1/embeddings`。Embeddings 只支持 OpenAI 分组,请换 OpenAI 分组 Key 和 embedding 模型,或关闭客户端的 embedding / memory indexing 功能。 **连接失败 / 超时?** 换用 [网关线路](#/gateway-lines) 中的备用线路,并先用 curl 验证同一 Base URL、同一密钥、同一模型是否可用。长推理/视频/搜索请求可把客户端 timeout 调到 300~3600 秒。其余网络类报错见 [故障排查](#/troubleshooting)。 --- ## 官方参考资料 - [xAI Quickstart](https://docs.x.ai/developers/quickstart):官方 REST/OpenAI SDK 示例使用 `https://api.x.ai/v1/responses`,对应 Clomio 时 base URL 填 `https://api.clomio.ai/v1`。 - [xAI Models](https://docs.x.ai/developers/models):模型、模态、上下文和是否需要搜索工具以最新模型页为准。 - [xAI Generate Text](https://docs.x.ai/developers/model-capabilities/text/generate-text):Responses 是首选文本接口,支持 `store:false`、`previous_response_id` 和长 timeout。 - [xAI Chat Completions legacy](https://docs.x.ai/developers/model-capabilities/legacy/chat-completions):Chat Completions 是 legacy,新能力优先 Responses。 - [xAI Image Generation](https://docs.x.ai/developers/model-capabilities/images/generation):Grok Imagine 使用 `/v1/images/generations`,常见模型为 `grok-imagine-*`,支持 `n`、`aspect_ratio`、`resolution`。 - [xAI Web Search](https://docs.x.ai/developers/tools/web-search):联网搜索需要显式启用 server-side tool 或使用专门搜索端点。 - [xAI Video Generation](https://docs.x.ai/developers/model-capabilities/video/generation):视频生成是 xAI/Grok 能力;Clomio 中仅 Grok 分组测试 `/v1/videos/*`。 - [xAI Rate Limits](https://docs.x.ai/developers/rate-limits):429 通常来自 per-model RPS/TPM 或账号 tier 限制,按 `Retry-After`/headers/backoff 处理。 --- ## 计费与选型 # 计费与额度 搞懂怎么计费,才能用得明白、花得放心。 --- ## 按 token 计费 模型按 **token**(文字的最小计费单位)收费,粗略地说:1 个英文单词 ≈ 1 token,1~2 个汉字 ≈ 1 token。 一次调用分两部分计费: | 类型 | 指什么 | 特点 | |------|--------|------| | **输入 token** | 你发给模型的内容(含历史对话、文件) | 较便宜 | | **输出 token** | 模型返回的内容 | 通常比输入贵 3~5 倍 | | **缓存写入** | 本次把可复用上下文写入缓存 | 可能单独计入 `cache_creation_tokens` / 5m / 1h 写入 | | **缓存命中** | 复用之前处理过的内容 | 计入 `cache_read_tokens`,通常比正常输入更省 | **一句话:说得越长、回得越长、轮次越多,token 越多,费用越高;命中缓存越多越省。** --- ## cost / total_cost / actual_cost 怎么看 控制台和 `/v1/usage` 里会同时出现几种成本口径: | 字段 | 含义 | 用途 | |------|------|------| | `input_cost` / `output_cost` / `cache_*_cost` | 各类 token 按基础价格算出的分项成本 | 排查是哪类 token 花钱 | | `cost` / `total_cost` | 倍率前的基础成本合计;部分聚合接口用 `cost` 命名 | 对照模型官方价、理解原始消耗 | | `rate_multiplier` | 用户/分组倍率快照 | 解释基础成本如何变成实际扣费 | | `actual_cost` | 实际从余额、订阅额度或 API Key quota 扣掉的金额 | 看账单、看剩余额度时以它为准 | 常见公式: ```text actual_cost = total_cost × rate_multiplier ``` 图片、视频、按次计费、分层价格(`billing_tier`)或服务层级(`service_tier`)场景可能不是单纯文本 token 价格；用量日志还可能记录 `billing_mode`、`image_count`、`image_size`、`image_output_tokens` 等字段。但页面展示仍遵循同一思路:**`total_cost`/`cost` 是基础口径,`actual_cost` 是最终扣费口径**。 真实扣费边界：用户余额、订阅额度、API Key quota、API Key 金额限速通常按 `actual_cost` 记账。图片请求在当前实现里可能不计入某些 Key quota 或金额限速，因此“图片扣费正常但 Key quota 没动”不一定是 bug。排查单笔媒体扣费时，优先看用量明细里的 `billing_tier`、`request_type`、图片尺寸/数量和输出 token 字段。 --- ## 实际扣费 = 基础成本 × 分组/用户倍率 倍率有几层，含义不同： - **分组倍率** 是当前分组的默认扣费倍率。 - **用户专属倍率** 命中时会覆盖分组默认倍率；没有专属规则时回到分组倍率。 - **媒体/搜索/音频价格** 可能使用独立价格或独立倍率，不一定套普通文本倍率。 - 图片、视频、搜索、音频等显式非文本计费以控制台展示、用量明细和当前分组价格为准。 --- ## 非 token 计费模式 除了文本 token，部分能力会使用更细的 `billing_mode`： | billing_mode | 场景 | 计费/排账提示 | |---|---|---| | `image` | `/v1/images/*`、Responses 图片桥接 | 看图片数量、尺寸 tier、输入/输出尺寸、图片输出 token/成本 | | `video` | Grok-only `/v1/videos/*` | 按分辨率 tier + 秒数/视频数量；只适用于已开通视频的 Grok 分组 | | `search` | Grok Web Search / tool search 计费 | 常按每 1k 次调用的显式价格折算 | | `audio` | realtime / TTS / STT | 分别关注分钟数、字符数或小时数 | | `per_request` | 按次或按上下文窗口分层的渠道 | 看请求次数、`billing_tier` 与渠道定价；找不到 tier 时可能回退默认按次价 | 更具体地看： - `token`：可能包含输入、输出、缓存写、缓存读、5m/1h 缓存写、图片输入 token、图片输出 token、`service_tier=priority/flex`、长上下文倍率。 - `image`：通常按图片数量 × 1K/2K/4K 单价；分组价格优先，缺省时可能回落渠道/内置默认价。2K/4K 在默认估算中可能按 1K 的倍数折算。 - `video`：Grok-only，按分辨率 tier × 秒数 × 视频数；tier 支持 480p、720p、1080p、4K；缺 tier 时可能回落到最高已配置价格。 - `search`：按每 1k 次搜索/工具调用价格折算为单次；未配置或非正数时这段成本可为 0。 - `audio`：realtime 按分钟、TTS 按百万字符、STT 按小时；未配置或非正数时这段成本可为 0。 这些价格不是所有用户固定相同；会随当前分组、模型和站点价格策略变化。对账时以控制台可见价格、用量明细里的 `billing_mode` / `actual_cost` 和实际响应为准。 排账时不要只看 token 是否为 0。图片、视频、搜索、音频可能本来就不是按输入/输出 token 计费；应结合 `request_type`、`billing_mode`、媒体字段、`actual_cost` 和控制台分组/渠道定价判断。 --- 倍率越低越省。不同[分组](#/api-key)对应不同上游与倍率,具体数值以控制台 [api.clomio.ai](https://api.clomio.ai) 实时显示为准。倍率的详细解释见 [常见问题](#/faq)。 --- ## 套餐、余额、Key 额度的优先理解 你可以把额度分成三层: | 层级 | 在哪里看 | 影响 | |------|------|------| | **账户余额** | 控制台余额、`/v1/usage` 的 `balance` | 没有订阅/Key 限制时,按 `actual_cost` 扣余额 | | **套餐/订阅** | 控制台「订阅与余额」、`/subscriptions`、`/subscriptions/active`、`/subscriptions/progress`、`/subscriptions/summary`、`/v1/usage` 的 `subscription` | 可能有日/周/月美元额度与到期时间 | | **API Key quota** | API Key 设置、`/v1/usage` 的 `quota` | 给单个 Key 设独立总额度,用完后这个 Key 不再可用 | | **用户级平台额度** | 控制台平台额度、`/api/v1/user/platform-quotas` | 按平台限制 daily/weekly/monthly 美元用量,和 Key quota、订阅额度分开计算 | 建议给 Claude、Codex、Grok、脚本任务分别建 Key。这样即使同一个账户共享余额,也能用 Key quota 控制某个工具最多花多少。 `/user/platform-quotas` 返回 `platform_quotas` 数组,平台包括 `anthropic`、`openai`、`gemini`、`antigravity`、`kiro`、`grok`。每个平台可包含 `daily_limit_usd`、`weekly_limit_usd`、`monthly_limit_usd`、对应 `*_usage_usd`、`*_window_start` 和 `*_window_resets_at`;过期窗口在响应中会按当前口径 lazy zero,重置时间可能为 `null`。 请求前会先做资格检查：简易模式可能跳过计费检查；订阅分组优先检查订阅状态、过期时间和日/周/月订阅额度；余额模式要求余额大于 0 且不低于最小保留额；用户级 platform quota 只在余额模式生效，订阅模式豁免。API Key 金额限速、API Key RPM、用户/分组 RPM 则是额外限制，两种模式都可能遇到。 没有“逐请求冻结余额”的强冻结模型。通常是请求前检查余额/额度，成功记录用量后按 `request_id + api_key_id` 幂等扣费；并发很高时，预检和后扣之间可能发生竞争，系统会记录扣费结果并刷新/失效余额缓存。因此排查余额异常时要看 `request_id`、`actual_cost`、扣费时间和幂等记录，而不是只看请求开始时的余额。 --- ## 并发、RPM 和金额限速 除了余额/套餐,还可能遇到三类限制。控制台若显示“平台额度”,其来源是 `/user/platform-quotas`,用于查看用户级平台限额与已用量: | 限制 | 含义 | 常见现象 | 处理 | |------|------|------|------| | 并发(concurrency) | 同时在跑的请求数量上限 | 多个终端/脚本一起跑时排队或失败 | 降低并发,等前面的流结束 | | RPM | 每分钟请求数上限;分组级优先,用户级兜底 | 短时间大量小请求返回 429 | 降低频率、合并请求 | | 金额限速 | API Key 的 5h/1d/7d 美元窗口 | `/v1/usage` 返回 `rate_limits` 和 `reset_at` | 等窗口重置或调整 Key 限额 | 流式长任务在结束前会占用并发;图片/视频单次 `actual_cost` 可能高于普通文本,更容易撞到金额限速。Videos 端点当前只支持 Grok/xAI 路径,如果用错 Claude/Codex/OpenAI 分组,会先表现为路由/账号能力错误,不是余额计算问题。 ### 常见计费报错与排查路径 | 报错 | 常见原因 | 排查路径 | |---|---|---| | `INSUFFICIENT_BALANCE` / `insufficient balance` | 余额小于等于 0 或低于 minimum reserve | 查用户余额、最小保留额、当前是否余额模式 | | `BILLING_SERVICE_ERROR` | 余额/订阅缓存或计费服务检查失败，熔断中也可能返回 | 查 Redis、billing cache、计费服务日志 | | `SUBSCRIPTION_INVALID` | 订阅非 active 或已过期 | 查订阅状态、到期时间、分组是否订阅型 | | `DAILY_LIMIT_EXCEEDED` / `WEEKLY_LIMIT_EXCEEDED` / `MONTHLY_LIMIT_EXCEEDED` | 订阅日/周/月额度用尽 | 查订阅进度和分组额度 | | `USER_PLATFORM_*_QUOTA_EXHAUSTED` | 用户级平台日/周/月额度用尽 | 查 `/user/platform-quotas`;注意订阅模式通常豁免 | | `GROUP_RPM_EXCEEDED` / `USER_RPM_EXCEEDED` | 分组或用户 RPM 超限，专属 override 可能参与 | 查 group RPM、user RPM、user-group override | | `pricing not found` / `no pricing available for model` | 动态/兜底价格都找不到 | 查渠道定价、模型映射后的 billing model | | `rate_multiplier must be > 0` | 当前分组倍率配置异常 | 提交工单并附错误文本和 request_id | | `image_rate_multiplier must be >= 0` | 图片独立倍率非法 | 修正图片计费配置 | --- ## 在哪看明细 控制台的「使用记录」能看到**每一次调用**的输入/输出 token、命中缓存、所用模型与扣费;错误请求页能看到面向用户脱敏后的失败详情。建议: - 给不同项目/用途**建不同密钥**,账单更容易按 key 区分(见 [创建 API 密钥](#/api-key)) - 发现某次扣费异常,对照使用记录里的 token 数、`request_id`、`requested_model`、`upstream_model`、`billing_mode` 和 `actual_cost` 核查 - 图片排账重点看 `image_count`、`image_size`、`image_input_size`、`image_output_size`、`image_size_source`、`image_size_breakdown`、`image_output_tokens`、`image_output_cost`；文本 token 为 0 不代表一定免费 - 需要程序化查询时,用 `GET /v1/usage` 看当前 Key 的 `mode`、`quota`、`rate_limits[]`、`usage.today/total`、`model_stats`、`balance`、`subscription` 和 `usage.*.actual_cost`;控制台页面则通过 `/usage`、`/usage/stats`、`/usage/dashboard/*` 查询明细、趋势、模型统计和 Key 日用量 示例: ```bash curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29' \ -H "Authorization: Bearer 你的密钥" ``` `mode: "quota_limited"` 表示 Key 自己配置了额度/限速;`mode: "unrestricted"` 表示这个 Key 没有独立限制,主要看账户余额或订阅额度。 --- ## 省钱技巧 - **及时压缩上下文**:对话变长时用 `/compact` 压缩,能显著省 token(见 [Claude Code 使用手册](#/claude-usage))。 - **挑对模型**:简单任务用轻量/便宜的模型,复杂任务再上强模型,别一律用最贵的。见 [模型选择指南](#/models)。 - **善用缓存**:连续多轮同一上下文会命中缓存,比频繁开新对话更省。 - **别让它无谓地长篇输出**:需要简洁时,直接要求"简明回答"。 --- ## 充值建议 - **先小额测试**:首次先充小额,验证速度、模型表现都满意,再按需追加。 - **按需充值**:用多少充多少,不必一次囤太多。 - 充值入口在控制台,支付后余额自动到账。开发票相关见 [常见问题](#/faq)。 --- > 想理解每个术语?[常见问题](#/faq) 里有倍率、扣费的通俗解释;选模型看 [模型选择指南](#/models)。 --- # 模型选择指南 模型不是越贵越好，**选对任务用对模型**才最省心。本页帮你快速判断该用哪个，并解释控制台里的渠道、平台、分组、模型与倍率关系。 > 具体有哪些模型、各自倍率，以控制台 [api.clomio.ai](https://api.clomio.ai) 你所在[分组](#/api-key)显示为准。下面讲的是“怎么选”和“为什么实际模型可能不同”的通用思路。 --- ## 渠道 → 平台 → 分组 → 模型 一次请求大致按这条链路选择模型： 1. **渠道（Channel）**：网关里配置的一条上游线路，决定请求能发到哪里。 2. **平台（Platform）**：OpenAI、Anthropic、xAI/Grok、Gemini 等能力类型。 3. **分组（Group）**：你的 API Key 绑定的分组，决定你能用哪些渠道/平台/模型，以及用户侧倍率。 4. **模型（Model）**：你在请求里写的模型名，可能经过模型映射后变成上游真实模型。 所以控制台用量里可能同时看到： - **请求模型**：你传入的模型名。 - **上游模型**：模型映射后真实发给上游的模型。 - **模型映射链**：从别名到真实模型的映射过程（若有）。 排查“为什么表现不像预期模型”时，请先看用量明细里的上游模型。 ### 模型名、别名、路由不是一回事 控制台和 API 里常见三种“模型名”: | 口径 | 你在哪里看到 | 说明 | |------|--------------|------| | 请求模型 | 请求体 `model`、`GET /v1/models` | 客户端可填写的名字;可能是平台自定义别名 | | 路由模型 / 映射目标 | 分组开放模型、模型映射、分组默认路由 | 网关用它改写请求；左侧通常是请求名，右侧通常是上游目标 | | 上游真实模型 | 控制台用量明细、错误详情里的 upstream model | 实际发到 OpenAI、Anthropic、Grok 等上游的模型 | 所以“列表里能看到某模型”只代表当前分组允许你用这个**请求名**；它不保证上游真实模型同名。若遇到质量、价格、能力和预期不一致，按顺序核对：控制台分组开放模型 → 模型映射/默认路由 → 本次用量明细里的上游模型。 `GET /v1/models` 返回的是**当前这把 Key 可见**的模型：会综合 Key 分组、平台和当前分组开放模型；没有显式模型列表时才回退到平台默认模型。控制台 `/channels/available` 也是“当前用户已有 active 可用 Key 的线路视图”，不是全站所有渠道或全部模型表。 --- ## 倍率怎么理解 - **默认倍率 / 分组倍率**：分组或模型默认倍率，决定用户侧基础扣费规则。 - **用户专属倍率**：平台可对特定用户设置专属倍率，最终会体现在 `actual_cost`。 对用户来说，余额/订阅真正减少的是用量明细里的 `actual_cost`；`cost` / `total_cost` 主要用于理解基础模型成本。 --- ## Claude 系列（Anthropic） | 档位 | 特点 | 适合 | |------|------|------| | **Haiku** | 最轻、最快、最省 | 简单问答、格式整理、批量小任务 | | **Sonnet** | 性价比之王，多数人日常首选 | 日常写代码、改文件、一般推理 | | **Opus** | 能力最强，价格也最高 | 复杂架构设计、深度推理、攻坚难题 | **建议：默认用 Sonnet，遇到啃不动的难题再升 Opus，简单杂活交给 Haiku 省钱。** 在工具里用 `/model` 随时切换。 --- ## GPT / Codex 系列（OpenAI） GPT 系列除了选型号，还能调**推理强度**（`model_reasoning_effort`：`low`→`high`/`xhigh`）： - 快速、简单的活：低推理强度，又快又省 - 需要细致分析：高推理强度，更可靠但更慢更费 配置见 [Codex 配置详解](#/codex-config)。 --- ## Grok（xAI）/ 国产模型 - **Grok**：擅长快速代码任务与对话，还支持图像/视频/联网搜索，见 [API 调用指南](#/api-usage)。 - **Videos 仅 Grok**：视频生成目前只走 Grok 视频能力；创建 Key 时请选择支持 Grok Videos 的 Grok 分组。 - **国产模型**：中文场景、成本敏感时的实惠选择，以控制台清单为准。 ### 能力先看端点,再看模型 不同平台开放的端点不一样,不要只看模型名: - Claude 分组主路径是 `/v1/messages`;`/v1/messages/count_tokens` 主要用于 Claude/Anthropic 兼容分组。 - OpenAI 分组主路径是 `POST /v1/responses`、`/v1/chat/completions`、`/v1/embeddings`、`/v1/images/*`;若要用 `/v1/messages`,当前分组必须开放 Messages 兼容能力。 - Grok 分组支持 `POST /v1/responses`、`/v1/chat/completions`、`/v1/images/*`、`/v1/videos/*`、`/v1/web_search`；`/v1/messages` 需当前分组开放 Messages 兼容能力，`/v1/embeddings` 仍只支持 OpenAI 分组。 - Gemini 分组走 [Gemini 原生兼容](#/api-gemini) 的 `/v1beta/models...`,Base URL 不带 `/v1`。 - Antigravity 分组走 [Antigravity 接入](#/antigravity) 的 `/antigravity/v1...` 或 `/antigravity/v1beta...`,不会和普通 Claude/OpenAI/Grok 混合调度。 - `GET /v1/responses` 是 Codex/Responses WebSocket 入口,不是按 ID 查历史;当前也没有 `GET /v1/models/{id}`。 --- ## 快速决策 | 你的任务 | 推荐 | |----------|------| | 日常写代码、改 bug | Claude Sonnet / GPT 中档 | | 复杂架构、深度推理 | Claude Opus / GPT 高推理 | | 简单问答、整理格式 | Haiku / 轻量模型 | | 执行任务、排查问题 | Codex（GPT） | | 理思路、聊方案 | Claude | | 生成图片 | 图像模型按分组选择 | | 生成视频 | Grok Videos 分组 | | Gemini 原生 SDK/CLI | Gemini 分组 + [Gemini 原生兼容](#/api-gemini) | | Antigravity 客户端 | Antigravity 分组 + [Antigravity 接入](#/antigravity) | 分不清就记：**日常 Sonnet，难题 Opus，杂活 Haiku；思考用 Claude，执行用 Codex；视频只选 Grok。** --- ## 确认模型表现是否符合预期 换了模型或分组后，想确认它发挥正常，可以简单自测： - **长上下文**：贴一篇较长的文档，让它总结中间某一段——能准确总结，说明上下文窗口够用。 - **推理能力**：出一道经典逻辑/数学题，看回答质量是否符合该档位模型的水平。 - **看使用记录**：在控制台核对本次调用的请求模型、上游模型、token、缓存和 `actual_cost`，做到心里有数。 如果表现和预期差距明显，换个[分组或线路](#/gateway-lines)再试，或在控制台联系支持。 --- ## 模型不可用时先看哪个报错 模型、分组和服务可用性是三层判断,报错含义不同: - `The current group does not support the requested model "xxx". Available models: ...`:分组明确不支持该模型,按列表换模型或换分组。可见模型很多时,报错只展示前一部分并追加 `and N more`,完整列表请看控制台或 `GET /v1/models`。 - `model_not_found` / `Model "xxx" is not supported by any configured account in this group`:当前分组没有可提供该模型的服务,常见于模型名写错或分组能力不匹配。 - `No available accounts supporting model: xxx`:该模型服务暂时不可用,可能是限速、额度或并发导致。 - `No available accounts`:当前分组暂时没有可用服务资源。 查可见模型用 `GET /v1/models` 或控制台模型清单;当前没有 `GET /v1/models/{id}`。Responses 历史也不能用 `GET /v1/responses/{id}` 查询,多轮续接交给 Codex/SDK 或在下一次 `POST /v1/responses` 传 `previous_response_id`。 --- > 选好模型后，怎么省着用见 [计费与额度](#/billing)。 --- ## 使用手册 # Claude Code 使用手册 装好并接上 Clomio 后([Claude Code 接入](#/claude-code)),这里是日常使用的速查。Claude Code 的主请求是 Anthropic `/v1/messages`;`/v1/messages/count_tokens` 只用于 token 估算,不是主对话路径。 --- ## 启动方式 | 方式 | 命令 | 说明 | |------|------|------| | 交互模式 | `claude` | 进入对话界面,最常用 | | 带提示启动 | `claude "解释这个项目"` | 进界面并立即执行一句 | | 非交互(出结果就退) | `claude -p "解释这个函数"` | 适合脚本/一次性任务 | | 管道输入 | `cat logs.txt \| claude -p "解释报错"` | 把文件内容喂给它分析 | | 指定模型 | `claude --model claude-sonnet-4-6` | 本次会话使用指定模型 | 首次启动后建议立刻运行 `/status`,确认: - `Anthropic base URL` 是 `https://api.clomio.ai` 或你选择的 Clomio 线路; - 凭据来源是 `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY`,而不是误用本机保存的 claude.ai 登录; - 当前项目目录与权限模式符合预期。 --- ## 常用命令 ```bash claude update # 更新到最新版(任何安装方式都适用) claude -c # 继续最近一次对话 claude --resume # 弹出历史会话选择器,挑一个恢复 claude commit # 让它帮你生成并创建一次 Git 提交 claude doctor # 检查安装健康状况 claude mcp # 管理 MCP 服务器(接外部工具) claude logs # 查看 background/daemon 会话日志 ``` --- ## 常用 CLI 标志 | 标志 | 作用 | 示例 | |------|------|------| | `--model` | 指定模型 | `claude --model claude-sonnet-4-6` | | `--permission-mode` | 权限模式(如 `plan` 只读规划) | `claude --permission-mode plan` | | `--allowedTools` | 本次允许的工具 | `claude --allowedTools "Bash(git*)" "Read"` | | `--add-dir` | 临时授权额外目录 | `claude --add-dir ../shared` | | `--verbose` | 详细日志 | `claude --verbose` | | `--mcp-config` | 临时加载 MCP 配置 | `claude --mcp-config ./mcp.json` | | `--dangerously-skip-permissions` | 跳过所有权限确认 | 谨慎用于隔离环境 | --- ## 键盘快捷键 | 按键 | 作用 | |------|------| | `Ctrl + C` | 取消当前输入 / 生成 | | `Ctrl + D` | 退出会话 | | `Ctrl + L` | 清屏 | | `↑ / ↓` | 浏览命令历史 | | `Esc` `Esc` | 编辑上一条消息 | | `Ctrl + O` | 任务像卡住时,查看 background 输出(再按一次切回) | | `\` + `Enter` | 多行输入(所有终端通用) | | `Option + Enter` | 多行输入(macOS 默认) | --- ## 斜杠命令 进入界面后输入 `/` 触发: | 命令 | 作用 | |------|------| | `/help` | 帮助 | | `/status` | 查看当前 base URL、凭据来源、模型、项目状态 | | `/model` | 切换模型(可选范围取决于你的[分组](#/api-key)与网关模型发现) | | `/compact` | 压缩当前对话,省 token | | `/clear` | 清空对话(话题跑偏想重来) | | `/config` | 打开设置界面(也可 `/config verbose=true` 改单项) | | `/permissions` | 管理工具权限 | | `/init` | 为项目自动生成 `CLAUDE.md` | | `/vim` | 开启 Vim 风格编辑 | | `/ide` | 检查 / 连接 IDE | | `/doctor` | 安装健康检查 | | `/agents` | 管理子代理 | | `/mcp` | 查看已连接的 MCP 工具 | --- ## 上下文管理(省 token) 对话越长越费 token。两招控制: - **`/compact [描述]`**:把当前长对话压缩成摘要,保留要点继续聊。 - **`claude -c` / `claude --resume`**:换个时间继续之前的会话,不必把所有背景重讲一遍。 Claude Code 会尝试调用 `/v1/messages/count_tokens` 做上下文估算。sub2api 对 Anthropic/Kiro 等可支持路径会转发;对 OpenAI/Grok 分组或不支持 count_tokens 的上游会返回 404 让客户端本地估算。主对话仍然看 `/v1/messages` 是否正常。 --- ## 发图片给它 让 Claude 看截图/设计图,三种方式任选: - 把图片**拖**进 Claude Code 窗口 - 复制图片后在终端 **`Ctrl + V`** 粘贴(macOS) - 直接给路径:`分析这个图:/path/to/image.png` 然后用自然语言提问,比如「这张报错截图是什么原因?」「用 HTML/CSS 还原这个设计」。 --- ## 连接 IDE Claude Code 支持 VS Code 与 JetBrains: - **VS Code**:在内置终端里运行 `claude`,扩展会自动安装;用 `/ide` 检查连接。详细接入(指向 Clomio)见 [VS Code 集成](#/vscode)。如果扩展不是从该 shell 启动,请在 VS Code 自己的 `claudeCode.environmentVariables` 里配置 `ANTHROPIC_BASE_URL` 和 key。 - **JetBrains**:安装官方插件后,用 `/ide` 连接。 - 连上后,Claude 的改动会以 diff 直接显示在编辑器里。 --- ## MCP:接外部工具 让 Claude 连上数据库、文档检索、浏览器等外部能力: ```bash claude mcp add <名字> <命令> [参数...] # 添加 claude mcp list # 列出 claude mcp get <名字> # 查看详情 claude mcp remove <名字> # 删除 claude mcp login <名字> # HTTP/SSE/OAuth 型 MCP 登录 claude mcp logout <名字> # 清除 MCP 登录 ``` 会话里用 `/mcp` 查看已连接的工具。用 `-s project|user` 指定配置存放范围。 自定义 `ANTHROPIC_BASE_URL` 时,官方 Claude Code 默认会把 MCP tool search 从“按需发现工具”退回到更兼容的模式,因为很多代理不转发 `tool_reference`。表现为模型先等待 MCP 连接,或一次性加载工具列表。排障建议: ```bash # 网关不支持 tool_reference 时最稳 export ENABLE_TOOL_SEARCH=false # 工具较少时自动决定是否按需搜索 export ENABLE_TOOL_SEARCH=auto # 只有确认网关透传 tool_reference beta 块时再强开 export ENABLE_TOOL_SEARCH=true ``` 也可以写进 `settings.json` 的 `env`。 --- ## Base URL 与 count_tokens 快速判断 - `/status` 里 `Anthropic base URL` 必须是不带 `/v1` 的根地址,例如 `https://api.clomio.ai`。 - 如果日志或错误里出现 `/v1/v1/messages`,就是 base URL 多写了 `/v1`。 - `count_tokens` 404 只代表 token 估算端点不可用;OpenAI 分组和不支持该端点的上游都会这样回退,不等于主对话失败。 - Grok 分组只有在启用 Messages 兼容能力时才适合跑 Claude Code；否则请使用 Grok 的 Responses 或 Chat 端点。 ## Clomio / sub2api 分组相关提示 | 现象 | 原因 | 处理 | |------|------|------| | 403: key 未分组 | API Key 的 `group_id` 为空,且系统不允许未分组调度 | 在控制台把 key 绑定到分组 | | 403: group 不允许 `/v1/messages` | OpenAI 平台分组未开放 Messages 兼容能力 | 换 Anthropic 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组 | | 404: `Token counting is not supported` | OpenAI/Grok 分组或上游不支持 count_tokens | 只要主对话正常可忽略;否则换 Anthropic 分组 | | 非 Claude Code 客户端被拒 | 分组开启 `claude_code_only` | 用官方 Claude Code 客户端,或换非 only 分组 | | 模型列表不完整 | 网关模型发现默认关闭 | 设 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 后重启 | --- > 想把常用提示词固化成命令、用子代理做大范围探索?见 [Claude Code 进阶](#/claude-advanced)。具体任务怎么做,见 [实战场景库](#/recipes)。 --- # Codex 使用手册 装好并接上 Clomio 后([Codex 接入](#/codex)),这里是日常使用速查。 --- ## 启动方式 | 方式 | 命令 | 说明 | |------|------|------| | 交互模式 | `codex` | 进入对话界面 | | 带提示启动 | `codex "看看当前文件夹里有什么"` | 进界面并执行一句 | | 非交互(脚本/CI) | `codex exec "修掉 ESLint 报错,别改逻辑"` | 不进界面,直接出结果 | `codex exec` 加 `--full-auto` 可全自动执行,适合写进自动化流程。 --- ## 审批与沙箱:控制它的"动手"自由度 Codex 执行命令前会按你设的策略决定是否先问你。两个核心概念: - **审批策略**(`approval_policy`):`untrusted` / `on-request` / `on-failure` / `never`——何时停下来征求同意。 - **沙箱**(`sandbox_mode`):`read-only`(只读)/ `workspace-write`(可改工作区)/ `danger-full-access`(完全放开,慎用)。 日常推荐 `on-request` + `workspace-write`:既能动手又有确认。进界面后可用 `/approvals` 快速调整。详见 [Codex 配置详解](#/codex-config)。 --- ## 常用斜杠命令 进入界面后输入 `/` 触发(不同版本略有差异): | 命令 | 作用 | |------|------| | `/model` | 切换模型 / 推理强度(范围取决于你的[分组](#/api-key)) | | `/approvals` | 调整审批与沙箱策略 | | `/init` | 为项目生成 `AGENTS.md` | | `/compact` | 压缩当前对话,省 token | | `/new` | 开一个新会话 | | `/status` | 查看当前配置与会话状态 | | `/diff` | 查看本次改动的 diff | | `/mcp` | 查看已连接的 MCP 工具 | --- ## 项目说明:AGENTS.md Codex 会读项目里的 `AGENTS.md` 作为"项目说明书",从仓库根向下逐层合并。把构建/测试命令、代码规范、目录约定、"别碰哪些文件"写进去,它就更懂你的项目。 ```bash # 在项目根目录,首次运行 /init ``` 更多用法见 [Codex 进阶](#/codex-advanced)。 --- ## 给它文件和图片 - **引用文件**:不少版本支持在输入里用 `@` 提及文件名快速带入;也可以直接把文件内容复制粘贴进对话框。 - **图片**:把图片复制后在终端粘贴,或给出图片路径,让它分析截图/设计图。 --- ## 生成图片 Codex 可以直接生图,触发 `$imagegen` 并描述画面即可。需要先配好 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`;若提示工具不可用,可安装生图 skill。完整步骤见 [Codex 生图](#/codex-image)。 --- ## 推荐的 Codex 接入形态 如果你是按 Clomio / OpenAI-compatible 网关接 Codex,推荐把 Codex provider 配成 **Responses wire API**: ```toml model_provider = "clomio" model = "gpt-5.4" [model_providers.clomio] name = "Clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` 要点: - `base_url` 写到 API 版本根,也就是带 `/v1`,不要写到 `/v1/responses`。 - `wire_api = "responses"` 让 Codex 使用 OpenAI Responses 形状,适合工具调用、流式事件和 Codex 会话状态。 - `env_key` 建议用业务专属变量,如 `CLOMIO_API_KEY`;不要把多个工具都挤在 `OPENAI_API_KEY` 里,排障时更清楚。 - 控制台复制模板可能使用 `experimental_bearer_token` + `requires_openai_auth = true` 的自包含方式;长期配置建议改回 `env_key`。两种方式不要同时写。 - 不要同时写 `requires_openai_auth = true` 和 `env_key`；前者会走 Codex/OpenAI 认证链路并忽略 `env_key`。Clomio 推荐 `env_key`。 - provider/base URL/auth 相关配置放用户级 `~/.codex/config.toml` 或 profile 文件；项目 `.codex/config.toml` 里的 `model_provider`、`[model_providers.*]`、`base_url`、`env_key` 可能被 Codex 忽略。 - 分组要选 OpenAI/Codex/GPT 类分组;Claude-only 分组不支持 `/v1/responses`。 完整配置项仍以 [Codex 配置详解](#/codex-config) 为准。 --- ## 多套配置:Profile 给不同[网关线路](#/gateway-lines)或场景各建一个 profile,启动时切换: ```bash codex --profile crs ``` 配置写法见 [Codex 配置详解 · Profile](#/codex-config)。 --- ## MCP:接外部工具 ```bash codex mcp add context7 -- npx -y @upstash/context7-mcp # 添加 codex mcp --help # 查看所有子命令 ``` 会话里用 `/mcp` 查看已连接工具。CLI 与 IDE 扩展共用同一份 MCP 配置。 --- ## Responses 流式/WS 排障 看到 Codex 卡在流式输出或工具结果回传时,先分清入口: - HTTP/SSE: `POST /v1/responses`,看是否有 `stream: true`、`previous_response_id`、`function_call_output.call_id`。 - WebSocket: `GET /v1/responses` 只作为 Upgrade 入口,首帧必须是 `response.create` 类 payload;它不是查询历史响应的 REST 接口。启用 Codex WS v2 时同时需要 provider 里的 `supports_websockets = true` 和 `[features].responses_websockets_v2 = true`;不稳定时改成 `supports_websockets = false` 回落 HTTP/SSE。 - 续接:下一轮仍通过 `POST /v1/responses` 或 WS 首帧携带上下文/`previous_response_id`,不要请求“按 response id 查询”的 GET 路径。 - `previous_response_id` 必须是 Responses 返回的 `resp_*`。不要把 Claude Messages 的 `msg_*`、Chat Completions 的 `chatcmpl-*`、工具调用 id 或你自己生成的会话 id 填进去。 - HTTP 工具结果必须带原始函数调用的 `call_id`；如果你只保存了工具输出文本,没保存 `call_id` / item reference,就让 Codex/SDK 重新跑一轮或压缩上下文,不要手工伪造。 常见判断: | 现象 | 先查 | |------|------| | 400 提到 `function_call_output` | 工具输出是否带回原始 `call_id` | | 400 提到 `previous_response_id must be a response.id` | 是否把 `msg_*`、`chatcmpl-*` 或自定义 id 当成 `resp_*` 用 | | 400 提到 encrypted/signature | 是否跨账号/跨会话复用了旧 `previous_response_id` | | 流式没有最终事件 | SSE 是否出现 `response.failed` / `response.cancelled`,WS 是否被 close | | `No available accounts supporting model` | 除模型名外,还要查本地账号槽位、冷却、临时不可调度 | ## 卡顿 / 报错怎么办 - 网络卡顿:换条[网关线路](#/gateway-lines)(改 `base_url`),通常立刻见效。 - 鉴权 401 / 模型不存在:核对 `base_url`、密钥、分组与模型名,见 [故障排查](#/troubleshooting)。 --- > 具体任务怎么做,见 [实战场景库](#/recipes)。 --- # 实战场景库 这里是场景库总入口。原来集中在一个长页面里的内容已经拆成三类，方便按“工具使用 / API 接入 / 控制台操作”查找。 | 分类 | 适合你正在做什么 | 入口 | |---|---|---| | CLI 实战 | 用 Claude Code、Codex、Grok CLI 读代码、修 bug、写测试、开 PR、换线路 | [CLI 实战场景](#/cli-recipes) | | API 调用 | 用 OpenAI SDK / curl / Node.js 调 Responses、Chat、Images、Videos、Web Search、Embeddings、Usage | [API 调用场景](#/api-recipes) | | 控制台实操 | 用 AI Studio、图片图库、Prompt 模板、用量错误详情、工单、订阅、2FA、兑换码 | [控制台实操场景](#/console-recipes) | 通用心法：**先说目标，让 AI 反问你要信息**，而不是自己先把所有细节想全。一句万能开场： ```text 我想完成 [你的目标]。你希望我先提供哪些信息，好帮我一步步完成? ``` 常用排障入口： - Base URL 和 `/v1` 规则见 [Base URL 与 /v1 规则](#/base-url-matrix)。 - 真实报错对照见 [故障排查](#/troubleshooting)。 - 工具组合和分工见 [协同与全局规则](#/collab)。 - 外部经验、常见误区和 request_id 排障包见 [实战经验与避坑清单](#/field-guide)。 --- # CLI 实战场景 Claude Code、Codex、Grok CLI、worktree 与线路切换的实操模板。适合“我该怎么问、怎么让工具动手、怎么排查 CLI 配置”的场景。 相关配置见 [Claude Code](#/claude-code)、[Codex](#/codex)、[Grok](#/grok)、[Base URL 与 /v1 规则](#/base-url-matrix)。 --- ## 快速读懂一个陌生项目 进到项目目录、启动工具后,从宽到窄地问: ```text 给我一个代码库概览:用了什么技术栈、目录怎么组织。 ``` ```text 这个项目的认证(登录)是怎么处理的?涉及哪些文件? ``` ```text 从前端到数据库,把一次登录的完整流程讲一遍。 ``` 小技巧:先问大方向,再聚焦到具体模块;让它顺带列一份"项目术语表"。 --- ## 定位某个功能的代码 ```text 帮我找处理用户认证的相关文件。 ``` ```text 这些文件之间是怎么协作的? ``` 用项目里实际的业务词汇提问,命中更准。 --- ## 修 Bug 把报错**原样**发给它,越完整越好: ```text 我运行 npm test 时报了下面的错(贴完整报错 + 复现步骤): ... ``` ```text 给我几种修 user.ts 第 45 行这个空指针的方案,说明各自利弊。 ``` ```text 按你建议的方案改 user.ts,加上空值检查。 ``` 说明错误是偶发还是必现、贴上复现命令和堆栈,诊断会更准。 --- ## 重构旧代码 ```text 找出代码库里用了过时写法 / 废弃 API 的地方。 ``` ```text 建议怎么用现代写法重构 utils.js,保持原有行为不变。 ``` ```text 按上面的方案重构,然后跑测试确认行为没变。 ``` 要点:**小步、可测试地改**,每改一块就跑测试,不要一口气重写一大片。 --- ## 补测试 ```text 找出 notification 模块里没被测试覆盖的函数。 ``` ```text 给通知服务写测试,重点覆盖边界情况和报错分支。 ``` ```text 跑新写的测试,修掉失败的。 ``` --- ## 生成 Pull Request ```text 总结我对认证模块做的改动。 ``` ```text 帮我创建一个 PR。 ``` ```text 在 PR 描述里补充这次安全性改进的说明,以及怎么测试。 ``` 提交前自己过一遍它生成的内容,让它顺便指出潜在风险。 --- ## 写文档 ```text 找出 auth 模块里缺少注释的函数。 ``` ```text 给这些函数补上注释,风格按项目现有的来,带上用法示例。 ``` --- ## 用 Git 工作树并行多任务 需要同时推进多个任务、又想各自隔离时,用 Git worktree: ```bash # 为一个新分支建独立工作目录 git worktree add ../project-feature-a -b feature-a # 进去单独跑一个工具实例 cd ../project-feature-a claude # 或 codex ``` 每个工作树文件隔离、共享同一份 Git 历史,互不干扰。 --- ## 当成 Unix 工具用 非交互模式可以把 AI 接进脚本和管道: ```bash cat build-error.txt | claude -p '简明解释这个构建错误的根本原因' > 分析.txt ``` ```bash codex exec "检查与 main 分支的差异,只报告拼写错误,每条两行" ``` --- ## 先 curl,再 CLI CLI 报错时不要先改一堆配置。先用同一把 Key、同一模型、同一 Base URL 发最小请求,确认网关和分组可用。 OpenAI/Codex/Grok Responses: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $CLOMIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"控制台里的模型名","input":"ping","max_output_tokens":8,"store":false}' ``` Claude/Anthropic Messages: ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` 如果 curl 不通,先修 Key/分组/模型/Base URL;如果 curl 通而 CLI 不通,再查 CLI 实际读取的配置文件、环境变量和协议模式。 --- ## Claude Code:读代码、改代码、看状态 适合 Claude 分组 Key + `ANTHROPIC_BASE_URL=https://api.clomio.ai`。进项目目录后: ```bash export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的 Claude 分组密钥" claude ``` 常用开场: ```text 先不要改文件。请阅读这个仓库,告诉我入口、主要模块、测试命令和最容易踩坑的地方。 ``` ```text 我希望修复这个报错。请先复现并定位根因,再给最小修改方案: [贴完整报错和复现命令] ``` 如果 Claude Code 报认证或模型错误,先在 Claude 里跑 `/status`,确认 Base URL 是 `https://api.clomio.ai`,再检查密钥是否属于 Claude 分组。 --- ## Codex Responses:让 Codex 执行任务 适合 OpenAI/Codex 分组 Key + `base_url = "https://api.clomio.ai/v1"` + `wire_api = "responses"`: ```toml model_provider = "clomio" model = "控制台里的 Codex/OpenAI 模型名" [model_providers.clomio] name = "Clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` 任务写法: ```text 你不是独自工作。请只修改我指定的文件,不要回退或覆盖他人改动。先审计现状,再给我改动和校验命令。 ``` Codex 常用 `POST /v1/responses`;WebSocket 入口是 `GET /v1/responses`。不要自行拼响应详情查询路径。多轮 HTTP 调用要用下一次 `POST /v1/responses` 的 `previous_response_id`/工具结果关联。 非交互任务推荐显式选 profile 或一次性覆盖 provider,避免读错项目级配置: ```bash export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥" codex exec --profile clomio "先不要改文件,总结这个仓库的测试命令" # 或临时覆盖模型/供应商 codex -c model_provider=clomio exec "检查当前 diff 的潜在问题" ``` --- ## Grok CLI:干净环境排查 Grok 只用 Grok 分组 Key,不要混入旧 `OPENAI_*`: ```bash env -i PATH="$PATH" \ GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" \ XAI_API_KEY="你的 Grok 分组密钥" \ grok --model "控制台里的 Grok 对话模型" --prompt "ping" ``` 如果 GUI 或包装器固定测 `/v1/chat/completions`,Grok 分组失败是预期;用 `/v1/responses` curl 判断对话主链路。 --- ## 通用排障路径 按这个顺序排: 1. **安装失败**:确认下载域名是 `https://help.clomio.ai`,终端里关闭代理后重试。 2. **401/403**:密钥是否复制完整、是否选错分组、余额/订阅/API Key quota 是否耗尽。 3. **404**:路径和分组是否匹配;OpenAI-compatible 要带 `/v1`,Anthropic-compatible 不要手动多拼。 4. **model not found / unsupported**:先 `GET /v1/models`,使用列表里的模型名;不要自行拼模型详情查询路径。 5. **429**:触发并发、RPM 或 5h/1d/7d 金额限速;降低并发、等 reset_at 后再试。 6. **能 test 但业务失败**:用同一个 Key、同一个 Base URL、同一个模型发最小 curl,排除客户端配置差异。 --- ## 换线路不换协议 线路只改变网络入口,不改变协议。国内网络不稳时,把域名从 `api.clomio.ai` 换成 `sub.qazwc.com` 或 `crs.qazwc.com`,其余规则不变: | 场景 | 默认线路 | 换到三网优化 | |------|------|------| | Claude Code | `https://api.clomio.ai` | `https://crs.qazwc.com` | | Codex / OpenAI SDK / Grok | `https://api.clomio.ai/v1` | `https://crs.qazwc.com/v1` | | Hermes/OpenClaw Anthropic-compatible | `https://api.clomio.ai` | `https://crs.qazwc.com` | | Hermes/OpenClaw OpenAI-compatible | `https://api.clomio.ai/v1` | `https://crs.qazwc.com/v1` | 也就是说:换线路只替换域名,不要把 Claude 改成带 `/v1`,也不要把 OpenAI/Codex/Grok 改成不带 `/v1`。 --- --- # API 调用场景 OpenAI-compatible、Grok、Images、Videos、Web Search、Embeddings、Usage 与 Node.js SDK 的最小调用模板。适合把 Clomio 接入程序、脚本或服务。 完整参数见 [API 概述](#/api-usage)、[Responses](#/api-responses)、[Images](#/api-images)、[Videos](#/api-videos)、[Web Search](#/api-websearch)。 --- ## OpenAI SDK:Responses、Chat、图片、Embeddings OpenAI-compatible 客户端统一: ```python from openai import OpenAI client = OpenAI(api_key="你的 OpenAI/Codex 分组密钥", base_url="https://api.clomio.ai/v1") ``` Responses: ```python r = client.responses.create( model="控制台里的模型名", input="把下面这段日志总结为 3 个要点: ...", ) print(r.output_text) ``` Chat Completions: ```python r = client.chat.completions.create( model="控制台里的模型名", messages=[{"role": "user", "content": "写一个 curl 调试清单"}], ) print(r.choices[0].message.content) ``` 图片: ```python import base64 r = client.images.generate( model="控制台里的图片模型名", prompt="一张干净的 SaaS 控制台插画", size="1024x1024", ) open("out.png", "wb").write(base64.b64decode(r.data[0].b64_json)) ``` Embeddings: ```python r = client.embeddings.create( model="控制台里的 embedding 模型名", input=["第一段文档", "第二段文档"], ) print(len(r.data[0].embedding)) ``` 排错顺序:先 `GET /v1/models` 看列表,再发最小请求;不要自行拼模型详情查询路径。 --- ## Grok CLI:干净环境最小启动 Grok CLI 使用 Grok 分组 Key,Base URL 带 `/v1`。控制台模板可能给 `grok-build` 等示例模型,真实模型以分组开放列表为准。 ```bash export GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" export XAI_API_KEY="你的 Grok 分组密钥" # 排除 OPENAI_* / 旧 GROK_* 干扰的一次性启动 env -i PATH="$PATH" \ GROK_MODELS_BASE_URL="$GROK_MODELS_BASE_URL" \ XAI_API_KEY="$XAI_API_KEY" \ grok --model "控制台里的 Grok 对话模型" ``` 也可写入 `~/.grok/config.toml`: ```toml [endpoints] models_base_url = "https://api.clomio.ai/v1" [model.grok-build] model = "控制台里的 Grok 对话模型" env_key = "XAI_API_KEY" ``` --- ## Grok videos only:只做视频 视频能力只在 Grok 分组开放。Base URL 仍是 `https://api.clomio.ai/v1`,提交后按返回的任务 ID 轮询。新接入优先使用 xAI 官方字段 `duration`、`aspect_ratio`、`resolution`;旧客户端的 `seconds`、`size` 只作为兼容字段。 ```bash curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台里的 Grok 视频模型名", "prompt": "雨后城市街道,霓虹倒影,电影质感", "duration": 6, "aspect_ratio": "16:9", "resolution": "720p" }' ``` ```bash curl https://api.clomio.ai/v1/videos/video_xxx \ -H "Authorization: Bearer 你的 Grok 分组密钥" ``` 如果返回 404,通常是 Key 不在 Grok 分组、路径写错或分组未开放该模型;如果返回 403 `Video generation is not enabled for this group`,说明 Grok 分组未开视频能力;如果返回 429,创建端看上游 rate-limit/`Retry-After`,轮询端降低到 5~10 秒以上。 --- ## 查询 Key 用量、余额和限速 `GET /v1/usage` 可用来确认一个 Key 是否有效、余额/套餐剩余、API Key quota、5h/1d/7d 限速和模型用量: ```bash curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29' \ -H "Authorization: Bearer 你的密钥" ``` 看返回里的: - `mode: "quota_limited"`:这个 Key 配了独立额度或限速,重点看 `quota` 和 `rate_limits`。 - `mode: "unrestricted"`:没有 Key 级限制,重点看 `balance`、`subscription`、`remaining`。 - `usage.today.actual_cost` / `usage.total.actual_cost`:实际扣费口径。 --- ## Grok 搜索:让模型带联网信息回答 使用 Grok 分组 Key,Base URL 是 `https://api.clomio.ai/v1`。推荐主路径是 Responses tool,因为它能使用官方 `web_search` 参数并直接返回带引用的回答: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台里的 Grok 对话模型", "input": "检索今天 xAI Grok API 有哪些更新,并给出引用", "tools": [{"type":"web_search"}], "store": false }' ``` 高级搜索参数放在 `tools[]` 里,不是 `/v1/web_search` 顶层: ```json { "model": "grok-4.3", "input": "只检索 x.ai 域名,概括 Grok API Web Search 能力", "tools": [{ "type": "web_search", "filters": { "allowed_domains": ["x.ai"] }, "enable_image_search": true }], "store": false } ``` 只想拿 sources-list、不需要模型总结时,再用 Clomio 简化端点: ```bash curl https://api.clomio.ai/v1/web_search \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{"query":"今天 xAI Grok API 有哪些更新?","max_results":5}' ``` 不要用 Claude/OpenAI 分组 Key 调 Web Search;Web Search 走 Grok。 --- ## Grok / OpenAI 图片:生成一张图 图片端点走 OpenAI-compatible Base URL,即 `https://api.clomio.ai/v1`。Images 可用 OpenAI 分组或 Grok 分组,但参数习惯不同。 OpenAI 图片模型通常用 `gpt-image-*` + `size`: ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer 你的 OpenAI 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台里的 OpenAI 图片模型名", "prompt": "一张极简风格的终端 AI 助手图标,深色背景,蓝紫渐变", "size": "1024x1024" }' ``` Grok Imagine 通常用 `grok-imagine-*` + `aspect_ratio` / `n`,默认返回 URL: ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台里的 Grok 图片模型名", "prompt": "A futuristic city skyline at night", "n": 1, "aspect_ratio": "16:9" }' ``` 如果返回平台不支持或模型不存在,优先检查:Key 是否属于对应分组、模型名是否来自控制台、端点是否是 `/v1/images/*`。如果报 `images endpoint requires an image model`,说明实际请求落到的不是图片模型；请换控制台列出的图片模型，并带 `x-request-id` 提交工单。 --- ## Agent 客户端协议速查:Codex / Hermes / OpenClaw 接 Agent/CLI 前先用 curl 验证协议,再写客户端配置。 Codex 非交互执行: ```toml model_provider = "clomio" model = "控制台里的 Codex/OpenAI 模型名" [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` ```bash export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥" codex exec "阅读当前仓库,只输出构建和测试命令" ``` Hermes 按协议拆 provider: ```yaml custom_providers: - name: clomio-responses base_url: https://api.clomio.ai/v1 key_env: CLOMIO_API_KEY api_mode: codex_responses models: [{ id: gpt-5.4, context_window: 128000 }] - name: clomio-openai base_url: https://api.clomio.ai/v1 key_env: CLOMIO_API_KEY api_mode: chat_completions models: [{ id: gpt-5.4, context_window: 128000 }] - name: clomio-anthropic base_url: https://api.clomio.ai key_env: CLOMIO_CLAUDE_KEY api_mode: anthropic_messages models: [{ id: claude-sonnet-4-6, context_window: 200000 }] ``` OpenClaw 同样拆成 `openai-responses`、`openai-completions`、`anthropic-messages` 三个 provider,默认模型写 `provider/model`,不要把 Claude、Grok、GPT 混到一个 provider。 --- ## Node.js OpenAI SDK:最小可运行脚本 适合把 Clomio 接进自己的 Node.js 项目。OpenAI-compatible 一律带 `/v1`: ```bash npm install openai export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥" ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.CLOMIO_API_KEY, baseURL: "https://api.clomio.ai/v1", }); const response = await client.responses.create({ model: "控制台里的 OpenAI/Codex 模型名", input: "用三句话写一份上线前检查清单。", }); console.log(response.output_text); ``` 如果你要换线路,只替换域名并保留 `/v1`,例如 `https://crs.qazwc.com/v1`。不要改成 Claude 的根地址规则。 --- --- # 控制台实操场景 控制台 AI Studio、图片图库、Prompt 模板、用量错误详情、工单附件、兑换码、订阅、2FA 与邀请返利的操作模板。 控制台功能以当前页面和站点开关为准；入口不可见时不要假设一定开放。相关说明见 [控制台总览](#/console)、[AI Studio](#/console-ai-studio)、[用量明细](#/console-usage)、[订阅与余额](#/console-billing)、[邀请、工单与账号](#/console-account)。 --- ## 错误请求:带 request_id 排查 当客户端返回 4xx/5xx 时,先把这几项保存下来: - 完整 HTTP 状态码和响应体 - 响应头里的 `x-request-id` / `x-client-request-id`(如果有) - 你实际使用的 Base URL、端点、模型名、Key 分组 - 发生时间和是否换过线路 最小复现 curl 模板: ```bash curl -i https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的 OpenAI/Codex 分组密钥" \ -H "Content-Type: application/json" \ -d '{"model":"控制台里的模型名","input":"ping","max_output_tokens":1}' ``` 把输出里的 request_id 连同报错一起发工单,支持可以按请求精确定位。不要只贴“model not found”截图,也不要在不同 Key/不同线路之间混测后只保留最后一张图。 --- ## 控制台内置 AI 聊天:先验证模型再接 CLI 如果控制台里能看到 **AI 聊天** 入口,新手可以先用它做一次最小验证: 1. 选择你准备给 CLI/API 使用的分组和模型。 2. 发送 `ping` 或一句很短的问题。 3. 到「使用记录」确认这次请求有记录、扣费正常、模型名正确。 4. 再把同一个模型名填到 Claude Code、Codex、Grok 或 SDK 配置里。 这样能先排除“余额不足、模型名写错、分组未开放”的问题。详细功能见 [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio)。入口不可见时,直接用 `GET /v1/models` 和最小 curl 验证即可。 --- ## 控制台图片、画廊、Prompt 模板:从可见入口开始 如果控制台开放了相关入口,可以这样用: - **图片生成**:先在控制台选择开放的图片模型试一张图,再把同样的 prompt 和模型迁移到 `/v1/images/*` 或 OpenAI SDK。 - **画廊**:如果有画廊入口,把满意结果保存为参考,后续复用 prompt、尺寸、风格描述。 - **Prompt 模板**:如果有模板入口,先从“代码审查、Bug 定位、文档总结、图片描述”等模板改写,再复制到 CLI。 详情见 [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio);如果要安装或创作网页端技能,见 [技能市场与创作者中心](#/console-skills)。 注意能力边界不变:Images 可用 OpenAI 分组或 Grok 分组;视频能力仅 Grok;Embeddings 走 OpenAI;Web Search 仅 Grok。 --- ## 从 Key 弹窗复制到客户端配置 API Key 列表里的「使用 / 复制配置」适合快速生成本机配置，但复制后仍建议用最小 curl 验证协议： 1. 先确认 Key 绑定分组平台：Claude、OpenAI/Codex、Gemini、Antigravity 或 Grok。 2. 打开「使用」弹窗，选择对应 tab：Codex、Codex WS、Claude Code、Gemini CLI、Grok CLI 或 opencode。 3. 把配置写入用户级配置文件或当前 shell；不要把带明文 Key 的配置提交到仓库。 4. 用本文档对应工具页的最小 curl 验证 Base URL、端点和模型。 注意几个容易误解的点： - OpenAI/Codex 分组默认生成 Codex Responses / WS / opencode；只有该分组开放 Messages 兼容能力时，弹窗才会出现 Claude Code `/v1/messages` 兼容配置。 - Grok 弹窗只生成 Grok CLI env 与 `~/.grok/config.toml`，不代表 Videos 已启用；Videos 仍要用 Grok 视频分组并测 `/v1/videos/generations`。 - Antigravity tab 会按 Claude/Gemini 专用路径生成，不要把 `/v1` 套到 `/antigravity/...` 前缀前面。 - opencode、Hermes、OpenClaw 这类多 provider 客户端请按协议拆 provider，避免一个 Key 同时尝试 Claude Messages、OpenAI Responses 和 Grok Videos。 --- ## 用量错误详情 + 工单附件:一次把排查材料带全 如果控制台使用记录能打开错误详情,按这个清单处理: ```text 1. 复制 request_id / x-request-id 2. 复制状态码、错误摘要、模型名、端点 3. 截图保存 Base URL、Key 分组、发生时间 4. 用同一个 Key 和 Base URL 发最小 curl 复现 5. 如果工单入口支持附件,上传截图和 curl -i 输出 ``` 工单描述模板: ```text 问题: [一句话说明] 时间: [本地时间和时区] request_id: [从响应头或用量详情复制] Base URL: [例如 https://api.clomio.ai/v1] 端点: [例如 /v1/responses] Key 分组: [OpenAI/Codex/Grok/Claude] 模型: [控制台开放模型名] 复现: [最小 curl 或工具命令] ``` 有 request_id 时支持能更快定位单次请求;没有时,至少提供发生时间和完整响应体。 --- ## 兑换码、订阅、2FA、邀请返利:账户侧操作 这些功能如果在你的控制台入口可见,按页面提示操作即可: - **兑换码**:在兑换入口输入,提交后回到余额/套餐页确认是否到账。 - **订阅**:选择套餐后看清额度、周期、到期时间和可用分组;实际权益以控制台展示为准。 - **2FA/TOTP**:用认证器 App 扫码,输入 6 位验证码完成绑定;先保存恢复码再开启。 - **邀请返利**:复制邀请链接给新用户;返利比例、结算周期和有效期以入口当前规则为准。 如果入口不可见,不要假设一定有该功能;继续按已开放的 API Key、模型和线路使用即可。 --- > 报错看不懂?把完整截图发给还能用的那个工具继续问;两个都不方便时再借助第三方 AI。排查套路见 [故障排查](#/troubleshooting)。 --- # 实战经验与避坑清单 这页把公开平台经验帖、网关厂商帮助文档和 Clomio 当前公开能力整理成可直接照做的排查路径。外部帖子适合发现“大家常踩什么坑”,但最终以控制台实时分组和本帮助文档为准。 --- ## 先分清三件事 | 先问什么 | 为什么重要 | 错了会怎样 | |---|---|---| | 客户端说的是哪种协议 | Claude/Anthropic、OpenAI Responses、OpenAI Chat、Gemini 原生、Antigravity 的 Base URL 和请求体不同 | `/v1/v1/...`、404、401、模型不存在 | | 这把 Key 绑定什么分组 | 分组决定可用平台、模型、倍率、Images/Videos/Web Search 能力 | `... API is not supported for this platform` | | 工具的“检测连接”测哪个端点 | 很多 GUI 只测 `/v1/chat/completions` 或 `/v1/models` | 检测失败不代表 Responses、Messages 或 Videos 不可用 | 一句话记忆: - Claude Code / Anthropic-compatible:Base URL 填 `https://api.clomio.ai`,请求落到 `/v1/messages`。 - Codex / OpenAI-compatible / Grok:Base URL 填 `https://api.clomio.ai/v1`,客户端再拼 `/responses`、`/chat/completions`、`/images/*` 等。 - Gemini 原生和 Antigravity:Base URL 填根地址,请求路径自己带 `/v1beta` 或 `/antigravity/...`。 - Videos 只用 Grok 分组;Images 可用 OpenAI 或 Grok 分组。 --- ## 公开经验沉淀成 8 条规则 ### 1. Claude Code 接网关时,token 是“网关 Key”,不是 Anthropic 官方 Key 公开网关文档和帖子反复强调:Claude Code 要改 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`。`ANTHROPIC_AUTH_TOKEN` 填 Clomio Key;不是把 Anthropic 官方 key 填进 Clomio。 ```bash export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的Clomio密钥" claude ``` 如果用 VS Code 扩展,从 Dock/开始菜单启动时可能不继承 shell 环境变量。优先写 `~/.claude/settings.json` 的 `env` 字段,然后彻底退出 VS Code 再打开。 排查费用时不要把请求里的客户端标记当成余额扣费依据；以控制台用量页的实际消费、缓存和计费明细为准。 参考: - Claude Code 环境变量官方页: - LiteLLM Claude Code quickstart: - Requesty Claude Code 环境变量说明: - X 上公开经验也常见同一结论:设置 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 后重新登录/启动客户端。 详见 [Claude Code](#/claude-code)、[VS Code 集成](#/vscode)。 ### 2. Claude Code 需要 Anthropic Messages 形状,不是 OpenAI Chat 形状 只支持 OpenAI `/v1/chat/completions` 的服务不能直接喂给 Claude Code,除非中间有 Anthropic Messages 兼容桥。Clomio 的 Claude 分组原生走 `/v1/messages`;OpenAI/Grok 分组在当前分组开放 Messages 兼容能力时也可走 `/v1/messages` 转换。 快速验证: ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' ``` 参考 vLLM 对 Claude Code 的解释:Claude Code 发送的是 Anthropic Messages API 形状:。 ### 3. Codex 的 provider/auth 配置放用户级或 profile,不要依赖项目级覆盖 Codex 官方配置说明中,project `.codex/config.toml` 只在 trusted project 加载,并且会忽略 `model_provider`、`model_providers`、`openai_base_url` 等 provider/auth 类键。Clomio 接入推荐写在 `~/.codex/config.toml` 或 `~/.codex/.config.toml`: ```toml model_provider = "clomio" model = "gpt-5.4" preferred_auth_method = "apikey" [model_providers.clomio] name = "clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` `env_key` 是环境变量名,不要把真实 Key 字符串直接写在 `env_key` 里。 参考: - OpenAI Codex Config basics: - OpenAI Codex Config reference: - Portkey Codex 集成示例也使用 `model_provider` + `[model_providers.*]` + `base_url` + `env_key`: 详见 [Codex](#/codex)、[Codex 配置详解](#/codex-config)。 ### 4. Codex/现代 OpenAI 模型优先走 Responses,不要被 Chat Completions 检测误导 Codex 的 `wire_api = "responses"` 最终请求 `POST /v1/responses`。`GET /v1/responses` 是 WebSocket 入口,不是按 id 查询历史;当前没有 `GET /v1/responses/{id}`。如果工具或 GUI 只会用 `/v1/chat/completions` 测连接,可能把 Responses 可用的 Key 误判为不可用。 快速验证: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":1}' ``` 如果遇到 `function_call_output requires call_id...`、`previous_response_not_found`、`invalid_encrypted_content`,不要先换线路;先看 [Responses](#/api-responses) 和 [故障排查](#/troubleshooting) 的续接/工具结果章节。 ### 5. Grok 是 OpenAI-compatible Responses 能力,但不是所有 OpenAI 端点都能用 Grok 分组在 Clomio 中支持: - `POST /v1/responses` - `/v1/images/*` - `/v1/videos/*` - `/v1/web_search` 不支持: - `/v1/messages` - `/v1/chat/completions` - `/v1/embeddings` 所以 Cherry Studio、OpenClaw、Hermes 或其它 GUI 如果固定拿 Chat Completions 测 Grok,失败是正常的;请用 `/v1/responses` 或 Grok 文档里的 curl 单独验证。 Grok 常见 404/429 判定树: | 现象 | 优先判断 | |---|---| | `404 endpoint not found` | Base URL 不要填完整 endpoint;应是 `https://api.clomio.ai/v1`,不是 `/v1/responses` | | `/v1/v1/...` | 客户端和用户都加了 `/v1`,删掉一层 | | `/v1/chat/completions` 404/unsupported | Grok 分组在 Clomio 不走 Chat,换 Responses 客户端或用 OpenAI 分组测 Chat | | `/v1/messages` 404/unsupported | Grok Key 被 Claude/Anthropic 客户端使用 | | `/v1/videos/*` 404 | 非 Grok 分组、视频能力未开或公开路径写错;新接入只写带 `/v1` 的 Videos 路径 | | `429` | 先降低并发/轮询；按 `Retry-After` 和 rate-limit headers 做 backoff；持续异常带 `x-request-id` 提交工单 | 参考: - xAI Quickstart: - xAI Web Search tool: - AI SDK xAI provider 对 Responses/server-side tools 的说明: 详见 [Grok](#/grok)、[Web Search](#/api-websearch)、[Videos](#/api-videos)。 ### 6. Videos 是 Grok-only;不要把 OpenAI Images / Codex 生图扩展成视频能力 公开 xAI/Grok 文档和 Grok Imagine 发布说明都把 video generation/editing 放在 Grok/xAI 能力下。Clomio 将 Videos 限制为 Grok 分组；OpenAI/Codex 分组调 `/v1/videos*` 会返回 `Videos API is not supported for this platform`。 ```bash curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的Grok分组密钥" \ -H "content-type: application/json" \ -d '{"model":"控制台显示的视频模型ID","prompt":"one second test"}' ``` 参考: - xAI Grok Imagine API: - Promptfoo xAI provider 能力总览: 详见 [Videos](#/api-videos)。 ### 7. Hermes/OpenClaw/CC Switch 这类多客户端工具,最容易错在“协议模式字段” 外部 issue 中常见问题不是 Key 错,而是工具把 Anthropic 请求发到 OpenAI endpoint,或把 OpenAI Responses provider 默认成 Anthropic Messages/OpenAI Chat。Clomio 文档里的 `api_mode` / `api` 字段要和 Base URL、分组一起看: | 工具 | OpenAI-compatible | Anthropic-compatible | |---|---|---| | Hermes | `api_mode: codex_responses` 或 `chat_completions` | `api_mode: anthropic_messages` | | OpenClaw | `api: "openai-responses"` / `openai-completions` | `api: "anthropic-messages"` | | CC Switch | Codex/OpenAI 供应商带 `/v1` | Claude 供应商不带 `/v1` | 普通 Base URL 填“服务根/版本根”，不要填完整 endpoint:例如不要把 `https://api.clomio.ai/v1/responses`、`/v1/chat/completions`、`/v1/messages` 填到 Base URL。只有工具明确启用 Full URL / 完整端点模式时才填完整 endpoint；Clomio 常规接入不需要。 多客户端工具还要看“谁在拼路径、谁在选 provider”: - CC Switch 的 Full URL 模式是高级例外,常规 Clomio 接入不要开。 - OpenClaw 的 `api` 有更多版本相关枚举,但 Clomio 常用只选 `anthropic-messages`、`openai-completions`、`openai-responses`;`provider/model` 第一段是 OpenClaw provider,不一定会原样发给上游。 - Hermes 中 `base_url` 比 `provider` 更直接;某个槽位写了 `base_url`,就按这个 URL 直连。辅助模型、vision、background review、fallback 也要单独检查。 - GUI 的“检查连接”是探针,不是能力证明。通过不代表 Images/Videos/Web Search/Embeddings 都能用;失败也不代表 Responses 或 Messages 不可用。 参考: - Hermes providers 文档: - Hermes `api_mode` 切换 issue: - OpenClaw Anthropic 请求打到 OpenAI endpoint 的 issue: - OpenClaw Responses 支持相关 issue: - CC Switch README: 详见 [Hermes](#/hermes)、[OpenClaw](#/openclaw)、[CC Switch](#/cc-switch)。 ### 8. 中转站排障要先拿 request_id,不要只发“失败了” 同一段错误可能出现在三个层面: - 客户端本地配置错误:Base URL、协议模式、环境变量没生效。 - Clomio 本地拒绝:分组不支持端点、Key 额度/IP/过期、请求体超限、风控拦截。 - 上游拒绝或调度失败:模型不支持、账号临时限流、`No available accounts`、上游 400/429/5xx。 最小排障包: ```bash curl -i https://api.clomio.ai/v1/models \ -H "Authorization: Bearer 你的密钥" curl -i https://api.clomio.ai/v1/usage \ -H "Authorization: Bearer 你的密钥" ``` 如果是具体对话失败,请同时提供: - `request_id` / `x-request-id`；如果客户端自己传了 request id，也带上 `client_request_id` - Base URL 与真实路径 - 模型名和 Key 名称/分组 - 是否流式 - 完整 HTTP 状态码和响应体末尾；SSE 里即使 HTTP 200，也要保留末尾的 `event: response.failed` / `response.cancelled` 支持排查时通常会先看响应头 `X-Request-Id` / `x-request-id`，再结合 `client_request_id` 和时间窗口定位。如果你只给“200 但工具失败”，没有 SSE 末尾事件，往往无法判断是客户端取消、上游失败还是网关容灾。详见 [故障排查](#/troubleshooting)。 Grok 429 排障时先看客户端响应里的 `Retry-After` / rate-limit headers，再对照 `/v1/usage` 中当前 API Key 的余额、quota、5h/1d/7d 限速和实际扣费。若余额和 Key 限额都正常但仍持续 429，请保留 `x-request-id`、时间和错误体提交工单。 --- ## 场景化用例 ### 场景 A:同一把 Key 在 Claude Code 可用,在 Codex 不可用 1. 看 Key 分组。如果是 Claude/Anthropic 分组,这是预期:Claude Code 走 `/v1/messages`,Codex 走 `/v1/responses`。 2. Codex 请换 OpenAI/Codex 分组 Key,Base URL 改 `https://api.clomio.ai/v1`。 3. 如果 Key 是 OpenAI 分组但 Claude Code 不通，只有当前分组明确开放 Messages 兼容能力时才继续排查；否则不要拿 OpenAI Key 跑 Claude Code。 ### 场景 B:GUI 检测失败,但 curl 可以调通 1. 抓 GUI 实际测的路径。若它测 `/v1/chat/completions`,不要用它判断 Grok Responses/Videos。 2. 用本文的 curl 验证真实端点。 3. 如果 GUI 没法改协议模式,给该 GUI 单独建一个 OpenAI Chat 可用分组 Key,不要混用 Grok/Claude Key。 ### 场景 C:从国外服务器搬到国内网络后卡顿 1. 只换线路域名,不要改变协议规则。 2. OpenAI/Codex/Grok:`https://crs.qazwc.com/v1`。 3. Claude/Anthropic:`https://crs.qazwc.com`。 4. Gemini/Antigravity:根地址 + 原路径 `/v1beta...` 或 `/antigravity...`。 ### 场景 D:图片可用,视频不可用 1. Images 支持 OpenAI 或 Grok;Videos 仅 Grok。 2. 检查你调的是 `/v1/images/*` 还是 `/v1/videos*`。 3. 视频模型名以 Grok 视频分组控制台显示为准。 4. OpenAI/Codex 生图的 `image_generation` tool 不等于视频能力。 ### 场景 E:终端 Claude Code 能用,VS Code 扩展仍跳登录 1. 分层验证:系统终端 `claude`、VS Code 内置终端 `claude`、侧边栏 Claude Code 扩展分别看。 2. 如果前两层可用但扩展失败,看 Output / Developer Console 的真实 host 和路径,确认是否仍在打官方 Anthropic 或 `/v1/v1/messages`。 3. 从已 export 的终端运行 `code .`,或在 VS Code 用户设置里写 `claudeCode.environmentVariables`;Remote SSH / Dev Container / WSL 要写远端 home。 4. 不要因为扩展跳登录就立刻判断 Clomio Key 失效。 --- ## 公开来源索引 这些链接用于解释“为什么这些坑常见”;Clomio 的最终行为仍以本文档和当前服务为准。 - Claude Code 环境变量: - Claude Code settings: - LiteLLM Claude Code gateway: - vLLM Claude Code integration: - OpenAI Codex config basics: - OpenAI Codex config reference: - xAI Quickstart: - xAI Web Search: - xAI Rate Limits: - xAI Grok Imagine API: - Cherry Studio custom provider: - Hermes providers: - CC Switch: --- ## 进阶指南 # Claude Code 进阶 跑通基础使用后,这几项能力能让 Claude Code 真正融入你的工作流。本页同时补充 Clomio/sub2api 网关下的兼容要点。 --- ## CLAUDE.md:让 Claude 记住项目规则 `CLAUDE.md` 是项目的说明书,Claude 每次开始会话都会读它。把项目的构建命令、代码规范、目录约定写进去,就不用每次重复交代。 - **生成**:在项目根目录运行 `/init`,Claude 会自动扫描并起草一份。 - **分层**:`~/.claude/CLAUDE.md`(全局)放你个人的通用偏好,对所有项目生效;每个项目目录下的 `CLAUDE.md` 放该项目专属规则。 - **别塞太满**:只写当前任务真正需要的内容。大段参考资料单独放文件,在 CLAUDE.md 里写明“需要时去看 xxx 文件”即可,避免拖慢、干扰判断。 - **别放密钥**:仓库内 `CLAUDE.md` 往往会提交到 git,不要写 Clomio key、cookie、token。 > 一句话: `CLAUDE.md` 写得好,后面少纠正很多次。 --- ## 自定义命令 / 技能 把你常输入的一整段提示词,固化成一个斜杠命令,下次一个 `/名字` 就能调用。 - 机制很简单:在 `.claude/commands/` 下放一个 Markdown 文件,文件名就是命令名,正文就是被注入的提示词。支持 YAML frontmatter 设置描述、允许的工具、模型、以及 `$ARGUMENTS` / `$1` 参数。 - 有真实逻辑或带配套文件的,放 `.claude/skills/<名字>/SKILL.md` 更合适;只是“插入一段提示词”的,用命令即可。 实用建议: - **用过痛了再做**:不要提前造一堆命令,等你真的反复手敲同一段时再固化。 - **一个命令一个明确产物**:`/pr` 就开 PR、`/release-notes` 就写发布说明。 - **把正文当契约**:写清先读什么、做什么、跳过什么、输出什么格式。 - **配好 `allowed-tools`**:否则需要跑 `gh` 十次的命令会弹十次授权。 - **别把密钥写进正文**:`.claude/commands/` 会进 git,密钥放环境变量或 `settings.local.json`。 --- ## 子代理:保护主对话的上下文 子代理(subagent)是另开的一个 Claude 会话,有独立的上下文窗口,适合做大范围探索或并行任务而不污染主对话。 - 定义在 `.claude/agents/`(项目)或 `~/.claude/agents/`(个人),Markdown + YAML frontmatter。 - **让它们只读**:推荐给探索型子代理只保留只读工具,把改文件的活交回主会话。 - **按成本分层**:用较便宜模型做第一遍粗筛,只把可疑文件交给更强模型复核。 - **并行要避开同文件编辑**:多人或多 worker 改文档/代码时,先约定文件所有权,不要让子代理直接写同一批文件。 如果给子代理单独指定模型,可在配置中设置: ```json { "env": { "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6" } } ``` --- ## MCP 与 tool search MCP 能让 Claude Code 接数据库、浏览器、文档检索、工单系统等外部能力。基础命令: ```bash claude mcp add <名字> <命令> [参数...] claude mcp list claude mcp get <名字> claude mcp login <名字> claude mcp remove <名字> ``` 自定义 `ANTHROPIC_BASE_URL` 下要特别注意 tool search: - 官方 Claude Code 默认启用按需 tool search,但当 `ANTHROPIC_BASE_URL` 指向非官方 host 时,默认会退回更兼容的加载方式。 - 原因是很多网关/代理不会完整透传 `tool_reference` blocks 和对应 beta header。 - 如果 Clomio 线路或你的自建代理已确认支持,可设 `ENABLE_TOOL_SEARCH=true`;否则优先用 `auto` 或 `false`。 推荐配置: ```json { "env": { "ENABLE_TOOL_SEARCH": "auto" } } ``` 排障: - `/mcp` 看服务器是否连接、是否有工具数。 - `claude mcp get <名字>` 看命令、环境变量、认证状态。 - HTTP/SSE MCP 认证失败时用 `claude mcp login <名字>`。 - 工具很多导致首轮很慢时,先 `ENABLE_TOOL_SEARCH=auto:5` 或 `false`。 - 强开 `ENABLE_TOOL_SEARCH=true` 后若 400 报 `tool_reference`、`anthropic-beta`、未知字段,说明代理/上游没有完整兼容,改回 `auto` 或 `false`。 --- ## 网关兼容与 sub2api 真实路由 Claude Code 接 Clomio 时,应把它当作 Anthropic Messages 客户端: ```text ANTHROPIC_BASE_URL=https://api.clomio.ai Claude Code -> POST /v1/messages Claude Code -> POST /v1/messages/count_tokens # 可选 token 估算 ``` 不要把 OpenAI `/v1/responses` 写成 Claude Code 主路径。sub2api 当前 `/v1` 路由会按 API Key 绑定分组的 `platform` 分流: | key 绑定分组平台 | `/v1/messages` 行为 | `/v1/messages/count_tokens` 行为 | |------------------|---------------------|----------------------------------| | `anthropic` | 走 Anthropic/Claude 网关主路径 | 校验余额/订阅后转发;不计并发、不记使用量 | | `openai` | 只有当前分组开放 Messages 兼容能力时才转 OpenAI 兼容调度 | 返回 404,客户端本地估算 | | `grok` | Messages API 直接 404 | 返回 404 | | `antigravity` / `kiro` 等 | 按服务端能力转发或委派 | 不支持时返回 404 让客户端 fallback | 其他真实行为: - **未分组 Key**:生产使用不建议空分组；若当前站点不允许未分组 Key，网关会按 Anthropic 错误格式返回 403。 - **分组平台是入口分流依据**:同一根地址 `/v1` 下,不是靠客户端路径猜平台,而是看 Key 绑定的分组。 - **Claude Code only**:这类分组要求请求来自 Claude Code。非 Claude Code 客户端可能会被拒绝。 - **Anthropic API key passthrough**:Anthropic APIKey 账号可开启透传,此时上游鉴权使用 `x-api-key`;对 Claude Code 接入 Clomio 的用户侧 key,仍推荐 `ANTHROPIC_AUTH_TOKEN`。 - **辅助端点**:真实 Claude Code 还可能访问 `/api/claude_cli/bootstrap`、`/api/claude_code/user_settings`、`/api/event_logging/batch` 等非 Messages 辅助端点。sub2api 对这些端点有 stub/drop/可选 forward,避免客户端因辅助请求失败影响主对话。 --- ## 企业网关、认证与代理细节 官方 Claude Code 网关文档把 `ANTHROPIC_BASE_URL` 定义为“指向网关”的变量;凭据可以来自 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`apiKeyHelper` 或已登录会话。接 Clomio 时推荐显式设置 `ANTHROPIC_BASE_URL=https://api.clomio.ai` 加一个网关 key,否则“只改 base URL、不改凭据”可能仍在用本机保存的 claude.ai 登录。 网络代理按标准环境变量走: ```bash export HTTPS_PROXY=http://127.0.0.1:7890 export NO_PROXY="localhost,127.0.0.1" ``` Claude Code 官方说明不支持 SOCKS 代理;如需 SOCKS,先在本机转成 HTTP/HTTPS 代理再给 `HTTPS_PROXY`。 ## 几个高频操作 | 操作 | 命令 / 快捷键 | |------|--------------| | 查看当前网关/凭据 | `/status` | | 切换模型 | `/model`(方向键选,回车确认) | | 压缩当前对话 | `/compact` | | 清空对话 | `/clear` | | 新开对话 | macOS `Command + N` / Windows `Ctrl + N` | | 误操作 | 先 `Esc`,不行再 `Ctrl + C` | | 任务像卡住了 | `Ctrl + O` 看 background 输出,再按一次切回 | | 检查安装 | `claude doctor` | --- ## 发文件 / 图片给 Claude 不用手敲完整路径:在文件管理器里复制文件,回到终端对话框粘贴即可。图片同理,粘贴后 Claude 能直接看。 --- ## 网关问题快速定位 ```bash # 1. base URL 必须是根地址 printf '%s\n' "$ANTHROPIC_BASE_URL" # 2. 看是否混用了两种凭据 env | grep '^ANTHROPIC_' # 3. 直接打 Claude Code 主路径 curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' # 4. 可选:验证 token 估算端点;404 不一定影响主对话 curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages/count_tokens" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"ping"}]}' ``` 常见结论: - curl 到 `/v1/messages` 401:凭据变量/密钥错。 - curl 到 `/v1/messages` 403 且提示未分组:key 没绑分组。 - `/status` 没有 `Anthropic base URL`:变量没有传到 Claude Code 进程。 - `/status` 显示 claude.ai 登录而不是 token/API key:清理冲突变量或 `/logout` 后重试。 - 400 提到未知 beta/字段:先设 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`,并关闭或降级 tool search。 > 想换更快的网关线路?见 [网关线路](#/gateway-lines)。配置层面的问题见 [Claude Code 接入](#/claude-code)。 --- # Codex 进阶 掌握这几项,Codex 能更好地贴合你的项目与工作流。 --- ## AGENTS.md:项目指令 `AGENTS.md` 是 Codex 版的项目说明书,任务开始前会被读取。Codex 会**从仓库根目录向下逐层合并** AGENTS.md,越靠近当前目录的优先级越高。 - **快速生成**:首次在项目里运行 `/init`,Codex 会起草一份。 - **放什么**:项目的构建/测试命令、代码规范、目录约定、"别碰哪些文件"等。 - **大小上限**:合并后的指令有字节上限(默认 32 KiB,由 `project_doc_max_bytes` 控制),内容多时可在 config 里调大,改完重启 Codex 生效。 --- ## config.toml:配置与 Profile 除了 [Codex 接入](#/codex) 里的基础配置,`config.toml` 还支持分层与多套切换。 - **Profile(多套配置)**:用 `--profile 名字` 启动时,Codex 先读 `~/.codex/config.toml`,再叠加对应 profile 的配置。适合在多个供应商/线路间切换——比如给 Clomio 的不同[网关线路](#/gateway-lines)各建一个 profile。 - **项目级配置**:项目目录下的 `.codex/config.toml` 只在 trusted 项目中加载,并从项目根到当前目录逐层叠加。团队可共享 AGENTS/rules、沙箱、MCP、hooks 等不含凭据的规则;`model_provider`、`[model_providers.*]`、`base_url`、`env_key`、`experimental_bearer_token`、`requires_openai_auth` 这类 provider/auth 配置请放用户级或 profile 文件,不要提交到仓库。受管环境配置了 requirements 时,危险审批/沙箱组合可能被禁止。 - **推理强度**:`model_reasoning_effort` 可设 `low` / `medium` / `high`,越高越细致但越慢越费 token。 --- ## Responses / WS 排障速查 Codex 默认走 OpenAI Responses,在网关上最常见的是两类入口: | 入口 | 用途 | 注意 | |------|------|------| | `POST /v1/responses` | 普通 Responses 请求、SSE 流式、工具调用 | 多轮续接用请求体里的 `previous_response_id` | | `GET /v1/responses` | Codex Responses WebSocket v2 入口 | 这是 WS/升级连接入口,不是 HTTP 查询历史响应 | 不要把排障文档写成“按 response id 发 GET 查询历史”:当前 OpenAI/Clomio Codex 路径不是这么查历史响应的。需要续接时,客户端会在下一次 `POST /v1/responses` 里带 `previous_response_id`,或由 Codex 自己维护会话。 工具调用相关的 400 优先看请求体形状: - HTTP `function_call_output` 必须带回模型给出的 `call_id`，并且要有能匹配该 `call_id` 的 item 引用；缺少这些字段会直接返回 400。 - `invalid_encrypted_content`、`thinking_signature_invalid` 一般不是“模型不支持 Responses”,而是上游拒绝了旧会话里的加密内容/持久项引用;排查时看是否误用了别的账号、别的会话或过期的 `previous_response_id`。 - 如果流式请求中途失败,Responses SSE 终止事件应看 `event: response.failed` 或 `event: response.cancelled`,不要按 Chat Completions 的 `[DONE]` 习惯判断。 - `No available accounts supporting model` 不一定等于模型永久不可用;也可能是临时限速、额度或并发导致。状态码也有提示:`404 model_not_found` 更偏“当前分组没有该模型”,`503 No available accounts` 更偏“服务暂时不可用”。 - HTTP 手写工具结果不能只带 `previous_response_id + function_call_output`;还需要原始 `call_id` 和可匹配的 `item_reference`。如果有 `function_call_output`,网关不会为了重试而盲删 `previous_response_id`,避免破坏工具上下文。WS v2 会维护更多上下文,但 `store:false` 或跨轮工具输出仍要求能匹配原始工具调用。 实操建议:先拿到请求 ID,再按顺序查请求路径、请求体是否 `stream:true`、是否有 `previous_response_id` / `function_call_output.call_id` / `item_reference`、SSE 终止事件。若是 WS 问题，注意区分“新请求可以继续使用同一个 session”与“旧连接已经关闭”。 --- ### Responses 路由对应关系 公开入口包括 `POST /v1/responses`、`POST /v1/responses/*subpath` 和用于 WebSocket Upgrade 的 `GET /v1/responses`。没有按 response id 发 GET 的历史查询路由。普通 HTTP GET 过鉴权后应是 426 WebSocket upgrade required。图像能力可在 OpenAI 分组和 Grok 分组走 `/v1/images/generations`、`/v1/images/edits`。视频能力仅在 Grok 分组开放。 ## MCP:接入外部工具 MCP(Model Context Protocol)让 Codex 能调用外部工具/数据源(查文档、操作浏览器、读数据库等)。配置就放在 `config.toml` 里,**CLI 和 IDE 扩展共用同一份**。 两种添加方式: ```bash # 方式一:命令行添加(以 context7 文档检索为例) codex mcp add context7 -- npx -y @upstash/context7-mcp # 查看所有子命令 codex mcp --help ``` ```toml # 方式二:在 config.toml 里手写一个 server [mcp_servers.my-db] command = "/usr/local/bin/my-mcp-server" env = { DB_URL = "postgres://..." } timeout_secs = 30 ``` 会话里用 `/mcp` 查看已连接的工具。常见可接入的有文档检索、Playwright(浏览器)、GitHub 等。 --- ## 非交互 / 脚本化:`codex exec` `exec` 子命令让 Codex **不进交互界面、直接出结果**,适合写进脚本或 CI: ```bash codex exec --full-auto "修掉所有 ESLint 报错,不要改业务逻辑" ``` --- ## 切换线路与分组 - **卡顿 / 不稳定** → 换[网关线路](#/gateway-lines):改 `config.toml` 里 `base_url`。 - **换模型能力** → 改 `config.toml` 里 `model`,或用 profile 切换。 - **更便宜 / 不同模型** → 控制台给密钥换分组。 --- > 基础安装与接入见 [Codex 接入](#/codex);报错排查见 [故障排查](#/troubleshooting)。 --- # Codex 生图 Codex 支持在对话里直接生成图片。用法是触发 `$imagegen`,把你的画面描述交给它。 --- ## 一、配置环境变量 生图走的是 OpenAI 的图像接口,需要在环境变量里按**标准字段名**配好地址和密钥: | 变量 | 值 | |------|-----| | `OPENAI_BASE_URL` | `https://api.clomio.ai/v1` | | `OPENAI_API_KEY` | 你的密钥 | **macOS / Linux(写进 `~/.zshrc` 或 `~/.bashrc` 永久生效):** ```bash export OPENAI_BASE_URL="https://api.clomio.ai/v1" export OPENAI_API_KEY="你的密钥" ``` **Windows(PowerShell,永久):** ```powershell [Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.clomio.ai/v1", "User") [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的密钥", "User") ``` > 地址可换成另外两条[线路](#/gateway-lines)的 `/v1`,如 `https://crs.qazwc.com/v1`。改完**重开终端**再启动 Codex 生效。 --- ## 二、使用 在 Codex 对话里触发 `$imagegen`,描述你要的画面,例如: ```text $imagegen 一只在钢琴上弹奏的橘猫,扁平插画风格,浅色背景 ``` 它会调用图像模型生成图片。 --- ## 二点五、两条生图路径别混淆 Codex 生图在网关里可能走两条不同路径,排障时先确认是哪一条: | 路径 | 典型入口 | 选模型方式 | 适合场景 | |------|----------|------------|----------| | Images API 原生路径 | `POST /v1/images/generations`、`POST /v1/images/edits` | 请求里的 `model` 是 GPT Image 模型,如 `gpt-image-2` | 单次生成/编辑、兼容 OpenAI Images API 的客户端 | | Responses image tool | `POST /v1/responses` + `tools:[{"type":"image_generation"}]` | `model` 是文本/主线模型,图像由内置 `image_generation` tool 执行 | Codex 对话内生图、多轮编辑、和工具调用同一轮完成 | 所以: - `/v1/images/*` 不是永远同一条上游路径：OpenAI **API-key** 账号通常走原生 Images API；OpenAI **OAuth/Codex** 账号会桥到 `/v1/responses` 的 `image_generation` tool；Grok OAuth 图片走 xAI/Grok images 兼容路径，不是 OpenAI Responses bridge。 - 用 `/v1/images/*` 时,`model` 要是图像模型;如果账号模型映射把 `gpt-image-2` 改成文本模型,上游会按 Images 端点报错。 - 用 `/v1/responses` 的 `image_generation` tool 时,`model` 不应写 `gpt-image-2`;应写支持工具的主线文本/多模态模型,让工具自己调用 GPT Image 能力。分组的 `openai_image_main_model` / image route 会影响 OAuth bridge 用哪个主模型；默认常见主模型不是 inbound 的 `gpt-image-*`。 - Clomio 的 OpenAI 图像能力只写 Images / Responses;不要把 Grok-only 的 `/v1/videos/*` 当成 OpenAI/Codex 能力写进这里。 - `OPENAI_BASE_URL` 仍然写带 `/v1` 的根地址,客户端或工具会自己拼 `/responses` 或 `/images/*`。 ### Images API 原生 curl 文生图: ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "content-type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "一张白底产品海报,主体是一只橘猫咖啡杯", "size": "1024x1024" }' ``` 图片编辑 multipart: ```bash curl https://api.clomio.ai/v1/images/edits \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F model=gpt-image-2 \ -F prompt="把背景换成浅灰色摄影棚" \ -F image=@input.png ``` ### Responses image tool 示例 ```json { "model": "gpt-5.4", "input": "生成一张白底产品海报,主体是一只橘猫咖啡杯", "tools": [{ "type": "image_generation", "size": "1024x1024" }], "tool_choice": { "type": "image_generation" } } ``` `image_generation_call` 的结果通常包含 base64 图片;多轮编辑可以继续带 `previous_response_id`。 注意三件事不要混淆: - `tools:[{"type":"image_generation"}]` 是能力声明;真正要求本轮生图通常要加 `tool_choice:{"type":"image_generation"}` 或让请求模型/意图明确进入图片路径。 - Codex bridge 开启时,普通 Responses/Codex 请求可能自动注入 image tool 和 instructions;如果分组未开图像或当前账号不支持,仅声明的 tool 可能被剥离后走文本账号,显式生图意图则会被 403 拒绝。 - 网关会规范化旧字段,并可能把顶层 image-only model 改成主文本模型、把图片模型放入 tool;排查时看 request_id 下的实际上游模型,不要只看客户端原始 body。 --- ## 平台能力边界 | 能力 | OpenAI/Codex 分组 | Grok 分组 | Claude 分组 | |------|-------------------|-----------|-------------| | `POST /v1/images/generations` / `edits` | 支持(取决于账号/模型/分组开关) | 支持 Grok 图像兼容路径 | 不支持 OpenAI Images | | `POST /v1/responses` + `image_generation` tool | 支持 Codex/Responses 生图 | 不作为 Grok Messages/Responses 能力 | 不支持 | | `/v1/videos*` | 不支持 | 仅 Grok/xAI-compatible 视频 | 不支持 | 因此本文只讲 OpenAI Images API 与 Responses `image_generation` tool。视频生成请放在 Grok 文档里,不要写成 Codex/OpenAI 能力。 ### 图片常见错误 | 报错 | 多半原因 | 处理 | |------|----------|------| | `Images API is not supported for this platform` | Key 不在 OpenAI/Grok 图片分组 | 换 OpenAI 或 Grok 图片分组 | | `model_not_found` / 图片模型不可用 | 模型名、分组模型列表或图片能力不匹配 | 以控制台模型列表和用量里的上游模型为准；持续异常时带 `x-request-id`、模型名和端点提交工单 | | `images endpoint requires an image model` | 把主线文本模型写到了 Images 端点 | `/v1/images/*` 用 `gpt-image-*` 或 `grok-imagine-*` | | Responses 主模型写成 `gpt-image-*` | 把 Images API 模型当成 Responses 对话模型 | Responses image tool 的 `model` 用主线文本/多模态模型,图像由 tool 执行 | | `Videos API is not supported for this platform` | 把 OpenAI/Codex 生图配置拿去调 videos | Videos 仅 Grok 分组,见 [Videos](#/api-videos) | ## 三、提示"工具不可用"怎么办 如果触发后提示生图工具不可用,可以安装开源的 **[codex-image](https://github.com/IanShaw027/codex-image)** skill 来补上这个能力。它面向"真正保存文件、精确路径、多图编辑、批量任务"的本地生图工作流。 ### 安装 用 Codex 自带的 skill 安装器(任选一种): ```bash # 方式一:按仓库 + 路径安装 python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \ --repo IanShaw027/codex-image \ --path skills/codex-image ``` ```bash # 方式二:按 GitHub URL 安装 python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \ --url https://github.com/IanShaw027/codex-image/tree/main/skills/codex-image ``` ```bash # 方式三:手动克隆复制 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" git clone https://github.com/IanShaw027/codex-image.git /tmp/codex-image cp -r /tmp/codex-image/skills/codex-image "${CODEX_HOME:-$HOME/.codex}/skills/" ``` 装完**重启 Codex**。需要 Python 3.11+。 ### 它需要的环境变量 和上面一致——`OPENAI_API_KEY` 与 `OPENAI_BASE_URL`(API key 模式下 `OPENAI_BASE_URL` 必填)。它也会从 `$CODEX_HOME/auth.json`、`config.toml` 里读取凭证。 ### 它的命令 这个 skill 不是 `$imagegen`,而是通过自己的脚本调用,子命令包括: | 子命令 | 作用 | |--------|------| | `generate` | 生成新图 | | `edit` | 编辑/合成输入图(带 `--image` 时自动用) | | `generate-batch` | 按 JSONL 批量生成 | 示例: ```bash bash "${CODEX_HOME:-$HOME/.codex}/skills/codex-image/scripts/codex-image" \ generate --model gpt-image-2 --size 3840x2160 "一只弹钢琴的橘猫" ``` Windows 用 `codex-image.cmd`。生成的图默认保存到 `${CODEX_HOME:-~/.codex}/generated_images/`,也可用 `--out` / `--out-dir` / `--name` 指定路径。 可选的调节变量:`CODEX_IMAGE_MODEL`、`CODEX_IMAGE_SIZE`、`CODEX_IMAGE_QUALITY`、`CODEX_IMAGE_OUTPUT_DIR`、`CODEX_IMAGE_FORMAT` 等。 --- ## 常见问题 **报 401 / 鉴权失败?** 检查 `OPENAI_BASE_URL` 是否为 `https://api.clomio.ai/v1`(注意带 `/v1`)、`OPENAI_API_KEY` 是否正确未过期、密钥分组是否支持图像模型。 **改了环境变量没生效?** 环境变量在进程启动时只读一次,改完要**重开终端**再启动 Codex。 > 其余报错见 [故障排查](#/troubleshooting);Codex 其他配置见 [Codex 配置详解](#/codex-config)。 --- # 必装 Skill 与插件 Skill 和插件能给 Claude Code / Codex 加上"方法论"、"实时面板"或专用工具流,大幅提升体验。下面几个是高频推荐。 > **安全提示:** Skill / 插件本质是一组会被执行的脚本、指令或工具配置。**安装前确认来源可信**,尤其是社区(非官方)的,别装来路不明的。 --- ## Superpowers —— 开发全流程方法论 [Superpowers](https://github.com/obra/superpowers/)(作者 obra,MIT 许可,已进入 Anthropic 官方插件市场)给 Claude 装上一套**规范化的软件开发方法论**:头脑风暴 → 写计划 → TDD(测试驱动)→ 子代理实现 + 代码审查 → 验证。它让 AI 不再"上来就乱写",而是每步都有章法。 **安装**(在 Claude Code 会话里执行,需 Claude Code 2.0.13+): ```text /plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace ``` 装完**退出并重启** Claude Code。之后这些命令可用: - `/brainstorm` —— 先把需求聊清楚,产出设计文档 - `/write-plan` —— 把设计转成可执行的实现计划 - `/execute-plan` —— 用子代理驱动、按 TDD 红/绿节奏实现 描述需求时相关技能会自动触发,无需每次手动调用。 --- ## Codex Skills / Plugins 怎么选 Codex 的持久能力大致分三层: | 层级 | 适合放什么 | 例子 | |------|------------|------| | `AGENTS.md` | 项目规则、构建测试命令、禁止触碰的目录 | “改后运行 `pnpm test`”、“不要改生成物” | | Skill | 可复用工作流、领域知识、脚本封装 | 生图 skill、TDD/调试方法论、发布检查清单 | | Plugin | 可安装的一整包能力:skills、命令、MCP、hooks、assets | Superpowers、状态栏、团队内工具包 | 排障顺序也按这三层来:先确认项目/全局 `AGENTS.md` 是否冲突,再看 skill 是否安装并被触发,最后看 plugin 是否安装、启用、重启后生效。涉及外部数据或私有系统时,优先用 MCP / connector,不要指望模型记忆或网页搜索替代实时权限。 --- ## 不要把 Skill / Plugin 和网关能力混在一起 Skill / Plugin 只能改变客户端工作流、提示词、脚本、MCP/hook 配置;它不能凭空让网关多出不存在的 API。Clomio 控制台里的网页端技能市场是另一套产品,见 [技能市场与创作者中心](#/console-skills)。例如: - Claude Code skill 仍然通过 `ANTHROPIC_BASE_URL + /v1/messages` 对话。 - Codex skill 仍然受 `config.toml` 的 `model_provider`、`base_url`、`wire_api = "responses"` 约束。 - 生图 skill 可以调用 OpenAI Images 或 Responses `image_generation`,但不能把 OpenAI/Codex 变成 Grok-only 的视频接口。 - 多代理/子代理适合并行阅读、规划、审查;让它们写文件时必须明确文件白名单,避免覆盖其他 worker。 安装前先确认本地确实有对应 skill/plugin/命令;文档里不要编造“默认自带”的工具。没有安装时,把它写成“可选安装”,并给出来源或让读者参考官方市场。 ## frontend-design —— Anthropic 官方前端设计 Anthropic 官方 Skill,专治 AI 生成的"千篇一律"前端(到处紫色渐变、一样的字体、雷同卡片)。它会在写代码前**先定一个明确的设计方向**(如极简、极繁、复古未来、奢华、活泼等),做出更有辨识度、完成度更高的页面。 **安装**(`/plugin` 里添加 `anthropics/claude-code` 市场后选 frontend-design),或直接放下 SKILL.md: ```bash curl -o .claude/skills/frontend-design/SKILL.md \ https://raw.githubusercontent.com/anthropics/claude-code/main/plugins/frontend-design/skills/frontend-design/SKILL.md ``` 用法:直接让 Claude 做前端,如「给一个音乐 App 做仪表盘」,Skill 会自动激活。 --- ## UI/UX Pro Max —— 设计智能库 社区里最全的设计智能 Skill(`nextlevelbuilder/ui-ux-pro-max-skill`)。如果说 frontend-design 给的是"审美方向",Pro Max 给的是一个**可检索的设计数据库**:50+ UI 风格、配色、字体搭配、UX 规范、图表类型,带一个 Python 检索脚本。 它的强项是"设计系统生成器":你说「fintech 仪表盘」,它自动给出风格、配色、字体、效果与要避免的反模式。安装方式参考其仓库说明(社区 Skill,安装前先核对来源)。 --- ## Claude HUD —— 实时状态栏 [Claude HUD](https://github.com/jarrodwatts/claude-hud)(作者 jarrodwatts,MIT)在 Claude Code 界面下方加一条**实时信息面板**,让你随时看到: - 上下文窗口用量(绿 → 黄 → 红 进度条,数据来自 Claude Code 本身,非估算) - 当前模型、项目路径、git 分支 - 正在调用的工具、运行中的子代理、待办进度 它用的是 Claude Code 原生状态栏 API,**纯本地、不联网、不读取凭证**。需 Claude Code v1.0.80+、Node.js 18+。 **安装**(会话里执行): ```text /plugin marketplace add jarrodwatts/claude-hud /plugin install claude-hud /claude-hud:setup ``` `setup` 会把状态栏配置写进 `~/.claude/settings.json`,然后**重启** Claude Code 生效。 > Linux 若报 `EXDEV: cross-device link`,先设临时目录:`mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude`。Windows 若提示缺 JS 运行时,先 `winget install OpenJS.NodeJS.LTS`。 --- > 想自己写命令/技能、用子代理,见 [Claude Code 进阶](#/claude-advanced) 与 [Codex 进阶](#/codex-advanced)。 --- # 协同与全局规则 Claude Code 和 Codex 各有所长。把两者搭配着用,再配上一份合适的全局规则,效率会明显提升。 --- ## 各用所长 | 场景 | 更推荐 | |------|--------| | 理解需求、规划方案、"我现在该怎么做" | **Claude Code** | | 执行任务、排查问题、动手直接改 | **Codex** | | 长篇梳理、文档整理 | Claude Code | | 跑命令、看报错、快速定位 | Codex | 记不住就两个词:**想清楚用 Claude,动手干用 Codex。** 如果当前只有一个能用,直接用它即可。 --- ## 一种顺手的协同方式 1. **先用 Claude Code 规划**:把目标讲清楚,让它产出一份分步方案 / 改动清单,必要时写进项目的 `CLAUDE.md` 或一个 `PLAN.md`。 2. **再用 Codex 执行**:让 Codex 读同一份方案,逐步实现、跑测试、排报错。 3. **回到 Claude Code 复盘**:让它审查 Codex 的改动、补文档、查遗漏。 让两个工具共享同一份**项目说明文件**(Claude 读 `CLAUDE.md`、Codex 读 `AGENTS.md`),它们对项目的理解就能对齐。可以让其中一个工具帮你把另一份生成出来,保持内容一致。 --- ## 多 worker 并行时的硬规则 当 Claude Code、Codex 或多个 worker 同时改同一套文档/代码时,最怕的是“好心回退”覆盖别人。建议把下面几条写进本次任务提示或项目规则: - 明确允许写入的文件白名单;没有列出的文件只读不写。 - 动手前记录目标文件当前 hash / 时间戳;写入前再读一次目标片段,只做增量 patch。 - 不执行 `git checkout -- .`、`git reset --hard`、批量格式化、全仓搜索替换这类会扫到他人改动的操作。 - 发现目标文件已被别人改过,先合并当前内容再补自己的段落,不要用旧快照整文件覆盖。 - 最后报告“改了哪些文件、没碰哪些禁改文件、怎么校验”。 协作时可以让 Claude 更偏规划/审查,让 Codex 更偏执行/验证;但两者都必须遵守同一份文件白名单。 --- ## 共享配置时的边界 - Claude Code 的共享规则是 `CLAUDE.md` / `.claude/settings.json`;接 Clomio 时根地址写 `https://api.clomio.ai`,主路径是 `/v1/messages`。 - Codex 的共享规则是 `AGENTS.md` / 受信任项目的 `.codex/config.toml`;接 Clomio 时 base URL 写 `https://api.clomio.ai/v1`,wire API 是 `responses`。 - 两者可以共享同一个 Clomio 控制台账号体系,但 Key 分组要匹配客户端:Claude Code 用 Anthropic/Claude 分组，或使用已开放 Messages 兼容能力的 OpenAI 分组；Codex 用 OpenAI/Codex/GPT 分组。 - 多 worker 同时工作时,把“只允许改哪些文件”写在任务开头;让子代理只读探索,最终写入由主 worker 合并当前文件后做最小 patch。 ## 推荐的全局规则 全局规则写在各自的用户级文件里,对所有项目生效: - Claude Code:`~/.claude/CLAUDE.md` - Codex:`~/.codex/AGENTS.md`(或项目级 `AGENTS.md`) 下面这几条对新手尤其有用,可按需放进去: ```text - 用中文回复。 - 动手改动前,先用一两句话说明你打算怎么做。 - 一次只聚焦一个目标,不要发散。 - 改动要小步、可回退;涉及多文件时先列清单再动手。 - 遇到报错,把完整报错和你的判断讲清楚,别默默吞掉。 - 不确定时先问我,不要擅自做破坏性操作(删文件、改全局配置等)。 - 完成后告诉我"做了什么、怎么验证"。 ``` > 全局规则不要写太长太细——只放真正通用的偏好,项目专属的放各项目自己的说明文件里。 --- ## 一个稳的工作习惯 - **小步提交**:让 AI 每完成一小块就停下来给你看,而不是一口气改一大片。 - **先读后写**:复杂改动前,先让它"只读地"梳理现状、给方案,你确认后再让它动手。 - **报错就喂回去**:把终端里的红字原样发给还能用的那个工具,让它接着排查;两个都不方便时再借助第三方 AI。 - **卡顿先换线路**:见 [网关线路](#/gateway-lines),换条线通常立刻见效。 --- > 想深入单个工具的能力,见 [Claude Code 进阶](#/claude-advanced) 与 [Codex 进阶](#/codex-advanced)。 --- ## 图形化客户端 # CC Switch 配置 不想碰命令行配置?[CC Switch](https://github.com/farion1231/cc-switch)(开源,作者 farion1231)是一个供应商切换小工具:点几下就能给 Claude Code / Codex 配好 Clomio,还能在多个密钥、多条[网关线路](#/gateway-lines)之间一键切换。 --- ## 一、下载安装 到 [CC Switch Releases](https://github.com/farion1231/cc-switch/releases) 下载对应系统的安装包: | 系统 | 文件 | 要求 | |------|------|------| | Windows | `.msi` | Windows 10+ | | macOS | `.dmg` | macOS 12 (Monterey)+ | | Linux | `.AppImage` / `.deb` | 主流发行版 | - **Windows**:双击 `.msi`,若弹「Windows 已保护你的电脑」→「更多信息」→「仍要运行」。 - **macOS**:打开 `.dmg`,把图标拖进「应用程序」。若提示「无法验证开发者」→ 系统设置 → 隐私与安全性 → 「仍要打开」;或在图标上右键 →「打开」。 > CC Switch 只负责**写配置**,工具本身(Claude Code / Codex)仍需另外装好,见 [Claude Code](#/claude-code) / [Codex](#/codex)。运行这些 CLI 还需要 [Node.js 环境](#/nodejs)(若用 npm 安装方式)。 --- ## 二、添加 Clomio 供应商 1. 打开 CC Switch。初次使用时列表为空或只有官方 official,都属正常。 2. 顶部选择要配置的工具(**Claude** 或 **Codex**)。 3. 点右上角 **`+`** → 选「**自定义配置**」。 4. 填写表单。Claude 和 Codex 要分开建供应商: | 工具/协议 | 供应商名称示例 | 请求地址 | API Key 分组 | |-----------|----------------|----------|-------------| | Claude Code / Anthropic-compatible | `clomio-claude` | `https://api.clomio.ai`(**不带 `/v1`**,且**不要**勾「完整 URL」) | Claude/Anthropic 分组;或允许 Messages 调度的 OpenAI 分组 | | Codex / OpenAI-compatible | `clomio-codex` | `https://api.clomio.ai/v1`(**带 `/v1`**) | OpenAI/Codex 分组 | | Grok / OpenAI-compatible Responses | `clomio-grok` | `https://api.clomio.ai/v1`(**带 `/v1`**) | Grok 分组 | 5. 点「**+ 添加**」。 > 请求地址也可填另外两条线路:`https://sub.qazwc.com` 或 `https://crs.qazwc.com`,国内通常更稳。可以各建一个供应商,卡顿时一键切换。详见 [网关线路](#/gateway-lines)。 > > 如果在 CC Switch 里配置 **Codex / OpenAI-compatible** 供应商,Base URL 按 OpenAI 规则写成 `https://api.clomio.ai/v1`(或其它线路 + `/v1`);不要把 Claude/Anthropic 的 `https://api.clomio.ai` 直接照搬过去。 ### 关于「完整 URL / Full URL Endpoint Mode」 这是 CC Switch 的高级例外模式,不是 Clomio 常规接入方式。默认情况下,CC Switch 会把你填的请求地址当作“前缀”,再按客户端类型拼出 `/v1/messages`、`/v1/responses` 或 `/v1/chat/completions`。 只有遇到供应商要求非标准路径、必须直接请求某个完整 endpoint 时,才启用「完整 URL」。启用后,请求地址必须写成完整端点,例如 `https://example.com/custom/path/messages`;不要只写 `https://api.clomio.ai` 或 `https://api.clomio.ai/v1`。Clomio 推荐保持关闭:Claude 填 `https://api.clomio.ai`;Codex/OpenAI/Grok 填 `https://api.clomio.ai/v1`。 --- ## 三、启用并检测 添加后,供应商出现在列表里: 1. 先点蓝色「**启用**」按钮。 2. 再点「**检测**」入口。 3. 顶部出现**绿色提示**,说明这个检测路径成功;最终仍以实际 `claude` / `codex` 会话和 request_id 为准。 若检测报错,先分清它测试的是哪个客户端协议: - **Claude Code / Anthropic-compatible**:Base URL 不带 `/v1`,请求最终会落到 `/v1/messages`。 - **Codex / OpenAI-compatible**:Base URL 带 `/v1`,请求最终会落到 `/v1/responses` 或 `/v1/chat/completions`。 - **Grok**:Base URL 也带 `/v1`,可走 Responses、Chat、Images、Videos、Web Search 和 Voice；Messages 是否可用以分组能力为准。 - 看到请求里出现 `/v1/v1/...` 就是双写了 `/v1`;看到 `Videos API is not supported for this platform`,说明用了非 Grok 分组调用 Videos。 - 看到 `Messages API is not supported for this platform`,说明当前分组未开放 Messages 兼容能力；切换 Claude/Anthropic 分组或使用 Responses/Chat。 - 看到 `Embeddings API is not supported for this platform`,说明当前客户端在调 embeddings,但 Key 不是 OpenAI 分组。 反过来也一样:检测通过不代表所有能力都能用。很多 GUI 只测 `/v1/models` 或一条最小聊天请求,不会覆盖 Responses 工具调用、Claude extended thinking、Images、Embeddings、Web Search 或 Grok-only Videos。遇到具体能力失败时,用本文 curl 或对应 API 参考单独验证。 | 检测报错 | 多半原因 | 处理 | |---|---|---| | `/v1/v1/messages` | Claude 供应商地址多写 `/v1` | 改成线路根地址,例如 `https://api.clomio.ai` | | `/v1/chat/completions` + Grok Key | 当前检测的模型或分组未开放 Chat | 改用 Responses 或换已开放 Chat 的 Grok 分组 | | `This group does not allow /v1/messages dispatch` | OpenAI 分组未开放 Messages 兼容能力 | 换 Claude 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组 | | `Videos API is not supported for this platform` | 非 Grok 分组调视频 | 换 Grok 视频分组 Key | 也可以把 [CC Switch 用户手册](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/README.md) 链接和报错截图一起发给能识别图片的 AI 排查,或对照 [故障排查](#/troubleshooting)。 --- ## 四、从控制台一键导入(更快) 控制台 [api.clomio.ai](https://api.clomio.ai) 的「API 密钥」页,密钥旁通常有「**导入到 CCS**」按钮:点它 → 浏览器弹窗点「允许」→ CC Switch 自动填好地址和密钥,省去手动复制粘贴。 --- ## 五、日常使用 - **切换工具**:顶部点 `Claude` 或 `Codex`,确认对应供应商已启用、检测通过,再去终端用 `claude` / `codex`。 - **切换线路 / 密钥**:在列表里点另一个供应商「启用」即可,无需改终端里的任何东西。 - **会话管理**:CC Switch 右上角有会话管理入口,可按工具筛选历史会话并「恢复会话」继续之前的内容。 --- ## 六、curl 快速验证 把下面的 `你的密钥` 换成当前供应商里同一把 Key。Claude 供应商用 Claude/Anthropic 分组验证;Codex/OpenAI 供应商用 OpenAI/Grok 分组验证。 **Claude / Anthropic-compatible:** ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' ``` **Codex / OpenAI-compatible:** ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.5","input":"ping","max_output_tokens":1}' ``` > 配好后回终端运行 `claude` 或 `codex` 验证。更深入的用法见 [Claude Code 进阶](#/claude-advanced) / [Codex 进阶](#/codex-advanced)。 --- # VS Code 集成 在 VS Code 里用 Claude Code,可以直接在编辑器侧边栏对话、看改动 diff,体验比纯终端更直观。本页讲怎么把它接到 Clomio。 --- ## 一、安装扩展 1. 打开 VS Code → 扩展面板(`Ctrl/Cmd + Shift + X`)。 2. 搜索 **Claude Code**(Anthropic 官方)。 3. 点安装。 > 扩展依赖本机的 Claude Code CLI。请先按 [Claude Code 接入](#/claude-code) 装好 `claude` 命令。 --- ## VS Code 里常见三类客户端怎么选 | 客户端 | 协议 | Base URL | 主路径 | Key 分组 | |---|---|---|---|---| | Claude Code 扩展 | Anthropic Messages | `https://api.clomio.ai` | `POST /v1/messages` | Claude/Anthropic | | Codex 扩展/CLI | OpenAI Responses | `https://api.clomio.ai/v1` | `POST /v1/responses` | OpenAI/Codex | | 普通 OpenAI-compatible 扩展 | Chat/Responses 取决于扩展 | `https://api.clomio.ai/v1` | `/v1/chat/completions` 或 `/v1/responses` | OpenAI/Grok 按能力 | `GET /v1/responses` 是 Codex/Responses WebSocket 入口,不是“按 id 查询历史”的 REST API；当前也没有 `GET /v1/models/{id}`。如果一个 VS Code 扩展只会测 Chat Completions,不要拿 Grok Responses/Videos 分组的检测结果判断所有能力。 --- ## 二、接到 Clomio(关键:用 settings.json) VS Code 扩展和命令行不同:**它不一定会读你 shell 里 export 的环境变量**,直接装完往往会跳出登录界面。优先把配置写进 Claude Code 的 `settings.json`;如果扩展仍跳登录或不认地址,再进入下面的二级排查。不同扩展版本对 settings/env 的读取行为可能不完全一致。 编辑 `~/.claude/settings.json`(Windows 为 `%USERPROFILE%\.claude\settings.json`),写入: ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.clomio.ai", "ANTHROPIC_AUTH_TOKEN": "你的密钥" } } ``` 保存后**完全退出 VS Code 再重新打开**(不是 reload 窗口)——这些值在进程启动时只读一次,不重启不生效。 > 地址可换成另外两条线路 `https://sub.qazwc.com` / `https://crs.qazwc.com`,见 [网关线路](#/gateway-lines)。注意 Claude Code / Anthropic-compatible 的 `ANTHROPIC_BASE_URL` **不带 `/v1`**;这里如果写成 `https://api.clomio.ai/v1`,扩展会再拼 `/v1/messages`,容易变成错误路径。 --- ## 三、开始使用 重开 VS Code 后: 1. 在侧边栏点 Claude Code 图标,或用命令面板(`Ctrl/Cmd + Shift + P`)搜 `Claude`。 2. 在对话框里直接提需求,扩展会读取当前工作区的代码。 3. 它给出的文件改动会以 **diff** 形式展示,你确认后再应用。 试一句「你现在用的是什么模型?」,能正常回复即接入成功。 也可先用终端验证同一把 Key 是否能走 Anthropic Messages 协议: ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' ``` --- ## 四、排查 **装完直接跳登录界面 / 不认地址?** 这是扩展的已知行为——它对环境变量的支持不如 CLI 完整。务必用上面 **settings.json** 的方式配置,并**彻底重启** VS Code。 **仍然不行? 先分三层定位:** 1. 系统终端运行 `claude` 是否可用。 2. VS Code 内置终端运行 `claude` 是否可用。 3. 只有侧边栏 Claude Code 扩展是否失败。 如果 1/2 可用但 3 失败,优先怀疑扩展进程没有读到 env、扩展登录检查先发生,或 Remote SSH / Dev Container / WSL 的 extension host 跑在另一台环境里,不要先改 Clomio Key。 - VS Code 从 Dock/开始菜单启动时通常不会继承你在终端里 `export` 的环境变量;Reload Window 也不等于重启外层进程。彻底退出 VS Code 后,从已经设置好环境变量的终端运行 `code .`,或把变量写进 `~/.claude/settings.json`。 - 打开 VS Code 的 Output / Developer Console,搜索实际请求路径、base URL、401/404 响应体;扩展日志里的 `/v1/messages`、`/v1/v1/messages`、官方 Anthropic host 往往比 UI 报错更有用。 - 如果扩展仍不读 `~/.claude/settings.json`,可在 VS Code 用户设置里临时显式写扩展环境变量验证: ```json { "claudeCode.environmentVariables": { "ANTHROPIC_BASE_URL": "https://api.clomio.ai", "ANTHROPIC_AUTH_TOKEN": "你的密钥" } } ``` - Remote SSH / Dev Container / WSL 场景下,扩展可能运行在远端 extension host;`~/.claude/settings.json` 和环境变量要写在远端 home,不是本机 home。 - 确认 `settings.json` 是合法 JSON(逗号、引号别漏),路径在 `~/.claude/` 下。 - 确认 Key 属于 Claude/Anthropic 可用分组。OpenAI/Grok 分组只有在当前分组开放 Messages 兼容能力时才可走 `/v1/messages` 兼容桥。 - 看到 404 或类似 `/v1/v1/messages`,先把 `ANTHROPIC_BASE_URL` 改回不带 `/v1` 的线路根地址。 - 如果响应体写着 `Messages API is not supported for this platform`,说明当前分组未开放 Claude Messages 兼容能力；换 Claude/Anthropic 分组或启用兼容能力。 - 如果 OpenAI 分组报 `/v1/messages` 不可用，说明当前分组未开放 Messages 兼容能力；请换 Claude/Anthropic 分组或改用 Codex/OpenAI-compatible 扩展。 - 卡顿则换[网关线路](#/gateway-lines);其余报错见 [故障排查](#/troubleshooting)。 > 如果你更习惯图形化管理多个密钥/线路,也可以用 [CC Switch](#/cc-switch) 写好配置,扩展同样会读 `~/.claude/` 下的配置。 --- ## 想要 Codex 的编辑器体验? Codex 也有 IDE 扩展,配置思路一致:装好 `codex` CLI 并按 [Codex 接入](#/codex) 写好用户级 `~/.codex/config.toml` 与 `env_key` 对应的环境变量;Clomio API-key 接入不要求 `auth.json`,那是 OpenAI 登录链路。Codex 是 OpenAI-compatible / Responses 协议,`base_url` 要写 `https://api.clomio.ai/v1`(或其它线路 + `/v1`),不要使用 Claude Code 的 `ANTHROPIC_BASE_URL` 规则。MCP 等高级能力 CLI 与扩展也是共享的,见 [Codex 进阶](#/codex-advanced)。 最小自检: ```toml model_provider = "clomio" model = "gpt-5.4" preferred_auth_method = "apikey" [model_providers.clomio] name = "Clomio" base_url = "https://api.clomio.ai/v1" wire_api = "responses" env_key = "CLOMIO_API_KEY" ``` ```bash export CLOMIO_API_KEY="你的OpenAI/Codex分组密钥" curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $CLOMIO_API_KEY" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` 同一台机器上同时装 Claude Code 和 Codex 时,把 provider 拆清楚:Claude Code/Anthropic-compatible 写 `https://api.clomio.ai`;Codex/OpenAI-compatible 写 `https://api.clomio.ai/v1`。看到错误路径是最快定位方式:`/v1/messages` 对应 Claude 协议,`/v1/responses` 对应 Codex/Responses 协议。普通 OpenAI-compatible VS Code 扩展若只用 Chat Completions 做健康检查，Grok/Responses-only Key 可能被误判失败；请用真实业务路径再验证。 --- # Cherry Studio 配置 [Cherry Studio](https://www.cherry-ai.com/) 是一个跨平台的 AI 桌面客户端,带图形界面、支持多模型切换。把它接到 Clomio,就能用聊天界面调用 Claude、Codex(GPT)、Grok 等模型。 --- ## 一、打开模型服务商设置 左下角齿轮「**设置**」→「**模型服务商**」。这里有一排预置服务商,也可以拉到最下面点「**添加自定义服务商**」新建一个。 --- ## 二、Base URL 的关键区别:加不加 `/v1` 这是最容易踩的坑。Cherry Studio 会根据服务商**类型**自动拼接请求路径,所以**类型选对、地址后缀写对**最重要: | 接入方式 | 服务商类型 | Base URL 后缀 | |----------|-----------|---------------| | **Anthropic 原生**(接 Claude) | Anthropic | **不加** `/v1`:`https://api.clomio.ai` | | **OpenAI 兼容**(接 GPT / Grok / Codex 模型等) | OpenAI | **要加** `/v1`:`https://api.clomio.ai/v1` | - Anthropic 类型下填了 `/v1` 反而会 404。 - 末尾**不要多余斜杠**:✅ `https://api.clomio.ai/v1` ❌ `https://api.clomio.ai/v1/` - 地址同样可换成另外两条线路(`sub.qazwc.com` / `crs.qazwc.com`),见 [网关线路](#/gateway-lines)。OpenAI 类型换线后仍要保留 `/v1`,例如 `https://crs.qazwc.com/v1`;Anthropic 类型仍不加。 - 不要手动拼完整端点:Base URL 填到版本根即可,不要填成 `/v1/chat/completions`、`/v1/responses` 或 `/v1/messages`。 > 怎么选?接 **Claude** 用 Anthropic 原生类型,能用上 extended thinking、PDF 输入等特性;接 **GPT / Grok** 用 OpenAI 兼容类型。日常聊天写代码,OpenAI 兼容也够用。 建议在 Cherry Studio 里按协议建多个服务商,例如 `Clomio Claude`、`Clomio OpenAI`、`Clomio Grok`,分别保存不同 Base URL 和 Key。不要在一个 OpenAI 服务商里同时塞 Claude 模型,也不要把 Grok Key 放到 Anthropic 类型下。 --- ## 三、填密钥与模型 1. **API Key**:填你在控制台 [api.clomio.ai](https://api.clomio.ai) 创建的密钥(注意分组要与模型和协议匹配,见 [创建 API 密钥](#/api-key)):Claude 模型用 Claude/Anthropic 分组;GPT/Codex 模型用 OpenAI 分组;Grok 模型和 Videos 用 Grok 分组。 2. **添加模型**:自定义服务商通常不会自动拉模型列表,需手动点「添加模型」,**手动输入模型 ID**(如 `claude-sonnet-4-6`)。 - 模型 ID **大小写敏感、必须完全匹配**,填错不会报语法错而是返回 `model not found`。 - 具体可用的模型名以控制台该分组显示为准。 3. 点「**检查连接**」只代表 Cherry Studio 当前探针通过。回到对话界面后,还要用你真实要用的模型和功能发一次最小请求。 > “检查连接”不是完整能力证明。它可能只测 `/v1/models`、`/v1/chat/completions` 或一个默认文本请求:绿色只说明这条探针通了,不代表当前模型、图片、知识库 embeddings、Responses、Videos、Web Search 都可用；红色也不一定代表 Key 失效,可能只是拿 Chat Completions 去测了 Grok Responses/Videos 分组。最终以真实请求路径为准,排障时记录 HTTP status、响应体和 `x-request-id`。 > > Cherry Studio 本页主要覆盖聊天/模型服务商接入。Videos 是 Grok-only 的独立视频端点,不要用聊天探针判断它是否可用；请按 [Videos](#/api-videos) 的 `/v1/videos/generations` curl 单独验证。 --- ## 四、常见报错 | 报错 | 原因 / 处理 | |------|------------| | **401 Unauthorized** | 密钥不对、复制不完整,或分组不匹配。确认这把 Key 属于当前服务商类型要用的分组。 | | **404 / Invalid URL** | 地址后缀错了。看到 `/v1/v1` 是重复;Anthropic 类型别加 `/v1`;OpenAI 类型别漏 `/v1`;去掉末尾多余斜杠。 | | **model not found** | 模型 ID 拼错、大小写不符,或 Key 分组没有这个模型,以控制台为准重填/换分组。 | | **Videos API is not supported for this platform** | Videos 仅 Grok 分组可用;换 Grok 分组 Key 和 Grok/video 模型。 | | **Embeddings API is not supported for this platform** | 当前 Key 不是 OpenAI 分组。Embeddings 仅 OpenAI 分组可用;关闭客户端向量/知识库索引或换 OpenAI 分组 Key。 | | **Messages API is not supported for this platform** | 当前分组未开放 Messages 兼容能力。把 Grok 配成 OpenAI 兼容服务商,或换已开放 Messages 的分组。 | | **SSL 证书错误** | 本机开着代理工具所致。设置 →「代理设置」→ 选「不使用代理」或直连。详见 [故障排查](#/troubleshooting)。 | --- ## 五、curl 快速验证 Cherry Studio UI 报错时,先用同一条线路和同一把 Key 验证协议是否选对。 **OpenAI 兼容:** ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"ping"}],"max_tokens":1}' ``` **Anthropic 原生:** ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' ``` **Grok / Responses:** ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的Grok密钥" \ -H "content-type: application/json" \ -d '{"model":"你的Grok模型","input":"ping","max_output_tokens":8}' ``` 如果 Cherry 的“检查连接”固定测试 `/v1/chat/completions`,Grok 分组会失败,这不代表 Grok Responses 不可用。请看实际请求路径,或用上面的 Responses curl 单独验证。 如果 UI 里能看到请求路径或响应体,优先用它定位分组不匹配: - `/v1/messages` + Grok Key:是否可用取决于分组 Messages ingress；未开放时换 Anthropic/Claude Key或改用 Responses/Chat。 - `/v1/chat/completions` + Grok Key:支持；若 Cherry Studio 检测仍失败，检查模型和分组能力。 - `/v1/responses` + Claude Key:不支持,换 OpenAI/Codex 或 Grok Responses 分组。 - `/v1/embeddings` + Grok/Claude Key:不支持,Embeddings 换 OpenAI 分组。 - `/v1/videos/*` + 非 Grok Key:不支持,Videos 只用 Grok 分组。 - `/v1/web_search` + 非 Grok Key:不支持,Web Search 只用 Grok 分组。 > 想配成命令行编程助手而不是聊天客户端?见 [Claude Code](#/claude-code) / [Codex](#/codex);图形化切换多供应商见 [CC Switch](#/cc-switch)。 --- ## API 参考 # API 概述 Clomio 网关提供与 **OpenAI**、**Anthropic**、Grok/xAI 等兼容的 HTTP API。本节是 API 参考的总入口,先讲通用约定,各端点的完整文档见左侧子页。 --- ## 基础信息 | 项 | 值 | |----|-----| | OpenAI-compatible Base URL | `https://api.clomio.ai/v1`(可换[线路](#/gateway-lines):`sub.qazwc.com/v1` / `crs.qazwc.com/v1`) | | Anthropic-compatible Base URL | `https://api.clomio.ai`(SDK/Claude Code 会自动拼 `/v1/messages`) | | 协议 | HTTPS,请求/响应均为 JSON(图像/视频编辑用 `multipart/form-data`) | | 鉴权 | 请求头 `Authorization: Bearer 你的密钥`;普通网关也接受 `x-api-key` / `x-goog-api-key` | | 字符编码 | UTF-8 | 密钥在控制台 [api.clomio.ai](https://api.clomio.ai) 创建,分组需与所调模型匹配,见 [创建 API 密钥](#/api-key)。Base URL 加不加 `/v1` 见 [Base URL 与 /v1 规则](#/base-url-matrix)。 --- ## 通用请求头 | 请求头 | 必填 | 说明 | |--------|:----:|------| | `Authorization` | 是* | `Bearer 你的密钥` | | `x-api-key` | 是* | Anthropic SDK/部分 GUI 常用的 Key 头 | | `x-goog-api-key` | 是* | Gemini/部分 Google 风格工具常用的 Key 头；普通 `/v1` 网关也兼容 | | `Content-Type` | 是* | JSON 请求填 `application/json`;上传文件填 `multipart/form-data` | | `Accept` | 否 | 流式可用 `text/event-stream` | | `anthropic-version` | 否** | Anthropic 原生端点建议带上,如 `2023-06-01` | | `x-request-id` | 否 | 自定义请求 ID,便于工单排查 | > \* 三种 Key 头任选其一即可，推荐优先用 `Authorization: Bearer ...`。GET 请求无需 `Content-Type`。\** OpenAI-compatible 端点不需要。 普通 Claude/OpenAI/Grok `/v1` 网关路径禁止把密钥放在 query string：`?key=` 或 `?api_key=` 会返回 400 `api_key_in_query_deprecated`。Gemini 原生 `/v1beta` 路径兼容 Google 风格 `key=` query，但 `api_key=` 仍会返回废弃错误；能用 header 时仍优先用 header。 --- ## 端点一览 | 分类 | 端点 | 方法 | 文档 | |------|------|:----:|------| | 对话(Chat Completions) | `/v1/chat/completions` | POST | [Chat Completions](#/api-chat) | | 对话(Responses) | `/v1/responses` | POST | [Responses](#/api-responses) | | Codex/WS v2 | `/v1/responses` | GET | [Responses](#/api-responses) | | 对话(Claude 原生 / OpenAI Messages dispatch) | `/v1/messages` | POST | [Messages](#/api-messages) | | 计数 | `/v1/messages/count_tokens` | POST | [Messages](#/api-messages) | | Gemini 原生兼容 | `/v1beta/models` · `/v1beta/models/{model}:generateContent` | GET/POST | [Gemini 原生兼容](#/api-gemini) | | Antigravity 专用 | `/antigravity/v1/messages` · `/antigravity/v1beta/models...` | GET/POST | [Antigravity 接入](#/antigravity) | | 向量 | `/v1/embeddings` | POST | [Embeddings](#/api-embeddings) | | 图像 | `/v1/images/generations` · `/v1/images/edits` | POST | [Images](#/api-images) | | 图像批处理 | `/v1/images/batches` 及其 `/:id` 子路径 | GET/POST/DELETE | [Images](#/api-images) | | 视频(仅 Grok 分组) | `/v1/videos` · `/v1/videos/generations` · `/v1/videos/edits` · `/v1/videos/extensions` | POST/GET | [Videos](#/api-videos) | | 语音(仅 Grok 分组) | `/v1/tts` · `/v1/stt` · `/v1/realtime` · `/v1/custom-voices` | POST/GET+WS | [Voice](#/api-voice) | | 联网搜索 | `/v1/web_search` | POST | [Web Search](#/api-websearch) | | Alpha Search | `/v1/alpha/search` | POST | OpenAI/Codex 专用搜索入口 | | 模型 | `/v1/models` | GET | [Models](#/api-models) | | 用量 | `/v1/usage` | GET | 见下 | | Key 计费 | `/v1/sub2api/billing` | GET | 当前 Key 的余额/计费信息 | > 文档和 SDK 示例以 `/v1/...` 作为规范写法；网关支持省略 `/v1` 的兼容形式。省略版本是否被客户端或外层线路直接转发，取决于所用 Base URL 和 endpoint 组合；如果响应是 HTML 而不是 API JSON，说明请求没有进入 API 路由，应改用同一 API 域名下的规范 `/v1/...` 路径。两种形式都可调用的端点请选择一种并保持 Base URL 与客户端的路径拼接规则一致，不要重复拼接路径。 > > `GET /v1/responses` 是 Codex/Responses WebSocket v2 流入口,**不是**查询历史响应的 REST 接口;当前没有 `GET /v1/responses/{id}`。模型端点也只提供 `GET /v1/models` 列表,没有 `GET /v1/models/{id}`。 ### 当前没有的常见误写端点 | 误写路径 | 当前事实 | 替代 | |---|---|---| | `/openai/v1/...` | 不是公开网关前缀 | 公开调用统一用 `/v1/...` | | `/v1/images/variations` | Images 只注册 generations/edits | 用 `/v1/images/generations` 或 `/v1/images/edits` | | `/v1/images2api/*` | 已不是公开入口 | 用 `/v1/images/*` 或 Responses `image_generation` tool | | `GET /v1/web_search` | Web Search 简化入口只支持 POST | 用 `POST /v1/web_search` | | `POST /v1/videos/{id}` | 视频任意子路径只用于 GET 查询/下载类透传 | 创建用 `/v1/videos/generations`;查询用 `GET /v1/videos/{request_id}` | | `/antigravity/v1/responses` / `/antigravity/v1/chat/completions` | Antigravity v1 专用入口只注册 messages/count_tokens/models/usage | 对话用 `/antigravity/v1/messages`;普通 OpenAI/Codex 用 `/v1/responses` | --- ## 端点 × 分组(重要) **端点是否可用,取决于你密钥所在分组的平台。** 用错分组会返回 404「not supported for this platform」或 403「does not support the requested model」。对应关系: | 端点 | Claude 分组 | OpenAI 分组 | Grok 分组 | Gemini 分组 | Antigravity 分组 | |------|:----:|:----:|:----:|:----:|:----:| | `/v1/messages` | ✓ | ✓* | ✓* | ✗ | ✗ | | `/v1/messages/count_tokens` | ✓/上游相关*** | ✗ | ✗ | ✗ | ✗ | | `/v1/chat/completions` | ✓** | ✓ | ✓ | ✗ | ✗ | | `POST /v1/responses` | ✗ | ✓ | ✓ | ✗ | ✗ | | `GET /v1/responses` | ✗ | ✓ | ✓ | ✗ | ✗ | | `/v1/embeddings` | ✗ | ✓ | ✗ | ✗ | ✗ | | `/v1/images/*` | ✗ | ✓ | ✓ | ✗ | ✗ | | `/v1/videos/*` | ✗ | ✗ | ✓ | ✗ | ✗ | | `/v1/web_search` | ✗ | ✗ | ✓ | ✗ | ✗ | | `/v1/tts` · `/v1/stt` · `/v1/realtime` · `/v1/custom-voices` | ✗ | ✗ | ✓ | ✗ | ✗ | | `/v1beta/models...` | ✗ | ✗ | ✗ | ✓ | ✗ | | `/antigravity/v1...` / `/antigravity/v1beta...` | ✗ | ✗ | ✗ | ✗ | ✓ | | `/v1/models` · `/v1/usage` | ✓ | ✓ | ✓ | ✓ | ✓ | > \* OpenAI/Grok 分组只有在当前分组开放 Messages ingress 能力时才接受 `/v1/messages`;否则返回 `This group does not allow /v1/messages dispatch`。Grok 的 Messages/Chat 请求会转换到 xAI Responses/Chat 兼容路径,模型和工具能力以分组为准。 > > \** Claude 分组的 Chat Completions 会经网关转换到 Anthropic Messages 再返回 OpenAI Chat 形状;若分组被限制为 Claude Code only,仍会拒绝非 `/v1/messages` 请求。Grok Chat Completions 使用 xAI 兼容 Chat/Responses bridge,不是 Claude 转换路径。 > > \*** `count_tokens` 是辅助估算端点;OpenAI/Grok 固定 404。其他 Anthropic-compatible 分组是否支持取决于模型；主 `/v1/messages` 成功时，辅助端点失败通常不影响正式请求。 > > 简记:**Claude Code/Anthropic SDK**走 `/v1/messages`;**Codex/OpenAI SDK**优先走 `/v1/responses` 或 chat/images;**Gemini SDK/CLI**走 `/v1beta/models...`;**Antigravity**走 `/antigravity/...`;**Videos 只在 Grok 分组开放**,Grok 还支持 images/web_search。每个分组实际开放的**模型**以控制台为准。 ### Base URL 与 `/v1` 怎么填 | 客户端/场景 | Base URL 建议 | 说明 | |-------------|---------------|------| | OpenAI SDK、Codex、OpenAI-compatible 工具 | `https://api.clomio.ai/v1` | SDK 会在此基础上追加 `responses`、`chat/completions`、`models` 等相对路径 | | Anthropic SDK、Claude Code | `https://api.clomio.ai` | Anthropic SDK/Claude Code 会自行请求 `/v1/messages` | | Gemini SDK/CLI 原生兼容 | `https://api.clomio.ai` | 客户端会自行请求 `/v1beta/models...`,详见 [Gemini 原生兼容](#/api-gemini) | | Antigravity 专用入口 | `https://api.clomio.ai` | 请求路径自带 `/antigravity/v1...` 或 `/antigravity/v1beta...`,详见 [Antigravity 接入](#/antigravity) | | 工具有独立 Endpoint Path 字段 | `https://api.clomio.ai` | Endpoint Path 再填 `/v1/...`,避免变成 `/v1/v1/...` | 兼容旧配置时，网关保留省略 `/v1` 的兼容入口。新接入建议沿用上表的 `/v1` 端点，便于不同 SDK 之间保持一致；手工使用根路径时请确认返回 `application/json` 或预期的音视频/WebSocket 响应，而不是站点 HTML。 另外还有两类专用兼容入口,只在对应分组/客户端场景下使用: | 专用入口 | 典型路径 | 用途 | 注意 | |----------|----------|------|------| | Gemini 原生兼容 | `GET /v1beta/models`、`GET /v1beta/models/{model}`、`POST /v1beta/models/{model}:generateContent` 等 | Gemini SDK/CLI 原生形状 | 需要 Google/Gemini 平台分组;错误体会偏 Google API 风格;详见 [Gemini 原生兼容](#/api-gemini) | | Antigravity 专用 | `/antigravity/models`、`/antigravity/v1/messages`、`/antigravity/v1/messages/count_tokens`、`/antigravity/v1beta/models...` | Antigravity 客户端专用入口 | 仅使用 Antigravity 分组；详见 [Antigravity 接入](#/antigravity) | --- ## 查询用量:GET /v1/usage 查询当前密钥的额度、限速窗口和用量统计。支持可选日期范围,影响 `model_stats` 的统计窗口: | Query | 说明 | |------|------| | `start_date` | 开始日期,格式 `YYYY-MM-DD`;默认近 30 天 | | `end_date` | 结束日期,格式 `YYYY-MM-DD`;按自然日包含该日期 | ```bash curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29' -H "Authorization: Bearer 你的密钥" ``` 如果这个 Key 配了总额度、有效期或 5h/1d/7d 限速,返回 `mode: "quota_limited"`: ```json { "mode": "quota_limited", "isValid": true, "status": "active", "quota": { "limit": 10, "used": 1.25, "remaining": 8.75, "unit": "USD" }, "rate_limits": [ { "window": "5h", "limit": 2, "used": 0.4, "remaining": 1.6, "reset_at": "2026-06-29T20:00:00Z" } ], "usage": { "today": { "requests": 12, "input_tokens": 1200, "output_tokens": 300, "cache_creation_tokens": 0, "cache_read_tokens": 0, "total_tokens": 1500, "cost": 0.12, "actual_cost": 0.18 }, "total": { "requests": 320, "input_tokens": 45000, "output_tokens": 12000, "cache_creation_tokens": 5000, "cache_read_tokens": 18000, "total_tokens": 80000, "cost": 3.1, "actual_cost": 4.2 } } } ``` 如果 Key 没有自身限制,返回 `mode: "unrestricted"`,并给出钱包余额或订阅剩余额度: ```json { "mode": "unrestricted", "isValid": true, "planName": "钱包余额", "remaining": 23.5, "unit": "USD", "balance": 23.5, "usage": { "today": { "requests": 12, "actual_cost": 0.18 } } } ``` `rate_limits[]` 会按窗口列出 `window`、`limit`、`used`、`remaining`、`window_start` 和可选 `reset_at`。`unrestricted` 不是“不计费”,只是 Key 本身没有独立 quota/限速;响应会按钱包或订阅模式给出 `balance` 或 `subscription`,并通常带 `usage` 与 `model_stats` 便于对账。 ### `/v1/usage` 字段边界 - `start_date` / `end_date` 只影响 `model_stats` 的查询窗口,不改变 `usage.today` 或 `usage.total`;日期解析失败时会静默沿用默认近 30 天或已成功解析的另一端。 - `usage.today` / `usage.total` 除 token 和金额外,还可能带 `average_duration_ms`、`rpm`、`tpm`;这些统计是 best-effort,客户端不要假设所有字段必定存在。 - `model_stats` 是可选数组,常见字段包括 `model`、`requests`、`input_tokens`、`output_tokens`、`cache_creation_tokens`、`cache_read_tokens`、`total_tokens`、`cost`、`actual_cost`、`account_cost`。 - `rate_limits[].limit/used/remaining` 的单位是 **USD 实际消费额 actual_cost** 窗口,不是请求数、RPM 或 token 数;窗口过期时 `used` 会按 0 计算,`reset_at` 只在窗口未过期且 `window_start` 非空时返回。 - `quota_limited.isValid` 对 `active`、`quota_exhausted`、`expired` 都可能为 true;它表示这个 Key 仍能查询 usage,不等于一定还能继续发起计费请求。 详细计费见 [计费与额度](#/billing)。 --- ## 鉴权示例 ```bash curl https://api.clomio.ai/v1/models -H "Authorization: Bearer 你的密钥" ``` 用 OpenAI SDK 时,把 `base_url` 指到带 `/v1` 的网关: ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" }); ``` 用 Anthropic SDK 时,`base_url` 不带 `/v1`: ```python from anthropic import Anthropic client = Anthropic(api_key="你的密钥", base_url="https://api.clomio.ai") ``` --- ## 流式响应(SSE) 对话类端点支持流式:请求体加 `"stream": true`,服务端以 **Server-Sent Events** 逐块返回,每块形如 `data: {...}`。Chat/Messages 通常以 `data: [DONE]` 或消息结束事件收尾;Responses 会发 `response.completed`。若流开始后上游失败,可能收到 `response.failed` / `response.cancelled` 等终止事件。 --- ## 错误格式 错误以 HTTP 状态码 + JSON 返回(OpenAI 风格、Anthropic 风格或 Google/Gemini 风格): ```json { "error": { "message": "具体错误描述", "type": "invalid_request_error", "code": "model_not_found" } } ``` Gemini 原生或 Antigravity `/v1beta` 入口可能返回 Google 风格: ```json { "error": { "code": 401, "message": "Invalid API key", "status": "UNAUTHENTICATED" } } ``` 常见状态码: | 码 | 含义 | 处理 | |----|------|------| | `200` | 成功 | — | | `400` | 参数错误 | 检查请求体、模型名、工具结果关联 | | `401` / `403` | 鉴权失败/分组或余额问题 | 密钥/分组/余额/订阅 | | `404` | 地址错误或端点不属于该分组 | 检查路径、`/v1`、端点 × 分组 | | `413` | 请求体过大 | 减少附件/上下文 | | `429` | 触发限速 | 降并发、稍后重试或换分组/线路 | | `529` / `503` | 服务或上游暂时不可用 | 稍后重试或换[线路](#/gateway-lines) | 模型和可用性错误可按这几个关键词区分: - `The current group does not support the requested model "xxx". Available models: ...`:当前密钥分组明确不开放该模型,按列表换模型或换分组。 - `This group does not allow /v1/messages dispatch`:OpenAI 分组未开启 Messages dispatch,不要把它当 Claude 分组用;改用 `/v1/responses` / `/v1/chat/completions`,或换到允许 dispatch 的 OpenAI 分组。 - `model_not_found` / `Model "xxx" is not supported by any configured account in this group`:当前分组不支持这个模型，通常是模型名或分组能力不匹配。 - `No available accounts supporting model: xxx`:当前暂时无法提供该模型服务。 - `No available accounts` / `Service temporarily unavailable`:当前服务暂时不可用，可能与并发、额度或上游限速有关。 - `Messages API is not supported for this platform`:当前分组未开放 Messages 兼容入口；Claude 分组直接使用，OpenAI/Grok 分组需以分组能力为准。 - `Chat Completions API is not supported for this platform`:当前分组未开放 Chat Completions；Grok 和 OpenAI 分组通常可用，Claude Code only 分组请改用 `/v1/messages`。 - `Responses WebSocket API is not supported for this platform`:当前分组未开放 Responses WebSocket；OpenAI/Grok 分组通常可用，普通 HTTP 客户端请使用 `POST /v1/responses`。 - `Web Search API is not supported for this platform`:独立 `/v1/web_search` 只走 Grok 分组。 - `Videos API is not supported for this platform` / `Video generation is not enabled for this group`:视频只走已开通视频能力的 Grok 分组。 - `API key group platform is not gemini`:普通 `/v1beta` 路径需要 Gemini 分组;如果是 Antigravity 客户端,应使用 `/antigravity/v1beta/...` 和 Antigravity 分组。 - `Query parameter api_key is deprecated. Use Authorization header or key instead.`:Gemini 风格入口不要再用 `api_key` query,改用 `Authorization`、`x-goog-api-key` 或 `key` query。 - `content_policy_violation` / `内容审计命中风险规则，请调整输入后重试`:本地内容审计拦截,HTTP 通常为 403;若审计服务失败且策略 fail-closed,可能返回 `内容审计服务暂不可用，请稍后重试`。 完整错误码与排查见 [故障排查](#/troubleshooting)。 --- ## 计费 响应里的 `usage` 字段展示本次 token。控制台和 `/v1/usage` 中: - `cost` / `total_cost`:倍率前的基础成本口径 - `actual_cost`:实际扣余额、订阅或 API Key quota 的口径 - 缓存命中会体现在 `cache_creation_tokens`、`cache_read_tokens` 或各端点的 usage details 中 详见 [计费与额度](#/billing) 与 [用量明细](#/console-usage)。 ## `/v1/usage` 参数与响应 | Query 参数 | 可选值/范围 | 默认/说明 | |---|---|---| | `start_date` | `YYYY-MM-DD` | 默认查询窗口；只影响 `model_stats` 时间范围 | | `end_date` | `YYYY-MM-DD` | 包含当天；不能早于 `start_date` | | `limit` | 正整数 | 部分部署支持；超范围会按服务端上限处理 | 成功响应可能包含 `mode`=`quota_limited`/`unrestricted`、`quota`、`rate_limits`、`usage`、`model_stats`。金额字段中的 `cost` 是基础成本，`actual_cost` 是叠加分组/Key 倍率后的实际消费。 ```json { "mode":"unrestricted", "isValid":true, "remaining":23.5, "unit":"USD", "usage":{"today":{"requests":12,"actual_cost":0.18}} } ``` | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | 日期格式不合法 | 使用 `YYYY-MM-DD` | | 401 | Key 无效/缺失 | 检查 Authorization | | 403 | 用户、订阅或分组不可用 | 检查控制台状态 | | 429 | usage 查询频率过高 | 客户端缓存结果 | | 500/503 | 计费或服务暂时不可用 | 稍后重试，保留 request_id | --- # Chat Completions OpenAI 兼容的对话补全端点,适合 OpenAI SDK、旧版函数调用和工具调用客户端。 ```text POST https://api.clomio.ai/v1/chat/completions ``` > **分组要求:** OpenAI 分组原生支持;Grok 分组支持 xAI 兼容 Chat/Responses bridge;Claude 分组也可经网关转换支持 Chat Completions,但启用 **Claude Code only** 的 Claude 分组只允许 `/v1/messages`,会拒绝本端点。模型和工具能力以当前 Key 分组为准，见 [端点 × 分组](#/api-usage)。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥` | | `Content-Type` | 是 | `application/json` | --- ## 请求参数 | 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `model` | string | 是 | 模型名,以控制台分组为准 | | `messages` | array | 通常是 | Chat 语义主输入；部分兼容客户端也可传 `input`，但这种写法应改用 Responses 端点 | | `temperature` | number | 否 | 随机性;推理模型可能忽略采样参数 | | `top_p` | number | 否 | 核采样 | | `max_tokens` | integer | 否 | 最大输出 token 数;兼容旧客户端 | | `max_completion_tokens` | integer | 否 | 最大输出 token 数;与 `max_tokens` 同时存在时优先使用 | | `stream` | boolean | 否 | 为 `true` 时 SSE 流式返回 | | `stream_options.include_usage` | boolean | 否 | 流式结束前附带 usage 块 | | `stop` | string/array | 否 | 普通 Chat→Responses 转换路径当前不保证透传；需要强 stop 时优先用 Responses 原生路径验证 | | `n` | integer | 否 | 普通 Chat→Responses 转换路径当前不保证透传，通常按 1 条处理 | | `presence_penalty` | number | 否 | 普通 Chat→Responses 转换路径当前不保证透传 | | `frequency_penalty` | number | 否 | 普通 Chat→Responses 转换路径当前不保证透传 | | `response_format` | object | 否 | 普通 Chat→Responses 转换路径当前不保证透传；JSON 输出建议直接用 Responses `text.format` 验证 | | `tools` | array | 否 | 工具定义;支持 `type:"function"`,部分路径也接受 `web_search`/`web_fetch` 等原生工具类型 | | `tool_choice` | string/object | 否 | `auto`/`none`/`required` 或指定函数,如 `{"type":"function","function":{"name":"get_weather"}}` | | `functions` | array | 否 | 旧版函数定义,会兼容转换为工具 | | `function_call` | string/object | 否 | 旧版函数选择,会兼容转换为 `tool_choice` | | `reasoning_effort` | string | 否 | 推理强度,如 `low`/`medium`/`high`/`xhigh` | | `service_tier` | string | 否 | 服务层级,如 `auto`/`default`/`flex`,按上游能力生效 | | `seed` | integer | 否 | 普通 Chat→Responses 转换路径当前不保证透传 | **messages 元素:** | 字段 | 类型 | 说明 | |------|------|------| | `role` | string | `system` / `user` / `assistant` / `tool`;旧版函数回传也可用 `function` | | `content` | string/array/null | 文本;多模态时为数组,含 `text`、`image_url` 等 | | `reasoning_content` | string | assistant 推理内容回传字段;转换到 Responses/Claude 时会尽量保留 | | `tool_calls` | array | assistant 发起的工具调用,每项含 `id`、`type:"function"`、`function{name,arguments}` | | `tool_call_id` | string | `role:"tool"` 时必填,对应上一轮 `tool_calls[].id` | | `name` | string | `role:"function"` 或具名消息兼容字段 | | `function_call` | object | 旧版 assistant 函数调用字段 | **多模态 content 示例:** ```json [ {"type": "text", "text": "这张图里有什么?"}, {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "auto"}} ] ``` **请求边界:** 请求体不能为空且必须是合法 JSON；`model` 必须存在且为非空 string；`stream` 如出现必须是 boolean，否则返回 400 `invalid stream field type`。`messages` 是 Chat Completions 语义下的主输入；部分兼容客户端在没有 `messages` 但有 `input` 时会按 Responses ingress 能力路由。OpenAI 和 Grok 分组可使用本端点，Claude Code only 分组只允许 `/v1/messages`。请求体过大时返回 413 `invalid_request_error`。 ### 兼容性说明 - 客户端只需要按本页 Chat 格式处理；服务会根据所选分组和模型返回 SSE 或 JSON。 - 普通 Chat→Responses 转换只保留当前转换器显式支持的字段。`response_format`、`presence_penalty`、`frequency_penalty`、`seed`、`n` 以及部分 `stop` 语义不保证透传；如果业务强依赖这些字段，请直接用 [Responses](#/api-responses) 做最小验证。 - 若请求没有 `messages` 但有 Responses 风格 `input`，会按兼容模式处理；部分 Chat 专用参数在该模式下不会生效，请改用 [Responses](#/api-responses) 发送 Responses 格式。 - 当模型映射到 `gpt-image-*` 这类图片模型时，Chat 请求会按图片能力处理；需要稳定控制图片格式时，建议直接使用 [Images](#/api-images)。 --- ## 响应 | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 本次请求 ID | | `object` | string | `chat.completion` 或流式 `chat.completion.chunk` | | `created` | integer | 时间戳 | | `model` | string | 实际使用的模型 | | `choices` | array | 结果数组,含 `message`/`delta`、`finish_reason` | | `usage` | object | `prompt_tokens` / `completion_tokens` / `total_tokens`,可能含缓存和推理 token 明细 | | `service_tier` | string | 上游返回时透出 | `finish_reason` 常见值: `stop`、`length`、`tool_calls`、`content_filter`。工具调用时读取 `choices[0].message.tool_calls`;流式时累积 `choices[].delta.content`、`delta.reasoning_content`、`delta.tool_calls`。 ```json { "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1730000000, "model": "gpt-5.4", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "你好!有什么可以帮你?" }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21 } } ``` --- ## 最小可验证 curl 下面请求可验证路由、鉴权、`model`/`messages` 基本形态和非流式响应；把 `stream` 改成字符串（如 `"false"`）可验证 400 `invalid stream field type`。 ## 示例:基础调用 ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.4", "messages": [ {"role": "system", "content": "你是简洁的助手。"}, {"role": "user", "content": "用一句话介绍你自己"} ] }' ``` ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") resp = client.chat.completions.create( model="gpt-5.4", messages=[{"role": "user", "content": "用一句话介绍你自己"}], ) print(resp.choices[0].message.content) ``` --- ## 示例:流式输出 ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.4", "messages": [{"role": "user", "content": "写一首关于秋天的短诗"}], "stream": true }' ``` 流式返回每块形如 `data: {"choices":[{"delta":{"content":"秋"}}]}`,以 `data: [DONE]` 结束。若流已经开始后才出错,不会再返回普通 JSON 错误体,而是写 `event: error` / `data: ...` 并尽量补 `data: [DONE]` 收尾。 --- ## 示例:多模态(发图片) ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "你的多模态模型名", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "这张图里有什么?"}, {"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}} ] }] }' ``` > 也可用 `data:image/png;base64,...` 内联图片。是否支持多模态取决于所选模型和分组上游能力。 --- ## 示例:函数 / 工具调用 ```json { "model": "gpt-5.4", "messages": [{"role": "user", "content": "北京现在天气如何?"}], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "查询城市天气", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } }], "tool_choice": "auto" } ``` 模型决定调用工具时,`choices[0].message.tool_calls` 会给出函数名与参数;你执行后把结果以 `role:"tool"` 和对应 `tool_call_id` 追加进 `messages` 再请求一次。 ## 常见请求错误 下面表格列出常见 OpenAI-style `{"error": ...}` 错误。鉴权、Key 状态或分组限制错误的字段可能略有不同。 | HTTP | `error.type` | `message` | 来源 / 处理 | |------|--------------|-----------|-------------| | 400 | `invalid_request_error` | `Request body is empty` | 请求体为空；发送 JSON body | | 400 | `invalid_request_error` | `Failed to parse request body` | JSON 非法 | | 400 | `invalid_request_error` | `model is required` | `model` 缺失、非 string 或空字符串 | | 400 | `invalid_request_error` | `invalid stream field type` | `stream` 不是 boolean | | 413 | `invalid_request_error` | `Request body too large, limit is ...` | 请求体超过服务限制;减少附件/上下文或分批 | | 404 | `not_found_error` | `Chat Completions API is not supported for this platform` | 当前 Key 分组不开放 Chat；Grok 分组可用时不会命中此项 | | 403 | `permission_error` | `This group is restricted to Claude Code clients (/v1/messages only)` | Claude Code only 分组只允许 Messages | | 403 | `content_policy_violation` / `permission_error` | 内容审计命中,或当前分组不支持请求模型并返回 Available models | 调整内容、模型或分组 | | 404 | `model_not_found` | 模型不在当前分组可用列表里 | 核对模型名和 `/v1/models` | | 429 | `rate_limit_exceeded` / `rate_limit_error` | API Key 金额窗口、用户/分组 RPM、平台日/周/月额度、pending 队列或并发限制 | 看 `Retry-After`、控制台额度/并发和用量窗口 | | 499 | `api_error` | `context canceled` | 客户端主动断开或超时取消 | | 503 | `billing_service_error` / `api_error` | 服务暂时不可用或上游繁忙 | 稍后重试；持续出现带 request_id 工单 | --- ## 实战场景 ### 场景一:流式输出并在最后读取 usage ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") usage = None stream = client.chat.completions.create( model="gpt-5.4", messages=[{"role": "user", "content": "用三点总结缓存命中率优化方法"}], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices: print(chunk.choices[0].delta.content or "", end="") if chunk.usage: usage = chunk.usage print("\nusage=", usage) ``` ### 场景二:旧版 `functions/function_call` 兼容 ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.4", "messages": [{"role":"user","content":"查一下上海天气"}], "functions": [{ "name": "get_weather", "description": "查询城市天气", "parameters": { "type":"object", "properties":{"city":{"type":"string"}}, "required":["city"] } }], "function_call": {"name":"get_weather"} }' ``` ### 场景三:工具结果回传并继续生成 ```json { "model": "gpt-5.4", "messages": [ {"role":"user","content":"北京现在天气如何?"}, {"role":"assistant","content":null,"tool_calls":[{ "id":"call_weather_1", "type":"function", "function":{"name":"get_weather","arguments":"{\"city\":\"北京\"}"} }]}, {"role":"tool","tool_call_id":"call_weather_1","content":"{\"temp\":\"28C\",\"condition\":\"晴\"}"} ] } ``` ### 场景四:结构化信息抽取(JSON 模式) ```python import json from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") resume = "张三,3 年后端经验,擅长 Go 和 PostgreSQL,邮箱 zhang@example.com" r = client.chat.completions.create( model="gpt-5.4", messages=[ {"role": "system", "content": "把简历抽取成 JSON:name, years, skills(数组), email。"}, {"role": "user", "content": resume}, ], response_format={"type": "json_object"}, ) data = json.loads(r.choices[0].message.content) print(data["name"], data["skills"]) ``` --- > 需要 Claude 原生 extended thinking、`cache_control` 或 `count_tokens` 时,见 [Messages](#/api-messages);需要 OpenAI Responses 形态时,见 [Responses](#/api-responses)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前 `/v1/models` 中的非空字符串 | 模型由 Key 分组决定；不要把其他分组模型名混用 | | `messages` | 至少 1 项；`role`=`system`/`developer`/`user`/`assistant`/`tool` | `content` 可为字符串或 content block 数组 | | `stream` | `true` / `false` | `true` 返回 SSE；默认 `false` | | `temperature` | `0` 至 `2` | 越高越随机；推理模型可能忽略 | | `top_p` | `0` 至 `1` | 与 temperature 通常只设置一个 | | `max_tokens` / `max_completion_tokens` | 正整数 | 输出上限；优先使用 `max_completion_tokens` | | `tool_choice` | `auto` / `none` / `required` / 指定函数对象 | 仅在请求含 `tools` 时有意义 | | `response_format` | `text`、`json_object`、`json_schema` 对象 | JSON 模式要求提示词明确要求 JSON | | `parallel_tool_calls` | `true` / `false` | 是否允许一轮返回多个工具调用 | ## 完整响应与错误 非流式成功响应至少包含 `id`、`object:"chat.completion"`、`model`、`choices[]` 和 `usage`；流式响应是 `data:` SSE，最后以结束事件收尾。错误统一形如： ```json { "error": { "type": "invalid_request_error", "message": "model is required", "code": "invalid_request" } } ``` | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `Request body is empty`、`Failed to parse request body`、`model is required` | 修正 JSON 和必填字段 | | 400 | `invalid stream field type` | `stream` 必须是真正的 JSON boolean | | 401 | `Invalid API key` / `API key is disabled` | 检查 Key 头和状态 | | 403 | `does not support the requested model` / Claude-only 限制 | 换模型或分组 | | 404 | `Chat Completions API is not supported for this platform` | 当前分组未开放 Chat | | 413 | `Request body too large` | 缩小上下文或附件 | | 429 | `rate_limit_exceeded` / `rate_limit_error` | 按 `Retry-After` 退避并降低并发 | | 502/503 | `Upstream request failed` / `No available accounts` | 带 `x-request-id` 重试或提交工单 | --- # Responses OpenAI 的 Responses API,Codex CLI 默认走这个端点(`wire_api = "responses"`)。相比 Chat Completions,它更适合带工具、带推理、带多模态输入的智能体场景。 ```text POST https://api.clomio.ai/v1/responses GET https://api.clomio.ai/v1/responses # Codex/WS v2 流入口,不是 HTTP 查询历史响应 # 兼容/直连别名: POST https://api.clomio.ai/responses POST https://api.clomio.ai/responses/{subpath} GET https://api.clomio.ai/responses # 同样只用于 WebSocket Upgrade POST https://api.clomio.ai/backend-api/codex/responses POST https://api.clomio.ai/backend-api/codex/responses/{subpath} GET https://api.clomio.ai/backend-api/codex/responses # Codex direct WebSocket 入口 ``` > **分组要求:** **OpenAI、Grok 分组**支持 `POST /v1/responses`；OpenAI 和 Grok 也支持 `GET /v1/responses` WebSocket 入口。Claude 分组请用 [Messages](#/api-messages)。需要实时语音请用 [Voice](#/api-voice)。见 [端点 × 分组](#/api-usage)。 > > **没有** `GET /v1/responses/{id}` 这个 HTTP 查询路由。`POST /v1/responses/*` 子路径会进入 Responses 处理（例如 compact），但历史查询/取回请不要写成 GET。多轮请在下一次 `POST /v1/responses` 中传 `previous_response_id`,或让 Codex 自己维护会话。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥` | | `Content-Type` | 是 | `application/json` | | `Accept` | 否 | 流式可用 `text/event-stream` | --- ## 请求参数 ### 服务处理的字段 | 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `model` | string | 是 | 模型名，以当前分组可见列表为准 | | `input` | string/array | 通常必填 | 输入:可为一段文本,或结构化消息数组 | | `stream` | boolean | 否 | `true` 时以 SSE 流式返回；如出现必须是 boolean，否则返回 400 `invalid stream field type` | | `previous_response_id` | string | 否 | 接续上一次 Responses 响应,必须是 `resp_*`。不能用 Anthropic `msg_*`、Chat Completions `chatcmpl-*`、工具调用 id 或自定义会话 id。HTTP 请求中带工具结果时仍需携带可关联的 `call_id` / item 引用 | | `max_output_tokens` | integer | 否 | 最大输出 token | | `reasoning` | object | 否 | 推理设置,如 `{"effort":"high","summary":"auto"}`；具体值以模型支持范围为准 | | `service_tier` | string | 否 | 服务层级提示,如 `priority` / `flex`;具体是否生效取决于分组与上游 | ### 常用透传字段 | 参数 | 类型 | 说明 | |------|------|------| | `instructions` | string | 系统级指令(相当于 system) | | `temperature` | number | 随机性 | | `top_p` | number | 核采样 | | `tools` | array | 可用工具定义;支持 `function`、`web_search`、`image_generation` 等上游支持的类型 | | `tool_choice` | string/object | 工具选择策略,如 `auto`、`required`、`{"type":"function","name":"..."}` | | `parallel_tool_calls` | boolean | 是否允许并行工具调用 | | `include` | array | 要求上游额外返回的字段,如推理加密内容/工具结果等 | | `store` | boolean | 是否让上游存储响应;Codex 会话续接通常由客户端处理 | ### `input` 结构化写法 `input` 可以是字符串,也可以是数组。数组里常见 item: | item / content 类型 | 用途 | |------|------| | `{ "role":"user", "content":"..." }` | 普通消息 | | `content: [{"type":"input_text","text":"..."}]` | 多模态消息里的文本块 | | `content: [{"type":"input_image","image_url":"https://..."}]` | 图片 URL / data URI | | `content: [{"type":"input_file","file_id":"..."}]` | 已上传文件引用 | | `content: [{"type":"input_file","file_data":"...","filename":"a.pdf"}]` | 内联文件数据 | | `{ "type":"function_call_output", "call_id":"...", "output":"..." }` | 把工具执行结果交还给模型 | > 工具结果的 `call_id` 必须能对应前一轮模型返回的函数调用。缺少 `call_id` 或缺少可关联 item 时,HTTP 路径会直接返回 400,不会盲目转给上游。手写 HTTP 工具结果建议同时带 `previous_response_id`、`item_reference` 和 `function_call_output.call_id`;只有 Codex/Responses WS v2 才能依赖会话上下文自动补齐更多引用。 ### 请求边界 - 请求体不能为空且必须是合法 JSON。 - `model` 必须存在且为非空 string；`stream` 如出现必须是 boolean，否则返回 400 `invalid stream field type`。`input` 通常必填，缺失时会返回请求参数错误。 - `input`、`instructions`、`tools`、`tool_choice`、`reasoning`、`include`、`store`、`parallel_tool_calls` 等字段会按 OpenAI/Grok 兼容路径转发；字段组合、工具类型和多模态文件能力是否可用由所选上游判断。 - 不同模型对 `temperature`、`top_p`、`verbosity`、`reasoning`、`metadata` 等字段的支持不同；不支持的字段可能被忽略或返回 400。需要稳定兼容时只使用本页标注为模型支持的字段，并以错误响应为准。 - Responses 图片工具需要在 `tools` 中声明 `image_generation`。图片模型、尺寸和格式必须使用当前分组支持的组合；未开放图片能力时会返回 403，请改用普通文本模型或 Images 端点。 - `previous_response_id` 会参与续接；`POST /v1/responses/*` 子路径可用于兼容客户端的 Responses 子操作，但没有 `GET /v1/responses/{id}`。 - Grok 分组支持 `POST /v1/responses` 和 `GET /v1/responses` WebSocket 入口。需要原生语音会话时请使用 [Voice Realtime](#/api-voice)，不要把 Responses WebSocket 当成 Voice WebSocket。 - `GET /v1/responses` 不是普通 HTTP API。过鉴权且分组允许后，普通 HTTP GET 会返回 426 `WebSocket upgrade required (Upgrade: websocket)`；真正 WS 首帧必须在超时内到达、必须是 JSON，且必须包含 `model`。 ### 常见请求错误 | HTTP | `error.type` | `message` | 来源 / 处理 | |------|--------------|-----------|-------------| | 400 | `invalid_request_error` | `Request body is empty` | 请求体为空 | | 400 | `invalid_request_error` | `Failed to parse request body` | JSON 非法 | | 400 | `invalid_request_error` | `model is required` | `model` 缺失、非 string 或空字符串 | | 400 | `invalid_request_error` | `invalid stream field type` | `stream` 不是 boolean | | 400 | `invalid_request_error` | `previous_response_id must be a response.id (resp_*), not a message id` | 把 Anthropic `msg_*` 或其它 ID 当 Responses 续接 ID 使用 | | 400 | `invalid_request_error` | `function_call_output requires call_id on HTTP requests; continuation via previous_response_id is only supported on Responses WebSocket v2` | HTTP 工具结果必须带 `call_id`;不能只靠 `previous_response_id` 让网关回放工具上下文 | | 400 | `invalid_request_error` | `function_call_output requires item_reference ids matching each call_id on HTTP requests; continuation via previous_response_id is only supported on Responses WebSocket v2` | HTTP 工具结果缺少可关联的 item 引用;改用完整 `call_id` / item_reference 或交给 Codex WS v2 | | 400 | `invalid_request_error` | `Failed to normalize compact request body` | compact 子路径 body 规范化失败 | | 413 | `invalid_request_error` | `Request body too large` / body 超限 | 请求体超过网关限制,缩小输入或改用文件/分片方案 | | 403 | `permission_error` | `This group is restricted to Claude Code clients (/v1/messages only)` | Claude Code only 分组拒绝 Responses | | 404 | `not_found_error` | `Responses WebSocket API is not supported for this platform` | 当前分组未开放 Responses WebSocket；OpenAI/Grok 分组通常可用 | | 426 | `invalid_request_error` | `WebSocket upgrade required (Upgrade: websocket)` | 对 `GET /v1/responses` 发了普通 HTTP 请求；该入口只给 Codex/Responses WS 使用 | | 404 | `model_not_found` | `No accounts are configured to support model ...` / `model not found` | 当前分组无法服务该模型；先查控制台分组模型列表和请求模型名，仍异常时带 `request_id` 提交工单 | | 503 | `api_error` | `No available accounts` / `All available accounts exhausted` | 当前分组暂时没有可用服务能力，可能是并发、冷却、限流或自动切换后仍不可用；稍后重试，持续异常带 `request_id` 提交工单 | --- ## 响应 | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 响应 ID(可用于 `previous_response_id`) | | `object` | string | `response` | | `status` | string | `completed` / `incomplete` / `failed` | | `model` | string | 实际模型 | | `output` | array | 输出项数组(文本、推理、工具调用、联网搜索等) | | `output_text` | string | 部分 SDK 汇总出的便捷字段:纯文本输出 | | `usage` | object | `input_tokens` / `output_tokens` / `total_tokens`,可能含缓存/推理明细 | | `incomplete_details` | object | `status=incomplete` 时给出原因,如 `max_output_tokens` | | `error` | object | `status=failed` 时给出错误 | 流式时常见事件包括 `response.output_text.delta`、`response.function_call_arguments.delta`、`response.reasoning_summary_text.delta`、`response.completed`、`response.failed`、`response.cancelled` 等。**流已经开始后**的失败通常会以 SSE 事件返回,而不是 HTTP 状态码变化。 ```json { "id": "resp_xxx", "object": "response", "status": "completed", "model": "gpt-5.4", "output": [ { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "你好!" }] } ], "output_text": "你好!", "usage": { "input_tokens": 8, "output_tokens": 5, "total_tokens": 13 } } ``` --- ## 最小可验证 curl 下面请求可验证 `POST /v1/responses`、`model`/`input` 基本形态和非流式响应；把 `stream` 改成字符串可验证 400 `invalid stream field type`。 常用负例也建议保存下来,用来区分“客户端拼错路径/字段”与“上游模型失败”: ```bash # GET /v1/responses 是 WS Upgrade 入口,不是 REST 查询 curl -i https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" # stream 类型错误:400 invalid stream field type curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.4","input":"ping","stream":"true"}' # previous_response_id 不是 resp_*:400 curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.4","previous_response_id":"msg_abc","input":"continue"}' ``` ## 示例:基础调用 ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer 你的密钥" -H "Content-Type: application/json" -d '{ "model": "gpt-5.4", "input": "用一句话解释什么是 API" }' ``` ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") resp = client.responses.create(model="gpt-5.4", input="用一句话解释什么是 API") print(resp.output_text) ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" }); const resp = await client.responses.create({ model: "gpt-5.4", input: "用一句话解释什么是 API" }); console.log(resp.output_text); ``` --- ## 示例:带指令、高推理和服务层级 ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer 你的密钥" -H "Content-Type: application/json" -d '{ "model": "gpt-5.4", "instructions": "你是严谨的算法专家,只给要点。", "input": "如何在 O(n) 时间内找出数组里出现次数过半的元素?", "reasoning": { "effort": "high", "summary": "auto" }, "service_tier": "priority", "max_output_tokens": 600 }' ``` --- ## 示例:流式 ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer 你的密钥" -H "Content-Type: application/json" -d '{ "model": "gpt-5.4", "input": "讲个一句话冷笑话", "stream": true }' ``` 客户端累积 `response.output_text.delta` 的 `delta` 即可。若收到 `response.failed` / `response.cancelled`,应把事件中的错误展示给用户并停止等待。 --- ## 示例:多模态输入 ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer 你的密钥" -H "Content-Type: application/json" -d '{ "model": "gpt-5.4", "input": [{ "role": "user", "content": [ {"type":"input_text","text":"这张图适合做什么标题?"}, {"type":"input_image","image_url":"https://example.com/cat.png"} ] }] }' ``` --- ## 示例:工具调用与工具结果 第一轮让模型决定是否调用函数: ```json { "model": "gpt-5.4", "input": "查一下订单 123 的物流状态", "tools": [{ "type": "function", "name": "get_order_status", "description": "查询订单物流状态", "parameters": { "type": "object", "properties": { "order_id": {"type":"string"} }, "required": ["order_id"] } }] } ``` 模型返回 `function_call` 后,执行工具,再把结果交回: ```json { "model": "gpt-5.4", "previous_response_id": "resp_xxx", "input": [ {"type":"item_reference","id":"call_abc"}, {"type":"function_call_output","call_id":"call_abc","output":"已发货,预计明天送达"} ] } ``` 如果是手写 HTTP 请求,`function_call_output` 需要保留能匹配原始工具调用的 `call_id` / `item_reference`；只保存工具输出文本或只填 `previous_response_id` 会返回 400。WebSocket 会话通常会自动维护这些引用,手写脚本不要删字段。 --- ## 示例:图像生成工具 如果模型/分组支持 Responses 内置图像工具,可通过 `tools` 触发生图;标准图片端点见 [Images](#/api-images)。仅声明 `tools` 是“可用能力”,强制本轮生图请配 `tool_choice` 或使用明确的图片意图;否则模型也可能只文本回答。 ```json { "model": "gpt-5.4", "input": "生成一张 1024x1024 的扁平插画:一只橘猫在写代码", "tools": [{ "type": "image_generation", "size": "1024x1024", "quality": "high" }] } ``` --- ## 实战场景 ### 场景:命令行问答小工具(流式 + 接续) ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") last_id = None while True: q = input("\n你: ").strip() if q in ("exit", "quit", ""): break stream = client.responses.create( model="gpt-5.4", input=q, previous_response_id=last_id, stream=True, ) print("AI: ", end="") for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) elif event.type == "response.completed": last_id = event.response.id elif event.type in ("response.failed", "response.cancelled"): print("\n[失败]", event) break ``` --- > 这是 Codex 默认端点,客户端配置见 [Codex 接入](#/codex)。普通 OpenAI 风格聊天也可用 [Chat Completions](#/api-chat)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前分组 `/v1/models` 中的非空字符串 | 必填 | | `input` | string 或 input/message/function_call 等数组 | 多模态时使用结构化数组 | | `stream` | `true` / `false` | 流式返回 `response.*` 事件 | | `max_output_tokens` | 正整数 | 输出上限；不传由模型/上游决定 | | `reasoning.effort` | `none`/`minimal`/`low`/`medium`/`high`/`xhigh` | 是否支持取决于模型；不支持时删掉 | | `tools[].type` | `web_search`、`x_search`、`image_generation`、`function` | Grok 搜索、图片工具和函数工具 | | `tool_choice` | `auto`、`none`、`required` 或指定工具 | 控制工具调用策略 | | `previous_response_id` | `resp_*` 字符串 | 用于多轮接续；不要传 message/event ID | | `store` | `true` / `false` | 是否保存响应；是否可用取决于模型和分组 | | `truncation` | `auto` / `disabled` | 仅支持该字段的路径使用；不支持时删除 | ## 完整响应与错误 成功非流式响应通常包含 `id`、`object:"response"`、`status`、`output[]` 和 `usage`；流式响应按事件类型处理，不要只按 Chat 的 `choices[].delta` 解析。 ```json { "id": "resp_example", "object": "response", "status": "completed", "output": [{"type":"message","role":"assistant","content":[{"type":"output_text","text":"OK"}]}], "usage": {"input_tokens": 10, "output_tokens": 2, "total_tokens": 12} } ``` | HTTP/事件 | 典型错误 | 处理 | |---|---|---| | 400 | `model is required`、`input is required`、`invalid_request_error` | 检查模型、input 和字段类型 | | 400 | `previous_response_id` 无效、`reasoning.mode` 不支持 | 使用 `resp_*`，删除当前模型不支持的字段 | | 401/403 | Key 无效、分组不支持模型或工具 | 换正确分组/模型 | | 404 | `No handler found on route` | 检查是否误用了视频、图片或其他非 Responses 路径 | | 429 | `rate_limit_exceeded` | 读取 `Retry-After` 并指数退避 | | 502/503 | `response.failed`、`No available accounts` | 保存完整失败事件和 `x-request-id` | 流式失败应处理 `response.failed`、`response.incomplete`、`response.cancelled`，不能只等待 TCP 断开。 --- # Messages（Claude） Anthropic Messages 兼容端点,支持 Claude 原生内容块、extended thinking、工具调用和 prompt cache。 ```text POST https://api.clomio.ai/v1/messages POST https://api.clomio.ai/v1/messages/count_tokens ``` > **分组要求:** `/v1/messages` 支持 Claude/Anthropic 分组,也支持启用了 Messages ingress 的 OpenAI/Grok 分组转换。具体模型、工具和流式能力以分组为准。`/v1/messages/count_tokens` 对 OpenAI/Grok 分组固定返回 404,其他 Anthropic-compatible 分组是否支持取决于平台能力;主对话成功时 count_tokens 404 通常可忽略。见 [端点 × 分组](#/api-usage)。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥`(也兼容 `x-api-key: 你的密钥`;普通网关还接受 `x-goog-api-key`,但 Claude Code 不推荐用它) | | `anthropic-version` | 是 | 如 `2023-06-01` | | `anthropic-beta` | 否 | 使用 beta 能力时按 Anthropic 规范传入 | | `Content-Type` | 是 | `application/json` | 手写 curl 至少带 `anthropic-version: 2023-06-01`。使用 beta 能力时按客户端要求保留 `anthropic-beta`。普通 `/v1` 网关路径禁止把密钥放在 query string:`?key=` 或 `?api_key=` 会返回 400 `api_key_in_query_deprecated`;请用 header。 --- ## 请求参数 | 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `model` | string | 是 | Claude 模型名或映射模型名,以控制台分组为准 | | `messages` | array | 是 | 对话消息,`role` 为 `user`/`assistant` | | `max_tokens` | integer | 是 | 最大输出 token | | `system` | string/array | 否 | 系统提示;可为字符串或 content block 数组 | | `temperature` | number | 否 | 采样温度;部分推理模型可能忽略 | | `top_p` / `top_k` | number/int | 否 | 采样控制 | | `stream` | boolean | 否 | SSE 流式返回 | | `stop_sequences` | array | 否 | 停止序列 | | `tools` | array | 否 | 工具定义,每项含 `name`、`description`、`input_schema`;也可带 `cache_control` | | `tool_choice` | object | 否 | `{"type":"auto"}` / `any` / `none` / `{"type":"tool","name":"..."}`;可带 `disable_parallel_tool_use` | | `thinking` | object | 否 | Extended thinking,如 `{"type":"enabled","budget_tokens":2000}` | | `output_config` | object | 否 | 输出强度配置,如 `{"effort":"low|medium|high|max"}` | | `metadata` | object | 否 | 终端用户或请求元数据,如 `user_id` | --- ## content block `messages[].content` 可为字符串,也可为 block 数组。常用 block: | type | 关键字段 | 说明 | |------|----------|------| | `text` | `text`, `cache_control` | 文本输入/输出 | | `image` | `source{type,media_type,data/url/file_id}` | 图片输入 | | `document` | `source`, `title`, `cache_control` | 文档输入 | | `thinking` | `thinking` | assistant extended thinking 内容 | | `tool_use` | `id`, `name`, `input` | assistant 请求调用工具 | | `tool_result` | `tool_use_id`, `content`, `is_error` | user 回传工具结果 | `cache_control` 可放在 `system` block、`messages[].content[]` block 或工具定义上,常见值: ```json {"type":"ephemeral"} ``` 也可带 `ttl`,如 `{"type":"ephemeral","ttl":"1h"}`;具体是否生效取决于上游模型能力。 **请求边界:** 请求体不能为空且必须是合法 JSON；`model` 必须是非空 string，`stream` 应使用 boolean。OpenAI/Grok 分组是否开放 Messages 转换由分组能力决定，未开放时返回 403 `This group does not allow /v1/messages dispatch`。OpenAI/Grok 分组调用 `/v1/messages/count_tokens` 返回 404 `Token counting is not supported for this platform`。请求体过大时返回 413 `invalid_request_error`。 --- ## 响应 | 字段 | 类型 | 说明 | |------|------|------| | `id` | string | 消息 ID | | `type` | string | `message` | | `role` | string | `assistant` | | `content` | array | 内容块数组,可能包含 `text`、`thinking`、`tool_use` 等 | | `model` | string | 实际模型 | | `stop_reason` | string | `end_turn` / `max_tokens` / `tool_use` 等 | | `stop_sequence` | string/null | 命中的停止序列 | | `usage` | object | `input_tokens` / `output_tokens`,可能含 `cache_creation_input_tokens`、`cache_read_input_tokens`、`service_tier` 等 | ```json { "id": "msg_xxx", "type": "message", "role": "assistant", "content": [{ "type": "text", "text": "你好!" }], "stop_reason": "end_turn", "usage": { "input_tokens": 10, "output_tokens": 6 } } ``` 流式以 SSE 返回 `message_start`、`content_block_start`、`content_block_delta`、`message_delta`、`message_stop` 等事件;累积 `text_delta.text`、`thinking_delta.thinking` 和 `input_json_delta.partial_json`。 --- ## 最小可验证 curl 下面请求可验证 `/v1/messages`、`anthropic-version`、`model`/`max_tokens`/`messages` 基本形态和非流式响应；在 Claude 分组下把 `stream` 改成字符串可验证本地解析错误 `Failed to parse request body`。 ## 示例:基础调用 ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 1024, "system": "你是简洁的助手。", "messages": [{"role": "user", "content": "你好"}] }' ``` ```python from anthropic import Anthropic client = Anthropic(api_key="你的密钥", base_url="https://api.clomio.ai") msg = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, messages=[{"role": "user", "content": "你好"}], ) print(msg.content[0].text) ``` > 用官方 anthropic SDK 时,`base_url` 填 `https://api.clomio.ai`(**不带** `/v1`,SDK 会自动补 `/v1/messages`)。 --- ## 示例:流式 ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "写一句鼓励的话"}], "stream": true }' ``` --- ## OpenAI 分组 Messages bridge OpenAI/Grok 分组下的 `/v1/messages` 仍使用 Anthropic Messages 请求形状；服务会按分组能力转换并返回 Anthropic Messages 响应。启用条件和边界: - API Key 必须绑定 OpenAI 分组，且当前分组已开放 Messages 兼容能力；否则返回 403 `This group does not allow /v1/messages dispatch`。 - 服务会按当前分组的兼容规则处理 Anthropic `model`；实际模型以当前分组模型列表和用量明细为准。 - 部分兼容路径会以流式方式处理请求；客户端传 `stream:false` 时，服务会聚合后返回非流式 Anthropic Messages 响应。 - 该兼容入口适合 Claude Code/Anthropic SDK 接入 OpenAI 或 Grok 分组；Grok 分组需要开启 Messages ingress 能力。 --- ## count_tokens 行为 `POST /v1/messages/count_tokens` 用于正式发送前估算输入 token: - `/v1/messages` 原生支持 Claude/Anthropic 分组;OpenAI/Grok 分组在开启 Messages ingress 时会经网关转换支持。 - `/v1/messages/count_tokens` 对 OpenAI/Grok 分组固定 404;其他 Anthropic-compatible 分组是否支持由平台能力决定，也可能返回 404。 - 它是辅助估算端点，不等同于正式对话；主 `/v1/messages` 成功而 count_tokens 404 时，通常只是客户端 token 估算回退。 - 请求体使用 Messages 形态,可包含 `system`、`messages`、`tools`、`thinking` 等字段;部分不适合计数的字段会在上游请求前清理。 - 返回 Anthropic 形态,核心字段为 `input_tokens`。 ```bash curl https://api.clomio.ai/v1/messages/count_tokens \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "这段话有多少 token?"}] }' ``` 返回: ```json { "input_tokens": 11 } ``` --- ## 实战场景 ### 场景一:工具调用与工具结果回传 第一轮让模型选择工具: ```json { "model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role":"user","content":"北京现在天气如何?"}], "tools": [{ "name": "get_weather", "description": "查询城市天气", "input_schema": { "type": "object", "properties": {"city": {"type":"string"}}, "required": ["city"] } }], "tool_choice": {"type":"auto"} } ``` 若响应 `stop_reason:"tool_use"`,把工具结果作为下一轮 `user` 消息回传: ```json { "model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [ {"role":"user","content":"北京现在天气如何?"}, {"role":"assistant","content":[{"type":"tool_use","id":"toolu_1","name":"get_weather","input":{"city":"北京"}}]}, {"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_1","content":"{\"temp\":\"28C\",\"condition\":\"晴\"}"}]} ] } ``` ### 场景二:缓存控制长上下文 ```json { "model": "claude-sonnet-4-6", "max_tokens": 1024, "system": [{ "type": "text", "text": "下面是长期稳定的项目背景和编码规范...", "cache_control": {"type":"ephemeral","ttl":"1h"} }], "messages": [{ "role": "user", "content": [{"type":"text","text":"基于这些规范,检查这个补丁。"}] }] } ``` 响应 usage 中如出现 `cache_creation_input_tokens` 或 `cache_read_input_tokens`,表示上游返回了缓存写入/读取用量。 ### 场景三:Extended thinking + output_config ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 4096, "thinking": {"type":"enabled","budget_tokens":2000}, "output_config": {"effort":"high"}, "messages": [{"role":"user","content":"分析这个并发 bug 的可能根因,最后给出修复顺序。"}] }' ``` 响应 `content` 可能同时包含 `thinking` 与最终 `text` block;流式时对应 `thinking_delta` 和 `text_delta`。 ### 场景四:发送前先估价,超长就提示 ```python from anthropic import Anthropic client = Anthropic(api_key="你的密钥", base_url="https://api.clomio.ai") def ask(text, budget=4000): n = client.messages.count_tokens( model="claude-sonnet-4-6", messages=[{"role": "user", "content": text}], ).input_tokens if n > budget: return f"输入约 {n} token,超过预算 {budget},请精简后再问。" msg = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, messages=[{"role": "user", "content": text}], ) return msg.content[0].text print(ask("帮我把这段话润色一下:今天我很开心")) ``` --- > 命令行装 Claude Code 见 [Claude Code 接入](#/claude-code);OpenAI SDK 客户端可用 [Chat Completions](#/api-chat) 或 [Responses](#/api-responses)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前分组可见的 Claude/Grok/OpenAI 模型 | 必填 | | `max_tokens` | 正整数 | 必填，包含 thinking 和最终输出预算 | | `messages[].role` | `user` / `assistant` | 系统指令使用顶层 `system` | | `content` | string 或 block 数组 | 支持 `text`、`image`、`document`、`tool_use`、`tool_result` | | `stream` | `true` / `false` | 流式返回 Anthropic SSE 事件 | | `thinking.type` | `enabled` / `adaptive` / `disabled` | `enabled` 还需 `budget_tokens` 正整数 | | `output_config.effort` | `low` / `medium` / `high` | 模型支持时生效 | | `tool_choice.type` | `auto` / `any` / `tool` | `tool` 时填写 `name` | | `system` | string 或 text block 数组 | 系统提示 | ## 完整错误目录 | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `Request body is empty`、`Failed to parse request body`、`model is required` | 修正 JSON 和必填字段 | | 400 | `max_tokens must be greater than 0`、thinking budget 不合法 | 使用正整数且不超过模型上下文 | | 400 | content block 类型未知或字段缺失 | 按 `text/image/document/tool_use/tool_result` 结构发送 | | 401 | `Invalid API key` | 使用对应平台 Key | | 403 | `This group does not allow /v1/messages dispatch` | 开启 Messages ingress 或更换分组 | | 404 | 不支持模型/路径 | 查看 `/v1/models` | | 413 | body 超过网关限制 | 压缩图片、拆分上下文 | | 429 | 额度、RPM、并发或上游限速 | 退避重试 | | 502/503 | 上游认证失败或服务暂时不可用 | 保存 `x-request-id` 和错误体 | --- # Gemini 原生兼容 Gemini 原生兼容入口用于接入会按 Google Gemini REST 形状请求 `/v1beta/models...` 的 SDK、CLI 或工具。它不是 OpenAI-compatible `/v1` 入口,Base URL 必须填服务根地址。 | 项 | 值 | |---|---| | Base URL | `https://api.clomio.ai`(线路可换 `https://sub.qazwc.com` / `https://crs.qazwc.com`) | | 路径前缀 | `/v1beta` | | Key 分组 | Google/Gemini 平台分组 | | 推荐鉴权 | `Authorization: Bearer 你的Gemini分组密钥` 或 `x-goog-api-key: 你的Gemini分组密钥` | | 官方形状参考 | [Gemini generateContent](https://ai.google.dev/api/generate-content)、[Gemini API versions](https://ai.google.dev/gemini-api/docs/api-versions)、[Models API](https://ai.google.dev/api/models) | > Google GenAI SDK 默认常用 `v1beta` 以访问预览能力。Clomio 的 Gemini 原生兼容也是围绕 `/v1beta/...` 路径工作;不要把 Base URL 写成 `https://api.clomio.ai/v1`。 --- ## 端点 | 方法 | 路径 | 用途 | |---|---|---| | `GET` | `/v1beta/models` | 列出当前 Gemini 分组可见模型 | | `GET` | `/v1beta/models/{model}` | 查询单个 Gemini 模型元数据 | | `POST` | `/v1beta/models/{model}:generateContent` | 非流式生成 | | `POST` | `/v1beta/models/{model}:streamGenerateContent?alt=sse` | SSE 流式生成 | | `POST` | `/v1beta/models/{model}:countTokens` | 计数；部分模型不支持时可能返回估算或错误 | 服务端也兼容部分 `/v1beta/models/{model}/{action}` 形态,但新接入建议使用官方冒号 action 形态,例如 `models/gemini-2.5-flash:generateContent`。路由会先接收 `POST /v1beta/models/*modelAction`，再解析 `{model}:{action}` 或 `{model}/{action}`；未知 action 会由服务返回 Google 风格 unsupported 错误。 --- ## 鉴权优先级 Gemini 原生入口使用 Google/Gemini 风格鉴权。服务端按以下顺序取 Key: 1. `x-goog-api-key` 2. `Authorization: Bearer ...` 3. `x-api-key` 4. Query `key=...`(仅 `/v1beta` / `/antigravity/v1beta` 兼容) 不要使用 query `api_key=...`;该参数已废弃,会返回 400: ```json { "error": { "code": 400, "message": "Query parameter api_key is deprecated. Use Authorization header or key instead.", "status": "INVALID_ARGUMENT" } } ``` --- ## generateContent 最小示例 ```bash curl https://api.clomio.ai/v1beta/models/gemini-2.5-flash:generateContent \ -H "Authorization: Bearer 你的Gemini分组密钥" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [{ "text": "你好,用一句话介绍 Gemini 原生接口" }] } ], "generationConfig": { "maxOutputTokens": 512, "temperature": 0.7 } }' ``` 流式 SSE: ```bash curl 'https://api.clomio.ai/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse' \ -H "x-goog-api-key: 你的Gemini分组密钥" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [{ "text": "用一句话回答:SSE 是什么?" }] } ] }' ``` --- ## 常用请求字段 | 字段 | 说明 | |---|---| | `contents[].role` | `user` / `model` 等会话角色 | | `contents[].parts[].text` | 文本输入片段 | | `systemInstruction` | 系统指令 | | `generationConfig.maxOutputTokens` | 最大输出 token | | `generationConfig.temperature` / `topP` / `topK` | 采样参数 | | `generationConfig.stopSequences` | 停止序列 | | `generationConfig.thinkingConfig` | 思考/推理相关配置,是否生效取决于模型 | | `generationConfig.imageConfig.aspectRatio` / `imageSize` | 图像相关模型的图片配置 | | `tools[].functionDeclarations` | 函数调用声明 | | `tools[].googleSearch` | Google Search grounding 工具声明 | | `toolConfig` | 工具调用配置 | | `safetySettings` | 安全设置,是否可用取决于模型 | ### `thoughtSignature` 兼容性 函数调用响应可能包含 `thoughtSignature`。继续发送工具结果时请原样保留该字段；如果客户端丢失或修改签名，Gemini 可能返回 `INVALID_ARGUMENT`。排查时保存 request_id、请求体和完整错误响应。 `countTokens` 是辅助估算端点；部分模型可能返回估算值或不支持该操作。不要把它的失败等同于主 `generateContent` 失败。 --- ## 模型列表与模型名 ```bash curl https://api.clomio.ai/v1beta/models \ -H "Authorization: Bearer 你的Gemini分组密钥" ``` 返回的是 Google/Gemini 风格模型对象,模型名通常带 `models/` 前缀。请求路径里的 `{model}` 可以写 `gemini-2.5-flash`,也可以按客户端习惯由 SDK 拼出 `models/gemini-2.5-flash`。实际可见模型以当前分组模型列表为准。 不要把 Gemini 模型查询误写成 OpenAI 的 `GET /v1/models/{id}`。OpenAI-compatible 模型端点只支持 [Models](#/api-models) 里的 `GET /v1/models` 列表;Gemini 单模型查询走本页的 `GET /v1beta/models/{model}`。 --- ## Google 风格错误体 Gemini 原生入口的错误体更接近 Google API 风格: ```json { "error": { "code": 401, "message": "Invalid API key", "status": "UNAUTHENTICATED" } } ``` 鉴权、分组、路径、限流和计费错误都会按这个结构返回,固定包含 `error.code`、`error.message`、`error.status`。`status` 是 Google RPC 风格字符串,例如 400 → `INVALID_ARGUMENT`、401 → `UNAUTHENTICATED`、403 → `PERMISSION_DENIED`、429 → `RESOURCE_EXHAUSTED`。 | 状态码 | message / 关键词 | 含义与处理 | |---:|---|---| | 400 | `API key group platform is not gemini` | Key 不是 Gemini 分组;换 Gemini 分组 Key | | 400 | `Missing model in URL` / `Missing action in URL` | 路径缺模型或 action;检查 `/v1beta/models/{model}:generateContent` | | 400 | `Request body is empty` / `Failed to read request body` | Body 为空或无法读取 | | 401 | `API key is required` / `Invalid API key` / `API key is disabled` | Key 缺失、错误或禁用 | | 401 | `User associated with API key not found` / `User account is not active` | Key 绑定用户异常 | | 403 | `No active subscription found for this group` | 分组需要有效订阅 | | 403 | `Insufficient account balance` | 余额不足 | | 403 | `API Key is not assigned to any group...` | Key 未绑定分组 | | 404 | `missing path` / `invalid model action path` / `Unsupported action: ...` | 路径或 action 不支持 | | 413 | `Request body too large...` | 请求体过大 | | 429 | `Upstream rate limit exceeded, please retry later` | 请求频率过高;降并发后重试 | | 502 | `Upstream authentication failed` / `Upstream access forbidden...` / `Upstream request failed` | 上游鉴权或请求失败，带时间和错误体提交工单 | | 503 | `No available Gemini accounts` / `Upstream service overloaded...` | 当前 Gemini 服务暂时不可用或上游过载 | 上游 failover 耗尽时有一个例外:如果最后一个 Gemini 上游返回了非空响应体,网关会优先保留该上游状态码、响应头和原始 body。此时 body 可能仍是 Google 风格 JSON,也可能是上游自己的 JSON/text;排障时请同时保存 HTTP status、`x-request-id`/`x-goog-request-id`、响应体和 Clomio request_id。只有没有可透传 body 时,才会映射成上表里的 `Upstream ...` 消息。 --- ## 和其他入口的边界 - OpenAI SDK / Codex / Grok 仍用 `https://api.clomio.ai/v1`,不要改成本页 Base URL。 - Claude Code / Anthropic SDK 用 `https://api.clomio.ai`,但请求形状是 `/v1/messages`,不是 `/v1beta/models...`。 - Antigravity 专用入口也不带 `/v1`,但路径以 `/antigravity/...` 开头,见 [Antigravity 接入](#/antigravity)。 - Videos 仅 Grok 分组支持;Gemini 原生入口不提供 `/v1/videos/*`。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | URL action | `generateContent`、`streamGenerateContent`、`countTokens` | action 必须和模型路径绑定 | | `contents[].role` | `user` / `model` | 多轮消息按时间顺序排列 | | `parts[]` | `text`、`inlineData`、`fileData`、`functionCall`、`functionResponse` | 图片/文件使用对应结构 | | `generationConfig.temperature` | `0` 至 `2` | 随机性 | | `generationConfig.topP` | `0` 至 `1` | 核采样 | | `generationConfig.topK` | 正整数 | 候选采样数量 | | `generationConfig.maxOutputTokens` | 正整数 | 输出上限 | | `generationConfig.candidateCount` | 正整数，通常为 `1` | 多候选能力以上游模型为准 | | `safetySettings[].threshold` | `BLOCK_NONE`、`BLOCK_ONLY_HIGH`、`BLOCK_MEDIUM_AND_ABOVE`、`BLOCK_LOW_AND_ABOVE` | 类别由 Google API 定义 | ## 完整请求示例：多模态与流式 ```bash curl 'https://api.clomio.ai/v1beta/models/gemini-2.5-flash:generateContent' \ -H 'Authorization: Bearer 你的 Gemini 分组密钥' \ -H 'Content-Type: application/json' \ -d '{ "contents":[{"role":"user","parts":[ {"text":"描述这张图片"}, {"inlineData":{"mimeType":"image/png","data":"BASE64_DATA"}} ]}], "generationConfig":{"temperature":0.2,"topP":0.9,"maxOutputTokens":512} }' ``` 流式请求追加 `?alt=sse` 并使用 `:streamGenerateContent`；每个 SSE 块都是 Gemini response 增量对象，客户端应合并 `candidates[].content.parts[]`。 ## 错误速查 | HTTP | `error.status`/关键词 | 处理 | |---:|---|---| | 400 | `INVALID_ARGUMENT`、`Missing model/action` | 检查 URL、JSON 和字段范围 | | 401 | `UNAUTHENTICATED` | 检查 `x-goog-api-key`/Authorization | | 403 | `PERMISSION_DENIED`、余额/订阅不足 | 检查分组和账户额度 | | 404 | `NOT_FOUND`、模型或 action 不存在 | 使用 `/v1beta/models` 返回的模型 | | 429 | `RESOURCE_EXHAUSTED` | 降低 RPM/并发，按 Retry-After 重试 | | 500/502/503 | Gemini 服务或上游暂时不可用 | 记录 `x-request-id`、`x-goog-request-id` 和原始 body | --- # Embeddings 把文本或 token 数组转成向量，用于语义搜索、相似度、聚类、推荐、分类、RAG 检索等。 ```text POST https://api.clomio.ai/v1/embeddings ``` > **分组要求:** **仅 OpenAI 分组**支持。其他分组返回 404，见 [端点 × 分组](#/api-usage)。新接入统一使用 `/v1/embeddings`。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥` | | `Content-Type` | 是 | `application/json` | --- ## 请求校验与字段边界 服务只做必要的请求格式校验： - 请求体不能为空。 - 请求体必须是合法 JSON，否则返回 400 `Failed to parse request body`。 - 请求体超过服务限制时返回 413 `invalid_request_error`。 - `model` 必须存在、必须是非空 string，否则返回 400 `model is required`。 - 端点只允许 OpenAI 分组；Grok/Claude/Gemini/其他分组返回 404 `Embeddings API is not supported for this platform`。 除 `model` 可能经过模型映射外，`input`、`encoding_format`、`dimensions`、`user` 等字段基本按原 JSON 透传给 OpenAI-compatible 上游；输入是否为空、token 上限、`dimensions` 是否被该模型支持、`encoding_format` 是否有效，主要由上游按 OpenAI Embeddings API 规则判断并返回错误。Embeddings 当前只面向 OpenAI 分组；如果持续出现 upstream error，请带 `x-request-id` 和错误体提交工单。 OpenAI 官方参数参考：；向量用途参考：。 Embeddings 是同步 HTTP JSON 请求,没有 SSE/WebSocket 流式输出,也不会返回 job id 或轮询进度；服务会一次性返回完整结果。即使客户端误传 `stream`,也按同步请求处理；需要进度显示时请在应用层分批调用。 --- ## 请求参数 | 参数 | 类型 | 必填 | 处理 / 说明 | |------|------|:----:|------| | `model` | string | 是 | 必须是当前分组可用的 Embeddings 模型 | | `input` | string / string[] / number[] / number[][] | OpenAI 语义必填 | 支持单条文本、批量文本、token 数组或 token 数组批量；具体上限以模型说明为准 | | `encoding_format` | string | 否 | `float` 或 `base64`；透传上游 | | `dimensions` | integer | 否 | 输出维度裁剪；OpenAI 文档说明仅 `text-embedding-3` 及后续模型支持 | | `user` | string | 否 | 终端用户标识；透传上游 | OpenAI 官方限制会随模型变化；单个输入不能超过模型 token 上限，数组批量也有总 token 上限。超出范围时服务会返回对应错误。 --- ## 响应 服务返回 OpenAI 兼容的响应体和 usage。 | 字段 | 类型 | 说明 | |------|------|------| | `object` | string | 通常为 `list` | | `data` | array | 每条输入对应一个 `{embedding, index, object}` | | `data[].embedding` | number[] 或 string | `encoding_format:"float"` 时是浮点数组；`base64` 时由上游/SDK 表现决定 | | `model` | string | 上游实际使用模型 | | `usage` | object | `prompt_tokens` / `total_tokens` | ```json { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456] } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 6, "total_tokens": 6 } } ``` --- ## 最小可验证 curl “单条”示例可验证 OpenAI-only 路由、`model` 必填校验、`input` 处理和成功响应中的 `data[].embedding`/`usage`；删除 `model` 可验证 400 `model is required`。 ## 示例: 单条 ```bash curl https://api.clomio.ai/v1/embeddings \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "text-embedding-3-small", "input": "今天天气真好", "encoding_format": "float" }' ``` ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") r = client.embeddings.create( model="text-embedding-3-small", input="今天天气真好", encoding_format="float", ) print(len(r.data[0].embedding), "维") ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" }); const r = await client.embeddings.create({ model: "text-embedding-3-small", input: "今天天气真好", encoding_format: "float", }); console.log(r.data[0].embedding.length, "维"); ``` --- ## 示例: 批量与降维 `input` 传数组即可一次嵌入多条，`data` 按 `index` 对应。支持的 `dimensions` 取决于上游模型： ```bash curl https://api.clomio.ai/v1/embeddings \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "text-embedding-3-small", "input": ["第一句", "第二句", "第三句"], "dimensions": 512, "encoding_format": "float" }' ``` --- ## 实战场景: 语义搜索 把一批文档嵌入，再用余弦相似度找出和提问最相关的一条： ```python import numpy as np from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") MODEL = "text-embedding-3-small" docs = [ "Clomio 提供三条网关线路:直连、CF 优化、三网优化。", "Claude Code 用 ANTHROPIC_BASE_URL 接入网关。", "Codex 的配置写在 config.toml 里。", ] def embed(texts): r = client.embeddings.create(model=MODEL, input=texts, encoding_format="float") return [np.array(d.embedding) for d in r.data] doc_vecs = embed(docs) q_vec = embed(["怎么换线路?"])[0] def cosine(a, b): return a @ b / (np.linalg.norm(a) * np.linalg.norm(b)) ranked = sorted(zip(docs, doc_vecs), key=lambda x: cosine(q_vec, x[1]), reverse=True) print("最相关:", ranked[0][0]) ``` 实际项目里，可把文档向量存入向量检索系统；查询时只对问题做一次嵌入即可。 --- ## 排障 | 现象 | 常见原因 | 处理 | |------|----------|------| | 404 `Embeddings API is not supported for this platform` | API Key 不在 OpenAI 分组 | 换 OpenAI 分组 Key | | 400 `Request body is empty` | 空 body | 发送 JSON 请求体 | | 400 `Failed to parse request body` | JSON 非法或 Content-Type/SDK 传参错误 | 用 `jq`/SDK 检查最终 body | | 400 `model is required` | `model` 缺失、非 string 或空字符串 | 传入非空嵌入模型名 | | 413 `invalid_request_error` | 请求体超过网关限制 | 缩小批量或分批调用 | | 403 `permission_error` / `The current group does not support the requested model ... Available models: ...` | 当前分组不支持请求模型 | 按 Available models 换模型 | | 404 `model_not_found` | 当前分组没有该模型 | 核对模型名和模型列表 | | 503 `api_error` / `Service temporarily unavailable` | 当前没有可用服务资源或请求过载 | 稍后重试、降低并发或更换分组 | | 502 `upstream_error` / `api_error` | 服务提供方请求失败 | 保存错误体和 `x-request-id` 提交支持 | | 上游报 `dimensions` 不支持 | 模型不支持降维 | 换 `text-embedding-3*` 或移除 `dimensions` | | 上游报 input/token 限制 | 输入为空、批量过大或超过模型 token 上限 | 分批、清理空字符串、缩短文本 | | 返回维度和预期不同 | 模型默认维度不同或设置了 `dimensions` | 统一索引库维度；已有向量库不可混用不同维度 | --- > Embeddings 常配合向量数据库做 RAG。对话端点见 [Responses](#/api-responses) 或 [Chat Completions](#/api-chat)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前 OpenAI 分组可用的 embedding 模型 | 必填 | | `input` | 非空 string 或 string 数组 | 批量数组大小和 token 上限以上游模型为准 | | `encoding_format` | `float` / `base64` | 默认通常为 `float` | | `dimensions` | 正整数 | 仅支持降维的模型可用；超出模型维度会被上游拒绝 | | `user` | string | 可选的最终用户标识 | ## 完整响应与错误 ```json { "object":"list", "data":[{"object":"embedding","index":0,"embedding":[0.01,-0.02]}], "model":"text-embedding-3-small", "usage":{"prompt_tokens":4,"total_tokens":4} } ``` | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | body 非法、`model is required`、input 为空 | 修正 JSON、模型和 input | | 400 | `dimensions`/`encoding_format` 不支持 | 删除参数或按模型文档调整 | | 401/403 | Key 无效、分组不是 OpenAI | 更换 OpenAI 分组 Key | | 413 | 请求体过大 | 缩小批量并分批提交 | | 429 | 请求或上游限流 | 指数退避 | | 502/503 | 上游请求失败或服务暂时不可用 | 带 `x-request-id` 排查 | --- # Images（OpenAI/Grok） 文生图与图像编辑。该端点在网关里同时开放给 **OpenAI 分组**和 **Grok 分组**。 ```text POST https://api.clomio.ai/v1/images/generations POST https://api.clomio.ai/v1/images/edits # 兼容别名: POST https://api.clomio.ai/images/generations POST https://api.clomio.ai/images/edits ``` > **分组要求:** OpenAI 或 Grok 分组支持；其他分组返回 404。见 [端点 × 分组](#/api-usage)。Videos 端点是 Grok-only，这里只作为相邻能力旁注，具体见 [Videos](#/api-videos)。 --- ## 路由与上游形态 | 场景 | 网关行为 | 适合用途 | |------|----------|----------| | `/v1/images/generations` / `/v1/images/edits` + OpenAI 分组 | 使用 OpenAI-compatible Images 能力 | 单次文生图、单次编辑、SDK `client.images.generate/edit` | | `/v1/images/*` + OpenAI/Codex 图片模型 | 使用分组开放的图片能力 | Codex/Responses 图片工作流 | | `/v1/images/*` + Grok 分组 | 使用 xAI/Grok 图片能力；模型名前缀需是 `grok-imagine-` | Grok Imagine 图片生成/编辑 | | `/v1/responses` + `tools:[{"type":"image_generation"}]` | 不是本页 Images API；这是 Responses 图片工具路径 | 多轮对话中生成/继续编辑图片 | OpenAI 官方也把 Image API 与 Responses API 图片工具区分为两条入口：Image API 适合单次生成/编辑，Responses API 适合对话式、多步图片体验。参考：、。 Grok Imagine 图片属于 xAI/Grok 能力。模型名请使用控制台分组开放的 `grok-imagine-*` 前缀模型；不要把 OpenAI `gpt-image-*` 模型名拿到 Grok 分组里测。若上游返回临时 URL，建议立刻下载保存到自己的对象存储或本地文件，避免后续链接过期、权限变化或无法复现。 ### Grok/xAI Imagine 响应差异 Grok Imagine 默认常见 `data[0].url` 响应，也支持 `aspect_ratio`、`resolution` 等字段；需要内联图片时传 `response_format:"b64_json"`。当前服务对显式 `response_format:"url"` 返回 400，因此想拿 URL 时请省略该字段。响应还可能带 `mime_type`、`revised_prompt` 和 usage 元数据,客户端应按实际响应读取。 JSON edits 使用本文下方的 `images[]` 形态；`image:{...}` 不是当前服务接受的 JSON 编辑格式。 --- ## 请求校验与字段边界 服务会先做以下请求校验/规范化： - 请求体不能为空；JSON 请求必须是合法 JSON，否则返回 `Request body is empty` / `failed to parse request body`；`multipart/form-data` 必须带 boundary。 - `model` 为空时默认填 `gpt-image-2`；非空时必须是图片模型前缀：`gpt-image-*` 或 `grok-imagine-*`，否则 400：`images endpoint requires an image model, got "..."`。 - `n` 必须是正整数，上限为 10；JSON 类型错误返回 `invalid n field type`，越界返回 `n must be between 1 and 10`。 - `size` 会被规范化：空值保持空、`auto` 保持 `auto`、`1k/2k/4k` 会映射为尺寸；不合法 `宽x高` 会尽量校正到最近的合法尺寸，无法解析时回落 `1024x1024`。 - 合法尺寸约束：宽高为正数、最大边不超过 `3840`、宽高比不超过 `3:1`、总像素在 `655360..8294400`，并按 16 像素步进校正。 - `stream` 必须是 boolean，JSON 非 boolean 返回 `invalid stream field type`，multipart 无法解析为 bool 返回 `invalid stream field value`；`output_compression` / `partial_images` 必须是数字，范围分别为 0..100 / 0..3。multipart 单个 part 约 50MB 上限,超过会返回 `payload exceeds 52428800 bytes`。 - `response_format` 只接受空值或 `b64_json`；显式传 `url` 会被拒绝：`response_format=url is not supported for gpt-image models; use b64_json`。Grok 想拿 URL 时请省略该字段。 - `background:"transparent"` 需要 `output_format` 为 `png` 或 `webp`；`output_compression` 只在 `output_format` 为 `jpeg` 或 `webp` 时有效；`input_fidelity` 不支持 `gpt-image-2`。 - edits：`multipart/form-data` 必须上传 `image` 文件；JSON edits 必须提供 `images[].image_url` 或 `images[].file_id`。 - edits 的 `mask` 图片若尺寸与首张 `image` 不同，网关会尝试按首图尺寸重采样为 PNG。 其他模型支持细节主要由模型决定：例如 `quality`、`moderation`、`style` 是否被接受，以及返回的错误字段。OpenAI 官方说明 `gpt-image-2` 支持灵活尺寸但不支持透明背景；服务会先拒绝明显不合法的 `transparent` + 非 `png/webp` 组合。参考：。 --- ## 文生图: generations ### 请求参数 | 参数 | 类型 | 必填 | 处理 / 说明 | |------|------|:----:|------| | `model` | string | 否 | 空值默认 `gpt-image-2`；非空必须为 `gpt-image-*` 或 `grok-imagine-*` | | `prompt` | string | 上游通常要求 | 画面描述；具体必填和长度限制以模型为准 | | `n` | integer | 否 | 默认 1；必须 >0，上限 10 | | `size` | string | 否 | OpenAI/GPT Image 常用尺寸字段,支持 `auto`、`1k/2k/4k`、`宽x高`；网关会规范化/就近校正 | | `aspect_ratio` | string | 否 | Grok/xAI Imagine 常用画幅字段,如 `16:9` | | `resolution` | string | 否 | Grok/xAI Imagine 常用分辨率字段,如 `1k`/`2k` | | `quality` | string | 否 | `low` / `medium` / `high` / `auto` 等，是否支持由模型决定 | | `background` | string | 否 | `opaque` / `auto`；透明背景取决于模型，`gpt-image-2` 当前不支持 `transparent` | | `output_format` | string | 否 | `png` / `webp` / `jpeg` | | `output_compression` | integer | 否 | JPEG/WebP 压缩质量，0-100；必须是数字 | | `moderation` | string | 否 | 模型支持时的审核强度提示 | | `style` | string | 否 | 旧模型/特定模型选项，网关识别后透传 | | `stream` | boolean | 否 | 流式返回；必须是 boolean | | `partial_images` | integer | 否 | 流式时的中间图数量；必须是数字，范围 0..3 | | `response_format` | string | 否 | 只接受空值或 `b64_json`；`url` 会被拒绝 | | `conversation_id` / `parent_message_id` | string | 否 | 多轮图片工作流的可选会话标识 | | `original_file_id` / `original_gen_id` | string | 否 | 引用已有图片或生成结果的可选标识 | | `mask_file_id` | string | 否 | 引用已有蒙版的可选标识 | ### 响应 OpenAI GPT Image 响应示例应优先按 `data[].b64_json` 处理，不要把示例写成读取 URL 字段；Grok/xAI Imagine 默认常见 `data[].url`，如果需要 inline/base64 再显式传 `response_format:"b64_json"`： ```json { "created": 1730000000, "data": [{ "b64_json": "" }], "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 } } ``` 旧模型或部分兼容上游可能返回 `data[].url`；Grok/xAI 默认也常见 URL。GPT Image 常规示例应解码 `b64_json`，OpenAI 官方示例也是读取 `response.data[0].b64_json` 后 base64 解码保存。 ### 最小可验证 curl 下面请求可验证 OpenAI/Grok 图片路由、图片模型前缀、`response_format` 限制和常规 `data[].b64_json` 响应处理；把 `response_format` 改为 `url` 可验证错误 `response_format=url is not supported for gpt-image models; use b64_json`。 ### 示例 ```bash curl https://api.clomio.ai/v1/images/generations \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "一只在钢琴上弹奏的橘猫,扁平插画风格,浅色背景", "size": "1024x1024", "quality": "high", "n": 1 }' | jq -r '.data[0].b64_json' | base64 --decode > cat.png ``` ```python import base64 from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") r = client.images.generate( model="gpt-image-2", prompt="一只在钢琴上弹奏的橘猫,扁平插画风格", size="1024x1024", ) img = base64.b64decode(r.data[0].b64_json) open("cat.png", "wb").write(img) print("已保存 cat.png") ``` ```javascript import fs from "fs"; import OpenAI from "openai"; const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" }); const r = await client.images.generate({ model: "gpt-image-2", prompt: "一只在钢琴上弹奏的橘猫,扁平插画风格", size: "1024x1024", }); fs.writeFileSync("cat.png", Buffer.from(r.data[0].b64_json, "base64")); console.log("已保存 cat.png"); ``` --- ## 图像编辑: edits 用 `multipart/form-data` 上传原图及可选蒙版，或用 JSON 提供已上传文件/图片 URL 引用。 ### 请求参数: multipart/form-data | 字段 | 类型 | 必填 | 处理 / 说明 | |------|------|:----:|------| | `model` | string | 否 | 空值默认 `gpt-image-2`；非空必须为图片模型前缀 | | `image` / `image[]` | file | 是 | 原图；可多张，单个 part 当前读取上限 50MB | | `prompt` | string | 上游通常要求 | 修改描述；具体必填和长度限制以模型为准 | | `mask` | file | 否 | 蒙版；尺寸不一致时网关尝试按首图尺寸重采样 | | `size` | string | 否 | 同 generations，网关会规范化/就近校正 | | `n` | integer | 否 | 默认 1；必须 >0，上限 10 | | `quality` | string | 否 | 透传，是否支持由模型决定 | | `background` | string | 否 | 透传/模型决定；`gpt-image-2` 不支持透明背景 | | `output_format` | string | 否 | `png` / `webp` / `jpeg` | | `output_compression` | integer | 否 | 必须是整数 | | `input_fidelity` | string | 否 | 是否支持由模型决定；OpenAI 文档说明 `gpt-image-2` 自动高保真，不允许手动改变 | | `style` / `moderation` / `partial_images` / `stream` | mixed | 否 | 按模型支持范围处理 | | `original_file_id` / `original_gen_id` / `mask_file_id` | string | 否 | 可与远程图片或已上传文件引用配合 | ### 请求参数: JSON edits JSON 方式适合复用已上传文件或远程图片： ```json { "model": "gpt-image-2", "prompt": "把背景换成星空", "images": [ { "image_url": "https://example.com/cat.png" } ], "mask": { "image_url": "https://example.com/mask.png" }, "size": "1024x1024" } ``` `images` 必须是数组，且至少一个元素包含 `image_url` 或 `file_id`；也可用 `original_file_id`、`original_gen_id`、`mask.file_id` 或 `mask_file_id` 引用已有素材。 ### 示例 ```bash curl https://api.clomio.ai/v1/images/edits \ -H "Authorization: Bearer 你的密钥" \ -F model="gpt-image-2" \ -F image="@cat.png" \ -F prompt="把背景换成星空" \ -F size="1024x1024" \ | jq -r '.data[0].b64_json' | base64 --decode > edited.png ``` ```python import base64 from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") r = client.images.edit( model="gpt-image-2", image=open("cat.png", "rb"), prompt="把背景换成星空", ) img = base64.b64decode(r.data[0].b64_json) open("edited.png", "wb").write(img) print("已保存 edited.png") ``` --- ## Responses image_generation tool 对照 如果你的请求本来是对话式 `/v1/responses`，不要改成 `/v1/images/*`；应在 Responses 请求中声明图片工具： ```json { "model": "gpt-5.5", "input": "画一张白底产品图", "tools": [{ "type": "image_generation", "size": "1024x1024", "quality": "high", "output_format": "png" }] } ``` 网关的 Responses 图片工具路径会规范化 `tools[].size`，并把旧字段 `format` / `compression` 迁移为 `output_format` / `output_compression`。OpenAI 官方说明该工具返回 `image_generation_call`，图片结果在该调用项的 `result` 字段中；它和 `client.images.generate()` 的 `data[0].b64_json` 不是同一个响应形态。 --- ## 实战场景: 批量生成并保存到本地 ```python import base64 from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") prompts = ["赛博朋克城市夜景", "水彩风格的山间小屋", "扁平插画的办公场景"] for i, p in enumerate(prompts): r = client.images.generate( model="gpt-image-2", prompt=p, size="1024x1024", quality="high", ) img = base64.b64decode(r.data[0].b64_json) with open(f"out_{i}.png", "wb") as f: f.write(img) print("已保存 out_%d.png" % i) ``` --- ## 排障 | 现象 | 常见原因 | 处理 | |------|----------|------| | 404 `Images API is not supported for this platform` | API Key 所在分组不是 OpenAI/Grok | 换到 OpenAI 或 Grok 分组 | | 403 `Image generation is not enabled for this group` | 当前分组未开放图片能力 | 更换已开放图片能力的 OpenAI/Grok 分组；如应已开放，带 `x-request-id` 提交工单 | | 403 `Codex image generation is not enabled for this group` | 当前 OpenAI 分组未开放 Codex/Responses 图片能力 | 改用原生 Images API，或更换已开放该能力的 OpenAI 分组 | | 400 `images endpoint requires an image model, got ...` | 实际使用的模型不是图片模型 | 检查请求 `model` 是否来自控制台图片模型列表；图片端点只能用 `gpt-image-*` / `grok-imagine-*`，持续异常带 `x-request-id` 提交工单 | | 400 `Request body is empty` / `failed to parse request body` | 空 body 或 JSON 非法 | 发送合法 JSON 或 multipart | | 400 `response_format=url is not supported for gpt-image models; use b64_json` | 请求显式要求 URL 返回 | 移除 `response_format` 或改为 `b64_json` | | 400 `invalid stream field type` / `invalid stream field value` | `stream` 不是 boolean | JSON 传 true/false，multipart 传 true/false 字符串 | | 400 `invalid output_compression field type` / `invalid partial_images field type` / `partial_images must be between 0 and 3` / `output_compression must be between 0 and 100` | 数值类型或范围不合法 | 按文档范围修正 | | 400 `background=transparent requires output_format png or webp` | 透明背景和输出格式不匹配 | 把 `output_format` 改为 `png`/`webp` 或取消透明背景 | | 400 `output_compression is only supported when output_format is jpeg or webp` | 对 PNG/auto 使用压缩参数 | 改为 `jpeg`/`webp` 或删除 `output_compression` | | 400 `input_fidelity is not supported for gpt-image-2` | `gpt-image-2` 不接受该字段 | 删除 `input_fidelity` 或换支持模型 | | 400 `multipart boundary is required` / `payload exceeds 52428800 bytes` | multipart 缺 boundary 或单个 part 太大 | 修正 Content-Type 或压缩/拆分文件 | | 400 `image file is required` | edits multipart 未上传 `image` | 使用 `-F image=@file.png` 或 JSON `images[]` | | 没有 `url` 字段 | GPT Image 常规返回 `b64_json` | 用 `base64.b64decode(r.data[0].b64_json)` 保存 | | Grok Imagine 返回 URL 后过期/打不开 | 上游图片 URL 可能是临时链接或受权限控制 | 成功后马上下载保存；不要把 URL 当长期素材库 | | 透明背景失败 | 所选模型不支持，如 `gpt-image-2` | 改用 `background:"auto"/"opaque"` 或换模型 | ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | `gpt-image-*` 或 `grok-imagine-*` | 必须是当前分组开放的图片模型 | | `n` | `1` 至 `10` | 生成数量；上游可能有更低限制 | | `size` | `auto`、`1k`、`2k`、`4k` 或合法 `宽x高` | GPT Image 会按模型规则校正尺寸 | | `quality` | `auto`、`low`、`medium`、`high` | Grok 模型是否支持由上游决定 | | `background` | `auto`、`opaque`、`transparent` | transparent 还要求 `output_format` 为 png/webp | | `output_format` | `png`、`jpeg`、`webp` | 具体模型支持由上游决定 | | `output_compression` | `0` 至 `100` | 仅 jpeg/webp | | `response_format` | 空值或 `b64_json` | GPT Image 拒绝显式 `url`；Grok 省略时通常返回 URL | | `stream` | `true` / `false` | 流式图片还可配 `partial_images`=`0..3` | | `aspect_ratio` | 例如 `1:1`、`16:9`、`9:16` | Grok Imagine 扩展字段 | | `resolution` | 例如 `1k`、`2k`、`4k` | Grok Imagine 扩展字段 | ## 完整成功响应 ```json { "created": 1780000000, "data": [{"b64_json":"BASE64_IMAGE","revised_prompt":"..."}], "usage": {"input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036} } ``` Grok URL 模式可能返回 `data[].url`；客户端应同时兼容 `b64_json`、`url` 和 `mime_type`。 ## 图片批处理 API 批处理是异步任务 API，不等同于单次 `/generations`。规范路径如下： | 方法 | 路径 | 用途 | |---|---|---| | `POST` | `/v1/images/batches` | 提交批任务 | | `GET` | `/v1/images/batches` | 按状态、时间、游标查询任务 | | `GET` | `/v1/images/batches/models` | 查询批处理可用模型 | | `GET` | `/v1/images/batches/{id}` | 查询任务 | | `GET` | `/v1/images/batches/{id}/items` | 查询任务条目 | | `GET` | `/v1/images/batches/{id}/items/{custom_id}/content` | 下载单个结果 | | `GET` | `/v1/images/batches/{id}/download` | 下载 ZIP（含 manifest） | | `POST` | `/v1/images/batches/{id}/cancel` | 取消任务 | | `DELETE` | `/v1/images/batches/{id}` | 删除任务记录 | | `DELETE` | `/v1/images/batches/{id}/outputs` | 清理输出文件 | 提交体核心字段：`model`、`task_name`、`items[]`；每个 item 至少包含 `custom_id` 和 `prompt`，可选 `output_count`、`reference_images`。`output_count` 必须为正整数，条目数量、文件大小和参考图限制由当前分组配置决定。 ```bash curl https://api.clomio.ai/v1/images/batches \ -H "Authorization: Bearer 你的密钥" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: batch-demo-001" \ -d '{ "model":"gpt-image-2", "task_name":"catalog-covers", "items":[ {"custom_id":"cover-001","prompt":"蓝色极简产品封面","output_count":1}, {"custom_id":"cover-002","prompt":"橙色极简产品封面","output_count":1} ] }' ``` 批处理错误常见为 `API_KEY_REQUIRED`、`INVALID_ITEMS`、`BATCH_NOT_FOUND`、`ITEM_NOT_FOUND`、`INVALID_STATUS`、`IMAGE_INDEX_OUT_OF_RANGE` 和 `BATCH_CANCEL_NOT_ALLOWED`；错误体包含 `error.code`、`error.message`，下载接口成功时返回 `image/*` 或 `application/zip` 二进制。 --- # Videos（仅 Grok） Grok/xAI 文生视频与视频编辑。**Videos 只支持 Grok 分组**,不是 OpenAI/Codex 能力。视频生成通常较慢,多为**异步任务**:先提交,再轮询结果。 ```text POST https://api.clomio.ai/v1/videos POST https://api.clomio.ai/v1/videos/generations POST https://api.clomio.ai/v1/videos/edits POST https://api.clomio.ai/v1/videos/extensions GET https://api.clomio.ai/v1/videos GET https://api.clomio.ai/v1/videos/{request_id} ``` > **分组要求:** **仅 Grok 分组**支持视频,且该分组必须启用视频能力;其他分组返回 404 `Videos API is not supported for this platform`,Grok 分组未开启视频能力时返回 403 `Video generation is not enabled for this group`。见 [端点 × 分组](#/api-usage)。 > > **接口形态:** 视频生成通常是异步任务。推荐使用 `POST /v1/videos/generations`、`POST /v1/videos/edits`、`POST /v1/videos/extensions`，再用 `GET /v1/videos/{request_id}` 查询；根路径仅作为兼容入口，不建议新客户端使用。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的密钥` | | `Content-Type` | POST 时是 | `application/json`(编辑/带图时用 `multipart/form-data`)；GET 轮询通常不需要请求体 | --- ## 网关处理边界 - 路由层仅 Grok 分组可进入；OpenAI/Claude/其他分组返回 404 `Videos API is not supported for this platform`。 - 服务支持 `model`、`prompt`、`duration`、`aspect_ratio`、`resolution` 以及兼容字段 `seconds`、`size`。`image`、`reference_images`、`input_reference`、`user` 等字段会按原请求发送；字段必填和取值范围以所选 Grok 视频模型说明为准。 - 成功的创建、编辑和延展请求会按时长、分辨率和变体数量计费；GET 查询只返回任务状态或内容，不重复计费。下载子路径如果返回二进制内容，客户端应按响应 `Content-Type` 保存。 --- ## 文生视频:generations ### 请求参数 | 参数 | 类型 | 必填 | 说明 | |------|------|:----:|------| | `model` | string | 通常必填 | 视频模型名,以当前 Grok 分组可用模型为准 | | `prompt` | string | 通常必填 | 画面描述;具体必填和长度限制以视频模型为准 | | `duration` | number | 否 | xAI 官方时长字段,通常 1-15 秒;老客户端也可能传 `seconds` | | `aspect_ratio` | string | 否 | xAI 官方画幅字段,如 `16:9`、`9:16`、`1:1`;老客户端也可能传 `size` | | `resolution` | string | 否 | xAI 官方分辨率字段,如 `480p`、`720p`、`1080p`;老客户端也可能传 `size`/`1280x720` | | `n_variants` | number | 否 | 生成变体数量;用于计费/统计时会计入视频数量 | | `image` / `reference_images` / `input_reference` | object/array | 否 | 图生视频或参考图视频输入,具体以 Grok/xAI 模型为准 | | `user` | string | 否 | 透传给上游的最终用户标识 | Grok 视频响应通常使用 `request_id`、`status`、`video` 或 `data` 等字段。服务保留这些字段，客户端应按实际响应读取；同时兼容旧客户端的 `seconds`、`size`、`n_variants`/`n` 写法。 ### 响应 提交后通常返回一个**异步任务对象**。xAI 官方常见返回 `request_id`;轮询状态以 `pending` / `done` / `expired` / `failed` 为准: ```json { "request_id": "video_xxx", "object": "video", "status": "pending", "model": "你的 Grok 视频模型名" } ``` --- ## 查询结果:GET /v1/videos 或 GET /v1/videos/{request_id} 这是 Grok 视频任务查询入口；返回任务列表、详情或其它结构以所选模型的响应格式为准。 ```bash curl https://api.clomio.ai/v1/videos/video_xxx \ -H "Authorization: Bearer 你的 Grok 分组密钥" ``` 完成后返回里可能带视频地址、下载子路径或可直接下载内容,字段以所选模型为准。不要假设 `data[0].url` 永远存在；xAI 官方示例常见完成响应是 `status:"done"` 且视频地址在 `video.url`。先打印响应,再按 `video.url`、`data[].url`、顶层 `url`、`download_url`、`content` 下载子路径或上游文档说明处理。上游返回的视频 URL 可能是临时 URL,生产环境建议成功后立刻下载/转存。 ```json { "request_id": "video_xxx", "status": "done", "video": { "url": "https://.../output.mp4" }, "data": [{ "url": "https://.../output.mp4" }], "url": "https://.../output.mp4" } ``` --- ## 最小可验证 curl “提交生成 + 轮询”示例可验证 Grok-only 路由、视频能力开关、POST 透传和 GET `/v1/videos/{request_id}` 轮询透传；用 OpenAI/Claude 分组 Key 调同一路径可验证 404 `Videos API is not supported for this platform`。 ## 示例:提交生成 + 轮询 ```bash # 1) 提交 curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "你的 Grok 视频模型名", "prompt": "海边日落,海鸥飞过,电影质感", "duration": 8, "aspect_ratio": "16:9", "resolution": "720p" }' # 2) 用返回的 request_id 轮询,直到 status 为 done curl https://api.clomio.ai/v1/videos/video_xxx \ -H "Authorization: Bearer 你的 Grok 分组密钥" ``` ```python import time, requests create_url = "https://api.clomio.ai/v1/videos/generations" headers = {"Authorization": "Bearer 你的 Grok 分组密钥"} job = requests.post(create_url, headers=headers, json={ "model": "你的 Grok 视频模型名", "prompt": "海边日落,海鸥飞过,电影质感", "duration": 8, "aspect_ratio": "16:9", "resolution": "720p", }).json() vid = job.get("request_id") while True: r = requests.get(f"https://api.clomio.ai/v1/videos/{vid}", headers=headers).json() if r.get("status") in ("done", "failed", "expired"): print(r) break time.sleep(5) ``` ### 完整场景:生成 → 轮询 → 下载到本地 ```python import time, requests CREATE_URL = "https://api.clomio.ai/v1/videos/generations" H = {"Authorization": "Bearer 你的 Grok 分组密钥"} job = requests.post(CREATE_URL, headers={**H, "Content-Type": "application/json"}, json={ "model": "你的 Grok 视频模型名", "prompt": "雨后的城市街道,霓虹倒影,赛博朋克风格", "duration": 6, "aspect_ratio": "16:9", "resolution": "720p", }).json() vid = job.get("request_id") print("任务已提交:", vid) # 轮询直到完成 while True: r = requests.get(f"https://api.clomio.ai/v1/videos/{vid}", headers=H).json() st = r.get("status") print("状态:", st) if st == "done": url = ( (r.get("video") or {}).get("url") or (r.get("data") or [{}])[0].get("url") or r.get("url") or r.get("download_url") ) if not url: print("已完成,但响应未提供直接 URL;请按上游字段或 content 子路径下载:", r) break open("output.mp4", "wb").write(requests.get(url).content) print("已下载 output.mp4") break if st in ("failed", "expired"): print("生成失败:", r); break time.sleep(8) # 视频较慢,间隔大一些,避免触发限速 ``` --- ## 视频编辑 / 延展 - `POST /v1/videos/edits` —— 基于输入视频编辑;官方形态通常是 JSON 里提供 `video:{url|file_id|data URL}` 与 `prompt` - `POST /v1/videos/extensions` —— 延长已有视频;官方形态通常也是 JSON 引用已有视频 字段与具体能力随模型而定,以控制台「视频模型」说明和 Grok/xAI 接口为准。编辑/延展请求可以使用模型要求的 JSON 或 multipart 格式；如果接口要求 JSON `video` 字段,不要误以为必须 multipart 上传。 ### 高级视频场景边界 - **image-to-video**:请求通常包含 `prompt` + `image`。如果不显式传 `aspect_ratio`,模型可能按输入图片比例生成;显式传入时可能出现拉伸或裁切,以模型为准。 - **reference-to-video**:请求通常包含 `prompt` + `reference_images`。公开 xAI 形态常限制参考图数量和最长时长;新接入按当前上游文档与控制台说明填写。 - **editing / extension**:编辑和延展不是普通文生视频参数的超集;有些模型不接受自定义 `duration`、`aspect_ratio`、`resolution`。不要把 generations 的字段原样复制到 edits/extensions。 ## 排障 | 现象 | 常见原因 | 处理 | |------|----------|------| | 404 `Videos API is not supported for this platform` | API Key 不在 Grok 分组 | 换 Grok 分组 Key | | 403 `Video generation is not enabled for this group` | 当前 Grok 分组未开放视频能力 | 更换已开放 Grok Videos 的分组；如应已开放，带 `x-request-id` 提交工单 | | 503 `No available compatible accounts for video generation` | 暂时没有可用的视频生成服务能力、上游限流或模型能力不匹配 | 降低并发稍后重试；确认模型和分组支持视频；持续失败带 `x-request-id` 提交工单 | | 503 `No available accounts after failover` | 自动切换后仍没有可用服务能力 | 稍后重试或换分组；持续失败带 `x-request-id` 和错误体提交工单 | | 429 Too Many Requests | 轮询太频繁、创建端触发 xAI per-model RPS/TPM 或服务侧限速 | 轮询间隔 5~10 秒以上；创建端按 `Retry-After` / rate-limit headers/backoff 处理；持续异常带 `x-request-id` 提交工单 | | 502/上游错误 `get access token for video: ...` / `missing token for video generation` | Grok 视频服务或凭证暂时异常 | 稍后重试；持续出现时带 `x-request-id`、时间和错误体提交工单 | | 上游 4xx/5xx 原样返回 | 字段缺失、模型不支持或服务繁忙 | 查看错误 body，并按视频模型要求调整请求 | --- > 视频能力目前仅 Grok 分组开放;图像见 [Images](#/api-images)。轮询间隔建议 5~10 秒,避免触发[限速](#/troubleshooting)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `model` | 当前 Grok 分组中的 `grok-imagine-video*` | 必填 | | `prompt` | 非空 string | 文生视频描述 | | `duration` | 通常 `1..15` 秒 | `seconds` 是旧兼容字段 | | `aspect_ratio` | `1:1`、`16:9`、`9:16` 等 | 以模型支持列表为准 | | `resolution` | `480p`、`720p`、`1080p`、`4k` | 以模型支持列表为准 | | `n_variants` / `n` | 正整数 | 变体数量，受上游限制 | | `image` | object，通常包含 `url` | 图生视频输入 | | `reference_images` | array，通常最多 7 项 | 参考图视频；同时使用 image 时可能冲突 | ## 状态与错误响应 ```json {"request_id":"video_xxx","status":"pending","model":"grok-imagine-video"} ``` 轮询终态通常是 `done`、`failed` 或 `expired`；完成响应可能在 `video.url`、顶层 `url` 或 `data[].url` 提供下载地址。 | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `model/prompt is required`、duration/resolution 不合法 | 按模型参数范围修正 | | 403 | `Video generation is not enabled for this group` | 开启 Grok 视频能力或换分组 | | 404 | `Videos API is not supported for this platform` | 使用 Grok 分组 Key | | 409/422 | 任务状态或输入视频不符合要求 | 检查 request_id、video 引用和终态 | | 429 | 创建/轮询过频 | 创建按 Retry-After 退避，轮询间隔 5~10 秒 | | 502/503 | 视频服务暂时不可用 | 保存 `x-request-id` 和原始错误体 | --- # Voice（Grok） Clomio 将 xAI Voice 能力以 Grok 分组 API 暴露出来，包含文字转语音、语音转文字和实时双向语音会话。 | 能力 | 方法 | 路径 | 返回 | 适用分组 | |---|---|---|---|---| | Text to Speech | `POST` | `/v1/tts` | 音频字节（默认 `audio/mpeg`） | Grok | | Speech to Text | `POST` | `/v1/stt` | JSON 转写结果 | Grok | | Realtime Voice | `GET` + WebSocket Upgrade | `/v1/realtime` | Realtime 事件流 | Grok | | Custom Voices | `POST` | `/v1/custom-voices` | 自定义声音对象 | Grok | > 文档以 `/v1/...` 作为规范写法；网关也提供省略 `/v1` 的 Voice 兼容入口。请确保 Base URL 与客户端的 endpoint 拼接方式一致，并确认响应是音频、JSON 或 WebSocket，而不是站点 HTML。 ## 通用鉴权 ```text Authorization: Bearer 你的 Grok 分组密钥 ``` 这些端点仅使用 Key 所在的 Grok 分组。用 OpenAI、Claude、Gemini 或 Antigravity 分组会返回 `404 Voice API is not supported for this platform`。 ## TTS：文字转语音 ```text POST https://api.clomio.ai/v1/tts Content-Type: application/json ``` ### 请求体 | 字段 | 类型 | 必填 | 说明 | |---|---|:---:|---| | `text` | string | 是 | 要合成的文字 | | `voice_id` | string | 是 | 内置或自定义声音 ID，例如 `eve`、`ara` | | `language` | string | 否 | 语言提示，例如 `en`、`zh` | | `output_format` | object | 否 | 按 xAI Voice 文档指定音频编码/采样率时使用 | ### cURL ```bash curl https://api.clomio.ai/v1/tts \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello from Grok", "voice_id": "eve", "language": "en" }' \ --output hello.mp3 ``` 成功响应是音频二进制，不是 JSON。网关会保留上游 `Content-Type`，通常为 `audio/mpeg`。不要对 TTS 响应调用 `.json()`；应直接写入文件或音频播放器。 ## STT：语音转文字 ```text POST https://api.clomio.ai/v1/stt Content-Type: multipart/form-data ``` ### 请求字段 | 字段 | 类型 | 必填 | 说明 | |---|---|:---:|---| | `file` | file | 是 | 音频文件，例如 WAV、MP3 | | `model` | string | 否 | Voice 模型提示；可使用 `grok-voice-latest` | ### cURL ```bash curl https://api.clomio.ai/v1/stt \ -H "Authorization: Bearer 你的 Grok 分组密钥" \ -F "file=@recording.mp3" \ -F "model=grok-voice-latest" ``` 成功响应示例： ```json { "text": "Hello from Grok", "language": "en", "duration": 1.72 } ``` 静音文件返回空 `text` 是正常现象。STT 是批处理 HTTP 接口；Realtime 会话中的音频不应再重复按 STT 接口计费。 ## Realtime：实时双向语音 Realtime 不是普通 HTTP POST，而是 WebSocket： ```text wss://api.clomio.ai/v1/realtime?model=grok-voice-latest ``` 客户端必须发送标准 WebSocket Upgrade，并带 `Authorization`。连接成功后首先会收到 `session.created`，随后可能收到 `conversation.created`、`ping` 等事件。 ### 最小 JavaScript 示例 ```javascript import WebSocket from "ws"; const ws = new WebSocket( "wss://api.clomio.ai/v1/realtime?model=grok-voice-latest", { headers: { Authorization: `Bearer ${process.env.GROK_API_KEY}` } }, ); ws.on("message", (raw) => { const event = JSON.parse(raw.toString()); if (event.type === "response.output_audio.delta") { const audio = Buffer.from(event.delta, "base64"); // 把 audio 写入播放器或音频缓冲区 } if (event.type === "response.output_audio_transcript.done") { console.log("assistant:", event.transcript); } }); ws.on("open", () => { ws.send(JSON.stringify({ type: "response.create", response: { modalities: ["audio"], instructions: "Say hello" }, })); }); ``` ### 常见事件 | 事件 | 方向 | 用途 | |---|---|---| | `session.created` | 服务端 → 客户端 | 会话建立成功，包含模型、默认声音和能力 | | `conversation.created` | 服务端 → 客户端 | 会话容器创建完成 | | `response.create` | 客户端 → 服务端 | 请求模型生成文字/音频回复 | | `response.output_audio.delta` | 服务端 → 客户端 | Base64 音频增量，需按顺序播放/拼接 | | `response.output_audio_transcript.done` | 服务端 → 客户端 | 音频回复的完整文字转写 | | `response.done` | 服务端 → 客户端 | 本轮响应结束 | | `error` | 双向 | 协议、参数或上游错误 | Realtime 音频回复是增量事件，不要等待一个完整 MP3 文件再播放。客户端应缓存 `delta`，并依据 xAI Voice 文档的音频格式解码。 ## Custom Voices：自定义声音 ```text POST https://api.clomio.ai/v1/custom-voices Content-Type: multipart/form-data ``` 自定义声音通常需要参考音频和声音名称/语言字段。字段形态由 xAI Voice 当前版本定义，网关会保留 multipart 内容并透传；请按 xAI 文档上传参考音频，成功后保存返回的 `voice_id`，再将它用于 `/v1/tts` 或 Realtime 会话。 ## 错误与排查 | 状态 | 常见原因 | 处理 | |---:|---|---| | `400` | JSON、multipart 或 WebSocket Upgrade 格式错误 | 检查 `Content-Type`、`file` 字段和 Upgrade 头 | | `401` | Key 无效或已过期 | 使用 Grok 分组 Key，并确认使用 `Authorization` 头 | | `404` | Key 不属于 Grok 分组，或路径缺少 `/v1` | 检查分组和最终 URL | | `503` `No available Grok accounts` | 当前暂时没有可用的 Grok Voice 服务资源 | 稍后重试；持续出现时提交 `x-request-id` | | `502` / 上游 4xx/5xx | xAI Voice 参数、凭证、代理或上游状态异常 | 保留完整错误体和 `x-request-id` 排查 | 每次请求都应记录响应头里的 `x-request-id`。不要在工单或日志中提交完整 API Key。 ## 参数与格式边界 | 接口 | 必填 | 可选值/范围 | 成功内容 | |---|---|---|---| | `/v1/tts` | `text`、`voice_id` | `language` 使用 BCP-47/常见语言代码；`voice_id` 为 `eve`、`ara` 或已创建的自定义 ID | 音频二进制 | | `/v1/stt` | multipart `file` | `model` 可填 `grok-voice-latest`；文件格式由 xAI Voice 支持列表决定 | `text`、`language`、`duration` | | `/v1/realtime` | 有效 WS Upgrade | `model` 默认 `grok-voice-latest`；事件字段按 Realtime 协议 | 事件流和 Base64 音频增量 | | `/v1/custom-voices` | 参考音频/声音信息 | 参考音频最长时长、编码和名称限制以 xAI Voice 当前版本为准 | `voice_id` 等 JSON | 不要把 `/v1/tts` 的音频响应当 JSON；不要把 Realtime 的 `delta` 当完整音频文件；不要把 Realtime 的音频时长再次按 `/v1/stt` 计费。 --- # Web Search Grok 联网搜索有两条入口：**推荐主路径**是 `/v1/responses` + `tools:[{"type":"web_search"}]`，可以让模型边搜索边推理并返回带引用答案；本页的独立 `/v1/web_search` 是 Clomio 的**简化兼容入口**，只返回统一来源列表，且 **仅 Grok 分组**支持。 ```text POST https://api.clomio.ai/v1/web_search ``` > 用其他分组调用会返回 404 `Web Search API is not supported for this platform`。Grok 分组的创建见 [创建 API 密钥](#/api-key)。新接入统一使用 `/v1/web_search`。如果你的客户端支持 Responses tools，优先使用 `/v1/responses` + `web_search`；独立 `/v1/web_search` 适合“只要 sources 列表”的程序化场景。 --- ## 它和 Grok Responses web_search tool 的关系 | 用法 | 请求形态 | 返回形态 | 适合场景 | |------|----------|----------|----------| | 本页 `/v1/web_search` | `{ "query": "...", "max_results": 5 }` | 统一 JSON：`query/results/provider/max_results` | 程序只想拿搜索结果列表，再自行总结/入库；不是官方 tool 参数透传 | | Grok `/v1/responses` + `tools:[{"type":"web_search"}]` | OpenAI Responses 兼容请求 | Grok 模型回答 + citations/tool usage | 需要模型边搜索边推理并给最终答案 | | xAI 官方 Web Search tool | `web_search` server-side tool | xAI API 自动执行工具并返回引用 | 与官方 SDK/Responses API 对齐 | | xAI 官方 X Search tool | `x_search` server-side tool | 搜索 X/Twitter 内容 | 查 X 帖子、用户、thread，而不是普通网页 | `/v1/web_search` 会返回统一的 `query/results/provider/max_results` 结构；如果它返回 `scheduling_error` 或 `web_search_error`，先用同一个 Grok Key 测 `/v1/responses` + `web_search` tool，以区分主搜索能力和简化入口问题。 xAI 官方说明 Web Search 是 Grok 的实时网页搜索/浏览工具，OpenAI Responses API 兼容工具名为 `web_search`；X Search 的工具名是 `x_search`，面向 X 平台内容。参考：、、。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是 | `Bearer 你的Grok密钥` | | `Content-Type` | 是 | `application/json` | --- ## 请求参数 | 参数 | 类型 | 必填 | 网关处理 / 说明 | |------|------|:----:|------| | `query` | string | 是 | 搜索关键词 / 问题；请传 trim 后非空查询。不支持把官方 tool 的 filters 参数放在本端点顶层 | | `max_results` | integer | 否 | `<=0` 默认 5，最大 20；用于限制统一结果列表 | ### 不支持直接透传的官方 tool 参数 xAI 官方 `web_search` tool 支持 `filters.allowed_domains`、`filters.excluded_domains`、`enable_image_understanding`、`enable_image_search` 等参数；这些属于 **Responses tool** 参数。本页 `/v1/web_search` 的简化接口当前只接收 `query` 和 `max_results`，不会把 allowed/excluded domains 或图片搜索开关透传。X/Twitter 搜索必须走 `/v1/responses` + `tools:[{"type":"x_search"}]`,不是 `/v1/web_search`。需要这些高级能力时，请直接调用 [Responses](#/api-responses)： ```json { "model": "grok-4.3", "input": [{ "role": "user", "content": "What is xAI?" }], "tools": [{ "type": "web_search", "filters": { "allowed_domains": ["x.ai"] }, "enable_image_search": true }] } ``` 反例：不要把 `allowed_domains`、`excluded_domains`、`enable_image_search`、`enable_image_understanding` 直接放到 `/v1/web_search` 顶层；当前独立端点只读取 `query` 与 `max_results`。这些字段必须放在 `/v1/responses` 请求的 `tools[].` 里才可能由 Grok/xAI 上游识别。 --- ## 响应 ```json { "query": "What is xAI?", "results": [ { "url": "https://x.ai/", "title": "xAI", "snippet": "" } ], "provider": "grok-native", "max_results": 5 } ``` | 字段 | 类型 | 说明 | |------|------|------| | `query` | string | 原始查询 | | `results` | array | 统一来源列表 | | `results[].url` | string | 来源 URL | | `results[].title` | string | 来源标题；上游缺失时可能为空 | | `results[].snippet` | string | 摘要；Grok native sources 常只有 URL/title，可能为空 | | `provider` | string | `grok-native` 或 Grok 服务标识 | | `max_results` | integer | 本次请求的回显参数;不代表上游实际搜索条数 | > 该端点只返回来源列表，不返回 Grok 的自然语言总结；要直接得到带引用的答案，请用 `/v1/responses` + `web_search` tool。成功调用会按一次 Grok web search 记录用量,不是按返回结果条数计费。 --- ## 最小可验证 curl 优先先测 Responses tool；这能验证 Grok Key、模型、Responses 路由和上游 web_search 工具是否可用。独立 `/v1/web_search` 再用于验证 sources-list 兼容入口。 ## 推荐: Responses + web_search tool ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的Grok密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-4.3", "input": "检索 xAI API 文档里 Web Search 的参数并总结", "tools": [{"type":"web_search"}], "stream": false }' ``` 如果这里能返回答案和 citations/annotations，而 `/v1/web_search` 报错，说明 Grok 搜索主链路可用，问题集中在独立 sources-list 入口或当前请求参数。 ## 示例: 独立 sources-list 搜索 ```bash curl https://api.clomio.ai/v1/web_search \ -H "Authorization: Bearer 你的Grok密钥" \ -H "Content-Type: application/json" \ -d '{ "query": "2026 年最新的 AI 编程工具", "max_results": 5 }' ``` ```python import requests r = requests.post( "https://api.clomio.ai/v1/web_search", headers={"Authorization": "Bearer 你的Grok密钥", "Content-Type": "application/json"}, json={"query": "2026 年最新的 AI 编程工具", "max_results": 5}, ) r.raise_for_status() for item in r.json().get("results", []): print(item.get("title", ""), "-", item["url"]) ``` ```javascript const r = await fetch("https://api.clomio.ai/v1/web_search", { method: "POST", headers: { "Authorization": "Bearer 你的Grok密钥", "Content-Type": "application/json", }, body: JSON.stringify({ query: "2026 年最新的 AI 编程工具", max_results: 5 }), }); if (!r.ok) throw new Error(await r.text()); const data = await r.json(); for (const item of data.results ?? []) console.log(item.title ?? "", "-", item.url); ``` --- ## 示例: 直接让 Grok 搜索并总结 如果你不需要中间 `results` 列表，而是要最终答案和引用，用 Responses tool： ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的Grok密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-4.3", "input": [{"role":"user","content":"What is xAI? Please cite sources."}], "tools": [{"type":"web_search"}], "stream": false }' ``` xAI 官方工具会在服务端自动执行；流式模式下可以观察工具调用，最终响应通常带 citations/annotations。工具调用按 xAI 规则计费。 --- ## 实战场景: 搜索 + 自己总结/入库 ```python import requests KEY = "你的Grok密钥" WEB_SEARCH_URL = "https://api.clomio.ai/v1/web_search" H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"} q = "Claude Code 和 Codex 有什么区别" hits = requests.post( WEB_SEARCH_URL, headers=H, json={"query": q, "max_results": 5}, ).json()["results"] context = "\n".join(f"- {h.get('title','')}: {h.get('snippet','')} ({h['url']})" for h in hits) ans = requests.post(f"{BASE}/responses", headers=H, json={ "model": "grok-4.3", "input": f"根据以下搜索结果回答:{q}\n\n{context}\n\n请给出结论并标注来源链接。", }).json() print(ans.get("output_text", ans)) ``` --- ## 排障 | 现象 | 常见原因 | 处理 | |------|----------|------| | 404 `Web Search API is not supported for this platform` | API Key 不在 Grok 分组 | 换 Grok 分组 Key | | 400 JSON binding 错误 / `query` 缺失 | 请求体不是合法 JSON，或未传 `query`；错误文本来自 Gin binding（如 `Key: ... Error:Field validation for ... failed on the 'required' tag`） | 设置 `Content-Type: application/json`，传入 `query` | | 400 `web search is only supported for grok groups` | 当前 Key 分组不是 Grok | 检查 Key 绑定分组和平台 | | 400 `group required` | API Key 没有关联分组 | 在控制台给 Key 绑定 Grok 分组 | | 503 `scheduling_error` | 独立端点暂时没有可用服务能力，或搜索服务繁忙 | 先用同 Key 测 `/v1/responses` + `web_search`；若主链路可用但独立端点持续失败，带 `x-request-id`、时间和错误体提交工单 | | 502 `web_search_error` | 搜索服务暂时失败 | 同 Key 先测 `/v1/responses` + `web_search`；若可用，带 `x-request-id`、时间和错误体反馈 | | `results` 为空但请求成功 | Grok 没有在响应中暴露 sources/annotations，或该问题无需搜索 | 改用 `/v1/responses` 让模型直接回答并查看 citations/annotations | | 想限制域名或开启图片搜索 | `/v1/web_search` 不透传这些参数 | 直接用 `/v1/responses` + `tools[].filters` / `enable_image_search` | --- > Grok 分组的对话走 [Responses](#/api-responses)；图像见 [Images](#/api-images)。Videos 仍是 Grok-only 相邻能力，见 [Videos](#/api-videos)。 ## 字段约束速查 | 字段 | 可选值/范围 | 说明 | |---|---|---| | `query` | 非空 string | 必填；建议限制在明确问题 | | `max_results` | `1..20` | 不传默认 `5`，超过 20 会归一化为 20 | 独立 `/v1/web_search` 只返回 `results` 列表；域名过滤、X Search、图片搜索和工具参数请改用 `/v1/responses` 的官方 tool 形态。 ## 完整响应与错误 ```json { "query":"最新的 Go 版本", "provider":"grok-native", "max_results":5, "results":[{"url":"https://go.dev/","title":"The Go Programming Language","snippet":"..."}] } ``` | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `query` 缺失、JSON binding 错误 | 使用 JSON body 和非空 query | | 401 | `API key required` / Key 无效 | 检查 Grok Key | | 404 | `Web Search API is not supported for this platform` | 换 Grok 分组 | | 429 | 请求频率过高 | 降低调用频率 | | 502 | `web_search_error` | 改测 Responses + web_search 区分上游与兼容层 | | 503 | `scheduling_error` | 暂无可用 Grok 搜索账号，稍后重试 | --- # Models 列出当前密钥(分组)可用的模型。 ```text GET https://api.clomio.ai/v1/models ``` > 当前网关只暴露模型列表路由,**没有** `GET /v1/models/{id}`。想确认某个模型是否可用,请看列表返回值或直接发一次最小请求。 > > Gemini 原生模型列表不是本页 `/v1/models`:Gemini 分组使用 `GET /v1beta/models`，单模型查询使用 `GET /v1beta/models/{model}`。不要把 Gemini 的单模型查询写成 `GET /v1/models/{id}`。 --- ## 请求头 | 请求头 | 必填 | 值 | |--------|:----:|-----| | `Authorization` | 是* | `Bearer 你的密钥` | | `x-api-key` | 是* | 你的密钥 | | `x-goog-api-key` | 是* | 你的密钥，兼容部分 Google 风格客户端 | > \* 三种 Key 头任选其一即可。不要把 Key 放进 `?key=` 或 `?api_key=` query；普通 `/v1` 网关会返回 400 `api_key_in_query_deprecated`。`GET /v1/models` 不需要 `Content-Type`。 --- ## 响应 | 字段 | 类型 | 说明 | |------|------|------| | `object` | string | `list` | | `data` | array | 模型数组;每项唯一稳定字段是 `id`,其他字段随平台/来源变化 | ```json { "object": "list", "data": [ { "id": "gpt-5.4", "object": "model", "owned_by": "clomio" }, { "id": "claude-sonnet-4-6", "object": "model", "owned_by": "clomio" } ] } ``` > 返回的具体模型取决于你密钥所在的[分组](#/api-key)。同一个模型名还可能经过控制台的模型映射转发到上游实际模型,使用记录里会记录实际用量。 ### data[] 字段不是固定 OpenAI 官方形态 `/v1/models` 的顶层稳定为 `object:"list"` 和 `data:[...]`;`data[]` 里只应把 `id` 当作稳定字段。OpenAI 默认/自定义列表可能有 `object`、`created`、`owned_by`、`type`、`display_name`;映射聚合列表、Claude/Kiro/Gemini/Grok 经 `/v1/models` 暴露时,可能只有 `id`、`type`、`display_name`、`created_at` 或省略 `created/owned_by`。兼容客户端不要强校验每项都必须是 OpenAI 官方 `model` object。 模型列表有短缓存；控制台模型列表或分组能力刚变化后，短时间内可能仍看到旧结果。 ## 模型名从哪里来 `GET /v1/models` 展示的是**当前密钥分组可请求的模型名**，通常是客户端可填写的请求模型名/别名，不是某个上游厂商的完整官方清单。它会综合当前分组开放模型、可用别名、平台默认模型列表以及已开放的兼容能力。 因此请区分: | 名称 | 出现位置 | 含义 | |------|----------|------| | 请求模型 | 请求体 `model`、`/v1/models` 列表 | 客户端允许填写的名字,可能是别名 | | 路由/映射模型 | 控制台模型映射、分组默认路由 | 网关用于改写上游请求的中间结果 | | 上游真实模型 | 控制台用量明细里的上游模型 | 实际发给上游供应商的模型,可能不同于请求模型 | 排查“我明明请求了 A,为什么像 B”时,优先看控制台用量明细里的**请求模型**和**上游模型**;不要只凭 `/v1/models` 判断上游真实模型。 --- ## 示例:列出所有模型 ```bash curl https://api.clomio.ai/v1/models \ -H "Authorization: Bearer 你的密钥" ``` ```python from openai import OpenAI client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1") for m in client.models.list().data: print(m.id) ``` ```javascript import OpenAI from "openai"; const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" }); const models = await client.models.list(); for (const m of models.data) console.log(m.id); ``` --- ## 示例:在 Shell 中判断模型是否存在 ```bash curl -s https://api.clomio.ai/v1/models -H "Authorization: Bearer 你的密钥" | jq -r '.data[].id' | grep -Fx 'gpt-5.4' ``` 有输出说明当前密钥分组里能看到该模型;没有输出则换模型名或换分组。 --- ## 常见模型错误怎么区分 | 关键词 | 含义 | 处理 | |--------|------|------| | `The current group does not support the requested model "xxx". Available models: ...` | 当前密钥分组明确不支持请求模型 | 按 `Available models` 换模型,或换到支持该模型的分组 | | `model_not_found` / `Model "xxx" is not supported by any configured account in this group` | 当前分组不支持该模型 | 核对模型名和分组模型清单 | | `No available accounts supporting model: xxx` | 当前暂时无法提供该模型 | 先看 `/v1/models`;持续出现带 request_id 工单 | | `No available accounts` | 当前服务暂时没有可用资源 | 稍后重试、换线路或降低并发 | | `This group does not allow /v1/messages dispatch` | OpenAI 分组未开启 Claude Messages 形状转 OpenAI 的 dispatch | 改走 `/v1/responses` 或 `/v1/chat/completions`,或换到允许 dispatch 的 OpenAI 分组 | > `/v1/models` 只返回当前密钥分组可见的模型列表;没有 `GET /v1/models/{id}`。模型名是否最终映射到另一个上游真实模型,以控制台用量记录为准。 --- > 拿到模型名后,填进对话/图像等请求的 `model` 字段。怎么挑模型见 [模型选择指南](#/models)。 ## 字段与查询约束 `GET /v1/models` 不接受请求体；Key 通过 `Authorization`、`x-api-key` 或 `x-goog-api-key` 三选一传入。`client_version` 为 Codex 客户端专用查询参数，存在时可能返回 Codex manifest 形态而不是普通 OpenAI list。 | 查询 | 可选值/范围 | 说明 | |---|---|---| | `client_version` | 客户端版本字符串 | 仅 Codex 模型选择器使用；普通 SDK 不要传 | ## 完整错误响应 ```json {"error":{"type":"authentication_error","message":"Invalid API key"}} ``` | HTTP | 典型错误 | 处理 | |---:|---|---| | 400 | `api_key_in_query_deprecated` | 把 Key 从 query 移到 header | | 401 | `API key required` / `Invalid API key` | 检查 Key、状态和用户 | | 403 | 未分组、订阅或 IP 限制 | 在控制台绑定正确分组 | | 429 | 请求频率过高 | 缓存模型列表并退避 | | 503 | 服务暂时不可用 | 稍后重试并带 request_id | --- ## Agent 接入 # Antigravity 接入 Antigravity 专用入口用于 Antigravity 客户端或兼容工具。它和普通 Claude/OpenAI/Gemini 分组分开调度,路由会强制使用 Antigravity 账户,不会和常规 Claude、OpenAI、Grok 账户混在一起。 | 项 | 值 | |---|---| | Base URL | `https://api.clomio.ai`(线路可换 `https://sub.qazwc.com` / `https://crs.qazwc.com`) | | 路径前缀 | `/antigravity/...` | | Key 分组 | Antigravity 分组 | | 两种形态 | Anthropic Messages 形态 `/antigravity/v1/...`;Gemini 原生形态 `/antigravity/v1beta/...` | | 外部参考 | [Antigravity Agent](https://ai.google.dev/gemini-api/docs/antigravity-agent)、[Google Antigravity docs](https://antigravity.google/docs/home)、[Antigravity models](https://antigravity.google/docs/models) | > 不要把 Base URL 写成 `https://api.clomio.ai/v1`。Antigravity 路径本身已经带 `/antigravity/v1...` 或 `/antigravity/v1beta...`。 --- ## 端点 | 方法 | 路径 | 形态 | 用途 | |---|---|---|---| | `GET` | `/antigravity/models` | 专用列表 | Antigravity 模型列表别名 | | `POST` | `/antigravity/v1/messages` | Anthropic Messages | 对话/Agent 消息 | | `POST` | `/antigravity/v1/messages/count_tokens` | Anthropic Messages | token 计数 | | `GET` | `/antigravity/v1/models` | Anthropic 风格 | 模型列表 | | `GET` | `/antigravity/v1/usage` | 专用 | 当前 Key 用量/额度 | | `GET` | `/antigravity/v1beta/models` | Gemini 原生 | Gemini 风格模型列表 | | `GET` | `/antigravity/v1beta/models/{model}` | Gemini 原生 | 单模型元数据 | | `POST` | `/antigravity/v1beta/models/{model}:generateContent` | Gemini 原生 | 非流式生成 | | `POST` | `/antigravity/v1beta/models/{model}:streamGenerateContent?alt=sse` | Gemini 原生 | SSE 流式生成 | --- ## Claude / Anthropic Messages 形态 适合按 Anthropic Messages 兼容协议工作的客户端。Base URL 仍是根地址,请求完整路径里带 `/antigravity/v1/messages`: ```bash curl https://api.clomio.ai/antigravity/v1/messages \ -H "Authorization: Bearer 你的Antigravity分组密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 512, "messages": [ { "role": "user", "content": "你好,请用一句话介绍 Antigravity 入口" } ] }' ``` 计数: ```bash curl https://api.clomio.ai/antigravity/v1/messages/count_tokens \ -H "Authorization: Bearer 你的Antigravity分组密钥" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "messages": [{ "role": "user", "content": "ping" }] }' ``` --- ## Gemini 原生形态 适合 Antigravity 侧以 Gemini `/v1beta/models...` 形状调用的工具。鉴权可用 `Authorization: Bearer` 或 `x-goog-api-key`: ```bash curl https://api.clomio.ai/antigravity/v1beta/models/gemini-2.5-pro:generateContent \ -H "Authorization: Bearer 你的Antigravity分组密钥" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [{ "text": "ping" }] } ] }' ``` 流式: ```bash curl 'https://api.clomio.ai/antigravity/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse' \ -H "x-goog-api-key: 你的Antigravity分组密钥" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "用一句话回答" }] }] }' ``` --- ## 和普通 Gemini / Claude / OpenAI 的区别 | 场景 | Base URL | 典型路径 | 分组 | |---|---|---|---| | Claude Code / Anthropic SDK | `https://api.clomio.ai` | `/v1/messages` | Claude/Anthropic 分组 | | Gemini 原生兼容 | `https://api.clomio.ai` | `/v1beta/models/{model}:generateContent` | Gemini 分组 | | Antigravity 专用 | `https://api.clomio.ai` | `/antigravity/v1/messages` 或 `/antigravity/v1beta/models...` | Antigravity 分组 | | OpenAI/Codex/Grok | `https://api.clomio.ai/v1` | `/v1/responses`、`/v1/chat/completions`、`/v1/images/*` | OpenAI 或 Grok 分组 | Antigravity 专用路径会强制 Antigravity 平台。即使请求体模型名看起来像 Claude 或 Gemini,也不会走普通 Claude/Gemini 分组。 Antigravity 目前没有 direct `/antigravity/v1/responses`、`/antigravity/v1/chat/completions`、`/antigravity/v1/embeddings`、`/antigravity/v1/images/*`、`/antigravity/v1/videos/*` 或 `/antigravity/v1/web_search`。如果工具只能发 OpenAI-compatible Responses/Chat/Images,不要套 Antigravity 前缀,请改用普通 `/v1/...` 并绑定对应 OpenAI/Grok 分组 Key;如果是 Videos 或 Web Search,只能绑定 Grok 分组 Key。 --- ## 常见错误 | 现象 / 错误 | 原因 | 处理 | |---|---|---| | 404 或路径重复 `/v1` | Base URL 写成 `.../v1`,客户端又拼 `/antigravity/v1...` | Base URL 改成 `https://api.clomio.ai` | | Anthropic 形态 401/403 | Key 不是 Antigravity 分组,或账号/订阅/余额不可用 | 换 Antigravity 分组 Key;检查订阅和余额 | | Gemini 形态返回 Google 风格 `UNAUTHENTICATED` | 缺 Key、Key 错误、用了废弃 query `api_key` | 使用 `Authorization: Bearer` 或 `x-goog-api-key`;不要用 `api_key` query | | `No active subscription found for this group` | 该分组需要有效套餐 | 开通或续订对应 Antigravity 分组 | | `Insufficient account balance` | 余额不足 | 充值或换有额度的 Key | | `Missing model in URL` / `Unsupported action` | `/antigravity/v1beta/models...` 路径拼错 | 使用 `/antigravity/v1beta/models/{model}:generateContent` | --- ## 排障信息 提交工单时请带: - 完整 Base URL 与实际请求路径。 - Key 名称和分组名,不要发送完整密钥。 - 使用的是 `/antigravity/v1/messages` 还是 `/antigravity/v1beta/models...`。 - HTTP 状态码、响应体、`x-request-id` 或控制台用量记录。 Antigravity 与 Gemini/Claude 的模型可见性可能不同。以 Antigravity 分组的控制台模型列表、`/antigravity/models` 或对应模型列表端点为准。 ## 相关文档 - [Gemini 原生兼容](#/api-gemini)：普通 Gemini 分组的 `/v1beta/models...` 调用方式。 - [创建 API 密钥](#/api-key)：确认 Key 绑定的是 Antigravity 分组还是普通 Gemini/Claude/OpenAI/Grok 分组。 - [Base URL 与 /v1 规则](#/base-url-matrix)：不同协议的根地址是否带 `/v1`。 - [故障排查](#/troubleshooting)：按错误码、端点和分组快速定位。 --- # OpenClaw 接入 [OpenClaw](https://openclaw.ai/) 是一个开源的自治 AI 智能体,带本地控制台、可接入多种消息渠道。把它的模型服务指向 Clomio,就能用 Clomio 的额度驱动它。 > 本页只解决一件事:**把 OpenClaw 的模型调用接到 Clomio 并验证可用**。渠道(如 WhatsApp/Telegram)配置请参考 OpenClaw 官方文档。 > **服务端边界:** Hermes/OpenClaw 的 `api_mode`、`api`、provider 枚举只是客户端侧选择。Clomio/sub2api 服务端不会识别“Hermes provider”或“OpenClaw enum”，只根据实际 HTTP path 与 API Key 绑定分组路由：Grok 对话走 `POST /v1/responses`，Claude 走 `POST /v1/messages`，OpenAI/Codex 走 Responses/Chat/Images/Embeddings 对应端点；Videos 只属于启用视频能力的 Grok 分组。 --- ## 一、准备 - 在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个 API 密钥(见 [创建 API 密钥](#/api-key)) - 知道你要调用的模型名(以控制台分组为准) - 环境:推荐 Node 较新版本;Windows 建议用 **WSL2 + Ubuntu** - 如需运行环境,见 [Node.js 环境](#/nodejs) --- ## 二、安装 macOS / Linux / WSL2: ```bash # 安装,--no-onboard 表示先不自动进向导 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` 验证: ```bash openclaw --help ``` --- ## 三、用向导接入 Clomio 启动接入向导: ```bash openclaw onboard ``` 到模型/鉴权步骤时,选 **Custom provider(自定义服务商)**,按下表填: | 字段 | 填写 | |------|------| | 兼容类型 / API | Clomio 常规只推荐 `openai-responses`、`openai-completions` 或 `anthropic-messages` | | 基础地址 | 见下方 `/v1` 规则 | | 模型名 | 控制台中该分组开放的模型,如 `claude-sonnet-4-6`、`gpt-5.4`、Grok 模型 | | Provider ID | `clomio` 或更细分的 `clomio-responses`、`clomio-anthropic` | | API Key | 你的 Clomio 密钥 | **基础地址按兼容类型填:** - `openai-responses` / `openai-completions` → `https://api.clomio.ai/v1`(**加** `/v1`) - `anthropic-messages` → `https://api.clomio.ai`(**不加** `/v1`) > 地址也可换成另外两条[线路](#/gateway-lines)。模型引用通常写成 **`provider/model`**,例如 `clomio/gpt-5.4`。 OpenClaw 官方模型引用以 `provider/model` 为核心:provider 负责鉴权、Base URL 和 API 形状,model 是该 provider 下声明的 `models[].id`。接 Clomio 时建议按协议拆 provider,而不是把 Claude、GPT、Grok 混进同一个 provider。 --- ## 四、配置文件方式:models.providers OpenClaw 的自定义服务商写在 `models.providers.`。核心字段: - `baseUrl`: 网关基础地址 - `apiKey`: API Key 或环境变量引用 - `api`: provider 的协议形状；接 Clomio 时优先用 `openai-responses`、`openai-completions`、`anthropic-messages` - `models`: 该 provider 下可用模型列表 `api` 字段不要把 OpenClaw 支持的所有枚举都当成 Clomio 推荐项。不同 OpenClaw 版本/内置 provider 报错里可能出现 `openai-completions`、`openai-responses`、`openai-codex-responses`、`openai-chatgpt-responses`、`anthropic-messages`、`google-generative-ai`、`github-copilot`、`bedrock-converse-stream`、`ollama`、`azure-openai-responses` 等值；接 Clomio custom provider 时按下面三类选即可: | Clomio 场景 | 推荐 `api` | `baseUrl` | |---|---|---| | Claude / Anthropic-compatible | `anthropic-messages` | `https://api.clomio.ai`，不加 `/v1` | | OpenAI Chat Completions | `openai-completions` | `https://api.clomio.ai/v1` | | Responses / Codex / Grok Responses | `openai-responses` | `https://api.clomio.ai/v1` | `openai-codex-responses`、`openai-chatgpt-responses`、`azure-openai-responses`、`google-generative-ai`、`ollama` 等只在对应 OpenClaw 版本或官方 provider 明确要求时使用，不作为 Clomio custom provider 的首选。 下面示例用环境变量保存密钥: ```bash export CLOMIO_API_KEY="你的密钥" ``` ### OpenAI Responses 示例 适合走 `/v1/responses` 的分组,例如 Responses/Codex/Grok Responses 类接口。 ```json { "models": { "providers": { "clomio-responses": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_API_KEY}", "api": "openai-responses", "models": [ { "id": "gpt-5.4", "name": "GPT 5.4 via Clomio Responses" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-responses/gpt-5.4" } } } } ``` Grok 用 OpenAI-compatible Responses provider,模型引用形如 `clomio-grok/grok-4.3`;Grok 不要配置到 `anthropic-messages`,也不要用 `openai-completions`: ```json { "models": { "providers": { "clomio-grok": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_GROK_API_KEY}", "api": "openai-responses", "models": [ { "id": "grok-4.3", "name": "Grok 4.3 via Clomio", "input": ["text", "image"] } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-grok/grok-4.3" } } } } ``` 如果该模型要接收图片,在 OpenClaw 的模型元数据里声明 `input: ["text", "image"]`;否则 WebChat 或节点侧附件可能被当成纯文本媒体引用。 ### OpenAI Completions 示例 适合标准 OpenAI-compatible `/v1/chat/completions` 服务。 ```json { "models": { "providers": { "clomio-openai": { "baseUrl": "https://api.clomio.ai/v1", "apiKey": "${CLOMIO_API_KEY}", "api": "openai-completions", "models": [ { "id": "gpt-5.4", "name": "GPT 5.4 via Clomio Chat Completions" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-openai/gpt-5.4" } } } } ``` ### Anthropic Messages 示例 适合 Claude / Anthropic Messages 形状的分组。注意 `baseUrl` **不带** `/v1`。 ```json { "models": { "providers": { "clomio-anthropic": { "baseUrl": "https://api.clomio.ai", "apiKey": "${CLOMIO_API_KEY}", "api": "anthropic-messages", "models": [ { "id": "claude-sonnet-4-6", "name": "Claude Sonnet via Clomio" } ] } } }, "agents": { "defaults": { "model": { "primary": "clomio-anthropic/claude-sonnet-4-6" } } } } ``` > 如果一个 Clomio 密钥只属于某个分组,请不要把不同协议的模型混在同一个 provider 里。建议按协议拆成 `clomio-responses`、`clomio-openai`、`clomio-anthropic`。 --- ## 五、验证 向导或配置完成后,先用 curl 证明 Clomio Key、模型和协议本身可用,再排 OpenClaw 配置。 OpenAI Responses / Grok Responses: ```bash curl https://api.clomio.ai/v1/responses -H "Authorization: Bearer $CLOMIO_API_KEY" -H "content-type: application/json" -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` OpenAI Chat Completions(不要用于 Grok 分组): ```bash curl https://api.clomio.ai/v1/chat/completions -H "Authorization: Bearer $CLOMIO_API_KEY" -H "content-type: application/json" -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' ``` Anthropic Messages: ```bash curl https://api.clomio.ai/v1/messages -H "Authorization: Bearer $CLOMIO_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` curl 通过后再运行: ```bash openclaw doctor # 检查配置格式、可修复项和密钥引用 openclaw models list # 查看 OpenClaw 实际加载到的 provider/model openclaw models get # 查看当前默认模型(如版本支持) openclaw status # 查看运行状态与默认模型 openclaw dashboard # 打开本地控制台,发一条消息测试 ``` 如果 `models get` 在你的版本里不可用,用 `openclaw models --help` 查看对应子命令。最终以 `openclaw models list` 能看到 `provider/model`、`openclaw status` 指向正确默认模型、dashboard 能收到模型回复为成功标准。 --- ## 六、脚本化接入(可选) 写进部署脚本时用非交互模式。OpenAI-compatible 示例: ```bash export CUSTOM_API_KEY="你的密钥" openclaw onboard --non-interactive \ --mode local \ --auth-choice custom-api-key \ --custom-base-url "https://api.clomio.ai/v1" \ --custom-model-id "gpt-5.4" \ --custom-provider-id "clomio-openai" \ --custom-compatibility openai \ --secret-input-mode ref \ --gateway-port 18789 \ --gateway-bind loopback ``` 手写配置时,默认模型要写成 **`服务商ID/模型名`** 格式(如 `clomio-openai/gpt-5.4`),只写模型名会报“模型不存在”。脚本里的 `--custom-compatibility openai` 在不同版本里可能默认落到 Chat Completions;如果目标是 Codex/Grok Responses,请确认该版本能显式选择 `openai-responses` 或在生成后的 `models.providers..api` 中改成 `openai-responses`,否则 Grok 会因为走 `/v1/chat/completions` 而失败。 --- ## 常见问题 **填了地址还连不上?** 先确认 `openai-responses` / `openai-completions` 的 `baseUrl` 带 `/v1`,而 `anthropic-messages` 的 `baseUrl` 不带 `/v1`,且没有多余斜杠。 **报模型不存在?** 模型名要与控制台分组一致;默认模型要写成 `provider/model`,例如 `clomio-responses/gpt-5.4`。只在 `agents.defaults.models` 里写 allowlist 不等于注册 provider,自定义模型还要在 `models.providers..models[]` 里声明。 **为什么 `provider/model` 有时会“少掉第一段”?** `provider/model` 的第一段主要给 OpenClaw 选择 provider。比如默认模型写 `clomio-responses/gpt-5.4`,真正发给 Clomio 的模型通常是 provider 下的 `models[].id`：`gpt-5.4`。如果真实上游模型 ID 本身带 slash,例如 `xai/grok-4.3`,就把 provider 下模型声明为 `"id": "xai/grok-4.3"`,默认模型写 `clomio-responses/xai/grok-4.3`;OpenClaw 去掉第一段 provider 后,发给 Clomio 的仍是 `xai/grok-4.3`。 **`openclaw models list` 看不到模型?** 检查配置文件层级是不是 `models.providers.`,字段名是不是 `baseUrl`、`apiKey`、`api`、`models`,而不是其他工具的 `base_url` 或 `key_env`。 **选错 `api` 会怎样?** `openai-completions` 会发 Chat Completions 形状请求;`openai-responses` 会发 Responses 形状请求;`anthropic-messages` 会发 Anthropic Messages 形状请求。协议和分组不匹配时常见 400、404、字段解析失败、工具调用异常。 **Anthropic-compatible 为什么配置不带 `/v1`?** OpenClaw 在 `anthropic-messages` 模式下按 Anthropic Messages 路径拼接请求。`baseUrl` 写成 `https://api.clomio.ai/v1` 容易导致路径重复或端点不匹配。 **一个 provider 能同时放 Claude、GPT、Grok 吗?** 不建议。不同协议对应不同 `api`,最好按协议拆 provider,再通过 `provider/model` 指定默认模型和 fallback。 **allowlist 写了但还是 `model not found`?** `agents.defaults.models["provider/model"]` 或可见性/别名配置只控制展示和默认选择,不等于注册运行时模型。自定义模型必须同时存在于 `models.providers..models[]`,且 `agents.defaults.model.primary` 要写完整的 `provider/model`。 **看到 `/v1/messages`、`/v1/responses` 或 `/v1/chat/completions` 与预期不一致?** 这是 `api` 选错的信号:`anthropic-messages` 会打 `/v1/messages`;`openai-responses` 会打 `/v1/responses`;`openai-completions` 会打 `/v1/chat/completions`。按错误里的路径反推当前 provider,再核对 Key 分组是否匹配。 **密钥环境变量没生效?** 先在同一个 shell 里运行 `echo ${CLOMIO_API_KEY:+set}`;如果用 systemd、桌面应用或守护进程启动 OpenClaw,要把环境变量写入对应启动环境。 **OpenAI 官方 provider 和 Clomio custom provider 怎么区分?** OpenClaw 官方 `openai/*` provider 面向 OpenAI/Codex 自身认证与运行时;Clomio 接入按 custom provider 写 `models.providers.` 更可控。不要把 `openai/gpt-*`、`clomio-responses/gpt-*` 和 `clomio-anthropic/claude-*` 混写成同一个默认模型。 --- ## 官方参考资料 - [OpenClaw Model providers](https://docs.openclaw.ai/concepts/model-providers):provider 负责认证与模型目录,默认模型使用 `provider/model`。 - [OpenClaw OpenAI provider](https://docs.openclaw.ai/providers/openai):官方 `openai/*` provider 的认证、Codex/OpenAI 运行时和模型路由说明。 - [OpenClaw Models CLI](https://docs.openclaw.ai/concepts/models):用 `openclaw models list/status/auth` 核对当前可用 provider、模型和认证状态。 这些资料里的外部经验落到 Clomio 时要做三件事:第一,不要直接复用官方 `openai/*` provider 的默认地址,应新建 `models.providers.` custom provider;第二,OpenAI-compatible provider 的 `baseUrl` 写到 `https://api.clomio.ai/v1`,Anthropic Messages provider 写到 `https://api.clomio.ai`;第三,把 Claude、GPT/Codex、Grok 拆成不同 provider,因为 sub2api 最终按真实 HTTP path 和 Key 分组门禁路由,不是按 OpenClaw 的模型展示名路由。 > 其余网络类问题见 [故障排查](#/troubleshooting)。 --- # Hermes 接入 [Hermes Agent](https://hermes-agent.nousresearch.com/)(Nous Research 出品,开源)是一个自治 AI 智能体:连接模型端点、执行任务,并通过持久记忆与技能不断改进。它既是 CLI,也带桌面/消息网关。它能接自定义模型端点,可用 `chat_completions`、`codex_responses`、`anthropic_messages` 三种 `api_mode` 对接 Clomio。 > **服务端边界:** Hermes/OpenClaw 的 `api_mode`、`api`、provider 枚举只是客户端侧选择。Clomio/sub2api 服务端不会识别“Hermes provider”或“OpenClaw enum”，只根据实际 HTTP path 与 API Key 绑定分组路由：Grok 对话走 `POST /v1/responses`，Claude 走 `POST /v1/messages`，OpenAI/Codex 走 Responses/Chat/Images/Embeddings 对应端点；Videos 只属于启用视频能力的 Grok 分组。 --- ## 一、安装 macOS / Linux(Windows 用 **WSL2**): ```bash curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` 安装器会把 Hermes 装到 `~/.hermes/`,创建 Python 3.11 虚拟环境并装好依赖与浏览器工具。需要 Python 3.11+。 --- ## 二、接入 Clomio(交互式) 运行模型设置: ```bash hermes model ``` 选 **Custom endpoint(自定义端点 / 自托管)**,依次填: | 项 | OpenAI-compatible | Anthropic-compatible | |----|-------------------|----------------------| | API 基础地址 | `https://api.clomio.ai/v1` | `https://api.clomio.ai` | | API Key | 你的 Clomio 密钥 | 你的 Clomio 密钥 | | API mode | `chat_completions` 或 `codex_responses` | `anthropic_messages` | | 模型名 | 控制台中该分组开放的 GPT/Grok/Codex 模型 | 控制台中该分组开放的 Claude 模型 | Hermes 当前自定义服务商以 `custom_providers` 保存配置,关键字段是 `api_mode`: - `chat_completions`: OpenAI-compatible Chat Completions 形状 - `codex_responses`: OpenAI-compatible Responses / Codex Responses 形状 - `anthropic_messages`: Anthropic Messages 形状 > 地址也可换成另外两条[线路](#/gateway-lines)。OpenAI-compatible base URL 带 `/v1`;Anthropic-compatible base URL 不带 `/v1`。 建议按协议拆多个 provider,不要把 GPT、Grok、Claude 放进同一个自定义 provider: - `clomio-openai`: `chat_completions`,给普通 OpenAI-compatible `/v1/chat/completions` - `clomio-responses`: `codex_responses`,给 Codex / Responses / Grok Responses - `clomio-anthropic`: `anthropic_messages`,给 Claude / Anthropic-compatible `/v1/messages` 这样 fallback、辅助模型和 `/model custom::` 切换时不会把 Key 发到错误协议。 --- ## 三、配置文件方式 Hermes 把服务商配置存在 `~/.hermes/config.yaml`,密钥可放 `~/.hermes/.env`。推荐写 `custom_providers`,不要再使用旧式 `providers:` 写法。 ### OpenAI-compatible 示例 适合 GPT、Grok、OpenAI-compatible 代理等。普通 Chat Completions 兼容端点用 `chat_completions`;如果目标分组明确要求 Responses/Codex Responses,改成 `codex_responses`。 ```yaml # ~/.hermes/config.yaml custom_providers: - name: clomio-openai base_url: https://api.clomio.ai/v1 key_env: CLOMIO_API_KEY api_mode: chat_completions models: - id: gpt-5.4 context_window: 128000 model: provider: custom:clomio-openai default: gpt-5.4 ``` 如果接的是只支持 Responses 的分组,例如 Codex Responses 类接口: ```yaml custom_providers: - name: clomio-responses base_url: https://api.clomio.ai/v1 key_env: CLOMIO_API_KEY api_mode: codex_responses models: - id: gpt-5.4-codex context_window: 128000 model: provider: custom:clomio-responses default: gpt-5.4-codex ``` Grok 建议单独配置 Responses provider；Grok 分组也可使用 Chat Completions，Messages 是否可用以分组能力为准: ```yaml custom_providers: - name: clomio-grok base_url: https://api.clomio.ai/v1 key_env: CLOMIO_GROK_API_KEY api_mode: codex_responses models: - id: grok-4.3 context_window: 1000000 model: provider: custom:clomio-grok default: grok-4.3 ``` ### Anthropic-compatible 示例 适合 Claude / Anthropic Messages 形状的分组。注意 base URL **不加** `/v1`。 ```yaml # ~/.hermes/config.yaml custom_providers: - name: clomio-anthropic base_url: https://api.clomio.ai key_env: CLOMIO_API_KEY api_mode: anthropic_messages models: - id: claude-sonnet-4-6 context_window: 200000 model: provider: custom:clomio-anthropic default: claude-sonnet-4-6 ``` 密钥写入 `~/.hermes/.env`: ```bash CLOMIO_API_KEY=你的密钥 ``` 也可以用命令直接设值,免去手改文件: ```bash hermes config set CLOMIO_API_KEY 你的密钥 ``` 排查 Hermes 时,先确认它到底读到哪份地址和 key: | 来源 | 常见位置 | 排查重点 | |------|----------|----------| | `custom_providers[*].base_url` / `api_mode` | `~/.hermes/config.yaml` | 决定请求走 `/v1/chat/completions`、`/v1/responses` 还是 `/v1/messages` | | `key_env` | 当前进程环境或 `~/.hermes/.env` | `hermes config set CLOMIO_API_KEY ...` 通常写到 `.env` | | `fallback_providers[*].api_key/base_url/api_mode` | `~/.hermes/config.yaml` | 显式 fallback 值会覆盖你以为的默认 provider | | 辅助模型 / review / vision / compression | `~/.hermes/config.yaml` | 这些槽位可能有自己的 `provider`、`base_url`、`api_mode`,不一定继承主聊天 | | 旧式 `providers:` | 旧配置文件 | 不推荐;优先迁到 named `custom_providers` | ```bash grep -nE 'custom_providers|provider|base_url|key_env|api_mode|fallback|auxiliary|vision|review|compression' ~/.hermes/config.yaml grep -n 'CLOMIO' ~/.hermes/.env env | grep -E 'CLOMIO|OPENAI|ANTHROPIC|XAI' ``` 切换到某个自定义服务商的模型时,可在会话内使用 Hermes 的 custom provider 语法: ```text /model custom:clomio-openai:gpt-5.4 /model custom:clomio-anthropic:claude-sonnet-4-6 ``` Hermes 的 `base_url` 比 `provider` 更显式:同一个模型槽位里只写 `provider` 时,Hermes 使用该 provider 的内置鉴权和内置地址;一旦写了 `base_url`,这个槽位就按该 URL 直连,并使用该槽位的 `api_key`、`key_env` 或 `OPENAI_API_KEY` 这类环境变量鉴权。不要写成 `provider: openrouter` + `base_url: https://api.clomio.ai/v1` 后还以为在走 OpenRouter 规则；实际请求会打到 Clomio。Clomio 最稳写法是 named `custom_providers` + 显式 `api_mode`。 ### Fallback 示例 fallback 也要保持协议一致。OpenAI Responses 失败时 fallback 到另一个 Responses provider;Anthropic Messages 失败时 fallback 到 Anthropic-compatible provider: ```yaml fallback_providers: - provider: custom:clomio-responses-backup model: gpt-5.4-codex base_url: https://sub.qazwc.com/v1 api_key: ${CLOMIO_BACKUP_OPENAI_KEY} api_mode: codex_responses ``` 不要把 `anthropic_messages` fallback 填到 `codex_responses` 会话里,也不要用 Grok provider 做 Claude fallback;协议不匹配时通常表现为 400/404 或响应字段解析失败。 --- ## 四、重要前提:上下文窗口 > Hermes 带工具的智能体用法**要求至少 64,000 token 的上下文**——窗口太小会在启动时被拒。请选择上下文足够大的模型(控制台分组里标注的大窗口模型)。 配置文件里可用 `context_window` 标注模型窗口,但真正是否能跑取决于上游模型实际支持的上下文。建议选择 64k 以上模型;Claude/GPT/Grok 的大窗口模型更适合 Hermes 的长任务和工具调用。 --- ## 五、验证 ### 先验证网关 Responses / Codex / Grok Responses: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer $CLOMIO_API_KEY" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` Chat Completions: ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer $CLOMIO_API_KEY" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' ``` Anthropic-compatible 可直接测 Messages: ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer $CLOMIO_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }' ``` > Anthropic-compatible 的 **配置 base URL 不带 `/v1`**,但 HTTP 端点本身仍是 `/v1/messages`;客户端会拼接这段路径。Clomio 用户侧 API Key 默认推荐 `Authorization: Bearer`;只有目标网关或直连 Anthropic Console 明确要求时,才改用 `x-api-key`。 ### 再验证 Hermes ```bash hermes model hermes ``` 配好后启动 Hermes,发一条消息能正常回复即接入成功。若校验端点失败,先确认: - OpenAI-compatible 的 `base_url` 是 `https://api.clomio.ai/v1`(带 `/v1`、无多余斜杠) - Anthropic-compatible 的 `base_url` 是 `https://api.clomio.ai`(不带 `/v1`) - `api_mode` 与分组协议匹配:`chat_completions` / `codex_responses` / `anthropic_messages` - 密钥正确、分组与模型匹配 - 选用的模型上下文 ≥ 64k --- ## 常见问题 **配置文件应该写 `providers:` 还是 `custom_providers:`?** 写 `custom_providers:`。Hermes 当前自定义端点文档和向导都围绕 `custom_providers` 与 `api_mode`。 **OpenAI-compatible 到底选哪个 `api_mode`?** 普通 `/v1/chat/completions` 兼容服务选 `chat_completions`;需要 `/v1/responses` / Codex Responses 形状的服务选 `codex_responses`。如果选错,常见表现是 404、400、没有工具调用结果或响应字段解析失败。 **Anthropic-compatible 为什么配置不带 `/v1`?** Hermes 会在 `anthropic_messages` 模式下拼 `/v1/messages`。配置成 `https://api.clomio.ai/v1` 容易变成重复路径或端点不匹配。 **启动时提示上下文太小?** 换 64k 以上上下文模型,并确认 `context_window` 不要写小于 64000。仅修改本地标注不能扩大模型真实窗口。 **`hermes model` 找不到模型?** 先确认 Clomio 控制台分组开放了该模型;再确认 `custom_providers[*].models[*].id` 与 `model.default` 完全一致。 **鉴权失败?** 确认 `key_env` 指向的环境变量存在。可运行 `grep CLOMIO_API_KEY ~/.hermes/.env` 或在当前 shell 中 `echo ${CLOMIO_API_KEY:+set}` 检查。`hermes config set CLOMIO_API_KEY ...` 会把密钥写入 `.env`;非密钥设置才进入 `config.yaml`。 **同 base URL 多个 custom provider 串 key?** 先升级 Hermes,再把不同协议/不同 key 拆成不同 provider 名。官方配置说明里 `base_url` 会覆盖 `provider` 并使用该槽位的 `api_key`/环境变量;如果你把多个辅助槽位、fallback 或 custom provider 都写成同一个裸 URL,排查时很难判断实际用了哪把 Key。 **主聊天正常,但 background review / vision / fallback 失败?** 这通常不是 Clomio API 本身的问题,而是 Hermes 某个辅助路径没有继承 custom provider 的 `base_url`、`api_key` 或 `api_mode`。把辅助模型也显式写成 named `custom_providers` 条目,并在 fallback/vision/review 配置里引用同一个 provider;不要只写裸 `provider: custom` + `key_env`。 **同一个 Key 有时通、有时 404/401?** 先看当前会话的 `model.provider` 和请求协议。OpenAI-compatible / Codex / Grok 的 Base URL 是 `https://api.clomio.ai/v1`;Claude / Anthropic-compatible 的 Base URL 是 `https://api.clomio.ai`。如果错误里出现 `/v1/messages` 但你用了 OpenAI/Grok Key,就是 Key 分组或 `api_mode` 不匹配;如果出现 `/v1/chat/completions` 但你配置的是 Grok,就是 provider 应改成 `codex_responses`。 > 关于可视化使用:Hermes 自带桌面端,安装后按其向导用同一套自定义端点配置即可;命令行只负责打通模型调用这一层。其余问题见 [故障排查](#/troubleshooting)。 --- ## 外部资料如何映射到 Clomio - [Hermes AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers/):Hermes 有多种内置 provider,也有 `Custom Endpoint`。接 Clomio 时不要套用内置 OpenRouter/xAI/Anthropic 的默认地址,而是按本页建 custom provider。 - [Hermes Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration/):辅助模型、fallback、vision、compression 等槽位都有自己的 `provider`/`model`/`base_url`/`api_key`。主聊天打通不代表这些辅助槽位一定继承 Clomio。 - [Hermes Adding Providers](https://hermes-agent.nousresearch.com/docs/developer-guide/adding-providers/):简单 API-key + OpenAI-compatible endpoint 走 custom provider 最清晰;只有要做专门鉴权/运行时适配时才需要新增内置 provider。 - 与 Clomio 的对应关系:OpenAI/Codex/Grok custom provider 使用 `https://api.clomio.ai/v1`;Claude/Anthropic-compatible custom provider 使用 `https://api.clomio.ai`;Videos 仍只属于 Grok 分组,不是 Hermes 的任意 provider 都能调用。 --- ## 下载与镜像 # CLI 镜像下载 `https://help.clomio.ai` 是 Clomio 的 CLI 安装镜像,只用于**安装、更新、确认 Claude Code / Codex / Grok CLI 版本**。模型调用请配置 API 网关 `https://api.clomio.ai`,不要把镜像域名当成 API Base URL。 --- ## 一键安装 打开终端,执行对应命令: | 工具 | macOS / Linux | Windows PowerShell | |------|------|------| | Claude Code | `curl -fsSL https://help.clomio.ai/claude/install.sh \| bash` | `irm https://help.clomio.ai/claude/install.ps1 \| iex` | | Codex | `curl -fsSL https://help.clomio.ai/codex/install.sh \| bash` | `irm https://help.clomio.ai/codex/install.ps1 \| iex` | | Grok | `curl -fsSL https://help.clomio.ai/grok/install.sh \| bash` | `irm https://help.clomio.ai/grok/install.ps1 \| iex` | --- ## 更新到最新版 安装和更新是同一条命令。想更新哪个工具,重新跑它的安装命令即可: ```bash curl -fsSL https://help.clomio.ai/claude/install.sh | bash curl -fsSL https://help.clomio.ai/codex/install.sh | bash curl -fsSL https://help.clomio.ai/grok/install.sh | bash ``` ```powershell irm https://help.clomio.ai/claude/install.ps1 | iex irm https://help.clomio.ai/codex/install.ps1 | iex irm https://help.clomio.ai/grok/install.ps1 | iex ``` 指定版本时,在命令末尾传版本号,例如: ```bash curl -fsSL https://help.clomio.ai/grok/install.sh | bash -s 0.2.73 ``` --- ## 确认版本 安装或更新后,重开终端,分别执行: ```bash claude --version codex --version grok --version ``` 能看到版本号就说明 CLI 本体已经装好。接下来还需要按工具配置 API Key 和 Base URL: - Claude Code / Anthropic-compatible:`https://api.clomio.ai`(不带 `/v1`) - Codex / OpenAI-compatible / Grok:`https://api.clomio.ai/v1`(带 `/v1`) 下一步按你要用的工具继续配置: - [Claude Code 接入](#/claude-code) - [Codex 接入](#/codex) - [Grok 接入](#/grok) - [Base URL 与 /v1 规则](#/base-url-matrix) --- ## 先查看脚本再执行 如果你不想直接 `curl | bash`,可以先把脚本下载到本地查看: ```bash curl -fsSL https://help.clomio.ai/claude/install.sh -o claude-install.sh sed -n '1,220p' claude-install.sh bash claude-install.sh ``` Codex / Grok 同理把路径换成 `/codex/install.sh` 或 `/grok/install.sh`。Windows 可将文件名换成 `install.ps1`,先用 `irm` 下载后再查看。脚本只负责下载对应平台的 CLI 文件、写入本地用户目录、提示 PATH;不会读取你的 Clomio API Key。 --- ## 版本、校验和下载位置 | 工具 | 版本指针 | 安装脚本内下载基址 | 说明 | |------|------|------|------| | Claude Code | `https://help.clomio.ai/claude/latest` | `https://help.clomio.ai/claude` | 按 manifest 下载对应平台二进制 | | Codex | `https://help.clomio.ai/codex/latest` | `https://help.clomio.ai/codex` | 版本目录内提供 `codex-package_SHA256SUMS` | | Grok | `https://help.clomio.ai/grok/stable` | `https://help.clomio.ai/grok` | 支持分片下载和指定版本 | 确认当前镜像版本: ```bash curl -fsSL https://help.clomio.ai/claude/latest curl -fsSL https://help.clomio.ai/codex/latest curl -fsSL https://help.clomio.ai/grok/stable ``` Codex 包可按版本目录里的 SHA256 文件做完整性校验。Claude/Grok 的校验逻辑以安装脚本和上游包信息为准;如果你在公司网络或安全审计环境里使用,建议先下载脚本和目标包,再由本机安全策略扫描后执行。 --- ## 卸载和清理 镜像安装默认写入当前用户目录,常见位置是 `~/.local/bin`、`~/.grok/bin` 或工具自己的配置目录。卸载时先查看命令位置: ```bash which claude || true which codex || true which grok || true ``` 然后删除对应二进制或安装目录。配置文件、登录状态和项目规则通常在 `~/.claude`、`~/.codex`、`~/.grok` 等目录;如果只是重装 CLI,不要直接删配置目录,避免丢失本地设置。 --- ## 常见安装提醒 - 如果终端下载超时,先完全退出 Clash、V2Ray、机场客户端等代理软件后重试。 - 如果提示 `command not found`,重开终端;仍不行再检查安装脚本提示的 PATH。 - 如果公司代理会替换证书,先按公司安全规范导入证书或换到可信网络;不要为了安装临时关闭系统证书校验。 - `help.clomio.ai` 是唯一镜像域名;不要使用其他不存在的镜像域。 > 镜像只负责安装 CLI。模型调用、Key、分组和线路排障见 [5 分钟快速开始](#/quickstart)、[服务状态](#/status) 与 [故障排查](#/troubleshooting)。 --- ## 平台信息 # 更新记录 这里记录 `help.clomio.ai` 文档、CLI 镜像和公开网关接入说明的用户可见变化。模型、倍率和分组实时能力仍以控制台当前显示为准。 --- ## 2026-06-30 ### 文档基础设施 - 公开文档主域名统一为 `help.clomio.ai`，旧 CLI 入口只保留兼容跳转。 - 新增 `robots.txt`、`sitemap.xml`、`llms.txt`、`docs/llms.txt`，方便搜索引擎和 AI 工具读取。 - 新增 `docs/search-index.json`，用于站内搜索。 - 新增基础 `openapi.json`，覆盖最常用的 Clomio 网关端点。 - 新增 [服务状态](#/status) 页面，集中说明公开入口、排障信号和工单信息。 ### 安装命令 - Claude Code、Codex、Grok 的安装与更新命令统一使用 `https://help.clomio.ai/.../install.sh`。 - 安装镜像只负责 CLI 下载和更新；模型调用仍使用 `https://api.clomio.ai` 或 `https://api.clomio.ai/v1`。 ### 文档体验 - 文档页将逐步补齐搜索、页面更新时间、Markdown 链接和反馈入口。 - Quickstart 将按“安装 CLI / 接 SDK / 排障 / 控制台”分流，降低新手理解成本。 --- # 服务状态 这个页面说明 Clomio 公开入口的用途和自查方式。实时可用模型、倍率、分组权限和服务可用性以控制台当前显示和单次请求的 `x-request-id` 记录为准。 --- ## 公开入口 | 入口 | 用途 | 正常现象 | |---|---|---| | `https://help.clomio.ai` | 文档、CLI 安装镜像、Codex Desktop 下载 | 首页和 `/docs/` 返回 200 | | `https://api.clomio.ai` | 默认 API 网关与控制台 | 控制台可登录，API 请求返回 `x-request-id` | | `https://sub.qazwc.com` | 备用/优化线路 | 协议和路径与默认网关一致 | | `https://crs.qazwc.com` | 备用/优化线路 | 协议和路径与默认网关一致 | --- ## 排障时先看什么 1. **HTTP 状态码**：401/403 先查密钥与分组，404 先查 Base URL 和 endpoint，429 先降并发，5xx 再看 request_id。 2. **响应头**：保留 `x-request-id` / `X-Request-Id`。 3. **控制台用量**：查看 request type、模型、分组、错误来源、上游状态和是否计费。 4. **线路替换**：如果只是网络不稳，可按 [网关线路](#/gateway-lines) 把 `api.clomio.ai` 换成备用线路，协议规则不变。 --- ## 最小健康检查 Claude / Anthropic-compatible： ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的Claude分组密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"控制台可用Claude模型","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` OpenAI / Codex Responses： ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的OpenAI或Codex分组密钥" \ -H "content-type: application/json" \ -d '{"model":"控制台可用GPT/Codex模型","input":"ping","max_output_tokens":8}' ``` Grok： ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的Grok分组密钥" \ -H "content-type: application/json" \ -d '{"model":"控制台可用Grok模型","input":"ping","max_output_tokens":8}' ``` --- ## 提交工单时带这些信息 - request_id 或错误详情页 ID - 发生时间和使用的线路域名 - API Key 所属分组，不要发送完整密钥 - endpoint、method、model - HTTP 状态码、响应体、客户端日志截图 - 是否流式、是否 WebSocket、是否经过代理 如果是安装问题，请附上执行的 `curl -fsSL ... | bash` 命令、操作系统、终端类型和脚本输出最后 30 行。 --- ## 排查与支持 # 故障排查 报错分两大类:**安装/环境类**(在你电脑上)和 **调用/网关类**(请求发出后)。下面按类型给出解法,网关类附了**真实高频报错对照表**。 > **通用技巧:** 看不懂的报错,截图发给能识别图片的 AI(豆包,或你已能用的 Claude / Codex),配一句"我是命令行新手,请一步一步带我解决,一次只给一步"。它会像远程陪你操作一样带你排查。 --- ## 一、安装 / 环境类 ## 1. 代理(翻墙)环境——最常见的隐形坑 很多电脑装了 Clash、V2Ray、Shadowsocks、机场客户端等代理软件。它们会悄悄改动系统网络设置,导致**浏览器能上网,但终端命令连不上**。 **典型症状:** `npm install` 卡住/超时、`ECONNREFUSED`、`ETIMEDOUT`、`UNABLE_TO_VERIFY_LEAF_SIGNATURE`、`CERT_HAS_EXPIRED`、`SELF_SIGNED_CERT_IN_CHAIN` 等证书/SSL 错误。 **解法:** 1. **完全退出**代理软件(右键退出,不是最小化) 2. **关掉当前终端,重开一个新窗口**(旧窗口的代理设置不会自动刷新) 3. 重新执行报错的命令 很多时候,关代理 + 重开终端就好了。 ## 2. 命令找不到(command not found / 不是内部或外部命令) 刚装过却说找不到 `claude` / `codex` / `grok` / `node`: - **没重开终端**:安装会改 `PATH`,先关掉重开新终端。 - **目录不在 PATH 里**:镜像安装的在 `~/.local/bin` 或 `~/.grok/bin`;npm 全局目录用 `npm bin -g` 查看,确认在 `PATH` 中。 ## 3. 权限问题(Permission denied / EACCES) 多见于 `npm install -g`:macOS/Linux 命令前加 `sudo`;Windows 用**提升权限**的 PowerShell。不要随意 `chmod 777` 系统目录。 ## 4. 网络 / 证书问题(timeout / fetch failed / SSL) 大概率仍是**代理**引起,先按第 1 节排查。确认无代理后,切国内 npm 源(见 [Node.js 环境](#/nodejs)):`npm config set registry https://registry.npmmirror.com`,或换个网络(手机热点)排除本地故障。 ## 5. 版本不兼容 / engine 不满足 提示需要更高 Node 版本时,先看 `node -v`,按 [Node.js 环境](#/nodejs) 升级到最新 LTS。 --- ## 二、调用 / 网关类(真实报错对照) 工具能连上、但请求出错。下面是平台上**最高频的真实报错**及处理方式。 ## 先按这个顺序定位 工单或自查时,不要只发一句“报错了”。按下面顺序收集信息,能最快定位到是路径、分组、模型、请求体还是上游问题: 1. **请求 ID**:`x-request-id` / 响应头 `X-Request-Id` / 工具日志里的 request_id。没有它很难精确定位单次请求。 2. **用量错误详情**:控制台用量明细里的错误类型、错误来源、错误阶段、上游状态码、上游错误详情、是否有 `Recovered upstream error ...`。 3. **分组平台**:当前 API Key 属于 Claude、OpenAI 还是 Grok 分组;同一个端点在不同分组可能完全不同。 4. **Base URL**:是否带 `/v1`,有没有拼成 `/v1/v1/...`,是否用了线路域名。 5. **endpoint**:实际请求路径和方法,例如 `POST /v1/responses`、`GET /v1/responses`、`POST /v1/videos/generations`。 6. **model**:请求体里的 `model`、控制台分组开放模型、模型映射、用量里的上游真实模型。 最常见误判是把“模型列表里有”当成“该端点可用”。端点能力先看分组平台,模型名再看分组开放和映射。 ### 为什么 request_id 仍要同时看用量与错误详情 `request_id` 是串联线索，但不同页面回答的问题不同：用量明细证明是否计费、用了哪个 Key/分组/模型、`request_type` 与 `billing_mode` 是什么；错误请求证明失败阶段、错误来源、上游状态和容灾链路。成功请求也可能有 `Recovered upstream error` 这类上游失败记录，它通常说明中间失败后已恢复，不等于最终失败。 错误详情里的用户侧 `category` 是稳定粗分类，适合工单和页面过滤：`auth`、`quota`、`rate_limit`、`invalid_request`、`upstream`、`service_unavailable`、`internal`、`cyber`、`other`。看到 `auth` 先查 Key 和权限，`quota` 先查余额/订阅/Key 限额，`rate_limit` 先降并发，`invalid_request` 先改请求体，`upstream` / `service_unavailable` 可稍后重试或换线路。 如果只有错误记录没有完整用量记录，也要提供错误 `id`、时间、模型、端点、Key 名称。响应头 `X-Request-Id` / `x-request-id` 和客户端自带的 `client_request_id` 都有排查价值；HTTP 200 但 SSE 里出现 `event: response.failed` 时，也应按流内失败提交。 ## 先用最小 curl 定位协议 把下面的 Key 和模型名替换成控制台里当前分组实际可用值。哪个 curl 成功,说明该协议、Base URL、Key 和模型这一层先通了；失败时保留 HTTP status、响应体和 `x-request-id`。 Claude / Anthropic Messages: ```bash curl https://api.clomio.ai/v1/messages \ -H "Authorization: Bearer 你的Claude分组密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}' ``` Codex / OpenAI Responses: ```bash curl https://api.clomio.ai/v1/responses \ -H "Authorization: Bearer 你的OpenAI或Codex分组密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}' ``` OpenAI Chat Completions: ```bash curl https://api.clomio.ai/v1/chat/completions \ -H "Authorization: Bearer 你的OpenAI分组密钥" \ -H "content-type: application/json" \ -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' ``` Grok Videos(Grok-only): ```bash curl https://api.clomio.ai/v1/videos/generations \ -H "Authorization: Bearer 你的Grok视频分组密钥" \ -H "content-type: application/json" \ -d '{"model":"控制台显示的视频模型ID","prompt":"one second test"}' ``` Gemini 原生: ```bash curl https://api.clomio.ai/v1beta/models \ -H "x-goog-api-key: 你的Gemini分组密钥" ``` Usage 查询: ```bash curl 'https://api.clomio.ai/v1/usage?limit=5' \ -H "Authorization: Bearer 你的密钥" ``` Claude Code 类问题先在会话里执行 `/status`，确认 `Anthropic base URL`、凭据来源和模型；不要只看 shell export 或某一个配置文件。如果 `/status` 仍显示旧 claude.ai 登录或旧网关,先 `/logout`,退出后清理旧变量: ```bash env | grep -E 'ANTHROPIC|CLAUDE' unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN export ANTHROPIC_BASE_URL="https://api.clomio.ai" export ANTHROPIC_AUTH_TOKEN="你的密钥" ``` 然后重开终端/Claude Code 再看 `/status`。Clomio 常规 Key 推荐 `ANTHROPIC_AUTH_TOKEN`，对应 `Authorization: Bearer`;`ANTHROPIC_API_KEY` 对应 `x-api-key`,只在网关明确要求时使用。 ## 端点 × 分组速查 | 端点 | Claude 分组 | OpenAI 分组 | Grok 分组 | |------|:----:|:----:|:----:| | `/v1/messages` | ✓ | ✓* | ✗ | | `/v1/messages/count_tokens` | ✓ | ✗ | ✗ | | `/v1/chat/completions` | ✓** | ✓ | ✗ | | `POST /v1/responses` | ✗ | ✓ | ✓ | | `GET /v1/responses` | ✗ | ✓ | ✗ | | `/v1/embeddings` | ✗ | ✓ | ✗ | | `/v1/images/*` | ✗ | ✓ | ✓ | | `/v1/videos/*` | ✗ | ✗ | ✓ | | `/v1/web_search` | ✗ | ✗ | ✓ | | `/v1/models` | ✓ | ✓ | ✓ | > \* OpenAI 分组只有在当前分组开放 Messages 兼容能力时才接受 `/v1/messages`,否则会返回 `This group does not allow /v1/messages dispatch`。 > > \** Claude 分组的 Chat Completions 是转换兼容路径;Claude Code only 分组仍只允许 `/v1/messages`。 当前没有 `GET /v1/responses/{id}` 和 `GET /v1/models/{id}`。`GET /v1/responses` 是 Codex/Responses WebSocket v2 入口,不是查询历史响应的 REST 资源。 常见误写也包括 `/openai/v1/...`、`/v1/images2api/*`、`/v1/images/variations`、`GET /v1/web_search`、`POST /v1/videos/{id}` 和 `/antigravity/v1/responses`。这些不是当前公开 gateway 路由；按 [API 概述](#/api-usage) 的端点表换成已注册路径。 配置入口可直接跳到对应文档:Claude 看 [Claude Code](#/claude-code),Codex 看 [Codex](#/codex),Grok 看 [Grok](#/grok),Cherry Studio 看 [Cherry Studio](#/cherry-studio),多供应商切换看 [CC Switch](#/cc-switch)。 ## 配置类(最常见,你能自己解决) | 报错文案(关键词) | 含义 | 怎么办 | |------|------|--------| | `The current group does not support the requested model "xxx". Available models: ...` | **分组明确不支持该模型**。OpenAI/Claude 兼容响应通常是 403 `permission_error`;Gemini 原生路径会更像 `PERMISSION_DENIED`;可用模型列表过长时只展示前 20 个并显示 `and N more` | 把模型名改成报错里 `Available models` 列出的;或在控制台给密钥换一个支持该模型的分组 | | `model_not_found` / `Model "xxx" is not supported by any configured account in this group` | 当前分组无法服务该模型。常见于模型名写错、模型映射未开放或用错分组 | 先核对模型名；再看控制台该分组支持模型。工单请带 `model_not_found`、模型名、分组名 | | `This group does not allow /v1/messages dispatch` | OpenAI 分组未开放 Claude Messages 形状转 OpenAI 调度 | 改用 `/v1/responses` / `/v1/chat/completions`；或换到已开放 Messages 兼容能力的 OpenAI 分组 | | `This group is restricted to Claude Code clients (/v1/messages only)` | Claude Code 专用分组被拿去调用 OpenAI Chat/Responses 端点 | Claude Code 用 `/v1/messages`;Codex/OpenAI SDK 请换 GPT/OpenAI 分组 | | `Chat Completions API is not supported for this platform` / `Messages API is not supported for this platform` / `Responses WebSocket API is not supported for this platform` | 当前分组未开放对应协议 | Grok/OpenAI 分组通常可用 Chat/Responses，Messages 和 WS 需看分组能力；Embeddings 仍使用 OpenAI 分组 | | `api_key_in_query_deprecated` / `API key in query parameter is deprecated` | OpenAI-compatible/Claude 网关路径把 API Key 放在 query 参数里 | 改用 `Authorization: Bearer sk-...`；Gemini 原生路径如需 query 只使用 `key=`，不要用 `api_key=` | | `ACCESS_DENIED` / `Access denied. Your IP is ...` | API Key 绑定了 IP 白名单或访问规则,当前出口 IP 不在允许范围 | 在控制台更新 Key 的 IP 白名单,或固定代理出口后重试 | | `Token counting is not supported for this platform` | Claude Code 会额外请求 `/v1/messages/count_tokens` 做上下文估算；OpenAI/Grok 分组或不支持该能力的上游会返回 404 | 只要主对话 `POST /v1/messages` 正常，通常可忽略；主对话也失败时再检查分组是否支持 Messages | | `Embeddings API is not supported for this platform` | `/v1/embeddings` 只支持 OpenAI 分组 | 换 OpenAI 分组和 embedding 模型 | | `Images API is not supported for this platform` | `/v1/images/*` 只支持 OpenAI/Grok 分组 | 换 OpenAI 或 Grok 图像分组 | | `Web Search API is not supported for this platform` | `/v1/web_search` 只支持 Grok 分组 | 换 Grok 分组 | | `Videos API is not supported for this platform` | 视频端点只在 Grok 视频分组开放,OpenAI/Claude 等分组会拒绝 | 视频生成请使用 Grok 分组;文本/图片继续用各自分组 | | `API key group platform is not gemini` | `/v1beta` Gemini 原生路径使用了非 Gemini 分组 | 换 Gemini 分组 Key;Antigravity 客户端用 `/antigravity/v1beta/...` | | `Query parameter api_key is deprecated. Use Authorization header or key instead.` | Gemini 风格入口用了废弃 `api_key` query | 改用 `Authorization: Bearer`、`x-goog-api-key` 或 `key` query | | `Video generation is not enabled for this group` | 当前分组没有开启视频生成权限 | 换到已开通视频的 Grok 分组,或联系支持开通 | | `Your input exceeds the context window of this model` | **输入超出该模型上下文窗口** | 精简输入;用 `/compact` 压缩对话;或换更大窗口的模型 | | `Insufficient account balance` / `余额不足` | **额度用尽** | 控制台充值,见 [计费与额度](#/billing) | | `API Key 所属分组已停用` | 该密钥的**分组被停用** | 换一个可用分组重建密钥 | | `No active subscription found for this group` | 该分组**无有效套餐/订阅** | 在控制台为该分组开通/续订,或换分组 | | `daily usage limit exceeded` / `weekly usage limit exceeded` / `monthly usage limit exceeded` | 密钥或订阅触发日/周/月用量限制 | 等窗口重置;或在控制台调整限额/换分组 | | `rate limit exceeded` | 本平台 API Key 侧限速,还没到上游 | 降低并发和自动重试频率;工单带 API Key 名称和时间窗口 | | `内容审计命中风险规则，请调整输入后重试` | **内容审计**拦截 | 调整输入措辞后重试。若认为误判,工单带 request_id 和原始提示词摘要 | | `内容审计服务暂不可用，请稍后重试` | 内容审计服务异常且当前策略按失败拦截 | 稍后重试;持续出现提交工单,带 `CONTENT_MODERATION` / `audit_api_failed` 关键词 | | `Request body too large, limit is ...` / `Request body is too large` / `message too big` | **请求体过大**(HTTP 413),通常是附件、图片、长上下文或整仓内容太大 | 减少附件/上下文;长文件分批处理;避免把二进制/大日志直接塞进一条请求 | ## 服务波动类(多为临时,重试或换线路) | 报错文案(关键词) | 含义 | 怎么办 | |------|------|--------| | `No available accounts supporting model: xxx` | 当前没有可用服务能力支持该模型；不一定是真模型名错误，也可能是临时容量或上游限速 | 先看是否同时出现 `model_not_found`（配置问题）；没有则按临时容量问题处理：稍后重试、换线路/分组/模型；工单带 request_id、模型名和时间 | | `No available accounts` / `Service temporarily unavailable` | 当前分组暂时没有可用服务能力。常见原因：上游 429、服务额度/订阅限制、临时限制或并发槽位耗尽 | 稍后重试；换[网关线路](#/gateway-lines)或分组。工单请带 request_id、时间和错误体 | | `No available compatible accounts for video generation` | 视频请求暂时没有可用的视频生成服务能力 | 确认使用 Grok 视频分组；稍后重试或换分组 | | `temp_unschedulable` / `temp_unschedulable_until` / `temporary unschedulable` | 服务能力被临时冷却；`temp_unschedulable_until` 是恢复时间，`temp_unschedulable_reason` 是冷却原因。它不是用户余额或 Key 额度能清掉的问题 | 等冷却时间结束会自动恢复；持续出现需工单带 request_id、分组和关键词 `temp_unschedulable_reason` | | `Upstream transport error` / `Upstream service temporarily unavailable` / `Upstream request failed` | **上游临时不可用**或网络传输失败 | 稍等重试;换线路。若多次自动切换后仍失败,带 request_id 工单 | | `Too many pending requests, please retry later` | **请求堆积/并发槽位等待超时** | 降低并发,稍后重试;避免多个工具共用同一密钥高并发冲刺 | | `Concurrency limit exceeded for user/account` | 用户级或服务侧并发槽位已满，不是上游模型不存在 | 降低并发、等待当前流式任务结束；不要让多个客户端共用同一 Key 同时冲刺 | | `Upstream rate limit exceeded, please retry later` / `rate_limit_exceeded` | 上游限速,网关会尽量切换账号;全部账号都受限时返回 429 | 降并发,稍后重试;换分组/线路分流 | | `The usage limit has been reached` / `You've hit your usage limit` / `usage_limit_reached` / `Approaching upstream rate limits` | 上游用量上限或 Codex/ChatGPT 套餐限制 | 等上游重置；换分组/模型；高峰期不要持续重试同一任务 | | `Upstream access forbidden` | 上游拒绝访问 | 换线路重试;持续出现联系支持 | | `our servers are currently overloaded` | 上游过载 | 稍后重试,或换线路 | 快速区分本地限制 vs 上游限制：`Too many pending requests...`、`Concurrency limit exceeded...` 多数是排队/并发槽位；`Upstream rate limit exceeded...`、`rate_limit_exceeded`、`The usage limit has been reached` 更偏上游限速或套餐。`Recovered upstream error 429/5xx: ...` 表示中途某个上游失败被容灾覆盖，不等于最终请求一定失败；最终状态仍看客户端响应和用量/错误详情。 ## OpenAI Responses / Codex 续接类 这类多见于 Codex、OpenAI Responses API、带工具调用的多轮会话。它们通常不是网络问题,而是**续接上下文或请求结构**不被上游接受。 | 报错文案(关键词) | 含义 | 怎么办 | |------|------|--------| | `invalid_encrypted_content` / `The encrypted content could not be verified` | 上一轮返回的加密 reasoning/context 无法被当前上游验证。常见于 `previous_response_id` 续接、账号切换、会话太旧或上下文被工具改写 | 新开一轮对话或执行 `/compact`;不要手工拼接/复用旧 `encrypted_content`。工单带 request_id、`previous_response_id`、是否 Codex | | `previous_response_not_found` / `unsupported_previous_response_id` | 上游找不到或不支持你要续接的 response id | 新开会话或让工具压缩上下文后继续;不要跨分组/跨工具复用 response id | | `function_call_output requires call_id on HTTP requests` | 发送了工具调用结果,但缺少对应 `call_id` | 使用工具/SDK自动生成的工具结果,不要手写删字段;HTTP 普通请求必须带 `call_id` | | `function_call_output requires item_reference ids matching each call_id` | 工具结果虽然有 `call_id`,但缺少能关联原始工具调用 item 的 reference | 让 Codex/SDK接管工具调用续接;不要只保存最后一条 `function_call_output` 后重放 | | SSE 中出现 `event: response.failed` | SSE 已经开始后才发生错误,HTTP 状态码可能仍是 200,真实失败在 SSE 终止事件里 | 看 `response.error.code/message`;工单带完整 SSE 末尾片段和 request_id | | SSE 中出现 `event: response.cancelled` | 同一会话有新请求抢占、客户端主动取消,或网关按 Responses 协议发出取消终止事件 | 如果是自己开了新请求,旧流取消属正常;否则带 request_id 和工具日志排查 | ## Base URL / 端点 / 分组不匹配 | 现象 | 常见原因 | 正确做法 | |------|----------|----------| | `404 Not Found`、`Cannot POST /v1/v1/...`、路径里出现两个 `/v1` | Base URL 多填了 `/v1`,而工具自己又追加 `/v1` | 若工具有独立 Endpoint Path,Base URL 填 `https://api.clomio.ai`;若工具要求 OpenAI Base URL,通常填 `https://api.clomio.ai/v1`。不要同时在两个地方都写 `/v1` | | `404` 且路径没有 `/v1` | 工具要求 OpenAI-compatible 地址,但 Base URL 少了 `/v1` | 把 Base URL 改为 `https://api.clomio.ai/v1`、`https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1` | | Claude Code 报 `/v1/messages` 相关错误 | Claude Code 应走 Anthropic Messages 协议 | Claude Code 用 Claude 分组和 `/v1/messages`;不要用 GPT/Grok 分组 | | Codex / OpenAI SDK 报 `/v1/responses`、`/v1/chat/completions` 相关错误 | OpenAI 工具应走 OpenAI-compatible 协议 | Codex/OpenAI SDK 用 GPT/OpenAI 分组;不要用 Claude-only 分组 | | Grok 视频请求在 OpenAI/Claude 分组返回 `Videos API is not supported for this platform` | 视频路由按分组平台限制,Grok 视频是 Grok/xAI 能力 | 视频用 Grok 分组;文本、图片、Claude Code 分开建 Key | | `GET /v1/responses/{id}` 或 `GET /v1/models/{id}` 返回 404 | 当前网关没有这两个按 ID 查询的 REST 路由。`GET /v1/responses` 仅是 Codex/Responses WS v2 流入口;Models 只支持列表 | Responses 多轮用下一次 `POST /v1/responses` 携带 `previous_response_id`;查模型用 `GET /v1/models` 列表或发最小请求验证 | ## 控制台账号 / 支付 / 工单真实报错 这些错误来自控制台网页功能,不要和模型网关调用失败混为一谈: | 错误关键词 | 来源 | 处理 | |---|---|---| | `PENDING_AUTH_NOT_READY` / `PENDING_AUTH_TARGET_USER_MISMATCH` / `Pending oauth session provider mismatch` | OAuth pending 注册/绑定 | 重新从对应 provider 入口授权,不要混用旧链接;详见 [邀请、工单与账号](#/console-account) | | `TOTP_INVALID_CODE` / `TOTP_SETUP_EXPIRED` / `TOTP_TOO_MANY_ATTEMPTS` | TOTP 双因素认证 | 核对手机时间,过期则重新 setup,多次失败先等冷却 | | `GROUP_NOT_ALLOWED` | API Key 创建/编辑绑定分组 | 当前用户不能绑定该分组：订阅型分组需有效订阅，其他分组以控制台可选列表为准；换可用分组或提交工单 | | `API_KEY_EXISTS` / `API_KEY_TOO_SHORT` / `API_KEY_INVALID_CHARS` / `API_KEY_RATE_LIMITED` / `INVALID_IP_PATTERN` | API Key 创建、导入、编辑 IP 白名单 | Key 已存在、长度不足、字符非法、失败次数过多或 IP/CIDR 格式错误;换更长 Key、只用字母数字下划线连字符,按 CIDR 修正白名单 | | `API_KEY_REQUIRED` / `INVALID_API_KEY` | API Key 缺失、填错或用了错误 header | 使用 `Authorization: Bearer sk-...`;确认没有把 Key 放到 query,也没有多余空格/换行 | | `API_KEY_INACTIVE` / `API_KEY_DISABLED` / `API_KEY_EXPIRED` / `API_KEY_QUOTA_EXHAUSTED` / `API_KEY_RATE_5H_EXCEEDED` / `API_KEY_RATE_1D_EXCEEDED` / `API_KEY_RATE_7D_EXCEEDED` | API Key 网关鉴权/额度 | Key 被停用、过期、总额度或 5h/1d/7d 窗口用完;启用/续期/调额度或等待窗口重置 | | `GROUP_DELETED` / `GROUP_DISABLED` | Key 绑定的分组已删除或停用 | 给 Key 换可用分组;订阅型分组先确认套餐仍有效 | | `REGISTRATION_DISABLED` / `EMAIL_EXISTS` / `EMAIL_RESERVED` / `EMAIL_VERIFY_REQUIRED` / `INVALID_VERIFY_CODE` / `INVALID_CREDENTIALS` / `USER_NOT_ACTIVE` / `TOKEN_EXPIRED` / `INVALID_TOKEN` / `TOKEN_REVOKED` / `REFRESH_TOKEN_INVALID` / `REFRESH_TOKEN_EXPIRED` / `REFRESH_TOKEN_REUSED` | 注册、登录、OAuth 绑定或控制台会话 | 注册关闭、邮箱已存在/保留、验证码缺失或错误、密码错误、账号禁用、登录态过期或 token 被撤销;按提示重新验证/登录,账号禁用需联系支持 | | `PAYMENT_METHOD_DISABLED` / `BALANCE_PAYMENT_DISABLED` / `PAYMENT_DISABLED` / `INVALID_AMOUNT` / `INVALID_INPUT` / `TOO_MANY_PENDING` / `DAILY_LIMIT_EXCEEDED` / `PAYMENT_GATEWAY_ERROR` / `NO_AVAILABLE_INSTANCE` | 支付创建或通道选择 | 支付方式关闭、金额/套餐参数非法、未支付订单过多、当日限额或通道不可用;按页面范围重新下单,必要时换支付方式 | | `INVALID_RETURN_URL` / `PAYMENT_RESUME_NOT_CONFIGURED` / `INVALID_RESUME_TOKEN` / `INVALID_WECHAT_PAYMENT_RESUME_TOKEN` / `INVALID_OUT_TRADE_NO` | 支付/订单恢复 | 恢复链接可能过期、签名不匹配或订单不匹配;`out_trade_no` 为空/过长/含非法字符也会失败。回到订单页恢复/重新下单;带订单 ID、`out_trade_no` 提工单 | | `CANCEL_RATE_LIMITED` / `ORDER_ALREADY_PAID` / `INVALID_STATUS` | 取消订单 | 只允许取消 `PENDING` 订单;若上游已支付会拒绝取消;频繁取消先等冷却 | | `INVOICE_ORDER_IDS_REQUIRED` / `INVOICE_ORDER_INELIGIBLE` / `INVOICE_ALREADY_INVOICED` / `INVOICE_CANNOT_CANCEL` / `INVOICE_NOT_ISSUED` / `INVOICE_FILE_STORAGE_UNAVAILABLE` | 退款/发票 | 先看订单是否可开票、发票状态和可退金额;不要重复提交退款或上传空文件 | | `TICKET_REVISION_CONFLICT` / `TICKET_REVISION_REQUIRED` / `TICKET_NOT_EDITABLE` | 工单编辑/提交 | 刷新工单详情,基于最新 revision 重新编辑 | | `TICKET_MESSAGE_REQUIRED` / `TICKET_MESSAGE_TOO_LARGE` / `MEDIA_STORAGE_DISABLED` | 工单回复/附件 | 填正文、压缩附件或等待媒体服务恢复 | | `VERIFY_CODE_TOO_FREQUENT` / `VERIFY_CODE_MAX_ATTEMPTS` / `NOTIFY_CODE_USER_RATE_LIMIT` | 通知邮箱验证码 | 等冷却后再发;验证码 15 分钟有效,最多 5 次尝试 | | `TOO_MANY_NOTIFY_EMAILS` / `EMAIL_NOT_FOUND` | 通知邮箱管理 | 额外通知邮箱最多 3 个;删除/切换前确认邮箱存在 | | `MEDIA_FILE_REQUIRED` / `MEDIA_FILE_TOO_LARGE` / `MEDIA_SIGNATURE_EXPIRED` / `MEDIA_FORBIDDEN` / `MEDIA_NOT_FOUND` | 媒体/附件上传或下载 | 重新上传、缩小文件或刷新签名链接;不要把媒体接口当模型文件 API | | `REFRESH_TOKEN_INVALID` / `REFRESH_TOKEN_EXPIRED` / `REFRESH_TOKEN_REUSED` / `invalid refresh token` | 控制台会话刷新失败、过期或 refresh token 被复用疑似重放 | 退出后重新登录;如已点“退出所有设备”,所有设备都需要重新登录 | | `PASSWORD_RESET_DISABLED` / `EMAIL_SUFFIX_NOT_ALLOWED` | 账号注册/重置密码被系统设置限制 | 使用允许的邮箱后缀;重置密码入口关闭时联系支持 | | `CHANNEL_MONITOR_NOT_FOUND` | 渠道监控详情 | 可能是功能关闭或该渠道不可见,先看列表是否为空 | | `AI_STUDIO_DISABLED` | 控制台 AI Studio | 站点关闭或入口未开放,详见 [AI Studio](#/console-ai-studio) | | `AI_KEY_NOT_FOUND` / `AI_KEY_FORBIDDEN` / `AI_KEY_GROUP_INVALID` / `AI_LINE_MISMATCH` | AI Studio/技能运行时选择的 Key、线路或分组不匹配 | 重新选择属于当前用户、已绑定有效分组且属于该线路的 API Key | | `AI_SKILL_NOT_FOUND` / `AI_SKILL_VERSION_NOT_FOUND` / `AI_SKILL_ACCESS_DENIED` | 技能市场访问 | 技能/版本不存在、未发布或无权访问;刷新市场/已安装列表,确认当前账号和技能可见性 | | `AI_SKILL_INPUT_REQUIRED` / `AI_SKILL_NAME_REQUIRED` / `AI_SKILL_TYPE_INVALID` / `AI_SKILL_RUN_INPUT_REQUIRED` / `AI_SKILL_RUN_MODE_INVALID` | 技能创建或运行输入非法 | 补齐名称、类型、变量和运行模式;不要手改接口参数 | | `AI_SKILL_VERSION_NOT_APPROVED` / `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` / `AI_SKILL_SCRIPT_EXECUTION_UNAVAILABLE` / `AI_SKILL_SCRIPT_NOT_APPROVED` / `AI_SKILL_SCRIPT_ARTIFACT_MISMATCH` / `AI_SKILL_EXECUTION_SPEC_INVALID` / `AI_SKILL_SERVICE_UNAVAILABLE` / `AI_SKILL_BALANCE_UNAVAILABLE` / `AI_SKILL_EXECUTION_FAILED` | 技能市场 | 版本需审核通过;脚本技能普通用户暂不可创建或执行产物不匹配;余额/执行服务异常时保留 run id 和版本 id,见 [技能市场与创作者中心](#/console-skills) | ## 关于 `Recovered upstream error ...` 如果你在使用记录里看到 **"Recovered upstream error 5xx/429: ..."** 而请求其实**成功了**(状态 200),这是**好事**——说明网关检测到某个上游出错后,自动切换账号/重试并成功了。**无需处理**,这正是多账号容灾在起作用。 这类记录通常来自上游错误关联链路：先按 `request_id` 查最终用量/响应，再看 ops 里同一 `request_id` 或 `client_request_id` 附近的 upstream 记录。若最终请求失败，工单请同时带最终错误和 recovered/upstream 错误摘要；若最终成功，只在频繁出现、耗时异常或扣费异常时继续排查。 --- ## 三、HTTP 错误码速查 | 码 | 含义 | 优先处理 | |----|------|----------| | `200` | 成功(若带 "Recovered" 说明自动容灾成功,正常) | — | | `400` | 参数错误 / 超出上下文 | 检查请求体、模型名;精简输入 | | `401` / `403` | 鉴权失败 / 分组不支持 / 余额不足 | 见上"配置类" | | `404` | 地址错误 / 端点不属于该分组 | 检查 `/v1` 路径;核对[端点 × 分组](#/api-usage) | | `413` | 请求体过大 | 减少附件 / 上下文 | | `429` | 触发限速 | 降并发、稍后重试、换分组/线路 | | `502` / `503` | 上游临时不可用 / 无可用账号 | 重试,或换[网关线路](#/gateway-lines) | | `524` / `525` | 网关超时 / TLS 握手问题 | 重试;换线路 | --- ## 四、排查口诀 | 症状关键词 | 先查 | |-----------|------| | timeout / ECONNREFUSED / SSL / 证书 | 代理环境(一·1) | | command not found / 不是内部命令 | 重开终端、PATH(一·2) | | Permission denied / EACCES | 权限,加 sudo / 提升权限(一·3) | | does not support the requested model | 分组与模型不匹配(二·配置类) | | exceeds the context window | 输入太长,精简/压缩/换大窗口模型 | | No available accounts / Upstream error | 上游波动,重试或换线路(二·服务波动类) | | 余额不足 / Insufficient balance | 充值([计费与额度](#/billing)) | | 429 / usage limit | 限速,降并发或换分组 | --- > 还搞不定?带上**完整报错截图**和你的密钥**分组名**,在控制台 [api.clomio.ai](https://api.clomio.ai) 提交[工单](#/console)联系支持。 ---