Free Claude Code（FCC）：让 11 个编码 Agent 用上 61 家供应商、每月 13 亿+ 免费 Token 的本地智能代理｜部署与使用全指南

适用版本：基于官方仓库 Alishahryar1/free-claude-code 2026 年 10 月的最新稳定版（v6.x 系列）撰写。项目当前高度活跃（1200+ commits、62k+ stars），本文所有命令均来自官方 README 与官方安装脚本。

Free Claude Code（下文简称 FCC）是一个运行在本地的智能代理服务器：它不训练模型、不开发 Agent，而是充当「转接头」——你的编码 Agent 仍然按 Anthropic Messages 协议说话，FCC 在本地端口拦截请求，做协议翻译与路由，再转发给你选定的 61 家模型供应商（NVIDIA NIM、OpenRouter、Groq、Google AI Studio、DeepSeek、硅基流动、Ollama 本地模型等）。

一、项目介绍与适用场景

1.1 它解决什么问题

2026 年的编码智能体（Claude Code、Codex、OpenCode、Cline 等）体验已经非常成熟，但存在三重痛点：

痛点	具体表现	FCC 的解法
成本高	重度使用一个复杂任务就能烧掉几十上百美元 API 费	聚合 61 家供应商的免费额度，每月 13 亿+ 免费 Token
可用性差	单一供应商限流、宕机会打断整轮工作	重试耗尽后自动切换到下一个已配置模型，无需重启回合
迁移成本高	换模型往往意味着换掉整套工作流	11 个 Agent 共享同一个模型目录，会话中随时切换

1.2 适用人群

学生 / 独立开发者 / 爱好者：没有公司预算，想零成本用上顶级编码 Agent。
多 Agent 重度用户：同时使用 Claude Code、Codex、Aider 等多个工具，想统一管理模型目录。
注重账号安全的人：FCC 明确遵循各供应商服务条款（ToS-friendly），一旦某集成不再被允许就移除它，不冒封号风险。
本地模型玩家：Ollama、LM Studio、llama.cpp 的本地模型可以直接接入全部编码 Agent。

1.3 不适合的场景

需要商用 SLA 保障的生产级服务（免费额度由各供应商控制，随时可能变化）。
无法接受代码请求经过第三方供应商网络的环境。

二、核心功能逐条拆解

61 家 ToS 友好供应商，每月 13 亿+ 免费 Token：免费、付费、订阅、本地模型统一在一个可搜索的 UI 里管理，不拿主账号冒险。
12 个编码 Agent，一个模型目录：Claude Code、Codex、Pi、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build、Muse Code、Aider、Antigravity CLI、VS Code Chat 全部共享同一份模型目录。
供应商宕机不断线：重试耗尽后自动 fallback 到下一个已配置模型，对所有客户端生效。
Token 用量最高降 90%：可选 RTK 过滤常见命令输出、Headroom 压缩工具结果；FCC 内置 5 项优化（配额探测、命令前缀识别、标题、建议、文件路径）完全不调用供应商。
浏览器原生 Code 会话：在 FCC 的浏览器 UI 里选一个文件夹直接跑 Codex，支持实时与后台任务，同一会话内自由切换供应商/模型。
终端、桌面、IDE、手机全端覆盖：原生启动器、VS Code、Codex App、JetBrains、Discord、Telegram 都能接入。
语音输入，代码输出：本地 Whisper 或 NVIDIA NIM 转写，动口不动手。
Agent 能力零损失：流式响应、工具调用、原生交错思考（interleaved thinking）、图片输入全部保留；Fable/Opus/Sonnet/Haiku 四个层级可独立路由到不同模型。

三、全套官方链接

