WANFENG API GUIDE

晚风API 使用教程

本指南将带您完成注册账号、添加密钥、安装 ccSwitch，并通过一键导入或手动配置完成客户端接入。

官网与控制台：https://sub.wanfengai.shop/↗ccSwitch 官网：https://ccswitch.io/zh/↗ccSwitch 下载：GitHub Releases 最新版本↗
GETTING STARTED

快速开始

01注册账号

  1. 访问晚风API平台首页：https://sub.wanfengai.shop/
  2. 点击首页上的「立即开始」。
  3. 在登录页面点击「注册」按钮。
  4. 填写邮箱地址和密码。
  5. 点击「获取验证码」，输入邮箱收到的验证码。
  6. 点击「注册」完成账号创建。
请使用有效邮箱地址接收验证码；如果收件箱未看到邮件，请检查垃圾邮件或广告邮件文件夹。

02进入控制台

  1. 在首页点击「登录」按钮。
  2. 输入注册时使用的邮箱和密码。
  3. 点击「登录」进入控制台。

03添加密钥

在控制台创建 API Key

  1. 登录后进入后台。
  2. 在左侧菜单点击「API 密钥」。
  3. 点击右上角亮绿色的「创建密钥」按钮。
  4. 名称可自定义，例如「晚风API-PLUS」。
  5. 选择这个密钥使用的分组，例如「GPT PLUS」「GPT PRO」「CLAUDE」等。
  6. 其他设置通常保持默认即可。
  7. 点击右下角「创建」完成添加。
点击「创建 API Key」
填写名称和分组后创建

04下载 ccSwitch

先访问 ccSwitch 官网了解工具说明；需要安装包时，访问 GitHub Releases 下载对应版本。

系统要求

系统最低版本架构
WindowsWindows 10 及以上x64
macOSmacOS 12 Monterey 及以上Intel x64 / Apple Silicon arm64
Linux见下方发行版说明x64 / ARM64

Windows

文件说明
CC-Switch-Windows.msi推荐，MSI 安装包，支持自动更新
CC-Switch-Windows-Portable.zip便携版，解压即用，不写入注册表

macOS

文件说明
CC-Switch-macOS.dmg推荐，拖入 Applications 即可
CC-Switch-macOS.zip解压后拖入 Applications
CC-Switch-macOS.tar.gz用于 Homebrew 安装和自动更新

Homebrew 安装：

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Linux

同时提供 x86_64 和 ARM64（aarch64）两种架构，请按机器的 uname -m 输出选择版本。

发行版推荐格式安装方式
Ubuntu / Debian / Linux Mint.debsudo apt install ./CC-Switch-*.deb
Fedora / RHEL / CentOS / Rocky.rpmsudo dnf install ./CC-Switch-*.rpm
openSUSE.rpmsudo zypper install ./CC-Switch-*.rpm
Arch Linux / Manjaro.AppImage添加执行权限后运行，或使用 AUR

05一键导入配置

从密钥页一键导入

  1. 安装并打开 ccSwitch，回到晚风API控制台的「API 密钥」页面。
  2. 找到刚创建的 API 密钥，点击右侧的「导入到 CCS」按钮。
  3. 浏览器询问是否打开外部应用时，选择始终允许并打开 ccSwitch。
  4. 在 ccSwitch 弹窗中确认供应商配置，点击「导入」并启用。
  5. 完全退出并重新启动终端，即可通过 API 使用。
点击「导入到 CCS」
确认打开 ccSwitch
如果浏览器没有自动唤起 ccSwitch，请确认软件已经安装并打开，然后重新点击「一键导入」。

06手动配置

如果一直无法一键导入配置，可使用下面的方式手动导入。

一键导入不可用时使用

  1. 在「API Keys」页面找到需要使用的密钥并复制 API Key。
  2. 打开 ccSwitch，选择需要使用的终端，点击添加按钮。
  3. 选择默认自定义配置并填写名称，例如「晚风API」。
  4. 官网链接填写 https://sub.wanfengai.shop/。
  5. API Key 粘贴刚刚复制的密钥。
  6. API 请求地址填写 https://sub.wanfengai.shop，无需开启「完整 URL」。
  7. 保存后测试模型，测试成功后点击「启用」。
复制 API Key 和 Base URL
在 ccSwitch 手动添加配置
配置保存成功后，请完全退出并重新打开 Codex、Claude Code 等客户端程序，使新配置生效。
TROUBLESHOOTING

常见问题

API Key 泄露了怎么办？

请立即删除泄露的 Key，创建新的 Key，并更新所有仍在使用旧 Key 的应用。

如何验证配置是否正确？

curl https://sub.wanfengai.shop/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

如何查看各分组状态？

点击控制台左侧菜单的「渠道状态」，即可查看各分组当前是否正常可用。

为什么返回 401？

通常是 API Key 无效、没有传入 API Key，或请求头格式不正确。

为什么返回 402？

通常是余额不足或当前账户额度不足。请充值、购买订阅或联系管理员处理。

为什么返回 429？

请求过于频繁，触发并发或速率限制。请降低请求频率后重试。

为什么返回 503？

通常是当前分组账号 token 额度用尽。可以更换其他可用分组后重试。

为什么返回 529？

上游服务繁忙或过载，请稍后重试。