企业官网建设流程全解析

很多开发者在第一次接触 Claude Code 的时候，会遇到一个非常实际的尴尬：官方默认配置用得好好的，但一旦你想在“官方 Anthropic 接口”和“公司内部网关”、在不同模型服务商之间来回切换，整个人就懵了。改环境变量、改配置文件、重启终端、再确认环境有没有生效，一套流程下来，比写代码本身还累。

CC-Switch 就是冲着这个问题来的。它解决的不是“如何安装 Claude Code”，而是“Claude Code 装好之后，如何高效管理多套 API 配置”。说得更直接一点：如果你只是用默认账号，从头到尾不需要 CC-Switch；但只要你需要在多个 API 端点、多套账号配置、不同模型服务之间切换，CC-Switch 就能把这些操作从“改文件 + 重启终端”压缩成“点一下按钮 / 执行一条命令”。

这篇文章会从零开始，把 Claude Code 安装、CC-Switch 下载与配置、多配置切换、会话上下文保留、常见故障排查完整走一遍。文章不是只告诉你“敲什么命令”，还会解释每一个操作背后的配置文件逻辑，让你在遇到报错的时候，知道从哪里下手。

1. 这篇文章真正要解决的问题

先说说我为什么认为 CC-Switch 值得单独写一篇教程。

Claude Code 的本质是一个运行在终端里的 AI 编程助手，它通过调用 Anthropic 的模型接口来完成任务。工具本身安装并不复杂，真正麻烦的是配置管理。任何一个长期使用 Claude Code 的开发者，迟早会遇到下面这几类场景：

第一类是多 API 端点切换。你本地开发时直连官方接口，到了公司环境，又需要走公司统一的模型网关，网关地址、密钥都和官方不同。每次切换都要重新设置ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这类环境变量，一旦忘记改，就会出现“明明配了新地址，实际跑的还是旧地址”的情况。

第二类是账号和密钥隔离。有的开发者个人环境和团队环境共用同一台电脑，个人密钥和团队密钥不能混在一起写进同一个全局配置。如果每次都手动改settings.json，误提交到 Git 仓库的风险会直线上升。

第三类是对话上下文的连续性。不少用户发现，通过切换工具换了配置之后，之前对话的上下文好像“丢了”。这其实不一定是真的丢了，而是会话恢复方式和配置切换的姿势不对。这个问题我在后面的常见问题章节会专门讲。

我的判断是：CC-Switch 真正的价值不是“省掉一次 export 命令”，而是把 Claude Code 的配置从“人肉维护”升级为“可视化、可回滚、可复用”的工程化手段。它适合的读者，不是刚装好 Claude Code 的新手，而是那些已经跑了几天真实项目、开始感觉到配置切换成本的人。

读完这篇文章，你应该能完成三件事：

1. 独立安装 Claude Code，理解它的配置加载逻辑。
2. 安装 CC-Switch，把多套 API 配置集中管理起来。
3. 掌握切换配置的正确姿势，包括如何保留和恢复历史会话上下文。

2. 基础概念与核心原理

2.1 Claude Code 是什么

Claude Code 是 Anthropic 推出的终端 AI 编程工具。它不是一个普通的聊天界面，而是一个可以直接读写项目文件、执行命令、运行测试的 Agent 型工具。你可以在终端里启动它，让它理解项目结构、修改代码、跑构建命令，甚至处理 Git 操作。

从工程角度看，Claude Code 的本体是一个 Node.js 命令行程序。它会读取你的配置文件，确定当前应该使用哪个 API 地址、哪个密钥、哪些模型参数，然后向模型服务端发起请求。

2.2 CC-Switch 是什么

CC-Switch 是一个面向 Claude Code 的配置切换管理工具。你可以把它理解成一个“配置路由器”：它把多套 API 配置保存起来，当你需要切换到某一套时，它会帮你把对应的配置写入 Claude Code 真正读取的位置，从而实现快速切换。

