What Free Claude Code Does

Claude Code is amazing — but it requires an Anthropic API key. What if you could use it with free or cheaper models instead?

The $0 AI coding setup

Claude Code is built to talk to Anthropic's servers. Every question you ask, every file it reads, every line of code it writes — it all goes through Anthropic's API, and you pay per token.

Free Claude Code is a proxy that intercepts those API calls and redirects them to free or cheaper alternatives: NVIDIA NIM (free GPU tier), OpenRouter, DeepSeek, local models via Ollama, and more.

💰

The key trick

Claude Code thinks it's talking to Anthropic. Free Claude Code pretends to be Anthropic, accepts the same API format, then quietly routes the request to a different model. Claude Code never knows the difference.

What you get

🔄

6 Provider Backends

Route to NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, or Ollama. Mix and match different providers for different Claude models.

🎯

Per-Model Routing

Send Opus traffic to OpenRouter (expensive tasks), Haiku traffic to local Ollama (quick questions). Fine-grained control over where each model tier goes.

🎙️

Voice Input

Optional voice-note transcription via local Whisper or NVIDIA NIM. Dictate coding instructions instead of typing.

💬

Bot Wrappers

Use Claude Code through Discord or Telegram — send a message from your phone and get code back. Great for remote sessions.

The journey of an API call

When you type a question into Claude Code, here's what actually happens with Free Claude Code in the middle:

1

You type a question in Claude Code

Claude Code formats your question as an Anthropic Messages API request — the standard JSON format Anthropic expects.

2

The request hits Free Claude Code instead

Claude Code is configured to point at localhost:8080 instead of api.anthropic.com. Free Claude Code is waiting there.

3

The model name is looked up in routing rules

Claude Code asked for claude-opus-4-5. The routing config says "send Opus to OpenRouter." So it goes to OpenRouter.

4

The response is translated back

OpenRouter responds in its own format. Free Claude Code translates it back to Anthropic format and returns it to Claude Code. Claude Code has no idea anything unusual happened.

Check your understanding

Why doesn't Claude Code need to be modified to work with Free Claude Code?

02

代理是什么？

Free Claude Code 的核心就是一个代理服务器——一个站在你和 AI 提供商之间的"翻译官"。

翻译官比喻

想象一个国际会议：你只会中文，对方只说英文。你们中间坐着一个翻译官——你说话，翻译官听懂后翻译给对方；对方回答，翻译官再翻译给你。

Free Claude Code 就是这个翻译官：

1

Claude Code 发请求到 localhost:8080

正常情况下 Claude Code 会连接 api.anthropic.com，但你通过环境变量把它指向本地代理。Claude Code 完全不知道自己不是在和 Anthropic 通信。

2

Free Claude Code 接收并解析请求

代理读到请求中的模型名（如 claude-sonnet-4-5）和消息内容，根据配置文件中的路由规则，决定把这个请求转发给哪个提供商。

3

转发到真实提供商

代理把 Anthropic 格式的请求翻译成目标提供商的格式（如 OpenRouter 或 DeepSeek 的 API 格式），发送出去并等待响应。

4

响应转换后原路返回

提供商返回结果后，代理将其翻译回 Anthropic 的响应格式，返回给 Claude Code。全程无感知。

消息流动画

点击"下一步"按钮，观察一个 API 请求从 Claude Code 发出到收到响应的完整旅程：

点击"下一步"开始演示

CC

Claude Code

PX

Free CC Proxy

AI

提供商

0 / 6

核心路由逻辑：代码 vs 人话

            config.js
            const routes = {
              "claude-opus-*": {
                provider: "openrouter",
                model:    "anthropic/claude-opus-4"
              },
              "claude-sonnet-*": {
                provider: "deepseek",
                model:    "deepseek-chat"
              },
              "claude-haiku-*": {
                provider: "ollama",
                model:    "llama3"
              }
            };
          

中文解释

Opus 级别的请求（复杂推理）→ 发给 OpenRouter，用真正的 Claude Opus

Sonnet 级别的请求（日常编码）→ 发给 DeepSeek，用便宜但同样强大的模型

Haiku 级别的请求（快速问答）→ 发给本地 Ollama，零成本

检验理解

Free Claude Code 作为代理的核心能力是什么？

03

模型路由