资源	链接
GitHub 仓库	https://github.com/Alishahryar1/free-claude-code
问题反馈 / 功能请求	https://github.com/Alishahryar1/free-claude-code/issues
贡献指南	https://github.com/Alishahryar1/free-claude-code/blob/main/CONTRIBUTING.md
许可证（AGPL-3.0-only）	https://github.com/Alishahryar1/free-claude-code/blob/main/LICENSE
NVIDIA NIM API Key 申请	https://build.nvidia.com/settings/api-keys
OpenRouter Key	https://openrouter.ai/keys
Groq Key	https://console.groq.com/keys
Google AI Studio (Gemini) Key	https://aistudio.google.com/apikey
DeepSeek Key	https://platform.deepseek.com/api_keys
硅基流动 SiliconFlow Key	https://cloud.siliconflow.com/account/ak
Claude Code 官方文档	https://code.claude.com/docs/en/overview
Codex 仓库	https://github.com/openai/codex

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

四、硬件与环境前置要求

4.1 系统与软件

项目	要求
操作系统	Windows 10/11、macOS（Apple Silicon/Intel）、主流 Linux 发行版
Python	3.14（安装脚本会自动通过 uv 管理版本，无需手动安装）
包管理器	uv（安装脚本自动装）
磁盘空间	≥ 2 GB（FCC 本体 + 依赖；启用本地 Whisper 另需 1–10 GB 模型空间）
网络	能访问 GitHub 与所选供应商 API；国内建议配置代理

4.2 硬件

FCC 本体只是一个代理转发层，本身不跑模型，对硬件几乎没有要求：

CPU：任意双核以上即可。
内存：2 GB 以上。
GPU：不需要。只有启用「本地 Whisper 语音转写（CUDA）」时才需要 NVIDIA GPU（CUDA 13.0）；CPU 模式跑 Whisper 也可以。
本地模型（可选）：如果通过 Ollama/LM Studio 接本地大模型，显存/内存需求取决于该模型本身，且要预留足够上下文窗口容纳 Agent 的系统提示词与工具定义。

五、多平台部署（Windows / macOS / Linux / 源码 / Docker）

5.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 Code / Codex / Aider 等，可多选，后续可补装）。
是否启用 RTK + Headroom Token 优化（针对支持的 Agent，建议启用）。

5.2 启动 FCC

平台	启动方式
Windows	从桌面或开始菜单打开 Free Claude Code；托盘图标可打开 Admin、重启或退出
macOS	从桌面或「应用程序」文件夹打开；菜单栏图标同上
Linux	终端运行 `fcc-server`（保持终端开启）

启动后 FCC 会打印 Admin UI 的 URL（本地回环地址，当前版本默认端口为 8082，以日志输出为准），浏览器打开即进入管理界面。

5.3 源码安装（开发者方式）

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
# 使用 uv 创建环境并安装（Python 3.14）
uv sync
uv run fcc-server

安装 pytest 开发依赖后可运行官方测试套件（tests/、smoke/、e2e/）验证安装完整性。

5.4 Docker 部署（非官方变通方案）

⚠️ 官方没有提供 Docker 镜像。FCC 的设计是与编码 Agent 跑在同一台机器、同一用户环境（启动器要写入各 Agent 的配置），容器化会丢失桌面/IDE 集成能力。如确有需要，可将源码方式装进容器，仅把 fcc-server 的端口映射出来作为纯代理使用：

