AGTCloud API Docs
文档指南API Reference集成与资源更新与帮助

CC-Switch

使用 CC-Switch 管理和切换 AGTCloud 配置。

CC-Switch 是跨平台的本地配置管理工具，可以为 Claude Code、Codex 等编码工具保存多个 Provider，并将当前启用的配置写入相应工具的配置文件。通过它可以在 AGTCloud 和其他已保存配置之间切换，无需每次手动编辑文件。

本教程只介绍 Claude Code 与 Codex 的应用专属 Provider。请求会由对应编码工具直接发送到 AGTCloud，不启用 CC-Switch 的 Local Proxy、Failover、协议转换或 Universal Provider。

切换操作会修改本机工具配置

CC-Switch 会更新 Claude Code 或 Codex 的实时配置文件。首次使用前，请确认现有配置已经被正确导入，并在添加 AGTCloud 前导出一份备份。

准备工作

开始前，请确认你已经：

  • 安装并完成 Claude Code 或 Codex 的基础启动；
  • 注册并登录 AGTCloud；
  • 在 API Keys 页面创建 AGTCloud API Key；
  • 从模型广场复制当前 API Key 可见、且支持目标工具协议的模型 ID；
  • 准备一个不包含敏感代码和生产凭证的测试项目。

Claude Code 应选择支持 Anthropic Messages 的模型；Codex 应选择支持 OpenAI Responses 的模型。MODEL_ID 是需要替换的占位符，不是实际模型名称。

下载并安装 CC-Switch

只从 CC-Switch 官方网站 或 GitHub Releases 获取安装包。任何要求为 CC-Switch 本身充值、付费或提交登录凭据的网站和客户端都不是官方渠道。

  • 常规安装选择 GitHub Releases 中当前版本的 Windows MSI；
  • 不希望安装时可以选择 Windows Portable ZIP；
  • Portable 版本解压后运行 CC-Switch.exe；
  • 如果 Windows 阻止运行，请先检查文件来源和数字签名，不要关闭系统安全功能。

CC-Switch 负责管理配置，但不会替代 Claude Code 或 Codex 本身。请先确保目标编码工具能够正常启动。

首次启动与备份

检查自动导入结果

首次启动时，CC-Switch 会尝试导入本机已有的 Claude Code、Codex 等配置。分别打开对应应用页面，确认原有官方配置或自定义 Provider 已经显示在列表中。

保留原有 Provider

不要删除自动导入的官方配置。后续需要退出 AGTCloud 时，可以重新启用该 Provider 恢复原来的连接方式。

导出数据备份

进入 设置 → 高级 → 数据管理，使用当前版本提供的导出功能保存备份。备份文件可能包含 API Key 和其他敏感 Provider 信息，请保存在受信位置，不要上传到仓库或公开网盘。

本教程不要求直接编辑配置文件

CC-Switch 会负责写入相应工具的配置。不要为了套用其他平台的示例而覆盖 ~/.claude/settings.json、~/.codex/auth.json 或 ~/.codex/config.toml。

添加 AGTCloud Provider

在顶部选择需要配置的应用，点击右上角的添加按钮，然后使用“应用专属供应商”中的自定义配置。Claude Code 和 Codex 使用不同协议与 Base URL，应分别建立 Provider。

打开 Claude Code Provider 页面

在 CC-Switch 顶部选择 Claude Code，点击添加供应商，选择“自定义”或当前版本对应的自定义 Provider 入口。

填写连接信息

字段填写内容
Provider NameAGTCloud
Base URLhttps://api.agtcloud.cn
API Keyyour-api-key
Primary ModelMODEL_ID
Authentication使用 API Key，不使用 ANTHROPIC_AUTH_TOKEN

Base URL 只填写本页显示的 API Origin，不追加 /v1。Claude Code 会自行请求 /v1/messages。

处理模型映射

如果当前版本显示 Haiku、Sonnet、Opus 角色映射，首次可以将三个角色都映射到同一个已确认支持 Anthropic Messages 的 MODEL_ID。只有掌握多个模型的真实能力时，再分别设置不同模型。

保存但暂不启用代理

保存 Provider。不要开启 Local Proxy、Failover、协议转换或其他高级路由功能。

使用 API Key 认证

AGTCloud 的 Claude Code 配置使用 ANTHROPIC_API_KEY 对应的 API Key 认证。不要复制其他平台使用 ANTHROPIC_AUTH_TOKEN 或 Bearer Token 的配置。

CC-Switch Claude Code 供应商配置CC-Switch Claude Code 模型映射

启用并验证配置

启用 AGTCloud

