free-claude-code 零基础教程：5分钟搭建代理服务器白嫖AI模型

你是否遇到过这种情况：想用 Claude Code 的 AI 编程能力，但每次打开终端看到“API 费用不足”的提示，心里就凉了半截？Claude Code 本身完全免费，真正烧钱的是它背后调用的 Anthropic API——每百万 Token 大约 3 到 15 美元，对于日常开发来说，这笔开销积少成多，确实让人肉疼。

在开始之前，可以先看一下这个工具的核心工作方式：它在本机启动一个代理服务器，拦截 Claude Code 的 API 请求，然后转发给免费的第三方模型。Claude Code 完全不知道自己用的不是 Anthropic，照常运行所有功能。

从下面这张图可以快速理解这个工具的核心使用方式：Claude Code 发出的请求原本指向 https://api.anthropic.com/v1/messages，现在被拦截到本地的 http://localhost:8082，然后路由到 NVIDIA NIM、OpenRouter 或本地模型。整个过程对用户透明，你只需要设置两个环境变量。

这就是 free-claude-code 使用教程 要讲的核心：一个开源代理服务器，让你绕过 Anthropic 的付费 API，用免费模型跑 Claude Code。这个项目在 GitHub 上已经有 10.2k Star，社区活跃度很高，说明确实解决了很多人的痛点。

原理：为什么能做到“零成本”

很多人以为 Claude Code 本身收费，其实不是。Claude Code 本体通过 npm install -g @anthropic-ai/claude-code 安装，完全免费。费用来源是每次对话调用的 Anthropic API——claude-3-5-sonnet、claude-opus-4 这些模型每百万 Token 收费 3 到 15 美元。

free-claude-code 的拦截原理很巧妙。正常情况下，Claude Code 直接请求 Anthropic 的 API。加了代理之后，请求先经过本地的 free-claude-code 服务器，这个服务器根据你配置的模型路由规则，把请求转发给 NVIDIA NIM（免费额度）、OpenRouter（部分免费模型）或本地运行的 LM Studio / llama.cpp。

模型路由机制是这套方案的核心。Claude Code 发出的请求里包含 model 字段，比如 claude-3-opus-20240229 对应 MODEL_OPUS 变量，claude-3-5-sonnet-20241022 对应 MODEL_SONNET 变量。你可以让 Opus、Sonnet、Haiku 分别对应不同的模型和服务商，混搭也没问题。

free-claude-code 适合新手吗？ 从配置复杂度来看，如果你熟悉终端操作，5 分钟就能跑起来。但如果完全没接触过环境变量和代理设置，可能需要多花点时间理解原理。

五分钟安装和配置

前置：安装 Claude Code 本体

首先确保已安装 Node.js 18+，然后安装 Claude Code：

node --version
npm install -g @anthropic-ai/claude-code
claude --version

安装 free-claude-code

推荐使用 uv 安装，这是最简单的方式：

# 安装 uv（Linux/Mac）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 一行安装 free-claude-code
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git

# 初始化配置文件
fcc-init
# 会在 ~/.config/free-claude-code/.env 生成配置模板

# 启动代理服务器
free-claude-code
# 服务器运行在 http://localhost:8082

如果你更习惯传统方式，也可以克隆仓库安装：

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .env
# 编辑 .env 填入 API Key 和模型名
uv sync
uv run uvicorn server:app --host 0.0.0.0 --port 8082

配置 .env 文件：三种免费方案

方案 A：NVIDIA NIM（免费额度，推荐）

NVIDIA NIM 提供大量模型的免费 API 调用额度，注册 NVIDIA Developer 账号即可获得免费 API Key。这是目前最稳定的免费方案。

# ~/.config/free-claude-code/.env
NVIDIA_NIM_API_KEY="nvapi-你的key"

MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"      # 重任务用强模型
MODEL_SONNET="nvidia_nim/moonshotai/kimi-k2.5"    # 日常编码
MODEL_HAIKU="nvidia_nim/stepfun-ai/step-3.5-flash" # 轻量快速
MODEL="nvidia_nim/z-ai/glm4.7"                    # fallback

方案 B：OpenRouter 免费模型

OpenRouter 有大量 :free 后缀的免费模型，注册即可用。适合作为 NVIDIA NIM 额度用完后的补充。

OPENROUTER_API_KEY="sk-or-你的key"

