free-claude-code（Alishahryar1/free-claude-code）：在本地 :8082 撬开编码智能体的后端锁定，61 家模型供应商随便换

一、导读

Claude Code 的能力瓶颈，从来不只是「模型够不够强」，而是你被绑在了一个后端上：想换模型就要换工具，想省钱就要牺牲体验。free-claude-code（下称 FCC）用最克制的方式撬开了这把锁——在本地起一个 :8082 的代理，接住 Claude Code、Codex、Pi、OpenCode 等 11 个编码智能体发出的请求，再按你配置的规则分派到 61 家模型供应商：免费层、你自己的付费 key、ChatGPT / GitHub Copilot 订阅，以及 LM Studio、llama.cpp、Ollama 等本地模型。它不改 agent 一行代码，只改一个 base_url。项目创建于 2026-01-28，截至 2026-10-12 已收获 58,992 星、当日涨星 705，单日连发四个版本。它的价值不在模型，而在于把「换模型」从重装工具降级为改一行配置。

二、项目速览

项目	详情
仓库	`Alishahryar1/free-claude-code`（简称 FCC）
作者	Ali Khokhar（GitHub @Alishahryar1；LICENSE 署名为 Ali Khokhar）
主语言	Python（`requires-python ==3.14.7`，uv 管理依赖）
Star 总数 / 当日涨星	58,992 / 705（GitHub Trending daily，抓取日 2026-10-12；月榜 +22,438）
Fork / Open Issues / Watchers	9,303 / 302 / 401
License	AGPL-3.0-only（`LICENSE` 文件与 README 徽章一致；GitHub API 因非标准文本返回 `NOASSERTION`，部分第三方文章称其为 MIT，属错误信息）
首次创建 / 最近推送	2026-01-28 / 2026-10-12
最新版本	v6.16.0（2026-10-12）；同日另有 v6.15.0、v6.14.0，前一日 v6.13.6
规模	1,031 个文件，其中 907 个 `.py`；累计约 959 个 PR
核心主张	61 家供应商、11 个编码智能体、每月 1.3B+ 免费 token、token 用量最高降 90%

三、为什么是它：问题背景与定位

痛点：编码智能体时代形成的「反向锁定」。 2026 年的编码智能体（Claude Code、Codex、Pi…）已经把「读项目 → 改文件 → 调工具 → 跑命令 → 接 IDE」这套体验做得非常成熟，问题是这套体验与提供它的模型公司深度耦合。用户面对的是三重难受：一是成本，重度使用编码智能体的月账单可以超过它创造的价值；二是配额与可用性，高峰期限流、单家供应商故障都会打断整轮工作；三是迁移成本，换模型往往意味着换掉整个工作流。

FCC 的定位极其精确：它不造模型、不造 agent，只造「中间那一层」。 用作者自己的隐喻——它是一个转接头：agent 仍然以 Anthropic Messages 协议说话，FCC 在中间做协议翻译与路由，再把请求送给你选的供应商。第三方评测把这一点总结得很到位：FCC 不打扰你原本的使用习惯，不要求你重学工具，不让你改 Claude Code 一行代码，只是安静地站在 :8082 接住每一次请求。

涨星动因（当日 +705）有三重叠加：

「省钱」是本地推理社群最强的动机。 项目主张「61 家对 ToS 友好的供应商、每月 1.3B+ 免费 token」，并明确承诺遵循各供应商条款、一旦某集成不再被允许就移除它——这种「不冒账号风险地白嫖」的叙事，比单纯的性能宣传传播力强得多。
协议转换层才是真正的护城河。 它同时提供 Anthropic Messages（/v1/messages）与 OpenAI Responses（/v1/responses）两条入站通道，并把二者统一到同一套路由与规范化管线。这不是简单的 HTTP 转发，而是要处理流式事件、工具调用、推理（thinking）块、图片输入在异构协议间的等价映射——工程量集中在这里。
分发链条完整到「不像个人项目」。 一行 install.sh 安装、Windows/macOS 托盘常驻、VS Code / JetBrains / Claude Desktop / Codex App 集成、Discord / Telegram 机器人、浏览器内原生 Codex 会话、语音留言转写——每一环都在降低「试一下」的成本，这是它半年做到近 5.9 万星的结构性原因。

