免费用 Claude - FCC

DanielChen
6 阅读14分钟

Free Claude Code (FCC) 项目

仓库地址：github.com/Alishahryar…

一、项目概览

Free Claude Code（简称 FCC） 是一个本地代理（local proxy），它把 Claude Code、Codex 等终端编码 Agent 发出的 API 请求，转发到你自选的模型供应商（免费额度、订阅、付费 API 或本地模型）上，从而让你不必绑定 Anthropic 官方付费订阅也能使用这些编码 Agent。

项目定位非常明确 —— 它不是 Claude Code 的替代品，也不是破解工具，而是一个协议转换与路由中间层。

维度数值 / 说明
Stars62.8k
Forks9.8k
Open Issues229
Commits1,209
Tags / Branches82 / 2
许可证AGPL-3.0-only（2026-09-24 由原许可证切换而来，PR #1887）
Python 版本强制 ==3.14.7
包管理器uv，要求 >=0.13.4
核心源码规模约 72,500 行 Python，250+ 模块
单元测试文件412 个（tests/），另有 e2e/（29 个）与 smoke/ 两套
默认监听端口8082
默认模型nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b

官方声明：本项目为独立开源项目，与 Anthropic 无隶属或背书关系；Claude / Claude Code 是 Anthropic 的商标。

二、核心原理：它到底做了什么

FCC 在本地启动一个 HTTP 服务，对客户端伪装成 Anthropic API 和 OpenAI API，对上游则把请求翻译成 OpenAI-compatible 格式。

数据流

Claude Code CLI / VS Code / JetBrains
        │  Anthropic Messages 协议
        ▼
┌─────────────────────────────────────────────┐
│  FCC Proxy  (:8082)                          │
│                                              │
│  /v1/messages        ← Anthropic 入口         │
│  /v1/responses       ← OpenAI Responses 入口  │
│         ▼                                    │
│   Responses Converter（OpenAI → Anthropic）   │
│         ▼                                    │
│   Model Router（Opus/Sonnet/Haiku/Fable 路由）│
│         ▼                                    │
│   Protocol Normalizer（流式 / 工具 / thinking）│
│         ▼                                    │
│   Provider Adapters（Anthropic + OpenAI 兼容）│
└─────────────────────────────────────────────┘
        │  OpenAI Chat Completions / Responses
        ▼
   61 家托管供应商 + LM Studio / llama.cpp / Ollama 本地模型

三层关键转换

  1. 入口层（API 兼容） —— 暴露 /v1/messages（Anthropic）、/v1/responses（OpenAI Responses）、/v1/messages/count_tokens，让客户端以为自己在跟官方 API 通信。
  2. 转换层（协议归一） —— 把 Anthropic 的 messages / thinking / tool_use 结构与 OpenAI 的 responses / reasoning_content / tool_calls 结构互转，并统一流式 SSE 帧格式。
  3. 适配层（Provider Adapters） —— 针对 61 家供应商各自的能力差异（上下文长度、输出上限、推理力度字段、工具 schema）做适配与降级。

三、核心能力清单

能力说明
61 家 ToS 友好供应商声称每月 1.3B+ 免费 token；声明遵守各家条款，若某集成不再被允许则移除
11 个编码 AgentClaude Code、Codex、Pi、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build、Muse Code、Aider、VS Code Chat
自动故障转移重试耗尽后自动切换到下一个配置的 Fallback 模型，无需重启当前轮次，跨所有客户端生效
Token 优化最高省 90%可选集成 RTK（过滤命令输出）+ Headroom（压缩工具结果）
浏览器原生 Code 会话在浏览器里选目录跑 Codex，支持实时 + 后台，会话内可自由换模型/供应商
全终端形态原生启动器、VS Code、Codex App、JetBrains、Discord、Telegram
语音输入本地 Whisper（CPU/CUDA）或 NVIDIA NIM 转写
Agent 能力不打折流式响应、工具调用、原生交错 thinking、图片输入、分层模型路由

四、安装与快速上手

1. 安装

macOS / Linux：

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh

Windows PowerShell：

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))

安装时会交互式询问：

  • 至少选择一个编码 Agent（默认预选 Claude、Codex、Pi、OpenCode、Hermes、DSH、Grok、Muse、Aider）
  • 是否启用 RTK + Headroom token 优化
  • 是否启用本地语音（Whisper）

