1. 为什么要把 NVIDIA 免费 API 接进 Claude CodeClaude Code 的工程能力确实好用上下文管理、记忆系统、Skill 封装、工具调用、Subagent 控制这些机制用过一段时间就很难回去了。但官方 API 的账单也是真的顶不住尤其是拿它跑长任务、反复读大文件的时候token 消耗速度远超预期。很多人想低成本体验 Claude Code卡点其实不在客户端本身而在于背后那个 Anthropic 兼容的 endpoint 从哪来。free-claude-code 这个开源项目解决的正是这个中间层问题。它本质是一个本地代理服务对外暴露 Anthropic Messages API 的格式对内把请求翻译成 OpenAI 兼容格式转发给 NVIDIA NIM 这类提供免费额度的推理服务。Claude Code 完全感知不到背后换了模型它以为自己还在和 Anthropic 官方通信于是原生的工具调用、思考链展示、Skill 机制都能继续用。NVIDIA NIM 的免费层给到每分钟 40 次请求注册即用对日常开发来说基本够。配合 free-claude-code 的并发控制和 429 退避不容易被限流打挂。它支持的模型里GLM-5.1 中文理解强、长上下文稳MiniMax M2.7 的 coding 速度不错Kimi K2 Thinking 的思考链保留得比较完整这些都能通过.env里的模型映射统一配置。这篇记录面向的是想低成本体验 Claude Code 的开发者我会把环境变量、配置文件片段、启动命令、验证请求一步步写清楚也会说明怎么把 endpoint 改到 TaoToken 的统一 Key/API 通道方便后续切换模型时不用反复改本地代理。整套流程在 Windows 上实测跑通Linux/macOS 只需把路径和启动脚本换一下即可。需要提前说明一点free-claude-code 是本地代理它不改变 Claude Code 的调用协议只是把请求转出去。所以你的settings.json里ANTHROPIC_BASE_URL指向的是http://localhost:8082而不是任何外部地址。这个认知很关键后面排查报错时全靠它。2. 前置准备NVIDIA Key、uv 与 free-claude-code 项目结构动手之前先把三样东西备齐一个 NVIDIA API Key、Python 的 uv 包管理器、以及克隆下来的 free-claude-code 仓库。这三样缺一个后面都会卡住所以先集中处理。NVIDIA API Key 去 build.nvidia.com 申请注册后生成的 Key 以nvapi-开头。免费层每分钟 40 次请求个人开发足够。拿到 Key 之后先别急着填等.env文件建好再统一写进去避免中途改来改去。uv 是 Python 的现代包管理器比 pip 快很多free-claude-code 官方推荐用它。安装命令pip install uv如果你机器上已经有 Python 3.10这行就能装上。装完可以用uv --version确认一下。接着克隆项目git clone https://github.com/Alishahryar1/free-claude-code.git cd free-claude-code进入目录后执行依赖同步uv sync这一步会创建.venv虚拟环境并把依赖装进去。实测下来第一次会拉一些包耐心等它跑完。项目结构里比较关键的几个文件server.py是代理入口.env是你的配置nvidia_nim_models.json列出了 NVIDIA NIM 可用的模型清单。后面改模型名的时候直接对照这个 json 里的命名空间写能少踩很多坑。这里插一句关于模型命名的经验。NVIDIA NIM 的模型名带命名空间比如z-ai/glm-5.1、minimaxai/minimax-m2.7、moonshotai/kimi-k2-thinking。在.env里配置时要带上nvidia_nim/前缀写成nvidia_nim/z-ai/glm-5.1这种形式。很多人报 “model may not exist” 就是因为前缀漏了或者命名空间写错。另外提醒一下Claude Code 的配置文件在 Windows 上是C:\Users\你的用户名\.claude\settings.jsonLinux/macOS 是~/.claude/settings.json。这个文件如果之前配过别的代理建议先备份一份免得改乱了回不去。3. 可复制配置.env 与 settings.json 片段这一节是整篇的核心配置写对了后面基本就顺了。先建.env文件放在 free-claude-code 项目根目录下NVIDIA_NIM_API_KEYnvapi-你的Key MODEL_OPUSnvidia_nim/z-ai/glm-5.1 MODEL_SONNETnvidia_nim/z-ai/glm-5.1 MODEL_HAIKUnvidia_nim/z-ai/glm-5.1 MODELnvidia_nim/z-ai/glm-5.1 ENABLE_THINKINGtrue PROVIDER_RATE_LIMIT40这里MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU是 Claude Code 内部三个档位的模型映射你可以让它们指向同一个模型也可以分别指向不同模型实现混搭。比如把 Haiku 档位映射到速度快的 MiniMaxOpus 档位映射到思考能力强的 Kimi K2MODEL_OPUSnvidia_nim/moonshotai/kimi-k2-thinking MODEL_SONNETnvidia_nim/z-ai/glm-5.1 MODEL_HAIKUnvidia_nim/minimaxai/minimax-m2.7 MODELnvidia_nim/z-ai/glm-5.1ENABLE_THINKINGtrue会让支持思考链的模型把推理过程透传出来GLM、Kimi K2 这类模型在 Claude Code 里能看到思考过程。PROVIDER_RATE_LIMIT40对应 NVIDIA 免费层的每分钟 40 次代理会据此做并发控制。接着配置 Claude Code 的settings.json。Windows 路径{ env: { ANTHROPIC_BASE_URL: http://localhost:8082, ANTHROPIC_AUTH_TOKEN: ccnim } }Linux/macOS 路径是~/.claude/settings.json内容一样。注意ANTHROPIC_AUTH_TOKEN这里填的是占位值ccnim因为真正的鉴权在代理层用 NVIDIA Key 完成Claude Code 这边只要有个非空 token 就行。如果你希望后续能统一走 TaoToken 的 Key/API 通道方便在不同模型之间切换可以把ANTHROPIC_BASE_URL改成 TaoToken 的 API 地址把ANTHROPIC_AUTH_TOKEN换成 TaoToken 的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的TaoToken Key } }这样 Claude Code 的请求会先到 TaoToken 的统一通道再由它路由到目标模型。好处是以后换模型只改 TaoToken 后台的配置不用动本地文件。TaoToken 的 Key 在控制台创建地址是 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。如果你更想先验证模型对话效果可以直接用 https://taotoken.net/models 试跑。配置写完后启动代理uv run uvicorn server:app --host 0.0.0.0 --port 8082Windows 上如果不想每次手动敲可以建一个启动代理.batecho off cd /d D:\project2026\free-claude-code start NVIDIA NIM Proxy cmd /k .venv\Scripts\uvicorn.exe server:app --host 0.0.0.0 --port 8082双击运行即可。代理起来后在任意终端执行claude就会自动走这个代理。4. 验证请求一次成功的接入演示配置写完不代表通了得实际发一次请求确认链路。验证分两步先确认代理端口在监听再让 Claude Code 发一条消息看返回。先检查端口。Windows 上用netstat -ano | findstr 8082Linux/macOS 用lsof -i :8082能看到监听状态说明代理起来了。如果没输出回去看代理启动那步的终端日志通常是.env里 Key 没填对或者依赖没装全。端口正常后直接启动 Claude Codeclaude进去之后说一句“你好”观察返回。如果配置正确你会看到模型正常回复而且因为ENABLE_THINKINGtrueGLM 或 Kimi K2 这类模型可能会把思考过程也展示出来。这一步成功说明 Anthropic 格式的请求已经被代理正确翻译并转发到 NVIDIA NIM返回也正确转换回了 Claude Code 能识别的格式。想更直接地验证代理本身可以绕过 Claude Code用 curl 打一次代理的接口curl http://localhost:8082/v1/messages \ -H Content-Type: application/json \ -H x-api-key: ccnim \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 用一句话说明你是什么模型}] }如果返回里有content字段和文本内容说明代理的 Anthropic 兼容层工作正常。注意这里的model字段填的是 Claude 的模型名代理会根据.env里的映射把它换成 NVIDIA 的模型名这正是 free-claude-code 的核心机制。实测下来第一次请求可能会慢一点因为要建立到 NVIDIA 的连接。后续请求会快很多。如果遇到 429说明触发了免费层的速率限制代理会自动退避重试等几秒再发就行。验证通过后你就可以正常用 Claude Code 的工程能力了。读文件、改代码、跑命令、调 Subagent 这些都不受影响因为协议层没变变的只是背后的模型。5. 常见报错排查401、local proxy failed 与 model may not exist接入过程中最容易撞上的几类报错我按实际遇到的频率排一下每个都给出定位思路。第一类是 401 鉴权失败。表现是 Claude Code 里发消息直接返回 401或者代理终端打印鉴权错误。原因通常是.env里的NVIDIA_NIM_API_KEY没填、填错、或者 Key 已失效。检查三点Key 是不是nvapi-开头、有没有多余空格、在 build.nvidia.com 后台看 Key 是否还有效。另外settings.json里的ANTHROPIC_AUTH_TOKEN不能为空虽然它只是占位但空值会导致 Claude Code 本地就拒绝发送。第二类是local proxy failed或连接被拒。这通常是代理没起来或者端口被占用。先确认uvicorn进程在跑再看 8082 端口是否被别的程序占了。Windows 上可以用netstat -ano | findstr 8082找到占用进程的 PID任务管理器里结束掉再重启代理。还有一种情况是settings.json里ANTHROPIC_BASE_URL写成了https而不是http本地代理是 http写错协议会直接连不上。第三类是model may not exist或reading choices相关报错。前者是模型名不对检查.env里的模型名有没有带nvidia_nim/前缀命名空间是否和nvidia_nim_models.json里一致。后者通常是代理在解析上游返回时出错可能是上游返回了非预期格式或者模型不支持当前请求的某些参数。遇到这种先看代理终端的完整日志里面会打印上游的原始返回定位起来比在 Claude Code 里猜快得多。第四类是 OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留了 OAuth 凭证和现在的 token 配置冲突。解决办法是清理~/.claude下的凭证缓存或者确认settings.json里的env配置优先级高于残留凭证。实测下来把ANTHROPIC_AUTH_TOKEN显式写成一个非空值能覆盖掉大部分 OAuth 残留问题。第五类是请求超时。NVIDIA 免费层在高峰期可能响应慢代理默认超时如果设得短就会断。可以在.env里适当调大超时参数或者错峰使用。如果频繁超时考虑把模型换成响应更快的 MiniMax M2.7 试试。排查时有个通用原则先看代理终端日志再看 Claude Code 的报错。代理日志里有完整的请求和上游返回是定位问题的第一现场。Claude Code 那边的报错往往是二次封装过的信息量不如代理日志。6. 后续切换模型与统一通道的实践建议跑通之后日常使用中切换模型是高频操作。free-claude-code 的方式是改.env里的MODEL值然后重启代理。比如从 GLM-5.1 换到 MiniMax M2.7MODELnvidia_nim/minimaxai/minimax-m2.7改完双击启动代理.bat重启即可。这种方式简单直接缺点是每次换模型都要动本地文件、重启服务。如果你希望更省事可以把 endpoint 统一到 TaoToken 的通道。做法是把settings.json里的ANTHROPIC_BASE_URL指向https://taotoken.net/apiANTHROPIC_AUTH_TOKEN换成 TaoToken 的 Key。这样 Claude Code 的请求先到 TaoToken由它统一路由。换模型时只改 TaoToken 后台的配置本地文件不用动也不用重启代理。对于需要长期在多个模型之间切换、或者团队协作统一入口的场景这种方式维护成本更低。TaoToken 的 Key 在 https://taotoken.net/api-keys 创建接入细节看 https://taotoken.net/doc 。如果你还在选模型阶段可以先用 https://taotoken.net/models 做对话验证确认效果再接到 Claude Code 里。对于长期跑编码任务、Agent 工作流的需求Coding Plan 会更合适地址是 https://taotoken.net/coding-plan 。有一点要提醒无论走本地 free-claude-code 代理还是走 TaoToken 统一通道Claude Code 的settings.json里ANTHROPIC_BASE_URL只能指向一个地址。想同时保留两种方式可以准备两份 settings 文件用的时候切换或者用环境变量覆盖。实测下来环境变量的优先级高于文件配置临时切换时比较方便。最后说个实用技巧把常用的几组模型配置写成.env的注释块切换时取消注释对应行比每次手敲模型名快也不容易写错命名空间。模型名对照nvidia_nim_models.json里的清单那个文件是权威来源。