深入解析 Free Claude Code：本地代理聚合 50 个免费 Provider

📘 项目信息

名称：Free Claude Code (FCC)

作者：Alishahryar1

License：MIT

仓库：https://github.com/Alishahryar1/free-claude-code ↗

协议层：Anthropic Messages API + OpenAI Responses API

语言：Python 3.14 + FastAPI

核心承诺：50 个 ToS 友好的 Provider、每月 1.3B+ 免费 token、9 款 coding agent 全兼容

一、为什么这个项目值得研究？#

Claude Code、Codex、Pi、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build、Muse Code —— 这些 CLI/IDE 形态的 coding agent 这两年大爆发，但绝大多数都默认绑定：

Anthropic API（按 token 烧钱），
或者各家自己的付费订阅（OAuth 锁死，换模型困难）。

Alishahryar1 的 free-claude-code（下文简称 FCC）走了一条完全不同的路：它不碰上游 SDK，而是在你本机起一个 FastAPI 反向代理，把任何兼容 Anthropic Messages 或 OpenAI Responses 协议的 coding agent 请求，透明地翻译并转发到 50 个第三方 Provider，而 Provider 那边用的是这些厂商对外的 免费档 或 注册就送的试用额度。

关键承诺（来自 README 顶部）： 50 ToS-friendly providers. 1.3B+ free tokens every month.

也就是说：你不需要订阅 Claude Pro，只要：

拿 1 个免费的 NVIDIA NIM key（注册送），或
用 OpenRouter 的 openrouter/free 系列，或
用 GitHub Models（已有 GitHub 账号就有），或
本地起 Ollama / LMStudio 跑 Qwen3-Coder / DeepSeek-Coder

就可以让 claude / codex / cline 跑得欢。本机即用、数据不出本机、限速时自动 fallback。

下面我把它的架构、协议转换、Provider 抽象、Fallback 机制、注册白嫖路径逐节拆解。

二、整体架构：一个本地代理的”全貌”#

FCC 自己维护的 ARCHITECTURE.md 给出了一张很干净的依赖图。我把它翻译一下：

┌────────────────────────┐
│ 9 款 Coding Agent       │  ← Claude Code / Codex / Pi / OpenCode / Cline /
│ (Claude Code / Codex / │     Hermes / DSH / Grok / Muse
│  Pi / OpenCode / Cline) │
└──────────┬─────────────┘
           │ HTTP（SSE 流式）
           ▼
┌──────────────────────────────────────────────┐
│ FCC 本地 FastAPI 代理 (fcc-server, :8082)    │
│  ┌──────────────┐  ┌────────────────────┐    │
│  │ Messages     │  │ Responses          │    │
│  │ Handler      │  │ Handler            │    │
│  └──────┬───────┘  └─────────┬──────────┘    │
│         └────────┬───────────┘                │
│                  ▼                            │
│       application.ModelRouter                 │
│       application.ProviderExecutor            │
│                  │                            │
│                  ▼                            │
│   Provider Generation Lease → ProviderRuntime │
└──────────┬───────────────────────────────────┘
           ▼
  50 个 Upstream Provider（OpenAI Chat / Responses / Native SDK）

plaintext

按 ARCHITECTURE.md 的依赖约束，整个仓库是严格的分层六边形架构：

包	角色	允许依赖
`core/`	协议中立的核心逻辑（Anthropic / OpenAI Responses 模型、SSE 拼装、失败语义、token 计数）	无
`config/`	设置、Provider 元数据、文件路径、日志	无
`application/`	路由、Provider 执行、模型元数据	`config`、`core`
`messaging/`	Discord / Telegram 适配、语音转写	`core`
`providers/`	Provider 构造、OpenAI Chat 共享、SSE 恢复、限流、模型列表、特殊 Provider	`application`、`config`、`core`
`api/`	FastAPI 路由、Admin UI、HTTP 错误映射	`application`、`config`、`core`
`cli/`	CLI launcher、托管会话	`config`、`core`
`runtime/`	启动/关闭、Provider 生命周期、组合根	上面所有

这条约束带来一个非常重要的副作用：core 没有任何外部依赖，意味着协议转换完全可单测、可复用，并且 Provider 模块不能反向依赖 API 层，架构不会”螺旋腐烂”。

三、协议转换：Anthropic Messages ↔ OpenAI Chat / OpenAI Responses#

FCC 的杀手锏是不重新实现一遍 Claude Code 的 SDK，而是 假装自己是 Anthropic 兼容端点。

3.1 客户端侧：让 Claude Code 以为自己还在连 Anthropic#

在 Claude Code 的 VS Code 插件里，加上这么一段环境变量（README 里的官方示例）：

