一天一个开源项目（第84篇）：free-claude-code —— 零费用运行 Claude Code 的代理黑魔法

冬奇Lab2026-04-27 22:43

引言

"当工具太贵，程序员就会造一把更便宜的钥匙。"

这是"一天一个开源项目"系列的第 84 篇文章。今天带你了解的项目是 free-claude-code ，一个在 GitHub 上以爆炸速度走红的 Python 代理项目，短短数周便积累了超过 14,000 颗星，一度登上 GitHub Trending 榜首。

Claude Code 是 Anthropic 推出的 AI 编程智能体，深度集成在终端和 VSCode 中，能够自主读取文件、修改代码、执行命令------但它需要真实的 Anthropic API Key，费用不低。free-claude-code 的核心洞察极其简单却异常有效：Claude Code 本质上只是一个调用 Anthropic Messages API 的客户端，只要有一个兼容的代理服务器在本地拦截这些请求，再转发给任何支持 OpenAI/Anthropic 格式的免费或低价后端，Claude Code 就完全感知不到差异。

你将学到什么

  • 代理拦截原理 ：如何通过修改 ANTHROPIC_BASE_URL 环境变量重定向 API 请求
  • 多后端接入方案：NVIDIA NIM 免费额度、OpenRouter 免费模型、本地 Ollama/LM Studio 的完整配置
  • API 格式转换：OpenAI Chat Completions 与 Anthropic Messages 格式之间的适配技巧
  • Thinking Token 支持 ：如何将开源模型的 <think> 推理标签转换为 Claude 原生思考块
  • Bot 自动化：通过 Discord/Telegram 远程驱动 Claude Code 执行编程任务

前置知识

  • 熟悉终端基本操作和环境变量
  • 了解 Claude Code 的基本使用方式
  • 对 REST API 和 HTTP 代理有基本认知（可选）

项目背景

项目简介

free-claude-code 是一个运行在本地的 HTTP 代理服务器，使用 FastAPI 构建，专门模拟 Anthropic API 接口。当 Claude Code 发出 API 请求时，代理接收请求、进行格式转换、路由至配置的免费后端，再将响应转换回 Anthropic 格式返回给 Claude Code------全程对 Claude Code 客户端完全透明。

项目的命名直接、暴力、精准：free-claude-code，就是免费运行 Claude Code。

作者介绍

  • 作者：Ali Khokhar（GitHub ID: Alishahryar1）
  • 位置：美国加利福尼亚州 Sunnyvale
  • 自我介绍："Writing easily understandable code..."（写易懂的代码）
  • 背景：个人开发者，在 free-claude-code 爆红之前 GitHub 上几乎没有引人注目的项目（其他两个 pinned 项目分别只有 3 颗星），这是一次典型的"一鸣惊人"
  • GitHub 成就：Starstruck ×4、Pair Extraordinaire ×2、Pull Shark ×2 等，显示出活跃的开源参与

项目数据

  • ⭐ GitHub Stars：14,300+（4 月单月新增超 10,700 颗星）
  • 🍴 Forks：2,000+
  • 👥 Contributors：22 人
  • 📄 License：MIT
  • 🌐 仓库地址：github.com/Alishahryar...
  • 📈 趋势：4 月 24--27 日连续登顶 GitHub Trending Python 榜和全站榜

主要功能

核心作用

free-claude-code 解决了一个具体痛点：Claude Code 的高昂 API 费用。通过在本地起一个代理，将 Claude Code 的 Anthropic API 调用无缝重定向至以下免费或极低成本的后端：

  • NVIDIA NIM：免费额度每分钟 40 次请求，可用模型包括 GLM-4、Llama 3、Mistral 等
  • OpenRouter：汇聚 580+ 模型，许多模型有每日免费额度
  • DeepSeek：价格极低，原生支持 Anthropic Messages 格式
  • 本地模型：LM Studio、llama.cpp、Ollama 全支持，完全离线，零边际成本

