# 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` 列表,不要自行拼模型详情查询路径。