快速开始

通用配置步骤

推荐路径

如果你不想手动维护每个 CLI 的配置文件，优先使用 CC-Switch。它可以把供应商、API Key、请求地址和本地代理集中管理。

CherryStudio 用户

如果你只需要配置 CherryStudio，可以直接跳到 CherryStudio 教程，按步骤填写 API Key、API 地址并获取模型列表。

1. 下载并安装 CC-Switch

下载 CC-Switch

点击下载按钮进入下载页面（可能需要梯子）以后往下翻找到图中的文件列表，选择最适合你的文件下载并且安装/解压。

CC-Switch 下载列表选择截图

2. 配置渠道商

  1. 准备工作：先准备好 API 请求地址和 API Key(令牌)。
    API 请求地址 https://api.aiwelink.cn

    API Key(令牌)获取：登录 Aiwelink 后台后在令牌管理页面生成密钥。

    点击 令牌管理-添加令牌。

    令牌管理页面截图 1

    输入名称并选择分组(推荐直接 Auto)，然后点击创建。

    令牌管理页面截图 2

    复制对应的令牌，准备填入 CC-Switch。

    令牌管理页面截图 3
  2. 打开刚刚安装/解压好的 CC-Switch，切换到 OpenAI 页面，然后点击右上角添加按钮来添加一个配置。
    CC-Switch OpenAI 页面添加配置截图
  3. "预设供应商" 保持默认的 "自定义配置"，填入 API Key 和 API 请求地址。
    CC-Switch 自定义配置填写截图 1
    CC-Switch 自定义配置填写截图 2
  4. 回到主界面，点击启用按钮来启用刚刚添加的配置。

3. 测试配置是否生效

在 CC-Switch 配置选择界面可以点击测试按钮来测试配置是否成功。

CC-Switch 测试配置截图

出现报错?点击查看常见报错解决方法

4. 前往配置客户端

Codex Cli (命令行) Codex 桌面端 VSCode Codex插件 OpenCode CherryStudio

客户端配置

Codex Cli (命令行)

这里合并 Codex CLI 的安装、配置目录、配置文件内容和模型提醒。

执行环境

下面的步骤默认都在 Windows 或 macOS 的终端里完成。

1. 检查 Node.js

先运行下面命令，确认本机已经安装 Node.js。只要能输出版本号，就说明环境正常。

node -v
如果没有 Node.js

如果上面这条命令没有输出版本号，可以直接在终端里安装，然后重新打开终端再执行 node -v 和 npm -v 检查。

不想用命令行?通过官网直接下载安装-> 打开官网

在管理员终端里运行：

winget install OpenJS.NodeJS.LTS

安装完成后，重新打开终端，检查是否生效：

node -v
npm -v

2. 安装 Codex CLI

先把 Codex CLI 装好，后面的命令行配置步骤都会基于它继续进行。

npm i -g @openai/codex@latest

3. 测试运行

打开终端，运行下面的命令。只要 Codex CLI 能正常拉起界面或进入对话，就说明安装阶段没有大问题。

codex

客户端配置

Codex 桌面端

1. 打开微软商店

在 Windows 里打开 Microsoft Store。

打开 Microsoft Store 搜索入口截图

2. 搜索 Codex 并下载安装

在商店里搜索 Codex，找到对应应用后下载安装。

Microsoft Store 搜索 Codex 截图 1
Microsoft Store 安装 Codex 截图 2

3. 直接打开 Codex 使用

安装完成后直接打开 Codex 桌面端开始使用。

打开 Codex 桌面端截图

4. 注意事项

避免配置文件混乱
  • 一定要先配置好 CC-Switch 再打开 Codex 桌面版，否则可能导致 Codex 配置文件混乱。
  • 需要切换或修改 CC-Switch 的配置时，一定要确保后台没有 Codex 桌面版进程，同样是为了防止 Codex 配置文件混乱。

客户端配置

VSCode Codex插件

1. 打开 VSCode 的插件商店

打开 VSCode 的插件商店，搜索 codex，下载并安装第一个插件。

VSCode 插件商店搜索并安装 Codex 截图

2. 打开 Codex 插件

安装完成以后，在右侧侧边栏找到 CODEX 插件并打开。

VSCode 右侧侧边栏打开 Codex 插件截图

客户端配置

在 OpenCode 中配置使用

OpenCode 已经并入 “客户端配置” 分类。这里保留原文档的实际操作步骤，但不再依赖站内图片和组件。

1. 下载预配置压缩包

OpenCode 资源

QuickConfiguration.zip

压缩包里包含 opencode.json 和 plugins 目录。

下载压缩包

2. 修改 opencode.json

分别在 Gemini、Claude、GPT 这三部分填入对应 API Key，然后保存。

填写密钥时的注意点

生成 API Key 时要选对你准备使用的 Aiwelink 渠道，文档里注明“可用模型”保持默认即可。

3. 找到 OpenCode 配置目录

首次配置先做这两步 
npm i -g opencode-ai
opencode
start "" "%USERPROFILE%\.config\opencode"

4. 复制文件

把你刚修改好的 opencode.json 和 plugins 目录整体复制到 OpenCode 的配置目录里。

5. 测试

opencode
/models

客户端配置