CC-Switch 有桌面端，也有不同的发行版本。不同的版本界面和功能可能略有差异，但核心理念是一样的：管理多套 provider 配置，一键应用到 Claude Code。

2.3 两个工具之间的边界

这里要特别强调一个容易混淆的地方：CC-Switch 不是 Claude Code 的插件，也不参与实际请求的转发。它的工作止步于“把配置写好”，真正发起请求的仍然是 Claude Code 本身。

这个边界非常重要，因为它决定了排错思路。如果 CC-Switch 切换之后，Claude Code 仍然使用旧配置，问题大概率出在“配置文件确实写了，但 Claude Code 没重新加载”或者“配置写入位置不对”。你不要第一时间怀疑 CC-Switch 坏了，而应该沿着配置文件的读取链去排查。

3. 环境准备与前置条件

在动手之前，先确认你的电脑满足最低要求。Claude Code 目前对主流桌面操作系统都有支持，包括 Windows、macOS、Linux。这篇文章的步骤以 macOS / Linux 终端为主，Windows 用户建议使用 PowerShell 或 Windows Terminal，并将命令中的路径替换为对应系统路径。

需要准备的工具如下：

• Node.js 16 或更高版本，建议使用 LTS 版本。
• npm，通常随 Node.js 一起安装。
• 一个可用的命令行终端。
• 能够访问目标模型 API 的网络条件，以及对应的 API Key。

版本说明：Claude Code 和 CC-Switch 都在快速迭代，文章中的命令和配置结构在写作时是通用的，但具体版本号请以你安装时的实际版本为准。遇到版本差异时，优先查看官方文档。

先验证 Node.js 环境：

node -v npm -v

如果系统提示找不到 node 或 npm，说明 Node.js 还没有安装，需要先去 Node.js 官网下载对应系统的 LTS 版本。安装完成后，重新打开终端，再次执行上面的命令确认版本号正常输出。

4. 安装 Claude Code 并验证基础配置

4.1 全局安装 Claude Code

Claude Code 的官方安装方式非常统一，通过 npm 全局安装即可：

npm install -g @anthropic-ai/claude-code

安装完成后，验证一下版本：

claude --version

如果能够正常输出版本号，说明安装成功。如果提示命令找不到，需要确认 npm 的全局 bin 目录是否在系统 PATH 中。macOS 和 Linux 下，常见的全局 bin 路径是/usr/local/bin或/usr/lib/node_modules对应的 bin 目录。

4.2 理解 Claude Code 的配置文件加载顺序

Claude Code 的配置分为几个层级，后面的配置会覆盖前面的配置。大致加载顺序如下：

1. 命令行参数。
2. 项目级配置：项目目录下的.claude/settings.json。
3. 用户级配置：用户主目录下的~/.claude/settings.json。
4. 环境变量。

在这个体系中，settings.json是整个配置的核心。CC-Switch 所做的工作，本质上就是把选中的 provider 配置写入到用户级或项目级的settings.json，或者帮你生成对应的环境变量组合。

你可以用下面的命令查看当前生效的配置：

claude config list

4.3 官方配置登录方式

如果你是官方 Anthropic 账号，可以直接使用 Claude Code 的登录流程。在终端输入：

claude

首次启动时，Claude Code 会引导你完成认证。认证成功后，工具会自动使用账号相关的凭证发起请求。这一步跑通之后，再往下配置 CC-Switch 才会有明确的意义，因为你至少已经拥有了一套可用配置作为对照。

5. 核心概念：一套可被切换的 API 配置包含哪些字段

在使用 CC-Switch 之前，你需要先理解一套完整的 API provider 配置包含哪些核心字段。这样无论 CC-Switch 界面长什么样，你都能看懂它让你填的内容是什么。

一套典型配置通常包含以下信息：

• 配置名称：用于在 CC-Switch 中标识这套配置，例如“官方直连”或“公司网关”。
• API 地址（Base URL）：Claude Code 发起请求的目标地址。
• API Key：访问该地址所需的认证密钥。
• 模型标识：可选，用于指定默认使用的模型名称。
• 请求头或额外参数：部分网关需要额外的请求头字段。

