配置与使用文档

新手路径

准备工作

下面两步用于准备账号和 API 密钥。完成后先安装一次 CC Switch，再进入对应工具教程。

登录云枢 API 并注册

打开云枢 API。没有账号时先按页面提示完成注册，已有账号直接登录，然后进入控制台。

打开云枢 API ↗

创建一枚独立 API 密钥

进入控制台的「API 密钥」页面，为当前客户端单独创建一枚密钥。不要让 Claude、Codex、Grok 和其他客户端共用同一枚密钥。

第 1 步：打开 API 密钥页面

在控制台左侧点击「API 密钥」，再点击页面右上角的「创建 API 密钥」。

第 2 步：按顺序填写创建表单

不同版本的字段排列可能略有变化。第一次创建时按下面填写，不认识的高级选项保持默认。

字段	建议填写	说明
名称	按用途命名，例如 codex-laptop	名称只用于自己识别，建议一个客户端一枚密钥。
分组	选择当前账号可用、与目标工具对应的分组	只有一个选项时保持默认；不确定时不要随意切换。
过期时间	按实际使用周期选择	测试密钥可选择 1 天或 1 个月；长期密钥也应定期更换。
额度设置	测试密钥建议设置可控额度	“无限额度”只表示不在密钥层单独限额，调用仍会消耗账户余额。
高级设置	保持默认	模型限制留空表示不额外限制；没有明确需求时不要设置 IP 限制。

第 3 步：复制刚创建的 API 密钥

保存成功后回到 API 密钥列表，找到刚创建的那一行，点击密钥右侧的复制图标。红色箭头指向的就是复制按钮。

API 密钥不能泄露

不要把完整密钥发到聊天群、工单、公开仓库或截图里，也不要交给陌生人远程配置。发现异常消耗时，立即在控制台禁用或删除对应密钥，再创建一枚新的。

推荐配置工具

CC Switch：下载与统一配置

CC Switch 是一个图形化配置管理工具，可以集中管理 Claude Code、Codex CLI、Codex 应用端 + Codex++ 和 Grok CLI 的供应商配置。新手只需安装一次，以后切换工具时不必到处寻找配置文件。

第 1 步：下载并安装 CC Switch

Windows

点击上面的“打开官方下载页”，进入最新版本，下载标有 Windows 且与电脑处理器匹配的安装版或便携版。普通 Intel / AMD 电脑通常选择 x64 或 amd64；只有明确使用 ARM 电脑时才选择 arm64。

成功标志：安装版完成向导后，或解压便携版后，能够正常打开 CC Switch 主界面。Windows 出现安全提示时，先确认文件来自上面的官方 GitHub 项目，不要从陌生网盘下载。

macOS

打开“终端 Terminal”，复制下面整行命令并按回车：

brew tap farion1231/ccswitch && brew install --cask cc-switch

成功标志：命令执行完成后，可以从“应用程序”中打开 CC Switch。若电脑没有 brew 命令，直接从官方下载页选择 macOS 对应版本。

Linux

已经安装 Linuxbrew 时，在终端运行：

brew tap farion1231/ccswitch && brew install cc-switch

没有 Linuxbrew 时，不必为了 CC Switch 单独安装它。直接从官方下载页选择适合当前发行版和处理器的 AppImage、deb 或 rpm 文件即可。

第 2 步：认识统一配置流程

打开对应客户端类型

准备配置哪个工具，就先在 CC Switch 中选择哪个客户端类型，例如 Claude Code、Codex 或 Grok。一次只配置当前要使用的工具。

添加自定义供应商

点击“添加供应商”“添加配置”或右上角的加号。不同版本按钮名称可能略有差异；如果预设列表中没有“云枢 API”，这是正常情况，请进入自定义供应商编辑页面。

填写名称与自己的 API Key

进入供应商编辑页面后再开始填写。下面先以 Claude Code 配置为例：供应商名称建议写成 云枢 API 或“云枢 + 工具名”，API Key 粘贴在密钥字段中，不要加引号、空格或 Bearer。

按对应教程填写并启用

继续查看下表中的对应教程，照图填写请求地址、协议和模型。保存后启用新配置，关闭旧终端，再重新打开终端启动工具。

第 3 步：进入你要配置的工具

