在 VSCode 中配置 GUI for Grok Build & Muse Code 插件调用 API2CN 的 grok-4.7 模型指引

本文档介绍如何在 Visual Studio Code (VSCode) 中安装 GUI for Grok Build & Muse Code 插件，并通过中转服务商 api2cn.com 接入并调用 grok-4.7 模型的完整步骤。

一、前期准备

在开始配置前，请确保准备好以下信息：

1. 已安装最新版 VSCode（建议保持最新以保证插件兼容性）。
2. api2cn 平台 API Key：
   • 登录 api2cn.com 控制台。
   • 在“API 密钥”页面生成并复制一个有效的 Grok 分组的API Key（格式通常形如 sk-xxxxxx）。
   • 确保账户内有足够的调用额度。
3. 接口地址与模型名称：
   • Base URL：https://api.api2cn.com/v1
   • Model Name：grok-4.7

二、安装插件

1. 打开 VSCode。
2. 点击左侧活动栏的 扩展 (Extensions) 图标（快捷键：Ctrl + Shift + X / macOS 下为 Cmd + Shift + X）。
3. 在搜索框中输入：

   1	GUI for Grok Build & Muse Code

4. 在搜索结果中找到该插件，点击 安装 (Install) 按钮。
5. 安装完成后，左侧活动栏会出现对应的插件图标（或通过命令面板调出）。

三、插件配置步骤

方法一：通过CC Switch 配置

打开 CC Switch，顶部应用切换器切到 Grok（Grok Build）面板
点右上角 + / Add Provider，选 Custom（自定义）或 Grok/xAI 预设
填配置：供应商名称、API 地址（https://api.api2cn.com/v1）、API Key、模型配置，然后保存
回到供应商列表，选中刚加的 → Enable
重启终端或 Grok CLI 使生效（Claude Code 才支持热切换，Grok 要重启）
4. 点击 保存 (Save)。

方法二：通过插件设置界面（GUI 界面）

1. 点击左侧活动栏的 GUI for Grok Build & Muse Code 图标打开插件交互面板。
2. 找到面板中的 设置 (Settings / 齿轮图标)。
3. 依次填写/修改以下参数：
   • API Provider / Type：选择 Custom（自定义）或兼容的 OpenAI Compatible。
   • Base URL / API Endpoint：

     1	https://api.api2cn.com/v1

     注意：部分插件默认会自动拼接 /chat/completions，请确保填入的 Base URL 结尾保留或去除末尾斜杠符合插件提示（推荐填 https://api.api2cn.com/v1）。

   • API Key：粘贴您在 api2cn 获取的 sk-xxxxxxxx 密钥。
   • Model (模型名称)：输入或选择：

     1

     grok-4.7

4. 点击 保存 (Save)。

四、验证与使用

1. 打开插件对话窗口或右键代码选区唤起插件功能。
2. 发送一段简单的测试提示词，例如：

   1	请用 Python 写一个快速排序函数，并附带简要说明。

3. 观察回复：
   • 若能正常流式输出且内容准确，说明中转服务与模型连接成功。
   • 可在 api2cn.com 控制台的“调用日志/额度消耗”中查看是否有对应的 grok-4.7 请求记录。

五、常见问题与排查

本站已内置视频中心，可简化调用过程。

前置准备

创建“Grok-Heavy号池组”分组或者“Seedance视频模型”分组密钥后即可调用。视频生成为异步任务，推荐调用流程如下：

1. 提交任务，保存返回的 task_id
2. 轮询查询任务状态
3. 任务完成后下载视频

⚠️ 注意：请勿对同一个任务重复提交。

接口列表

分辨率与计费规则

按网站货币计价，下表价格均为每个计费秒的价格，并非整段视频的固定打包价格。

• 扣费保障：任务失败按原扣费全额退回。
• 免费查询：查询状态与下载视频不会重复扣费。

模型对比与定价

参考网站模型广场

注：参考视频时长由服务端读取，客户端自填估计值无法改变扣费。

调用代码示例

1. 创建文生视频任务

1
2
3
4
5
6
7
8
9
10
11

curl https://api.api2cn.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Seedance-2.0",
    "prompt": "蓝色陶瓷球的产品特写，镜头缓慢环绕，光线自然",
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

2. 上传参考素材

每次仅能上传一个文件，kind 可选用 image、video 或 audio。

• 文件规格限制：

• 图片：支持 PNG / JPEG / WebP，单张最大 20MB

• 音频：单文件最大 20MB

• 视频：单文件最大 64MB

• 链接时效：返回的授权链接有效期为 24 小时，请勿公开转发，并在过期前提交任务。

1
2
3
4
5

curl https://api.api2cn.com/v1/video-assets \
  -H "Authorization: Bearer $API_KEY" \
  -F "kind=video" \
  -F "file=@motion.mp4"

3. 创建全能参考任务

将素材上传接口返回的链接填入 referenceImages、referenceVideos、referenceAudios 数组中（也支持其他可公开读取的 HTTPS 地址，不支持本地路径或 blob 链接）。提示词中可使用 @图1、@视频1、@音频1 引用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl https://api.api2cn.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Seedance-2.5",
    "prompt": "画面主体参考@图1，运镜参考@视频1，节奏参考@音频1",
    "ratio": "16:9",
    "duration": 5,
    "resolution": "480p",
    "referenceImages": ["YOUR_UPLOADED_IMAGE_HTTPS_URL"],
    "referenceVideos": ["YOUR_UPLOADED_VIDEO_HTTPS_URL"],
    "referenceAudios": ["YOUR_UPLOADED_AUDIO_HTTPS_URL"]
  }'

📌 细节说明：

• 画面比例 (ratio)：支持 21:9、16:9、4:3、1:1、3:4、9:16、Auto。
• 首尾帧模式：使用 first_image，可选 last_image，并配合 ratio=Auto（不要与全能参考数组混用）。