如果你手动配置 Claude Code 使用某一套 API，通常的做法是在~/.claude/settings.json中写入对应的环境变量块。下面是一个典型的配置示意：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.anthropic.com", "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxxxxxxx", "ANTHROPIC_API_KEY": "sk-ant-xxxxxxxx" } }

这里最关键的是env字段。Claude Code 启动时会把env里的内容合并到进程环境中，从而影响实际请求。

CC-Switch 的工作方式就是：在它的界面或配置文件中存放多套这样的 provider 信息，当你选择其中一套时，它把对应的ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY等字段写入 Claude Code 的配置文件中。你不需要自己打开 JSON 文件去改。

6. CC-Switch 的安装与配置方法

6.1 下载和安装 CC-Switch

CC-Switch 的安装方式以发行版安装包为主。你可以在项目的官方发布页面找到对应系统的安装包，macOS 使用 dmg 或 pkg，Windows 使用 exe 或 msi，Linux 使用 deb 或 AppImage。

安装完成后，打开 CC-Switch。第一次启动时，它会让你确认 Claude Code 配置文件的路径。这里有一个容易出错的点：Claude Code 的配置文件路径不同版本略有差异，一般默认是用户主目录下的~/.claude/目录。如果你之前自定义过 Claude Code 的配置目录，需要在这里把它改成实际路径。

另外，CentOS 7.9 这种较老的 Linux 发行版，如果直接运行新版 CC-Switch 安装包报 GLIBC 版本错误，大概率是系统基础库版本过低，建议在安装前检查系统版本和图形环境，或者考虑使用支持范围内较新的 Linux 发行版。

6.2 创建第一套 provider 配置

打开 CC-Switch 后，一般会看到 provider 列表和新增按钮。点击新增配置，开始创建你的第一套配置。

下面是一个常见的配置示例，你可以对照着理解每一项的含义。不同版本的 CC-Switch 界面字段可能叫法略有不同，但核心含义一致。

{ "name": "Anthropic 官方", "provider": "anthropic", "baseUrl": "https://api.anthropic.com", "apiKey": "sk-ant-xxxxxxxx", "models": ["claude-sonnet-4-20250514"] }

如果你的场景是接入兼容 OpenAI 协议的公司网关，配置可能长这样：

{ "name": "公司网关", "provider": "openai-compatible", "baseUrl": "https://llm-gateway.example.com/anthropic", "apiKey": "sk-gateway-xxxxxxxx", "models": ["claude-sonnet-4-20250514"] }

这里要先说一个容易踩的坑：不是所有“兼容 OpenAI 协议”的网关都能直接被 Claude Code 使用。Claude Code 的请求格式有自己的一套规范，网关必须能正确处理 Anthropic 风格的请求。如果你配置了公司网关之后，Claude Code 报出请求格式错误，不要急着怪 CC-Switch，先确认网关对 Anthropic 接口的兼容程度。

6.3 应用配置到 Claude Code

创建好配置后，在 CC-Switch 列表中点击“应用”或“切换”。这一步的动作，就是把选中的配置写入 Claude Code 的配置文件。

应用完成后，你可以手动检查一下配置文件，确认内容确实被修改了：

cat ~/.claude/settings.json

如果配置正确，你应该能看到env字段中的 API 地址和密钥都变成了刚才选中的 provider 的值。

这里特别提醒：如果你同时打开了多个终端窗口，修改配置后，已经启动的 Claude Code 进程不一定能立即感知到变化。最稳妥的做法是，切换配置之后，关闭旧终端里的 Claude Code 进程，重新启动。

7. 用 CC-Switch 管理多套配置的完整实战流程

7.1 场景设定

假设你现在有两套配置：

• 配置 A：官方 Anthropic 直连，用于个人开发。
• 配置 B：公司内部模型网关，用于团队项目，密钥和管理规范都不同。

你希望在不同的项目目录下，分别使用不同的配置。这是 CC-Switch 最典型的用法。

