free-claude-code 是一个开源代理服务器，将 Claude Code 的 Anthropic API 请求转发至 NVIDIA NIM、OpenRouter、DeepSeek、Ollama 等替代服务商，让开发者无需订阅 Claude Pro 即可在终端、VS Code 和 JetBrains IDE 中完整使用 Claude Code 的编程能力。项目于 2026 年 5 月在 GitHub 获得超过 22,000 Star，单周新增 3,775 Star，是近期增长最快的 AI 开发工具之一。
free-claude-code 是什么，工作原理如何
free-claude-code 的本质是一个运行在本地的 API 代理层，拦截 Claude Code 发向 api.anthropic.com 的请求，并将其重定向至用户自行配置的后端服务商。
整个请求链路如下：
- Claude Code 向本地代理（默认
http://localhost:8082）发送 Anthropic 格式的 Messages 请求 - 代理根据模型层级（Opus / Sonnet / Haiku）匹配对应的服务商配置
- 将请求翻译为目标服务商支持的格式（OpenAI Chat 或 Anthropic Messages）
- 返回标准化的流式响应，Claude Code 无感知地完成工具调用和代码生成
这一架构保留了 Claude Code 的完整功能：流式输出、工具使用（Tool Use）、推理块（Thinking Block）均正常运作。
支持的服务商与免费额度
free-claude-code 支持以下 6 类后端，涵盖在线 API 和完全本地运行两种模式：
| 服务商 | 模式 | 免费额度 | 配置前缀 |
|---|---|---|---|
| NVIDIA NIM | 在线 API | 每月免费额度（限速） | nvidia_nim/ |
| OpenRouter | 在线 API | 部分模型提供 :free 标签 |
open_router/ |
| DeepSeek | 在线 API | 注册赠送 API Credits | deepseek/ |
| LM Studio | 本地运行 | 完全免费（本地算力） | lmstudio/ |
| llama.cpp | 本地运行 | 完全免费（本地算力） | llamacpp/ |
| Ollama | 本地运行 | 完全免费（本地算力） | ollama/ |
典型免费组合（按 Token 质量排序）：
- 在线优先：
MODEL_OPUS=nvidia_nim/moonshotai/kimi-k2.5，MODEL_SONNET=open_router/deepseek/deepseek-r1-0528:free - 纯本地：
MODEL=lmstudio/unsloth/GLM-4.7-Flash-GGUF（需 16GB+ 内存）
安装步骤（macOS / Linux / Windows）
前置条件
- 已安装 Claude Code（
npm install -g @anthropic-ai/claude-code） - Python 3.14 +
uv包管理器
第一步：安装 uv
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update
uv python install 3.14
Windows PowerShell：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
uv python install 3.14
第二步：克隆并配置代理
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .env
第三步：编辑 .env 文件
最简单的单 provider 配置（以 NVIDIA NIM 为例）：
NVIDIA_NIM_API_KEY="nvapi-<你的API Key>"
MODEL="nvidia_nim/z-ai/glm4.7"
ANTHROPIC_AUTH_TOKEN="freecc"
多 provider 分层路由配置（推荐）：
NVIDIA_NIM_API_KEY="nvapi-<你的API Key>"
OPENROUTER_API_KEY="sk-or-<你的API Key>"
MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"
MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free"
MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
MODEL="nvidia_nim/z-ai/glm4.7"
ANTHROPIC_AUTH_TOKEN="freecc"
第四步：启动代理服务器
uv run uvicorn server:app --host 0.0.0.0 --port 8082
服务启动后保持运行，另开终端执行第五步。
第五步：启动 Claude Code
Bash：
ANTHROPIC_AUTH_TOKEN="freecc" \
ANTHROPIC_BASE_URL="http://localhost:8082" \
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
claude
PowerShell：
$env:ANTHROPIC_AUTH_TOKEN="freecc"
$env:ANTHROPIC_BASE_URL="http://localhost:8082"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude
VS Code 与 JetBrains 配置方法
VS Code 扩展配置
在 VS Code 设置（settings.json）中添加以下字段：
"claudeCode.environmentVariables": [{ "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },{ "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" }
]
配置后重载扩展即生效，无需重启 VS Code。
JetBrains ACP 配置
编辑对应平台的配置文件：
- Windows：
C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json - macOS / Linux：
~/.jetbrains/acp.json
在文件中加入：
"env": {"ANTHROPIC_BASE_URL": "http://localhost:8082","ANTHROPIC_AUTH_TOKEN": "freecc","CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
}
修改后重启 IDE 生效。
代理方案 vs 官方订阅：如何权衡
| 维度 | free-claude-code 代理 | 官方 Claude Pro |
|---|---|---|
| 费用 | 接近零（部分 provider 有限速） | $20/月 |
| 模型质量 | 取决于 provider（替代模型） | 原生 Claude 3.5/4.x |
| 稳定性 | 依赖第三方 provider SLA | Anthropic 官方保障 |
| 数据隐私 | 本地 provider 完全私有 | 受 Anthropic 隐私政策约束 |
| 配置复杂度 | 需手动部署和维护 | 开箱即用 |
| 工具调用支持 | 全支持（含 Streaming） | 全支持 |
适合使用代理方案的场景：
- 个人学习和探索阶段，不想为订阅付费
- 数据敏感项目，要求全部流量本地处理
- 已有 NVIDIA NIM / OpenRouter 账号且有剩余额度
不建议依赖代理方案的场景：
- 生产环境中的代码审查或重要功能开发（替代模型输出质量不稳定）
- 需要 Claude 最新模型能力（Opus 4.7 等）
对于希望以标准 API 接入多种大模型的开发者，也可参考支持 OpenAI 和 Anthropic 双协议的推理服务（例如七牛云 AI 推理服务兼容两种接口格式，可作为 OpenRouter 的替代选项之一）。
性能调优参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
PROVIDER_RATE_LIMIT |
1 | 每秒最大请求数，避免触发 provider 限速 |
PROVIDER_MAX_CONCURRENCY |
5 | 并发请求上限 |
HTTP_READ_TIMEOUT |
120 | 响应超时（秒），本地 LLM 可适当调高 |
ENABLE_MODEL_THINKING |
false | 启用推理块（Thinking），仅部分模型支持 |
本地 LLM（如 Ollama）推荐将 HTTP_READ_TIMEOUT 调至 300，首次推理加载时间较长。
常见问题
Q：使用代理后 Claude Code 会报 API 鉴权失败吗？
ANTHROPIC_AUTH_TOKEN 是本地代理的自定义鉴权值，与 Anthropic 官方 Key 无关。只要三个环境变量（ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY）全部设置正确，Claude Code 不会报鉴权错误。.env 中的 ANTHROPIC_AUTH_TOKEN 和启动时传入的值必须一致。
Q：Ollama 本地运行的模型能完整支持 Claude Code 的工具调用功能吗？
支持程度取决于具体模型。支持 Function Calling / Tool Use 的模型（如 Qwen 2.5 Coder、Llama 3.1 70B）可正常使用，不支持工具调用的模型则会导致部分 Claude Code 功能失效。建议优先选用 lmstudio/ 路径下经过 GGUF 量化且明确标注支持 tool_use 的模型。
Q：如何在不同项目间切换 provider？
可以为每个项目创建独立的 .env 文件，或在启动代理时通过环境变量覆盖 .env 配置。对于 VS Code 用户，claudeCode.environmentVariables 配置是全局的，不支持按工作区区分。
Q：代理服务器崩溃后 Claude Code 会自动重连吗？
不会自动重连。需要重新执行 uv run uvicorn server:app --host 0.0.0.0 --port 8082 恢复代理服务。建议使用 pm2 或 systemd 将代理作为后台服务管理，避免手动重启。
Q：使用 OpenRouter 的 :free 模型有什么限制？
OpenRouter 免费模型通常有 RPM（每分钟请求次数）和 TPD（每日 Token 总量）限制，且模型池会动态变化。OpenRouter 免费模型有请求频率限制，超限后返回 429 错误。[数据待核实：建议查阅 OpenRouter 官方 Rate Limits 文档确认当前具体 RPM 数值]PROVIDER_RATE_LIMIT=1 的默认配置通常足以避免触发限速。
小结
free-claude-code 通过标准 API 代理层实现了 Claude Code 与任意 OpenAI / Anthropic 兼容服务商的对接，理论上可将使用成本降至零。项目完整支持流式输出、工具调用和多平台配置（终端、VS Code、JetBrains），对个人开发者的学习和实验场景具有实用价值。核心约束在于替代模型的输出质量和 provider 的稳定性，无法替代官方 Claude 订阅在生产场景的可靠性。
项目维护者 Alishahryar1 在 README 中明确指出，推荐生产场景仍使用官方 API。本文数据基于 2026 年 5 月 GitHub 仓库状态（v0.x 阶段），项目迭代较快，建议参考仓库最新 README 获取最新配置方式。
延伸资源
- free-claude-code GitHub 仓库
- Claude Code Router 七牛云配置指南
- NVIDIA NIM 免费 API 申请