四、【重点】架构原理

4.1 整体架构：双协议入站 + 一条本地代理总线

FCC 的架构可以概括为一句话：入站收敛到两条协议，出站扇出到 61 家适配器，中间是一条带路由、优化与恢复能力的本地管线。仓库自带的官方架构图（assets/how-it-works.mmd）画得很清楚，这里整理为 ASCII 版：

┌── 客户端层（编码智能体 / Harness）─────────────────────────────────┐
│ Claude Code CLI / VS Code / JetBrains / Claude Desktop / 消息机器人 │
│ Codex CLI / Codex VS Code 扩展 / Codex App                         │
└──────────┬───────────────────────────────────┬────────────────────┘
           │ ① Anthropic Messages              │ ① OpenAI Responses
           │    /v1/messages, /v1/models       │    /v1/responses
           ▼                                   ▼
   ┌───────────────────┐            ┌──────────────────────────┐
   │ Anthropic API 面  │            │ Responses Converter      │
   │ （原生面）        │            │ OpenAI → Anthropic 归一  │
   └─────────┬─────────┘            └────────────┬─────────────┘
             └──────────────┬────────────────────┘
                            ▼
╔══ Free Claude Code Proxy  :8082 ═══════════════════════════════════╗
║  Local Admin UI（keys / models / status）                          ║
║  Managed Config  ~/.fcc/.env                                       ║
║          │                                                         ║
║          ▼                                                         ║
║  ┌──────────────────┐   Model Router：Fable / Opus / Sonnet / Haiku ║
║  │  Model Router    │   把「模型名」解析为 provider + model + key#    ║
║  └────────┬─────────┘   并附加有序 fallback 链                      ║
║           ▼                                                        ║
║  ┌──────────────────┐   本地廉价探针：配额探测、命令前缀、          ║
║  │ Request Optimize │   标题、建议、文件路径——不打供应商即可应答    ║
║  └────────┬─────────┘                                              ║
║           ▼                                                        ║
║  ┌──────────────────┐   流式事件、工具调用、thinking 块、图片        ║
║  │ Protocol         │   在 Anthropic / OpenAI 两套语义间等价映射    ║
║  │ Normalizer       │                                              ║
║  └────────┬─────────┘                                              ║
║           ▼                                                        ║
║  ┌──────────────────┐   Admission：准入、并发、重试、恢复预算       ║
║  │ Provider Adapters│   原生 Anthropic 透传 + OpenAI 兼容适配       ║
║  └────────┬─────────┘                                              ║
╚═══════════╪═══════════════════════════════════════════════════════╝
            │
    ┌───────┴────────────────────────────────────────────┐
    ▼                                                    ▼
┌── 托管供应商 ────────────────┐          ┌── 本地供应商 ──────────┐
│ NVIDIA NIM · Kimi · Wafer    │          │ LM Studio :1234        │
│ OpenRouter · DeepSeek · Groq │          │ llama.cpp :8080        │
│ Anthropic · Gemini · Bedrock │          │ Ollama :11434          │
│ …（共 61 家，见 provider_catalog.py）  │ Ollama Cloud           │
└──────────────────────────────┘          └────────────────────────┘

这张图的关键在于两端都做了极致收敛：入站只有两条协议（agent 差异被收敛成「说 Messages 还是说 Responses」），出站是 61 个平级适配器（供应商差异被收敛成「是否原生支持 Messages 透传」）。中间才因此有了可维护的路由与优化空间。

4.2 分层模块拆解

仓库共 20 个顶层包、约 15.3 MB 源码（size=15270 KB），按职责分层非常清晰：