7.2 创建配置并验证

第一步，在 CC-Switch 中分别创建配置 A 和配置 B，填入各自的 Base URL 和 API Key。注意，这里填入的密钥一定要严格保密，不要截图发到群里，也不要提交到 Git 仓库中。

第二步，先应用配置 A，然后启动 Claude Code，执行一个最简单的测试任务：

claude

输入一句“你好，请确认你已经正常工作”，观察模型是否能正常回复。这一步验证的是“配置 A 链路是通的”。

第三步，退出 Claude Code，回到 CC-Switch，应用配置 B。再次启动 Claude Code，重复同样的测试。如果配置 B 也能正常回复，说明两套配置都已经可用。

7.3 在项目目录中使用不同的配置

在实际项目中，更合理的做法是把 provider 的选择和项目绑定在一起。比如，你在/workspace/personal-project下工作时使用配置 A，在/workspace/company-project下工作时使用配置 B。

Claude Code 支持项目级配置文件，路径是项目目录下的.claude/settings.json。你可以在项目目录下手动创建这个文件，或者在使用 CC-Switch 应用配置时，选择写入到项目级配置而不是用户级配置。

如果 CC-Switch 支持按项目写入配置，建议优先使用这个能力，因为项目级配置更不容易影响其他项目。如果没有这个功能，切换配置后记得在离开项目目录前切回默认配置，避免把公司网关的密钥带到个人项目中。

7.4 验证配置是否真的生效

切换配置后，如何确认当前生效的确实是目标配置？最直接的方法是查看配置内容：

claude config get

或者直接打开配置文件：

cat ~/.claude/settings.json

还有一种更彻底的验证方式：在下发请求时，你自己在代码中打印或记录请求的目标地址。不过对于日常使用，看配置文件加上跑一次对话测试已经足够。

8. 运行结果与效果验证

配置正确时，使用 Claude Code 的体验应该是流畅的。你在终端输入问题，模型返回结果，不会出现认证错误或请求 401 的情况。

如果一切正常，你会在终端看到类似这样的输出流程：

• 输入claude启动工具。
• 工具读取配置并初始化会话。
• 输入问题后，模型正常返回文本。
• 工具能够正常感知项目目录中的代码文件。

这里的验证重点是“请求链路是否通”。如果配置 B 返回了 401 或 403，不要怀疑工具本身，优先检查 API Key 是否有权限、Base URL 是否正确。

如果切换配置后，Claude Code 报错“Invalid API Key”或“Authentication failed”，第一步应该看刚才写入的settings.json中的密钥和地址是否与实际配置一致，第二步看目标网关的日志，确认请求是否到达了服务端。

9. 常见问题与排查思路

9.1 切换配置后，Claude Code 仍在用旧配置

这是最高频的问题。可能原因有三个：

• CC-Switch 写入配置后，Claude Code 进程还在运行，没有重新加载配置。
• 用户级配置和项目级配置同时存在，项目级配置覆盖了用户级配置。
• 环境变量优先级高于配置文件，终端里残留了旧的ANTHROPIC_API_KEY。

排查方式：先关掉所有 Claude Code 进程，再执行env | grep ANTHROPIC检查终端环境变量，最后查看settings.json确认写入位置。

9.2 通过 CC-Switch 切换账号之后，之前对话的上下文不能加载

这个问题在社区里讨论得很多。先说结论：切换配置本身不会删除你的本地会话历史，但也不会自动把旧会话恢复到新的 provider 下。

Claude Code 的对话历史是按本地会话文件保存的。切换配置后，如果你直接新建一个会话，那它就是一个全新的会话，和旧会话没有任何关联。如果你希望继续之前的对话，正确的做法不是“切回旧配置”，而是使用 Claude Code 的会话恢复功能。

在终端中恢复历史会话：

claude --resume

运行后，Claude Code 会列出最近的历史会话，你选择需要继续的那一个即可。注意，这个操作和你当前使用哪套 provider 配置没有直接关系，只要会话文件还在，就能恢复。