使用场景

  1. 个人学习与实验

    • 学生或独立开发者想体验 Claude Code 的终端编程智能体功能，但无力承担 Anthropic API 费用

  2. 模型横向对比

    • 通过 MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 变量，将 Claude Code 的不同"模型层级"分别路由至不同后端，同一界面下对比 GPT-4o、Gemini、Llama 等的编码能力

  3. 离线编程助手

    • 配合 Ollama + Qwen2.5-Coder 或 DeepSeek-Coder-V2，在无网络环境中运行完整的 Claude Code 工作流

  4. 远程自动编程

    • 通过 Discord/Telegram Bot 接口，在手机上发送指令，让远端服务器的 Claude Code 自主完成编程任务

  5. 团队低成本 AI 协作

    • 内网部署代理 + Ollama，让团队成员共享同一本地模型服务，无需每人申请 API Key

快速开始

bash 复制代码 
# 1. 克隆仓库
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

# 2. 复制配置文件
cp .env.example .env

# 3. 编辑 .env，填入免费 API Key（以 NVIDIA NIM 为例）
# NVIDIA_NIM_API_KEY=nvapi-xxxx
# MODEL_OPUS=nvidia_nim/nvidia/llama-3.1-nemotron-ultra-253b-v1
# MODEL_SONNET=nvidia_nim/nvidia/llama-3.3-70b-instruct
# MODEL_HAIKU=nvidia_nim/meta/llama-3.1-8b-instruct

# 4. 启动代理服务器（需要先安装 uv: pip install uv）
uv run uvicorn server:app --host 0.0.0.0 --port 8082

# 5. 在另一个终端，通过代理运行 Claude Code
ANTHROPIC_BASE_URL="http://localhost:8082" claude

就这样------Claude Code 已经在通过免费的 NVIDIA NIM 接口运行，不需要 Anthropic API Key，也不产生任何费用。

核心特性

  1. 零侵入接入

    • 只需设置 ANTHROPIC_BASE_URL 环境变量，不修改 Claude Code 任何源码或配置文件

  2. 6 大后端支持

    • NVIDIA NIM、OpenRouter、DeepSeek、LM Studio、llama.cpp、Ollama，覆盖云端免费额度和本地全离线两条路线

  3. 按模型分级路由

    • 可独立配置 Opus/Sonnet/Haiku 对应的后端模型，精细控制请求分发

  4. Thinking Token 转换

    • 自动将开源模型输出中的 <think>...</think> 推理标签转换为 Claude 原生的 thinking 内容块，保持前端体验一致

  5. 智能限速

    • 内置主动节流（Proactive Throttling）+ 反应式退避（Reactive Backoff），自动应对免费 API 的速率限制

  6. Discord / Telegram Bot

    • 内置机器人接口，支持远程发送编程指令、查看实时输出、持久化会话状态

  7. 语音输入（实验性）

    • 通过 Whisper 模型支持语音转文字输入，配置 VOICE_NOTE_ENABLED=true 开启

  8. 本地优化拦截

    • 对部分微小 API 调用（如心跳检测、简单判断）在代理层本地响应，节省宝贵的免费配额

项目优势对比

对比维度 free-claude-code 直接付费使用 Claude Code 其他替代 CLI（如 Aider、OpenCode）
使用成本 免费（NVIDIA NIM / 本地） $5-200+/月 取决于后端 API
保留 Claude Code UX ✅ 完整保留 ✅ ❌ 不同界面
多后端切换 ✅ 6 种后端 ❌ 仅 Anthropic ✅（部分支持）
本地离线支持 ✅ Ollama/llama.cpp ❌ ✅（部分）
安装复杂度 中等（需配置代理） 简单 简单到中等
模型质量 取决于后端模型 顶级（Claude 3.5/3.7） 取决于后端模型

项目详细剖析

架构设计：透明代理模式

free-claude-code 的架构可以用一句话概括：在 Claude Code 和真实 API 之间插入一个格式翻译层。

bash 复制代码 
Claude Code CLI/VSCode
        │
        │ HTTP POST /v1/messages  (Anthropic API 格式)
        ▼
