古法编程

将 Free Claude Code 代理部署到本地，只需完成四个核心步骤：安装 Python 3.14 与 uv 工具、克隆仓库并配置 .env 文件、启动代理服务、设置环境变量连接 Claude Code CLI。本教程提供 macOS、Linux、Windows 三个平台的完整操作命令，助你从零开始在 5 分钟内启动一个可工作的 Anthropic API 代理。

Free Claude Code 安装部署教程：5 分钟从零启动 Anthropic 代理

Free Claude Code 是一个开源的 Anthropic API 代理，它允许你将 Claude Code CLI、VS Code 扩展等工具的后端请求，转发到 NVIDIA NIM、OpenRouter、DeepSeek 或 Ollama 等服务，从而实现免费或低成本的使用。以下是完成部署所需的全部步骤。

前置条件

在开始之前，请确保你的系统满足以下要求：

  1. Claude Code CLI：已按照官方指南安装完毕。
  2. Python 3.14：Free Claude Code 项目使用了 Python 3.14 的新语法特性，必须安装此特定版本。
  3. uv 包管理器：一个用于管理 Python 项目和工具的快速包管理器，本项目使用它来安装依赖和运行服务。

第一步：安装 Python 和 uv

根据你的操作系统，选择对应的命令进行安装。

macOS / Linux (Bash/zsh)：

首先安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果 uv 已安装，建议更新到最新版本：

uv self update

然后，使用 uv 安装 Python 3.14：

uv python install 3.14

Windows (PowerShell)：

在 PowerShell 中执行：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
uv python install 3.14

验证安装： 安装完成后，可以运行以下命令确认 uv 和 Python 3.14 已就绪：

uv --version
uv python list --installed

你应该能看到 uv 的版本号以及 Python 3.14 在已安装列表中。

第二步：克隆仓库并配置环境变量

从 GitHub 克隆 Free Claude Code 的仓库到本地：

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

接下来，需要创建并配置环境变量文件。首先复制模板：

# macOS / Linux
cp .env.example .env
# Windows PowerShell
Copy-Item .env.example .env

用文本编辑器打开 .env 文件。你只需配置三个核心变量。下面是一个使用 NVIDIA NIM 作为后端的最简配置示例：

NVIDIA_NIM_API_KEY="nvapi-你的密钥"
MODEL="nvidia_nim/z-ai/glm4.7"
ANTHROPIC_AUTH_TOKEN="freecc"
  • NVIDIA_NIM_API_KEY：填入你在 NVIDIA NIM 平台申请的 API Key。
  • MODEL：指定要使用的模型标识符。
  • ANTHROPIC_AUTH_TOKEN：可设为任意字符串，Claude Code 会将其原样发回给代理作为凭据。若留空，则表示不进行校验（仅建议在本地测试时使用）。

如何选择 Provider？ 根据你的使用场景，可以选择不同的后端。更多详细配置，请参考各 Provider 的专文说明。

场景 推荐 Provider 说明
快速尝试、体验 NVIDIA NIM 提供免费 GPU 额度，申请 API Key 即可使用
追求性价比、中文优化 DeepSeek 价格低廉，中文处理能力较强
希望尝试多种免费模型 OpenRouter 拥有免费模型池，模型选择丰富
完全离线、零成本 Ollama / LM Studio 在本地运行模型，无需联网

第三步：启动代理服务

配置完成后，在 free-claude-code 项目目录下，你可以选择两种方式启动代理。

方式一：直接运行（推荐用于开发调试）

uv run uvicorn server:app --host 0.0.0.0 --port 8082

当你在终端看到类似 Uvicorn running on http://0.0.0.0:8082 的输出时，即表示代理已成功启动。端口 8082 是默认值，你可以根据需要修改。

方式二：通过 uv tool 安装（启动命令更简洁） 这种方式会将 free-claude-code 安装为一个全局可用的命令行工具。

# 从 GitHub 仓库安装
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git
# 首次运行，会创建配置模板
fcc-init
# 启动代理
free-claude-code

fcc-init 命令会在 ~/.config/free-claude-code/ 目录下创建 .env 文件模板。你需要编辑这个文件完成配置，之后就可以直接使用 free-claude-code 命令启动代理了。

第四步：连接 Claude Code CLI

代理运行后，你需要设置环境变量，将 Claude Code CLI 的请求指向本地代理。

在 Bash / zsh 终端中：

ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude

在 Windows PowerShell 中：

$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude

请特别注意：ANTHROPIC_BASE_URL 的值应为代理的根地址 http://localhost:8082，不要添加 /v1 后缀，代理内部已处理路由。

连接成功后，你在 Claude Code CLI 中进行的所有对话，都会经由本地代理转发到你配置的后端 Provider。其使用体验与直接调用 Anthropic API 完全一致。

验证代理是否正常运行

你可以通过访问代理的根地址和健康检查接口来验证其状态。

检查代理返回的配置信息：

curl http://localhost:8082/

正常响应应包含当前配置的 Provider 和模型信息，例如：

{"status":"ok","provider":"nvidia_nim","model":"z-ai/glm4.7"}

执行健康检查：

curl http://localhost:8082/health

正常响应为：

{"status":"healthy"}

FAQ

Q: 启动时报错 uv: command not found 怎么办？ A: uv 安装脚本会将其添加到 PATH，但需要重启终端使其生效。你也可以手动 source 配置文件：Linux/macOS 执行 source ~/.bashrc 或 source ~/.zshrc。Windows 用户请检查 %USERPROFILE%\.local\bin 是否已加入系统 PATH 环境变量。

Q: 默认端口 8082 被其他程序占用了怎么办？ A: 你可以在启动命令中指定一个不同的端口，例如 uv run uvicorn server:app --host 0.0.0.0 --port 9090。同时，连接 Claude Code CLI 时设置的 ANTHROPIC_BASE_URL 环境变量也需要使用新的端口，如 http://localhost:9090。

Q: 代理启动成功了，但 Claude Code CLI 无法连接？ A: 首先，通过 curl http://localhost:8082/health 确认代理服务正常。其次，仔细检查环境变量 ANTHROPIC_BASE_URL，确保没有添加 /v1 等多余后缀。Windows PowerShell 用户需注意其环境变量设置语法与 Bash 不同，不能使用 KEY=value command 的格式。