# 简介

**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)。