FROM python:3.14-slim
RUN apt-get update && apt-get install -y curl git && rm -rf /var/lib/apt/lists/*
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
RUN git clone https://github.com/Alishahryar1/free-claude-code.git /opt/fcc
WORKDIR /opt/fcc
RUN uv sync
EXPOSE 8082
CMD ["uv", "run", "fcc-server"]

docker build -t fcc .
docker run -d --name fcc -p 8082:8082 -v fcc-data:/root/.fcc fcc

强烈建议同时在 Admin 中开启 Proxy Authentication（Bearer Token），否则容器端口暴露后局域网内任何人都能用你的供应商 Key。

六、配置详解（Admin UI 全参数）

FCC 的所有配置都在本地 Admin UI 中完成，数据保存在 ~/.fcc/ 目录，无需手改配置文件。

6.1 Providers（供应商配置）

每个供应商一张卡片，支持编号 API Key（Add key 添加多把、拖拽排序，FCC 优先使用 Key 1）。核心供应商与设置项对照：

供应商	Admin 设置项	MODEL 示例
NVIDIA NIM	`NVIDIA_NIM_API_KEY`	`nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b`
OpenRouter	`OPENROUTER_API_KEY`	`open_router/openrouter/free`
Groq	`GROQ_API_KEY`	`groq/llama-3.3-70b-versatile`
OpenAI / ChatGPT 订阅	OAuth 连接（非 API Key）	`openai/<model-id>`
GitHub Copilot	OAuth 连接	`github_copilot/<model-id>`
Google AI Studio	`GEMINI_API_KEY`	`gemini/models/gemini-3.1-flash-lite`
Google Vertex AI	`VERTEX_PROJECT_ID` + ADC	`vertex/google/gemini-3.5-flash`
DeepSeek	`DEEPSEEK_API_KEY`	`deepseek/deepseek-chat`
Anthropic	`ANTHROPIC_API_KEY`	`anthropic/<model-id>`
Azure OpenAI	`AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL`	`azure_openai/<deployment-name>`
硅基流动	`SILICONFLOW_API_KEY`	`siliconflow/Qwen/Qwen3-32B`
Kimi API / Kimi Code	`KIMI_API_KEY` / `KIMI_CODE_API_KEY`	`kimi/kimi-k2.5` / `kimi_code/k3`
阿里云百炼	`ALIBABA_CLOUD_API_KEY`	`alibaba_cloud/<model-id>`
Z.ai	`ZAI_API_KEY`	`zai/glm-5.2`
Ollama（本地）	`OLLAMA_BASE_URL`	`ollama/<model-tag>`
LM Studio（本地）	`LM_STUDIO_BASE_URL`	`lmstudio/<model-id>`
llama.cpp（本地）	`LLAMACPP_BASE_URL`	`llamacpp/<model-id>`

关键配置规则：

模型 ID 前缀：MODEL 必须写成 <供应商前缀>/<模型ID> 格式，例如 nvidia_nim/...、ollama/llama3.1。Kimi 订阅 Key 用 kimi_code/、按量 Key 用 kimi/，二者不可混用；QwenCloud 的 Coding Plan（qwencloud_coding/）与 Token Plan（qwencloud/）同样不可互换。
自定义供应商：Providers → Custom providers → Add provider，填 API Base URL、可选 Key、API 格式；Model IDs 留空则自动发现。
OAuth 类供应商（ChatGPT 订阅、GitHub Copilot）：在 Providers → OAuth providers 里点 Connect 走浏览器登录，连完后重启正在运行的 Agent。
Vertex AI：不用 API Key，先 gcloud auth application-default login，再设 VERTEX_PROJECT_ID（可选改 VERTEX_LOCATION，默认 global）。
本地供应商：FCC 启动时自动发现已在运行的本地服务；后启动的服务点卡片上的 Refresh models / Test。

6.2 Model Config（模型路由）

MODEL：全局默认模型，是所有请求的兜底。
分层路由：MODEL_FABLE、MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 可单独覆盖 Claude Code 的四个请求层级（选 None 则回落到 MODEL）。
Fallback Models：有序回退列表，对全部客户端生效。每个回退项可单独设置推理力度（Inherit / Off / From client / Low / Medium / High / X-High / Max）和使用的 Key 编号。注意：一次失败请求可能连续消耗多家供应商的额度后才成功。

6.3 Reasoning Control（推理力度）

Admin UI → Model Config → Model Routing，按模型选择力度。Default Effort 默认 From client（尊重 Agent 发来的设置），四个 Claude 层级默认 Inherit。

6.4 Messaging（Discord / Telegram / 语音）

Discord：Developer Portal 建机器人 → 开启 Message Content Intent → 授予读取/发送/历史/管理消息权限（/clear 需要）→ 平台选 discord → 填 Bot Token、允许的频道、绝对路径的 Allowed Directory。
Telegram：@BotFather 建机器人 → @userinfobot 拿自己的数字用户 ID → 平台选 telegram → 填 Bot Token、Allowed Telegram User ID、Allowed Directory。
语音：默认内置 NVIDIA NIM 转写（需 NIM Key）；本地 Whisper 重跑安装脚本加 --voice-local（Windows -VoiceLocal），CUDA 13.0 再加 --torch-backend cu130，装完重启 fcc-server，在 Voice 里选 cpu 或 cuda 并挑 Whisper 模型。本地门控模型需要 HUGGINGFACE_API_KEY。

6.5 安全：Proxy Authentication

在 Admin 中启用 Proxy Authentication 后，本地代理会要求 Bearer Token，防止本机其他用户/局域网滥用你的 Key。把端口暴露到非回环地址时必开。

七、启动、后台常驻、开机自启与改端口

7.1 日常启动

fcc-server          # 前台启动（Linux），保持终端开启
fcc-server --version  # 只查版本不启动

Windows / macOS 用户直接用桌面启动器，启动器会自动拉起服务。

7.2 Linux 后台常驻 + 开机自启（systemd）

官方桌面启动器在 Linux 上不带自启。以下为通用 systemd 用户服务方案（把 YOURUSER 换成你的用户名，路径以 which fcc-server 实际输出为准）：

# ~/.config/systemd/user/fcc-server.service
[Unit]
Description=Free Claude Code local proxy
After=network-online.target

[Service]
ExecStart=/home/YOURUSER/.local/bin/fcc-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now fcc-server   # 启动并设为开机自启
journalctl --user -u fcc-server -f          # 看日志（Admin UI URL 在这里）

服务器（无桌面）场景必须在 loginctl enable-linger YOURUSER 后用户服务才能开机自启。

7.3 改端口 / 对外暴露

FCC 默认只监听本地回环（当前版本端口 8082，实际以启动日志打印的 Admin UI URL 为准；运行 fcc-server --help 可查看当前版本支持的启动参数）。要换对外端口或远程访问，推荐用 Nginx 反代而不是硬改监听：

server {
    listen 8443 ssl;
    server_name fcc.example.com;
    location / {
        proxy_pass http://127.0.0.1:8082;
        proxy_http_version 1.1;
        proxy_set_header Connection "";      # 支持流式响应
        proxy_buffering off;                  # SSE 必须关缓冲
        proxy_read_timeout 3600s;
    }
}

并在 FCC Admin 中开启 Proxy Authentication。

八、功能实操教程

8.1 首次跑通（NVIDIA NIM 为例，免费额度最足）

到 build.nvidia.com/settings/api-keys 创建 API Key。
浏览器打开启动日志里的 Admin UI URL。
Providers → NVIDIA NIM → Add key，粘贴 Key，Save。
MODEL 保持默认 nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b，或在模型下拉里搜索换一个。
点 Apply 保存模型选择。

8.2 启动编码 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
fcc-agy         # Antigravity CLI（先在 Integrations 页连接）

每个 fcc-* 启动器都会自动拉起 fcc-server（如果还没跑），并注入对应 Agent 所需的环境变量。Agent 内部用原生的 /model 选择器即可看到 FCC 模型目录：

8.3 会话中切换模型

直接在 Agent 原生 /model 选择器里换，或在浏览器 Admin UI 里改 MODEL 后按 Apply——同一会话内生效，无需重启回合。

8.4 浏览器原生 Code 会话

打开 Admin UI 的 Code 会话页 → 选择本地文件夹 → 直接跑 Codex，支持实时与后台任务、同会话换供应商/模型：

8.5 IDE / 桌面集成

装好客户端后，Admin UI → Integrations 点对应卡片 Connect，然后重载 VS Code 或重启应用：

Claude Code VS Code 扩展 / VS Code 内置 Chat
Claude Desktop（连接前必须完全退出；Disconnect 恢复正常登录）
Codex VS Code 扩展 / Codex App
JetBrains ACP（装 Claude Agent 并启动一次后连接，IDE 里选 Claude Code (FCC)；JetBrains 更新 Agent 后需重启 FCC）
DeepSeek Harness Desktop（先打开一次 App 再连接）

8.6 Discord / Telegram 远程遥控

按 6.4 配好后，在聊天里直接发任务，支持以下命令：

命令	行为
`/stats`	查看会话状态
独立 `/stop`	取消全部工作
回复某条消息 `/stop`	只取消选中的请求，队列里其他请求继续
独立 `/clear`	清空本聊天所有 FCC 会话
回复某条消息 `/clear`	只删除选中消息及其回复链

发语音条即可语音输入转代码（Whisper / NIM 转写）。

8.7 接入本地 Ollama 模型

ollama pull llama3.1
ollama serve        # 默认 http://localhost:11434

Admin → Providers → Ollama 卡片点 Refresh models，然后在 Model Config 选 ollama/llama3.1。建议选支持工具调用且上下文窗口足够大的模型（Agent 的系统提示词+工具定义本身就占不少 Token）。

九、全套报错与故障排查

9.1 万能第一步：fcc-doctor

fcc-doctor

它会收集版本、环境、连通性诊断信息。给官方提 issue 时必须附上它的输出。

9.2 安装阶段

报错/现象	原因与解决
`curl ... \\| sh` 卡住或 403	GitHub Raw 被墙/限流。换代理，或先 `wget` 脚本再本地执行
Python/uv 版本报错	删除旧的 uv 缓存重装脚本；确认系统架构（arm64/x86_64）
Windows 提示脚本无法执行	用官方给的 `irm` 一行式（ScriptBlock 方式），不要手动改 ExecutionPolicy
Agent 未出现在选择列表	安装时至少勾选一个 Agent；漏选就重跑安装脚本补选

9.3 启动阶段

报错/现象	原因与解决
端口被占用（8082 冲突）	`ss -ltnp \\| grep 8082` 找到占用进程；要么结束它，要么用 Nginx 换对外端口（见 7.3）
Admin UI 打不开	URL 以 `fcc-server` 日志打印为准；确认没把服务跑在远程机器而浏览器在本地访问回环地址
开机自启没生效	systemd 用户服务需 `loginctl enable-linger`；检查 `journalctl --user -u fcc-server`
浏览器会话/桌面集成失效	集成必须与 FCC 同一台机器、同一用户环境；更新客户端后按官方要求重启 FCC

9.4 供应商与模型

报错/现象	原因与解决
供应商卡片显示不可用	Key 填错或额度用尽；点 Test 重新检测；核对区域（如阿里云 Key 与 endpoint 必须同区域）
模型下拉里找不到目标模型	下拉只列已发现模型；可手动输入 `<供应商前缀>/<精确模型ID>`
Azure 选不到模型	部署名不在下拉时手动输入 deployment name；确认 `AZURE_OPENAI_BASE_URL` 是完整 v1 端点
本地模型回复质量差/工具失败	模型不支持工具调用或上下文窗口不够；换 tool-capable 模型并调大上下文
请求连续失败	检查 Fallback 列表顺序；一次失败请求可能已消耗多家供应商额度，去 `/stats` 核对
OAuth 连不上/突然失效	订阅类（ChatGPT/Copilot）登录过期，重新 Connect 并重启 Agent
Claude Desktop 断连后异常	Disconnect 恢复正常 Claude 登录；重连前完全退出 Claude Desktop

9.5 消息与语音

报错/现象	原因与解决
Telegram 机器人不响应	Allowed Telegram User ID 必须是数字 ID（@userinfobot 查询）；群组里要给机器人删消息权限
`/clear` 无效（Discord）	机器人缺少 Manage Messages 权限
语音转写失败	NIM 方案检查 NIM Key；本地 Whisper 确认用 `--voice-local` 重装并重启过 `fcc-server`，门控模型需 HUGGINGFACE_API_KEY

十、升级、回滚与卸载

10.1 升级

# 1. 停掉所有正在运行的 fcc-* 命令
# 2. 执行官方升级
fcc-update

fcc-update 会安装经过检查的稳定版及配套安装器。只想改选可选组件（如补装本地语音）时，直接重跑安装脚本并带参数：

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

Windows 上 Muse Code 可单独升级/卸载：install-muse.ps1 / uninstall-muse.ps1（卸载 FCC 不会动 Muse Code）。

10.2 回滚

官方未提供版本锁定命令。如需回滚：

cd free-claude-code            # 源码目录
git fetch --tags
git checkout v6.15.0           # 换回目标版本 tag
uv sync                        # 重装依赖
uv run fcc-server

~/.fcc/ 配置目录向前兼容一般没问题，但回滚前建议先备份该目录。

10.3 卸载

先停掉所有 FCC 命令并退出已连接的桌面/编辑器应用，然后：

# macOS / Linux
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh

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

会删除：FCC 本体、桌面启动器与全部 fcc-* 命令、~/.fcc/ 配置目录。 会保留：uv 和 Python、你安装的编码 Agent、RTK、Headroom。

十一、商用许可与合规风险提示

11.1 许可证

FCC 采用 GNU AGPL-3.0-only（2026-09 由原许可证切换而来）。这意味着：

自用、修改、内部部署完全自由。
修改后对外提供网络服务（哪怕只是公司内网），必须向使用者公开修改后的完整源码。
二次开发商用产品并集成 FCC 代码，整体需按 AGPL-3.0 开源，闭源商业集成需与版权方另谈商业授权。
"FCC 不打扰你原本的使用习惯" 与 AGPL 义务是两回事：只要你的服务用到了它的代码，开源义务就存在。

11.2 商标与归属

项目与 Anthropic 无隶属、无背书关系；Claude、Claude Code 是 Anthropic 的商标。商用宣传中不得暗示获得官方认证。

11.3 免费额度与 ToS 风险

免费额度由各供应商控制且可能随时变化，1.3B Token/月是各供应商免费额度之和，不是 FCC 承诺的 SLA。
FCC 主打 ToS-friendly：遵循供应商条款，集成一旦不被允许就移除。但使用方仍应自行阅读并遵守所用供应商的条款（例如 QwenCloud Coding Plan、Kimi Code 明确限定本地、个人、交互式编码用途）。
一次失败请求可能消耗多家供应商额度（Fallback 机制），核算成本时要注意。
不要把 FCC 当作规避付费的手段用于商业牟利宣传，供应商有权调整或终止免费额度。

11.4 数据隐私

FCC 本身运行在本地，但你的代码上下文、提示词会发送给你选择的供应商（云供应商即第三方网络）。涉密/敏感代码建议走 ollama/、lmstudio/、llamacpp/ 等本地前缀，数据不出本机。
启用 Proxy Authentication，避免本机/局域网他人冒用你的 Key 与额度。

附录：快速命令速查

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

# 启动与诊断
fcc-server          # 启动（Admin UI URL 看日志）
fcc-doctor          # 诊断，报 bug 必附
fcc-server --version

# Agent 启动器
fcc-claude / fcc-codex / fcc-pi / fcc-opencode / fcc-cline
fcc-hermes / fcc-dsh / fcc-grok / fcc-muse / fcc-aider / fcc-agy

# 维护
fcc-update          # 升级
# 卸载
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh

免责声明：本文为技术教程，免费额度与可用性以各供应商实际政策为准；请遵守所在地区法律法规及各服务商条款。