你在技术社区刷到“Claude Code”这个词的频率应该已经很高了。它是Anthropic推出的命令行AI编程助手能直接在终端里帮你读代码、改代码、跑测试、提交commit。对开发者来说确实爽但很多人卡在了配置这一步官方服务不便宜想给团队统一接入更熟悉的模型服务商时文档又写得让人头大。很多人问Claude Code能不能接国产大模型能不能把推理引擎换成DeepSeek、Kimi、通义这些我天天在用的服务答案是能而且配置起来并不复杂。这篇教程就从一个完全没有配置经验的小白视角出发从安装Node.js开始一步步把Claude Code装好再把国产大模型接进去全程给出可直接抄作业的命令和配置。适合刚接触终端工具、想用AI编程助手但不想在官方计费上花太多钱的开发者。文章不搞虚的我踩过的坑都直接标出来。1. 为什么要把 Claude Code 接到国产大模型上1.1 先搞清楚 Claude Code 到底是什么Claude Code 本质上是一个跑在终端里的 AI 结对编程工具。它不是IDE插件那种附件式的存在而是直接让你在命令行里用自然语言驱动它让它读整个项目的代码结构、定位某个bug的根源、写单元测试、解释一段看不懂的历史代码甚至让它自己执行命令完成一次重构。它和普通聊天机器人的最大区别在于“能动手”。你可以让它直接修改文件、运行测试、查看git diff然后根据结果继续调整。这种工作方式对开发效率的提升非常明显尤其是面对不熟悉的代码库时它相当于一个随叫随到的资深同事。不过 Claude Code 默认情况下对接的是 Anthropic 自己的模型服务。这个前提带来了两个现实问题一是成本问题日常高频使用下来token费用累积速度很快二是灵活性很多团队或个人开发者已经有自己习惯的大模型服务商了希望让 Claude Code 调用这些已有的模型能力。好消息是Claude Code 天生支持通过环境变量改写模型服务的地址。这意味着你可以把模型端点改到任意一个兼容的AI服务上国产大模型自然也能接进来。这个“可替换后端”的设计是所有后续配置的基础。1.2 为什么值得把国产大模型接进来从我的实际体验来看把 Claude Code 接到国产大模型上有几个非常务实的好处。最直观的是成本。国产大模型的接口定价普遍比海外主流API低一个量级对个人开发者和中小团队来说长时间挂着AI编程助手跑账单压力会小很多。有些服务商还提供按量充值和免费额度拿来做试验性质的代码生成任务非常划算。其次是统一管理。如果团队已经在用某家国产模型服务把 Claude Code 也接到同一个服务商API Key、用量统计、限额控制都能在一个后台里管理不需要大家各自去注册海外账号、各自绑卡。这一点对团队协作的价值很大。最后是模型选择自由。接国产大模型不代表“只能用一个”。你可以配置好网关之后在 DeepSeek、Kimi、通义这些模型之间来回切换不同任务用不同模型。比如简单的小函数生成用轻量模型大型代码重构用推理能力更强的大模型合理分配之后成本和体验能同时兼顾。1.3 核心认知协议转换和网关在动手之前有一个概念必须先理解否则后面配置很容易一头雾水。Claude Code 默认使用的是 Anthropic 的 Messages API 协议。而市面上大多数国产大模型服务商提供的是 OpenAI 兼容协议。两种协议在请求格式、参数命名、消息结构上都不一样直接让 Claude Code 去请求国产模型的接口大概率会报错。所以中间需要一个“协议转换层”把 Anthropic 协议的请求翻译成 OpenAI 协议的请求再把模型的响应翻译回去。这个转换层通常由一个“模型网关”承担。可以这么理解Claude Code 是一台美标插头的设备国产模型接口是欧标插座网关就是一个转换头。没有转换头插不进去。这个认知基本决定了后面要做什么要么找一个已经帮你做好协议转换的服务商要么自己搭建一个网关比如LiteLLM、one-api这类开源工具。搞清楚这一点再看后面的安装配置思路就特别清晰。2. 动手前的环境准备2.1 安装 Node.js 和 npmClaude Code 是 npm 包安装它的前提是电脑里有 Node.js 环境和 npm 包管理器。去 Node.js 官网下载 LTS 版本即可不要下 Current 尝鲜版。LTS 版本稳定兼容性更好Claude Code 的运行要求是 Node 18 以上下载最新 LTS 基本都满足。Windows 用户安装时注意勾选“Add to PATH”否则后面命令行找不到 node 命令。安装完成后打开终端验证一下node -v npm -v能正常输出版本号就说明环境没问题。如果你用的是 nvm 这类Node版本管理工具安装完之后要注意当前终端会话是否已经切换到目标版本有时候默认版本不对会导致各种奇怪问题。2.2 安装 GitClaude Code 和 Git 的耦合度很高它需要读取仓库状态、看 diff、执行 commit。没有 Git 环境很多功能用不起来。Windows 用户下载 Git for Windows 安装包一路默认配置即可。macOS 用户一般自带 Git如果提示没有可以安装 Xcode Command Line Toolsgit --version能输出版本号就说明 OK。安装完成后命令行里还要确认一下全局用户信息是否配置过如果没配置过Claude Code 在自动提交时会提示git config --global user.name your name git config --global user.email youremail.com2.3 准备国产大模型的 API Key这一步很简单但是很多人会卡在细节上。选一家你常用的国产大模型服务商注册账号进入控制台创建一个 API Key。创建完成后把 Key 完整复制保存好。大多数平台的 Key 只在创建时完整显示一次关闭页面后只能重新生成所以一定要当场存好。充值方面建议先充很少的金额。很多人一上来就充大额结果模型还没选对钱就消耗了一部分。先小额充值跑通整个链路后再根据使用量决定是否增加。拿到 Key 之后还要注意记录两个信息服务商提供的 API Base URL接口地址以及你想使用的确切模型名称。不同服务商对模型名称的命名规则不一样后续配置时写错了会直接导致请求失败。比如同样是一个中文名模型在不同服务商平台里可能叫不同的字符串标识。3. 安装 Claude Code 本体3.1 全局安装与版本验证环境准备好的前提下Claude Code 的安装可以用一条命令完成npm install -g anthropic-ai/claude-code安装过程会持续一会儿耐心等它跑完。如果出现权限错误常见于 macOS 和 Linux 系统在命令前加 sudosudo npm install -g anthropic-ai/claude-codeWindows 用户在 PowerShell 或 CMD 中如果遇到权限问题需要用管理员身份打开终端再执行。安装完成后验证一下claude --version能输出版本号说明安装成功。如果提示“claude 不是内部或外部命令”大概率是 npm 的全局安装目录没有加进 PATH检查 npm 全局 bin 路径并手动添加到环境变量即可。动手时我一个小技巧安装之前先看一眼 npm 镜像配置。如果之前配置了自定义 registry安装可能会变慢或失败可以临时切换回官方源或国内镜像源npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com这个命令即使你之前配置过其他镜像源也会临时用国内镜像完成这次安装。3.2 第一次启动的正确姿势安装完成后直接在终端里输入 claude 就能进入交互界面。很多教程会让你先登录官方账号但如果你计划接国产大模型第一次启动时可以不用急着登录。Claude Code 的环境变量配置如果已经设置好它会优先走你配置的模型端点不再强制走官方登录流程。具体来说先把后面的环境变量配置搞定再启动 claude体验会顺很多。当然不同版本的 Claude Code 对登录态的要求不太一样有些版本即便配置了第三方端点第一次启动还是会弹出登录提示。遇到这种情况也不用慌正常完成登录即可后续请求会被环境变量里的模型端点接管并不会影响你使用国产大模型。进入交互界面后再输入/exit退出确认基本流程没问题就可以进入核心配置环节了。3.3 更新、卸载与常见安装报错Claude Code 的更新频率很高基本每隔几周就有版本更新。更新直接用 npm 就行npm update -g anthropic-ai/claude-code强烈建议频繁使用的人每次开工前先更新一下。我遇到过几次旧版本在某个模型端点配置下表现异常更新到新版后问题就消失了。卸载也很简单npm uninstall -g anthropic-ai/claude-code安装过程中的报错九成以上是三类一是 Node 版本过低升级到 18 即可解决二是网络问题导致 npm 下载失败换镜像源重试三是权限不足用 sudo 或管理员终端重跑。这些都属于环境问题不是 Claude Code 本身的问题逐个排查就能解决。4. 核心环节配置国产大模型4.1 最省事的方案选有 Anthropic 兼容端点的服务配置国产大模型有一个最省路的方案找一家已经直接提供 Anthropic 协议兼容接口的模型服务商。现在有些模型聚合平台和服务商在推出兼容层你不需要自己搭建任何中间服务只需要把它提供的 Base URL 和 API Key 填到 Claude Code 的环境变量里就行。具体填法如下export ANTHROPIC_BASE_URLhttps://你选的服务商提供的接口地址 export ANTHROPIC_AUTH_TOKENsk-你的APIKey export ANTHROPIC_MODEL服务商要求的模型名这种方式适合只想快速跑通的人。不需要折腾 Docker、不需要维护网关五分钟就能让 Claude Code 说话。缺点是可选择性有限你只能用那一家服务商提供的模型如果它没有你想要的那个模型就得换方案。4.2 自建 LiteLLM 网关方案如果你不想被某一家的兼容端点限制住那么自建一个 LiteLLM 网关是最好的选择。LiteLLM 是目前社区里很主流的开源模型网关它可以把 OpenAI 兼容的模型请求统一转换成 Anthropic 协议暴露出去Claude Code 只需要对接它。用 Docker 部署最简单。假设你想接 DeepSeek一条命令就能跑起来docker run -d --name litellm-proxy \ -e DEEPSEEK_API_KEYsk-你的key \ -p 4000:4000 \ ghcr.io/berriai/litellm:main-latest \ --model deepseek/deepseek-chat --port 4000启动之后LiteLLM 会在本地 4000 端口暴露一个兼容 Anthropic 协议的接口。然后配置 Claude Code 环境变量export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-你的key export ANTHROPIC_MODELdeepseek/deepseek-chat这里有个很重要的点Claude Code 的鉴权头是读 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY不同版本有差异。以我实测的情况AUTH_TOKEN 在很多版本中优先级更高。所以我建议两个变量都设置成同一个 Key避免漏配导致请求直接打到官方。如果不方便用 Docker也可以通过 pip 安装 litellm 后命令行启动。原理不变只是运行方式不同。网关的日志会显示每次请求的路由目标和耗时排查问题的时候非常有用。4.3 用 one-api 类网关统一管理多个供应商如果团队成员多、模型供应商也多可以考虑用 one-api 这类自带管理界面的网关。它支持一个后台配置多家模型的 API Key对外提供一个统一地址和统一鉴权 Token。配置 Claude Code 时环境变量指向 one-api 的地址Token 填 one-api 生成的渠道 Token模型名填 one-api 里配置的模型别名。这样的好处是以后要换模型供应商只需要在管理后台改渠道所有客户端不用动。这个方案对上规模的团队更友好。个人的话LiteLLM 已经足够one-api 的管理成本会显得有点重。4.4 环境变量的持久化设置环境变量设置好之后只在当前终端会话生效。关掉终端再打开又得重新 export 一遍非常麻烦。所以需要把环境变量做成持久化配置。macOS/Linux 用户在 shell 配置文件中追加即可echo export ANTHROPIC_BASE_URLhttp://localhost:4000 ~/.zshrc echo export ANTHROPIC_AUTH_TOKENsk-你的key ~/.zshrc echo export ANTHROPIC_MODELdeepseek/deepseek-chat ~/.zshrc source ~/.zshrc如果你用的是 bash对应改 ~/.bashrc 或 ~/.bash_profile。Windows 用户用 setx 设置系统级环境变量setx ANTHROPIC_BASE_URL http://localhost:4000 setx ANTHROPIC_AUTH_TOKEN sk-你的key setx ANTHROPIC_MODEL deepseek/deepseek-chat注意 setx 设置完不会立即对当前终端生效需要重开一个终端窗口。配置好之后验证一下echo $ANTHROPIC_BASE_URL能输出正确地址说明配置生效了。5. 多套配置切换与 IDE 集成5.1 用 CC Switch 管理多套配置很多人的实际需求不止“接入一个国产模型”而是希望能在官方模型、DeepSeek、Kimi、通义之间随时切换。手动改环境变量太痛苦这时候就需要 CC Switch 这样的配置管理工具。CC Switch 是社区里流行的 Claude Code 配置切换工具它的工作方式是把多套配置存成“配置集”每个配置集里包含 Base URL、API Key、模型名称这些信息。切换的时候只需要在工具里选一下目标配置它会自动帮你更新 Claude Code 的配置文件不需要再手动修改环境变量。我个人的习惯是这样的官方模型保留一套配置集DeepSeek、Kimi、通义各建一套跑代码生成任务时切到便宜的模型需要做复杂架构设计时切回推理能力更强的模型。用 CC Switch 管理配置之后有一个非常重要的注意事项切换配置后必须重启 Claude Code 进程。如果当前打开了 claude 会话配置切换不会热生效重启才能看到效果。我刚开始用的时候经常忘记这一步切换之后还以为配置没生效白白排查了半天。5.2 在 VSCode 里用 Claude CodeClaude Code 在 VSCode 里有官方扩展支持可以直接在扩展市场搜索安装。安装完成后侧边栏会多出 Claude Code 的面板入口启动后就是一个内置的对话终端和命令行版的体验一致好处是能直接结合编辑器上下文查看代码修改。如果你不想用扩展也可以在 VSCode 的集成终端里直接运行 claude效果一样。两种方式共享同一套配置环境变量和配置文件都是全局的不需要单独设置。集成到 IDE 之后建议把常用操作命令化。比如在项目里新建一个 README 说明文件把常用的 claude 启动指令、配置切换指令写清楚方便团队成员快速上手。5.3 项目级配置与命令行覆盖环境变量是全局配置但有些项目可能需要独立的模型设置。Claude Code 支持在项目目录下放置配置文件来做局部覆盖在项目根目录创建.claude配置目录写入环境变量配置后这个项目启动 claude 时会优先读取项目级配置。这种方式的好处很明显每个仓库可以用最适合它的模型和参数不需要来回切换全局配置。比如一个机器学习项目你在项目级配置里指定了擅长代码生成的模型另一个维护老项目的仓库可以指定另一个更注重稳定性的模型。命令行参数同样能完成临时覆盖claude --model deepseek/deepseek-chat这种临时指定方式适合快速测试模型效果不修改任何配置文件。测试完直接退出重启又回到默认配置。实际调试模型选择时这种方式非常方便。6. 常见问题与排查技巧实录6.1 高频报错速查表配置过程中遇到的报错大部分集中在下面几个场景。我整理了一个速查表按图索骥就能定位问题。报错现象大概率原因排查思路claude 命令找不到npm 全局 bin 目录不在 PATH重装 npm 包或手动配置 PATH启动后卡在登录页面环境变量没生效echo 检查环境变量确认后重启终端401 UnauthorizedAPI Key 无效或填错位置检查 Key 本身确认 AUTH_TOKEN 和 API_KEY 都已配置404 model not found模型名写错到服务商控制台查确切模型标识确认大小写Connection Error网关地址不可达curl 网关地址验证端口和服务状态请求超时模型服务商侧波动或网关过载看网关日志等待重试或切换备用模型回复质量明显差模型指令遵循能力弱换成支持 function calling 且代码能力更强的模型使用限额提示被限配额用尽或共享配置被抢占切换配置集、稍后重试检查团队共享 Key 用量6.2 排查链路实例这里分享一个具体的排查过程帮你建立解决问题的思路。有一次我配置完成后启动 claude 请求一直报 401。我先检查了服务商的 Key 是否有效在平台后台能看到调用记录和余额没有问题。接着检查环境变量发现 BASE_URL 和 AUTH_TOKEN 都设置正确。最后灵机一动打开网关日志发现请求到达网关时Authorization 头里带的是一个完全不同的 Key——原来是另一个配置工具自动写入的旧 Key 把环境变量里面的值覆盖了。这个案例想说明的是出现问题不要盯着单一原因死磕按照“环境变量 → 配置文件 → 网关日志 → 服务商后台”的顺序逐层排查效率最高。尤其环境变量和配置文件的覆盖关系是很多奇奇怪怪问题的根源。6.3 给新手的避坑清单最后整理一些我踩过很多次才总结出来的经验算不上高深但每条都真实有效。环境变量优先级要心里有数。AUTH_TOKEN、API_KEY、BASE_URL 这些变量的生效优先级在不同版本里有细微差别不要凭记忆猜测以实际生效结果为准。排查问题前先 echo 确认当前值。第一次跑通链路先用小流量测试。不要一上来就让它重构整个项目先让它读一个文件、改一个函数确认整条链路稳定后再放开使用。很多人在刚开始就遇到超时、限流这些问题往往是因为大任务把并发拉满了。不要忽略网关日志。如果你自建了网关日志就是你的第一排查入口。它能告诉你请求到底有没有到达、路由到了哪个模型、响应耗时多少。关掉日志等于蒙着眼睛排查问题。不要共用 API Key。团队里如果多人共用一个 Key一旦某个人配置错误会把所有人的请求都带到错误的路由上而且非常不好排查。给每个人都分配独立的 Key出了问题能快速定位责任链。模型选择不要迷信性能榜单。实际代码场景中一个模型在 benchmarks 上表现好不一定在 Claude Code 的长链路工具调用中表现好。建议把高频任务类型列出来用小批量真实任务测试看哪个模型最顺手。我个人实际用下来的体会是先把“能跑通”作为第一目标不要一步到位追求完美配置。先用最简单的方式把 Claude Code 和国产大模型接上哪怕只用一家服务商、只用一个模型先把流程跑顺。等对工具的行为模式有感觉了再逐步引入网关、配置切换、多模型路由这些进阶能力。技术路线的价值不在于一次到位而在于你随时知道每一层配置在干什么、出了问题能从哪下手。这套链路吃透了以后不管再出现什么新模型你都能在一顿饭的时间内把它接进去。
Claude Code 接入国产大模型：从环境配置到网关搭建指南
你在技术社区刷到“Claude Code”这个词的频率应该已经很高了。它是Anthropic推出的命令行AI编程助手能直接在终端里帮你读代码、改代码、跑测试、提交commit。对开发者来说确实爽但很多人卡在了配置这一步官方服务不便宜想给团队统一接入更熟悉的模型服务商时文档又写得让人头大。很多人问Claude Code能不能接国产大模型能不能把推理引擎换成DeepSeek、Kimi、通义这些我天天在用的服务答案是能而且配置起来并不复杂。这篇教程就从一个完全没有配置经验的小白视角出发从安装Node.js开始一步步把Claude Code装好再把国产大模型接进去全程给出可直接抄作业的命令和配置。适合刚接触终端工具、想用AI编程助手但不想在官方计费上花太多钱的开发者。文章不搞虚的我踩过的坑都直接标出来。1. 为什么要把 Claude Code 接到国产大模型上1.1 先搞清楚 Claude Code 到底是什么Claude Code 本质上是一个跑在终端里的 AI 结对编程工具。它不是IDE插件那种附件式的存在而是直接让你在命令行里用自然语言驱动它让它读整个项目的代码结构、定位某个bug的根源、写单元测试、解释一段看不懂的历史代码甚至让它自己执行命令完成一次重构。它和普通聊天机器人的最大区别在于“能动手”。你可以让它直接修改文件、运行测试、查看git diff然后根据结果继续调整。这种工作方式对开发效率的提升非常明显尤其是面对不熟悉的代码库时它相当于一个随叫随到的资深同事。不过 Claude Code 默认情况下对接的是 Anthropic 自己的模型服务。这个前提带来了两个现实问题一是成本问题日常高频使用下来token费用累积速度很快二是灵活性很多团队或个人开发者已经有自己习惯的大模型服务商了希望让 Claude Code 调用这些已有的模型能力。好消息是Claude Code 天生支持通过环境变量改写模型服务的地址。这意味着你可以把模型端点改到任意一个兼容的AI服务上国产大模型自然也能接进来。这个“可替换后端”的设计是所有后续配置的基础。1.2 为什么值得把国产大模型接进来从我的实际体验来看把 Claude Code 接到国产大模型上有几个非常务实的好处。最直观的是成本。国产大模型的接口定价普遍比海外主流API低一个量级对个人开发者和中小团队来说长时间挂着AI编程助手跑账单压力会小很多。有些服务商还提供按量充值和免费额度拿来做试验性质的代码生成任务非常划算。其次是统一管理。如果团队已经在用某家国产模型服务把 Claude Code 也接到同一个服务商API Key、用量统计、限额控制都能在一个后台里管理不需要大家各自去注册海外账号、各自绑卡。这一点对团队协作的价值很大。最后是模型选择自由。接国产大模型不代表“只能用一个”。你可以配置好网关之后在 DeepSeek、Kimi、通义这些模型之间来回切换不同任务用不同模型。比如简单的小函数生成用轻量模型大型代码重构用推理能力更强的大模型合理分配之后成本和体验能同时兼顾。1.3 核心认知协议转换和网关在动手之前有一个概念必须先理解否则后面配置很容易一头雾水。Claude Code 默认使用的是 Anthropic 的 Messages API 协议。而市面上大多数国产大模型服务商提供的是 OpenAI 兼容协议。两种协议在请求格式、参数命名、消息结构上都不一样直接让 Claude Code 去请求国产模型的接口大概率会报错。所以中间需要一个“协议转换层”把 Anthropic 协议的请求翻译成 OpenAI 协议的请求再把模型的响应翻译回去。这个转换层通常由一个“模型网关”承担。可以这么理解Claude Code 是一台美标插头的设备国产模型接口是欧标插座网关就是一个转换头。没有转换头插不进去。这个认知基本决定了后面要做什么要么找一个已经帮你做好协议转换的服务商要么自己搭建一个网关比如LiteLLM、one-api这类开源工具。搞清楚这一点再看后面的安装配置思路就特别清晰。2. 动手前的环境准备2.1 安装 Node.js 和 npmClaude Code 是 npm 包安装它的前提是电脑里有 Node.js 环境和 npm 包管理器。去 Node.js 官网下载 LTS 版本即可不要下 Current 尝鲜版。LTS 版本稳定兼容性更好Claude Code 的运行要求是 Node 18 以上下载最新 LTS 基本都满足。Windows 用户安装时注意勾选“Add to PATH”否则后面命令行找不到 node 命令。安装完成后打开终端验证一下node -v npm -v能正常输出版本号就说明环境没问题。如果你用的是 nvm 这类Node版本管理工具安装完之后要注意当前终端会话是否已经切换到目标版本有时候默认版本不对会导致各种奇怪问题。2.2 安装 GitClaude Code 和 Git 的耦合度很高它需要读取仓库状态、看 diff、执行 commit。没有 Git 环境很多功能用不起来。Windows 用户下载 Git for Windows 安装包一路默认配置即可。macOS 用户一般自带 Git如果提示没有可以安装 Xcode Command Line Toolsgit --version能输出版本号就说明 OK。安装完成后命令行里还要确认一下全局用户信息是否配置过如果没配置过Claude Code 在自动提交时会提示git config --global user.name your name git config --global user.email youremail.com2.3 准备国产大模型的 API Key这一步很简单但是很多人会卡在细节上。选一家你常用的国产大模型服务商注册账号进入控制台创建一个 API Key。创建完成后把 Key 完整复制保存好。大多数平台的 Key 只在创建时完整显示一次关闭页面后只能重新生成所以一定要当场存好。充值方面建议先充很少的金额。很多人一上来就充大额结果模型还没选对钱就消耗了一部分。先小额充值跑通整个链路后再根据使用量决定是否增加。拿到 Key 之后还要注意记录两个信息服务商提供的 API Base URL接口地址以及你想使用的确切模型名称。不同服务商对模型名称的命名规则不一样后续配置时写错了会直接导致请求失败。比如同样是一个中文名模型在不同服务商平台里可能叫不同的字符串标识。3. 安装 Claude Code 本体3.1 全局安装与版本验证环境准备好的前提下Claude Code 的安装可以用一条命令完成npm install -g anthropic-ai/claude-code安装过程会持续一会儿耐心等它跑完。如果出现权限错误常见于 macOS 和 Linux 系统在命令前加 sudosudo npm install -g anthropic-ai/claude-codeWindows 用户在 PowerShell 或 CMD 中如果遇到权限问题需要用管理员身份打开终端再执行。安装完成后验证一下claude --version能输出版本号说明安装成功。如果提示“claude 不是内部或外部命令”大概率是 npm 的全局安装目录没有加进 PATH检查 npm 全局 bin 路径并手动添加到环境变量即可。动手时我一个小技巧安装之前先看一眼 npm 镜像配置。如果之前配置了自定义 registry安装可能会变慢或失败可以临时切换回官方源或国内镜像源npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com这个命令即使你之前配置过其他镜像源也会临时用国内镜像完成这次安装。3.2 第一次启动的正确姿势安装完成后直接在终端里输入 claude 就能进入交互界面。很多教程会让你先登录官方账号但如果你计划接国产大模型第一次启动时可以不用急着登录。Claude Code 的环境变量配置如果已经设置好它会优先走你配置的模型端点不再强制走官方登录流程。具体来说先把后面的环境变量配置搞定再启动 claude体验会顺很多。当然不同版本的 Claude Code 对登录态的要求不太一样有些版本即便配置了第三方端点第一次启动还是会弹出登录提示。遇到这种情况也不用慌正常完成登录即可后续请求会被环境变量里的模型端点接管并不会影响你使用国产大模型。进入交互界面后再输入/exit退出确认基本流程没问题就可以进入核心配置环节了。3.3 更新、卸载与常见安装报错Claude Code 的更新频率很高基本每隔几周就有版本更新。更新直接用 npm 就行npm update -g anthropic-ai/claude-code强烈建议频繁使用的人每次开工前先更新一下。我遇到过几次旧版本在某个模型端点配置下表现异常更新到新版后问题就消失了。卸载也很简单npm uninstall -g anthropic-ai/claude-code安装过程中的报错九成以上是三类一是 Node 版本过低升级到 18 即可解决二是网络问题导致 npm 下载失败换镜像源重试三是权限不足用 sudo 或管理员终端重跑。这些都属于环境问题不是 Claude Code 本身的问题逐个排查就能解决。4. 核心环节配置国产大模型4.1 最省事的方案选有 Anthropic 兼容端点的服务配置国产大模型有一个最省路的方案找一家已经直接提供 Anthropic 协议兼容接口的模型服务商。现在有些模型聚合平台和服务商在推出兼容层你不需要自己搭建任何中间服务只需要把它提供的 Base URL 和 API Key 填到 Claude Code 的环境变量里就行。具体填法如下export ANTHROPIC_BASE_URLhttps://你选的服务商提供的接口地址 export ANTHROPIC_AUTH_TOKENsk-你的APIKey export ANTHROPIC_MODEL服务商要求的模型名这种方式适合只想快速跑通的人。不需要折腾 Docker、不需要维护网关五分钟就能让 Claude Code 说话。缺点是可选择性有限你只能用那一家服务商提供的模型如果它没有你想要的那个模型就得换方案。4.2 自建 LiteLLM 网关方案如果你不想被某一家的兼容端点限制住那么自建一个 LiteLLM 网关是最好的选择。LiteLLM 是目前社区里很主流的开源模型网关它可以把 OpenAI 兼容的模型请求统一转换成 Anthropic 协议暴露出去Claude Code 只需要对接它。用 Docker 部署最简单。假设你想接 DeepSeek一条命令就能跑起来docker run -d --name litellm-proxy \ -e DEEPSEEK_API_KEYsk-你的key \ -p 4000:4000 \ ghcr.io/berriai/litellm:main-latest \ --model deepseek/deepseek-chat --port 4000启动之后LiteLLM 会在本地 4000 端口暴露一个兼容 Anthropic 协议的接口。然后配置 Claude Code 环境变量export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-你的key export ANTHROPIC_MODELdeepseek/deepseek-chat这里有个很重要的点Claude Code 的鉴权头是读 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY不同版本有差异。以我实测的情况AUTH_TOKEN 在很多版本中优先级更高。所以我建议两个变量都设置成同一个 Key避免漏配导致请求直接打到官方。如果不方便用 Docker也可以通过 pip 安装 litellm 后命令行启动。原理不变只是运行方式不同。网关的日志会显示每次请求的路由目标和耗时排查问题的时候非常有用。4.3 用 one-api 类网关统一管理多个供应商如果团队成员多、模型供应商也多可以考虑用 one-api 这类自带管理界面的网关。它支持一个后台配置多家模型的 API Key对外提供一个统一地址和统一鉴权 Token。配置 Claude Code 时环境变量指向 one-api 的地址Token 填 one-api 生成的渠道 Token模型名填 one-api 里配置的模型别名。这样的好处是以后要换模型供应商只需要在管理后台改渠道所有客户端不用动。这个方案对上规模的团队更友好。个人的话LiteLLM 已经足够one-api 的管理成本会显得有点重。4.4 环境变量的持久化设置环境变量设置好之后只在当前终端会话生效。关掉终端再打开又得重新 export 一遍非常麻烦。所以需要把环境变量做成持久化配置。macOS/Linux 用户在 shell 配置文件中追加即可echo export ANTHROPIC_BASE_URLhttp://localhost:4000 ~/.zshrc echo export ANTHROPIC_AUTH_TOKENsk-你的key ~/.zshrc echo export ANTHROPIC_MODELdeepseek/deepseek-chat ~/.zshrc source ~/.zshrc如果你用的是 bash对应改 ~/.bashrc 或 ~/.bash_profile。Windows 用户用 setx 设置系统级环境变量setx ANTHROPIC_BASE_URL http://localhost:4000 setx ANTHROPIC_AUTH_TOKEN sk-你的key setx ANTHROPIC_MODEL deepseek/deepseek-chat注意 setx 设置完不会立即对当前终端生效需要重开一个终端窗口。配置好之后验证一下echo $ANTHROPIC_BASE_URL能输出正确地址说明配置生效了。5. 多套配置切换与 IDE 集成5.1 用 CC Switch 管理多套配置很多人的实际需求不止“接入一个国产模型”而是希望能在官方模型、DeepSeek、Kimi、通义之间随时切换。手动改环境变量太痛苦这时候就需要 CC Switch 这样的配置管理工具。CC Switch 是社区里流行的 Claude Code 配置切换工具它的工作方式是把多套配置存成“配置集”每个配置集里包含 Base URL、API Key、模型名称这些信息。切换的时候只需要在工具里选一下目标配置它会自动帮你更新 Claude Code 的配置文件不需要再手动修改环境变量。我个人的习惯是这样的官方模型保留一套配置集DeepSeek、Kimi、通义各建一套跑代码生成任务时切到便宜的模型需要做复杂架构设计时切回推理能力更强的模型。用 CC Switch 管理配置之后有一个非常重要的注意事项切换配置后必须重启 Claude Code 进程。如果当前打开了 claude 会话配置切换不会热生效重启才能看到效果。我刚开始用的时候经常忘记这一步切换之后还以为配置没生效白白排查了半天。5.2 在 VSCode 里用 Claude CodeClaude Code 在 VSCode 里有官方扩展支持可以直接在扩展市场搜索安装。安装完成后侧边栏会多出 Claude Code 的面板入口启动后就是一个内置的对话终端和命令行版的体验一致好处是能直接结合编辑器上下文查看代码修改。如果你不想用扩展也可以在 VSCode 的集成终端里直接运行 claude效果一样。两种方式共享同一套配置环境变量和配置文件都是全局的不需要单独设置。集成到 IDE 之后建议把常用操作命令化。比如在项目里新建一个 README 说明文件把常用的 claude 启动指令、配置切换指令写清楚方便团队成员快速上手。5.3 项目级配置与命令行覆盖环境变量是全局配置但有些项目可能需要独立的模型设置。Claude Code 支持在项目目录下放置配置文件来做局部覆盖在项目根目录创建.claude配置目录写入环境变量配置后这个项目启动 claude 时会优先读取项目级配置。这种方式的好处很明显每个仓库可以用最适合它的模型和参数不需要来回切换全局配置。比如一个机器学习项目你在项目级配置里指定了擅长代码生成的模型另一个维护老项目的仓库可以指定另一个更注重稳定性的模型。命令行参数同样能完成临时覆盖claude --model deepseek/deepseek-chat这种临时指定方式适合快速测试模型效果不修改任何配置文件。测试完直接退出重启又回到默认配置。实际调试模型选择时这种方式非常方便。6. 常见问题与排查技巧实录6.1 高频报错速查表配置过程中遇到的报错大部分集中在下面几个场景。我整理了一个速查表按图索骥就能定位问题。报错现象大概率原因排查思路claude 命令找不到npm 全局 bin 目录不在 PATH重装 npm 包或手动配置 PATH启动后卡在登录页面环境变量没生效echo 检查环境变量确认后重启终端401 UnauthorizedAPI Key 无效或填错位置检查 Key 本身确认 AUTH_TOKEN 和 API_KEY 都已配置404 model not found模型名写错到服务商控制台查确切模型标识确认大小写Connection Error网关地址不可达curl 网关地址验证端口和服务状态请求超时模型服务商侧波动或网关过载看网关日志等待重试或切换备用模型回复质量明显差模型指令遵循能力弱换成支持 function calling 且代码能力更强的模型使用限额提示被限配额用尽或共享配置被抢占切换配置集、稍后重试检查团队共享 Key 用量6.2 排查链路实例这里分享一个具体的排查过程帮你建立解决问题的思路。有一次我配置完成后启动 claude 请求一直报 401。我先检查了服务商的 Key 是否有效在平台后台能看到调用记录和余额没有问题。接着检查环境变量发现 BASE_URL 和 AUTH_TOKEN 都设置正确。最后灵机一动打开网关日志发现请求到达网关时Authorization 头里带的是一个完全不同的 Key——原来是另一个配置工具自动写入的旧 Key 把环境变量里面的值覆盖了。这个案例想说明的是出现问题不要盯着单一原因死磕按照“环境变量 → 配置文件 → 网关日志 → 服务商后台”的顺序逐层排查效率最高。尤其环境变量和配置文件的覆盖关系是很多奇奇怪怪问题的根源。6.3 给新手的避坑清单最后整理一些我踩过很多次才总结出来的经验算不上高深但每条都真实有效。环境变量优先级要心里有数。AUTH_TOKEN、API_KEY、BASE_URL 这些变量的生效优先级在不同版本里有细微差别不要凭记忆猜测以实际生效结果为准。排查问题前先 echo 确认当前值。第一次跑通链路先用小流量测试。不要一上来就让它重构整个项目先让它读一个文件、改一个函数确认整条链路稳定后再放开使用。很多人在刚开始就遇到超时、限流这些问题往往是因为大任务把并发拉满了。不要忽略网关日志。如果你自建了网关日志就是你的第一排查入口。它能告诉你请求到底有没有到达、路由到了哪个模型、响应耗时多少。关掉日志等于蒙着眼睛排查问题。不要共用 API Key。团队里如果多人共用一个 Key一旦某个人配置错误会把所有人的请求都带到错误的路由上而且非常不好排查。给每个人都分配独立的 Key出了问题能快速定位责任链。模型选择不要迷信性能榜单。实际代码场景中一个模型在 benchmarks 上表现好不一定在 Claude Code 的长链路工具调用中表现好。建议把高频任务类型列出来用小批量真实任务测试看哪个模型最顺手。我个人实际用下来的体会是先把“能跑通”作为第一目标不要一步到位追求完美配置。先用最简单的方式把 Claude Code 和国产大模型接上哪怕只用一家服务商、只用一个模型先把流程跑顺。等对工具的行为模式有感觉了再逐步引入网关、配置切换、多模型路由这些进阶能力。技术路线的价值不在于一次到位而在于你随时知道每一层配置在干什么、出了问题能从哪下手。这套链路吃透了以后不管再出现什么新模型你都能在一顿饭的时间内把它接进去。
浏览器扩展：网页视频下载的完整流程与避坑指南)
