接入国内大模型

国内模型接入的关键不是“把 Base URL 换成某个地址”这么简单，而是确认这个服务能不能承接 Claude Code 的 agent 工作流：长上下文、工具调用、流式输出、权限确认、模型选择和稳定报错。

推荐方式：用 cc switch 切换模型

cc switch 的价值是把“改 Base URL、换 Key、换模型名、切回官方配置”这些动作变成可选择的配置档。新手不要每次手动改环境变量，也不要把密钥写进项目文件。

最舒服的使用方式是准备 3 个档案：

• 官方 Claude：网络和账号稳定时使用，适合学习主线和复杂任务。
• 国内主力网关：日常开发使用，要求响应稳定、上下文足够、工具调用正常。
• 国内备用网关：主力网关限流、余额不足或故障时切换。

cc switch 的正确流程

1. 先确认 Claude Code 本身已经安装并能启动。
2. 准备国内网关给出的 Base URL、API Key、模型名和说明文档。
3. 打开 cc switch，新增一个国内模型配置档。
4. 把 Base URL、Key、模型名填进切换器，而不是填进项目代码。
5. 保存后切换到这个配置档。
6. 重新打开 Claude Code 或按工具提示刷新配置。
7. 先做只读验证，确认模型真的生效。

配置档应该怎么命名

名字要让人一眼看懂，后面排障会轻松很多。

• official-claude：官方默认配置。
• cn-main-coding：国内主力 coding 网关。
• cn-backup-fast：国内备用快速模型。
• team-gateway：公司或团队统一网关。

国内模型接入的三种路线

路线 A：官方 Claude 可稳定使用

如果账号、网络、额度都稳定，优先使用官方 Claude 模型完成学习路线。新手同时折腾安装、权限、网络、模型和项目，很容易把问题混在一起。

路线 B：使用国内可访问的 Claude / Anthropic 网关

这是国内用户最常见、也最适合新手的方案。网关负责把 Claude Code 的请求转发到可用模型服务，用户只需要拿到网关提供的 Base URL、API Key 和可选模型名。

• 网关最好提供 Anthropic Messages 格式，例如 /v1/messages 和 /v1/messages/count_tokens。
• 网关需要正确转发 Claude Code 依赖的 headers 和流式响应。
• 如果网关提供 /v1/models，可以让 Claude Code 发现模型；否则要手动指定模型选项。
• 如果模型名不是 Claude 系列，也要做严格验证，因为工具调用和代码能力可能不稳定。

路线 C：通过团队 LLM Gateway 接国产模型

团队可以用统一网关接入通义千问、DeepSeek、Kimi、智谱、百度千帆或其他模型服务。这个方案适合有技术同学维护网关、审计、限额和模型路由的团队。

对普通用户来说，不需要自己研究网关实现，只需要让 CC 帮忙整理清单，然后把清单交给网关管理员确认。

配置前必须确认的 7 件事

1. 这个服务支持的是 Anthropic Messages，还是只有 OpenAI Chat Completions。
2. Base URL 是 Claude Code 专用地址，还是普通模型 API 地址。
3. 认证方式用 ANTHROPIC_AUTH_TOKEN，还是 ANTHROPIC_API_KEY。
4. 模型名是否需要手动指定，是否能在 /model 里看到。
5. 是否支持流式输出、工具调用、长上下文和 token 统计。
6. 是否有速率限制、余额限制、并发限制和失败重试规则。
7. 密钥应该放在用户环境或本机安全配置里，不能写进项目仓库。

直接发给 CC：让它指导 cc switch 配置

我要用 cc switch 配置 Claude Code 的国内模型。

请先不要让我修改项目文件，也不要要求我把 API Key 发给你。

我会自己在 cc switch 里填写真实密钥。你只需要指导我确认这些信息：
1. 这个配置档应该叫什么名字。
2. Base URL 应该填服务商给的哪个地址。
3. 模型名应该填哪个，不确定就提示我去控制台确认。
4. API Key 应该只填在 cc switch 或本机安全配置里，不能写进项目。
5. 切换后怎么验证 Claude Code 已经使用这个配置。
6. 如果验证失败，按认证、Base URL、模型名、余额、网络这几个方向排查。

请用步骤清单回答，不要编造服务商参数。

直接发给 CC：配置前检查

请只读检查我当前 Claude Code 的模型配置环境，不要修改任何文件，也不要读取或输出任何真实 API Key。