层	目录	文件数	职责与代表模块
接入层	`api/`	96	FastAPI 路由与出站投递。`routes.py`（12.0KB）定义 `/v1/messages`、`/v1/responses`、`/v1/models`；`stream_delivery.py`（15.2KB）与 `response_streams.py`（13.5KB）负责 SSE 投递与生命周期；`admin_routes.py`（19.4KB）+ `admin_static/`（67 文件，含 113KB 的 `admin.js`）构成 Admin UI
应用层	`application/`	20	路由与执行编排。`routing.py`（12.5KB）实现 `ModelRouter`；`execution.py`（23.9KB）是「入站适配器共用的供应商执行」管线；`reasoning.py` 解析推理档位
供应商层	`providers/`	116	61 家适配器 + 横切能力。`admission.py`（33.6KB，全项目最大单文件之一）负责准入、并发与重试生命周期；`failure_policy.py`（20.1KB）、`model_listing.py`（17.9KB）、`continuation.py`（12.9KB）、`credential_validation.py`（12.7KB）、`stream_recovery.py`（8.6KB）
协议层	`core/`	78	协议语义与不变式。`anthropic/`（25 文件）与 `openai_responses/`（23 文件）各成一套；`history_replay.py`（22.9KB）处理历史重放，`delivered_response.py`（20.7KB）保证「已投递内容」的账本一致
Harness 层	`harnesses/`	18	各 agent 的接入细节。`claude_desktop_integration.py`（14.6KB）、`jetbrains_acp_integration.py`（8.3KB）、`dsh_desktop_integration.py`（7.8KB）、`codex_integration.py`（5.2KB）、`vscode_chat_integration.py`（4.9KB）
运行时层	`runtime/`	31	服务装配与持久化。`integration_service.py`（33.2KB）、`provider_manager.py`（31.0KB）、`code_sessions_sqlite.py`（30.4KB）、`codex_app_server.py`（30.3KB）、`messaging_service.py`（14.4KB，Discord/Telegram）
配置/CLI	`config/` `cli/`	28+37	`provider_catalog.py`（34.6KB，61 个 `ProviderDescriptor` 的单一事实来源）、12 个 `fcc-*` 入口脚本

从体积分布能看出工程重心：providers/（116 文件）与 api/（96 文件）合计占了近一半文件数，而真正「业务逻辑」很薄。这说明 FCC 不是一个应用，而是一层基础设施——它的大部分代码在写「怎么和 61 家供应商把话说清楚」以及「怎么把两条协议的事件流对齐」。

4.3 核心机制：路由、协议归一与恢复

(a) 路由：把「模型名」解析为「执行目标 + 回退链」。 application/routing.py 的 ModelRouter.resolve() 是全线最关键的函数。它做两件事：

_ROUTE_SETTINGS = (
    ("fable",  "model_fable",  "reasoning_fable"),
    ("opus",   "model_opus",   "reasoning_opus"),
    ("haiku",  "model_haiku",  "reasoning_haiku"),
    ("sonnet", "model_sonnet", "reasoning_sonnet"),
)

class ModelRouter:
    def resolve(self, claude_model_name: str) -> ResolvedModelRoute:
        # ① 先看是不是 <provider>/<model> 直接指定（如 kimi_code/k3）
        direct_provider_id, direct_provider_model, force_reasoning_off = \
            self._direct_provider_model(claude_model_name)
        if direct_provider_id is not None:
            return ResolvedModelRoute(primary=self._target(...),
                                      fallbacks=self._fallback_targets(primary), ...)
        # ② 否则按 Fable/Opus/Sonnet/Haiku 四档映射到配置的模型
        provider_model_ref = self._resolve_model_ref(claude_model_name)
        primary = self._target_from_ref(provider_model_ref)
        return ResolvedModelRoute(original_model=claude_model_name, primary=primary,
                                  fallbacks=self._fallback_targets(primary), ...)

这套设计最巧妙的地方是「四档映射」：Claude Code 内部把模型分成 Fable / Opus / Sonnet / Haiku 四档（思考强度与场景不同），FCC 就让你逐档指定不同的供应商模型——典型配置如「Opus 甩给 Kimi、Sonnet 甩给 openrouter/free、Haiku 甩给本地 Qwen」。这样既不损失 Claude Code 的分档调度能力，又让每一档都走最便宜/最合适的后端。ProviderModelTarget 里还带 api_key_number，同一家供应商可以挂多个 key 并指定用第几个（v6.16.0 的更新正是「为 fallback 模型选择 API key」）。

(b) 协议归一：两条入站通道，一套执行语义。 api/routes.py 的分派逻辑揭示了一个重要优化——如果目标供应商原生支持 Messages 协议，就走透传；否则才做转换：

