---
title: Manai 教程文档
description: Manai Codex、Claude、Grok、生图与 Hermes Agent 教程文档
---

# Manai 教程文档

请选择需要查看的教程：

- [Codex 教程](./cc-switch-guide.html#codex-guide)
- [Claude 教程](./cc-switch-guide.html#claude-guide)
- [Grok 教程](./cc-switch-guide.html#grok-guide)
- [生图教程](./cc-switch-guide.html#shengtu-skill)
- [Hermes 教程](./cc-switch-guide.html#hermes-guide)

---

# Codex 接入 CC-Switch 教程

本文将引导你使用 CC-Switch 配置 Manai 中转 API。按照步骤完成后，即可在 Codex 中使用 Manai 提供的 API 服务。

## 准备工作

开始前，请确认你已经准备好以下内容：

- 一个可正常登录的 Manai 账号
- 可访问的 Manai API Key
- 已安装或准备安装 CC-Switch
- 已安装 Codex 客户端

## 一、注册并登录 Manai

打开 Manai 网站，注册并登录你的账号。

登录后，进入控制台，准备创建用于调用 API 的访问令牌。

![Manai 控制台令牌列表](./assets/cc-switch-guide/01-manai-token-list.png)

## 二、创建 API 令牌

在 Manai 控制台中创建新的 API 令牌。

创建时请注意：

- 根据你的实际用途选择对应分组。
- 创建完成后，请复制并妥善保存密钥。
- API Key 只展示一次时，请及时保存，避免后续无法查看。

后续在 CC-Switch 中填写的 `Api Key`，就是这里创建的令牌密钥。

![创建令牌并选择分组](./assets/cc-switch-guide/02-create-token-group.png)

## 三、下载 CC-Switch

请下载 CC-Switch Windows 便携版：

[下载 CC-Switch v3.16.1](https://github.com/farion1231/cc-switch/releases/download/v3.16.1/CC-Switch-v3.16.1-Windows-Portable.zip)

下载完成后，解压压缩包，并打开 CC-Switch 程序。

如果后续软件版本更新，也可以前往 CC-Switch 的 Release 页面下载新版。

## 快速方式：一键导入 CC-Switch

网页版教程顶部已经提供“一键导入 CC-Switch”按钮：

```text
https://api.manai8.xyz/docs/cc-switch-guide.html#quick-import
```

打开后粘贴你在 Manai 控制台创建的 API Key，点击按钮即可把 Manai Provider 添加到 CC-Switch。

如果浏览器没有唤起 CC-Switch，请确认 CC-Switch 已安装并已打开；仍无法导入时，再按下面的手动步骤配置。

## 四、添加 Manai 配置

打开 CC-Switch 后，新增一个配置，并按以下信息填写：

![打开 CC-Switch 设置](./assets/cc-switch-guide/03-open-cc-switch-settings.png)

![新增供应商配置](./assets/cc-switch-guide/04-add-cc-switch-provider.png)

在供应商类型中选择自定义配置。

![选择自定义供应商](./assets/cc-switch-guide/05-select-custom-provider.png)

| 配置项 | 填写内容 |
| --- | --- |
| 名称 | Manai |
| Api Key | 你在 Manai 控制台创建的令牌密钥 |
| Api 请求地址 | `https://api.manai8.xyz/v1` |

请确认 API 请求地址填写完整，末尾包含 `/v1`。

![填写 Manai 配置信息](./assets/cc-switch-guide/06-fill-manai-config.png)

## 五、启用配置

配置保存后，在 CC-Switch 中启用刚刚创建的 Manai 配置。

![启用 Manai 配置](./assets/cc-switch-guide/07-enable-manai-config.png)

启用前建议检查：

- API Key 是否复制完整。
- API 请求地址是否为 `https://api.manai8.xyz/v1`。
- 当前启用的配置是否为 Manai。

## 六、重启 Codex

配置启用后，请关闭并重新打开 Codex。

重启完成后，Codex 会读取新的 API 配置。此时即可开始使用 Manai 中转服务。

## 常见问题

### Api Key 应该填什么？

填写你在 Manai 控制台创建的 API 令牌密钥。

不要填写账号密码，也不要填写其他平台的密钥。

### API 请求地址应该填什么？

请填写：

```text
https://api.manai8.xyz/v1
```

注意地址需要包含 `https://` 和末尾的 `/v1`。

### 配置后没有生效怎么办？

可以按以下顺序检查：

1. 确认 CC-Switch 中已启用 Manai 配置。
2. 确认 API Key 没有多复制空格或遗漏字符。
3. 确认 API 请求地址填写正确。
4. 关闭并重新打开 Codex。
5. 如果仍无法使用，请重新创建令牌后再配置一次。

## 安全提醒

API Key 是你的访问凭证，请勿公开分享。

请不要将 API Key 发布到聊天群、论坛、公开仓库或截图中。如发现密钥泄露，请立即在 Manai 控制台删除旧令牌，并重新创建新的令牌使用。

> **Codex 教程完成**：本教程到这里结束。下面的 Grok 教程是独立的配置流程，请按需选择。
>
> [返回教程选择](./cc-switch-guide.html#tutorial-picker-title) ｜ [查看 Grok 教程](./cc-switch-guide.html#grok-guide)

---

# Claude 接入 CC-Switch 教程

本章节介绍如何创建专用于 Claude 的 Manai 令牌，并在 CC-Switch 中完成供应商配置、本地路由和 Claude 路由设置。完成后，CC-Switch 中的 Claude 供应商配置应显示为“使用中”，本地路由应显示为运行状态。

## 第一步：在网站创建 Claude 令牌

登录 Manai 网站并进入控制台，在左侧选择“令牌管理”，然后点击“添加令牌”。

1. 令牌名称建议填写 `claude`，方便后续识别。
2. 分组请选择你账号中可使用 Claude 的分组，具体名称以控制台实际显示为准。
3. 保存令牌后，复制以 `sk-` 开头的密钥，下一步需要粘贴到 CC-Switch。

![在 Manai 控制台的令牌管理页面添加 Claude 令牌](./assets/claude-guide/01-create-claude-token.png)

## 第二步：在 CC-Switch 添加 Claude 配置

打开 CC-Switch，切换到图中带显示器标识的 Claude 配置页，然后点击右上角的“+”按钮新增供应商。

![在 CC-Switch 中切换到 Claude 配置页并点击加号](./assets/claude-guide/02-add-claude-provider.png)

在新增供应商页面按下表填写：

| 配置项 | 填写内容 |
| --- | --- |
| 供应商名称 | `Claude` |
| API Key | 第一步在 Manai 网站创建的令牌密钥（网站密钥） |
| 请求地址 | `https://api.manai8.xyz` |
| 官网链接、备注 | 可选，不需要时可以留空 |

> **重要：**这里使用的是 Claude 路由，请求地址必须填写 `https://api.manai8.xyz`，后面不需要加 `/v1`，也不要以斜杠结尾。

![填写 Claude 供应商名称、Manai API Key 和请求地址](./assets/claude-guide/03-fill-claude-config.jpg)

### 配置 API 格式与模型映射

继续向下找到“API 格式”和“模型映射”区域，按以下顺序设置：

1. API 格式选择 `Anthropic Messages (原生)`。
2. 点击“获取模型列表”，等待 CC-Switch 读取可用模型。
3. 在 Sonnet、Opus、Haiku 三个模型角色中，将菜单显示名和实际请求模型分别设置为：
   - Sonnet → `claude-fable-5`
   - Opus → `claude-opus-4-8`
   - Haiku → `claude-opus-4-7`
   建议勾选“声明支持 1M”。

> **不要遗漏模型映射：**三个模型角色都要配置完成。实际请求模型须与本站名称完全一致。

![选择 Anthropic Messages 原生并完成模型映射](./assets/claude-guide/04-anthropic-messages-model-mapping.jpg)

完成模型映射后再保存配置，然后返回 CC-Switch 主页面。

## 第三步：应用配置并开启本地路由

在供应商列表中找到刚创建的 `Claude` 配置，点击“应用”或“使用”。当该配置显示“使用中”后，打开页面左上方的本地路由开关，使开关保持绿色。

![在 CC-Switch 中应用 Claude 配置并打开本地路由](./assets/claude-guide/05-apply-local-route.png)

## 第四步：在设置中开启 Claude 路由

点击 CC-Switch 左上角的设置按钮，进入“路由”页面并展开“本地路由”。确认路由总开关已开启，然后在“路由启用”区域打开 `Claude` 开关。

> **说明：**开启 Claude 路由是为了让 Claude 客户端的请求经过本地路由，实际使用的是你刚才选中的 Claude 供应商配置。Codex 和 Gemini 路由无需同时开启。

![在 CC-Switch 设置的路由页面开启 Claude 路由](./assets/claude-guide/06-enable-claude-route.png)

## 第五步：重启客户端并验证

1. 完全退出正在运行的 Claude 客户端，再重新打开。
2. 发送一条简单消息，确认能够正常返回内容。
3. 返回 CC-Switch，确认 `Claude` 仍显示“使用中”，本地路由仍处于运行状态。

## Claude 配置常见问题

### 提示 401 或认证失败

请重新复制网站令牌，确认没有遗漏字符或多复制空格，并确认该令牌仍为启用状态、分组具备 Claude 模型权限。

### 提示 404 或地址不可用

请检查请求地址是否为 `https://api.manai8.xyz`。Claude 路由不要填写 `https://api.manai8.xyz/v1`。

### 提示模型不存在 / model not found

请确认三个角色的实际请求模型分别为 `claude-fable-5`、`claude-opus-4-8`、`claude-opus-4-7`，且与本站名称完全一致。

### 配置后没有生效

依次确认 Claude 配置已应用、本地路由开关已打开、设置中的 Claude 路由已打开，API 格式为 Anthropic Messages (原生)，然后完全退出并重新启动 Claude 客户端。

### API 格式选错会怎样

若误选成 OpenAI Responses API 等其它格式，可能导致鉴权失败或模型不可用。请改回 `Anthropic Messages (原生)` 后重新获取模型列表并保存。

### 令牌安全提醒

Claude 令牌属于账号访问凭证，请勿发送给他人或放入公开截图。怀疑令牌泄露时，请立即在 Manai 控制台删除旧令牌并重新创建。

## 配置速查

```text
CC-Switch 页面 ：Claude 配置页
供应商名称     ：Claude
API Key        ：sk-你的本站令牌
请求地址       ：https://api.manai8.xyz   （不要 /v1）
API 格式       ：Anthropic Messages (原生)
模型映射       ：
  Sonnet → claude-fable-5
  Opus   → claude-opus-4-8
  Haiku  → claude-opus-4-7
本地路由       ：开启
Claude 路由    ：开启
```

> **Claude 教程完成**：本教程到这里结束。下面的 Grok 教程是另一套独立内容。
>
> [返回教程选择](./cc-switch-guide.html#tutorial-picker-title) ｜ [查看 Grok 教程](./cc-switch-guide.html#grok-guide)

---


# Grok 接入 CC-Switch 教程

本章节介绍如何创建专用于 Grok 的 Manai 令牌，并在 CC-Switch 中完成供应商配置、本地路由和 Claude 路由设置。完成后，CC-Switch 中的 `grok` 配置应显示为“使用中”，本地路由应显示为运行状态。

## 第一步：在网站创建 Grok 令牌

登录 Manai 网站并进入控制台，在左侧选择“令牌管理”，然后点击“添加令牌”。

1. 令牌名称建议填写 `grok`，方便后续识别。
2. 分组请选择你账号中可使用 Grok 的分组，具体名称以控制台实际显示为准。
3. 保存令牌后，复制以 `sk-` 开头的密钥，下一步需要粘贴到 CC-Switch。

![在 Manai 控制台的令牌管理页面添加 Grok 令牌](./assets/grok-guide/01-create-grok-token.png)

## 第二步：在 CC-Switch 添加 Grok 配置

打开 CC-Switch，切换到图中带显示器标识的 Claude 配置页，然后点击右上角的“+”按钮新增供应商。

![在 CC-Switch 中切换到 Claude 配置页并点击加号](./assets/grok-guide/02-add-grok-provider.png)

在新增供应商页面按下表填写：

| 配置项 | 填写内容 |
| --- | --- |
| 供应商名称 | `grok`，也可以填写便于自己识别的名称 |
| API Key | 第一步在 Manai 网站创建的令牌密钥 |
| 请求地址 | `https://api.manai8.xyz` |
| 官网链接、备注 | 可选，不需要时可以留空 |

> **重要：**这里使用的是 Claude 路由，请求地址必须填写 `https://api.manai8.xyz`，末尾不要添加 `/v1`，也不要以斜杠结尾。

![填写 Grok 供应商名称、Manai API Key 和请求地址](./assets/grok-guide/03-fill-grok-config.png)

### 配置 API 格式与模型映射

继续向下找到“API 格式”和“模型映射”区域，按以下顺序设置：

1. API 格式选择 `OpenAI Responses API（需开启路由）`。
2. 点击“获取模型列表”，等待 CC-Switch 读取可用模型。
3. 在 Sonnet、Opus、Haiku 三个模型角色中，将“实际请求模型”全部选择为 `grok-4.5`；菜单显示名也可以填写 `grok-4.5`。

> **不要遗漏模型映射：**三个模型角色都要映射到 `grok-4.5`。API 格式提示“需开启路由”是正常的，继续按第三、第四步开启即可。

![选择 OpenAI Responses API 并将模型角色映射到 grok-4.5](./assets/grok-guide/04-model-mapping.png)

完成模型映射后再保存配置，然后返回 CC-Switch 主页面。

## 第三步：应用配置并开启本地路由

在供应商列表中找到刚创建的 `grok` 配置，点击“应用”或“使用”。当该配置显示“使用中”后，打开页面左上方的本地路由开关，使开关保持绿色。

![在 CC-Switch 中应用 Grok 配置并打开本地路由](./assets/grok-guide/04-apply-local-route.png)

## 第四步：在设置中开启 Claude 路由

点击 CC-Switch 左上角的设置按钮，进入“路由”页面并展开“本地路由”。确认路由总开关已开启，然后在“路由启用”区域打开 `Claude` 开关。

> **说明：**开启 Claude 路由是为了让 Claude 客户端的请求经过本地路由，实际使用的仍是你刚才选中的 Grok 供应商配置。Codex 和 Gemini 路由无需同时开启。

![在 CC-Switch 设置的路由页面开启 Claude 路由](./assets/grok-guide/05-enable-claude-route.png)

## 第五步：重启客户端并验证

1. 完全退出正在运行的 Claude 客户端，再重新打开。
2. 发送一条简单消息，确认能够正常返回内容。
3. 返回 CC-Switch，确认 `grok` 仍显示“使用中”，本地路由仍处于运行状态。

## Grok 配置常见问题

### 提示 401 或认证失败

请重新复制网站令牌，确认没有遗漏字符或多复制空格，并确认该令牌仍为启用状态。

### 提示 404 或地址不可用

请检查请求地址是否为 `https://api.manai8.xyz`。Claude 路由不要填写 `https://api.manai8.xyz/v1`。

### 配置后没有生效

依次确认 Grok 配置已应用、本地路由开关已打开、设置中的 Claude 路由已打开，然后完全退出并重新启动目标客户端。

### 令牌安全提醒

Grok 令牌属于账号访问凭证，请勿发送给他人或放入公开截图。怀疑令牌泄露时，请立即在 Manai 控制台删除旧令牌并重新创建。

> **Grok 教程完成**：本教程到这里结束。下面的生图教程是另一套独立内容，不属于 Grok 配置流程。
>
> [返回教程选择](./cc-switch-guide.html#tutorial-picker-title) ｜ [查看生图教程](./cc-switch-guide.html#shengtu-skill)

---

# Manai8 生图 Skill 使用教程

本文介绍如何在 Codex 中安装并使用 Manai8 生图 Skill。按照本文完成配置后，你可以直接在 Codex 中通过自然语言生成图片，或基于已有图片进行修改。

## 一、适用场景

Manai8 生图 Skill 适合以下使用场景：

- 文生图：输入一段图片描述，生成一张新图片。
- 改图：上传或指定一张原图，并描述需要修改的内容。
- 海报与素材制作：生成产品图、宣传海报、头像、插画、封面等视觉素材。

该 Skill 默认使用 Manai8 图片接口：

| 项目 | 默认值 |
| --- | --- |
| 接口地址 | `https://api.manai8.xyz` |
| 默认模型 | `gpt-image-2` |
| 默认尺寸 | `1024x1024` |
| 默认格式 | `png` |
| 默认质量 | `low` |

实际请求会发送到：

```text
https://api.manai8.xyz/v1/images/generations
https://api.manai8.xyz/v1/images/edits
```

## 二、下载 Skill 包

请先下载 Manai8 生图 Skill 包：

[下载 Manai8 生图 Skill 安装包](./assets/shengtu-skill/manai8-shengtu-skill-guide-package.zip)

下载后解压压缩包。解压后你会看到：

```text
README_Manai8_Shengtu_Skill.md
shengtu-skill/
```

其中 `shengtu-skill` 文件夹才是真正需要安装到 Codex 的 Skill 文件夹。请复制整个文件夹，不要只复制里面的单个文件。

## 三、准备 API Key

使用前请准备一把可用于 Manai8 生图接口的 API Key。

请注意：

- API Key 是你的访问凭证，请勿发给他人。
- 不要把 API Key 写进公开文档、截图、聊天群或公开仓库。
- 如果怀疑 API Key 已泄露，请立即在 Manai 控制台删除旧 Key，并重新创建新的 Key。

## 四、安装到 Codex

将解压后的 `shengtu-skill` 文件夹复制到 Codex 的 skills 目录。

Windows 通常是：

```text
C:\Users\你的用户名\.codex\skills\shengtu-skill
```

macOS 通常是：

```text
/Users/你的用户名/.codex/skills/shengtu-skill
```

复制完成后，请重启 Codex，让 Codex 重新加载 Skill。

## 五、保存 Manai8 生图 API Key

打开终端，进入 `shengtu-skill` 文件夹。

Windows 示例：

```powershell
cd C:\Users\你的用户名\.codex\skills\shengtu-skill
python scripts\generate_image.py --save-api-key "你的Manai8_API_KEY"
```

macOS 示例：

```bash
cd /Users/你的用户名/.codex/skills/shengtu-skill
python scripts/generate_image.py --save-api-key "你的Manai8_API_KEY"
```

看到类似下面的提示，即表示保存成功：

```text
Saved image API key to ...
```

这个操作只会保存生图 Skill 自己使用的 Key，不会修改你的 `OPENAI_API_KEY`。

## 六、让 Codex 生成图片

安装并保存 API Key 后，可以直接在 Codex 中提出生图需求。

示例一：

```text
用 shengtu-skill 生成一张图片：一只白色猫咪坐在窗边，阳光照进来，写实摄影风格，保存为 cat.png
```

示例二：

```text
用 shengtu-skill 生成一张 1024x1024 的产品海报，主体是一瓶香水，干净背景，高级商业摄影风格，保存为 perfume.png
```

为了获得更稳定的效果，建议描述中包含：

- 主体：画面中最重要的对象。
- 背景：图片所在环境。
- 风格：写实、插画、海报、商业摄影等。
- 尺寸：例如 `1024x1024`。
- 文件名：例如 `poster.png`。

推荐模板：

```text
用 shengtu-skill 生成一张 1024x1024 的图片：主体是【你要的东西】，背景是【背景】，风格是【写实/插画/海报/摄影】，画面干净清晰，保存为【文件名.png】
```

## 七、使用 Skill 修改图片

如需改图，请先准备一张原图，例如 `input.png`。

然后在 Codex 中说明要修改什么：

```text
用 shengtu-skill 修改 input.png：保持主体不变，把背景换成干净的白色影棚背景，保存为 edited.png
```

也可以这样写：

```text
用 shengtu-skill 修改 input.png：让图片更明亮、更清晰，人物不要变形，保存为 fixed.png
```

改图时建议明确说明哪些内容需要保留、哪些内容需要变化。例如“保持人物不变”“只替换背景”“不要改变商品外观”等。

## 八、常用尺寸

常用尺寸如下：

| 尺寸 | 适用场景 |
| --- | --- |
| `1024x1024` | 方图、头像、常规素材 |
| `1536x1024` | 横图、横版海报 |
| `1024x1536` | 竖图、竖版海报 |
| `3840x2160` | 4K 横图 |
| `2160x3840` | 4K 竖图 |

请使用 `宽x高` 的格式填写尺寸，例如 `1024x1024`。不建议只写 `1K`、`2K` 或 `4K`。

## 九、也可以直接用命令生成

如果你不想通过 Codex 对话，也可以在终端中直接运行脚本。

文生图示例：

```bash
python scripts/generate_image.py \
  --prompt "A clean product poster with clear subject and soft studio lighting" \
  --size 1024x1024 \
  --out poster.png
```

改图示例：

```bash
python scripts/generate_image.py \
  --mode edit \
  --prompt "Improve the lighting and keep the main subject unchanged" \
  --image input.png \
  --size 1024x1024 \
  --out edited.png
```

## 十、常见问题

### 提示 Missing image API key

说明还没有保存生图 API Key。请重新运行：

```bash
python scripts/generate_image.py --save-api-key "你的Manai8_API_KEY"
```

### 提示 HTTP 401

通常是 API Key 不正确、已过期、余额不足，或该 Key 没有生图权限。请检查 Key 是否复制完整，并确认账号状态正常。

### 提示输入图片不存在

请检查图片路径是否正确。如果你写的是：

```text
input.png
```

那么这张图片必须真实存在于当前文件夹中。

### 图片生成时间较长

图片生成可能需要几十秒。高分辨率、复杂提示词、多人场景或精细商品图通常会更慢，请耐心等待。

### 如何查看 Key 保存位置

在 `shengtu-skill` 文件夹里运行：

```bash
python scripts/generate_image.py --show-config-path
```

### 如何删除已保存的 Key

在 `shengtu-skill` 文件夹里运行：

```bash
python scripts/generate_image.py --clear-api-key
```

## 十一、安全建议

- API Key 只应保存在自己的设备中。
- 不要将 API Key 发给他人或上传到公开平台。
- 生成商业素材前，请自行确认素材用途、版权要求和平台规则。
- 如果需要给多人使用，建议为不同人员创建不同的 API Key，便于后续管理和停用。

> **生图教程完成**：生图教程到这里结束。
>
> [返回教程选择](./cc-switch-guide.html#tutorial-picker-title) · [查看 Hermes 教程](./cc-switch-guide.html#hermes-guide)

---

# Hermes Agent（爱马仕）接入教程

通过本站中转，即可在 Hermes Agent 中使用 GPT、Claude 等模型。

**本站地址：** https://api.manai8.xyz

## 一、获取 API Key

1. 打开 https://api.manai8.xyz 并登录账号
2. 进入 **令牌** 页面，点击 **添加令牌**
3. 创建后复制密钥（形如 `sk-xxxxxxxx`），请妥善保存

> 若还没有账号，请先在本站注册并完成充值。

## 二、在 Hermes Agent 中配置

1. 打开 Hermes Agent，进入 **设置 / Settings**（或模型 / Provider 相关页面）
2. 提供商类型选择：**OpenAI Compatible**（或 Custom OpenAI / OpenAI API）
3. 按下面填写：

| 配置项 | 填写内容 |
| --- | --- |
| **API Base URL** | `https://api.manai8.xyz/v1` |
| **API Key** | 本站令牌，例如 `sk-xxxxxxxx` |
| **Model** | 本站已开通的模型名（见下方说明） |

4. 保存设置，发送一条消息测试即可

## 三、模型名称

模型名须与本站 **完全一致**（可在本站「模型」或令牌可用模型列表中查看）。

常用示例（以你账号实际开通的为准）：

- GPT 系列：如 `gpt-4o`、`gpt-4o-mini`
- Claude 系列：如 `claude-sonnet-4`、`claude-3-5-sonnet` 等

具体可用模型以本站页面显示为准。

## 四、常见问题

### 1. 提示 401 / 密钥无效

检查 Key 是否完整复制、额度是否用尽、令牌是否被禁用。

### 2. 提示 404 / 接口不存在

Base URL 请使用：`https://api.manai8.xyz/v1`

若仍报错，可去掉末尾 `/v1` 再试：`https://api.manai8.xyz`

### 3. 提示模型不存在

模型名填错，或不在你令牌的可用模型范围内。请到本站核对准确名称。

### 4. 能聊天但工具调用失败

请换用支持工具调用（function call）的模型，如 GPT-4o、Claude Sonnet 等。

## 五、配置速查

```text
Base URL：https://api.manai8.xyz/v1
API Key ：sk-你的本站令牌
Model   ：本站模型列表中的名称
```

站点：https://api.manai8.xyz  
有问题请联系本站客服。

> **Hermes 教程完成**：教程到这里结束，以上为 Manai 教程文档的全部内容。
>
> [返回教程选择](./cc-switch-guide.html#tutorial-picker-title)