手动配置 Astra

这份手册直接写最终配置文件，不依赖任何配置管理工具。适用于 Claude Code、Codex CLI 和 Gemini CLI。

如果希望用图形化 Provider 管理多套配置，请看 CC Switch 配置 Astra；本文只讲手动编辑文件。

注意：本文中的 model_provider = "astra" 是你手动命名的 Codex Provider。CC Switch 的第三方 Provider 通常会使用 custom 并自动生成文件，两者不要混用。

开始前

在 Astra 控制台创建 API Key。完整 Key 只显示一次，先保存到密码管理器。
备份原配置文件，再合并下面的字段。不要整文件覆盖，否则会丢掉 MCP、项目规则和其他本地设置。
把示例里的 YOUR_API_KEY 替换成完整 Key。sk-abcd...1234 只是预览值，不能鉴权。
改完后重启客户端。

地址怎么填

客户端 / 协议	配置值
Claude Code / Anthropic Messages	`https://api.637274.xyz`
Codex / OpenAI Responses	`https://api.637274.xyz/v1`
Gemini CLI / Gemini API	`https://api.637274.xyz/v1beta`

Claude Code 的地址不要加 /v1；Codex 必须带 /v1；Gemini 必须带 /v1beta。Codex 的 WebSocket 会从 HTTPS 地址自动升级，不要手填 wss://。

Claude Code

配置文件：

macOS / Linux：~/.claude/settings.json
Windows：%USERPROFILE%\\.claude\\settings.json

使用 Claude 模型

把下面字段合并到现有 JSON：

{
  "model": "claude-sonnet-4-6",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.637274.xyz",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

env 里已有其他变量时只追加或修改这两个字段。model 必须是 Astra 首页当前显示的可用模型。

使用 GPT / Gemini 模型

Claude Code 仍然走 Anthropic Messages 协议，只需要把模型映射到 Astra 暴露的模型：

{
  "model": "gpt-5.4-mini",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.637274.xyz",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4-mini",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

CLAUDE_CODE_ATTRIBUTION_HEADER=0 可以避免非 Claude 模型路径带入额外归因字段，减少缓存 miss。只映射实际在首页可用的模型。

Codex CLI

Codex 使用两个文件：

macOS / Linux：~/.codex/auth.json、~/.codex/config.toml
Windows：%USERPROFILE%\\.codex\\auth.json、%USERPROFILE%\\.codex\\config.toml

`auth.json`

合并或创建：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

auth_mode 填 apikey。不要填 chatgpt，那是本机 OpenAI 登录态，不是 Astra API Key。

`config.toml`

合并以下字段：

model_provider = "astra"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.astra]
name = "Astra"
base_url = "https://api.637274.xyz/v1"
wire_api = "responses"
supports_websockets = true

[features]
responses_websockets_v2 = true

model_provider 必须等于 model_providers.astra 的段名。已有 [features] 时只追加字段，不要重复创建同一个表。

如果 WebSocket 连接不稳定，先把 responses_websockets_v2 改为 false，回退到 HTTPS Responses 请求；Base URL 保持不变。

Gemini CLI

按客户端支持的方式设置环境变量：

export GEMINI_API_KEY="YOUR_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.637274.xyz/v1beta"

如果客户端使用配置文件而不是 shell 环境变量，写入同名字段：

{
  "GEMINI_API_KEY": "YOUR_API_KEY",
  "GOOGLE_GEMINI_BASE_URL": "https://api.637274.xyz/v1beta"
}

不要同时保留指向其他供应商的旧 GEMINI_API_KEY，否则 shell 中后加载的值会覆盖 Astra Key。

检查配置是否生效

先检查模型列表：

curl https://api.637274.xyz/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

如果返回 401，检查完整 Key、Header 和环境变量；如果模型列表没有目标模型，不要继续手填调用。

不同协议的最小连通性检查：

# OpenAI / Codex
curl https://api.637274.xyz/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","input":"ping"}'

# Claude Code / Anthropic
curl https://api.637274.xyz/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Gemini
curl "https://api.637274.xyz/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"ping"}]}]}'

修改和回滚

每次修改前保留一个带时间的备份，例如 config.toml.bak-2026-09-05。出现异常时先恢复备份，再检查三件事：

Base URL 是否多写或少写协议路径。
API Key 是否是完整值，而不是脱敏预览。
model 是否仍在 Astra 首页的可用模型列表中。

配置文件里的 MCP、项目规则、插件和本地偏好与 Astra 无关，始终保留原内容，只改本手册列出的字段。