resolved = router.resolve(model)
native = resolved is not None and supports_native_messages(resolved.primary.provider_id)
if native:
    native_request = NativeMessagesRequest(raw)          # 原生透传，零转换损耗
else:
    request_data = MessagesRequest.model_validate(raw)    # 归一化路径
    await lease.wait_for_token_estimation()

「原生支持就走透传」是一个很务实的取舍：转换必然有信息损耗（thinking 块、工具 schema、图片编码都可能失真），所以只在必要时付这个代价。而 core/anthropic/ 与 core/openai_responses/ 各 20+ 文件的规模说明，归一化本身是硬活——think_tag_parser、tool_schema_patterns、map_stop_reason、aggregate_anthropic_sse_to_message 这些模块都是在填平两套协议的语义鸿沟。

(c) 准入与恢复：把「供应商会挂」当成常态来设计。 这是 FCC 最被低估的部分，也是它区别于「简单反向代理」的分水岭。providers/admission.py（33.6KB）定义了明确的预算：

UPSTREAM_TRANSIENT_TOTAL_ATTEMPTS = 5      # 瞬时错误最多 5 次尝试
DEFAULT_UPSTREAM_BASE_DELAY = 2.0          # 指数退避起点 2 秒
DEFAULT_UPSTREAM_MAX_DELAY = 60.0          # 退避上限 60 秒
DEFAULT_UPSTREAM_JITTER = 1.0              # 抖动，避免惊群

更关键的是 core/stream_recovery.py——它处理一个真实世界最恶心的问题：流式响应已经吐了一半，上游挂了怎么办？ 直接重试会让用户看到重复内容，直接报错会浪费已生成的部分。FCC 用一个「已投递前缀账本」来判定安全动作：

class RecoveryAction(StrEnum):
    RESTART = "restart"    # 还没吐内容 → 直接重来
    CONTINUE = "continue"  # 已吐文本 → 带上前缀续写
    HANDOFF  = "handoff"   # 工具调用已完成 → 安全交接到 fallback 模型
    STOP     = "stop"      # 结构化输出/正常结束 → 不可恢复，如实停止

def assess_recovery(*, content_released, prefix, source, retryable):
    if source.normal_stop_seen: return RecoveryAssessment(RecoveryAction.STOP, ...)
    if not content_released:    return RecoveryAssessment(RecoveryAction.RESTART, ...)
    if prefix is None:          return RecoveryAssessment(RecoveryAction.STOP, reason="missing_prefix")
    if prefix.has_calls:
        if retryable and not source.structured_output and source.can_handoff and prefix.can_handoff:
            return RecoveryAssessment(RecoveryAction.HANDOFF, reason="completed_tool_calls")
        return RecoveryAssessment(...)

这套「四态恢复判定」直接支撑了 README 里那句「供应商中断也能继续写代码」的承诺：重试耗尽后自动切到下一个配置模型，且不需要你重启这一轮对话。但代码同时诚实保留了 unsafe_reason 与「结构化输出不可交接」的守卫——能恢复的才恢复，不能恢复的如实停下，而不是伪造续写。

(d) 五处本地优化：不打供应商就把活干了。 README 明确列出「五项 FCC 优化不调用供应商即可处理：配额探测、命令前缀识别、标题、建议、文件路径」。这类请求（如 Claude Code 频繁询问的标题生成、命令前缀补全）原本每次都要打一次真实 API，FCC 在本地廉价应答，兑成了「token 用量最高降 90%」的一部分。另有可选的 RTK（过滤常见命令输出）与 Headroom（压缩工具结果）两个外部组件参与降耗。

4.4 性能优化手段与设计取舍

手段	做法	为什么	代价
原生协议透传	供应商支持 Messages 就零转换	避免 thinking/工具 schema 失真	需按供应商维护 `native_messages_passthrough` 标记
四档模型映射	Fable/Opus/Sonnet/Haiku 各指一个后端	保留 agent 分档调度，同时按档配最省的后端	配置复杂度上升
有序 fallback 链	重试耗尽即切下一个模型	供应商故障不再中断整轮	一个失败请求可能消耗多家供应商额度（README 明确警告）
流式四态恢复	按已投递前缀决定重启/续写/交接/停止	不重复输出、不浪费已生成内容	逻辑复杂（20.7KB 的投递账本）
本地廉价应答	标题/建议/配额探测不打上游	直接省 token	需持续跟随 agent 的请求模式变化
多 key 轮换	同供应商挂多个 key 并指定序号	对冲单 key 限流	key 管理成本上升
托盘常驻 + 本地优先	代理跑在本机，无云同步、无遥测	密钥不出本机	需用户自行保证本机安全