9.3 配置文件内容变成了非法 JSON

CC-Switch 写配置时如果遇到进程被强制退出，或者同时有两个工具在写同一个settings.json，可能导致配置文件损坏。现象是 Claude Code 启动直接报 JSON 解析错误。

处理方式：先备份当前文件：

cp ~/.claude/settings.json ~/.claude/settings.json.bak

然后重新通过 CC-Switch 应用一次配置，让它重新生成一份合法的 JSON。如果 CC-Switch 也无法覆盖，可以手动把备份中不涉及密钥的部分恢复回来。

9.4 npm 安装 Claude Code 失败

通常是因为 Node.js 版本过低或网络原因导致 npm 下载超时。先升级 Node.js 到 LTS 版本，再考虑切换 npm 镜像源。注意镜像源的选择要符合你所在网络环境的使用规范。

9.5 部署到 CentOS 时 CC-Switch 启动失败

老系统常见的 GLIBC 版本不满足问题。检查系统库版本，或者选择在支持范围内的新版系统上运行。尽量不要在老系统上强行修改系统库文件来适配，风险太大。

以下是常见问题速查表：

10. 最佳实践与工程建议

10.1 密钥管理是第一优先级

无论 CC-Switch 多方便，都不要把真实 API Key 直接写进会被同步的配置文件中。如果你用 Git 管理配置目录，一定要在.gitignore中把settings.json排除掉，或者使用变量引用方式，从本地密钥管理工具中读取。

在实际团队中，更推荐的做法是：在 CC-Switch 中只保存“配置模板”，密钥通过本地环境变量或密钥管理服务注入。CC-Switch 处理的是“切换哪套配置”的问题，具体密钥应该由更底层的安全机制保护。

10.2 区分用户级配置和项目级配置

用户级配置影响所有项目，项目级配置只影响当前项目。默认建议：

• 个人通用密钥放进用户级配置。
• 公司项目密钥以项目级配置方式管理。
• 离开项目目录前，切换回个人默认配置，避免误用密钥。

10.3 会话上下文的保存策略

Claude Code 的会话历史是珍贵的工程资料。定期清理时，不要直接删除整个.claude目录，而是优先清理明显无用的旧会话文件。对于需要长期保留的会话，可以单独备份目录。

当你需要在切换配置后继续之前的任务时，记住两个命令：

claude --continue claude --resume

--continue用于继续最近一次会话，--resume用于从历史会话列表中选择。这两个命令切换配置后仍然可用，是保留上下文关键中的关键。

10.4 版本升级与回滚

Claude Code 升级频率较高，CC-Switch 也一样。升级前先记录当前版本号：

claude --version

如果你的工作流严重依赖某一版本，不要在项目进行到一半时贸然升级。先在测试目录中验证新版本兼容性，再决定是否全量切换。

10.5 日志与错误记录

遇到问题不要只截图，要把报错信息完整复制下来。Claude Code 的错误日志通常包含请求地址、状态码、响应体摘要，这些信息对于定位“是配置问题”还是“是服务端问题”非常有价值。

11. 总结与后续学习方向

这篇文章真正讲清楚了几件事：Claude Code 的配置不是只能靠手工维护，CC-Switch 可以把多套 API 配置变成可视化切换；配置切换的底层逻辑，实际上就是改写settings.json中的env字段；切换配置后遇到“上下文不加载”，正解不是回滚配置，而是使用会话恢复命令。

下一步，建议你先准备两套真实的配置，一套官方直连，一套公司网关或兼容接口，按照文章中的流程完整走一遍。跑通之后，再去研究 Claude Code 的项目级配置、自定义系统提示词、MCP（Model Context Protocol）扩展等进阶能力。

如果你当前只使用单一官方配置，CC-Switch 对你的价值可能还不明显；但一旦你的工作环境开始出现“换一台电脑就要重新配”“不同项目要用不同网关”这类需求，这篇文章里的配置思路就能直接复用。建议收藏备用，等用到的时候再翻出来照着做。