free-claude-code 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

free-claude-code 是一个以 Python 编写的本地代理项目，项目配置将其描述为连接编程智能体与 OpenAI 兼容 AI 提供方的工具。README 将其定位为统一入口：通过一个可搜索界面使用免费、付费、订阅和本地模型，并连接多种编程客户端。

仓库资料列出的 GitHub 元信息为 63,916 个 Star、9,999 个 Fork，默认分支为 `main`。README 宣称覆盖 61 个符合其服务条款（Terms of Service，ToS）要求的提供方，并称每月有超过 13 亿免费令牌；这些数字是项目方的描述，不代表对模型可用性、配额或未来供应的保证。

定位与目标用户

该项目面向需要在多个编程客户端和模型提供方之间切换的开发者。其核心取舍是由本地代理承担客户端连接与提供方选择的衔接工作，而不是要求每个客户端分别配置所有模型服务；具体路由、认证与会话处理细节，所给资料没有完整展开。

README 明确列出 Claude Code、Codex、Antigravity、VSCode、Pi 和 OpenCode，并称总计支持 12 个编程智能体。用户应把这些名称理解为项目所声明的集成范围，不应据此推定每个客户端在所有操作系统、模型或功能上的兼容程度相同。

• 当工作流涉及多个已列名客户端，且希望使用统一模型目录时，可以评估本项目。
• 当项目需要把免费、付费、订阅或本地模型放到同一入口管理时，可重点核对 README 中的提供方清单和当前接入条件。
• 当团队要求有明确的服务等级协议（Service Level Agreement，SLA）、固定模型配额或长期供给承诺时，现有资料不足以证明项目满足这些要求。

核心功能

README 描述的主要能力，是将不同类型的模型提供方放进一个可搜索的目录，再让多个编程客户端连接该目录。目录的输入是项目支持的提供方及其模型信息，用户通过界面选择模型；代理与客户端之间的具体请求格式、模型筛选规则和失败回退行为，官方仓库未提供该信息，建议以最新 README 为准。

多提供方目录

项目宣称支持免费、付费、订阅和本地模型，并以 ToS 友好作为提供方筛选原则。README 还写明，如果集成后来不再符合允许条件，项目会移除该集成；这是维护策略描述，不能替代用户自行核实提供方条款或账户权限。

目录的实际可用范围取决于提供方是否仍开放服务、用户所在地区、账号状态及其自身限额。所给资料没有逐项列出 61 个提供方名称、各自认证方法、价格或速率限制，因此不应将总数解读为对任意模型随时可用的承诺。

多个客户端共享模型入口

项目资料将代理描述为客户端与 OpenAI 兼容 AI 提供方之间的连接层。按这一定位，客户端发起模型请求，代理负责把请求接到已配置的提供方；但支持的协议细节、请求转换范围以及每个客户端的专属适配行为，现有摘录没有说明。

`pyproject.toml` 声明了 `fcc-claude`、`fcc-codex`、`fcc-pi`、`fcc-opencode`、`fcc-cline`、`fcc-hermes`、`fcc-dsh`、`fcc-grok`、`fcc-muse` 和 `fcc-agy` 等命令入口。入口清单只是包配置中的事实，不足以单独证明每个命令的完整交互流程或安装后的行为。

终端、应用与浏览器使用方式

仓库描述称可从终端、应用、IDE、手机和浏览器使用，并将浏览器能力描述为原生浏览器会话，支持多客户端与多模型；描述还提及语音支持和符合 ToS 的方向。资料摘录没有给出浏览器功能的安装、权限、会话存储或语音服务配置步骤，部署前应查看最新 README 对应章节。

由于不同入口可能涉及不同的凭据与会话边界，不能仅凭“浏览器会话”推断数据如何存储、是否同步或是否经过第三方服务。相关数据流与隐私细节应以仓库当前文档及具体提供方的政策为准。

本地代理服务

`pyproject.toml` 注册了 `fcc-server`，其入口指向 `free_claude_code.cli.entrypoints:serve`。结合项目描述，这一命令用于启动服务入口；但绑定地址、端口、认证机制、后台运行方式和健康检查路径均未出现在所给资料中，不能据此提供可核验的启动参数或接口示例。

系统架构与关键模块

可确认的架构线索来自包描述、依赖声明与命令入口：项目是 Python 包，提供服务器、诊断和多客户端启动器，并依赖 FastAPI、Uvicorn、HTTP 客户端及多种模型接入相关库。以下是根据这些声明能确认的边界，不代表完整源码架构图。