取舍的本质：FCC 用「工程复杂度」换「供应商可替换性」。 它把自己做成了一层「协议与故障的适配器」——所有复杂度都来自「异构」二字：协议异构、能力异构、限流策略异构、失败模式异构。如果只用一家供应商、一个模型，FCC 毫无价值；一旦你开始混用多家，这层适配器就从负担变成了基础设施。

五、【重点】应用场景

场景一：把编码智能体的成本压到接近零

业务痛点：独立开发者、学生、早期团队想用 Claude Code 这类编码智能体，但月账单可能超过它带来的收益——官订档位固定，而实际用量波动很大，忙时不够用、闲时白交钱。

如何解决：FCC 聚合 61 家供应商，多家提供免费层。你把不同「档位」指向不同后端，Claude Code 的完整体验保持不变，只有后端换了。

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

# 2) 启动服务（首次会打开本地 Admin UI）
fcc-server

# 3) 在 Admin UI（127.0.0.1:8082/admin）中：
#    Providers → NVIDIA NIM → Add key → 粘贴 key → Save
#    Model Config → MODEL 填 nvidia_nim/nvidia/nemotron-3-super-120b-a12b → Apply

# 4) 用原生方式启动 Claude Code
fcc-claude

收益与量化：官方主张「61 家对 ToS 友好的供应商、每月 1.3B+ 免费 token、token 用量最多降 90%」。其中降耗主要来自五项在本地完成的优化（配额探测、命令前缀、标题、建议、文件路径），加可选 RTK（过滤命令输出）与 Headroom（压缩工具结果）——这些请求原本每次都要打一次真实 API。仓库 stats.json 记录 npm 侧用户 629.3k+、市场侧 46.3k+。

适用边界与不建议：免费层额度与可用性由各供应商控制且随时变化，项目明确声明「一旦某集成不再被允许就移除」。不建议把免费层用于关键交付或商业合规场景——它是省钱手段，不是 SLA 保障。

场景二：把「供应商挂掉」从打断变为无感

业务痛点：单家供应商限流、高峰降级、突发 5xx，对编码智能体伤害极大——Agent 正在改一批文件，中途断流可能留下半成品状态；重新发起往往要从头再来，浪费的不只是钱，还有已完成的推理。

如何解决：FCC 的有序 fallback 链 + 流式四态恢复。在 Admin UI → Model Config → Fallback Models 中按顺序添加候选，每个 fallback 可独立指定推理档位与 API key 序号。

# Fallback 链示例（在 Admin UI 中依次 + 添加）
# 1. kimi_code/k3                （主力，订阅档）
# 2. open_router/openrouter/free
# 3. ollama/qwen3-coder:480b     （本地兜底）

# 多 key 轮换：同一供应商可配置编号 key，fallback 可指定用第几个
# NVIDIA_NIM_API_KEY='["key-one","key-two"]'

收益与量化：上游瞬时错误最多重试 5 次，采用 2s 起步、60s 封顶的指数退避加 1s 抖动；重试耗尽后自动切换下一个配置模型，无需重启当前轮次。流式恢复按已投递内容分四态：未吐内容 RESTART，已吐文本带前缀 CONTINUE，工具调用已完成 HANDOFF 交接，结构化输出或正常结束则如实 STOP——既不重复输出，也不伪造续写。

适用边界与不建议：README 明确警告「一个失败请求可能在成功前触达并消耗多家供应商的额度」，因此不要把高价模型无节制地放在链条尾部。此外 HANDOFF 需要 can_handoff 与 retryable 同时成立，结构化输出（如 JSON schema）场景不可交接，此时会如实停下。

场景三：本地模型与云端模型混用（数据隔离 + 成本分层）