4. 查询状态与下载视频

获取 task_id 后建议每 3–5 秒查询一次状态。取得 task_id 后应轮询查询原任务，请勿重复创建。其他用户无法使用其自己的密钥查询或下载你的任务。

• queued / in_progress：处理中，请继续等待
• completed：任务完成，可以发起下载
• failed：任务失败，可查看错误和退款记录

1
2
3
4
5
6
7
8
9

# 查询任务状态（将 task_xxx 替换为实际返回的 task_id）
curl https://api.api2cn.com/v1/videos/task_xxx \
  -H "Authorization: Bearer $API_KEY"

# 状态变为 completed 后下载视频
curl -fL https://api.api2cn.com/v1/videos/task_xxx/content \
  -H "Authorization: Bearer $API_KEY" \
  -o result.mp4

异步生图通过“提交即返回、后台排队渲染”彻底规避长请求超时，是支持高分辨率（2K/4K）与高并发大图渲染的高效、稳定性方案。本指引适用于解决批量生图超时与网关报错

API2CN 异步生图接口指引

本文档介绍了如何在使用 智惠API 时，对接 api2cn 提供的异步生图服务。通过异步任务机制，可以有效避免高分辨率或复杂提示词生成过程中的超时问题。

1. 基础配置信息

• API Base URL: https://api.api2cn.com
• 默认模型 (Model): gpt-image-2
• 支持分辨率: 1K / 2K / 4K
• 存储桶与图片访问:
  • URL 规则: https://s3.api2cn.com/images/{task_id-0}.png
  • 有效时间: 24小时（生成的图片链接在存储桶中仅保留 24 小时，请及时下载或转存）

2. 接口调用与 cURL 示例

2.1 提交任务 (Submit)

向服务器提交异步生图任务。接口会立即返回一个包含 task_id 的响应，代表任务已进入后台队列。

• 请求方式: POST

• 请求地址: https://api.api2cn.com/v1/images/generations

• cURL 示例:

  1 2 3 4 5 6 7 8

  curl -X POST "https://api.api2cn.com/v1/images/generations" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "A futuristic city with flying cars at sunset, cyberpunk style", "size": "2K" }'

• 响应示例:

  1 2 3 4 5 6 7 8

  { "code": 200, "message": "Task submitted successfully", "data": { "task_id": "task_abc123xyz789", "status": "processing" } }

2.2 轮询任务状态 (Polling)

通过上一步获取的 task_id 定期向后端查询生成进度，直至任务状态变为 completed。

• 请求方式: GET

• 请求地址: https://api.api2cn.com/v1/tasks/{task_id}

• cURL 示例:

  1 2	curl -X GET "https://api.api2cn.com/v1/tasks/task_abc123xyz789" \ -H "Authorization: Bearer YOUR_API_KEY"

• 响应示例 (处理中):

  1 2 3 4 5 6 7 8

  { "code": 200, "data": { "task_id": "task_abc123xyz789", "status": "processing", "progress": "50%" } }

• 响应示例 (已完成):

  1 2 3 4 5 6 7

  { "code": 200, "data": { "task_id": "task_abc123xyz789", "status": "completed" } }

2.3 获取与下载结果 (Retrieve)

当轮询确认任务完成后，即可根据存储桶规则拼凑链接，直接获取或下载最终生成的图片。

• 图片 URL 拼凑规则: https://s3.api2cn.com/images/{task_id-0}.png
• cURL 示例 (下载图片到本地):

  1 2	curl -X GET "https://s3.api2cn.com/images/task_abc123xyz789.png" \ --output generated_image.png

3. 注意事项

1. 时效性：图片在存储桶中的有效期为 24小时，请务必在此时间内完成转存或下载。
2. 轮询策略：建议轮询间隔设为 3~5 秒，避免高频请求触发限流。
3. 分辨率确认：提交任务时请严格对照 1K / 2K / 4K 标准参数填写。

本站已内置生图中心，可大幅简化生图过程。如果有大批量生图需求，请参考 异步生图 指引

前置准备