MODEL_OPUS="open_router/deepseek/deepseek-r1-0528:free"
MODEL_SONNET="open_router/openai/gpt-oss-120b:free"
MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"
MODEL="open_router/stepfun/step-3.5-flash:free"

方案 C：本地模型（LM Studio / llama.cpp，完全免费）

无需任何 API Key，需要本机有足够的 GPU/CPU 资源。适合对隐私要求高的场景。

# LM Studio 配置
MODEL_OPUS="lmstudio/unsloth/MiniMax-M2.5-GGUF"
MODEL_SONNET="lmstudio/unsloth/Qwen3.5-35B-A3B-GGUF"
MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
MODEL="lmstudio/unsloth/GLM-4.7-Flash-GGUF"

方案 D：混搭（最推荐的方式）

重任务用云端免费模型，轻任务用本地模型，平衡质量和速度。

NVIDIA_NIM_API_KEY="nvapi-..."
OPENROUTER_API_KEY="sk-or-..."

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="lmstudio/unsloth/GLM-4.7-Flash-GGUF"         # fallback

free-claude-code 免费版够用吗？ 从功能完整性来看，免费版完全够用。所有核心功能——模型路由、多端支持、语音输入——都不需要付费。唯一的限制是你选择的免费模型本身的能力上限。

三种使用方式

方式一：终端（Claude Code CLI）

这是最常用的方式。启动代理服务器后，设置环境变量即可：

# 启动代理服务器（保持在后台运行）
free-claude-code &

# 方法1：每次临时设置环境变量
ANTHROPIC_BASE_URL="http://localhost:8082" \
ANTHROPIC_AUTH_TOKEN="freecc" \
claude

# 方法2：写入 ~/.zshrc 永久生效
echo 'export ANTHROPIC_BASE_URL="http://localhost:8082"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="freecc"' >> ~/.zshrc
source ~/.zshrc
# 之后直接运行 claude 即走代理

进阶技巧： 你可以为不同模型创建别名，快速切换：

alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude'
alias claude-deepseek='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:deepseek/deepseek-r1:free" claude'

方式二：VS Code 插件

安装 Claude Code 的 VS Code 插件后，在 settings.json 里配置：

{
  "claude-code.anthropicBaseUrl": "http://localhost:8082",
  "claude-code.anthropicApiKey": "freecc"
}

或者在终端里启动 VS Code 时带环境变量：

ANTHROPIC_BASE_URL="http://localhost:8082" \
ANTHROPIC_AUTH_TOKEN="freecc" \
code .

方式三：Discord / 消息平台

free-claude-code 支持通过 Discord Bot 使用 Claude Code——团队共享一个代理服务器，多人通过 Discord 频道调用。在 .env 里添加 Discord 配置：

DISCORD_TOKEN="你的-discord-bot-token"
DISCORD_CHANNEL_ID="频道ID"

然后在 Discord 里 @ Bot 直接提问，Bot 调用你配置的模型回答。

使用误区： 很多人以为配置好代理后，Claude Code 的所有功能都能完美运行。实际上，免费模型的能力参差不齐，有些模型不支持 function calling 或 tool use，会导致某些高级功能失效。建议先用简单任务测试，确认模型兼容性。

进阶配置

完整 .env 配置参考

# ~/.config/free-claude-code/.env

# ── 模型路由 ──
NVIDIA_NIM_API_KEY="nvapi-你的key"
OPENROUTER_API_KEY="sk-or-你的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="lmstudio/unsloth/GLM-4.7-Flash-GGUF"

# ── 思考模式 ──
ENABLE_THINKING=true          # 开启推理过程显示

# ── 语音输入（可选）──
WHISPER_DEVICE="cpu"
WHISPER_MODEL="base"

# ── NVIDIA NIM 代理（可选）──
# NIM_PROXY="http://your-proxy:port"

开启语音输入

# 安装语音支持
uv tool install "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"

# .env 里配置
WHISPER_DEVICE="cuda"         # 有 GPU 就用 cuda，否则 cpu
WHISPER_MODEL="small"         # 英文用 base，中文用 small

子 Agent 控制（防止失控）

free-claude-code 会拦截 Task 工具调用，强制 run_in_background=False，防止子 Agent 在后台无限制地运行任务。这是一个安全机制，不需要额外配置。日志里会看到：

[free-claude-code] Task intercepted: run_in_background forced to False