业务痛点：代码里既有可上云的通用逻辑，也有不能外发的敏感模块（凭据处理、合规算法、内部脱敏）。理想状态是「敏感活走本地、重活走云端」，但 agent 只会打一个后端，做不到分流。

如何解决：四档映射天然支持这种分层——把最频繁、最轻的档位（Haiku）指向本地模型，把需要强推理的档位（Opus）指向云端；本地三种后端各有独立前缀。

# 本地后端准备（以 Ollama 为例）
ollama pull qwen3-coder:480b
ollama serve

# Admin UI → Model Config 分档指定：
# MODEL_HAIKU  = ollama/qwen3-coder:480b      （本地，边际成本为零）
# MODEL_SONNET = open_router/openrouter/free  （云端免费层）
# MODEL_OPUS   = kimi_code/k3                 （云端强模型）

收益与量化：本地默认地址由 provider_catalog.py 作为单一事实来源声明——LM Studio http://localhost:1234/v1、llama.cpp http://localhost:8080/v1、Ollama http://localhost:11434。轻档位走本地意味着这部分请求完全不出机器；项目同时明确「本地运行，无遥测、无云同步、无账号」，密钥与代码始终留在本机。

适用边界与不建议：README 提醒本地模型必须支持工具调用，且上下文要足够容纳 agent 的系统提示与工具定义，否则编码智能体会频繁失败。不建议把本地小模型指向需要长上下文与强工具调用的主档位——分层前提是「轻活走本地」，反过来用会显著降低体验。

场景四：统一团队的 IDE / 桌面端模型策略

业务痛点：团队里有人用 VS Code，有人用 JetBrains，有人用 Claude Desktop，模型选择、key、配额都散落在个人配置里。想统一换模型或加供应商，就得逐个通知、逐个改配置。

如何解决：FCC 提供「一点配置、多端生效」的集成卡片——在 Admin UI → Integrations 点击 Connect 即完成接入，配置统一落在 ~/.fcc/.env。也可不依赖向导，手动把客户端指向代理。

# 手动接管 Claude Code（不依赖集成向导）
#   ANTHROPIC_BASE_URL=http://localhost:8082
#   ANTHROPIC_AUTH_TOKEN=freecc

# 集成向导：VS Code 扩展 / JetBrains ACP / Claude Desktop / DeepSeek Harness Desktop
#   JetBrains：装 Claude Agent → 启动一次 → Connect → 重开 IDE → 新建会话
#   Claude Desktop：先完全退出 → Connect → 重新打开

收益与量化：受支持客户端覆盖 Claude Code（CLI / VS Code / JetBrains ACP / Claude Desktop）、Codex（CLI / VS Code / Codex App）、VS Code Chat 与 DeepSeek Harness Desktop；服务在 Windows/macOS 可托盘常驻，随时打开 Admin、重启或退出。改一处配置，所有接入端同时切换后端——这正是「反向锁定」被打破的地方。

适用边界与不建议：README 要求代理与被配置的客户端跑在同一台机器、同一用户环境下；JetBrains 更新 agent 后需重启 FCC 再新建会话。不建议把它当团队多租户网关——FCC 没有租户隔离与审计计费能力，那是 LiteLLM 之类服务端网关的领域。

场景五：移动端与消息机器人口述写代码

业务痛点：通勤路上、会议间隙突发一个修复想法，但打开 IDE 的成本太高；等坐下时灵感已经流失，而手机上直接写代码体验并不好。

如何解决：FCC 内置 Discord / Telegram 机器人，并支持语音留言自动转写。入口在 Admin UI → Messaging，填完点 Apply。

# Discord：开发者门户建 bot → 开启 Message Content Intent
#   → 邀请时授予 read / send / message-history / Manage Messages
#   → 填 Bot Token、Allowed Channels、Allowed Directory

# Telegram：@BotFather 建 bot，@userinfobot 取用户 ID
#   → 填 Bot Token、Allowed User ID、Allowed Directory

# 语音转写（本地 Whisper，CPU 或 CUDA）
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local --torch-backend cu130

