Free Claude Code

国内不少开发者都有过这样的经历：早早订阅了Claude Code，用起来确实顺手，但一方面API账单逐月上涨，另一方面Claude对中国用户不够友好，订阅容易被封，很多时候只能被迫用第三方模型。

这两天GitHub上有个项目火得不行——Free Claude Code，已收获超过14,300颗Star、2,000多个Fork，连续四天霸榜GitHub Trending。它不是一个破解工具，也不是官方的免费版，而是一个本地代理，核心价值一句话就能说清楚：让你继续用Claude Code的客户端，但模型流量可以走NVIDIA NIM、OpenRouter、Gemini、DeepSeek、Kimi、Ollama等后端。

下面就来拆解一下这个项目到底怎么用、适合谁、有哪些值得注意的地方。

一、核心原理：一个本地代理层

Free Claude Code在本地启动一个FastAPI服务，拦截Claude Code原本发给Anthropic的API请求，再根据你的配置把请求转发到其他Provider上。Claude Code完全不知道背后发生了什么——它以为自己还在和Anthropic愉快地通信，实际上请求已经被“偷梁换柱”了。

这个代理层最核心的能力包括：

• 提供/v1/messages、/v1/messages/count_tokens、/v1/models等Anthropic兼容接口，Claude Code直接就能用，无需改动；
• 支持按模型层级路由：MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU可以分别指向不同的Provider，空着的tier会自动继承MODEL的配置；
• 支持Streaming流式输出、工具调用、推理/思考块处理等高级特性；
• 内置Admin UI，告别手撸配置文件的痛苦。

二、支持的Provider

目前项目官方列出的Provider多达17个，可分为三类：

云端API类（带免费额度或低成本）：

• NVIDIA NIM：免费额度约1000积分起（约40次/分钟/模型），是官方文档推荐的入门首选
• OpenRouter：提供30+免费模型接入，无需绑定信用卡
• Google AI Studio（Gemini）：Google官方免费API
• DeepSeek：国产大模型，API价格低得离谱
• Kimi（Moonshot）：国产大模型，支持Anthropic兼容接口
• Cerebras、Groq：超高速推理平台
• Fireworks AI、Z.ai等

本地部署类：

• Ollama：最轻量的本地模型运行方案
• LM Studio：带GUI的本地模型运行工具
• llama.cpp：纯C++实现的本地推理框架

远程调用类：

• Discord/Telegram Bot：远程执行Claude Code会话
• 语音笔记：支持Whisper或NVIDIA NIM语音转文字

简单说：想省钱，接带免费额度的云端API；注重隐私，接本地Ollama；想按任务类型拆分成本，用分层路由。

三、安装与配置（分步教程）

前置要求

• 已安装Claude Code CLI（官方版，需要先完成基础安装）
• Python ≥3.14.0
• （可选）对应Provider的API Key

步骤1：安装Free Claude Code

macOS / Linux：

curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh

Windows PowerShell：

irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex

⚠️ 安装前建议先看一眼脚本内容（scripts/install.sh或scripts/install.ps1），养成先阅后跑的好习惯。Re-run同样命令即可更新到最新版本。

步骤2：启动代理服务

fcc-server

启动后，终端会打印Admin UI地址：http://127.0.0.1:8082/admin（本地访问，不回环）。

步骤3：Admin UI中配置Provider

打开Admin UI后，你会看到可视化的配置面板。以最常见的三种场景为例：

场景一：NVIDIA NIM免费额度（最省心）

1. 前往 build.nvidia.com 注册免费账号，获取NVIDIA NIM API Key
2. 在Admin UI中粘贴到NVIDIA_NIM_API_KEY字段
3. 默认模型已设为nvidia_nim/nvidia/nemotron-3-super-120b-a12b，可直接使用
4. 点击Validate验证，再点Apply保存

场景二：OpenRouter多模型自由切换

1. 注册OpenRouter，获取API Key
2. Admin UI中填入OPENROUTER_API_KEY
3. 设置MODEL为open_router/openrouter/free，走免费额度

场景三：Ollama本地模型（零API成本）

1. ollama pull llama3.1拉取模型
2. ollama serve启动服务
3. Admin UI中保持OLLAMA_BASE_URL为默认（一般是http://localhost:11434）
4. 设置MODEL为ollama/llama3.1

步骤4：启动Claude Code

普通用户用官方启动命令即可：

fcc-claude

这个包装命令会自动设置环境变量，包括ANTHROPIC_BASE_URL指向代理、ANTHROPIC_AUTH_TOKEN、以及一个190k token的自动压缩窗口CLAUDE_CODE_AUTO_COMPACT_WINDOW。

四、与IDE集成