个人判断： 这个安全机制很实用。我见过有人用 Claude Code 写自动化脚本时，子 Agent 在后台跑了几个小时，消耗了大量 API 额度。强制同步执行虽然慢一点，但至少不会失控。

免费模型选择建议

2026 年推荐的免费模型

NVIDIA NIM 免费模型（注册即得额度）

模型	特点	适合场景
moonshotai/kimi-k2.5	代码能力强	Opus 位置
moonshotai/kimi-k2-thinking	带推理链	复杂任务
z-ai/glm4.7	国产强模型	中文代码
stepfun-ai/step-3.5-flash	速度快	Haiku 位置

OpenRouter 完全免费模型（带 :free 标记）

模型	特点
deepseek/deepseek-r1-0528:free	DeepSeek 推理模型，强
openai/gpt-oss-120b:free	GPT 开源版，综合好
stepfun/step-3.5-flash:free	轻量快速
meta-llama/llama-3.3-70b:free	Llama 3.3，开源强模型

本地模型推荐（LM Studio / llama.cpp）

模型	显存需求	特点
MiniMax-M2.5-GGUF	8GB+	代码强
Qwen3.5-35B-A3B-GGUF	12GB+	中文代码优秀
GLM-4.7-Flash-GGUF	4GB+	轻量版本
Qwen3-7B-Q4_K_M.gguf	8GB	入门级

按任务选模型的建议

任务类型	建议模型
复杂架构设计/重构	kimi-k2.5 / deepseek-r1
日常代码编写	glm4.7 / gpt-oss-120b
快速问答/简单修改	step-3.5-flash / GLM-4.7-Flash
中文代码+注释	glm4.7 / Qwen3.5
离线/隐私场景	本地 LM Studio 模型

free-claude-code 替代方案： 如果你觉得配置代理太麻烦，也可以考虑直接使用支持 OpenAI 兼容 API 的 IDE 插件，比如 Continue.dev 或 Cody。不过这些方案通常需要自己管理模型切换，不如 free-claude-code 的模型路由机制灵活。

常见问题速解

问题 1：启动报 AssertionError / pydantic 错误

这是 Python 版本兼容问题（Python 3.14 与 pydantic 不兼容）：

# 使用 Python 3.11 或 3.12
uv python install 3.12
uv venv --python 3.12 .venv
source .venv/bin/activate
uv sync
uv run uvicorn server:app --host 0.0.0.0 --port 8082

问题 2：Claude Code 连不上代理

# 检查代理服务器是否在运行
curl http://localhost:8082/health
# 应该返回 {"status": "ok"}

# 检查环境变量
echo $ANTHROPIC_BASE_URL   # 应该是 http://localhost:8082
echo $ANTHROPIC_AUTH_TOKEN # 应该是 freecc

问题 3：模型回复质量差，一直出错

原因 1：选的免费模型能力不够。换更强的模型，比如 deepseek-r1。

原因 2：模型的上下文窗口太小。在 Claude Code 里用 /compact 压缩上下文。

原因 3：模型不支持 function calling / tool use。查 OpenRouter 的模型详情页确认。

问题 4：NVIDIA NIM API Key 免费额度用完了

切换到 OpenRouter 免费模型或本地模型兜底。

问题 5：Windows 上 Git Bash 报 cygpath 错误

安装 Git for Windows（含 bash + cygpath），或者在 WSL2 里运行。

安全注意事项

本地代理的安全模型

安全的做法：

只绑定 localhost（默认），只有本机能访问
API Key 不上传，.env 文件只在本机，不要 git commit
代理服务器不做任何持久化，所有请求都是透传

需要注意的：

如果你修改 host 为 0.0.0.0 对外暴露，务必设置 ANTHROPIC_AUTH_TOKEN 认证
使用第三方模型（NIM/OpenRouter），你的对话内容会发送给这些服务商
有隐私需求请使用本地模型

各方案成本对比

方案	月成本	上手难度	模型质量	适合场景
官方 Claude API	¥50-500+	低	最高	专业商用
NVIDIA NIM	¥0	低	高	日常学习首选
OpenRouter 免费模型	¥0	低	中高	补充免费额度
LM Studio 本地	¥0（电费）	中	视配置	隐私/离线
llama.cpp	¥0（电费）	高	视配置	极客向
free-claude-code 混搭	¥0	中	灵活	最推荐