安装脚本规模不小：install.sh 1,728 行、install.ps1 2,006 行，负责安装 uv、Python 3.14.7、选定 Agent（走各家官方安装脚本）、RTK v0.44.2、Headroom 0.40.0，并写入 fcc-* 系列命令。

依赖硬门槛：uv >= 0.13.4。原因见 PR #2151 —— 低于 0.13.4 的 uv 内置信任库含 emSign ECC Root CA - G3 证书，存在 HTTPS 中间人冒充风险（GHSA-hq85-5cpj-mr62）。安装脚本会自动升级旧版 uv，并拒绝预发布版本。

2. 启动

平台方式
Windows桌面 / 开始菜单打开 Free Claude Code
macOS桌面 / Applications 打开 Free Claude Code（菜单栏图标）
Linux终端执行 fcc-server（需保持终端开启）

启动后自动打开 Admin UI（Windows/macOS 用托盘/菜单栏图标打开 Admin、重启或退出）。

fcc-server --version 可只查看版本而不启动服务。

3. 配置 NVIDIA NIM（推荐起步）

  1. 到 build.nvidia.com/settings/ap… 创建 API key
  2. 打开服务日志中的 Admin UI URL
  3. Providers → NVIDIA NIM → Add key → 粘贴 → Save
  4. MODEL 保持默认 nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b，或从下拉框搜索其他模型
  5. 点击 Apply

可选：在 Admin 开启 Proxy Authentication，用 bearer token 保护本地代理。

4. 启动编码 Agent

fcc-claude     # Claude Code
fcc-codex      # Codex
fcc-pi         # Pi
fcc-opencode   # OpenCode 2
fcc-cline      # Cline
fcc-hermes     # Hermes
fcc-dsh        # DeepSeek Harness Web
fcc-grok       # Grok Build
fcc-muse       # Muse Code
fcc-aider      # Aider

五、支持的 11 个编码 Agent

#AgentFCC 命令备注
1Claude Codefcc-claude主力场景，支持原生 /model 选择器
2Codexfcc-codexOpenAI Responses 协议路径
3Pifcc-pi含 pi_extension.ts 扩展
4OpenCode 2fcc-opencode独立配置适配模块
5Clinefcc-cline
6Hermesfcc-hermesNousResearch
7DeepSeek Harnessfcc-dsh含桌面版集成
8Grok Buildfcc-grokxAI
9Muse Codefcc-museMeta；Windows 有独立安装/卸载脚本
10Aiderfcc-aider
11VS Code Chat通过 Integrations 连接VS Code 内置 Chat 模型选择器

每个 Agent 在 src/free_claude_code/cli/launchers/ 下有各自的 launcher 模块，复杂者（Cline / Hermes / OpenCode / Aider）还带独立的 *_config.py 配置适配。

六、61 家供应商生态

src/free_claude_code/config/provider_catalog.py（837 行）用 ProviderDescriptor 数据类统一声明每家供应商的 ID、展示名、官网、logo、凭证环境变量、凭证申请 URL、默认 base URL、代理属性。该模块严格不含任何 provider 实现导入（有契约测试守护这条边界），实现工厂在 providers/runtime/factory.py。

主要供应商（节选）