{
  "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" },
    { "name": "DISABLE_AUTOUPDATER", "value": "1" }
  ]
}

json

Claude Code 启动时，会把请求发给 http://localhost:8082/v1/messages，附上 Authorization: Bearer freecc。FCC 拿到后：

在 api/handlers/messages.py 里解析成 core.anthropic.MessagesRequest；
application.ModelRouter 根据当前 MODEL / MODEL_OPUS / MODEL_SONNET / MODEL_HAIKU 选 model slug；
application.ProviderExecutor 拿 application.ProviderResolver 解析到一个 BaseProvider；
把请求通过 provider 适配层转成上游格式（OpenAI Chat / OpenAI Responses / Gemini / Mistral / Bedrock / Vertex …）；
SSE 流回，再由 core.anthropic.aggregate_anthropic_sse_to_message 拼回 Anthropic SSE 协议，原封不动喂给 Claude Code。

整个过程对 Claude Code 是透明的 —— 它以为自己还在用 Anthropic 后端，但实际底层跑的是 Qwen3-Coder / DeepSeek-V4-Flash / GLM-5.2 / Kimi-K3 之一。

3.2 Provider 抽象层：50 个 Provider 只写一份”协议差异表”#

src/free_claude_code/providers/base.py 里定义了基类：

class BaseProvider(ABC):
    @abstractmethod
    def preflight_stream(self, request, *, reasoning=DEFAULT_REASONING_POLICY): ...
    @abstractmethod
    async def cleanup(self): ...
    @abstractmethod
    async def list_model_infos(self) -> frozenset[ProviderModelInfo]: ...
    @abstractmethod
    def stream_response(
        self, request, input_tokens=0, *,
        request_id=None, response_model=None,
        reasoning=DEFAULT_REASONING_POLICY,
    ) -> AsyncIterator[str]: ...

python

每个 Provider 只需要实现 4 个方法：

preflight_stream：在开 SSE 流之前，校验请求是否合法（比如某些 Provider 不支持 tool_use、system 长度有限制）。
list_model_infos：去上游拉一次 /models，回传可用模型清单（决定 Admin UI 下拉菜单）。
stream_response：把 MessagesRequest → 上游 chat/responses 协议 → 上游 SSE → 重新格式化成 Anthropic SSE → yield 出去。
cleanup：释放连接池。

最巧妙的是 OpenAI Chat 共享 Profile：因为 OpenRouter / Groq / Together / DeepInfra / SiliconFlow / Cerebras / SambaNova / Novita / Fireworks / HuggingFace / Cohere / OpenCode / Ollama Cloud … 大部分都提供 OpenAI Chat 兼容端点，FCC 写了一份 providers/openai_chat/ 共享实现，只换 base_url + API key + 模型 ID 前缀，就把 30 多个 Provider 拿下了。剩余的是 OpenAI Responses 直连、Gemini 私有协议、Vertex、Bedrock、Claude 官方等少数需要单独适配的。

这就是为什么 50 个 Provider 能塞进一个 274 个 Python 文件的项目里 —— 真正的”硬编码” Provider 只有 10 个左右，其余全是配置驱动。

3.3 失败恢复：SSE 重连 + Fallback Model 自动接力#

FCC 还有两个非常”工程化”的亮点：

a. `stream_recovery.py`：SSE 中途断流不丢响应#

上游免费档经常在长流中途 503/429/连接重置。普通代理会直接断。FCC 在 provider 层捕获 可恢复的 transport 错误 后，用本地缓存的 token 续传 chunk，让客户端看不出断流。

b. `application.routing.ModelRouter`：Fallback Models 列表#

Admin UI 里可以配置 MODEL_FABLE / MODEL_OPUS / MODEL_SONNET / MODEL_HAIKU / Fallback Models。当首选 Provider 报失败时，自动切下一个 Provider 重新发起同一个请求，客户端不感知。

README 里的关键描述：

Keep coding through provider outages. After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.

这就是为什么”免费档”虽然单个 Provider 经常超限，但组合起来近乎无限 —— 你可以同时挂 5 个免费 key，一个挂了立刻接力。

四、Token 优化：5 个本地微优化省下 90% 终端 token#

FCC 的设计哲学里有一条非常实用：不是所有 token 都该让 Provider 算钱（哪怕免费）。

优化	做什么	受益
Quota Probes	启动前只发 `/models` 不发消息，验证 key	不消耗配额
Command-Prefix Detection	识别 `git status`、`npm test` 这类确定性命令，本地直接返回	0 token
Title / Suggestion 生成	标题与候选建议本地拼	0 token
Filepath 解析	文件路径引用本地化	极小 token
RTK（可选）	过滤 `npm install` / `cargo build` 等长输出	最多省 90% 终端输出 token