Windows 图形界面 · 可选路线

Codex 应用端 + Codex++：安装、导入与启动

如果你更喜欢窗口界面，可以先安装 OpenAI 官方 Windows 桌面应用，再用 Codex++ 导入在 CC Switch 中配置好的云枢 Codex 供应商。下面只讲 Windows；这条路线不要求你先安装 Codex CLI，适合希望配置更简洁、启动更高效的用户。

步骤 1：安装官方 Codex 应用端

点击下面的微软官方下载按钮安装 ChatGPT。在微软商店搜索 codex 时，官方结果也会显示为 ChatGPT；进入详情页后请确认开发者是 OpenAI，不要安装名称相近的第三方应用。

如果网页按钮没有拉起微软商店，也可以打开 PowerShell，运行官方应用对应的安装命令：

winget install --id 9PLM9XGG6VKS -s msstore

成功标志：开始菜单中能够找到 ChatGPT，即代表官方应用已经安装。第一次直接打开时可能先看到登录页；使用云枢纯 API 的用户可以先完全退出应用，继续配置 Codex++，不必为了这一步登录官方账号。不同版本可能显示 ChatGPT 或 Codex 名称，以 OpenAI 官方条目为准。

步骤 2：从 GitHub 下载并安装 Codex++

打开 Codex++ 的 GitHub Releases 页面，进入标有 Latest 的最新发布，在 Assets 中下载文件名类似 CodexPlusPlus-*-windows-x64-setup.exe 的 Windows x64 安装包。星号位置是版本号，不需要照抄某个固定版本。

步骤 3：从 CC Switch 导入云枢配置

首次使用先打开 Codex++ 管理工具，不要直接打开桌面的 Codex++。界面名称可能随版本略有变化，按下面顺序操作即可。

步骤 4：必须从 Codex++ 启动官方应用

步骤 5：在应用中选择模型

点击输入框右下角显示当前模型和推理强度的按钮，再展开“高级”并点击“模型”，从列表中选择当前云枢供应商实际提供、并且支持 Responses API 的模型。模型名称和列表会随供应商、账号权限与版本变化，因此不要照抄截图中的固定型号。

成功标志：选中的模型名称显示在输入框下方，并且发送消息后能够正常收到回复。若列表为空，先回到 Codex++ 的供应商详情检查导入结果和模型配置，不要手工猜模型名称。

步骤 6：选择项目并做第一次只读测试

点击“选择项目”，选择准备让 Codex 读取的文件夹，然后发送：“只读取当前项目并说明目录结构，不要修改任何文件。”能收到与当前文件夹相符的回复，说明应用、Codex++ 和云枢配置已经连通。

CLI 下载中心

Codex CLI：安装、配置、首次运行

按顺序完成“准备 Git → 安装 Node.js LTS → 安装 Codex CLI → 用 CC Switch 配置云枢 API → 启动验证”。手动编辑配置文件只作为高级备用方式。

git --version

node --version

npm --version

npm install -g @openai/codex

codex --version

git --version

node --version

npm --version

npm install -g @openai/codex

codex --version

codex --version

npm install -g @openai/codex

codex --version

步骤 4：用 CC Switch 配置云枢 API（推荐）

CC Switch 可以自动管理 Codex 的配置文件和认证信息。普通用户只需选对应用、填写 Key、模型和地址，不需要手动编辑 config.toml 或 auth.json。

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null

notepad "$HOME\.codex\config.toml"

mkdir -p ~/.codex

${EDITOR:-nano} ~/.codex/config.toml

model = "<当前可用的 Codex 模型名称>"
model_provider = "yunshu"
model_reasoning_effort = "medium"

[model_providers.yunshu]
name = "云枢 API"
base_url = "https://yunshuapi.wiki/v1"
env_key = "YUNSHU_API_KEY"
wire_api = "responses"
requires_openai_auth = false

$env:YUNSHU_API_KEY = Read-Host "请粘贴云枢 API Key"

printf "请粘贴云枢 API Key: "
read -s YUNSHU_API_KEY
printf "\n"
export YUNSHU_API_KEY

步骤 5：启动并验证

在准备交给 Codex 处理的项目文件夹中打开一个新的终端。云枢用户先确认 CC Switch 中启用的是刚创建的 Codex 云枢配置，然后运行：

