说实话去年我第一次装 Claude Code 的时候折腾得够呛先要注册账号、绑定支付方式然后启动时还得走一套 OAuth 授权中间任何一步卡住整个工具就没法用。后来我换了个思路把认证方式从“账号登录”换成 API Key 直连再把模型端点指向国产模型的兼容接口一套免登录的 Claude Code 环境就稳定跑了起来。这篇文章就把完整流程写一遍从 Node.js 环境准备、Claude Code 安装、免登录实现到国产模型DeepSeek、通义千问、Kimi 等接入全程用实际命令和参数说话。适合被官方账号登录折磨过的开发者也适合想用国内模型跑 Claude Code 的个人和团队。1. 先搞清楚这套方案在解决什么问题1.1 为什么是 Claude CodeClaude Code 是 Anthropic 官方的命令行编程智能体能直接在终端里读取项目文件、执行命令、批量修改代码本质上把“对话式 AI 编程”嵌入到了 Git 和 Shell 的工作流里。跟 Cursor、Copilot 这种插件型工具相比它最大的优势是轻量和可脚本化不依赖编辑器任何终端里都能跑还能用-p参数一次性执行任务适合自动化流程。我一开始入坑就是看中它能处理多文件重构和复杂任务拆解这种场景下图形界面反而不如命令行顺手。另外一点很关键Claude Code 的交互模型是“智能体模式”它会自己规划步骤、读取文件、执行命令、检查结果而不是像传统补全工具那样只顾着接句子。做一个小型功能模块时它能直接完成从设计到实现的完整链路这种体验一旦习惯就很难退回去。所以哪怕你已经在用 Cursor 或 Copilot我也建议留一个终端入口给 Claude Code把它当项目里的“执行型助手”用。1.2 “免登录”到底免掉了什么官方默认流程是先执行claude然后浏览器打开授权链接完成 OAuth 登录之后工具才能用。这套流程在个人电脑上问题不大但放到自动部署、CI/CD、或者团队内部分发的时候就很麻烦交互式授权没法自动完成账号权限也不好统一管理。所谓“免登录”本质上是跳过这个浏览器授权环节改用 API Key 直连的方式完成鉴权。它不是绕过什么安全机制而是用一种更可控的认证配置替代交互式登录。具体实现靠两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。Claude Code 启动时会优先读取它们一旦检测到就不会再走 OAuth 登录流程。这里有一个容易混淆的点需要单独说明免登录只是免了“产品账号授权”后端模型的鉴权仍然存在。也就是说你始终需要给模型提供合法有效的 API Key只是这个 Key 变成了环境变量里的 token而不是浏览器会话。1.3 国产模型是怎么接进来的Claude Code 默认请求的是 Anthropic 本身的 Messages API而 DeepSeek、通义千问、Kimi 这些国产模型大多提供的是 OpenAI 风格的接口两者在请求格式、消息结构上并不一致。所以单纯把ANTHROPIC_BASE_URL改成国产模型的地址通常不会成功中间还差一层协议转换。常见的解决办法是用 API 网关比如 one-api、new-api 这类开源网关把 Anthropic 格式转成 OpenAI 格式再把请求转发到具体模型也有一些模型服务商直接提供了 Anthropic 兼容的端点那配置就更简单。个人体验下来先部署一个网关把“模型映射”管起来是最省心的路径。后面想换模型只需要在网关里改映射关系不用频繁动 Claude Code 的配置。这套思路和开发环境里的“统一网关层”很像客户端只认一个地址后端怎么路由、怎么切换、怎么限流全在网关层解决。对于要接多个国产模型、给多个团队成员共用一套配置的场景这个优势尤其明显。2. 环境准备Node.js 和安装基础2.1 Node.js 版本怎么选Claude Code 是基于 Node.js 的命令行工具官方要求 Node.js 18 及以上。我建议直接装 20 或 22 的 LTS 版本版本太老会遇到一些依赖解析问题版本太新有时又容易踩到生态兼容的坑LTS 是最稳的区间。安装方式就看个人习惯Windows 直接官网下载安装包macOS 用 HomebrewLinux 用包管理器但如果你会同时维护多个 Node 项目强烈建议用 nvm 或 nvm-windows 这种版本管理器。装完之后先确认环境变量和命令是否生效终端里执行node -v和npm -v能正常输出版本号再往下走。不要小看这一步我见过不少后面怎么排查都找不到原因的问题最后发现是 Node 没装好或者 PATH 有问题导致 npm 命令没指向预期版本。确认好了再安装 Claude Code可以省掉后面一长串的排查时间。2.2 安装 Claude Code 的两种方式第一种是全局安装终端里执行npm install -g anthropic-ai/claude-code。好处是任何目录下都能直接用claude命令个人电脑上最省事。第二种是项目内安装执行npm install --save-dev anthropic-ai/claude-code然后通过npx claude启动好处是版本跟着项目走适合团队协作时锁定统一版本。这里有一个常见坑在 Unix 系统上用sudo npm install -g去解决权限问题事后往往会引入更多麻烦比如不同用户下 Node 版本不一致、全局目录归属混乱等。更干净的做法是用 nvm 管理 Node这样 npm 全局目录就在用户目录下不需要 sudo。Windows 用户如果遇到 npm 全局目录没有加入 PATH 导致claude命令找不到优先检查 npm 的 prefix 路径而不是马上重装 Node。2.3 验证安装是否成功安装完成后先执行claude --version看版本号再执行claude doctor它会检查 Node 版本、环境变量、模型端点、配置文件是否就绪。这一步很重要很多问题在 doctor 阶段就能看出来比如某个关键环境变量没读到它会直接提示省得你进交互界面后才发现异常。注意如果还没配环境变量直接执行claude可能会弹出登录界面这是正常现象按 CtrlC 退出即可不影响后续配置。把环境变量配好之后再启动就会跳过这一步。我自己在搭建过程中习惯把claude --version和claude doctor的输出截图保存一份后面对比配置变更很方便尤其是 Claude Code 频繁更新版本的时候很多环境变量名在不同版本之间会有差异。3. 免登录配置从 OAuth 到 Key 直连3.1 免登录的原理环境变量优先级Claude Code 启动时判断认证来源的顺序大致是环境变量、settings.json 中的 env 配置、已保存的登录态。只要检测到有效的ANTHROPIC_AUTH_TOKEN它就用这个 token 作为请求头的 Authorization 信息完全跳过浏览器 OAuth。同理设置ANTHROPIC_BASE_URL后所有请求会发送到你定义的服务地址不再访问默认的官方 API 地址。两个变量一组合就实现了“免登录 自定义模型端点”。这里面有个值得注意的细节不同版本对变量名的支持稍有差异。新版本会统一读取ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL这类变量个别早期版本还兼容旧的变量名。所以配置前先执行claude --help看当前版本支持哪些环境变量比在网上抄一段配置然后发现失效要高效得多。Claude Code 迭代速度很快隔几个月接口行为就可能变化一切以你本地版本的帮助信息为准。3.2 Windows 下的环境变量设置实操Windows 上终端分为 PowerShell 和 CMD命令不一样。PowerShell 里临时设置用$env:ANTHROPIC_BASE_URL http://localhost:8080 $env:ANTHROPIC_AUTH_TOKEN sk-你的网关KeyCMD 里则用setset ANTHROPIC_BASE_URLhttp://localhost:8080 set ANTHROPIC_AUTH_TOKENsk-你的网关Key临时设置只在当前终端窗口生效关掉就没了。永久设置可以用系统设置界面新增用户环境变量也可以用setx但我不太推荐直接用setx写 token因为命令本身会留在 shell 历史记录里存在泄露风险。我个人的做法是把环境变量写在一个.env文件里用 PowerShell 写一个小函数在每次启动终端时加载而不是用 setx。这样 token 不会散落到 shell 历史里也方便团队拷贝更新。3.3 macOS / Linux 下的环境变量设置实操macOS 和 Linux 下通常把配置写在~/.zshrc或~/.bashrc里export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_AUTH_TOKENsk-你的网关Key保存后执行source ~/.zshrc或者新开一个终端窗口。如果是团队项目强烈推荐用 direnv 让变量只在某个项目目录生效避免所有项目共用同一个模型端点。改完.zshrc一定要 source 或者新开终端否则环境变量不生效这是新手最容易踩的坑没有之一。很多人在终端里临时 export 一次发现能跑就以为配置成功了结果新开窗口又打回原形其实只是没做持久化。3.4 settings.json另一种全局注入方式Claude Code 也支持通过项目根目录下的.claude/settings.json写入 env 字段{ env: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: sk-xxx } }这种方式的好处是配置跟着项目走团队成员 clone 下来之后自带一份基础配置不用每个人手动敲环境变量。坏处也很明显token 如果写进去很容易被提交到 Git 仓库造成密钥泄露。所以我建议 settings.json 里只写非敏感配置比如模型名、输出偏好token 一律用环境变量或本地的.env文件管理。团队场景下可以让成员各自维护本地的环境变量settings.json 只负责项目通用的行为配置这样既保证了开箱即用又不会把密钥暴露在代码库里。4. 接入国产模型兼容层与模型选型4.1 协议桥接为什么要有一层网关国产模型服务商给的大多是 OpenAI 风格接口而 Claude Code 发出的是 Anthropic Messages API 格式两边直接对接会鸡同鸭讲。整体流程就像两个说不同语言的人要通话中间得有个翻译。这里的“翻译”就是协议转换层把 Claude Code 的请求转成 OpenAI 格式再把国产模型返回的结果转回 Anthropic 格式。目前最常见的实现是部署 one-api 或 new-api 这类开源网关。它们自带渠道管理、模型映射、令牌签发功能配置界面也比较直观。整体流程分三步第一步在网关后台添加渠道填入国产模型平台的 API Key 和端点地址第二步建立模型映射把 Claude Code 请求的模型名指向你要用的国产模型第三步在网关里生成一个令牌这个令牌就是ANTHROPIC_AUTH_TOKEN的值网关地址就是ANTHROPIC_BASE_URL。网关方案只是其中一种选择如果你用的模型厂商本身提供 Anthropic 兼容端点那就可以省掉网关这一层直接配置但就目前市面上的情况看多数国产模型还没有原生 Anthropic 兼容接口所以网关还是最常见的方案。4.2 主流国产模型接入参数对照下表是我整理过的几家常见国产模型公开兼容信息重点看端点格式和推荐模型名。具体参数和限流信息请以各家官方文档为准因为这类信息会调整。厂商OpenAI 兼容端点推荐模型名备注DeepSeekhttps://api.deepseek.com/v1deepseek-chat、deepseek-reasoner编码和逻辑能力稳定工具调用表现不错阿里云百炼通义千问https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus、qwen-turbo、qwen-coder-pluscoder 系列在代码生成上更专注MoonshotKimihttps://api.moonshot.cn/v1moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k长上下文是特色适合处理大型代码库智谱 GLMhttps://open.bigmodel.cn/api/paas/v4glm-4-plus、glm-4.5整体性能均衡国内访问速度不错在网关里配置渠道时把上面对应的端点填到渠道 URLAPI Key 填对应的密钥然后建立模型映射。比如 Claude Code 默认请求claude-sonnet-4-20250514这类模型名在网关里把这个名字映射到deepseek-chat这样 Claude Code 端看到的还是 Claude 的模型名实际背后调用的已经是国产模型了。如果映射漏了最常见的报错就是Model Not Found。4.3 模型参数与编码体验调优免登录加国产模型的体验上限往往取决于三件事模型映射是否完整、上下文长度是否够用、工具调用是否稳定。第一件事是模型映射完整性。Claude Code 除了主模型还会调用一个小模型做后台任务比如生成对话标题、总结上下文对应的环境变量是ANTHROPIC_SMALL_FAST_MODEL。如果你只映射了主模型而漏掉小模型可能会出现主流程正常、后台任务偶发报错的情况。建议把主模型和小模型都映射好并在网关里分别指定实际目标。第二件事是上下文长度。不同国产模型支持的窗口大小差异很大而 Claude Code 默认会维护较长的对话历史。如果模型窗口不够对话变长后容易截断或报错。我常用的办法是在 settings.json 里适当限制历史保留轮数或者对话太长时用/compact压缩上下文把历史对话总结成精简摘要再继续。第三件事是工具调用稳定性。Claude Code 高度依赖 function calling 来执行多步任务一次完整的代码重构可能涉及十几轮工具调用。不同模型在这一项上的表现差异非常大单纯看跑分很难判断。选型时应该重点测试“多轮工具调用是否能保持稳定”比如让它连续修改多个文件中途不断句、不跳步骤。国产模型里有些在单轮问答上表现很好但一旦进入复杂工具调用流程就会掉链子这个只能实测。5. 实战免登录模式下跑通第一个任务5.1 完整启动流程配置完成后的启动流程其实很短整理成清单如下启动网关确认模型渠道状态正常。设置好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。进入项目目录。执行claude --version确认工具可用。执行claude看到 Claude Code 启动提示并且没有跳登录页面就说明配置成功。我实际跑通过一次典型场景用 DeepSeek 的deepseek-chat模型让它“读取当前目录的 README.md总结项目结构和主要模块”。启动后直接进入交互模式没有登录弹窗输入指令后模型很快给出分析结果。整个过程和用官方模型没有明显差别工具调用的日志也能在终端里看到。为了让结果更直观我还让它自己对一个旧模块做了重构它先分析了目录结构再用编辑器工具批量替换了变量命名最后跑了一遍测试命令确认没有破坏功能。这套流程下来基本可以确定整条链路是通的。5.2 非交互模式与内置命令除了交互式使用Claude Code 还支持非交互模式。用-p参数可以直接在命令行里一次性执行任务比如claude -p 帮我检查 src 目录下有没有未使用的 import这种用法非常适合脚本调用和 CI 流程。我可以把它嵌到一个 Git 钩子里每次提交前让 Claude Code 快速做一轮代码审查几十秒出结果虽然不能完全替代人工 review但能挡掉不少低级问题。交互模式下有几个内置命令值得熟悉/help查看所有命令/status查看当前连接端点和模型信息/model切换模型/compact压缩上下文/clear清空当前会话/exit退出。我平时用/status最多它能直接告诉你当前请求到底打到了哪个端点、用的哪个模型排查配置问题时非常方便。/model能否列出可选模型取决于网关是否实现了模型列表接口如果网关没实现这个命令可能不生效需要回到网关侧去改映射。5.3 与 VSCode 终端的集成技巧虽然 Claude Code 是纯终端工具但配合 VSCode 使用体验会提升不少。最直接的方式是在 VSCode 里打开内置终端直接执行claude。这样它在终端里操作文件时左侧的文件树会实时刷新你一眼就能看出哪些文件被修改了。如果你是 Windows 用户建议用 Windows Terminal 加 PowerShell Core 或者 Git Bash默认的 CMD 终端在处理字符编码和交互输出时偶尔会有小问题。在 VSCode 的settings.json里也可以做一些体验优化比如把终端字体调大一点、开启平滑滚动长时间使用会舒服很多。另外我习惯在项目根目录配一个.vscode/settings.json默认把终端设为项目专用打开 VSCode 后直接按快捷键就能调出终端并进入项目目录省去手动 cd 的步骤。6. 常见问题排查与避坑实录6.1 常见问题速查表下面这张表是我在搭建和日常使用中总结的高频问题按“现象、可能原因、解决办法”三列整理方便你对照处理现象可能原因解决办法启动后仍然弹登录界面ANTHROPIC_AUTH_TOKEN没有写入到实际生效的 shell确认环境变量已导出并新开终端执行echo $env:ANTHROPIC_AUTH_TOKEN检查调用报 401 Unauthorizedtoken 无效或者网关没有识别请求头里的认证信息在网关后台用测试功能验证渠道和令牌确认 token 前后没有误加空格报 404 Model Not Found模型映射缺失Claude Code 请求的模型名在网关里不存在在网关中建立模型映射把请求的模型名指向实际要用的国产模型请求超时网关连接模型服务超时或所选模型响应太慢调大网关超时时间先换一个快速的模型排查是不是模型本身的问题返回内容截断上下文长度溢出超过了模型窗口用/compact压缩历史在 settings.json 里限制历史轮数npm 安装失败Node 版本不对或 npm 源不稳定用 nvm 切换 Node 20 LTS清除 npm 缓存后重试claude命令找不到npm 全局 bin 目录不在 PATH检查npm prefix把全局目录加入 PATH6.2 值得注意的几个细节第一免登录不是免鉴权。模型侧的 API Key 依然必须有只是从交互式登录变成了环境变量注入。换句话说ANTHROPIC_AUTH_TOKEN本质上就是一个密钥它的安全级别应该和正式 API Key 同等对待。第二使用第三方网关时代码内容会经过网关转发。如果你的项目涉及敏感数据这一点需要提前评估。在个人开发机上跑没问题但在公司环境里使用前要确认网关的部署位置和访问权限不要让网关直接暴露在公网上。第三环境变量不生效时优先检查当前的 shell 类型。Windows 下 PowerShell 和 CMD 的语法不一样macOS 下 zsh 和 bash 的配置文件也不一样。改了配置文件一定要新开一个终端窗口不要在当前窗口里反复刷source然后说没生效。第四Claude Code 版本迭代很快配置参数可能随时变化。我在不同版本上就遇到过环境变量名调整、/model行为变化的情况。最靠谱的方式是遇到问题先看claude --help和claude doctor的输出而不是直接翻旧帖子照搬。第五国产模型很多不支持图片输入和多模态能力。如果你有“截图让 AI 看”的需求目前这套免登录加国产模型的方案可能覆盖不了需要考虑保留官方模型入口或者做功能降级。这套配置跑顺之后我最大的感受不是“省了登录那一步”而是整个工具链变得可编程了。我后来把它封装成一个启动脚本团队成员拉下来就能用前后端同事不用各查一套文档。如果你也想搭自己的 Claude Code 环境建议先别急着上大模型拿一个小而快的模型把整条链路跑通再逐步替换成大参数模型这样排查问题会容易很多。希望这篇记录能帮你少走几步弯路。