从这些线索可以看出，安装包同时定义了服务命令和客户端启动器，而非只有单一命令行程序。模块之间的调用顺序、代理请求生命周期、模型目录更新机制及持久化策略，官方仓库未提供该信息，建议以最新 README 和源码为准。

依赖与运行环境

运行环境约束较明确：`pyproject.toml` 将 Python 版本写为 `==3.14.10`，即项目元数据要求精确匹配该版本。README 徽章显示使用 uv；在实际部署前，应先确认目标机器可以提供该 Python 版本及相应平台轮子。

依赖包括 FastAPI、Uvicorn、HTTP 客户端、Pydantic、OpenAI SDK、Telegram 与 Discord SDK、Google Auth、SQLAlchemy、gRPC、NVIDIA Riva 客户端等。清单中还包含仅在 Windows 或 macOS 条件下安装的 `pystray` 和 Pillow；这只能说明条件依赖的声明，不足以推断完整平台支持矩阵。

• 包构建后端使用 Hatchling，并声明 `hatch-vcs>=0.5.0`。
• 依赖安装工具的 README 徽章指向 uv；资料没有提供最低 uv 版本。
• 测试徽章标注 Pytest，类型检查徽章标注 Ty，格式化工具徽章标注 Ruff。
• 项目版本为动态版本，构建配置使用 `hatch-vcs`；所给资料没有提供当前发布版本号。

依赖数量与名称来自 `pyproject.toml`，不应被解释为每种功能都在每次运行时必需。按功能拆分的可选依赖组、操作系统兼容表和离线安装流程，官方仓库未提供该信息，建议以最新 README 为准。

快速开始

当前资料足以确认 Python 版本要求、uv 的使用线索以及 `fcc-doctor` 命令入口，但没有提供可核验的完整安装命令、服务启动参数和验证输出。为避免把猜测包装成可执行步骤，下面列出能确认的最小闭环边界，以及需要从最新 README 补齐的部分。

已确认的运行环境检查

python --version
uv --version

第一条命令用于查看当前 Python 版本，项目声明要求 `3.14.10`；第二条命令用于确认 uv 命令可用。该检查不会安装项目或启动服务，uv 的版本要求没有出现在所给资料中。

安装、运行与验证的资料边界

uv pip install -e .
fcc-server
fcc-doctor

上面的安装命令虽然采用了常见的 uv 用法，但所给 README 摘录没有给出它，因此不能将其视为经资料核验的官方安装步骤；同样，资料也没有说明 `fcc-server` 是否可直接无参数启动。此代码块仅展示包元数据中真实登记的命令名称，不应在生产或敏感环境中直接执行，完整且安全的安装与启动流程应以最新 README 为准。

包配置确认存在 `fcc-server` 和 `fcc-doctor` 两个入口，但没有提供健康检查地址、预期诊断输出或退出码，因此无法构造完整的“安装—运行—验证”官方最小示例。请先从仓库 README 获取安装命令、启动参数和验证标准；在这些信息缺失时，不要猜测端口、服务地址或凭据变量。

配置说明

所给资料没有包含 `.env.example`、完整配置章节或服务配置样例。为明确区分已知与未知，下面的表格只列出 `pyproject.toml` 中实际存在的项目元数据和依赖约束；这些字段不是运行时配置项，表格不会将它们伪装成环境变量或服务器参数。

依赖约束中的版本下限来自 `pyproject.toml`，例如 `fastapi[standard]>=0.141.1` 和 `openai>=3.37.0`；它们不是项目运行时配置项，也不表示安装时恰好使用该版本。确切解析结果取决于安装环境与锁定文件，而所给资料没有包含锁文件内容。

不要据此自行创建环境变量名称或假定服务默认端口。认证、缓存、日志级别、数据库路径、代理设置与提供方选择配置均需查阅当前仓库文档。

进阶用法

进阶使用首先应围绕已声明的命令入口和目标客户端展开，而不是猜测命令参数。包配置中有多个独立 launcher，表明客户端适配以命令入口形式暴露；各入口是否负责安装客户端、修改其配置或仅启动进程，资料没有说明。

按客户端选择入口

用户可先依据正在使用的客户端，查阅 README 对应集成说明，再决定是否使用相应 `fcc-*` 命令。`pyproject.toml` 中可见 `fcc-claude`、`fcc-codex`、`fcc-pi` 和 `fcc-opencode` 等名称，但完整的客户端清单与参数文档未包含在所给摘录中。

多模型工作流

README 将统一模型目录和多客户端使用列为项目目标。对于需要在不同任务间切换模型的工作流，应先确认目录中模型的来源、限额与客户端兼容性，再测试实际任务；资料未提供自动路由条件、模型优先级、回退策略或并发行为。