类别代表供应商环境变量示例 MODEL
免费额度主力NVIDIA NIMNVIDIA_NIM_API_KEYnvidia_nim/nvidia/nemotron-3-ultra-550b-a55b
OpenRouterOPENROUTER_API_KEYopen_router/openrouter/free
ZenMuxZENMUX_API_KEYzenmux/deepseek/deepseek-v4-flash-free
TokenRouter / NaraRoute / OrcaRouter / xKiro各自 key.../*-free
订阅型 OAuthOpenAI / ChatGPTAdmin UI → OAuth providersopenai/<model-id>
GitHub CopilotAdmin UI → OAuth providersgithub_copilot/<model-id>
ClinePassCLINE_API_KEYcline_pass/cline-pass/kimi-k3
主流云 APIAnthropic、OpenAI API、Google Gemini / Vertex、Azure OpenAI、Amazon Bedrock各自 key—
国产 / 亚洲DeepSeek、Qwen（QwenCloud / QwenCloud Coding）、Kimi（API / Code）、MiniMax、Z.ai、SiliconFlow、Alibaba Cloud各自 key—
推理加速Groq、Cerebras、SambaNova、Fireworks、Together、DeepInfra各自 key—
本地LM Studio、llama.cpp、Ollama（含 Ollama Cloud）*_BASE_URLlmstudio/<id> / llamacpp/<id> / ollama/<tag>

完整 61 家清单见仓库 README 的 Provider catalog 折叠块。

自定义供应商

Providers → Custom providers → Add provider：填 API base URL + 可选 key + API 格式，Model IDs 留空则自动发现，或每行一个上游 model ID。

编号 API Key

Provider 弹窗支持多把编号 Key（Add key / 删除行 / 拖拽排序）。FCC 默认用 key 1，Fallback 里可指定用第几把 —— 这是摊薄单 key 速率限制的实用手段。

七、模型路由与推理控制

分层路由

MODEL 是所有请求的兜底。可以单独覆盖 Claude Code 的各个层级：

设置作用
MODEL全局兜底
MODEL_FABLEFable 层覆盖
MODEL_OPUSOpus 层覆盖
MODEL_SONNETSonnet 层覆盖
MODEL_HAIKUHaiku 层覆盖

选 None 即回落到 MODEL。

Fallback 模型链

Admin UI → Model Config → Fallback Models：按顺序添加备用模型，失败即自动尝试下一个，对所有已连接客户端生效。每一级 fallback 可独立设置推理力度。

⚠️ 官方提示：一次失败的请求可能在成功前消耗多家供应商的额度。

推理力度（Reasoning）

选项行为
From client使用编码 Agent 传来的力度；未传则用供应商默认（Default Effort 初始即此项）
Off请求关闭推理
Low / Medium / High / X-High / Max覆盖客户端设置
Inherit分层覆盖沿用 Default Effort；Fallback 沿用原请求已解析的力度

Fable / Opus / Sonnet / Haiku 初始为 Inherit。

八、浏览器原生 Code 会话

application/code_sessions/ + runtime/codex_app_server.py + SQLite 持久化（code.db，含 5 个迁移版本）构成这套能力。

  • 浏览器中选一个目录，直接跑 Codex
  • 支持实时会话与后台任务
  • 同一会话内自由切换 provider / model
  • 官方 Roadmap：同一会话内切换 harness（coming soon）

九、客户端集成

统一入口：Admin UI → Integrations → 对应卡片 → Connect

客户端前置条件
VS Code 中的 Claude Code安装 Claude Code 扩展
VS Code Chat安装最新 VS Code，在内置 Chat 模型选择器中选 FCC 模型
Claude Desktop安装后完全退出再连接；Disconnect 可恢复官方登录态
VS Code / App 中的 Codex安装 Codex 扩展或 Codex App
DeepSeek Harness Desktop先安装并打开一次该 App
JetBrains ACP 中的 Claude Code先装并启动一次 JetBrains AI Assistant 的 Claude Agent，连接后重开 IDE 选 Claude Code (FCC)

连接后需 Reload VS Code / 重启 App 或 IDE。Claude Code 的 onboarding 可在 Integrations → Claude Code onboarding → Complete onboarding 单独完成。

注意：FCC 与客户端必须跑在同一台机器、同一用户环境下。

十、可选的聊天机器人集成

在 Admin UI → Messaging 配置，支持 Discord 与 Telegram 两个平台（各自有 _inbound.py / _io.py 收发模块 + 独立的 Markdown 渲染器）。

  • Discord 需开启 Message Content Intent，并授予读/发/历史/Manage Messages 权限
  • Telegram 需从 @BotFather 建 bot、从 @userinfobot 取数字 user ID
  • 两者都要求配置绝对路径的 Allowed Directory（安全边界）
  • 语音消息由 platforms/voice_flow.py 处理

消息命令

用法行为
/stats显示会话状态
单独 /stop取消所有工作
回复中 /stop只取消该请求，队列中的其他请求继续
单独 /clear清除该聊天的所有 FCC 会话与消息
回复中 /clear删除选中消息及其回复链，保留其他会话

语音输入

  • NVIDIA NIM 转写：每次安装都自带，Admin → Messaging → Voice 选 nvidia_nim 即可
  • 本地 Whisper：需重装并加参数 
    # macOS/Linux（CPU）
curl -fsSL ".../install.sh" | sh -s -- --voice-local
# macOS/Linux（CUDA 13.0）
curl -fsSL ".../install.sh" | sh -s -- --voice-local --torch-backend cu130
# Windows
... install.ps1 -VoiceLocal [-TorchBackend cu130]
    本地 gated 模型还需 HUGGINGFACE_API_KEY。voice_local 额外依赖：torch / transformers / accelerate / librosa。

十一、配置与数据目录

所有状态集中在 ~/.fcc/：

路径用途
~/.fcc/.env托管配置（凭证、模型、路由）
~/.fcc/fcc.db主数据库（SQLite，SQLAlchemy）
~/.fcc/code.dbCode 会话持久化（含 v0001~v0005 迁移）
~/.fcc/logs/server.log、startup.log日志（Loguru）
~/.fcc/auth/OAuth 凭证（openai.json 等）
~/.fcc/tmp/launchers/启动器私有临时配置
~/.fcc/agent_workspace/消息平台状态
~/.fcc/*.lockconfig.lock / server.startup.lock / server.owner.lock / code.lock —— 跨进程协调

配置系统有独立的 env_migrations.py 负责版本迁移（例：NVIDIA 下线 Super 端点后，自动把已存配置迁移到 Ultra，PR #2135）。

十二、命令参考

命令作用
fcc-server启动服务（--version 只看版本）
fcc-doctor诊断，出问题时把输出贴到 bug report
fcc-desktop桌面 GUI 启动器（gui-script）
fcc-claude / fcc-codex / fcc-pi / fcc-opencode / fcc-cline / fcc-hermes / fcc-dsh / fcc-grok / fcc-muse / fcc-aider启动对应编码 Agent
fcc-update更新到已验证的稳定版本（含匹配的 installer）
_fcc-update-check更新检查（内部用）

更新

fcc-update          # 先停掉所有正在运行的 FCC 命令

Windows 本地语音用户需追加 -VoiceLocal [-TorchBackend cu130]。

Muse Code（原生 Windows）有独立脚本：install-muse.ps1 / uninstall-muse.ps1；卸载 FCC 不会移除 Muse Code。

卸载

移除：FCC 本体、桌面启动器、所有命令、~/.fcc/ 保留：uv、Python、你的编码 Agent、RTK、Headroom

curl -fsSL ".../uninstall.sh" | sh              # macOS/Linux
& ([scriptblock]::Create((irm ".../uninstall.ps1")))   # Windows

十三、代码架构（源码分层）

src/free_claude_code/ 采用清晰的分层 + 端口适配器（Ports & Adapters） 风格：

包职责关键点
api/FastAPI 适配层routes.py（协议入口）、admin_routes.py（628 行，管理面）、handlers/（messages / responses / token_count）、stream_*.py（流式帧）、tool_call_buffer.py
application/应用层用例routing.py（模型路由）、reasoning.py、model_catalog.py、code_sessions/（浏览器会话）、web_tools/
core/领域核心anthropic/（21 个模块：协议模型、SSE 聚合、thinking、工具结果、流式账本/恢复/发送器）、openai_responses/（18 个模块）
providers/供应商适配runtime/（发现、工厂、模型缓存）、openai_chat/（通用 OpenAI 兼容基座，14 个模块）+ 各厂商特化子包
harnesses/Agent 集成Claude / Codex / DSH / JetBrains ACP / VS Code Chat 的集成与清理
cli/命令行与桌面launchers/（11 个 Agent 启动器）、managed/（托管 Claude 进程）、desktop_tray.py、macos_app.py、doctor.py
config/配置域provider_catalog.py（61 家）、admin/（Admin 表单 spec 与持久化）、settings.py（Pydantic，747 行定义 port 等）
messaging/聊天平台Discord / Telegram、消息树（trees/）、转写（transcript/）、渲染（rendering/）
runtime/运行时装配bootstrap.py、lifecycle.py、SQLite、Codex App Server、集成服务
updater/自更新check.py

工程规范（写在 CONTRIBUTING.md，很有参考价值）

  • PR 标题即版本号来源：改动 assets/、scripts/、src/、pyproject.toml、uv.lock 的 PR，标题必须以 patch: / minor: / major: 开头（冒号后恰好一个空格）。版本号由发版流程在 merge 后计算，禁止手改。
  • 目标 Python 3.14，依赖原生惰性注解，禁止 from __future__ import annotations
  • CI 禁止 # type: ignore / # ty: ignore，必须真正修类型问题
  • 共享的 Anthropic 协议行为只能放 core/anthropic/；供应商专属配置只放该供应商自己的包
  • 不接受 Docker 集成 PR；独立文档 PR 仅仓库所有者可提

质量门禁

  • 格式化/Lint：Ruff（target py314，启用 E/W/F/I/UP/B/C4/SIM/PERF/RUF）
  • 类型检查：Ty（Astral 出品）
  • 测试：Pytest + pytest-asyncio / xdist（worksteal）/ cov / playwright / split
  • 完整本地 CI：./scripts/ci.sh（PowerShell 用 .\scripts\ci.ps1）
  • 测试分四层：tests/（412 个文件，单元+契约）、e2e/（29 个，Playwright 级端到端）、smoke/（live 标记，可碰真实服务，分 prereq/product/desktop/installers）、tests/contracts/
  • pyproject.toml 把 filterwarnings = ["error"] 设为默认 —— 警告即失败，纪律相当严

十四、近期演进（近一个月的关键 PR）

PR日期内容影响
#215110-22要求 uv >= 0.13.4安全：规避 emSign 根证书 HTTPS 冒充风险（GHSA-hq85-5cpj-mr62）
#213510-21NVIDIA Super → Ultra 迁移NVIDIA 下线 Nemotron 3 Super 免费端点，FCC 自动迁移已存配置/环境变量/tier/fallback
#211210-18移除 5 个 Claude 请求"优化"配额探测、命令前缀检测、标题生成、建议、文件路径提取不再本地伪造响应，一律转发给真实 provider（代价：承担真实延迟/限流/失败）
#210110-17依赖最低版本 + 类型检查器兼容—
#209510-16修复 macOS 菜单栏启动身份用原生可执行文件承载 uv 管理的 Python，保留 App Bundle 身份（修复 issue #2092 零高度窗口）；arm64 + x86_64 双启动器 + ad-hoc 签名
#203510-10新增 Atlas Cloud providerprovider 总数修正为 61

#2112 是值得注意的方向调整：FCC 早期为了省 token 会拦截并伪造部分辅助请求的响应，现在主动放弃这类"优化"，选择如实转发。这意味着透明性优先于省额度。

十五、优势与需要注意的点

优势

  1. 协议转换做得很扎实 —— Anthropic ↔ OpenAI 双向转换、流式帧、thinking / reasoning_content、工具 schema 适配都有独立模块，不是简单转发。
  2. 故障转移设计体贴 —— Fallback 链 + 编号 Key + 不中断当前轮次，直击免费额度不稳定的痛点。
  3. 工程纪律罕见地严格 —— 警告即失败、PR 标题驱动语义化版本、契约测试守护模块边界、三层测试体系、#2112 主动砍掉"作弊式优化"。
  4. 覆盖形态全 —— 终端 / 桌面 / IDE / 手机 / 浏览器 / 聊天机器人全打通。

需要注意

  1. 订阅型接入的合规边界 —— OpenAI/ChatGPT、GitHub Copilot、ClinePass、Kimi Code、QwenCloud Coding Plan 走的是订阅凭证。项目自称 ToS-friendly 并承诺移除不再被允许的集成，但用户仍需自行判断各家条款（README 也专门提示 Kimi Code / Coding Plan 仅限个人交互式编码用途）。
  2. 免费额度不稳定 —— 官方明示"免费层可用性与限额由各供应商控制，可能变动"；#2135 就是端点被下线的实例。现有会话会保留旧模型选择，需手动改到 Ultra。
  3. Python 版本锁死 ==3.14.7 —— 相当激进，部署环境需配合。
  4. AGPL-3.0-only —— 若你基于它做网络服务二次分发，需注意 AGPL 的网络交互条款传染性。
  5. 本地代理的安全面 —— 默认 8082 端口，官方建议开启 Proxy Authentication；消息机器人务必配置 Allowed Directory 绝对路径限制。

十六、30 秒总结

FCC = 一个跑在本机 8082 端口的协议转换代理，左手伪装成 Anthropic / OpenAI API 接住 11 个编码 Agent，右手把请求翻译后发给 61 家供应商（含本地模型）。核心价值是让你把编码 Agent 的"大脑"换成任何你想要/免费/本地的模型，并在供应商挂掉时自动换下一个。工程完成度高、测试纪律严格，是同类工具里少见的"认真做产品"的项目。

附录：关键链接

avatar
文章
阅读
粉丝