free-claude-code
Alishahryar1/free-claude-code加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象这样一个场景：你刚看完一篇用 Claude Code 做项目的教程，心潮澎湃地打开终端，准备大干一场——然后被提示需要订阅付费计划，每个月至少 25 美元。对于学生党、独立开发者，或是只是想体验一把的爱好者来说，这笔钱说多不多，但说少也不少。
Free Claude Code 正是为解决这个问题而生。它本质上是一个本地反向代理，运行在你自己的机器上，将 Claude Code 和 Codex 客户端原本发往 Anthropic/OpenAI 的流量「劫持」下来，透明地转发到你配置的其他 AI 提供商。由于 Claude Code 和 Codex 采用的是标准协议（Anthropic Messages API、OpenAI Responses API），这个转发过程对客户端完全透明——你不需要修改任何配置，就能用上免费或便宜的模型。
这就是该项目的核心价值主张：打破 AI 编程工具的付费壁垒，让更多人以零成本使用 Claude Code 级别的编程辅助工具。
图1：Codex CLI 通过 Free Claude Code 代理连接本地 Ollama/LM Studio 提供商，运行效果与官方服务无异。
Free Claude Code 由独立开发者 Ali Shahryar 创建和维护，GitHub 账号为 Alishahryar1。截至 2026 年 6 月，该项目已获得超过 35,000 颗星，在 GitHub trending 上多次登顶，成为 AI 编程辅助工具领域的现象级开源项目。
Ali 的初衷非常直接：Anthropic 的 Claude Code 订阅价格对于全球大量开发者来说过于昂贵，尤其在发展中国家的开发者群体中，能够负担每月 25 美元以上订阅费的用户只占少数。但 Claude Code 本身的产品力——代码补全、Bash 工具调用、文件系统操作、代码库问答——是极具生产力的。Ali 通过分析 Claude Code 的协议发现：Claude Code 客户端本身并不验证订阅状态，真正验证的是 Anthropic 的 API 端点。因此，只要在本地搭建一个「协议兼容的代理」，就能让 Claude Code 客户端连接任何符合规范的 AI 模型。
这个思路看似简单，实现起来却极具技术挑战。Claude Code 客户端使用了复杂的 SSE（Server-Sent Events）流式协议、内置的 thinking/reasoning 块处理、工具调用 schema 转换等高级特性。Free Claude Code 必须完整还原这些行为，才能保证客户端正常工作。
从时间线来看，项目在 2025 年中期快速增长，2025 年底至 2026 年初随着 Claude Code VS Code 扩展和 Codex CLI 的发布迎来爆发式增长，目前是 Claude Code 相关生态中最活跃的开源项目之一。
如果只是换个 endpoint，那用 Nginx 反向代理就够了。Free Claude Code 的深度在于它完整实现了 Claude Code 客户端所依赖的所有协议细节。
项目同时支持两条流量路径：
路径一：Anthropic Messages API（Claude Code 客户端）
Claude Code 发出的请求格式是 Anthropic 的原生 /v1/messages 接口，包含 thinking 块、工具调用 schema、streaming SSE 等。项目中的 core/anthropic/ 模块负责解析这些请求，再通过 providers/anthropic_messages.py 中的通用传输层，将请求适配到不同的提供商。
路径二：OpenAI Responses API（Codex 客户端）
Codex CLI 和 VS Code 扩展使用的是 OpenAI 的 Responses API（与 Chat Completions 不同，是较新的接口）。core/openai_responses/conversion.py 负责将 Responses 格式转换为 Anthropic 兼容的 payload，这样就能复用同一套提供商路由逻辑。
项目内置支持 17 种不同的 AI 提供商，基本覆盖了主流的免费/低成本选项：
| 提供商 | 协议类型 | 免费额度 |
|---|---|---|
| NVIDIA NIM | Anthropic Messages | 每日免费额度 |
| OpenRouter | Anthropic Messages | 多种免费模型 |
| Google AI Studio (Gemini) | OpenAI Chat | 免费 tier |
| DeepSeek | Anthropic Messages | 免费 |
| Mistral La Plateforme | OpenAI Chat | 免费 |
| Groq | OpenAI Chat | 免费高速 |
| Fireworks AI | Anthropic Messages | 免费 |
| Cerebras | OpenAI Chat | 免费 |
| Z.ai | Anthropic Messages | 免费 |
| Kimi (Moonshot) | Anthropic Messages | 免费 |
| Ollama | OpenAI Chat | 完全本地免费 |
| LM Studio | OpenAI Chat | 完全本地免费 |
| llama.cpp | OpenAI Chat | 完全本地免费 |
| OpenCode | Anthropic Messages | 免费 |
| Wafer | Anthropic Messages | 免费 |
| Codestral | OpenAI Chat | 免费 |
| Cerebras | OpenAI Chat | 免费 |
提供商通过 providers/ 目录下的独立模块实现，每个模块遵循 BaseProvider 抽象接口（定义在 providers/base.py），包含 chat() 和 stream() 两个核心方法，返回类型均为异步迭代器（AsyncIterator）。这种设计使得添加新提供商非常标准化：只需实现接口、配置 base_url 和认证方式即可。
Free Claude Code 不只是「把所有请求发到一个 API」，它支持按模型名路由。你可以在配置中指定：Claude Opus 发往 NVIDIA NIM、Claude Sonnet 发往 DeepSeek、Claude Haiku 发往 Groq。api/model_router.py 实现了这个路由逻辑，基于配置的模型映射表解析客户端请求中的 model 字段，动态选择上游提供商。
图2：Claude Code 原生 /model 选择器可直接看到 FCC 网关配置的模型列表，实现无缝体验。
图3：Codex CLI 通过 fcc-codex 启动脚本加载动态生成的本地模型目录，模型选择器与官方体验一致。
Claude Code 的核心能力之一是工具调用（Bash 命令执行、文件读写、搜索等）。Free Claude Code 必须正确处理工具调用的 SSE 事件流，包括：
message_start、content_block_start、content_block_delta 等 SSE 事件的正确排序thinking 块（reasoning）的透传或转换（OpenAI 兼容提供商不支持原生 thinking 时）core/anthropic/stream_recovery.py 实现了流恢复机制，当上游连接意外中断时，通过记录已发送的 token 位置，实现无缝续传。这个功能在连接不稳定的网络环境下尤为重要。
项目的架构文档（ARCHITECTURE.md，约 27KB）非常详尽，展示了作者的架构设计能力。整体采用分层架构，每层职责明确：
Claude Code / Codex 客户端
↓
FastAPI HTTP 代理层 (api/)
↓
ClaudeProxyService (服务编排层)
↓
ModelRouter (模型路由层)
↓
ProviderRegistry (提供商工厂层)
↓
具体 Provider 实现 (providers/*/)
↓
上游 AI 提供商 API
api/ 层：FastAPI 应用，处理所有 HTTP 端点，包括 Anthropic Messages 接口、OpenAI Responses 接口、health check、model listing、admin API 等。Admin UI 的静态文件也通过 api/admin_static/ 目录直接服务。
core/ 层：核心协议转换逻辑，anthropic/ 子目录处理 Anthropic 协议细节（消息格式转换、token 计数、thinking 块处理、SSE 策略等），openai_responses/ 处理 OpenAI Responses 到 Anthropic 的格式转换，rate_limit.py 实现全局速率限制。
providers/ 层：17 种提供商的具体实现，每种提供商独立子目录，包含请求构造、错误处理、速率限制等。registry.py 是工厂模块，根据配置动态实例化对应的 Provider。
cli/ 层：命令行启动器，fcc-claude 和 fcc-codex 分别封装了 Claude Code 和 Codex 的启动逻辑，自动读取 Admin UI 的端口和认证 token，配置环境变量后启动对应客户端。
messaging/ 层：可选的消息桥接模块，支持 Discord 和 Telegram。当用户不方便 SSH 连接到运行代理的机器时，可以通过消息平台远程向 Claude Code 发送指令。这对于在服务器上部署 Free Claude Code 的用户非常有用。
smoke/ 层：端到端测试套件，使用 pytest 和 VCR（HTTP 录制回放）确保各提供商的行为符合预期。smoke 测试按 tier 分组（T1/T2/T3），T1 是核心功能，必须全部通过。
图4：本地 Admin UI 界面，可管理所有提供商配置、查看连接状态、验证 API key 有效性。
图5：Admin UI 中的消息桥接配置面板，支持 Discord 和 Telegram 远程控制。
项目使用 Python 3.14（最新版本），这是一个相当激进的选择——Python 3.14 在 2025 年中期发布，项目紧跟上游。这个版本带来了 except X, Y 语法回归（Python 3.14 final 版本中恢复），README 中特别提到了这一点。
关键依赖：
项目的代码质量保障体系相当完善：
ty 工具（由 astral-sh 开发， Ruff 作者的新项目）进行严格类型检查tests/contracts/ 来验证各层之间的接口契约，防止重构破坏从测试文件数量来看（tests/ 下超过 80 个测试文件），测试覆盖密度非常高，远超大多数同规模开源项目。
项目为开发者提供了清晰的扩展路径：
添加新提供商：只需继承 BaseProvider，实现 chat() 和 stream() 方法，在 providers/registry.py 中注册工厂，在 config/provider_catalog.py 中添加元数据即可。
添加新消息平台：在 messaging/platforms/ 下实现 MessagingPlatform 接口，注册到工厂即可。
处理新的请求/响应格式：Codex 可能会引入新的 Responses API 字段，core/openai_responses/conversion.py 提供了扩展点。
项目提供跨平台安装脚本：
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | shirm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex安装脚本自动完成：
uv 包管理器（>= 0.11.0）uv python install）安装过程完全自动化，对于技术用户来说体验非常顺滑。
安装完成后，通过 fcc-init 或 Admin UI（/admin）配置 API key。Admin UI 支持验证 API key 有效性（直接向上游发测试请求），避免配置了无效 key 后才发现问题。
配置文件位于 ~/.fcc/.env，格式参考 .env.example。配置项包括：
fcc-server 或 free-claude-code：启动代理服务fcc-claude：启动 Claude Code，配置好代理环境变量，自动指向本地代理fcc-codex：启动 Codex CLI，生成动态模型目录代理默认监听本地端口（loopback），保证安全性——除非主动暴露端口，否则外部网络无法访问你的代理。
需要明确指出的是：该项目不提供 Docker 镜像。项目 README 明确声明「不接受 Docker 集成 PR」。这意味着：
对于希望在服务器上运行的用户，messaging bridge（Discord/Telegram）提供了远程交互能力，可以绕过这个限制——服务器上只运行代理 + messaging bridge，本地通过消息平台操控。
Free Claude Code 解决的是「如何免费使用 Claude Code 客户端」的问题，但免费模型的输出质量与 Claude Opus/Sonnet 有本质差距。DeepSeek、Groq 等免费层提供的模型在复杂代码推理、长上下文理解、多文件协同等方面，远不及 Claude 的旗舰模型。用 DeepSeek 替代 Claude Opus 写一个复杂项目，体验差距会非常明显。
这也是项目文档坦诚指出的：它适合想要体验 Claude Code 工作流的用户，以及预算有限的开发者，但不承诺免费方案能达到付费方案的产出质量。
Claude Code 客户端和 Codex 的协议并非公开稳定接口，Anthropic 和 OpenAI 可能随时引入破坏性变更。项目需要持续跟进这些变更，smoke 测试的录制回放机制缓解了这个问题，但无法完全消除上游变更带来的维护压力。
README 明确说明「不接受 README 变更 PR，只接受 Issue」，作者的维护策略是围绕 Issue 驱动。这种方式在项目规模快速扩张时可能面临响应速度的挑战。
作为一个单人或小团队维护的项目（从仓库活动看，主要贡献者不超过 5 人），Free Claude Code 的长期可持续性存疑。项目在 2026 年初经历了快速迭代，但随着 Claude Code 本身的版本更新，维护成本可能上升。同时，Anthropic 也在持续增加 Claude Code 的付费专属功能（如高级工具集、深度集成），这些功能可能无法被免费代理完全模拟。
Free Claude Code 的 35,000 颗星和 5,000+ fork 证明了市场需求的真实存在。它代表了一种开源社区对抗「软件订阅化」趋势的方式——当工具变得封闭和昂贵时，开源社区会寻找并实现替代路径。这与 LibreOffice 之于 Office 365、Nextcloud 之于 Google Drive 的逻辑一脉相承。
项目对 Ollama、LM Studio、llama.cpp 的原生支持，反映了一个更大的趋势：本地 AI 模型正在快速追赶闭源模型。DeepSeek-R1、Qwen2.5-Coder 等开源模型的能力已经足以支撑日常编程任务，让「本地免费使用 Claude Code 级别工具」成为现实。项目为这个趋势提供了产品化的入口。
35K stars 的项目已经形成了生态：社区 fork 出了针对特定提供商的定制版、各种配置指南、以及集成到其他工具链的插件。随着 AI 编程工具市场的持续增长，Free Claude Code 有可能成为「AI 编程代理层」的事实标准。
如果 Anthropic 官方推出了免费版 Claude Code（类似于 GitHub Copilot 的免费 tier），Free Claude Code 的核心价值主张会弱化，但这反而可能推动项目转向「统一多种 AI 编程工具的体验层」——不管底层是 Claude Code、Codex 还是未来的其他竞品，用户都能通过统一的本地代理层管理所有流量。
Free Claude Code 是一个极具工程价值的开源项目，它用精巧的协议兼容性设计，打通了 Claude Code/Codex 客户端与多种 AI 提供商之间的壁垒。对于预算有限的开发者、本地模型爱好者、以及希望深入理解 AI 协议栈的工程师来说，它是当前最值得关注的项目之一。
然而，它并非银弹：免费模型的能力上限是真实的限制，协议维护的持续成本不可忽视，项目本身的可持续性也存在不确定性。如果你只是想找一种方式免费用 Claude Code 的体验层，它可以完美满足需求；如果你期待的是用免费模型达到 Claude Opus 的产出质量，这个期望需要调整。
无论如何，35,000 颗星已经说明：无数开发者愿意通过自己的方式，「绕过」AI 编程工具的付费墙——而 Free Claude Code 是目前最优雅的那把钥匙。