codex

进入 Codex 界面后，输入下面的命令检查配置是否被读取：

/status

成功标志：云枢用户应看到刚配置的 Provider 和模型；官方账号用户应看到自己的登录状态。确认后再发送只读测试任务：

只读取当前目录，告诉我这里有哪些文件，不要修改任何内容。

CLI 快速配置

Claude Code：安装、配置、首次运行

按顺序完成“准备 Git → 安装 Claude Code → 选择登录路线 → 配置云枢 API → 启动验证”。云枢用户默认使用 CC Switch 图形化配置，手动编辑文件只作为高级备用方式。

步骤 1：安装

先安装 Git（按平台准备）

Claude Code 在 Windows 原生环境中依赖 Git for Windows。打开下面的官方下载页，运行安装程序，安装过程保持默认选项即可。

安装完成后，关闭原来的 PowerShell，再重新打开一个 PowerShell，运行下面这一条检查 Git：

git --version

成功标志：看到类似 git version 2.xx.x 的版本号。若提示“无法识别 git”，先重开终端；仍无效时重新检查 Git 是否安装成功。

再安装 Claude Code

官方原生安装脚本是推荐方式，安装后可以自动保持更新。请根据自己的系统只选择下面一种方式，不要把所有安装命令都执行一遍。

Windows PowerShell（推荐）

irm https://claude.ai/install.ps1 | iex

等待安装结束并重新出现 PowerShell 输入提示。若之后找不到 claude 命令，关闭 PowerShell 再重新打开。

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows CMD

只有在使用“命令提示符 CMD”而不是 PowerShell 时，才使用这一条：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

可选：使用包管理器安装

已经熟悉 Homebrew、WinGet 或 npm 时，可以从下面任选一种代替原生安装脚本。普通 Windows 用户优先使用上面的 PowerShell 方法。

brew install --cask claude-code

winget install Anthropic.ClaudeCode

npm install -g @anthropic-ai/claude-code

npm 方式要求电脑已经安装 Node.js LTS；包管理器安装的版本通常需要自行更新。

最后验证 Claude Code

无论使用哪种安装方式，都用下面这一条检查结果：

claude --version

成功标志：终端显示 Claude Code 版本号。只有看到版本号后，才继续配置云枢 API。

步骤 2：先确认自己走哪条路线

Claude Code 可以使用 Claude 官方账号，也可以使用云枢 API Key。两种方式只选一种；先根据自己的情况判断，再继续操作。

步骤 3：用 CC Switch 配置云枢 API（推荐）

CC Switch 是图形化配置工具，适合第一次使用 Claude Code 的用户。你只需要按界面填写地址和 Key，不用手动创建文件，也不用编辑 JSON。

New-Item -ItemType Directory -Force "$HOME\.claude" | Out-Null

notepad "$HOME\.claude\settings.json"

mkdir -p ~/.claude

${EDITOR:-nano} ~/.claude/settings.json

{
  "model": "<当前可用的 Claude Code 模型名称>",
  "env": {
    "ANTHROPIC_BASE_URL": "https://yunshuapi.wiki"
  }
}

$env:ANTHROPIC_API_KEY = Read-Host "请粘贴云枢 API Key"

printf "请粘贴云枢 API Key: "
read -s ANTHROPIC_API_KEY
printf "\n"
export ANTHROPIC_API_KEY

步骤 4：启动并验证

“项目目录”就是你准备让 Claude Code 读取的代码或文档文件夹。先在该文件夹中打开一个新的终端：官方账号用户按登录提示操作；云枢用户先确认 CC Switch 中启用的是刚创建的云枢配置。

claude

成功标志：终端进入 Claude Code 交互界面，不再提示找不到命令、登录失败或要求重新配置。

进入后先发送一个只读任务，确认模型能够正常回复：

只读取当前目录并说明项目结构，不要修改任何文件。

终端客户端

Grok CLI：安装、配置、首次运行

按顺序完成“安装 Grok CLI → 用 CC Switch 配置普通对话 → 检查模型 → 启动验证”。生图和生视频使用另一条媒体地址，放在后面的“媒体与计费”中单独配置。

步骤 1：安装 Grok CLI

irm https://x.ai/cli/install.ps1 | iex