┌─────────────────────────────────┐
│     free-claude-code Proxy      │
│  ┌────────────────────────────┐ │
│  │  FastAPI Router            │ │
│  │  ┌──────────────────────┐  │ │
│  │  │ 请求解析 & 模型路由  │  │ │
│  │  └──────────┬───────────┘  │ │
│  │             │               │ │
│  │  ┌──────────▼───────────┐  │ │
│  │  │ 格式转换层           │  │ │
│  │  │ Anthropic → OpenAI   │  │ │
│  │  │ 或直接 Anthropic 透传│  │ │
│  │  └──────────┬───────────┘  │ │
│  │             │               │ │
│  │  ┌──────────▼───────────┐  │ │
│  │  │ 限速 & 重试管理      │  │ │
│  │  └──────────┬───────────┘  │ │
│  └─────────────┼───────────────┘ │
└────────────────┼─────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
NVIDIA NIM   OpenRouter   Ollama/本地
（免费）      （免费层）   （完全离线）

整个代理以 server.py 为入口，调用 api/app.py 中的 create_app() 工厂函数构建 FastAPI 应用。路由逻辑、格式转换、限速管理均封装在 api/ 模块下，实现关注点分离。

关键实现：API 格式转换

这是项目最核心的技术挑战。Anthropic Messages API 和 OpenAI Chat Completions API 在格式上存在显著差异：

Anthropic Messages 格式（Claude Code 发出的请求）：

json 复制代码 
{
  "model": "claude-opus-4-5",
  "max_tokens": 8096,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "帮我重构这段代码"},
        {"type": "tool_result", "tool_use_id": "xxx", "content": "..."}
      ]
    }
  ],
  "tools": [...],
  "thinking": {"type": "enabled", "budget_tokens": 5000}
}

OpenAI Chat Completions 格式（发往 NVIDIA NIM / OpenRouter）：

json 复制代码 
{
  "model": "nvidia/llama-3.1-nemotron-ultra-253b-v1",
  "messages": [
    {"role": "user", "content": "帮我重构这段代码"}
  ],
  "tools": [...],
  "stream": true
}

代理需要处理的转换点包括：

  • 多模态内容 ：将 Anthropic 的 content 数组（文本、图像、工具调用结果）拼接为 OpenAI 的字符串或对象格式
  • 工具调用 ：Anthropic tool_use 块 ↔ OpenAI function_call / tool_calls
  • 流式响应 ：将后端的 SSE 流转换为 Anthropic 的 event: content_block_delta 流格式
  • Thinking 块 ：将 <think> 标签提取为独立的 thinking 内容块

Thinking Token 支持

这是项目的一个亮点功能。部分开源模型（如 DeepSeek-R1、QwQ、GLM-Z1）在推理时会输出 <think> 标签包裹的思考过程。代理通过解析这些标签，将其映射为 Anthropic 的原生 thinking 内容块：

python 复制代码 
# 伪代码示意
if "<think>" in model_output:
    thinking_content = extract_between_tags("<think>", "</think>", model_output)
    response["content"].insert(0, {
        "type": "thinking",
        "thinking": thinking_content
    })

这样，Claude Code 的前端界面（包括 VSCode 扩展的思考过程折叠显示）能够完整呈现开源模型的推理链。

智能限速机制

NVIDIA NIM 免费层限制为每分钟 40 次请求，这对 Claude Code 频繁的 API 调用来说很容易触发。项目实现了双层防护：

  1. 主动节流（Proactive）：在发出请求前，根据已知速率限制预判下一次请求的可行时间窗口，主动等待
  2. 反应式退避（Reactive） ：收到 429 Too Many Requests 响应后，解析 retry-after 头或使用指数退避策略重试
  3. 并发控制 ：通过 PROVIDER_MAX_CONCURRENCY 环境变量限制同时进行的请求数

Discord/Telegram Bot 模式

这是 free-claude-code 区别于纯代理项目的独特功能。在 Bot 模式下，项目不仅转发 API 请求，还管理 Claude Code 的完整生命周期：

css 复制代码 
手机 Telegram/Discord 消息
        │
        ▼
Bot Token 接收消息
        │
        ▼