浏览器与语音入口

项目描述提到从浏览器使用原生会话，并提及语音支持，但没有给出具体安装或连接步骤。团队在启用相关入口前，应确认浏览器会话所需的授权范围、数据处理方式及可关闭机制；这些实现细节在当前资料中无法核实。

对部署脚本、团队共享配置或自动化任务，建议将经过 README 核验的命令和参数固定在受控环境中。该建议属于根据本文作者的经验判断，不是仓库对部署方式的承诺。

可观测性与运维

依赖清单包含 Loguru，README 也将其标为日志工具；这能证明项目采用了该日志依赖，但不能确定日志字段、输出位置、轮转策略或敏感信息脱敏规则。运营环境应先通过源码和实际运行结果核对日志行为，再制定留存周期与访问权限。

包提供 `fcc-doctor` 诊断入口，适合作为排查流程的起点；诊断覆盖范围和输出契约没有在资料摘录中说明。运行结果应结合当前 README 的解释，不宜把命令存在本身当作所有依赖和提供方都已连通的证明。

• 部署前记录 Python 版本、安装来源和项目版本；动态版本构建方式来自 `pyproject.toml`。
• 验证客户端是否连接到预期代理和模型时，应使用项目文档提供的验证步骤，所给资料没有给出可用的健康检查端点。
• 排查外部模型不可用时，应分别核对客户端配置、提供方状态、账户权限与配额；这一排查顺序是根据本文作者的经验判断。
• 升级前应确认新版本的依赖变化和兼容说明；当前材料没有列出发布记录或升级策略。

仓库摘录没有提供服务指标、追踪系统、告警规则、备份恢复流程或 SLA。需要这些能力的团队应自行评估并补齐运维控制，不应将日志库或诊断命令等同于完整可观测性体系。

安全与合规边界

该项目会连接模型提供方及编程客户端，并可能涉及账号凭据、提示内容、代码片段和浏览器会话，因此安全评估应覆盖本地代理、客户端和外部提供方三个边界。以下内容只适用于有权使用的账户、设备和数据，不涉及规避提供方限制或绕过检测的方法。

“FCC follows provider terms and removes integrations if they stop being allowed.”

来源：README

README 将遵守提供方条款与移除不再允许的集成作为项目原则。用户仍需自行阅读提供方当前条款，确认账户是否允许自动化或特定客户端接入；项目描述不能替代用户与服务提供方之间的授权关系。

• 仅在本人或组织授权的账户与设备上配置凭据，避免把密钥提交到代码仓库、日志或共享终端记录。
• 发送代码、提示词或业务数据之前，确认其分类要求及提供方的数据处理条款；资料没有给出数据保留或训练用途说明。
• 浏览器会话与语音功能的权限、会话持久化和数据流应以官方文档为准；当前摘录未披露其实现细节。
• 对需要隔离、审计或禁止外传的工作负载，应先确认项目及所选提供方满足组织控制要求，不能仅凭“本地代理”推断所有数据都留在本机。

“ToS-friendly”是 README 的项目表述，不构成法律意见或对所有地区、账户、提供方和使用场景的合规保证。若某个提供方的条款或组织政策不允许相关接入，应停止使用该接入方式并以适用规则为准。

许可证与商用条款

仓库的 LICENSE 文件标明 GNU Affero 通用公共许可证第三版（GNU Affero General Public License version 3，AGPL-3.0-only），版权行写有 Copyright (c) 2026 Ali Khokhar。`pyproject.toml` 的 `license` 字段也标注 `AGPL-3.0-only`，两处信息一致。

AGPL-3.0-only 并不以禁止商业使用为前提；许可证文本允许复制、分发、修改并收费，但分发或提供网络服务等情形的具体义务应按 LICENSE 完整条文判断。修改、分发和网络交互场景可能触发源码提供等条件，本文不替代法律意见，实际使用应以仓库 LICENSE 为准。

• 保留版权与许可证声明，并遵守适用的分发条件。
• 若修改后分发或通过网络向用户提供服务，仔细核对 AGPL 第三版对应义务。
• 第三方依赖具有各自许可证；所给资料未列出完整依赖许可证清单，不能据此推定所有依赖条款相同。

GitHub 元信息摘要中出现的许可证字段为 `NOASSERTION`，但仓库所给 LICENSE 和包配置明确写明 AGPL-3.0-only。遇到元数据与许可证文件表达不一致时，应以实际 LICENSE 文本及权利人后续说明为准。

局限性与已知限制

