1. free-claude-code 到底解决了什么问题从 Claude Code 的 API 账单说起Claude Code 是 Anthropic 推出的终端编程智能体能读文件、改代码、跑命令深度集成在终端和 VSCode 里。它的工作方式其实很朴素客户端把上下文打包成 Anthropic Messages API 格式POST 到/v1/messages拿到响应后解析成工具调用、文本输出、思考块。问题在于这个接口背后是真实的 Anthropic API Key按 token 计费重度使用一个月几十到几百美元很正常。free-claude-code 的核心洞察就一句话Claude Code 只是一个 HTTP 客户端它只认ANTHROPIC_BASE_URL指向的地址。只要在本地起一个兼容 Anthropic Messages 格式的代理服务器把请求拦截下来转换成 OpenAI Chat Completions 格式转发给免费或低价后端NVIDIA NIM、OpenRouter、DeepSeek、本地 Ollama/LM Studio再把响应转回 Anthropic 格式Claude Code 完全感知不到差异。这个项目用 Python FastAPI 实现入口是server.py调用api/app.py里的create_app()工厂函数构建应用。路由、格式转换、限速管理都封装在api/模块下。它适合谁想低成本体验 Claude Code 工作流的学生、想对比不同开源模型编码能力的开发者、想在内网用 Ollama 做完全离线编程助手的小团队。不适合谁指望免费后端达到 Claude Sonnet/Opus 同等代码推理质量的生产环境用户——这一点后面会展开。我试过把 Opus/Sonnet/Haiku 三个层级分别路由到不同后端同一套 Claude Code 界面下横向对比模型表现这个玩法比单纯省钱更有意思。下面从代理原理讲到可复制的配置片段再到一次真实的请求转发验证。2. 前置准备Python 环境、uv 与 FastAPI 代理的依赖安装在动手之前先把环境理清楚。free-claude-code 是纯 Python 项目推荐用uv管理依赖它比 pip 快很多也能自动处理虚拟环境。你需要 Python 3.10 以上终端能正常访问网络以及至少一个后端服务的凭证或本地模型服务。第一步安装 uv。如果你已经有 pip直接pip install uvmacOS 或 Linux 也可以用官方脚本curl -LsSf https://astral.sh/uv/install.sh | sh第二步克隆仓库并进入目录git clone https://github.com/Alishahryar1/free-claude-code.git cd free-claude-code第三步复制配置文件模板cp .env.example .env第四步安装依赖。项目用pyproject.toml声明依赖uv 会自动读取uv sync这一步会拉取 FastAPI、uvicorn、httpx、pydantic 等包。如果uv sync报错找不到 lock 文件可以先用uv pip install -e .兜底。关于后端选择这里给一个决策参考后端成本是否需要联网适合场景NVIDIA NIM免费额度 40 req/min是快速体验模型质量中等OpenRouter部分模型每日免费是模型选择多580DeepSeek极低价格是原生支持 Anthropic 格式Ollama完全免费否离线、隐私敏感、有显卡LM Studio完全免费否图形界面管理本地模型如果你只是想先跑通链路NVIDIA NIM 的免费额度最省事注册后在控制台拿nvapi-开头的 Key 即可。本地 Ollama 路线则完全零成本但需要至少 16GB 显存跑 7B 级别模型32B 编码模型建议 24GB 以上。环境准备好后下一步就是写配置。这里有个容易踩的坑.env文件里的变量名必须和项目读取的完全一致大小写敏感写错一个字母代理就会用默认值导致请求发到错误的后端。3. 可复制配置.env 文件、模型分级路由与 settings 片段这一节给出可以直接粘贴的配置。free-claude-code 通过.env文件读取所有参数核心分四组后端凭证、模型分级路由、Thinking 支持、限速控制。先看最小可运行配置以 NVIDIA NIM 为例# 后端凭证 NVIDIA_NIM_API_KEYnvapi-你的真实key # 模型分级路由 MODEL_OPUSnvidia_nim/nvidia/llama-3.1-nemotron-ultra-253b-v1 MODEL_SONNETnvidia_nim/nvidia/llama-3.3-70b-instruct MODEL_HAIKUnvidia_nim/meta/llama-3.1-8b-instruct # 服务监听 HOST0.0.0.0 PORT8082模型分级路由是项目的精髓。Claude Code 内部会根据任务复杂度选择 Opus、Sonnet 或 Haiku 层级代理把这三个层级映射到不同后端模型。你可以让 Opus 走最强模型、Haiku 走最便宜的精细控制成本。如果你用本地 Ollama配置改成这样OLLAMA_BASE_URLhttp://localhost:11434 MODEL_OPUSollama/qwen2.5-coder:32b MODEL_SONNETollama/qwen2.5-coder:14b MODEL_HAIKUollama/qwen2.5-coder:7bThinking 支持是另一个亮点。部分开源模型DeepSeek-R1、QwQ、GLM-Z1会输出think.../think包裹的推理过程代理能把它转成 Anthropic 原生 thinking 内容块VSCode 扩展里能折叠显示ENABLE_SONNET_THINKINGtrue ENABLE_OPUS_THINKINGtrue限速配置针对免费额度的速率限制PROVIDER_RATE_LIMIT1 PROVIDER_MAX_CONCURRENCY5PROVIDER_RATE_LIMIT是每秒最大请求数PROVIDER_MAX_CONCURRENCY是最大并发。NVIDIA NIM 免费层是 40 req/min换算约 0.67 req/s设成 1 比较稳妥。如果你用 Claude Code 的 settings 文件方式管理环境变量可以在~/.claude/settings.json里加{ env: { ANTHROPIC_BASE_URL: http://localhost:8082, ANTHROPIC_API_KEY: sk-ant-placeholder } }注意ANTHROPIC_API_KEY这里填占位符即可因为真正的鉴权在代理层用后端 Key 完成。Claude Code 只要求这个变量存在不校验内容。配置写完后启动代理uv run uvicorn server:app --host 0.0.0.0 --port 8082看到Uvicorn running on http://0.0.0.0:8082就说明代理起来了。此时它还没收到任何请求下一步我们验证链路。4. 验证请求用 curl 和 Claude Code 走通代理链路代理启动后先别急着开 Claude Code用 curl 直接打一发确认格式转换正常。这一步能快速定位是代理问题还是客户端问题。curl -X POST http://localhost:8082/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-ant-placeholder \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 256, messages: [ {role: user, content: 用一句话解释什么是 FastAPI} ] }如果代理工作正常你会收到 Anthropic 格式的响应结构类似{ id: msg_xxx, type: message, role: assistant, content: [ {type: text, text: FastAPI 是一个基于 Python 类型注解的现代异步 Web 框架。} ], stop_reason: end_turn }注意model字段你填的是claude-sonnet-4-5但代理内部会把它映射到MODEL_SONNET配置的后端模型。这就是透明代理的关键——客户端以为自己在调 Claude实际请求发到了 Llama 或 Qwen。curl 通了之后再启动 Claude CodeANTHROPIC_BASE_URLhttp://localhost:8082 claude进入交互界面后随便让它读一个文件比如帮我看看当前目录下的 README.md 讲了什么Claude Code 会发起工具调用读文件代理把 Anthropic 的tool_use块转成 OpenAI 的tool_calls后端模型返回结果后再转回来。如果这一步能正常显示文件内容说明工具调用链路也通了。流式响应是另一个验证点。Claude Code 默认用 SSE 流式接收代理需要把后端的 SSE 流转成 Anthropic 的event: content_block_delta格式。如果 curl 用-N参数能看到逐块输出说明流式转换正常curl -N -X POST http://localhost:8082/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-ant-placeholder \ -d {model:claude-sonnet-4-5,max_tokens:128,stream:true,messages:[{role:user,content:数到五}]}实测下来NVIDIA NIM 的 Llama 3.3 70B 在简单问答上响应稳定但涉及多步工具调用时偶尔会格式错乱代理的启发式解析能兜底一部分但不是 100% 可靠。这是免费后端的固有局限不是代理的 bug。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth代理链路涉及客户端、代理、后端三层出错时定位要按层排查。下面是我踩过的几个典型坑。401 Unauthorized最常见。先确认.env里的后端 Key 是否正确NVIDIA NIM 的 Key 以nvapi-开头OpenRouter 以sk-or-开头。如果 Key 没问题检查代理是否真的读到了.env——uvicorn 启动时的工作目录必须是项目根目录否则.env不会被加载。可以在server.py里临时加一行print(os.environ.get(NVIDIA_NIM_API_KEY))确认。local proxy failed / connection refusedClaude Code 报这个说明它连不上ANTHROPIC_BASE_URL。检查代理是否在监听、端口是否被占用、防火墙是否拦截。用curl http://localhost:8082/health或直接打/v1/messages确认代理存活。如果代理在 Docker 里localhost要换成宿主机 IP。Error reading choices / 响应解析失败这个报错来自代理内部通常是后端返回的 JSON 结构不符合预期。OpenAI 格式的响应里choices[0].message.content是核心字段如果后端返回了非标准结构比如某些模型把内容放在reasoning_content里代理解析就会失败。解决办法是在.env里换一个更规范的模型或者检查后端是否开启了兼容模式。OAuth / authentication_error如果你之前用真实 Anthropic Key 登录过 Claude Code它可能缓存了 OAuth token导致请求没走代理。清掉~/.claude/下的凭证缓存或者显式设置ANTHROPIC_API_KEY为占位符覆盖。429 Too Many Requests免费额度打满了。NVIDIA NIM 是 40 req/minClaude Code 频繁发上下文很容易触发。调低PROVIDER_RATE_LIMIT或者开启代理的主动节流。项目内置了反应式退避收到 429 后会解析retry-after头重试但等待期间 Claude Code 界面会卡住。工具调用格式错误开源模型的tool_calls格式参差不齐有的把参数写成字符串而非 JSON 对象。代理有启发式解析兜底但复杂工具调用仍可能失败。如果频繁遇到换一个工具调用能力更强的模型比如 Qwen2.5-Coder 系列。排查时建议开代理的 debug 日志能看到每个请求的原始格式和转换后格式定位问题快很多。6. 从免费代理到稳定接入TaoToken 的模型对话与 Coding Plan 路径free-claude-code 证明了代理层的可行性但免费后端的模型质量和速率限制是硬约束。如果你希望保留 Claude Code 的工作流同时获得更稳定的模型供给和更清晰的计费可以把代理指向 TaoToken 的兼容接口。TaoToken 提供 Anthropic 兼容的 API 端点Base URL 是https://taotoken.net/api你可以在控制台创建 API Key然后在.env里把后端指向它ANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_API_KEY你的taotoken_key MODEL_SONNETclaude-sonnet-4-5 MODEL_OPUSclaude-opus-4-5这样 Claude Code 的请求会经过 TaoToken 转发到真实模型格式无需转换工具调用和 thinking 块原生支持。相比免费后端稳定性和模型质量都有保障。如果你主要做长期编码和 Agent 任务可以了解 Coding Plan它针对高频编程场景做了额度优化。想先验证模型效果可以直接在模型对话页面测试。需要管理多个 Key 或查看用量进控制台接入文档在文档页API Key 创建入口在 API Keys 页面。对于 Claude Code 用户还有一个细节如果你用 ClaudeCodeAnthropic 相关的配置方式确保ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY同时设置且 Key 有对应模型的调用权限。代理层和直连层的区别只在于中间多了一跳客户端配置逻辑是一样的。回到 free-claude-code 本身它的价值不在于替代付费服务而在于把代理层的工程实现摊开给你看FastAPI 路由、格式转换、流式处理、限速退避这些是构建任何 AI 网关都会遇到的核心问题。读懂它你就能自己搭一个更可控的接入层。