启动 Claude Code 子进程（CLAUDE_WORKSPACE 目录）
        │
        ▼
实时将输出流转发回聊天窗口
        │
        ▼
会话持久化（session persistence）

这使得用户可以在手机上给"远程编程助手"发指令，Claude Code 在服务器上自主完成任务，执行结果实时推送到 Telegram。

环境变量配置体系

项目通过 .env 文件实现高度灵活的配置，关键变量分组如下：

bash 复制代码 
# === 后端选择（三选一或组合使用）===
NVIDIA_NIM_API_KEY=nvapi-xxxxx          # NVIDIA NIM 免费额度
OPENROUTER_API_KEY=sk-or-xxxxx          # OpenRouter（580+ 模型）
DEEPSEEK_API_KEY=sk-xxxxx               # DeepSeek（极低价格）
OLLAMA_BASE_URL=http://localhost:11434  # 本地 Ollama（完全免费）

# === 模型分级路由 ===
MODEL_OPUS=nvidia_nim/nvidia/llama-3.1-nemotron-ultra-253b-v1
MODEL_SONNET=nvidia_nim/nvidia/llama-3.3-70b-instruct
MODEL_HAIKU=nvidia_nim/meta/llama-3.1-8b-instruct

# === Thinking 支持 ===
ENABLE_SONNET_THINKING=true
ENABLE_OPUS_THINKING=true

# === 限速配置 ===
PROVIDER_RATE_LIMIT=1           # 每秒最大请求数
PROVIDER_MAX_CONCURRENCY=5      # 最大并发数

# === Bot 配置（可选）===
MESSAGING_PLATFORM=telegram
TELEGRAM_BOT_TOKEN=xxxxx
ALLOWED_TELEGRAM_USER_ID=123456789

局限性与注意事项

使用 free-claude-code 前，有几个重要的现实情况需要了解：

1. 模型质量差异是根本矛盾

free-claude-code 提供的是 Claude Code 客户端体验，而非 Claude 模型本身。免费后端的模型（如 Llama 3、GLM-4）在复杂代码推理、多步骤任务规划、指令遵循稳定性上，与 Claude Sonnet/Opus 存在明显差距。一位 YouTube 评测者的总结很准确："Simply wrapping Claude application layer around native open LLMs will not produce the same quality output."

2. NVIDIA NIM 免费额度有限制

40 req/min 的免费配额在 Claude Code 的激进请求模式下（频繁发送上下文、工具调用等）会较快耗尽，导致请求暂停等待。实际编程体验可能出现明显的"卡顿感"。

3. 工具调用的格式兼容性问题

Claude Code 深度依赖结构化的工具调用（文件读写、bash 执行、搜索等）。开源模型在工具调用的稳定性和格式规范性上参差不齐，可能出现工具调用失败、响应解析错误等问题。项目已有"启发式工具解析"作为兜底，但并非 100% 可靠。

4. 不支持 Claude 专属能力

以下 Claude Code 依赖的 Anthropic 专属功能无法通过代理实现：

  • Anthropic 的计算机使用（Computer Use）功能
  • 真实的扩展思考（Extended Thinking，即深度推理模式）
  • 最新 Claude 模型的训练数据和安全护栏

5. 本地模型对硬件要求较高

若选择 Ollama/LM Studio 路线运行高质量编码模型（如 Qwen2.5-Coder-32B），需要至少 20-24GB VRAM，普通消费级显卡可能无法流畅运行。

社区反响

free-claude-code 在开源社区引发了强烈共鸣，尤其是在 Reddit 的 r/ClaudeCode、r/ClaudeAI、r/LLMDevs 等社区：

  • r/StartupMind 有帖子写道："Someone just built a proxy that runs Claude Code completely free... and it's wild."
  • r/ZaiGLM 和 r/LLMDevs 多个帖子讨论了将 NVIDIA NIM 上的 GLM-5 与该代理结合使用的完整流程
  • YouTube 上出现了多个"Claude Code is now FREE"系列视频，其中一个标题为《free-claude-code --- The 7,900-Star Hack That's Not What It Seems》，提醒用户注意模型质量差距
  • 项目本身在 4 月活跃度极高：单月 52 个 Issue、16 个合并 PR

