# 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 处理。