收益与量化：会话内 /stop 单独使用时取消所有工作、回复使用时只取消当前请求而其他排队请求继续；/clear 单独使用时清空全部会话，回复使用时只删该消息及其回复链。语音有两条路径——本地 Whisper（CPU/CUDA）或 NVIDIA NIM 转写（每次安装都内置 NIM 转写支持）。这把手写代码的入口从「必须坐在电脑前」扩展到「任何能发消息的地方」。

适用边界与不建议：机器人需配置 Allowed Directory（绝对路径） 限定可访问范围，这是安全边界而非可选装饰；Discord 还需授予 Manage Messages，否则 /clear 无法删除用户提示。不建议把它暴露到公网或多人共享频道——它是单用户工具，代理鉴权需自行开启（Admin 中的 Proxy Authentication）。

六、快速上手（最小可用）

# —— 安装 ——
# 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")))

# —— 启动 ——
fcc-server              # Linux：保持终端开启；Win/macOS 用托盘图标打开 Admin

# —— 配置（浏览器打开日志中的 Admin URL，默认 127.0.0.1:8082/admin）——
#   Providers → NVIDIA NIM → Add key → Save
#   MODEL = nvidia_nim/nvidia/nemotron-3-super-120b-a12b → Apply

# —— 跑起来（沿用各 agent 原生用法与 /model 选择器）——
fcc-claude      # Claude Code
fcc-codex       # Codex
fcc-opencode    # OpenCode 2
fcc-aider       # Aider

# —— 诊断与升级 ——
fcc-server --version   # 不启动服务，只查版本
fcc-doctor             # 出问题时跑这个，把输出贴进 issue
fcc-update             # 已是最新则直接退出

三个必须提前知道的坑：一是Python 版本被锁死——pyproject.toml 声明 requires-python == "3.14.7"（精确等于，不是 >=），用其他版本会直接装不上；二是 Admin UI 配置存在 ~/.fcc/.env，卸载脚本会连同整个 ~/.fcc/ 一起删除（但会保留 uv、Python 与已装的 coding agent、RTK、Headroom）；三是代理默认可能无鉴权，若本机有他人使用，请在 Admin 中开启 Proxy Authentication 加 bearer token。

七、横向对比

维度	Free Claude Code	Claude Code Router	LiteLLM	直接用官方 API
部署位置	本机 `:8082`（托盘常驻）	本机	服务端	无（云）
入站协议	Anthropic Messages + OpenAI Responses	主要 Anthropic	多协议（面向服务端）	各家原生
供应商数量	61 家（`provider_catalog.py` 为单一事实来源）	多家，偏路由	极多	1 家
客户端覆盖	11 个 harness + VS Code / JetBrains / Claude Desktop / Codex App	Claude Code 系	以 SDK / HTTP 为主	各自官方
故障回退	有序 fallback + 流式四态恢复	基础重试	支持重试/回退	无
成本优化	五项本地应答 + RTK/Headroom，宣称最高 -90%	有限	预算与限流治理	无
消息 / 语音	Discord + Telegram + 语音转写	无	无	无
多租户与计费	无	无	核心能力	N/A
License	AGPL-3.0-only	见仓库	见仓库	商业
最适合	个人开发机、多供应商混用	单一替换	团队服务端网关	求稳、预算充足

一句话选型：要在自己电脑上把 Claude Code 变成「可换后端」，选 FCC；只要换一个后端，Claude Code Router 更轻；要做团队多租户网关与计费，选 LiteLLM；追求零转换损耗与最高稳定性且预算充足，就是官方 API。

八、局限、风险与社区观察

一、License 是 AGPL-3.0-only，且被广泛误传为 MIT。 仓库 LICENSE 首行写明 SPDX-License-Identifier: AGPL-3.0-only，署名 Copyright (c) 2026 Ali Khokhar；但多篇第三方文章称其为 MIT 代理，这是明确错误信息。AGPL 意味着：改造成网络服务对外提供必须开源修改；企业内部自用不受影响，包装成 SaaS 售卖则触发 AGPL 义务。

二、合规风险由「供应商条款」而非代码决定。 项目反复强调「ToS-friendly」并承诺移除不再被允许的集成，但「用订阅账号跑第三方 agent」是否被上游许可，最终解释权在各供应商。README 自己也对多个订阅方案加了限定：Kimi Code 与 QwenCloud Coding Plan 均标注「仅限个人交互式编码使用」；Anthropic 路径则明确「使用独立计费的 API key」并提示「工具访问与费用照常计」。这些是真实的法律与封号风险，使用时请自行核对当期条款。