第 5 个是可选依赖 rtk-ai/rtk，装上之后类似 Rtk 的压缩器。前 4 个是 FCC 默认开启，加起来能省掉不少”无效 round-trip”。

五、客户端适配：9 款 coding agent 一份代理全包#

通过 CLI launcher 的方式，FCC 把 9 款 agent 都接了进来：

fcc-claude     # Claude Code
fcc-codex      # OpenAI Codex CLI / App
fcc-pi         # Pi Coding Agent
fcc-opencode   # OpenCode
fcc-cline      # Cline
fcc-hermes     # Nous Hermes Agent
fcc-dsh        # DeepSeek Harness Web
fcc-grok       # Grok Build (xAI)
fcc-muse       # Meta Muse Code

bash

每个 launcher（src/free_claude_code/cli/launchers/*.py）的作用是：用环境变量把客户端指向 FCC 端口 + freecc 假 token，然后原样 exec 客户端二进制。Launcher 不做协议转换 —— 转换都在 FCC server 这边。

所以即便你原来已经装了 Claude Code，装完 FCC 之后：

claude 走 Anthropic 官方（付费）
fcc-claude 走 FCC 代理（免费）

两者并存，你随时切换。

六、可选集成：Discord / Telegram / 语音输入#

FCC 把”编程 agent 接入日常聊天”做得也很完整（虽然跟”免费”主线没强相关，值得单独说一下）：

Discord / Telegram Bot：把群消息映射成托管的 Claude CLI session，长任务用 tree queue 排队。
语音输入：本地 Whisper（openai/whisper）或 NVIDIA NIM Riva ASR 都可以，转写完直接发给 coding agent。
Web Tools：内置 web_search / web_fetch，不过有 egress 白名单，避免被滥用成代理出口。

这三块都是可选的，安装命令分别带 --voice-local / --voice-nim / --voice-all 开关。

七、重点：如何真的”免费”用起来？#

下面给出实战路径，全部来自 README 的 Provider 目录和 .env.example。

7.1 最推荐的”零成本 + 高质量”组合#

Provider	怎么拿 key	免费额度	推荐模型
NVIDIA NIM	https://build.nvidia.com/settings/api-keys ↗ 注册就有	Nemotron-3-Super-120B 等几十款，注册送额度	`nvidia_nim/nvidia/nemotron-3-super-120b-a12b`
OpenRouter	https://openrouter.ai/keys ↗ 注册	`:free` 后缀模型无限免费	`open_router/openrouter/free`
ZenMux	https://zenmux.ai/platform/pay-as-you-go ↗ 注册	部分模型免费	`zenmux/deepseek/deepseek-v4-flash-free`
Kilo.ai	https://kilo.ai ↗ 注册	`kilo-auto/free`	`kilo/kilo-auto/free`
TokenRouter	https://www.tokenrouter.com/ ↗ 注册	Kimi-K3-Free	`tokenrouter/moonshotai/kimi-k3-free`
NaraRoute	https://router.bynara.id/ ↗ 注册	Kimi-K3-Free	`nararoute/kimi-k3-free`
GitHub Models	https://github.com/marketplace?type=models ↗	有 GitHub 账号就有，限速	`github_models/openai/gpt-4.1`
OpenCode Zen/Go	https://opencode.ai/auth ↗	注册送	`opencode_zen/gpt-5.3-codex`、`opencode_go/minimax-m2.7`
Mistral	https://console.mistral.ai/ ↗	注册送试用	`mistral/devstral-small-latest`
DeepSeek	https://platform.deepseek.com/api_keys ↗	注册送少量试用金	`deepseek/deepseek-chat`

⚠️ 关键原则（README 里 FCC 自己强调的）：Free-tier 限额由各家 Provider 控制，会变。FCC 承诺”一旦某 Provider 改了 ToS 不让这么用，会主动把该集成下架”。所以这套玩法长期来看是”动态清单”，不是”一劳永逸”。

7.2 完全离线、零网络方案：本地模型#

如果你不想填任何 key：

本地 Provider	怎么用
Ollama	`ollama serve`，FCC 走 `ollama/<model-tag>`
LM Studio	启动 LM Studio 的本地 server，FCC 用 `LM_STUDIO_BASE_URL`
llama.cpp	启 server，FCC 用 `LLAMACPP_BASE_URL`

推荐模型（工具调用能力 + 代码能力强 + 显存友好）：

qwen3-coder:480b（多卡）
qwen3-coder:30b（24GB 显存）
deepseek-coder-v2:16b（消费级显卡）
qwen2.5-coder:7b（笔记本）

7.3 实战配置（`.env`）#

把 README 里给的 .env.example 简化成”零成本起步版”：

# 主模型：NIM Nemotron-3-Super 120B（注册送）
MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
NVIDIA_NIM_API_KEY=nvapi-xxxxxx

# Fallback：OpenRouter 免费档
# 留空表示不启用，去 Admin UI 里加也行
OPENROUTER_API_KEY=sk-or-xxxxxx

# 再加一层：GitHub Models（多数开发者都有）
GITHUB_MODELS_TOKEN=ghp_xxxxxx

# Fallback 列表（Admin UI 里配置更直观）：
# 1. nvidia_nim/nvidia/nemotron-3-super-120b-a12b
# 2. open_router/openrouter/free
# 3. github_models/openai/gpt-4.1
# 4. zenmux/deepseek/deepseek-v4-flash-free
# 5. ollama/qwen2.5-coder:7b  ← 完全离线兜底

# 本地代理鉴权
PROXY_API_KEY=freecc
PROXY_PORT=8082

bash

7.4 启动 + 接入 Claude Code#

# 一键安装（macOS / Linux）
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh

# 启动 FCC server
fcc-server
# → 浏览器自动打开 Admin UI，默认 http://localhost:8082

# 启动 Claude Code（走 FCC）
fcc-claude

# 或 Codex / Cline / Pi / OpenCode ...
fcc-codex
fcc-cline
fcc-pi
fcc-opencode

bash

VS Code 里给 Claude Code 插件配上环境变量（关键 3 行）：

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

json

搞定 —— Claude Code 现在跑的是 NIM 的 Nemotron，你不用付 Anthropic 一分钱。

7.5 限额用尽时的”无缝接力”#

FCC README 强调的关键能力：

After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.

意思是：NIM 限速了 → 自动切 OpenRouter Free → OpenRouter 限速了 → 自动切 GitHub Models → 全网限速了 → 自动切本地 Ollama。整个过程你在 Claude Code 端看不到任何 error，turn 不会断。

这套 Fallback 机制是”免费档可用性”的真正护城河 —— 单个 Provider 的免费额度可能只够写 50 个文件，但 5 个串起来就能写一整天。

八、FCC 的工程化设计可以学到什么？#

抛开”免费 token”这个诱人的卖点，FCC 在工程上有几条值得借鉴：

8.1 协议中立的 `core` 包#

core/anthropic、core/openai_responses 是协议模型层，不依赖任何 Provider SDK。这意味着：

上游换 SDK 不会污染协议层；
Provider 层只需要”翻译”，不需要重新实现 SSE；
单测可以无网络跑完整个请求 / 响应生命周期。

8.2 OpenAI Chat 共享 Profile + 工厂同步#

providers/openai_chat/ 把”所有兼容 OpenAI Chat 的 Provider”做成一个共享实现 + 注入 base_url / api_key / 模型前缀。新增 Provider 经常只是 3 行注册代码 + Admin UI 加个图标。

8.3 Fallback 不是”运维特性”，而是”一等公民”#

application/routing.py 里的 ModelRouter 把 Fallback 提到路由层，而不是 Provider 层。这意味着：

Fallback 跨”协议族”（从 Anthropic 兼容的 OpenAI 切到 Gemini）；
Fallback 跨”地理位置”（从 NIM 切到 OpenRouter）；
Fallback 跨”在线/离线”（最后兜底本地 Ollama）。

这种设计把”可用性”和”成本”解耦了。

8.4 失败分类标准：可恢复 vs 不可恢复#

core/failures.py 里把异常分成 ExecutionFailure（可恢复，自动重试/Fallback）和普通异常（直接报错）。不让 Provider 决定重试策略，让上层统一调度。

8.5 协议保真度高于 SDK 兼容性#

README 里 FCC 反复强调”原样保流 Anthropic SSE”，包括：

流式 chunk 顺序；
interleaved_thinking 块；
tool_use 增量；
错误码映射（anthropic_status_for_error_type）。

这是它能让 Claude Code / Codex / Pi 全部”无感切换”的原因。

九、潜在的坑与限制#

9.1 不是所有模型都”完全替代 Claude”#

免费档的模型（Nemotron-3-Super-120B / Qwen3-Coder / DeepSeek-V4-Flash / GLM-5.2 / Kimi-K3）在通用编码任务上接近 Claude Sonnet，但在：

极长上下文（>200k tokens）保真度
复杂工具调用编排（多层 agent）
复杂代码重构推理

仍有差距。建议把 Claude Code 当 UI，但把重负载任务路由到 NIM / OpenRouter Free 上 —— 真遇到关键决策再切到 Anthropic 官方。

9.2 ToS 风险#

每个 Provider 的免费档都有”禁止批量调用""禁止用作产品后端”之类的条款。FCC 自己在 README 顶部写了：

Independent open-source project. Not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic.

并且承诺会”主动下架违反 ToS 的 Provider”。用户自己也要心里有数 —— 这是个人玩具 / 学习项目，不是企业生产环境。

9.3 不替代真正的 Claude Max/Pro#

FCC 是协议代理，不是 Claude 官方功能的复刻。比如：

Claude Code 的”项目记忆”（.claude/projects/）功能依赖 Anthropic 端的部分存储，FCC 不会复刻；
官方 skills marketplace、官方 MCP server 列表也都不在 FCC 范围内。

所以 FCC 是 “用 Claude Code 的 UX，跑别人家的模型”，不是 “白嫖 Claude Max”。

9.4 Python 3.14 + uv 安装#

pyproject.toml 锁了 Python 3.14.0，uv.lock 是单点真相。建议直接装 uv 然后 uv tool install free-claude-code —— 不要用 pip 装，否则 torch / librosa 这类可选依赖可能编译失败。

十、总结：FCC 的真正价值#

维度	评价
节省成本	⭐⭐⭐⭐⭐：每月 1.3B+ 免费 token，单用 NIM 就够日均 coding
上手成本	⭐⭐⭐⭐：5 分钟 curl 安装 + 填 1 个 key 就能跑
模型质量	⭐⭐⭐⭐：免费档 70%-90% Claude Sonnet 水平
稳定性	⭐⭐⭐⭐⭐：Fallback 跨 5 个 Provider 自动接力
隐私	⭐⭐⭐⭐：本机代理，密钥 + 代码不出本机
生产可用	⭐⭐⭐：个人开发 / 学习 OK，企业慎用

如果你是：

学生 / 个人开发者：闭眼上 FCC，把省下的 Claude Pro 订阅费拿去吃顿好的；
AI 重度用户：FCC + Claude Max 双轨，平时 FCC，关键任务切官方；
架构爱好者：读一遍 ARCHITECTURE.md + core/anthropic/，看一个”协议中立 + 严格分层”的优秀 Python 工程长什么样；
企业：先咨询法务（ToS），再决定是否接入。

💡 小吴笔记：FCC 这种”协议代理 + Provider 聚合 + 本地 Fallback”的模式，未来很可能是”AI 工程师桌面”的标配 —— 类似早年 Postman 之于 API、Charles 之于 HTTP。不绑定单一上游，是个人开发者抵抗供应商锁定的最实用姿势。

🦞

一、为什么这个项目值得研究？#

二、整体架构：一个本地代理的”全貌”#

三、协议转换：Anthropic Messages ↔ OpenAI Chat / OpenAI Responses#

3.1 客户端侧：让 Claude Code 以为自己还在连 Anthropic#

3.2 Provider 抽象层：50 个 Provider 只写一份”协议差异表”#

3.3 失败恢复：SSE 重连 + Fallback Model 自动接力#

a. stream_recovery.py：SSE 中途断流不丢响应#

b. application.routing.ModelRouter：Fallback Models 列表#

四、Token 优化：5 个本地微优化省下 90% 终端 token#

五、客户端适配：9 款 coding agent 一份代理全包#

六、可选集成：Discord / Telegram / 语音输入#

七、重点：如何真的”免费”用起来？#

7.1 最推荐的”零成本 + 高质量”组合#

7.2 完全离线、零网络方案：本地模型#

7.3 实战配置（.env）#

7.4 启动 + 接入 Claude Code#

7.5 限额用尽时的”无缝接力”#

八、FCC 的工程化设计可以学到什么？#

8.1 协议中立的 core 包#

8.2 OpenAI Chat 共享 Profile + 工厂同步#

8.3 Fallback 不是”运维特性”，而是”一等公民”#

8.4 失败分类标准：可恢复 vs 不可恢复#

8.5 协议保真度高于 SDK 兼容性#

九、潜在的坑与限制#

9.1 不是所有模型都”完全替代 Claude”#

9.2 ToS 风险#

9.3 不替代真正的 Claude Max/Pro#

9.4 Python 3.14 + uv 安装#

十、总结：FCC 的真正价值#

a. `stream_recovery.py`：SSE 中途断流不丢响应#

b. `application.routing.ModelRouter`：Fallback Models 列表#

7.3 实战配置（`.env`）#

8.1 协议中立的 `core` 包#