前阵子有朋友问了我一个问题Claude Code 到底该怎么装为什么网上搜出来的教程全是扫码登录然后卡在账号验证那一步。这个问题很典型。Claude Code 作为本地终端里的 AI 编码助手真正难住大家的往往不是安装本身而是后面那扇门官方账号体系、海外支付门槛、以及调用模型时的网络条件。大多数人其实只想把它装到本地让它能稳定调用国内可访问的大模型服务于是“安装配置 Claude Code免登录 国产模型”就成了一个非常实在的需求。这篇内容我会从方案选型讲到完整实操把免登录的原理、国产模型接入方式、常见报错排查都过一遍。适合三种人看刚接触 Claude Code 想少走弯路的新手、已经在用官方版但想换成国产模型的开发者、以及准备在团队内做工具落地的技术负责人。整个过程不需要你有云服务器也不需要你折腾复杂的编译只要跟着步骤来基本十几分钟就能跑起来。1. Claude Code 本地化的核心痛点与方案选型思考1.1 为什么官方默认方式会卡住大部分人先说清楚 Claude Code 本身是什么。它是 Anthropic 推出的命令行 AI 编程助手可以直接在终端里运行能读取项目文件、执行命令、修改代码交互方式比网页版更接近“并肩写代码”的感觉。这也是它最近热度很高的原因。但官方默认的启动方式有一个绕不开的环节首次运行claude命令时它会拉起浏览器要求你用 Claude 账号扫码登录。登录完成后客户端会把凭证写到本地后续请求都走官方 API。问题就在这里注册账号要能接收海外短信或邮箱验证绑定支付方式又是一道门槛而且官方 API 的计费方式对很多个人开发者来说并不友好。我在实际帮朋友排查的时候发现很多人其实已经装好了 Claude Code卡住的步骤是“登录”而不是“安装”。所以免登录方案的核心不是破解什么而是绕开 OAuth 登录流程直接在请求层用环境变量注入一个可用的 API Key让客户端跳过浏览器授权把请求转发到你自己指定的模型网关。1.2 免登录 国产模型的整体链路这套方案的技术链路说穿了很简单Claude Code 客户端支持通过环境变量指定 API 地址和密钥所以你可以让它不再请求官方服务而是把请求发送到一个兼容 Anthropic API 格式的网关再由网关转发给国产模型。整体看起来是这样的一段链路claude 命令本地终端 ↓ 读取环境变量 ANTHROPIC_BASE_URL → 你的模型网关地址 ↓ 转发 国产大模型DeepSeek / 通义 / GLM 等这个链路里有两个关键点。第一Claude Code 是开箱即用地支持环境变量覆盖默认 API 地址的这是官方设计的一部分不是 hack。第二国产模型本身大部分提供的是 OpenAI 兼容接口不能直接给 Claude Code 用所以中间需要一个“网关”层做协议转换。理解了这两点后面所有配置你都看得懂了。1.3 免登录的边界与合规意识这里我必须多说一句。很多人听到“免登录”就以为能绕过一切鉴权这是误解。免登录只是跳过 Claude 官方的 OAuth 登录环节但你仍然需要在某个模型网关或云厂商那注册账号、创建 API Key。区别在于这一步的门槛比官方低得多国内手机号就能注册支付方式也友好而且模型调用按量计费没有订阅绑定的包袱。从使用角度看这个方案还有两个额外好处一是请求走的是国内可直连的模型服务稳定性可控二是模型可以按需切换今天用 DeepSeek明天想试试通义千问改一行配置就行不需要在多个工具之间反复横跳。2. 环境准备装之前先过一遍这三样东西2.1 Node.js 版本与 PATH 检查Claude Code 是 npm 包所以第一个前置条件是 Node.js。很多安装失败案例都栽在版本太老上。我建议直接用 Node.js 20 LTS 或 22 LTS至少也要 18 以上。版本太旧npm 装包时会直接报引擎不兼容。打开终端先确认node -v npm -v如果你还没装 Node.js去官网下载 LTS 版本安装包一路下一步就行。装完之后需要重新开一个终端窗口PATH 才会生效。这里有个容易忽略的坑在 Windows 上用 nvm-windows 管理 Node 版本时如果切换版本后claude全局命令突然失效多半是全局安装目录不在当前 PATH 里。可以先执行npm config get prefix拿到 npm 全局目录后把这个目录加到系统 PATH。macOS/Linux 上一般不需要手动操作但如果你用了 homebrew 或 nvm最好也确认一下which claude能找到命令。2.2 Git 与终端环境的隐性要求第二个前置是 Git。Claude Code 在执行代码修改、git diff 查看、提交信息生成等功能时会频繁调用 git 命令。虽然没有 Git 也能启动但很多核心体验都会打折扣。建议提前装好并完成基础配置git --version git config --global user.name 你的名字 git config --global user.email 你的邮箱第三个前置是你的终端环境。说句实在话Windows 系统上我用过的体验排名是Windows Terminal PowerShell 7 最好纯 cmd 经常遇到 UTF-8 编码问题。如果你在 Windows 下用 Claude Code 输出中文乱码先检查终端编码执行chcp 65001切到 UTF-8。2.3 npm 镜像源的配置建议国内安装 npm 包经常遇到超时这跟网络环境有关。配置镜像源是最省事的做法npm config set registry https://registry.npmmirror.com配完之后可以验证一下npm config get registry这一步不是必须的但如果你安装时报ETIMEDOUT或ECONNRESET优先检查镜像源。我自己的习惯是一开始就配好后面装任何全局工具都省心。3. Claude Code 安装与免登录配置实操3.1 三种安装方式怎么选Claude Code 的安装方式主要有三种我逐个说一下适用场景。第一种是 npm 全局安装最常见也是我推荐的方式npm install -g anthropic-ai/claude-code全局装的好处是任意目录下都能直接敲claude命令升级也方便npm update -g anthropic-ai/claude-code第二种是npx临时调用适合你只想试用一下、不想污染全局环境的情况npx anthropic-ai/claude-code这种方式每次都会去拉取最新包速度稍慢但不影响使用。第三种是官方原生安装脚本一条命令装好但下载走的是海外 CDN很多环境下成功率不高。所以我的建议很直接国内用户老老实实用 npm 镜像装少折腾。装完以后验证版本claude --version如果这步报command not found十有八九是 npm 全局目录没进 PATH回到上一节去看。3.2 免登录原理与关键环境变量解析接下来是重头戏。Claude Code 启动时如果检测到环境变量里有ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN就会跳过浏览器登录直接使用这个 Key 去请求 API。这就是“免登录”的实现基础。协议层的关键变量有几个变量名作用必填性ANTHROPIC_BASE_URL指定 API 网关地址Claude Code 会把请求发到这里必填ANTHROPIC_AUTH_TOKEN自定义认证令牌网关用它识别调用者身份二选一ANTHROPIC_API_KEY标准 API Key部分网关也接受这种传法二选一ANTHROPIC_MODEL指定主模型名称选填ANTHROPIC_SMALL_FAST_MODEL指定轻量模型用来做标题生成等快速任务选填实际配置中ANTHROPIC_BASE_URL和认证令牌是关键。如果你用的是支持自定义 token 头的网关优先用ANTHROPIC_AUTH_TOKEN如果网关兼容标准 Anthropic 风格直接用ANTHROPIC_API_KEY也行。两者不要同时设否则容易混乱。在 Linux/macOS 上直接在当前终端窗口里测试export ANTHROPIC_BASE_URLhttps://你的网关地址/v1 export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude在 Windows PowerShell 里写法略有不同$env:ANTHROPIC_BASE_URL https://你的网关地址/v1 $env:ANTHROPIC_AUTH_TOKEN sk-你的密钥 $env:ANTHROPIC_MODEL deepseek-chat $env:ANTHROPIC_SMALL_FAST_MODEL deepseek-chat claude首次启动后如果配置正确你会看到终端直接进入对话界面不再弹出任何登录窗口。3.3 用 settings.json 固化配置上面临时环境变量的方式适合测试但每次开新终端都要重新 export很烦。更推荐把配置写进 Claude Code 的配置文件。Claude Code 会读取两个层级的配置文件全局配置在~/.claude/settings.json项目级配置在你项目的.claude/settings.json。项目级配置会覆盖全局配置适合团队协作时统一模型。配置格式长这样{ env: { ANTHROPIC_BASE_URL: https://你的网关地址/v1, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat } }保存后重新打开终端直接敲claude就能进入免登录状态。注意settings.json 里如果写入了真实密钥千万别把它提交到 Git 仓库。不建议在项目级配置里放密钥你可以放到全局配置并在项目里用.gitignore把.claude/目录忽略掉。4. 国产模型接入的四种典型姿势与参数对照4.1 网关中转、官方直连与兼容层国产模型接入的核心问题是 Claude Code 说“Anthropic 话”而国产模型大多说“OpenAI 话”。怎么让两者对上话现实里有几种典型姿势。第一种也是最推荐的方式是使用开源网关做协议转换。这类项目通常部署在你自己的服务器上启动后提供一个兼容 Anthropic 的/v1/messages接口Claude Code 用这个接口发请求网关再把消息翻译成 OpenAI 格式转发给后端模型。国内用得比较多的网关有 One API、New API 这类项目社区活跃度很高支持的模型渠道也很全。自己部署一个网关其实不复杂拉起服务后在后台配置一个国内模型渠道拿到一个带路径的地址填到ANTHROPIC_BASE_URL就行。第二种是直接使用部分国产模型的 Anthropic 兼容端点。现在有一些主流云厂商开始提供 Anthropic 兼容接口你可以直接拿到一个 base URL 和 API Key不用自建网关。这种方式最省事但覆盖的模型和功能范围取决于厂商自己做的兼容程度需要以官方文档为准。第三种是借助社区维护的轻量转发层。这类项目一般体量很小只做 Anthropic 和 OpenAI 协议之间的本地转发适合想快速验证的个人用户。优点是启动快一条命令就能跑缺点是功能和稳定性依赖作者后期维护生产环境慎用。第四种是官方模型直连也就是你去申请 Anthropic 官方 API Key。这个就不展开说了回到本文的痛点范围之外。做一个简单对比方案部署成本模型多样性稳定性适合场景开源网关中转中高高生产使用、团队共用模型厂商兼容端点低中高个人快速上手社区轻量转发层低低中技术验证、个人折腾官方 API低低高不差钱且账号链路通畅的人4.2 模型名称映射与调用参数调优配置网关之后你大概率会遇到一个让人困惑的问题ANTHROPIC_MODEL到底填什么是填官方模型名还是国产模型名答案取决于网关的实现。有的网关做了模型名映射你即使填claude-3-5-sonnet它也会自动转成你配置的国产模型有的网关要求填它自己的模型标识比如deepseek-chat、qwen-plus、glm-4-flash。最稳妥的做法是登录网关后台查看“模型列表”页面上面显示的模型名称就是你能填的值。以我常用的组合为例export ANTHROPIC_BASE_URLhttps://your-gateway.example.com/v1 export ANTHROPIC_AUTH_TOKENsk-xxxx export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat把主模型和轻量模型都指向同一个模型是刚开始最不容易出错的配置。如果你追求更高性能可以试试deepseek-reasoner这类推理模型如果追求响应速度可以给ANTHROPIC_SMALL_FAST_MODEL配一个便宜快速的模型很多轻量任务比如自动生成对话标题会用它能省不少 token。另外两个实际体验相关的参数也值得关注。一个是CLAUDE_CODE_MAX_OUTPUT_TOKENS控制单次回复的最大输出长度国产模型如果总是话说到一半被截断适当调大这个值。另一个是API_TIMEOUT_MS控制请求超时时间默认 60 秒如果你用的模型推理比较慢频繁报 timeout可以提到 120000 甚至更长。5. 高频报错与排查技巧实录5.1 连接类报错启动后界面一直停留在加载中或者直接报网络请求失败这是最常见的。排查思路就一条先确认你填的 base URL 到底能不能访问。用 curl 测试网关连通性curl -v https://你的网关地址/v1/messages如果能通你会看到一个 JSON 格式的错误响应里面通常包含认证相关信息这说明链路是通的。如果超时或连接被拒就要检查地址写没写对、网关服务是否启动、防火墙是否放行端口。另外要注意/v1后缀的问题。有的网关文档里给你的 base URL 已经带了/v1有的不带。Claude Code 拼请求时会直接在你给的地址后面加/messages所以如果你填了https://xxx.com但网关实际监听在https://xxx.com/v1就会 404。我建议在网关后台确认完整的 base URL而不是凭直觉拼接。5.2 认证与模型类报错典型的认证报错是 401 Unauthorized 或 403 Forbidden。这种情况 90% 是密钥的问题。先检查令牌变量是否真的传进去了可以临时在配置里加一条env | grep ANTHROPIC如果变量没出现说明 export 的终端窗口和启动claude的终端窗口不是同一个或者配置文件没生效。还有 401 的可能前提是密钥前缀不对。很多网关要求 Key 以sk-开头你填了个别的格式就会直接被拒绝。建议去网关后台重新生成一个 Key复制时注意别带上多余空格。模型不存在的报错一般长这样model: not found、Unsupported model。处理方式很简单去后台模型列表里对照一下名称。这里有个小技巧优先在网关后台看“测试调用”页面有些后台支持直接试发一条消息能省下不少和时间。5.3 工具调用与对话历史等体验类问题再聊几个有国产模型特色的问题。第一个是工具调用不稳定。Claude Code 最大的优势是能调用终端工具修改代码、执行命令但这是通过 Anthropic 消息 API 中的tool_use功能块实现的。国产模型对 function calling 的支持程度参差不齐如果你发现 Claude Code 偶尔“出戏”只会聊天不会改代码大概率是模型的函数调用能力不行。解决方法是切换一个支持 function calling 的模型版本比如通义的 qwen-max、智谱的 GLM-4 系列、DeepSeek 的 chat 版本目前都对工具调用有较好支持。第二个是对话历史丢失。热词里经常有人问“Claude Code 怎么保存对话历史”。实际上免登录配置下对话历史文件默认存放在~/.claude/projects/目录下。如果会话中断你可以在启动 Claude Code 后输入/resume它会列出历史会话选一个继续。这个功能官网文档里写得很隐蔽很多人用了一周都没发现。如果这个目录不存在先确认你确实正常发起过对话再检查是不是权限问题。第三个是上下文窗口不够用。国产模型的上下文长度各有不同如果你在一个大项目里频繁让 Claude Code 分析文件很快会撞到上下文上限。最直接的办法是拆任务而不是一股脑全塞给它或者在会话里用/clear清空上下文重新开始。我的习惯是每完成一个功能模块就开一个新会话让工具保持“专注模式”。6. 把免登录的 Claude Code 调得更顺手6.1 给 claude 起个别名省去每次刷环境变量如果你和我一样是个“懒人”不想每次开终端都要 source 一遍环境变量可以把它固化到 shell 配置里。在~/.bashrc或~/.zshrc末尾追加export ANTHROPIC_BASE_URLhttps://你的网关地址/v1 export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat alias claude-cnclaude保存后执行source ~/.bashrc或source ~/.zshrc以后每次开终端直接敲claude-cn就能进入免登录模式。不改全局变量名claude保留一个默认入口方便你在不同配置之间切换。6.2 MCP、Skills 与对话历史管理Claude Code 的扩展能力也是很多人关注的重点尤其是 MCPModel Context Protocol和 Skills。MCP 可以理解成是给 Claude Code 外接工具的标准化接口比如你想让它直接查数据库、读取某个 HTTP 服务的数据都可以通过 MCP 实现。安装方式是在会话里输入/mcp然后根据提示添加 MCP Server。Skills 的定位则更像“预设工作流”你可以给 Claude Code 定义一套针对特定场景的处理模板。安装 skill 也很简单把做好的 skill 目录放到~/.claude/skills/下就能被识别。我在实际使用中有一个习惯每个 skill 里明确写好输入输出约定和步骤清单这样模型执行时不会东一榔头西一棒子。需要提醒的是MCP 工具赋予了模型真实执行能力所以只添加你信任的工具不要盲目从网上拉一堆来路不明的 server 配置。6.3 密钥安全与个人使用建议最后说一个很多人不会提但很重要的事密钥安全。很多人喜欢把ANTHROPIC_AUTH_TOKEN直接写进项目级 settings.json然后随手把项目推到 GitHub 仓库密钥就泄露了。第三方拿到你的网关 Key不止会消耗你的 token 额度还可能在网关后台看到你的调用记录。我的习惯是密钥只放在全局环境变量或全局配置里项目级配置只写 base URL不写认证信息。如果是团队协作优先用网关后台生成的临时子 Key而不是把管理员 Key 到处传。这套方案我已经跑了很长一段时间日常编码完全稳定。最开始我也走了一段弯路一门心思想着配官方版本后来把模型网关切到国产模型之后反倒发现两个额外好处一个是响应速度在某些时段比官方还快另一个是费用更透明充多少用多少没有订阅焦虑。如果你是刚开始折腾 Claude Code我的建议是先按最小链路跑通——本地装好、环境变量指到网关、cp 一个国产模型进去、跑一个简单问答验证——然后再去研究 MCP、Skills 这些进阶功能。链路通了后面怎么玩都是水到渠成的事。