说实话，去年我第一次装 Claude Code 的时候，折腾得够呛：先要注册账号、绑定支付方式，然后启动时还得走一套 OAuth 授权，中间任何一步卡住，整个工具就没法用。后来我换了个思路，把认证方式从“账号登录”换成 API Key 直连，再把模型端点指向国产模型的兼容接口，一套免登录的 Claude Code 环境就稳定跑了起来。这篇文章就把完整流程写一遍，从 Node.js 环境准备、Claude Code 安装、免登录实现，到国产模型（DeepSeek、通义千问、Kimi 等）接入，全程用实际命令和参数说话。适合被官方账号登录折磨过的开发者，也适合想用国内模型跑 Claude Code 的个人和团队。
1. 先搞清楚这套方案在解决什么问题
1.1 为什么是 Claude Code
Claude 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 用 Homebrew，Linux 用包管理器，但如果你会同时维护多个 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可能会弹出登录界面，这是正常现象，按 Ctrl+C 退出即可，不影响后续配置。把环境变量配好之后，再启动就会跳过这一步。我自己在搭建过程中习惯把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-你的网关Key"CMD 里则用set：
set ANTHROPIC_BASE_URL=http://localhost:8080 set ANTHROPIC_AUTH_TOKEN=sk-你的网关Key临时设置只在当前终端窗口生效，关掉就没了。永久设置可以用系统设置界面新增用户环境变量，也可以用setx，但我不太推荐直接用setx写 token，因为命令本身会留在 shell 历史记录里，存在泄露风险。我个人的做法是：把环境变量写在一个.env文件里，用 PowerShell 写一个小函数在每次启动终端时加载，而不是用 setx。这样 token 不会散落到 shell 历史里，也方便团队拷贝更新。
3.3 macOS / Linux 下的环境变量设置实操
macOS 和 Linux 下，通常把配置写在~/.zshrc或~/.bashrc里：
export ANTHROPIC_BASE_URL="http://localhost:8080" export ANTHROPIC_AUTH_TOKEN="sk-你的网关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 兼容端点 | 推荐模型名 | 备注 |
|---|---|---|---|
| DeepSeek | https://api.deepseek.com/v1 | deepseek-chat、deepseek-reasoner | 编码和逻辑能力稳定，工具调用表现不错 |
| 阿里云百炼（通义千问） | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-plus、qwen-turbo、qwen-coder-plus | coder 系列在代码生成上更专注 |
| Moonshot（Kimi） | https://api.moonshot.cn/v1 | moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k | 长上下文是特色，适合处理大型代码库 |
| 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 | glm-4-plus、glm-4.5 | 整体性能均衡，国内访问速度不错 |
在网关里配置渠道时，把上面对应的端点填到渠道 URL，API 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 Unauthorized | token 无效，或者网关没有识别请求头里的认证信息 | 在网关后台用测试功能验证渠道和令牌；确认 token 前后没有误加空格 |
| 报 404 Model Not Found | 模型映射缺失，Claude Code 请求的模型名在网关里不存在 | 在网关中建立模型映射，把请求的模型名指向实际要用的国产模型 |
| 请求超时 | 网关连接模型服务超时，或所选模型响应太慢 | 调大网关超时时间；先换一个快速的模型排查是不是模型本身的问题 |
| 返回内容截断 | 上下文长度溢出，超过了模型窗口 | 用/compact压缩历史；在 settings.json 里限制历史轮数 |
| npm 安装失败 | Node 版本不对，或 npm 源不稳定 | 用 nvm 切换 Node 20 LTS；清除 npm 缓存后重试 |
claude命令找不到 | npm 全局 bin 目录不在 PATH | 检查npm prefix，把全局目录加入 PATH |
6.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 环境，建议先别急着上大模型，拿一个小而快的模型把整条链路跑通，再逐步替换成大参数模型，这样排查问题会容易很多。希望这篇记录能帮你少走几步弯路。