社区中出现的衍生项目也印证了其影响力：Rishurajgautam24/free-claude-code 是该仓库的直接 Fork，free-coding-models 等 TUI 工具也引用了相关思路。

同类项目对比

项目 核心思路 与 free-claude-code 的区别
openclaw Claude Code 替代 CLI 独立实现，不依赖官方 Claude Code 客户端
Aider 独立 AI 编程 CLI 成熟稳定，直接接多后端，不模拟 Claude Code
OpenCode 另一款终端 AI 编程工具 支持多模型，原生设计而非代理模式
free-claude-code API 代理层 保留完整 Claude Code UX，仅替换后端

free-claude-code 的独特价值在于：它让已经熟悉 Claude Code 工作流的用户无需重新学习任何新工具，只需改变一个环境变量，即可将成本降至零。

项目地址与资源

官方资源

相关资源

总结与展望

核心要点回顾

  1. 核心洞察极其简单 ：Claude Code 是 Anthropic API 的客户端，修改 ANTHROPIC_BASE_URL 即可重定向至任何兼容代理
  2. 技术门槛适中：真正的工程挑战在于 Anthropic ↔ OpenAI API 格式转换、流式响应处理、工具调用适配
  3. "免费"有代价：节省了 API 费用，但牺牲了模型质量；NVIDIA NIM 免费额度会带来速率限制
  4. 社区生命力旺盛：14k+ 星、22 位贡献者、活跃的 Issue 讨论，项目仍在快速迭代

适用人群

  • 学生/爱好者：想体验 Claude Code 工作流，但没有预算支付 API 费用
  • 模型研究者：想对比不同开源模型在 Claude Code 界面下的编码能力
  • 企业内网部署：配合 Ollama 实现完全私有化、离线运行的 AI 编程助手
  • 远程编程爱好者：利用 Telegram/Discord Bot 功能，随时随地遥控服务器上的编程任务

给读者的建议

如果你的主要目标是高质量的 AI 编程辅助 ，免费代理可以作为入门体验，但生产环境还是建议使用真实的 Claude Sonnet 或 Opus。如果你的目标是探索开源模型的极限 ，或者学习 API 代理的工程实现，那么 free-claude-code 是一个设计简洁、代码可读性高、值得深入研究的优秀项目。

这个项目的走红，本质上是开源社区对高质量 AI 工具民主化的一次集体呼声------让好工具不只属于付得起账单的人。

访问我的个人网站，探索更多实用知识和有趣产品

相关推荐
泡泡茶壶ᐇ2 小时前
个人网站构建完全指南：从功能规划到技术实现与AI辅助开发
人工智能
cyyt2 小时前
深度学习周报（4.20~4.26)
人工智能·深度学习
Java小生不才3 小时前
spring AI文生图
java·人工智能·spring ai
罗西的思考3 小时前
【OpenClaw】通过 Nanobot 源码学习架构---（10）Heartbeat
人工智能·机器学习
IT_陈寒3 小时前
我竟然被JavaScript的隐式类型转换坑了三天！
前端·人工智能·后端
love530love3 小时前
Clink 调校指南：让 Windows CMD 拥有现代终端的便捷体验
人工智能·windows·python·cmd·clink
FrontAI7 小时前
深入浅出 LangGraph —— 第6章：工具调用与ToolNode
人工智能·langchain·ai agent·langgraph
前端DOM哥7 小时前
8 年前的老代码 + 20 刀 AI token = 我的第一款独立产品
前端·人工智能·架构
热门推荐
01GitHub 镜像站点02近期有什么ai的新消息，新动态？ 2026.4月032026年4月AI大事件深度解读：大模型竞争进入“深水区“042026年AI前瞻：量子AI、具身智能与科学发现的新纪元05在Windows 11上安装Docker的踩坑记录06codex app每次打开重连5次Reconnecting问题解决072026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元08Codex 接入 DeepSeek API 完整配置文档092026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot10DeepSeek V4 全面解析：测评、对比、案例及实操指南