`生图能力 模型属于 Image-2出图组、Image-2 Adobe原生4K渠道、Grok-Heavy号池组（使用grok-imagine-image-2.0模型） 分组，使用前需要创建相应的分组KEY。分组选择 Image-2出图组、Image-2 Adobe原生4K渠道、Grok-Heavy号池组 三者之一。

调用方式概览

OpenAI 官方文档将图片相关能力分为 Responses API、Images API、Chat Completions API 三类。对于 gpt-image-2，出图请优先使用 Images API。

Images API 调用说明（推荐）

Images API 分为文生图和图片编辑/图生图两个接口：

• 文生图：POST [https://api.api2cn.com/v1/images/generations](https://api.api2cn.com/v1/images/generations)
• 图片编辑 / 图生图：POST [https://api.api2cn.com/v1/images/edits](https://api.api2cn.com/v1/images/edits)

💡 推荐用法：单纯生成图片使用 /v1/images/generations；如需上传参考图进行编辑/改图，使用 /v1/images/edits。

1. 文生图：/v1/images/generations

接口实例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl --location 'https://api.api2cn.com/v1/images/generations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer 你的生图分组key' \
  --header 'Accept: */*' \
  --header 'Host: api.api2cn.com' \
  --header 'Connection: keep-alive' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫戴着橙色围巾抱着水獭，温暖插画风格",
    "size": "3840x2160",
    "quality": "high",
    "output_format": "png",
    "response_format": "url",
    "n": 1
  }'

文生图参数说明

2. 图片编辑 / 图生图：/v1/images/edits

/v1/images/edits 使用 multipart/form-data 格式上传图片。image 为二进制图片文件，prompt 写明修改需求。

接口实例

1
2
3
4
5
6
7
8
9
10
11

curl --location 'https://api.api2cn.com/v1/images/edits' \
  --header 'Authorization: Bearer 你的生图分组key' \
  --header 'Accept: */*' \
  --form 'model="gpt-image-2"' \
  --form 'prompt="把图片里的主体保留，在右上角加一枚红色小印章，印章上写 DEMO"' \
  --form 'image=@"/path/to/your-image.jpg"' \
  --form 'size="1024x1024"' \
  --form 'quality="high"' \
  --form 'output_format="png"' \
  --form 'response_format="url"'

图片编辑参数说明

📌 局部修改提示：如需局部修改，可额外上传 mask（建议 PNG 图片），透明区域代表允许模型重点修改的位置；若不传 mask，模型将根据提示词对整张图进行编辑。

通用说明

1. 尺寸与质量

常用尺寸（Popular sizes）

• 1024x1024：正方形
• 1536x1024：横向
• 1024x1536：纵向
• 2048x2048：2K 正方形
• 2048x1152：2K 横向
• 3840x2160：4K 横向
• 2160x3840：4K 纵向
• auto：自动（默认）

尺寸限制（Size constraints）

• 最大边长：必须 $\le 3840$ 像素
• 整倍数要求：宽和高都必须是 16 的倍数
• 宽高比限制：长边与短边比例不能超过 3:1
• 总像素限制：介于 655,360 至 8,294,400 像素之间

质量选项（Quality options）

• low：低质量
• medium：中等质量
• high：高质量
• auto：自动（默认）

2. 参数选择建议

1. 最简文生图：仅传 model 和 prompt，并把 n 设为 1。
2. 提高清晰度：添加 "quality": "high"。
3. 指定生成尺寸：添加 size 参数（如 "1024x1024" 或 "1536x1024"）。
4. 获取图片链接：保留默认的 "response_format": "url"。
5. 程序直接读取 Base64：设置 "response_format": "b64_json"。
6. 批量生成限制：请勿将 n 设置为大于 1 的值，生成多张图片请使用循环单独发起请求。

3. 返回结果

默认返回（图片下载地址 url）

1
2
3
4
5
6
7
8
9
10

{
  "created": 1776923999,
  "data": [
    {
      "url": "https://XXXXXXXXXXXX/file_download/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "revised_prompt": "..."
    }
  ]
}

• url 为生成的图片链接，直接访问即可下载。
• revised_prompt 为模型实际使用前优化改写过的提示词，属于正常返回字段。

Base64 格式返回（b64_json）

请求中传入 "response_format": "b64_json" 时返回：

1
2
3
4
5
6
7
8
9
10

{
  "created": 1776923999,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ]
}

• 此响应格式下不包含 url，需要客户端自行将 b64_json 字符串解码保存为图片文件。
• 普通场景更推荐使用默认的 url 方式，更易于保存与分享。

CC Switch 配置Claude & Codex完整教程

CC Switch 是一款强大的跨平台图形化配置管理工具，支持一键切换并管理 Claude Code CLI、Claude Desktop 桌面端、Codex CLI 以及 Codex 客户端/App 等多款 AI 编程工具的 API 供应商（如原生官方、DeepSeek、QCode、SiliconFlow 等）、Base URL、Token 与模型映射。

1. 准备工作

1.1 官方渠道与系统要求

⚠️ 安全提示
请只从 ccswitch.io、GitHub Releases 或项目官方源码仓库获取 CC Switch。任何要求付费、充值或索取登录凭据的“CC Switch”网站或客户端都不是官方渠道。

注：安装包可以从官网的下载页或 GitHub Releases 获取，两处文件完全相同。

1.2 可选：安装要管理的工具

CC Switch 本身不需要 Node.js 或其他运行环境。它管理的是你已经安装的 Claude Code、Codex 等工具；若尚未安装，可以先装好 CC Switch，再用以下任一方式安装工具：

方式一：在 CC Switch 内一键安装（推荐）

打开 「设置 → 关于」，工具列表会显示每个工具的当前版本和最新版本：

• 未安装的工具旁提供 安装 按钮。
• 已安装的工具可以单独升级或选择 「全部升级」。
• 支持工具：Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi。（详见 1.5 个性化配置 → 关于页面）

方式二：按各工具官方方式安装

ℹ️ 说明

• Claude Desktop、MiniMax Code 以及 Windows 上的安装方式，请参考各工具的官方文档。
• 用 npm 安装需要先装好 Node.js。各工具要求的版本不同（例如 Claude Code 需要 22 及以上，OpenClaw 需要 24.16+ 或 26.1+），建议安装当前的 LTS 版本；版本不满足时 npm 会给出提示。

💡 镜像加速提示
国内用户如果 npm 下载较慢，可以在命令后加上 --registry=https://registry.npmmirror.com，或全局设置镜像源：

1	npm config set registry https://registry.npmmirror.com

镜像同步偶尔可能会有滞后，若安装到的版本比官方旧，可临时改回官方源：https://registry.npmjs.org。

1.3 CC Switch 安装指南

💻 Windows

1. 安装包方式

1. 在下载页或 Releases 页面下载 CC-Switch-v{版本号}-Windows.msi（ARM 版 Windows 请下载 CC-Switch-v{版本号}-Windows-arm64.msi）。
2. 双击运行安装程序。
3. 按界面提示完成安装。

📌 常见问题：运行安装程序后如果没有任何反应，可右键点击该文件选 属性，在 常规 标签页底部勾选 解除锁定 即可。

2. 绿色版（免安装）

1. 下载 CC-Switch-v{版本号}-Windows-Portable.zip（ARM 版为 CC-Switch-v{版本号}-Windows-arm64-Portable.zip）。
2. 解压到任意目录。
3. 直接运行 CC-Switch.exe。

🍎 macOS

方式一：Homebrew 安装（推荐）

1
2
3
4
5

# 安装
brew install --cask cc-switch

# 更新到最新版本
brew upgrade --cask cc-switch

方式二：手动下载安装

1. 下载 CC-Switch-v{版本号}-macOS.dmg（推荐）或 CC-Switch-v{版本号}-macOS.zip。（此为 Universal 通用包，Apple Silicon 和 Intel Mac 均可原生运行）
2. 打开 DMG，或解压 zip 获得 CC Switch.app。
3. 将图标拖动到 「应用程序 (Applications)」 文件夹。

🛡️ 安全认证：CC Switch macOS 版本已通过 Apple 代码签名和公证，安装后可直接打开，无需额外信任设置。

🐧 Linux

⚠️ 系统要求：CC Switch Linux 版需要 glibc 2.35+ 和 WebKitGTK 4.1（例如 Ubuntu 22.04+、Debian 12+ 及较新的 Fedora）。RHEL / Rocky / Alma 8–9 的系统库版本不够，暂不支持。

Arch Linux

使用 AUR 助手进行安装：

1
2
3
4
5

# 使用 paru
paru -S cc-switch-bin

# 或使用 yay
yay -S cc-switch-bin

Debian / Ubuntu

1. 根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.deb 或 CC-Switch-v{版本号}-Linux-arm64.deb。
2. 执行安装命令：

   1 2 3 4

   sudo dpkg -i CC-Switch-v{版本号}-Linux-*.deb # 如果遇到依赖问题，运行以下命令修复： sudo apt-get install -f

Fedora 等 RPM 发行版

1. 根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.rpm 或 CC-Switch-v{版本号}-Linux-arm64.rpm。
2. 执行安装命令：

   1	sudo dnf install ./CC-Switch-v{版本号}-Linux-*.rpm

AppImage

适用于满足系统要求但没有对应安装包的发行版：

1. 下载对应的 CC-Switch-v{版本号}-Linux-x86_64.AppImage 或 CC-Switch-v{版本号}-Linux-arm64.AppImage。
2. 添加执行权限并运行：

   1 2	chmod +x CC-Switch-v{版本号}-Linux-*.AppImage ./CC-Switch-v{版本号}-Linux-*.AppImage

1.4 验证安装

安装完成后启动 CC Switch，确认以下事项：

• 应用窗口正常显示。
• 系统托盘区域出现 CC Switch 图标。
• 在应用切换器中能看到已启用的受管应用，并能流畅切换到目标应用面板。

1.5 自动更新

CC Switch 内置自动更新功能：

1. 自动检查：启动时会自动检查是否有新版本。
2. 更新提示：存在新版本时会在界面弹出提示。
3. 一键升级：点击提示即可自动下载并完成安装。

注：您也可以随时在 「设置 → 关于」 中手动检查更新。

2. 配置 Claude (Claude Code CLI 与 Desktop)

2.1 配置 Claude Code CLI

CCSwitch 会将配置直接写入全局配置文件 ~/.claude/settings.json。

1. 添加供应商：

在本站API密钥页面，直接点击“导入CCS”按钮，即可自动帮你完成配置，无需手动设置。

3. 启用配置：
   • 保存后，在供应商卡片上点击 「启用」 (使用)。
4. 终端验证：
   • 打开新的命令行终端，运行：

     1

     claude

   • 首次启动若提示登录可按 Esc 跳过网页授权。

2.2 配置 Claude Desktop 桌面客户端

Claude Desktop 需要配合 CCSwitch 的 本地代理 (Local Proxy) 与 第三方网关 (3P Gateway) 使用。

1. 开启 CCSwitch 本地代理与模型映射：

   • 在 CCSwitch 中切换至 Claude Desktop 面板，开启 本地路由 开关。

   • 配置模型映射：Claude Desktop 仅识别官方模型名称，如果使用第三方非原生模型（如 Kimi、DeepSeek 等），需在供应商设置中勾选 “需要模型映射”，将目标模型映射为 Sonnet 或 Opus 角色。

2. 配置 Claude Desktop 客户端 Gateway：
   • 打开 Claude Desktop -> 点击左上角汉堡菜单 -> Help -> Troubleshooting -> Enable Developer mode。
   • 再次点击菜单 -> Developer -> Configure third-party inference。
   • Connection 标签选 Gateway。
   • Gateway base URL：填入本地代理地址（如 http://127.0.0.1:15721）。
   • Gateway API key：固定填写 PROXY_MANAGED（必须严格一致）。
   • Gateway auth scheme：填写 bearer。
3. 重启验证：完全退出 Claude Desktop（从系统托盘右键退出）后重新启动。

3. 配置 Codex (Codex CLI 与 Desktop 客户端)

Codex 是基于 OpenAI 协议的终端助手与桌面客户端，CCSwitch 会将配置自动写入全局配置文件 ~/.codex/config.toml 中。

3.1 配置 Codex CLI

1. 添加 Codex 供应商：
   在本站API密钥页面，直接点击“导入CCS”按钮，即可自动帮你完成配置，无需手动设置。
   • 注意：界面上的 「需要本地路由映射」 开关只在目标上游仅支持旧版 Chat Completions、需要本地代理转换为 Responses 协议时开启。若接入的服务已原生支持 OpenAI/Responses 协议（如 QCode、OpenAI 原生或专业网关），请保持关闭。
2. 启用配置：
   • 保存配置后，点击对应供应商卡片上的 「启用」 (Use) 按钮。
3. 终端验证：
   • 打开新的终端，输入并运行：

     1

     codex

   • 在终端中发送命令或问题测试请求是否正常返回。

3.2 配置 Codex Desktop 客户端 / Codex App

1. 配置文件共享机制：
   • Codex 桌面客户端 (Codex App) 默认直接读取 ~/.codex/config.toml 或当前环境变量。
2. 配置生效步骤：
   • 在 CCSwitch 中选择并启用所需的 Codex 供应商。
   • 启动或重启 Codex App（运行 codex app 或从系统程序菜单中打开）。
   • App 会自动使用当前的全局配置进行 API 请求。

4. 版本检查与升级指南

为了保持功能兼容性并修复已知 Bug，建议定期检查并升级各项 CLI 及客户端工具。

4.1 Claude 检查与升级

4.2 Codex 检查与升级

4.3 CCSwitch 管理工具升级

5. 常见问题排查 (FAQ)

1. 切换供应商后 CLI 依然请求旧服务节点：
   • 已打开的命令行进程不会实时重载配置。请关闭当前终端标签页，重新打开终端再运行 claude 或 codex。
2. Claude Desktop 提示认证或连接 401 报错：
   • 检查 CCSwitch 的“本地代理”是否保持开启状态。
   • 确认 Claude Desktop 开发者设置中的 Gateway API key 是否严格为 PROXY_MANAGED 字符串。
3. Codex CLI 启动后卡住或提示 URL 错误：
   • 检查 Base URL 后缀格式（如 OpenAI 规范协议通常以 /openai 或 /v1 结尾）。
   • 若非必要，请确认已关闭 Codex 供应商卡片中的“需要本地路由映射”选项。
4. 能否同时配置并使用 Claude 与 Codex？：
   • 可以完全并行使用。CCSwitch 分别维护 ~/.claude/settings.json 与 ~/.codex/config.toml，两者互不影响。

智惠API网站功能用户使用手册

本文介绍登录智惠API http://api.api2cn.com/ 后，左侧“我的账户”区域常用菜单的用途，以及第一次调用 API 的完整流程。

一、第一次使用

1. 注册或登录账户。
2. 打开“仪表盘”，确认账户余额、API 密钥数量和近期用量。
3. 进入“API 密钥”，点击“创建密钥”。填写名称并选择可用分组，按页面提示保存。
4. 立即复制新生成的 API Key。密钥只应保存在自己的密码管理器或本地安全配置中，不要发到群聊、截图、公开仓库或前端代码里。
5. 在客户端中填写“API 密钥”页面显示的 API 端点。端点以页面显示内容为准，不要自行追加 /v1、/chat/completions 等路径。
6. 在请求中使用以下认证头：

1

Authorization: Bearer YOUR_API_KEY

如果客户端支持自动获取模型，可以在“API 密钥”页面使用模型列表入口或复制对应的模型端点。模型名称、可用分组和访问权限以页面实际显示为准。

二、“我的账户”菜单说明

1. 仪表盘

查看账户总览，包括余额、API 密钥数量、今日请求、今日消费、Token 用量、最近使用记录和常用快捷操作。

第一次登录建议先查看这里；开始调用后，可从“最近使用”进入完整的“使用记录”。

2. API 密钥

这是日常使用最重要的页面，可以：

• 创建、编辑和删除 API Key；
• 为密钥选择分组；
• 查看密钥状态、用量、有效期和配额；
• 复制 API 端点和密钥；
• 在支持时将密钥导入 CC Switch；
• 对异常的限流或配额用量执行重置操作。

建议为不同应用创建不同的密钥，并使用容易识别的名称。发现密钥泄露时，应立即删除或撤销，再创建新的密钥。

3. 生图中心

用于在线提交图片生成任务。页面会提供任务参数和可复制的 Agent 调用说明。

使用前确认账户拥有生图权限KEY，并留意任务数量、模型和图片规格可能产生的费用。任务提交后可根据页面状态跟踪处理结果。

4. 使用记录

查看和分析 API 使用历史。常用信息包括：

• 请求时间、模型、端点和请求状态；
• 输入、输出、缓存和总 Token；
• 标准费用、实际扣费和平均耗时；
• 按 API Key、时间范围和模型筛选；
• 导出 CSV 或 Excel。

排查扣费、请求失败或调用量异常时，先在这里缩小时间范围，再按密钥和模型查看明细。

5. 渠道状态

查看渠道当前可用性、延迟和近期状态。页面通常提供：

• 渠道和分组名称；
• 主模型；
• 7 天可用率；
• 最新延迟；
• 7 天、15 天和 30 天状态详情。

调用失败时，可以先检查对应渠道是否处于 DEGRADED 或 UNAVAILABLE，再尝试其他可用模型或渠道。

6. 充值/订阅

用于充值余额或购买订阅套餐，具体显示哪些选项取决于站点配置。

一般流程是：

1. 选择“充值”或“订阅”标签；
2. 输入充值金额，或选择订阅套餐；
3. 查看最终报价、赠送金额和会员权益；
4. 选择支付方式并完成支付；
5. 返回页面等待订单状态更新。

充值和订阅的最终到账金额以创建订单时的服务端报价为准。

7. 加密货币支付

使用 USDT 为账户余额充值。下单后请严格按照页面显示的金额、收款地址和网络转账：

1. 输入充值金额并创建订单；
2. 核对应付 USDT、收款地址和网络；
3. 从钱包转账，避免使用不支持的网络；
4. 等待区块确认和系统入账；
5. 在当前页面或“我的订单”查看结果。

收款地址和网络以当前订单页面为准。转账前请再次核对，错误网络或错误地址通常无法追回。

8. 我的订单

查看充值、订阅和加密货币支付订单，包括订单编号、金额、实付金额、到账金额、支付方式、状态和创建时间。

对于仍在等待支付的订单，可以按页面提供的操作取消；遇到支付完成但余额未更新的情况，先刷新订单状态，再联系管理员或客服并提供订单编号。

9. 兑换

使用兑换码增加余额、并发数或试用权限：

1. 输入完整兑换码；
2. 注意兑换码区分大小写；
3. 点击“兑换”；
4. 在结果提示和“最近活动”中确认余额、并发数或订阅权限是否更新。

每个兑换码通常只能使用一次。兑换码不要公开分享；兑换失败时请检查字符、大小写和有效期。

10. 我的奖励

本站特色营销活动，集中查看和领取活动奖励，常见内容包括：

• 每日签到；
• 充值抽奖或活动奖励；
• 排名奖励；
• 奖励明细和发放记录。

每日签到是否开放、奖励金额和活动规则以页面显示为准。领取奖励后建议检查账户余额或奖励记录是否更新。

11. 个人资料

管理账户基本资料和安全设置，包括用户名、头像、密码、双因素认证和通知提醒等。

建议完成以下安全设置：

• 使用独立且不重复的账户密码；
• 为账户启用双因素认证（如果站点已开放）；
• 保持邮箱等联系信息可用；
• 不在公共设备上保留登录状态；
• API Key 泄露时立即回到“API 密钥”页面撤销。

三、推荐使用顺序

注册登录后，可以按下面的顺序完成配置：

1. 仪表盘：确认余额和账户状态。
2. API 密钥：创建一个专用 Key，选择分组并复制端点。
3. 可用渠道 / 渠道状态：确认可用模型和渠道健康情况。
4. 客户端调用：填写端点、API Key 和模型名称。
5. 使用记录：确认请求、Token 和扣费正常。
6. 充值/订阅、加密货币支付或兑换：按需要补充余额或权限。
7. 个人资料、我的奖励：完成安全设置并领取可用奖励。

四、常见问题

API 调用返回认证错误怎么办？

检查 API Key 是否完整、是否已删除或过期，确认请求头使用 Authorization: Bearer YOUR_API_KEY，并确认使用的是当前密钥页面显示的端点。

API 调用失败但密钥正常怎么办？

先检查“渠道状态”，再到“使用记录”查看具体状态码、模型和端点。也可以确认 API Key 是否绑定了正确分组，以及账户余额或订阅是否有效。

充值后余额没有变化怎么办？

先打开“我的订单”确认订单状态。支付处理中时等待系统确认；订单已完成但余额仍未更新，请保留订单编号并联系管理员。

请妥善保管账户密码和 API Key。任何需要提交密钥的排查，都只通过站点的安全渠道进行，不要在公开聊天中发送完整密钥。

🔍 故障排查指南

当客户端无法调用、返回异常或消耗异常时，可以按以下顺序进行排查与修复。

⚡ 快速自检

在深入排查具体报错前，请按顺序检查以下基础配置：

1. 检查 Base URL

• OpenAI Compatible 客户端应填写 [https://api.api2cn.com/v1](https://api.api2cn.com/v1)
• ⚠️ 注意： 有v1删除v1,没V1加上v1 或 /chat/completions。

2. 检查 API Key

• 确认密钥未被禁用。
• 复制时注意检查前后是否有空格或换行符。

3. 检查余额

• 确认账户内有可用余额或有效的订阅额度。

4. 检查模型名

• 模型名称必须与控制台中“可用模型列表”的名称完全一致。

🧪 命令行测试

您可以通过终端运行以下命令验证 API 的连通性与密钥有效性：

1
2
3

curl https://api.api2cn.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

• 测试结果判定：
• 若能正常返回模型列表 JSON，说明网络与 API Key 正常。
• 若命令正常但客户端依然报错，请优先检查客户端的 Base URL 格式、模型名拼写及本地缓存。

🛠️ 常见问题与解决方案

❓ 常见问题

这里整理 api2cn.com 使用过程中最常见的问题与解答。

💡 问题解答

1. 为什么我的客户端请求失败？

请优先检查以下三项：

• Base URL：是否填写为 [https://api.api2cn.com/v1](https://api.api2cn.com/v1)。
• API Key：是否输入正确（确认未包含空格或换行）。
• 账户额度：确认账户内是否有可用余额或有效订阅额度。

2. 余额和订阅哪个先扣？

系统会根据账户计费偏好和可用额度选择扣费来源。通常情况下，如果有可用订阅，将优先消耗订阅额度。

3. 支持哪些充值方式？

• 在线充值：支持微信支付、支付宝、Visa 等银行卡及加密货币
• 兑换码充值：支持使用卡密/兑换码进行充值。

提示：实际可用的支付方式可能会因地区、币种、设备和浏览器有所不同。

4. 支持哪些客户端？

支持所有能够配置 OpenAI Compatible Base URL、API Key 和 模型 ID 的客户端，包括：

• 桌面端与 Web 端：Cursor、Cherry Studio、Chatbox、Open WebUI 等。
• CLI 与 SDK：Claude Code、Codex CLI、CC Switch 以及常见 SDK。

注意：某些客户端的专用代码补全（Completion）或内置 Agent 功能可能仍使用其官方服务。

5. 接入 API2CN.COM 需要退出工具原来的账号吗？

通常不需要。

• 工具本身账号：负责同步、订阅或编辑器固有功能。
• API2CN.COM API Key：负责处理自定义模型请求。

只需在模型或 Provider 设置中选择 API2CN.COM 即可；只有当客户端明确要求重新认证时才需要退出。

6. Base URL 到底填哪个？

根据不同客户端的需求填写：

• OpenAI Compatible 客户端：填写 [https://api.api2cn.com/v1](https://api.api2cn.com/v1)
• Claude Code（Anthropic 网关变量）：填写 [https://api.api2cn.com](https://api.api2cn.com)
• 完整 Endpoint：只有字段明确要求填写完整接口地址时，才追加 /chat/completions。

7. 为什么模型列表为空，但 Key 没报错？

部分客户端不会自动读取兼容接口的模型列表，或者会过滤不认识的模型。
解决方法：请从 api.api2cn.com 控制台复制完整的模型 ID，并在客户端中手动添加。

8. 怎样确认请求确实走了 api.api2cn.com？

1. 为该工具专门创建一个 API Key。
2. 使用该 Key 发送一条短消息进行测试。
3. 登录 api.api2cn.com 控制台，在 用量日志 中按时间与 Key 核对请求记录。

注意：仅看客户端界面显示的模型名称并不可靠，请以控制台日志为准。

9. 怎样恢复工具原来的官方模型？

1. 在模型选择器中切回内置 Provider，并停用自定义 Base URL 或 api.api2cn.com Provider。
2. CLI 用户：删除或取消对应环境变量。
3. 重启终端或客户端软件以生效。

在 Cursor 中使用 API2CN.COM

在 Cursor 的模型设置中添加 OpenAI Compatible 服务，将 Base URL、API Key 和模型名指向 API2CN.COM。

📋 准备信息

🛠️ 配置步骤

1. 打开模型设置
   进入 Cursor Settings，找到 Models、API Keys 或自定义模型供应商区域。（不同版本的菜单名称可能略有差异）
2. 添加兼容服务
   选择 OpenAI Compatible；如果版本只提供 OpenAI 配置，则使用允许覆盖 Base URL 的入口。
3. 填写地址和密钥

• Base URL：填写 [https://api.api2cn.com/v1](https://api.api2cn.com/v1)
• API Key：填写在 API2CN.COM 控制台创建的密钥

4. 添加模型
   从控制台复制完整模型 ID。（注意：请勿自行删减版本号、短横线或修改大小写）
5. 启用并测试
   保存并启用模型，在 Chat 或 Agent 中发送一条短请求，确认模型能够正常返回。

🔄 账号、内置模型与切换

• 无需退出 Cursor 账号
  Cursor 登录负责编辑器、配置同步及 Cursor 自带功能，API2CN.COM API Key 只负责对应的自定义模型请求。
• 并非所有功能都经过 CUN.AI
  Tab Completion 等依赖 Cursor 专用模型的功能，仍可能继续使用 Cursor 自带服务。
• 切回 Cursor 官方模型
  如果启用了全局 Override OpenAI Base URL，使用官方模型前需先关闭该开关；再次使用 API2CN.COM 时重新开启。
• 免费版限制
  Cursor 对自定义 API Key 在 Agent 和 Edit 功能上的可用范围可能受当前套餐限制，具体以 Cursor 客户端提示为准。

❓ 常见问题

💡 最佳建议

建议为 Cursor 单独创建一个独立的 API Key，便于后期按客户端查看用量、轮换密钥或单独停用。

在 CodeBuddy 中使用 API2CN.COM

如果您使用的 CodeBuddy 版本支持自定义模型、OpenAI Compatible 或自定义 API 地址，可以将 API2CN.COM 配置为模型供应商。

🛠️ 配置步骤

1. 打开模型设置
   进入 CodeBuddy 的设置页，查找 Model、Provider、API Key、Custom Model 或 OpenAI Compatible 相关配置。
2. 新增自定义服务商
   服务商类型选择 OpenAI Compatible；如果没有该选项，可选择 OpenAI 并修改 Base URL。
3. 填写接口地址
   Base URL 填写 [https://api.api2cn.com/v1](https://api.api2cn.com/v1)（*注意：不要额外添加 /chat/completions*）。
4. 填写 API Key
   使用 API2CN.COM 控制台创建的 API Key。建议为 CodeBuddy 单独创建一个 Key。
5. 选择模型测试
   选择控制台中可用的模型名称，发送一条短消息验证是否能正常返回。

📋 推荐填写参数

💡 版本差异说明

不同 CodeBuddy 版本的菜单名称可能不同。只要能配置自定义 Base URL 和 API Key，即可按 OpenAI Compatible 方式接入。

❓ 常见问题

• 配置后是否需要重新登录？
  无需退出 CodeBuddy 或编辑器账号；在模型选择器中切换到 API2CN.COM 自定义模型即可。
• 找不到配置入口怎么办？
  如果当前版本完全没有自定义 Provider、Base URL 或 API Key 入口，则该版本暂时无法直接接入。
• 功能生效范围
  代码补全与聊天可能使用不同模型设置；请分别检查 Chat、Agent 和 Completion 的供应商。
• 如何恢复官方模型？
  恢复官方模型时，在模型选择器中切回内置模型；如仍请求 API2CN.COM，关闭自定义 Provider 后重启客户端。

在日常使用中，虽然Claude Code直接使用OPUS模型是解决问题的最佳选择，但无奈模型太贵，本文指引如何介绍CC-Switch的进阶用法，配置Claude Code使用GPT模型。

一、什么是 CC Switch
CC Switch 是一款跨平台桌面应用，专为使用 AI 编程工具的开发者设计。它帮助你统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes 等受管应用的配置。

二、官方网站及下载地址：
https://ccswitch.io/zh/ 下载并安装。

三、导入本站Claude分组配置

1、请登录网站后，在API密钥页面，在“Claude Max号池组” 对应行，点击导入到CCS

2、先按默认设置导入

3、CCS软件中选择刚导入的配置并进行编辑

4、**非常重要！复制本站的codex Pro号池组的key，替换Claude号池的key

5、点击获取模型列表，根据你的需求，选择gpt5.5或者5.4后保存！

6、重新打开vscode 即可在claude code 插件中使用gpt模型！

7、后台验证模型调用,确认！

在官方ccs 导入功能的基础上，本站自己修改了相关导入逻辑，现在点击CCS，直接先选好模型，在导入CCS，避免还要手工在修改，帮助大家更好的使用系统！

Claude模型组导入界面，下拉选择默认模型

Codex模型组导入界面，下拉选择默认模型

选择好之后，点击导入即可！

💸 为什么 Auto-Agent（自主智能体）像“Token 碎纸机”？

在使用 Hermes Agent、OpenClaw 等自主代理或自动化工具进行开发时，你可能会发现 Token 消耗极快。这并不是你的错觉，也不是代码写错了，而是由 Auto-Agent 架构的底层逻辑 决定的。这类工具在开发和运行阶段，存在几个天然的“Token 碎纸机”机制。

以下是核心原因的深度剖析：

1. 恐怖的“上下文滚雪球”效应 (Context Accumulation)

Auto-Agent 核心的运作方式是 ReAct 框架：

$$\text{思考} \rightarrow \text{行动} \rightarrow \text{观察} \rightarrow \text{再思考}$$

随着任务推移，其上下文会呈指数级或线性堆叠：

• 第 1 轮：Prompt + 任务目标 $\rightarrow$ 消耗 $2\text{k}$ Token
• 第 2 轮：Prompt + 任务目标 + 第 1 轮思考与执行结果（如读文件、查数据库） $\rightarrow$ 消耗 $4\text{k}$ Token
• 第 3 轮：Prompt + 任务目标 + 前两轮所有历史和报错信息 $\rightarrow$ 消耗 $8\text{k}$ Token

💥 核心痛点：Agent 每尝试修复一个 Bug 或多走一步，都会把前面所有的对话历史、代码上下文和控制台报错原封不动地叠加塞回给大模型。这种上下文堆叠是烧 Token 的头号杀手。

2. System Prompt（系统提示词）过于臃肿

像 OpenClaw 和 Hermes 这种为了保证高成功率、能进行复杂工具调用（Function Calling）的 Agent，其背后的 System Prompt 极其庞大。里面包含了：

• 严密的逻辑框架与角色设定
• 各种异常处理守则
• 输出格式规范（例如强制要求 JSON 且不能出错）
• 每一个可调用工具（API、文件读写、执行 Shell 命令行）的定义说明

📌 结果：哪怕你只是让它修改一行代码，只要产生一次交互（哪怕模型只回答一个词），这几千甚至上万 Token 的 System Prompt 都要作为输入重新计费一次（在未开启 Context Caching 的情况下）。

3. “反思”与“自我纠错”机制的代价

Hermes 等 Agent 之所以显得聪明，是因为它拥有一套 Self-Reflection（自我反思） 与纠错闭环：

1. 编写代码：Agent 完成代码修改。
2. 运行测试：自动调用编译器或运行环境执行代码。
3. 捕获报错：将报错信息吞入上下文。
4. 自我讨论：“哦，看来这里类型不对，我得换个方法…”

🔍 隐形消耗：用户表面上只看到了最终改好的那一行代码，但在后台，Agent 可能已经与背后的 Claude 或 GPT 悄悄交互了 $5 \sim 10$ 个回合，且每一回合都是全量上下文的输入。

4. 代码文件全量读取 (Full File Injection)

在执行开发任务时，Agent 为了理解依赖关系，往往需要读取整个文件甚至多个关联文件的内容：

• 输入端 (Input)：如果你没有做精细的路径裁剪，Agent 可能会把整段文件的代码都塞进 Prompt 里面。
• 输出端 (Output)：一旦它决定“重写这个函数”，它在 Output 侧又会把整段代码重新吐出来。

⚠️ 高昂代价：Output Token 的价格通常是 Input Token 的 $3$ 倍左右，反复吐出大段代码会让账单瞬间飙升。

💡 CC-Switch 配置余额显示方法

按照以下步骤即可快速完成 CC-Switch 的用量及余额查询配置：

📝 操作步骤

1. 进入配置页面
   点击界面中的 配置用量查询 按钮。

2. 选择模板
   选择预设模板。

3. 填入配置代码
   复制并粘贴下方代码至对应的配置框中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

({
  request: {
    url: "{{baseUrl}}/v1/usage",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}"
    }
  },
  extractor: function(response) {
    const remaining = response?.remaining ?? response?.quota?.remaining ?? response?.balance;
    const unit = response?.unit ?? response?.quota?.unit ?? "USD";
    return {
      isValid: response?.is_active ?? response?.isValid ?? true,
      remaining,
      unit
    };
  }
})

claude-code-skills 是一组面向 Claude Code 的开源 skills。这里重点推荐 codex 和 codex-plan：前者适合让 Codex CLI 给代码、方案或问题提供第二意见；后者适合在动手开发前做多轮对抗式计划审查。

安装前准备

• 先安装 Codex CLI，并执行 codex login 完成登录。
• 确认 ~/.codex/config.toml 已配置好可用模型和 Provider。
• Claude Code 的 skills 目录一般是 ~/.claude/skills/，Windows 可对应到 %USERPROFILE%\.claude\skills\。

1
2

npm install -g @openai/codex
codex login

安装 codex-plan skills

可以直接让 Claude Code 根据仓库说明安装：

1

请阅读 https://github.com/lldxflwb/claude-code-skills 帮我安装里面的 codex 和 codex-plan skill

也可以手动克隆仓库并创建软链：

1
2
3
4

git clone https://github.com/lldxflwb/claude-code-skills.git
mkdir -p ~/.claude/skills
ln -s /path/to/claude-code-skills/skills/codex ~/.claude/skills/codex
ln -s /path/to/claude-code-skills/skills/codex-plan ~/.claude/skills/codex-plan

如果不想使用软链，也可以直接把仓库里的 skills/codex 和 skills/codex-plan 两个文件夹复制到 ~/.claude/skills/。

Skill 对比

使用建议

• 小问题、代码复核、方案第二意见，用 /codex。
• 重要重构、迁移方案、架构设计，先用 /codex-plan 过一遍。
• codex 默认让 Codex 以只读方式参与，不会直接改文件；最终是否采纳由你决定。
• codex-plan 更适合在动手前使用，可以提前暴露边界情况、风险点和过度设计。

如果你已经按上面的 CC-Switch 方法配置好智惠 API，可以先确保 Codex CLI 使用本站 Provider，再安装这两个 skills。这样 Claude Code 调用 Codex 复核时，也会走同一套模型配置。