当前提供的资料以 README 开头、许可证和部分包配置为主，并非完整文档集。能够确认项目方向和若干入口，但不足以核实部署参数、全部提供方、兼容矩阵、浏览器数据流或运维指标。

• “61 个提供方”和“每月超过 13 亿免费令牌”来自 README 的项目声明，资料没有给出统计口径、配额分布或独立核验结果。
• README 摘录只列出若干客户端名称，包配置也只展示了部分入口，无法据此列出全部 12 个智能体。
• 项目要求精确 Python 版本 `3.14.10`，环境不匹配时的兼容处理方式未提供。
• 包依赖清单较长，但所给资料没有说明哪些依赖属于可选功能、哪些是启动服务所必需。
• 性能基准、最大并发、可用性保证、故障恢复和安全审计结果均未提供。

这些边界不等同于项目不存在相关能力，只表示当前资料不足以作出可核验结论。需要据此做生产决策时，应直接检查仓库最新 README、源码、发布信息与具体提供方条款。

适合谁 / 不适合谁

是否采用，应按客户端覆盖、模型供给、运行环境和组织合规要求判断，而不是仅看 Star 数或免费令牌宣传。下列信号依据仓库明确描述，并将尚未证实的运维能力单独排除。

适合进一步评估

• 团队正在使用 README 列出的 Claude Code、Codex、Pi 或 OpenCode 等客户端，并希望核对统一模型入口能否减少重复配置。
• 工作流允许在免费、付费、订阅及本地模型之间选择，且团队会逐项审查提供方条款与配额。
• 部署环境能够满足项目精确声明的 Python `3.14.10` 要求，并能按 README 处理安装与升级。
• 使用者愿意自行验证客户端适配、凭据保护和数据处理边界，而不是要求仓库摘录中未提供的 SLA 或审计证明。

不适合直接采用

• 生产系统必须具备已确认的 SLA、性能基准、最大并发保证或正式支持承诺，而这些材料当前未提供。
• 组织禁止代码或提示词传给外部模型服务，且没有经批准的本地模型与隔离方案。
• 运行平台无法满足 Python `3.14.10`，且团队没有验证兼容性和依赖安装的时间窗口。
• 团队需要确定的固定免费额度或长期模型供应，不能接受提供方配额和政策变化。
• 项目必须公开完整的数据流、浏览器会话持久化细节或第三方处理清单，而当前资料尚未提供这些信息。

常见问题与排查（FAQ / Troubleshooting）

排查时先区分环境、入口、客户端和提供方问题，再对照最新 README 确认参数。下面只回答资料能够支持的问题；未提供的接口和默认值不以猜测补齐。

项目要求什么 Python 版本？

`pyproject.toml` 写明 `requires-python = "==3.14.10"`。先确认解释器版本与此约束一致；其他 Python 版本是否可运行，官方仓库未提供该信息，建议以最新 README 为准。

服务默认监听哪个端口？

所给资料没有提供默认端口、监听地址或覆盖方式。不要自行假定常见端口，也不要将未经核验的地址用于防火墙规则；请以当前 README 或源码配置为准。

如何检查安装后的命令入口？

`pyproject.toml` 声明了 `fcc-server` 和 `fcc-doctor`，以及多个客户端 launcher。具体参数、输出和诊断项目未提供；遇到命令不可用时，先检查安装是否完成、虚拟环境是否已激活，再核对 README 的安装步骤。

为什么某个模型无法调用？

README 所称的提供方数量不代表每个账户都拥有相同权限或额度。检查所选提供方是否仍在支持范围内、账户授权是否有效，以及当前提供方条款是否允许该接入；项目没有在所给资料中承诺模型持续可用。

如何验证代理是否正常工作？

仓库提供 `fcc-doctor` 入口，但没有给出预期输出、健康检查接口或退出码。应按最新 README 解读诊断结果，并使用文档指定的客户端验证流程；不要把服务进程启动成功等同于上游模型请求成功。

许可证能否用于商业项目？

许可证标识为 AGPL-3.0-only，商业使用并非仅因收费而当然禁止；分发和网络服务场景的义务须按 LICENSE 全文核对。具体项目合规判断以仓库 LICENSE 为准，必要时咨询法律专业人士。

项目地址与资源

核对安装、客户端适配、提供方清单和配置前，应以仓库当前版本的官方资料为准。以下仅列出资料中出现的项目仓库及官方站点。

• free-claude-code GitHub 仓库
• Claude Code 官方文档
• OpenAI Codex GitHub 仓库
• Python 官方下载页面
• uv GitHub 仓库
• 项目 Pytest 工作流
• Ty 项目页面
• Loguru GitHub 仓库