在 CherryStudio 中配置使用

CherryStudio 是图形化 AI 客户端。按下面步骤下载、安装，然后把 Aiwelink 的 API Key 和 API 请求地址填到 OpenAI-Response 类型的提供商里。

1. 下载 CherryStudio

打开 CherryStudio 官网

进入 CherryStudio 官网后，点击下载按钮获取安装包。也可以通过官方文档下载页或 GitHub Releases 获取不同系统的安装包。

官网首页 官方下载说明 GitHub Releases
CherryStudio 官网下载按钮截图

2. 安装 CherryStudio

运行下载好的安装包，安装选项可以选择“仅为我安装”；安装路径建议不要放在 C 盘，方便后续管理。

CherryStudio 安装选项截图
CherryStudio 安装路径选择截图

3. 打开设置入口

安装完成后打开 CherryStudio，点击右上角齿轮图标进入设置。

CherryStudio 设置入口截图

4. 添加 Aiwelink API 提供商

  1. 进入左侧 模型服务，点击底部 添加。
  2. 提供商名称可以自行命名，例如 Aiwelink、测试 或其他方便识别的名称。
  3. 提供商类型选择 OpenAI-Response，然后点击确定。
CherryStudio 添加提供商入口截图
CherryStudio 添加提供商类型选择截图
CherryStudio 添加 OpenAI-Response 提供商示例截图

5. 填写 API Key 和 API 地址

在新建的提供商里填写 Aiwelink 后台获取的 API Key，并把 API 地址填写为下面这个地址。

API 请求地址 https://api.aiwelink.cn
CherryStudio 填写 API Key 和 API 地址截图

6. 获取并添加模型列表

填写 API Key 和 API 地址后，点击 获取模型列表。弹出的模型窗口里可以点击右侧加号，把需要的模型添加到 CherryStudio。

CherryStudio 获取模型列表按钮截图
CherryStudio 模型列表添加模型截图
CherryStudio 全部选择模型后的效果截图
CherryStudio 提供商配置完成效果截图

7. 设置默认模型

进入左侧 默认模型，按需要选择默认助手模型、快速模型和翻译模型。默认助手模型也可以创建角色后再切换。

CherryStudio 默认模型设置截图

翻译模型可以选择可用模型，推荐使用响应快、成本低的模型；如果要用官方 DeepSeek 模型，需要先按下方补充步骤配置 DeepSeek 官方 API。

CherryStudio 翻译模型设置截图

8. 可选：修改翻译提示词

如果需要把输入内容快速翻译成英文，可以打开翻译设置，把提示词里的目标语言改成 {English}。后续在输入框输入 prompt 后，点击右侧翻译按钮即可触发翻译。

CherryStudio 翻译提示词默认状态截图
CherryStudio 翻译提示词改为 English 截图
CherryStudio 翻译提示词下划线内容说明截图

9. 开始使用 CherryStudio

回到首页后，可以点击添加助手或选择已有助手；顶部可以选择模型，输入框底部可以使用附件、联网搜索、临时模型调用、翻译 prompt 等功能。

CherryStudio 助手选择和提示词说明截图
CherryStudio 话题和输入框功能说明截图

10. 可选：配置 DeepSeek 官方 API

如果你要使用 DeepSeek 官方平台的模型，可以在模型服务里搜索或下划找到 DeepSeek 官方服务，填写 DeepSeek 平台获取的 API Key，并把 API 地址设置为 https://api.deepseek.com。

DeepSeek 官方 API 地址 https://api.deepseek.com
CherryStudio 搜索 DeepSeek 官方服务截图
CherryStudio DeepSeek 官方 API 配置截图

常见问题

常见问题

请求报错相关

503

特征/关键词：unexpected status 503 Service Unavailable: No available channel for model gpt-XXX under groupup XXX

原因：该令牌(API Key)不支持使用这个模型，或者说令牌选择的分组下没有这个模型。

解决方案：确认 Key 的分组下是否有这个模型，切换需要使用的模型对应的分组。

Selected model is at capacity.

特征/关键词：Selected model is at capacity. Please try a different model.

原因：官方该模型负载较高，被暂时中止。

解决方案：直接重试即可。

stream disconnected

特征/关键词：stream disconnected before completion: stream closed before response.completed

stream disconnected before completion: error sending request for url (https://XXXXXXXXX)

原因：

  1. 网络波动/不稳定导致的断连。常见于平时都在正常用，突然一下出现该报错。
  2. API 请求地址设置得不正确。常见于刚配置完开始尝试直接出现该报错。

解决方案：

  1. 如果是第一种情况，直接重试或者重新打开/关闭一下梯子即可。
  2. 如果是第二种情况，需要去检查配置文件是否有误，建议在关闭所有 Codex 相关进程的情况下，通过 CC-Switch 重新添加一份配置。
  3. 如果长期无法解决可呼叫技术支持。
flagged for potentially high-risk cyber activity

特征/关键词：stream disconnected before completion: This request has been flagged for potentially high-risk cyber activity. Learn more here: https://platform.openai.com/docs/guides/safety-checks/cybersecurity

原因：5.5 新版的云端审核，不允许进行网络安全相关工作。

解决方案：暂无，推荐切换回 5.4。

客户端相关