不是所有任务都需要最贵的模型。路由规则让你按需分配，把钱花在刀刃上。

为什么需要路由？

Claude Code 在不同场景下会请求不同级别的模型。如果你把所有请求都发给最贵的 Opus，钱包会很受伤；如果都发给最便宜的模型，复杂任务的质量会明显下降。

模型路由的核心思路：

Opus

复杂推理 → 用贵但强的模型

架构设计、复杂 bug 调试、多文件重构——这些任务需要最聪明的模型。路由到 OpenRouter 上的 Claude Opus 或 GPT-4o。

Sonnet

日常编码 → 用便宜够用的模型

写函数、加注释、简单重构——DeepSeek-V3 这类模型已经足够好，成本只有 Opus 的十分之一。

Haiku

快速问答 → 用本地免费模型

"这个函数是干什么的？""帮我格式化这段代码"——本地 Ollama 跑 Llama 3，零成本，零延迟（不走网络）。

五种路由策略

🎯

Opus → OpenRouter

复杂任务走 OpenRouter 的 Claude Opus 或 GPT-4o。按量付费但质量最高。适合需要深度理解的场景。

⚡

Sonnet → DeepSeek

日常编码走 DeepSeek-V3。价格极低（约 ¥1/百万 token），编码能力接近 Claude Sonnet，性价比之王。

🏠

Haiku → Ollama 本地

简单问答走本地 Ollama。零成本、零网络延迟、数据不出本机。需要自己的 GPU 或 CPU 跑推理。

🔧

自定义规则

按文件类型、项目目录或时间条件路由。例如：TypeScript 文件走 DeepSeek，Python 文件走 OpenRouter。

🔄

回退机制

主提供商不可用时自动切换备用。例如 OpenRouter 挂了 → 自动切到 DeepSeek → 再挂切到本地 Ollama。保证不中断。

检验理解

当你配置的路由中，主提供商突然不可用了，Free Claude Code 会怎么做？

04

提供商与适配器

Free Claude Code 支持 6 个后端提供商，每个都有独特的优势。适配器模式让它们看起来都一样。

六大提供商

每个提供商在不同场景下各有优势。了解它们的特性，才能做出最优选择：

N

NVIDIA NIM

免费 GPU 推理层。NVIDIA 提供免费试用的云端模型推理，适合体验各种开源模型，不需要自己的 GPU。

OR

OpenRouter

统一接口聚合 100+ 模型。一个 API key 访问 Claude、GPT-4o、Llama、Mistral 等所有主流模型。按量计费。

DS

DeepSeek

便宜且强大。DeepSeek-V3 编码能力接近 Claude Sonnet，价格仅为其十分之一。日常编码的性价比首选。

LM

LM Studio

本地 GUI 工具。可视化下载和管理开源模型，内置推理服务器。适合不想碰命令行的用户。

ll

llama.cpp

C++ 推理引擎。极致性能优化，支持 CPU/GPU 混合推理。技术用户的首选，需要自己编译和配置。

Ol

Ollama

本地部署最简方案。一条命令 ollama run llama3 就能跑模型。自动管理下载、量化和推理，开箱即用。

适配器模式：统一接口的秘密

这 6 个提供商的 API 格式各不相同。OpenRouter 用一种格式，DeepSeek 用另一种，Ollama 又不一样。Free Claude Code 怎么同时支持它们？

答案是适配器模式——每个提供商一个适配器，对上层暴露完全相同的接口：

            adapter.js
            // 统一接口 —— 所有适配器都实现这两个方法
            class BaseAdapter {
              async sendRequest(messages, model) { }
              translateResponse(rawResponse) { }
            }
            
            // DeepSeek 适配器：把 Anthropic 格式转成 DeepSeek 格式
            class DeepSeekAdapter extends BaseAdapter {
              async sendRequest(messages, model) {
                // Anthropic → DeepSeek 格式转换
                const body = toOpenAIFormat(messages, model);
                return fetch("https://api.deepseek.com/v1/chat",
                  { method: "POST", body: JSON.stringify(body) });
              }
            }
          

中文解释

BaseAdapter 定义了统一接口：所有提供商都必须实现 sendRequest 和 translateResponse 两个方法。

DeepSeekAdapter 继承基类，在 sendRequest 里把 Anthropic 的消息格式转换成 DeepSeek（兼容 OpenAI）格式。

