## 1. 项目简介

free-claude-code 是一个用 Python 编写的模型路由代理，核心目标是在终端、IDE 或手机里「白嫖」Claude Code、Codex、Pi、OpenCode 等主流编程 Agent。它聚合了 50+ 免费或订阅制模型服务方，将请求统一下发到各个编码 Agent，并内置降级链与 Admin UI，方便开发者统一管理和切换模型来源。

## 2. 核心特性

- 聚合 50+ 免费/订阅模型方，统一接入多个编程 Agent。
- 内置降级链：当某个模型方不可用或限流时，自动切换到备用模型。
- 提供 Admin UI，方便查看路由状态、模型健康度与调用统计。
- 纯 Python 实现，部署简单，适合个人开发者或小团队自用。

## 3. 工作原理

free-claude-code 本质上是一个位于「编程 Agent」与「模型服务方」之间的代理层。开发者在本机配置好 Agent 后，将请求指向本代理，代理再根据路由规则把请求转发到具体的模型方，并把响应返回给 Agent。

```mermaid
flowchart TD
  A["开发者终端 / IDE / 手机"] --> B["Claude Code / Codex / Pi / OpenCode"]
  B --> C["free-claude-code 路由代理"]
  C --> D["模型方 1"]
  C --> E["模型方 2"]
  C --> F["模型方 3"]
  C --> G["... 50+ 模型方"]
  D --> H["降级链"]
  E --> H
  F --> H
  G --> H
  H --> B
```


## 4. 快速开始

### 4.1 前置条件

在开始之前，请确认你的环境满足以下要求：

- **Python 版本**：需要 Python 3.9 及以上版本（推荐 3.10+），可通过 `python --version` 检查。
- **模型方账号**：至少注册一个受支持的模型服务方账号（如 Anthropic、OpenAI、Google Gemini 等），并准备好对应的 API Key。免费模型方通常有速率限制，建议准备 2-3 个备用账号以配合降级链使用。
- **网络环境**：能够正常访问所选的模型服务方 API 端点。

### 4.2 安装命令

克隆仓库并安装依赖：

```bash
# 克隆仓库
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

# 安装依赖
pip install -r requirements.txt
```

### 4.3 最小配置示例

在项目根目录创建 `.env` 文件，填入你的模型方 API Key 与代理监听端口：

```bash
# .env 示例
PORT=8080
ANTHROPIC_API_KEY=sk-ant-xxxx
OPENAI_API_KEY=sk-xxxx
GEMINI_API_KEY=xxxx
```

然后在 shell 中导出环境变量（或直接写入 `.env` 由代理自动加载）：

```bash
export PORT=8080
export ANTHROPIC_API_KEY="sk-ant-xxxx"
export OPENAI_API_KEY="sk-xxxx"
```

### 4.4 完整操作流程

按以下步骤从零开始完成首次请求：

1. **克隆并安装**：执行 `git clone` 与 `pip install -r requirements.txt`，确认依赖安装无报错。
2. **配置环境变量**：在 `.env` 中填入至少一个模型方的 API Key，并设置 `PORT=8080`。
3. **启动路由代理**：运行 `python main.py`，看到监听日志（如 `listening on 0.0.0.0:8080`）即表示启动成功。
4. **验证健康检查**：另开终端执行 `curl -s http://127.0.0.1:8080/health`，应返回 `200` 或 `ok` 状态。
5. **发送首次请求**：用 `curl` 向代理发送一条最小消息，确认能拿到模型响应。

```bash
# 启动代理
python main.py

# 健康检查
curl -s http://127.0.0.1:8080/health

# 首次请求
curl -s http://127.0.0.1:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-free-claude-code-token" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

### 4.5 验证成功的判断标准

- **健康检查通过**：`/health` 返回 `200` 或 `ok`，说明代理进程正常运行。
- **请求返回 200**：`/v1/messages` 返回 HTTP `200`，且响应体为合法 JSON。
- **响应包含模型输出**：JSON 中 `content` 字段非空，包含模型生成的文本（如对 `ping` 返回 `pong`）。
- **日志无异常**：代理终端未出现 `ERROR` 或 `ProviderError` 堆栈，降级链未触发。

满足以上全部条件，即表示 free-claude-code 已成功部署并完成首次请求。
## 5. 实战：配置 Claude Code 接入代理

下面以 Claude Code 为例，演示如何把本机 Agent 指向 free-claude-code 代理。

### 5.1 修改 Claude Code 配置文件

Claude Code 的配置文件位于 `~/.claude/settings.json`，在其中指定代理地址与模型路由：

```json
{
  "apiBaseUrl": "http://127.0.0.1:8080",
  "model": "claude-sonnet-4-20250514",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080",
    "ANTHROPIC_AUTH_TOKEN": "your-free-claude-code-token"
  }
}
```

- `apiBaseUrl` / `ANTHROPIC_BASE_URL`：指向本机代理地址，默认端口为 `8080`。
- `ANTHROPIC_AUTH_TOKEN`：代理的访问令牌，可在 Admin UI 中生成。

### 5.2 设置环境变量

也可以在 shell 中直接导出环境变量，效果与配置文件等价：

```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
export ANTHROPIC_AUTH_TOKEN="your-free-claude-code-token"
```

### 5.3 验证连通性

启动代理后，用 `curl` 快速验证路由是否正常：

```bash
# 确认代理已监听
curl -s http://127.0.0.1:8080/health

