CC Switch 配置 Astra

CC Switch 适合管理 Claude Code、Codex 和 Gemini CLI 的多套供应商配置。Astra 侧只需要一把 API Key 和对应协议的 Base URL，剩下的配置交给 CC Switch 保存、切换和备份。

如果不使用 CC Switch，直接编辑客户端文件，请看手动配置 Astra。本文只讲 CC Switch 的 Provider、预览、同步和回滚。

**先分清两种配置：**下面填的是 CC Switch 的 Provider 表单或 JSON 编辑器；model_provider = "astra" 那种完整 TOML 是手动配置文档的写法，不要粘贴到 CC Switch 的 JSON 编辑器。CC Switch 会把 Provider 转换后写入客户端文件，Codex 的 provider id 通常是 custom。

推荐流程

1. 在 Astra 控制台的「API Key」页创建一把 Key，完整 Key 只显示一次。
2. 打开 CC Switch，切到要配置的应用，点击右上角 +。
3. 添加应用专属 Provider：名称填 Astra，Base URL 和 API Key 按下表填写；Codex 选择原生 OpenAI Responses，不要开启 Needs Local Routing；能看到 Fetch Models 时先拉取模型再选择。
4. 先预览配置，再确认保存。切换前建议先导出备份。
5. 启用 Astra Provider，重启对应 CLI。

这是 Astra 的直连模式：Codex 直接访问 Astra，不经过 127.0.0.1:15721，也不需要 CC Switch 本地路由进程持续运行。CC Switch 仍负责保存、切换和投影配置。

CC Switch 的 Universal Provider 可以把同一套配置同步到多个应用，但 Astra 在 Claude、Codex、Gemini 使用的 Base URL 路径不同。要分别填写路径时，使用应用专属 Provider；只有你的 CC Switch 版本支持按应用覆盖 endpoint 时才使用 Universal Provider。

Astra 字段

不要把 Key 预览值（例如 sk-abcd...1234）填入配置；那只是识别用，不能鉴权。

Claude Code

在 CC Switch 的 Claude Code Provider 中打开 JSON 编辑器，使用 Custom JSON：

{
  "model": "claude-sonnet-4-6",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.637274.xyz",
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

ANTHROPIC_AUTH_TOKEN 也可作为 ANTHROPIC_API_KEY 的替代字段。若把 Claude Code 切到 GPT 或 Gemini 模型，再加入对应的 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 和 ANTHROPIC_DEFAULT_OPUS_MODEL。模型名以 Astra 首页显示的可用模型为准。

Codex

在 CC Switch 的 Codex 面板添加或编辑第三方 Provider，填写 Name、API Key、Base URL 和 Model。不要把下面的 TOML 当成 CC Switch 表单输入；这是 CC Switch 切换后可能生成到本机的结果示意。

直连模式：把第三方 Token 写入 config.toml

在 Codex Provider 表单中选择原生 OpenAI Responses，关闭 Needs Local Routing。如果要保留 Codex 官方登录、手机遥控或官方插件，再打开 设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录。切换 Astra 后，第三方 Token 会写到当前 provider 的 experimental_bearer_token，Codex 直接访问 Astra：

model_provider = "custom"
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.custom]
name = "Astra"
base_url = "https://api.637274.xyz/v1"
wire_api = "responses"
experimental_bearer_token = "sk-xxx"

这里的 custom 是 CC Switch 为第三方 Codex Provider 使用的 provider id，name = "Astra" 才是界面展示名称。直连模式下 base_url 必须保持 https://api.637274.xyz/v1，不要改成 127.0.0.1，也不要填 wss://。CC Switch 版本或 Provider 选项可能额外生成模型目录、功能开关或 supports_websockets，不要手动覆盖它生成的完整文件。

兼容旧模式：Token 写入 auth.json

如果没有开启上面的保留登录开关，部分 CC Switch 版本会按旧兼容行为把第三方 Key 写入 ~/.codex/auth.json，并在 config.toml 使用 requires_openai_auth = true。这能调用 API，但会覆盖或失去官方登录态；不需要官方 Codex 功能时才使用：

{
  "OPENAI_API_KEY": "sk-xxx"
}

所以你看到 Token 在 config.toml 是正确的——直连模式也使用这条路径。详见 CC Switch 官方登录保留攻略。

什么时候才需要本地路由

只有上游不支持 Responses、而只支持 Chat Completions 时，才打开 Needs Local Routing 并启动 CC Switch 本地路由。此时 Codex 会先访问 http://127.0.0.1:15721/v1，CC Switch 再负责协议转换；Astra 不属于这种情况。

Gemini CLI

在 CC Switch 的 Gemini Provider 中使用 Custom JSON：

{
  "env": {
    "GEMINI_API_KEY": "sk-xxx",
    "GOOGLE_GEMINI_BASE_URL": "https://api.637274.xyz/v1beta"
  }
}

自动发现模型

如果 CC Switch 的 Provider 表单提供 Fetch Models，先填 Base URL 和 API Key，再点击发现模型。Astra 的 OpenAI 兼容模型列表来自 /v1/models；列表里没有的模型不要手填后强行调用。

修改与回滚

建议把一个客户端对应一个 Provider：Astra-个人、Astra-工作、Astra-测试。需要切换时切换 Provider，不要反复覆盖同一份配置文件。

修改前导出 CC Switch 备份；修改后如果 CLI 行为异常，先切回上一个 Provider，再检查 Base URL 是否多写或少写了 /v1。

CC Switch 的 Provider 导入、预览确认、Universal Provider 同步和备份机制可参考其官方配置文档。