translateResponse 把 DeepSeek 返回的 OpenAI 格式响应翻译回 Anthropic 格式。

同样的模式，再写 OllamaAdapter、OpenRouterAdapter……每个适配器只关心格式转换，路由逻辑不用改。

🔌

想加新提供商？只写一个适配器。

适配器模式意味着添加新提供商不需要修改路由逻辑或 Claude Code 本身——只需要实现 sendRequest 和 translateResponse，注册到配置文件即可。

检验理解

为什么 Free Claude Code 使用适配器模式而不是为每个提供商写独立的服务？

05

调试与实战

理论到此结束。真实使用中你会遇到各种问题——这里教你怎么快速定位和解决。

四大常见问题

几乎所有 Free Claude Code 的新用户都会碰到这些问题。提前认识它们，出问题时就能快速定位：

🔌

连接失败

症状：Claude Code 报 "Connection refused" 或 "ECONNREFUSED"。原因：代理没启动，或端口被占用。解决：确认 node server.js 正在运行，检查 localhost:8080 是否可访问。

🚫

模型不可用

症状：404 或 "Model not found" 错误。原因：路由配置中的模型名拼写错误，或提供商下架了该模型。解决：检查提供商文档确认模型名，更新路由配置。

📋

响应格式错误

症状：Claude Code 崩溃或显示乱码。原因：适配器的格式转换有 bug，或提供商返回了非预期格式。解决：启用代理的 DEBUG 日志，检查原始响应内容，确认适配器版本。

🐌

延迟过高

症状：响应慢得像拨号上网。原因：网络链路太长（本地→代理→海外提供商），或本地模型推理太慢。解决：复杂任务用远程提供商，简单任务切本地模型；检查网络代理设置。

调试流程：六步排障法

遇到问题不要慌，按这六步逐层排查：

1

确认代理正在运行

终端执行 curl http://localhost:8080/health。如果无响应，启动代理服务。如果端口被占用，用 lsof -i :8080 查看占用进程。

2

检查 Claude Code 的 API 地址配置

确认环境变量 ANTHROPIC_BASE_URL=http://localhost:8080 已设置。在 Claude Code 中用 /config 命令查看当前配置。

3

查看代理日志

启用 DEBUG=1 环境变量重启代理。日志会显示收到的请求、路由决策、提供商的原始响应——这是定位问题的关键线索。

4

验证提供商 API 可用

跳过代理，直接 curl 提供商的 API 端点。如果直连也不通，说明是提供商侧的问题（限流、key 过期、服务宕机），不是代理的锅。

5

测试回退机制

如果主提供商有问题，检查回退链配置是否正确。临时把路由指向另一个可用的提供商，确认代理本身工作正常。

6

最小化复现

用最简单的请求测试：curl -X POST localhost:8080/v1/messages -H "Content-Type: application/json" -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'。如果这个都失败，问题在代理层；如果成功，问题在特定请求的格式。

💡

调试黄金法则

90% 的问题出在前三步。先确认"代理在跑"→"Claude Code 指向了代理"→"代理日志里能看到请求"。这三步通过，问题范围就缩小到提供商或适配器了。

The $0 AI coding setup

What you get

6 Provider Backends

Per-Model Routing

Voice Input

Bot Wrappers

The journey of an API call

Check your understanding

Why doesn't Claude Code need to be modified to work with Free Claude Code?

翻译官比喻

消息流动画

核心路由逻辑：代码 vs 人话

检验理解

Free Claude Code 作为代理的核心能力是什么？

为什么需要路由？

五种路由策略

Opus → OpenRouter

Sonnet → DeepSeek

Haiku → Ollama 本地

自定义规则

回退机制

检验理解

当你配置的路由中，主提供商突然不可用了，Free Claude Code 会怎么做？

六大提供商

适配器模式：统一接口的秘密

检验理解

为什么 Free Claude Code 使用适配器模式而不是为每个提供商写独立的服务？

四大常见问题

连接失败

模型不可用

响应格式错误

延迟过高

调试流程：六步排障法

最终检验

当 Free Claude Code 返回错误时，第一步应该做什么？

当 Claude Code 返回乱码或崩溃时，最可能的原因是什么，怎么定位？