Codex / Claude Code 配置教程

0. 先确认 CC Switch 来源

只从官方渠道安装：ccswitch.io、GitHub 仓库、GitHub Releases。CC Switch 官方 README 写明它可管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes，并支持 Provider、MCP、Skills 统一管理。

安装本站下载的 CC-Switch-v3.16.5-Windows.msi，或去官方 Releases 下载对应系统版本。
打开 CC Switch，进入 Provider 管理，添加你的 API 服务。填入服务商给你的 Base URL、API Key、模型名。
优先使用 CC Switch 的“一键导入 / 切换 / 应用级代理接管”功能；若你的环境需要手动配置，再按下面的 Codex 和 Claude Code 官方字段填写。

1. Codex 配置

Codex CLI 和 IDE 扩展共用配置层。个人默认配置在 ~/.codex/config.toml，项目级配置可放在仓库的 .codex/config.toml。如果只想把内置 OpenAI provider 指向一个代理或网关，可用 openai_base_url；如果要定义新的 provider，则使用 [model_providers.<id>]。

方案 A：让内置 OpenAI provider 走代理

当 CC Switch 或你的网关提供 OpenAI 兼容地址时，先把 Key 放到环境变量，再设置 openai_base_url：

# macOS / Linux / WSL
export OPENAI_API_KEY="你的网关或 OpenAI Key"

mkdir -p ~/.codex
$EDITOR ~/.codex/config.toml

# ~/.codex/config.toml
model = "gpt-5.5"
openai_base_url = "http://127.0.0.1:你的端口/v1"

方案 B：定义一个 CC Switch / 网关 provider

当你希望明确选择 provider，或这个 provider 不只是改 OpenAI 的 base URL 时，用自定义 provider：

# ~/.codex/config.toml
model = "gpt-5.5"
model_provider = "ccswitch"

[model_providers.ccswitch]
name = "CC Switch Gateway"
base_url = "http://127.0.0.1:你的端口/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

注意：wire_api = "responses" 适用于支持 OpenAI Responses API 的代理。若你的服务只支持 Chat Completions，去掉这一行或按服务商说明配置；Codex 官方手册说明 Chat Completions 支持已处于弃用路径，后续会移除。

验证 Codex

codex --version
codex -m gpt-5.5

进入 Codex 后发一个短问题，确认返回正常。若需要在远程或无浏览器机器登录 Codex，官方手册建议使用 codex login --device-auth，或在有浏览器的机器登录后安全复制 ~/.codex/auth.json。

2. Claude Code 配置

Claude Code 官方文档把网关配置分成两类变量：ANTHROPIC_BASE_URL 指向网关；凭据按网关要求选择 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY。

Bearer Token 网关

export ANTHROPIC_BASE_URL="http://127.0.0.1:你的端口"
export ANTHROPIC_AUTH_TOKEN="你的网关 token"

x-api-key 网关

export ANTHROPIC_BASE_URL="http://127.0.0.1:你的端口"
export ANTHROPIC_API_KEY="你的网关 key"

持久化到 Claude Code settings

个人全局配置放在 ~/.claude/settings.json。不要把真实 key 写进项目的 .claude/settings.json，因为它通常会提交给团队。

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:你的端口",
    "ANTHROPIC_AUTH_TOKEN": "你的网关 token"
  }
}

验证 Claude Code

claude --version
claude doctor
claude

进入 Claude Code 后运行 /status，确认能看到 Anthropic base URL 和对应凭据来源。官方文档建议先用 curl 直连网关验证：

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

如果你的网关使用 x-api-key，把 Authorization 头替换为 x-api-key: $ANTHROPIC_API_KEY。

3. Windows 建议路径

工具	Windows 路径 / 命令
Codex 配置	`%USERPROFILE%\.codex\config.toml`
Claude Code 配置	`%USERPROFILE%\.claude\settings.json`
Claude Code 安装	PowerShell：`irm https://claude.ai/install.ps1 \| iex`；或 WinGet：`winget install Anthropic.ClaudeCode`
推荐 shell	Claude Code 官方文档建议 Windows 可原生运行，也可在 WSL 2 里运行；如果使用 Git for Windows，可让 Claude Code 使用 Git Bash。

4. 常见问题

CC Switch 已经“接管”应用，还需要手写配置吗？

通常不用。先用 CC Switch 的可视化开关验证 Claude Code / Codex 是否已经正常切换。只有在工具没有读到 CC Switch 写入的配置，或你需要固定某个项目/某台机器的网关时，再手写上面的配置。

Key 应该写在哪里？

个人机器可用用户级配置或环境变量。团队仓库不要提交真实 key；项目级文件只放共享的非敏感策略，真实凭据放个人环境变量、系统凭据库或公司密钥管理工具。

如何判断是 Base URL 错了还是 Key 错了？

先用 curl 直接打网关。连不上通常是 URL、端口、代理或防火墙问题；返回 401 通常是 key/token 放错变量或凭据无效；返回“unknown model”至少说明 URL 和凭据已经通过认证，下一步检查模型名。

官方资料

CC Switch 官网：https://ccswitch.io/
CC Switch GitHub：https://github.com/farion1231/cc-switch
OpenAI Codex Manual：https://developers.openai.com/codex/codex-manual.md
Windows 版 Codex App 官方下载：Microsoft Store installer
Claude Code Settings：https://code.claude.com/docs/en/settings
Claude Code LLM Gateway：https://code.claude.com/docs/en/llm-gateway-connect
Claude Code Setup：https://code.claude.com/docs/en/setup