我准备接入国内大模型或国内网关。

请帮我确认：
1. 当前 Claude Code 是否已经能正常响应。
2. 当前是否能看到模型、账号或 provider 信息。
3. 如果我要接入国内网关，必须向服务商确认哪些参数。
4. 仅 OpenAI 兼容接口是否足够；如果不够，需要服务商额外支持什么。
5. 哪些配置适合放在用户级配置，哪些绝对不能写进项目仓库。
6. 给我一份配置前检查清单。

只做分析，不要执行修改。

需要拿到的配置清单

向服务商、网关平台或团队管理员要下面这些信息。拿不到就不要硬猜。

• Provider 类型：官方 Anthropic、Anthropic 兼容网关、Bedrock、Vertex、Foundry，还是团队自建网关。
• Base URL：Claude Code 应该请求的根地址。
• 认证字段：API Key、Bearer Token、临时 Token 或企业 SSO。
• 模型名：日常 coding 用哪个，复杂规划用哪个，便宜快速任务用哪个。
• 上下文长度：是否足够读取大型项目。
• 功能支持：工具调用、流式输出、thinking、prompt caching、模型列表。
• 限制规则：限流、余额、并发、超时、是否记录请求内容。

直接发给 CC：让它生成本机配置方案

请根据下面信息，为我生成 Claude Code 国内模型网关配置方案。

服务商或网关名称：【填写名称】
Base URL：【填写地址，但不要包含密钥】
模型名：【填写模型名；不知道就写“待确认”】
认证方式：【API Key / Bearer Token / 其他；不要填写真实密钥】
使用场景：【个人学习 / 团队开发 / 公司内网】
系统：【Windows / macOS / Linux / WSL】

要求：
1. 先判断这个方案是否适合 Claude Code。
2. 明确说明需要 Anthropic Messages 格式，还是可以通过网关转换。
3. 不要把密钥写入项目文件。
4. 优先给出用户级或本机级配置方式。
5. 配置前先列风险，配置后给只读验证步骤。
6. 如果信息不足，先列出需要我向服务商确认的问题，不要编造参数。

配置后第一件事：不要直接改项目

国内模型或网关接入成功后，第一步只做只读验证。不要马上让 CC 修 Bug、重构或跑大任务。

请做一次国内模型接入后的只读验证。

要求：
1. 不要修改任何文件。
2. 读取项目根目录、README、package 或配置文件。
3. 用中文总结项目用途、技术栈、入口文件和可用脚本。
4. 明确区分“从文件确认的事实”和“模型推测”。
5. 检查自己是否出现明显幻觉：编造不存在的文件、命令、目录或功能。
6. 如果模型能力、上下文、工具调用或响应稳定性不适合继续开发，请直接说明。

判断接入是否成功

• CC 能稳定回答，不频繁断流、超时或报认证错误。
• CC 能读取项目文件，并正确引用真实存在的文件和目录。
• CC 不会把 OpenAI、Claude、国产模型的参数混在一起瞎说。
• CC 能说明当前结论来自文件还是推测。
• 小任务能完成，并能解释 diff、风险和验收方式。

常见坑

只填了 Base URL，但模型没变

ANTHROPIC_BASE_URL 只决定请求发往哪里，不等于自动切换成某个模型。模型选择还要看 /model、模型名、别名映射或网关路由规则。

OpenAI 兼容接口能聊天，但 CC 工作流不稳定

能普通聊天不等于能做 agent 编程。Claude Code 需要更复杂的多轮、工具和上下文能力，网关转换不完整时，最容易出现工具调用失败、上下文丢失、响应格式异常。

模型便宜但改代码不可靠

便宜模型适合解释错误、整理文档、小范围改文案。复杂重构、跨文件推理、数据库变更、权限敏感任务，优先选更强的 coding 模型，并且强制 Plan Mode 和人工审查 diff。

把 API Key 写进了项目文件

这是高风险错误。密钥应该放在用户环境、本机安全配置、系统密钥管理或团队网关里，不应该进入 .env.example 之外的项目文件，更不能提交到 Git。

验收结果

• 你知道国内模型接入优先看网关格式，而不是只看 Base URL。
• 你知道 OpenAI 兼容接口不一定适合 Claude Code。
• 你能让 CC 生成配置清单，但不会把密钥发进对话或写进仓库。
• 你能用只读任务验证模型是否适合继续开发。