Claude Code + Codex 如何配置，以及ccswitch的原理是什么

TP_base

703人浏览 · 2026-05-04 10:53:39

TP_base · 2026-05-04 10:53:39 发布

这篇文章记录一下我个人在配置 Claude Code（下面简称 CC）和 Codex 时遇到的坑。重点不是介绍工具怎么安装，而是讲清楚：终端读哪个配置文件、IDE 插件读哪个配置文件、Key 和 Base URL 放在哪里、服务器环境怎么排查配置是否生效。

适合场景：Windows 本地、Linux/云服务器、VS Code/Cursor/Windsurf 等 IDE 插件、中转 API 或自定义网关。

一、先说结论：配置排查先看“实际生效的文件”

很多问题不是 Key 错了，而是工具没有读取你以为的那个文件。

工具	终端/CLI 常用配置	IDE 插件常用配置	重点
Claude Code	`~/.claude/settings.json`，Windows 对应 `C:\Users\用户名\.claude\settings.json`	IDE 自己的 `settings.json`	CLI 和 IDE 可能不是同一个配置入口
Codex	`~/.codex/config.toml` + `~/.codex/auth.json`	项目目录下 `.codex/config.toml` + `.codex/auth.json`	项目级配置优先级更高，但需要信任项目后才会加载

如果你使用类似 ccswitch 这样的切换工具，本质上也是改这些配置文件。排查时不要只看工具界面，最好直接打开配置文件确认内容有没有真的写进去。

二、Claude Code 终端配置

在终端中使用 Claude Code 时，主要看用户目录下的：

Windows: C:\Users\用户名\.claude\settings.json
Linux/macOS: ~/.claude/settings.json

可直接保存的基础版本如下：

{
  "env": {
    "ANTHROPIC_BASE_URL": "",
    "ANTHROPIC_AUTH_TOKEN": "",
    "ANTHROPIC_MODEL": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": ""
  }
}

字段说明：

字段	作用
`ANTHROPIC_BASE_URL`	自定义 API 地址，常用于中转、代理或网关
`ANTHROPIC_AUTH_TOKEN`	自定义 `Authorization` 鉴权值，Claude Code 会自动按 Bearer Token 方式使用
`ANTHROPIC_MODEL`	默认模型名，通常填中转商支持的模型别名
`ANTHROPIC_DEFAULT_SONNET_MODEL`	覆盖 Sonnet 默认模型
`ANTHROPIC_DEFAULT_OPUS_MODEL`	覆盖 Opus 默认模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	覆盖 Haiku 默认模型

注意：如果只是普通 Anthropic API Key，也可能使用 ANTHROPIC_API_KEY。但很多中转场景会让你配置 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN，具体以中转商文档为准。

三、Claude Code IDE 插件配置

在 IDE 里使用 Claude Code 插件时，通常需要修改 IDE 自己的 settings.json。以 VS Code / Cursor 这一类编辑器为例，可以在设置 JSON 中加入：

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": ""
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": ""
    }
  ]
}

如果想同时固定插件位置和模型，可以使用完整版本：

{
  "claudeCode.preferredLocation": "panel",
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": ""
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": ""
    }
  ],
  "claudeCode.selectedModel": "opus[1m]"
}

这里用 jsonc 是为了说明字段含义。实际编辑器的 settings.json 通常支持注释，但如果你把内容放到严格 JSON 文件里，就不要写 // 注释。

四、Claude Code 常见坑

1. 终端能用，IDE 不能用

优先检查 IDE 的 settings.json，因为 IDE 插件不一定读取你终端里的环境变量或 ~/.claude/settings.json。

2. 配置改了但没生效

进入 Claude Code 后运行：

/status

这个命令可以查看当前加载了哪些配置层。如果文件格式错误，也更容易定位。

3. 服务器上不要把 Key 写进项目仓库

服务器上建议使用用户级配置：

~/.claude/settings.json

不要把包含 Token 的 .claude/settings.json 提交到 Git 仓库。如果必须放项目级配置，建议只放不敏感的工具权限、MCP、规则等内容，Key 仍然放环境变量或用户级私有配置里。

五、Codex CLI 配置

Codex CLI 的常见配置目录是：

Windows: C:\Users\用户名\.codex\
Linux/macOS: ~/.codex/

一般需要两个文件：

~/.codex/config.toml
~/.codex/auth.json

1. config.toml

下面是我个人常用的中转配置模板：

# 指定当前使用哪个模型服务商，必须和下面 [model_providers.xxx] 的 xxx 对应
model_provider = "中转商名称"

# 默认模型名，填官方模型名或中转商提供的模型别名
model = "gpt-5.5"