三、单作者依赖度极高，但迭代速度惊人。 contributors 前 15 名中 Alishahryar1 一人 984 次提交，第二名 cursoragent 仅 53 次，其余多为个位数——巴士系数极低。正面看，迭代节奏极其密集：2026-10-12 单日连发 v6.14.0 / v6.15.0 / v6.16.0 三个版本，累计约 959 个 PR；负面看，长期路线完全依赖个人投入，且热门项目一旦停更，安全修复会同步停止。

四、生产可用性的边界要划清。 它明确不是多租户网关：无租户隔离、无计费与配额治理、无审计日志，302 个 open issues 也说明维护压力真实存在。密钥还集中在一处——所有供应商 key 都写在 ~/.fcc/.env，本机一旦被入侵等于一次性交出全部后端凭据，只能靠本机安全与 Proxy Authentication 兜底。

五、正面信号。 工程规范度远超一般个人项目：907 个 .py 文件中测试占比很高（三个最大测试文件均超 70KB），配有 pytest + ty + ruff + loguru 工具链；.github/ 下有 CI、依赖更新与版本策略工作流。pyproject.toml 用 hatchling + hatch-vcs 从 git tag 推导版本——发布纪律是工程化的，不是手写的。

九、小结与行动建议

一句话总结：FCC 不是模型，也不是 agent，而是插在两者之间的一层「可替换接口」——它用协议归一、能力映射与故障恢复的工程复杂度，换回了用户对后端的自由选择权。它解决的不是「哪个模型更强」，而是「我能不能随时换掉它」。

先想清楚你要换的是「成本」还是「能力」。 只为省钱 → 把轻档位（Haiku）指向免费层或本地模型即可，改动最小；想提升能力 → 用四档映射把 Opus 档指向更强模型。两种目标的最优配置完全不同。
务必开启 Proxy Authentication。 代理默认监听本机端口，且所有供应商 key 集中在一个 .env 里。多人共用机器时，不加鉴权等于把全部凭据裸露在局域网上。
fallback 链要按「额度成本」排序，而不是按能力排序。 README 明确警告一次失败请求可能消耗多家供应商的额度；把高价模型放在链条尾部前请先估算最坏情况的花费。
核对上游条款再上量，尤其订阅类方案。 Kimi Code、QwenCloud Coding Plan 等被明确限定为「个人交互式使用」，Anthropic 路径走独立计费 key。把 FCC 接进团队生产环境前，请逐个确认所接供应商当期条款，并注意代码自身的 AGPL-3.0-only 义务。
把它当「个人开发机的适配层」，不要当「团队网关」。 需要多租户、计费、审计时，正确的选择是 LiteLLM 一类服务端网关；FCC 的甜点区是一个人、一台机器、多个后端。

资料来源（抓取日期 2026-10-12）：GitHub REST API（Alishahryar1/free-claude-code：★58,992 / fork 9,303 / open issues 302 / watchers 401 / created 2026-01-28 / pushed 2026-10-12 / size 15,270KB / Python；Releases v6.13.6～v6.16.0；contributors 抽样 Alishahryar1 984、cursoragent 53；约 959 个 PR）；仓库原文 README.md、LICENSE（AGPL-3.0-only，34,108 字节）、pyproject.toml、assets/how-it-works.mmd（官方架构图）、stats.json、src/free_claude_code/application/routing.py、api/routes.py、providers/admission.py（33.6KB）、providers/anthropic_messages/transport.py、providers/openai_chat/transport.py（67.0KB）、core/stream_recovery.py、config/provider_catalog.py（61 个 ProviderDescriptor）；GitHub Trending daily/weekly/monthly 榜（2026-10-12 抓取）；第三方解读：腾讯云开发者社区、feinterview.poetries.top、daily.dev、知乎专栏。已标注待确认项：第三方称本项目为「MIT 代理」与仓库 AGPL-3.0-only 声明不符，以 LICENSE 为准；「1.3B+ 免费 token / 最高降 90% token」为项目自报口径，未见第三方可复现基准。