VS Code：在settings.json中添加如下配置，然后重载扩展：

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },
  { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" }
]

JetBrains IDE：修改~/.jetbrains/acp.json中的环境变量配置（Windows路径为%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json），保存后重启IDE。

五、进阶用法：按模型层级路由

用一个例子来说明分层路由的能力：在Admin UI中设置环境变量如下：

MODEL_OPUS="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
MODEL_SONNET="open_router/openrouter/free"
MODEL_HAIKU="ollama/llama3.1"
MODEL="zai/glm-5.1"

• Opus级别任务（最高要求）走NVIDIA NIM
• Sonnet级别（中等要求）走OpenRouter免费额度
• Haiku级别（轻量任务）走本地Ollama
• 兜底fallback走Z.ai

不是所有任务都需要最贵模型。改文案、补测试、扫lint、解释报错，很多时候用便宜模型就已经够用了。这个分层能力对重度用户非常实用。

六、进阶用法：远程Bot + 语音笔记

Discord/Telegram Bot

Admin UI → Messaging面板中配置：

1. Discord：在Discord Developer Portal创建Bot，开启Message Content Intent，获取Bot Token和频道ID
2. Telegram：通过@BotFather创建Bot，用@userinfobot获取自己的User ID
3. Admin UI中填入Token和Allowed Directory（Bot可访问的目录路径）
4. 支持/stop取消任务、/clear重置会话、/stats查看状态

语音笔记

需要安装语音扩展（--voice-local或--voice-nim），Admin UI中开启Voice Notes即可。在外边灵感乍现，直接给Telegram Bot发一句语音，让它在指定目录里开一个任务，回电脑前再看diff和测试结果。

⚠️ 远程Bot场景务必注意权限控制：ALLOWED_DIR尽量收窄到具体项目目录，不要直接给整个home目录。

七、注意事项与常见问题

为什么不推荐本地模型跑复杂任务？
Claude Code对上下文、工具调用、代码推理能力要求不低。本地部署的轻量模型很难达到满血状态，一般配置的话，建议直接用现成的云端API更靠谱。真要在本地跑，也要选足够大的模型，并注意上下文长度的配置。

Provider不稳定的问题
代理层越多，变量越多。不同Provider的限流、模型兼容、工具调用格式、流式输出都可能成为问题。用之前最好先在小范围测一下。

Python版本要求
项目要求Python ≥3.14.0，注意检查版本兼容性。

关于“免费”的冷思考
市面上不少“免费使用Claude Code”的教程容易让人产生误解。Free Claude Code解决的核心问题是模型选择，而不是从Anthropic白嫖算力。本地Ollama方案确实可以做到零API成本，但Agent能力取决于模型本身。建议把预期拉平：它让你可以低成本试验不同的模型组合，但不要指望免费方案能达到官方Opus级别的代码推理水平。

安全提示

• 安装脚本直接从GitHub拉取执行，养成先看后跑的习惯
• 远程Bot和API Key放在一起，权限要收住
• 目前项目在GitHub上还没有正式Release版本，属于快速迭代的开发者工具，不建议在生产环境的关键流程中直接依赖

八、适合谁用

第一类：Claude Code重度用户
已经习惯Claude Code的交互，想把一部分低风险任务切到便宜模型或免费额度上——解释代码、补单测、生成README、跑小修小补，切到便宜模型完全够用。

第二类：喜欢折腾多模型路由的技术爱好者
同一个Claude Code前端，后面接不同Provider。Opus类请求走一个模型，Sonnet类请求走另一个，普通fallback再走更便宜的模型，按任务成本做拆分。

第三类：想在本地模型上试Agent工作流的人
Ollama、LM Studio、llama.cpp都支持。虽然效果要看模型和上下文长度，但至少给了一个低成本试验入口。

不太适合谁？
如果你只想要官方Claude Code原汁原味的稳定体验，就没必要折腾这个。代理层越多，变量越多——Provider的限流、模型兼容、工具调用格式、流式输出，都可能成为问题。

总结

Free Claude Code真正戳人的地方不是名字里的“free”，而是它抓住了一个很实际的需求：大家喜欢Claude Code的开发体验，但不想所有任务都被绑定在同一个模型和同一套计费上。它把Claude Code变成一个更开放的前端，后面接免费额度、接便宜模型、接本地模型，都可以自己选。

当然，别把它想成魔法。模型能力不够，Agent该犯错还是会犯错；Provider不稳定，任务该中断还是会中断；本地模型上下文不够，读大项目照样吃力。

但如果你本来就在用Claude Code，又想试试多模型路由、降低一部分成本，或者把本地模型塞进Agent工作流里，这个项目值得翻一翻。