GitHub 上的开源项目 Alishahryar1/free-claude-code 已经积累 4.77 万 star，MIT 协议，由独立开发者维护，与 Anthropic 没有隶属关系（README 明确声明 Claude 和 Claude Code 是 Anthropic 的商标）。它做的事情可以概括为一句话：在本机跑一个代理服务器，把 Claude Code、Codex、OpenCode 等 9 个编码 Agent 的模型请求统一接管，转发给 49 家模型供应商，把其中免费额度聚合成一个统一的模型目录。项目方在 README 中给出的数字是每月 13 亿以上的免费 token。
它解决的是供应商碎片化问题
编码 Agent 这两年野蛮生长，每家都有自己的订阅体系：Claude Code 绑定 Anthropic 订阅，Codex 绑定 ChatGPT 计划，各家国产模型推各自的 Coding Plan。想把 Codex 换成 QwenCloud 的编码套餐，或者让 Claude Code 跑在本地 Ollama 上，都要翻配置文档改环境变量。免费额度更分散：NVIDIA NIM、OpenRouter、Groq、SiliconFlow 各家都给新用户发免费 token，但每家的调用方式、模型 ID、限额规则都不一样，单独接入任何一家都要写一遍胶水代码。
Free Claude Code（下称 FCC）的思路是把这些差异全部收进一个本地代理。编码 Agent 只知道自己在调用一个 Anthropic 或 OpenAI 兼容的端点，实际的模型路由、供应商切换、协议转换全部由 FCC 完成。任何一家供应商断供或限流，FCC 在重试耗尽后自动换下一个配置的模型继续当前回合，不需要重启任务。
双协议代理：Anthropic Messages 与 OpenAI Responses
FCC 的 HTTP 层是 FastAPI + Uvicorn，对外暴露两组核心路由：POST /v1/messages 提供 Anthropic Messages 兼容的流式接口，POST /v1/responses 提供 OpenAI Responses 兼容接口。Claude Code 和 Pi 走前者，Codex、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build、Muse Code 走后者，协议转换在适配器边界完成（Responses 到 Anthropic 的互转）。另有 token 计数端点和 GET /v1/models 模型列表端点，模型列表提供三种视图：claude 视图保留供应商模型和内置 Claude 兼容 ID，messages 视图给 Messages 原生客户端，responses 视图附带传输、重试、reasoning 元数据。
代理默认监听本机 8082 端口。认证靠一个本地 bearer token（ANTHROPIC_AUTH_TOKEN），开启后做常数时间比较，其余凭证头一律忽略，避免残留的供应商 API key 误充当代理凭证。Admin 管理界面和 admin API 只监听 loopback，外部网络无法访问。
九个启动器，客户端零改动接入
FCC 为每个支持的 Agent 提供独立启动器：fcc-claude、fcc-codex、fcc-pi、fcc-opencode、fcc-cline、fcc-hermes、fcc-dsh（DeepSeek Harness）、fcc-grok、fcc-muse。启动器做三件事：剥离继承的官方凭证环境变量（防止旧 key 干扰）、注入 FCC 代理地址和认证 token、保持 Agent 原有的会话、设置、扩展完全不动。对版本有明确要求：Hermes 0.20.4 以上、DeepSeek Harness 0.1.0-rc.8、Grok Build 1.0.5 以上、Muse Code 0.2.1 以上。
IDE 集成走配置文件。VS Code 的 Claude Code 扩展通过 environmentVariables 注入 ANTHROPIC_BASE_URL 指向本地代理；Codex 桌面版在 ~/.codex/config.toml 里加一段 model_provider，认证命令直接调用 fcc-codex --print-proxy-auth-token 读取当前代理 token，wire_api 指定为 responses。Codex 的模型目录通过 ~/.fcc/codex-model-catalog.json 文件注入，FCC 在配置变更后原子写入，相同字节不重写。
49 家供应商，一个模型目录
供应商元数据集中在 provider_catalog.py，每家声明 ID、认证方式、凭据环境变量、默认 base URL 和配置就绪条件。目录覆盖三大类：
| 类别 | 代表供应商 |
|---|---|
| 云端免费/免费档 | NVIDIA NIM（默认，nemotron-3-super-120b-a12b）、OpenRouter、Groq、Together、Nebius、Chutes、Featherless、ZenMux、TokenRouter |
| 订阅制 Coding Plan | Kimi Code、QwenCloud Coding Plan、z.ai Coding Plan、OpenCode Zen/Go、ClinePass |
| 按量付费 API | DeepSeek、MiniMax、Mistral/Codestral、xAI、Cerebras、SambaNova、Fireworks、Novita、Bedrock、Vertex、Azure OpenAI、Cloudflare Workers AI |
| 本地推理 | Ollama、llama.cpp、LM Studio、Ollama Cloud |
配置优先级是 Settings 默认值、托管文件 ~/.fcc/.env、进程环境变量三层叠加，唯一的例外是 ANTHROPIC_AUTH_TOKEN：托管文件里的非空值优先于继承的进程变量，保证服务器和它启动的客户端永远用同一个 token。Admin UI 的每次 Apply 做原子写入，省略的字段保持原值，密钥字段打码显示。
四档模型独立路由与故障切换状态机
Claude Code 的请求按档位命名（Fable、Opus、Sonnet、Haiku）。FCC 的路由层把 MODEL 设为兜底，MODEL_FABLE、MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 可以分别覆盖。例如 Opus 档路由到 NVIDIA NIM 的 Nemotron，Sonnet 档路由到 OpenRouter 免费模型，Haiku 档路由到本地 LM Studio，兜底模型设为 GLM-5.2，四个档位互不干扰。Reasoning 控制同样独立：默认透传客户端的 effort 值，也可以强制关闭或固定在 Low 到 Max 的某一档。
故障切换是一个有限首帧行状态机：只有在当前候选吐出第一个非空协议块之前发生可重试失败，才会切换到下一个配置的目标；首帧已经发出，当前候选即被提交，后续错误按既有终止语义处理，避免同一次生成输出两份内容。认证失败、权限不足、计费问题、上下文溢出这类确定性错误不触发切换。每个候选保留原始请求 ID、公开响应模型名、输入 token 数和 reasoning 策略，上游的私有模型名永远不会作为响应模型暴露给客户端。供应商进度超时默认 600 秒，收到任何非空数据块就续期，空 keepalive 不算。
不打上游的本地优化
有五类低价值请求在 FCC 本地直接短路，根本不发给供应商：额度探测、命令前缀检测、标题生成、建议模式、文件路径提取。终端输出侧可选集成 RTK 过滤常见命令输出，项目方给出的数字是终端输出 token 最多减少 90%。Claude Code 自动模式的安全分类器请求也在本地处理：检测到分类器形态后强制关闭 reasoning，只消费其终止标记，供应商正常完成即返回解析器可读的判定。
安全与隐私边界
FCC 的安全设计集中在四点：Admin 界面仅 loopback 可达；代理认证 token 常数时间比较；本地 web_fetch 出口默认阻断私网地址；日志 50MB 轮转保留 5 份，磁盘占用上限约 300MB，API 原始 payload 默认不记录，结构化 trace 里 key 类字段自动打码。
工程细节值得单独一提的地方
这个项目的架构文档（ARCHITECTURE.md）写得相当认真。包依赖遵循最小权限策略：config 和 core 是零依赖叶子，application 只依赖这两者，runtime 是唯一的组合根，全量依赖关系由 AST 扫描器强制校验，第一方模块图必须无环。供应商运行时采用代际租约（generation lease）设计：每个请求先获取当前供应商代际的租约，Admin 热更新产生新一代配置后，新请求走新代际，进行中的流在旧代际上跑完，最后一个租约释放时恰好关闭一次。关闭顺序也是显式编排的：静默消息入口、排空工作流、刷持久化、关投递、关转录、关供应商、关账户与 HTTP 资源，任何一步失败都保留可重试状态而不是硬砍。CI 包含 ruff 格式与检查、ty 类型检查、pytest，以及用无头 Chromium 加假供应商跑的 Playwright e2e。
适用场景与限制
FCC 适合三类人：在多个编码 Agent 之间切换、想把供应商配置集中管理的人；想聚合各家免费额度、控制编码订阅开销的人；以及想让断供时的自动切换代替手动改配置的人。限制也很清楚：免费额度的可用性和限额完全由各供应商控制，随时可能变动；项目承诺遵循供应商条款，条款收紧时会移除对应集成；它对供应商官方订阅协议没有豁免权，绕过条款式用法不在设计目标内。语音输入（本地 Whisper 或 NVIDIA NIM 转录）和 Discord、Telegram 机器人桥接属于可选集成，安装脚本按需勾选。
安装本身是标准 curl 脚本加 uv 工具链（Python 3.14），卸载只移除 FCC 本体和 ~/.fcc/ 目录，九个 Agent 的安装不受影响。