# 发送一次最小请求，观察是否返回模型响应
curl -s http://127.0.0.1:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-free-claude-code-token" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

若返回 `200` 与正常 JSON 响应，说明 Claude Code 已成功接入代理。

### 5.4 常见错误及解决方法

| 错误现象 | 可能原因 | 解决方法 |
| --- | --- | --- |
| `Connection refused` | 代理未启动或端口错误 | 确认 `python main.py` 已运行，检查端口是否与配置一致 |
| `401 Unauthorized` | 令牌错误或未设置 | 重新生成 `ANTHROPIC_AUTH_TOKEN` 并同步到配置 |
| `Model not found` | 模型名不在路由列表 | 在 Admin UI 中确认该模型方已启用，或改用列表内的模型名 |
| 请求超时 | 免费模型方限流或网络慢 | 检查降级链配置，或稍后重试 |


以下是一个最小化的本地部署示例：

```bash
# 克隆仓库
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code

# 安装依赖
pip install -r requirements.txt

# 启动路由代理
python main.py
```

启动后，将你的 Claude Code 或 Codex 配置指向本代理地址即可开始使用。

## 5. 降级链设计

降级链是 free-claude-code 的核心机制之一。当主模型方返回错误、超时或触发限流时，代理会自动按优先级尝试下一个模型方，直到请求成功或所有模型方都失败。

```python
# 伪代码示例：降级链核心逻辑
MODEL_PROVIDERS = ["provider_a", "provider_b", "provider_c"]

def route_request(prompt):
    for provider in MODEL_PROVIDERS:
        try:
            return call_provider(provider, prompt)
        except ProviderError:
            continue
    raise AllProvidersFailed("所有模型方均不可用")
```

## 6. Admin UI 与监控

Admin UI 提供以下能力：

- 查看各模型方的实时健康状态。
- 统计每个模型方的调用次数、成功率与平均延迟。
- 手动切换默认模型方或调整降级顺序。
- 查看最近请求日志，便于排查问题。

## 7. 适用场景与注意事项

适用场景：

- 个人开发者希望低成本体验多个编程 Agent。
- 需要在一个统一入口下管理多个模型订阅。
- 希望在主模型限流时自动降级到备用模型。

注意事项：

- 免费模型方通常有速率限制，不适合高并发生产环境。
- 请遵守各模型方的服务条款，避免滥用。
- 代理本身不存储对话数据，但请留意模型方的数据使用政策。

## 8. 总结

free-claude-code 通过一个轻量 Python 代理，把 50+ 模型方聚合到统一的编程 Agent 入口，并借助降级链与 Admin UI 提升了可用性与可观测性。对于想低成本体验多种编码 Agent 的开发者来说，是一个值得尝试的开源工具。

free-claude-code 是一个用 Python 编写的模型路由代理，核心目标是在终端、IDE 或手机里「白嫖」Claude Code、Codex、Pi、OpenCode 等主流编程 Agent。它聚合了 50+ 免费或订阅制模型服务方，将请求统一下发到各个编码 Agent，并内置降级链与 Admin UI，方便开发者统一管理和切换模型来源。

一个聚合 50+ 模型方的编程 Agent 路由代理

编程语言

人工智能

开发工具

free-claude-code是Python编写的模型路由代理，聚合50+免费模型服务方，统一接入ClaudeCode、Codex等编程Agent。内置自动降级链、AdminUI监控，支持一键切换模型来源，部署简单，适合个人开发者低成本体验多种编码Agent。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

一个聚合 50+ 模型方的编程 Agent 路由代理-腾讯云开发者社区-腾讯云

一个聚合 50+ 模型方的编程 Agent 路由代理

一个聚合 50+ 模型方的编程 Agent 路由代理

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