# 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`(如有),方便支持按请求定位。