grok --version

curl -fsSL https://x.ai/cli/install.sh | bash

grok --version

grok --version

grok update

grok --version

步骤 2：用 CC Switch 配置普通对话（推荐）

这里先配置 Grok 的普通文字对话。CC Switch 会自动管理 Grok 配置，普通用户不需要手动创建或编辑 .grok/config.toml。

New-Item -ItemType Directory -Force "$HOME\.grok" | Out-Null

notepad "$HOME\.grok\config.toml"

mkdir -p ~/.grok

${EDITOR:-nano} ~/.grok/config.toml

[models]
default = "yunshu-grok"

[model.yunshu-grok]
model = "grok-4.5"
base_url = "https://yunshuapi.wiki/v1"
name = "云枢 Grok"
api_backend = "responses"
env_key = "YUNSHU_API_KEY"

$env:YUNSHU_API_KEY = Read-Host "请粘贴云枢 API Key"

printf "请粘贴云枢 API Key: "
read -s YUNSHU_API_KEY
printf "\n"
export YUNSHU_API_KEY

步骤 3：启动并验证普通对话

在准备使用 Grok 的项目文件夹中打开一个新的终端。先检查 CC Switch 中启用的是云枢普通对话配置。

grok models

成功标志：模型列表中出现刚添加的云枢 Grok 配置。显示名称可能跟随你填写的供应商名称。

grok

进入后先发送普通文字测试：

请只回复“云枢连接成功”，不要调用任何工具。

图形客户端

Cherry Studio、Cursor 等客户端

在客户端中选择「OpenAI Compatible」「自定义服务商」或含义相同的选项，再填写三项。

无需安装依赖

用 PowerShell 测试第一次 API 请求

先用模型列表接口验证 Key，再调用 Chat Completions。这样能快速区分“Key 不对”和“客户端配置不对”。

步骤 1：临时载入 Key

$env:YUNSHU_API_KEY = Read-Host "请粘贴云枢 API Key"

步骤 2：读取模型列表

$headers = @{ Authorization = "Bearer $env:YUNSHU_API_KEY" }
Invoke-RestMethod `
  -Uri "https://yunshuapi.wiki/v1/models" `
  -Headers $headers `
  -Method Get

步骤 3：发送最小聊天请求

从上一步返回的列表中选择一个当前 Key 可以访问的模型名称，填入下面的占位位置。

$headers = @{
  Authorization  = "Bearer $env:YUNSHU_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "<返回列表中的可用模型名称>"
  messages = @(
    @{ role = "user"; content = "只回复：连接成功" }
  )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "https://yunshuapi.wiki/v1/chat/completions" `
  -Method Post `
  -Headers $headers `
  -Body $body

地址规则

Base URL 到底要不要带 /v1？

多数 OpenAI 兼容客户端要填写带 /v1 的基础地址；直接请求某个接口时，要写完整路径。

模型选择

不要先问“最强”，先看任务和协议

模型会更新，固定推荐很快过期。先判断任务和协议，再按对应工具教程或客户端提供的可用选项进行选择。

小白选择顺序

1. 先确认令牌属于哪个分组，以及该分组能看到哪些模型。
2. 确认客户端需要的协议：普通聊天常用 Chat Completions，Codex 使用 Responses。
3. 优先在 CC Switch 或客户端的可用列表中选择，不要把 Chat、Responses 和 Anthropic Messages 模型混用。
4. 先用小请求验证，确认成功后再运行长任务或多图任务。

媒体与计费 · 第一步

生图和生视频前，先添加 Grok 媒体模型

普通对话配置使用 https://yunshuapi.wiki/v1；生图和生视频必须另外添加一条媒体配置，使用 https://yunshuapi.wiki/grok-media/v1。两条地址不能混用。

[models]
default = "yunshu-grok-media"

[model.yunshu-grok-media]
model = "grok-4.5"
base_url = "https://yunshuapi.wiki/grok-media/v1"
name = "云枢 Grok 媒体"
api_backend = "responses"
env_key = "YUNSHU_API_KEY"

启动前做一次文字连接测试

grok

进入后先发送下面这条普通文字测试，不要一开始就提交付费媒体请求：

请只回复“云枢媒体连接成功”，不要调用任何工具。

