# free-claude-code 深度研究报告

更新时间：2026-05-18

## 一句话结论

free-claude-code 是一个本地 Anthropic-compatible proxy。它不是破解 Claude Code，而是把 Claude Code、VS Code、JetBrains ACP 或聊天机器人发出的 Anthropic Messages API 请求，转发到 NVIDIA NIM、Kimi、OpenRouter、DeepSeek、LM Studio、Ollama、llama.cpp 等后端模型。

## 项目定位

它解决的是 Claude Code 使用里的三个痛点：

- 想保留 Claude Code 的终端交互体验。
- 想降低模型成本，或使用免费 / 本地模型。
- 想把不同 provider 接到同一个 Anthropic-compatible 接口下。

所以它更像“Claude Code 的模型网关”，而不是一个新的 AI 编程 Agent。

## 核心能力

| 能力 | 说明 |
| --- | --- |
| Anthropic-compatible proxy | 接收 Claude Code 的 `/v1/messages` 请求 |
| 多 provider | NVIDIA NIM、Kimi、OpenRouter、DeepSeek、LM Studio、llama.cpp、Ollama 等 |
| 分层路由 | Opus、Sonnet、Haiku、fallback 可走不同模型 |
| 工具调用 | 支持 Claude Code 的 tool use、streaming、thinking block |
| Admin UI | 本地 `/admin` 管理模型、Key、端口和配置 |
| IDE / 聊天集成 | 支持 VS Code、JetBrains ACP、Discord、Telegram |
| 本地模型 | 可接 LM Studio、Ollama、llama.cpp |
| 语音能力 | 支持本地 Whisper 或 NVIDIA NIM 转写 |

它的关键价值是：不改 Claude Code 的使用习惯，只换后端模型。

## 技术路线

项目主语言是 Python，要求 Python 3.14 和 uv。它启动一个本地 Uvicorn 服务，监听类似 `http://127.0.0.1:8082` 的地址。

Claude Code 侧通过环境变量接入：

```bash
ANTHROPIC_BASE_URL=http://localhost:8082
ANTHROPIC_AUTH_TOKEN=freecc
```

项目还提供 `fcc-server` 和 `fcc-claude`，前者启动代理，后者读取当前配置后启动真实 `claude` 命令。

## 和同类方案对比

| 方案 | 定位 | free-claude-code 的差异 |
| --- | --- | --- |
| Claude Code 官方 | 原生 Claude 模型体验 | free-claude-code 可换后端，但稳定性依赖第三方 |
| LiteLLM | 通用 LLM 网关 | free-claude-code 更贴 Claude Code 协议和工具调用 |
| OpenRouter | 模型聚合平台 | free-claude-code 是本地代理，可再接 OpenRouter |
| Ollama / LM Studio | 本地模型运行 | free-claude-code 把它们伪装成 Claude Code 可用后端 |
| OpenClaw | Claude Code 类替代 | free-claude-code 更像网关，不是完整新客户端 |

一句话：它不是替代 Claude Code 的前端，而是替换 Claude Code 背后的模型来源。

## 风险与边界

第一，它不是 Anthropic 官方服务。Claude Code 客户端虽然能通过代理使用其他模型，但工具调用质量、上下文处理、thinking block 表现都取决于后端模型和 provider。

第二，所谓 free 不等于无限稳定。免费模型通常有速率、上下文、可用性和质量波动。

第三，安全风险不能忽略。代理会处理代码上下文、API key 和模型请求，必须本地可信运行，不能随便暴露公网端口。

第四，合规和服务条款要谨慎。Claude Code、各 provider、本地模型许可都可能对代理、转发、商用使用有不同限制。

## 最终判断

free-claude-code 是一个很有现实价值的 Claude Code 模型网关。它抓住了 AI 编程工具里的关键需求：用户喜欢 Claude Code 的交互方式，但希望模型后端更便宜、更自由、更可控。

结论：free-claude-code 不是官方 Claude Code 替代品，而是一个高热度的本地模型代理层。它能降低试错成本，但不能保证获得 Claude 原生模型级别的可靠体验。

## 信息来源

- GitHub 仓库：https://github.com/Alishahryar1/free-claude-code
- README：https://github.com/Alishahryar1/free-claude-code