# 实战经验与避坑清单

这页把公开平台经验帖、网关厂商帮助文档和 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 环境变量官方页:<https://code.claude.com/docs/en/env-vars>
- LiteLLM Claude Code quickstart:<https://docs.litellm.ai/docs/tutorials/claude_responses_api>
- Requesty Claude Code 环境变量说明:<https://www.requesty.ai/blog/claude-code-environment-variables-anthropic-base-url-auth-token>
- 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 形状:<https://docs.vllm.ai/en/stable/serving/integrations/claude_code/>。

### 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/<profile>.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:<https://developers.openai.com/codex/config-basic>
- OpenAI Codex Config reference:<https://developers.openai.com/codex/config-reference>
- Portkey Codex 集成示例也使用 `model_provider` + `[model_providers.*]` + `base_url` + `env_key`:<https://docs.portkey.ai/docs/integrations/libraries/codex>

详见 [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:<https://docs.x.ai/developers/quickstart>
- xAI Web Search tool:<https://docs.x.ai/developers/tools/web-search>
- AI SDK xAI provider 对 Responses/server-side tools 的说明:<https://ai-sdk.dev/providers/ai-sdk-providers/xai>

详见 [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:<https://x.ai/news/grok-imagine-api>
- Promptfoo xAI provider 能力总览:<https://www.promptfoo.dev/docs/providers/xai/>

详见 [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 文档:<https://hermes-agent.nousresearch.com/docs/integrations/providers>
- Hermes `api_mode` 切换 issue:<https://github.com/NousResearch/hermes-agent/issues/8181>
- OpenClaw Anthropic 请求打到 OpenAI endpoint 的 issue:<https://github.com/openclaw/openclaw/issues/4889>
- OpenClaw Responses 支持相关 issue:<https://github.com/openclaw/openclaw/issues/72725>
- CC Switch README:<https://github.com/farion1231/cc-switch>

详见 [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 环境变量:<https://code.claude.com/docs/en/env-vars>
- Claude Code settings:<https://code.claude.com/docs/en/settings>
- LiteLLM Claude Code gateway:<https://docs.litellm.ai/docs/tutorials/claude_responses_api>
- vLLM Claude Code integration:<https://docs.vllm.ai/en/stable/serving/integrations/claude_code/>
- OpenAI Codex config basics:<https://developers.openai.com/codex/config-basic>
- OpenAI Codex config reference:<https://developers.openai.com/codex/config-reference>
- xAI Quickstart:<https://docs.x.ai/developers/quickstart>
- xAI Web Search:<https://docs.x.ai/developers/tools/web-search>
- xAI Rate Limits:<https://docs.x.ai/developers/rate-limits>
- xAI Grok Imagine API:<https://x.ai/news/grok-imagine-api>
- Cherry Studio custom provider:<https://docs.cherry-ai.com/docs/en-us/pre-basic/providers/zi-ding-yi-fu-wu-shang>
- Hermes providers:<https://hermes-agent.nousresearch.com/docs/integrations/providers>
- CC Switch:<https://github.com/farion1231/cc-switch>