# 推理强度。支持范围以当前 Codex 版本和模型能力为准
model_reasoning_effort = "xhigh"

# 可选：部分隐私/ZDR 或中转场景会要求关闭响应存储
# 如果当前 Codex 版本不识别该字段，可以先注释掉再排查
disable_response_storage = true

# 工作区可写沙盒：允许 Codex 修改当前工作区文件，但不会直接放开全盘权限
sandbox_mode = "workspace-write"

# 自定义模型服务商配置
[model_providers.中转商名称]
name = "中转商名称"
base_url = ""
wire_api = "responses"
requires_openai_auth = true

字段说明：

字段	作用
`model_provider`	当前默认模型服务商 ID，需要对应 `[model_providers.xxx]`
`model`	默认使用的模型
`model_reasoning_effort`	推理强度，常见值有 `low`、`medium`、`high`、`xhigh`
`disable_response_storage`	关闭响应存储，常见于隐私/ZDR 或中转要求；是否支持以当前 Codex 版本为准
`sandbox_mode`	命令执行沙盒模式，`workspace-write` 比全权限更稳妥
`base_url`	中转商或自定义网关地址
`wire_api`	新版 Codex 推荐使用 `responses`
`requires_openai_auth`	使用 OpenAI 风格鉴权

如果你只是想覆盖内置 OpenAI Provider 的地址，新版本 Codex 也支持 openai_base_url；如果你要管理多个中转商，用 [model_providers.xxx] 更清晰。

2. auth.json

auth.json 里放 API Key：

{
  "OPENAI_API_KEY": ""
}

注意：这个文件不要提交到仓库。建议在项目根目录的 .gitignore 里加上：

.codex/auth.json
.claude/settings.local.json

六、Codex IDE 插件配置

在 IDE 中使用 Codex 插件时，可以在项目目录下新建：

项目根目录/.codex/config.toml
项目根目录/.codex/auth.json

项目级配置适合做“这个项目专用”的模型、沙盒、MCP 或规则配置。比如你希望某个项目固定走某个中转商，就可以放到项目下的 .codex/config.toml。

需要注意的是：Codex 会有配置优先级。一般来说，CLI 参数和 profile 优先级最高，其次是项目 .codex/config.toml，最后才是用户级 ~/.codex/config.toml。如果项目没有被信任，项目级 .codex/ 配置可能不会被加载。

七、本地和服务器配置建议

本地 Windows

Windows 上路径一定要看清楚用户名：

C:\Users\你的用户名\.claude\settings.json
C:\Users\你的用户名\.codex\config.toml
C:\Users\你的用户名\.codex\auth.json

如果你在 PowerShell、CMD、Git Bash、IDE 终端之间切换，环境变量可能不一致。遇到“终端 A 能用，终端 B 不能用”，先检查实际启动工具的那个终端环境。

Linux / 云服务器

服务器上优先用用户级目录：

~/.claude/settings.json
~/.codex/config.toml
~/.codex/auth.json

如果多人共用服务器，不建议把 Key 放到公共目录，也不建议使用 root 用户随便跑。最好每个人用自己的 Linux 用户，配置放在自己的 home 目录下。

八、排查顺序

遇到请求失败、模型不对、Key 不生效时，我一般按这个顺序查：

看当前运行环境：是在终端、IDE 插件、本地还是服务器。
看实际配置文件：确认改的是 ~/.claude、IDE settings.json、~/.codex 还是项目 .codex。
看 JSON/TOML 格式：少逗号、多逗号、中文引号都会导致配置失效。
看模型名：模型名必须是官方支持或中转商支持的值。
看 Base URL：注意是否带 /v1，这个以中转商要求为准。
看 Token：不要多写 Bearer ，有些工具会自动拼。
看配置优先级：项目级配置、profile、CLI 参数可能覆盖用户级配置。

九、总结

Claude Code 和 Codex 的配置问题，本质上大多是三个问题：

改错文件：终端和 IDE 不是同一个入口。
优先级覆盖：项目配置、profile、命令行参数可能覆盖用户配置。
敏感信息管理不当：Key 不要进仓库，服务器不要放公共目录。

我的建议是：先把终端 CLI 配通，再配 IDE 插件；先用最小配置跑通，再逐步加模型、MCP、沙盒和权限配置。这样排查成本最低。

参考资料

Claude Code Settings：https://code.claude.com/docs/en/settings
Claude Code Environment Variables：https://code.claude.com/docs/en/env-vars
Codex Config Basics：https://developers.openai.com/codex/config-basic
Codex Configuration Reference：https://developers.openai.com/codex/config-reference