成功标志：能够正常回复。随后再按生图或生视频章节的固定模板提交一次付费请求。

图片生成

Grok CLI 自然语言生图

先在 CC Switch 中启用上面的 Grok 媒体配置并重开终端。提交时最关键的是写清楚“动作 + 数量 + 图片类型 + 内容”，并避免自动重试造成额外费用。

固定提示词模板

请生成一张1K图片：[主体]，[风格]，[背景]，[光线或构图要求]

请生成一张1K图片：白色背景上的红色传统剪纸作品，正面构图，细节清晰。

显式选择 Quality 高质量图片模型

默认生图仍使用 grok-imagine-image。只有提示词明确包含完整模型名 grok-imagine-image-quality 时，服务端才会切换到 Quality；只写“高质量”“高清”或“2K”不会切换模型。

使用 grok-imagine-image-quality 生成一张2K图片：[主体]，[风格]，[背景]，[光线或构图要求]

使用 grok-imagine-image-quality 生成一张2K图片：雨夜霓虹灯下的未来城市街道，写实电影感，横向构图，细节清晰，无文字、无水印。

提交前检查

完整版本：《云枢 API Grok CLI 生图使用与计费避坑指南》

视频生成 · 已开放

Grok CLI 自然语言生视频

云枢 API 已于 2026-08-03 完成真实视频生成与计费验证。先在 CC Switch 中启用 Grok 媒体配置并重开终端，再使用明确模板直接文生视频。

标准视频提示词以“生成视频：”开头

生成视频：时长[1-15]秒，分辨率[480p或720p]，画面比例[例如16:9]。画面内容：[主体、环境和动作]。镜头：[景别、机位和运镜]。风格：[写实、电影感、动画等]。要求：[光影、运动连续性和需要避免的内容]。无文字、无字幕、无水印。

生成视频：时长5秒，分辨率480p，画面比例16:9。清晨的现代城市天台上，一架红色纸飞机随微风起飞，穿过三道透明玻璃圆环，最后平稳落在木桌上。写实电影感，单镜头连续跟拍，运动自然流畅，光影真实，主体清晰，无文字、无字幕、无水印。

显式选择 Grok Video 1.5 Preview

grok-imagine-video-1.5-preview 同时支持纯文字生成和带参考图生成。两种方式都必须在提示词中写出完整模型名；参考图是可选项，不提供参考图时会直接按文字描述生成视频。

使用 grok-imagine-video-1.5-preview 生成视频：时长[1-15]秒，分辨率[480p或720p]，画面比例[例如16:9]。画面内容：[主体、环境和动作]。镜头：[景别、机位和运镜]。风格：[写实、电影感、动画等]。无文字、无字幕、无水印。

使用 grok-imagine-video-1.5-preview 生成视频：时长[1-15]秒，分辨率[480p或720p]。让参考图中的[主体]执行[动作]。镜头：[运镜要求]。要求：[运动连续性、光影和需要避免的内容]。无文字、无字幕、无水印。

支持规格与费用

异常与下载处理

完整版本：《云枢 API Grok CLI 生视频使用与计费避坑指南》

费用说明

如何看懂 Grok 图片与视频消费记录？

普通文字、图片和视频使用不同的计费方式。先看消费记录中的模型，再核对图片数量或视频时长与分辨率。

容易增加费用的情况

• 提示词含糊，客户端调用 imagine 后自动重试。
• 请求超时后立刻再次回车或手动点击重试。
• 多个终端、设备或自动化任务同时提交相同请求。
• 一次明确要求生成多张图片。
• 视频时长更长，或选择费用更高的 720p。
• 在很长的旧会话中反复说“换一种”“再试一次”。

先看状态码

常见报错与处理顺序

不要一看到失败就反复重试。先根据状态码定位，再做一次最小验证。

通用排查顺序

1. 停止自动重试和并发窗口，记录报错时间。
2. 请求 /v1/models，先验证 Base URL 和 Key。
3. 刷新客户端或接口返回的模型列表，重新选择当前可用模型。
4. 核对客户端协议、旧环境变量和缓存配置。
5. 仍无法解决时，再联系客服，并提供脱敏后的信息。

凭据安全

把 Key 当作银行卡密码保管

FAQ

常见问题