更换 API key 或切换提供商，听起来像改一个值。它失败的原因更简单：同一份凭证存在于四个地方，而每个工具读取这些地方的优先级，你未必想过。如果你来这里是想知道如何在 Claude Code 里更换 API key，或者如何在 cc-switch 里为不同的编码 agent 切换提供商，机制都能归结为三个问题。这个值存在哪个层面？还有哪些地方仍指向旧值？你的会话历史会怎样？本指南针对 Claude Code、Codex CLI 和 CC Switch 回答这些问题，并且不重复首次配置的内容。
凭证可能存在的四个地方
动手改之前，先定位你真正要做的是哪一种变更。更换 key、切换提供商、切换账号看起来相似，触及的却是不同层面。轮换一个在同一台机器上被多个编码 agent 共用的 API key 是最难的情况，因为它会牵动其中不止一个。
Shell 环境变量。写在 shell profile 或终端里的 export。它们只对其被设置的那个终端会话生效，这就是为什么某次改动昨天看着生效、今天又不行了。
工具配置文件。Claude Code 设置文件里的env块；Codex 的config.toml。这些文件会持久保存，并且常常以取决于具体变量的方式压过 shell 里的值，因为优先级是按变量对逐个判定的，而不是只看来源层级。
凭证文件。Codex 把凭证保存在auth.json，位于它的主目录内。切换提供商时经常会改config.toml，却让这个文件仍指向旧账号，这就是经典的“我换了，但它还显示我原来的登录”报告。
切换器配置档。像 CC Switch 这样的管理器会保存整套提供商配置，并把对应的那一套写进各个工具。此时凭证住在管理器里，问题就变成了哪个配置档在生效。
到底该不该为廉价切换做架构，本身就是一个取舍，我们在聚合层与直连里比较过。本文假设你今天就要动手改点什么。
无论它在哪里，都假设它可能泄漏；卫生清单把隔离步骤集中在一处。
Claude Code：如何更换 API key 与切换端点
Claude Code 的文档对网关模式规定得很精确，照做就好，别猜。端点放在ANTHROPIC_BASE_URL中；对 String AI 这样的平台，它就是站点根地址，末尾不带/v1。凭证变量取决于网关签发的是什么，官方的接入指南讲得很清楚：ANTHROPIC_AUTH_TOKEN用于 bearer token 形式的凭证，ANTHROPIC_API_KEY用于 API key，而apiKeyHelper用于从 vault 或 SSO 流程获取轮换凭证的命令。放错变量的凭证会随一个网关不读的 header 发出，请求以 401 失败；遇到这种情况，换到正确的变量再重试。
变更过程中有两个细节容易踩坑。第一，网关凭证优先于已保存的 claude.ai 登录：用ANTHROPIC_AUTH_TOKEN时会立即生效，而用ANTHROPIC_API_KEY时，在交互模式下会先提示一次请求批准，之后才生效。第二，层面很重要。CLI 读取 shell 变量和设置文件，但 VS Code 扩展是在它自己的用户设置里配置的；而且按同一份文档，Slack 和云端会话始终使用 Anthropic 的 API，不属于网关部署的一部分：在云端会话的环境配置里设置的网关变量不会被应用。如果有人说他本地的改动在网页端毫无作用，这就是文档给出的原因，不是 bug。
在哪里设置这个值，决定了它能存活多久：shell export 只活一个终端会话，设置文件则在 Claude Code 运行的每个地方持续生效。设置系统还会在会话进行中重新加载若干类改动，包括像apiKeyHelper这样的凭证 helper，所以通过 helper 轮换无需重启即可生效；而另一个终端窗口里过期的 shell export 会悄悄把旧值留住。
Codex CLI：如何切换提供商与轮换凭证
实践中，Codex CLI 的切换提供商要动两个文件，而不是一个。提供商定义放在config.toml里，位于[model_providers.<name>]之下，字段包括base_url、wire_api和requires_openai_auth；凭证则单独保存在auth.json中，形式为OPENAI_API_KEY。String AI 的平台文档在字段层面展示了它的形态，base URL 以/v1结尾；动手改之前，值得打开官方配置参考看看当前的键列表：例如参考文档指出，wire_api只接受responses这一个受支持的值，而放在项目本地.codex/config.toml里的提供商键会被忽略，以用户级配置为准。最后这一点，解释了一整类“我改了，但什么都没发生”的报告。
切换的规则是：在同一次操作里同时改config.toml和auth.json。只改 base URL，旧账号的凭证还留在原处；只改凭证，旧端点还留着。又因为 CLI 在启动时读取配置，已打开的会话必须重启才能拿到新值，这也正是平台配置指南让你写完文件之后要做的事。
CC Switch：一键切换提供商，并保留会话历史
CC Switch 的存在，让这件事从“改文件”变成“做管理”。它是一款面向主流编码 agent 的跨平台桌面管理器，覆盖 Claude Code、Codex、OpenCode、OpenClaw、Grok Build、Hermes Agent 等；仓库明确说明了首次启动时会发生什么：它会把现有的 Claude Code、Codex、Gemini CLI 和 Grok Build 配置导入为一个名为default的提供商，并为这些工具各加一个官方提供商，因此已配置的内容不会丢失。
在此之上，切换被设计成一个动作：提供商预设填好那些显而易见的字段，Projects 功能则保存整套配置——提供商，以及（对 Claude Code 和 Codex 而言）MCP、skills 和 prompt 文件——于是整份配置可以从主页顶部的项目切换器一次性换过去。如果你要在里面把 String AI 接成一个提供商，平台的文档在字段层面描述了 Universal Provider 表单：名称、base URL、你的 API key 和一个默认模型，之后是一次 Health Check，在你依赖它之前先确认连接可用。细节都在官方的CC Switch 仓库里，关于当前行为，也应当以该工具自己的文档为准。
用一次最小请求验证改动
任何改动之后，都别急着一头扎进你最大的项目。先发一个小请求，这正是五步快速入门在首次调用时用的同一套纪律。确认三件事：
- 请求确实走了新端点。在 Claude Code 里，用
/status的输出就能看出当前生效的是网关凭证还是已保存的登录；在平台侧，用量记录里应当出现这笔请求，并挂在你预期的账号和 key 上。 - 会话仍然可用。开一个新会话，问点无关紧要的问题。如果旧会话行为异常，那就是该重启工具的信号，而不是继续改配置。
- 没有混用的凭证。在一台有多个层面的机器上，检查那些你没碰过的地方：另一个终端的 export、一个设置文件、一个切换器配置档、一个编辑器扩展。混用的配置是“这个窗口行、那个窗口不行”最常见的原因。
动手之前，先给你即将改动的文件和变量做个快速快照。两分钟的复制，决定了糟糕的改动会变成一次回滚，还是耗掉一个下午。
编码 agent 的会话历史迁移
编码 agent 的会话历史迁移，是没人愿意为它留时间的那一步，而诚实的起点是：会话存储归各个工具自己管。换提供商或换 key 是凭证层面的变更，它本身不会重写会话存放的位置。按 CC Switch 的 README，它的 Session Manager 正是为这个缺口存在的：可以从一个地方浏览、搜索并恢复每个工具的对话历史；README 也把边界说在前面，指出目前还不支持恢复 OpenClaw 和 Hermes 的会话，所以在围绕它做规划之前，先看当前的限制。就 Codex 而言，平台的配置说明描述了一个面向旧版基于 OAuth 会话的可选迁移脚本，其中还提到：这类会话在切换提供商后可能暂时显示为丢失，而实际上并未被删除；说明要求你先确认配置，执行前先预览。
切换期间的安全做法是：在新凭证下的新会话表现正常之前，保持旧配置完好；在工具自己的文档给出别的说法之前，把旧会话当作只读历史。凭证方面没有任何东西能保证历史会被带过去；那只由工具的存储层决定，而用一个会话做测试，比任何指南都更快给出答案。
排查：症状、层面、修法
下表把常见故障对应到最可能负责的层面。
| 症状 | 检查 | 修法 |
| --- | --- | --- |
| 切换后仍是旧账号 | 优先级与残留 | 检查其他终端窗口、设置文件、切换器配置档、编辑器扩展；某个窗口里过期的 export 会在那里覆盖你的新值 |
| 换 key 后返回 401 | 凭证变量类型 | bearer token 应放在ANTHROPIC_AUTH_TOKEN；API key 应放在ANTHROPIC_API_KEY；换过来再重试 |
| 每个请求都 404 | base URL 的路径约定 | OpenAI 兼容客户端需要带/v1路径；Claude Code 的 base URL 用站点根地址，不带这一段 |
| 找不到模型 | 模型标识 | 用平台文档里当前的模型列表，而不是凭记忆的名字 |
| 本地可用，Slack 或云端会话不可用 | 文档写明的限制 | 云端界面使用 Anthropic 的 API，会忽略网关变量；围绕它做规划，而不是跟它较劲 |
| 用量与预期不符 | 配置档未生效 | 用/status或管理器确认，然后到平台的用量记录里核对请求本身 |
接下来读什么
- 完全从零开始配置。从一把 key 通用于多个编码工具开始，那是首次配置的内容，本文有意不重复。
- 确认端点支持什么。用兼容性清单来核对你所依赖的层面。
- 把账目对齐。 用量与成本归因是你在切换之后确认请求和花费落在预期位置的方法。
一次只改一个层面，用一个小请求验证，并在新配置真正答话之前保留旧配置。