返回对应应用的供应商列表，点击 AGTCloud 卡片上的“启用”。确认卡片显示“当前启用”或当前版本中的等效状态。

重新加载目标工具

  • Claude Code 通常可以检测配置变化，但建议新开一个会话进行验证；
  • Codex 需要关闭当前终端窗口，再重新打开终端并启动 Codex。

不要使用已经发送过请求的旧会话判断切换是否成功。

检查当前配置

在目标工具中执行：

/status

核对 Provider、Base URL、认证来源和模型 ID。Claude Code 不应显示重复 /v1；Codex 的 Base URL 应以单个 /v1 结尾。

发起只读测试

在包含 README.md 的安全测试项目中输入：

请读取 README.md，并用三点概括项目用途。不要修改任何文件。

能够正常返回结果，且没有发生未授权修改，说明基础连接已经建立。本步会产生正常的 API 用量。

CC-Switch Claude Code 配置已启用 CC-Switch Codex 配置已启用

使用系统托盘快速切换

CC-Switch 在系统托盘中为不同应用提供独立的 Provider 列表。右键点击托盘图标，进入 Claude 或 Codex 子菜单，再选择需要启用的 Provider。

托盘切换只是另一种配置入口，不要求启用 Local Proxy。切换 Codex 后仍应重新打开终端。

切回原有配置

  1. 在 CC-Switch 中打开 Claude Code 或 Codex 页面；
  2. 找到首次启动时导入的官方 Provider；
  3. 点击“启用”；
  4. Claude Code 新开会话确认恢复，Codex 重新打开终端确认恢复。

Claude Code 和 Codex 的 Provider 相互隔离。切换 Claude Code 不会自动修改 Codex，反之亦然。

常见问题

现象优先检查处理方式
找不到合适的安装包下载来源、操作系统和处理器架构只从 ccswitch.io 或官方 GitHub Releases 获取当前版本
原有 Provider 没有出现首次导入结果和原工具配置路径先确认 Claude Code 或 Codex 已经安装并存在配置，再重新打开 CC-Switch
启用时提示无法写入配置文件权限和占用状态关闭正在运行的目标工具，检查用户配置目录权限后重试
返回 401API Key 内容和认证方式使用有效 API Key；Claude Code 不要使用 ANTHROPIC_AUTH_TOKEN
返回 403Key 状态、账户权限和模型权限在控制台检查当前 API Key 与模型可用范围
返回 404Base URL、重复 /v1、完整 Endpoint 和模型 IDClaude Code 使用 https://api.agtcloud.cn；Codex 使用 https://api.agtcloud.cn/v1，不要填写完整请求路径
模型列表无法加载/v1/models 支持、网络和 API Key从模型广场复制当前 Key 可见的完整模型 ID 后手动填写
Claude Code 仍使用旧配置Provider 启用状态和旧会话缓存确认 AGTCloud 卡片为当前启用，然后新开 Claude Code 会话并执行 /status
Codex 仍使用旧配置终端是否重新启动关闭当前终端窗口，重新打开终端后再启动 Codex
普通对话成功但工具调用失败模型协议和工具调用能力为 Claude Code 选择支持 Anthropic Messages 与工具调用的模型；为 Codex 选择支持 Responses 的模型
Base URL 变成 /v1/v1应用类型与 URL 填写方式Claude Code 删除 /v1；Codex 只保留一个 /v1

遇到无法定位的问题时，请记录目标工具、请求时间、API Base URL、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key 或 CC-Switch 数据备份。

安全建议

  • 不要把 API Key 放入截图、日志、仓库或共享配置；
  • CC-Switch 数据导出可能包含敏感 Provider 信息，应作为凭证备份妥善保存；
  • 只从官方渠道下载安装 CC-Switch，不要向第三方客户端提交平台登录凭据；
  • 首次验证使用安全测试项目，并保持 Claude Code、Codex 的操作审批开启；
  • API Key 疑似泄露时，立即在控制台禁用或删除，然后创建新 Key。

下一步

集成与资源

查找第三方工具集成、SDK、开发工具和迁移资料。

Claude Code

在 Claude Code 中配置和使用 AGTCloud。

本页目录

准备工作下载并安装 CC-Switch首次启动与备份检查自动导入结果保留原有 Provider导出数据备份添加 AGTCloud Provider打开 Claude Code Provider 页面填写连接信息处理模型映射保存但暂不启用代理打开 Codex Provider 页面填写连接信息获取或手动填写模型保存标准 Provider启用并验证配置启用 AGTCloud重新加载目标工具检查当前配置发起只读测试使用系统托盘快速切换切回原有配置常见问题安全建议下一步