和书籍生活在一起，永远不会叹气。——罗曼罗兰

Free Claude Code：一位“翻译官”站在你的终端里，让 Claude Code 免费开口说话

它叫 Free Claude Code。
一个轻量级的代理（proxy），专门把 Claude Code（CLI / VSCode 扩展）发出的 Anthropic API 请求，悄悄“改道”到别的地方去——比如 NVIDIA NIM（40 req/min 免费）、OpenRouter（海量模型）、DeepSeek（直连 API），甚至还能把对话带回家，交给 LM Studio / llama.cpp / Ollama 这类完全本地的模型服务器来处理。

它的仓库一句话介绍得很直白：

Use claude-code for free in the terminal, VSCode extension or via discord like openclaw

它像个擅长变装的向导：表面上你依然在用 Claude Code，实际上它已经在背后帮你把请求“领”到了你选的 LLM 供应商那里，并且尽力保持一切像 Anthropic 一样工作。

它会什么？（Features）

Free Claude Code 不是那种“只能跑起来”的工具，它更像一个认真做事的管家，习惯把细节也照顾好：

  • Zero Cost（零成本）
    NVIDIA NIM 提供 40 req/min 免费；OpenRouter 也有免费模型；想更安静？还能直接走 LM Studio / Ollama / llama.cpp，完全本地、无限制。

  • Drop-in Replacement（无痛替换）
    你不需要改 Claude Code CLI 或 VSCode 扩展。它只要求你设定 2 个环境变量，就能把 Claude Code 的“嘴”接到你想接的模型上。

  • 6 Providers（六大后端）
    NVIDIA NIM、OpenRouter、DeepSeek、LM Studio（本地）、llama.cpp（llama-server）、Ollama。

  • Per-Model Mapping（按 Opus/Sonnet/Haiku 分流）
    你可以把 “Opus / Sonnet / Haiku” 这三类请求分别送去不同的模型、不同的供应商，混搭也行。

  • Thinking Token Support（思考块支持）
    它会解析 <think> 标签和 reasoning_content，把“思考内容”转换成 Claude 原生的 thinking blocks（在启用 thinking 时）。

  • Heuristic Tool Parser（工具调用自动解析）
    有些模型把 tool call 当文本吐出来，它会尝试自动把这些“文字化的工具调用”解析回结构化 tool use。

  • Request Optimization（请求优化）
    Claude Code 的一些“琐碎 API 请求”（比如 quota 探测、标题生成、前缀检测、建议模式、文件路径提取等）会被它在本地拦截并直接响应——省配额、省延迟。

  • Smart Rate Limiting（聪明的限流）
    包含滚动窗口节流 + 429 指数退避 + 可选并发上限。

  • Discord / Telegram Bot（远程操控）
    你可以在 Discord/Telegram 上发任务，让 Claude Code “远程自主编码”；支持树状线程、会话持久化、实时进度。

  • Subagent Control（子代理控制）
    它会拦截 task 工具，强制 run_in_background=False，防止子代理失控狂奔。

  • Extensible（易扩展）
    提供干净的 BaseProvider 与 MessagingPlatform 抽象类（ABC），想加新 provider 或新平台，有路可走。

Quick Start：把它请进来（并让它开始工作）

Prerequisites

先准备好它要用的“燃料”（API Key 或本地服务）：

  1. 选择一个提供商并获取 API key（或者用本地 provider）：

  2. 安装 Claude Code：https://github.com/anthropics/claude-code

安装 uv

Free Claude Code 选择了 uv 作为主要工具链（并且明确写了：本项目需要 Python 3.14）。

macOS/Linux：

1
2
3
4
5
6
7
8
# Recommended installer (works on macOS/Linux without relying on system pip)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Keep uv current if it is already installed
uv self update

# This project requires Python 3.14
uv python install 3.14

Windows PowerShell：

1
2
3
4
5
6
7
8
# Recommended installer (avoids relying on system pip)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Keep uv current if it is already installed
uv self update

# This project requires Python 3.14
uv python install 3.14

Clone & Configure：把它带回家，给它一份 .env

1
2
3
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .env

接下来，挑一个你喜欢的“后端人格”，把 .env 配好。

NVIDIA NIM（40 req/min free, recommended）

1
2
3
4
5
6
7
8
9
10
11
12
13
NVIDIA_NIM_API_KEY="nvapi-your-key-here"

MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
MODEL="nvidia_nim/z-ai/glm4.7"                     # fallback

# Per-Claude-model switches for provider reasoning requests and Claude thinking blocks.
# Blank per-model switches inherit ENABLE_MODEL_THINKING.
ENABLE_OPUS_THINKING=
ENABLE_SONNET_THINKING=
ENABLE_HAIKU_THINKING=
ENABLE_MODEL_THINKING=true

OpenRouter（hundreds of models��

1
2
3
4
5
6
OPENROUTER_API_KEY="sk-or-your-key-here"

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"     # fallback

DeepSeek（direct API）

1
2
3
4
5
6
DEEPSEEK_API_KEY="your-deepseek-key-here"

MODEL_OPUS="deepseek/deepseek-reasoner"
MODEL_SONNET="deepseek/deepseek-chat"
MODEL_HAIKU="deepseek/deepseek-chat"
MODEL="deepseek/deepseek-chat"                      # fallback

LM Studio（fully local, no API key）

1
2
3
4
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"         # fallback

llama.cpp（fully local, no API key）

1
2
3
4
5
6
LLAMACPP_BASE_URL="http://localhost:8080/v1"

MODEL_OPUS="llamacpp/local-model"
MODEL_SONNET="llamacpp/local-model"
MODEL_HAIKU="llamacpp/local-model"
MODEL="llamacpp/local-model"

Ollama（fully local, no API key）

1
2
3
4
5
6
OLLAMA_BASE_URL="http://localhost:11434"

MODEL_OPUS="ollama/llama3.1"
MODEL_SONNET="ollama/llama3.1"
MODEL_HAIKU="ollama/llama3.1"
MODEL="ollama/llama3.1"                             # fallback

Mix providers：让它学会“分身术”

每个 MODEL_* 都可以来自不同 provider，MODEL 作为兜底：

1
2
3
4
5
6
7
NVIDIA_NIM_API_KEY="nvapi-your-key-here"
OPENROUTER_API_KEY="sk-or-your-key-here"

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="nvidia_nim/z-ai/glm4.7"                      # fallback

Optional Authentication：给它一把门锁（可选）

如果你把代理跑在公共网络上，或者你想让别人用、但不想随便谁都能用，那么可以设置：

1
ANTHROPIC_AUTH_TOKEN="your-secret-token-here"

它的规则很清楚：

  • 若 ANTHROPIC_AUTH_TOKEN 为空（默认），则不需要鉴权（兼容旧用法）
  • 若设置了，则客户端必须通过 ANTHROPIC_AUTH_TOKEN header 提供同样的 token
  • claude-pick 脚本会自动从 .env 读取 token（如果你配置了）

示例：

1
2
3
4
5
6
# With authentication
ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \
ANTHROPIC_BASE_URL="http://localhost:8082" claude

# claude-pick automatically uses the configured token
claude-pick

Run It：两扇门，一边是代理，一边是 Claude Code

它很像一位站在门口的接待员：你先让它站好岗，然后再让 Claude Code 走进来。

Terminal 1：启动代理服务

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

Terminal 2：启动 Claude Code，并把它引到代理门口

注意：ANTHROPIC_BASE_URL 要指向代理的根 URL，不是 http://localhost:8082/v1。

PowerShell：

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

Bash：

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

就这样。Claude Code 会以为自己在跟 Anthropic 说话，而 Free Claude Code 会把它的话转交给你配置的 provider。

VSCode Extension Setup：让 VSCode 也认识这位“翻译官”

  1. 启动代理（同上）。
  2. 打开 Settings（Ctrl + ,），搜索 claude-code.environmentVariables。
  3. 点击 Edit in settings.json，加入：
1
2
3
4
"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
]
  1. Reload extensions。
  2. 如果你看到登录界面：点击 Anthropic Console 授权。扩展会开始工作。浏览器可能把你带去购买 credits；忽略它即可。

切回 Anthropic 官方模型：把新增块注释掉并 reload extensions。

IntelliJ Extension Setup：让 JetBrains 也跟上节奏

  1. 打开配置文件：
    • Windows：C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
    • Linux/macOS：~/.jetbrains/acp.json
  2. 找到 acp.registry.claude-acp，把：
1
"env": {}

改成：

1
2
3
4
"env": {
"ANTHROPIC_AUTH_TOKEN": "freecc",
"ANTHROPIC_BASE_URL": "http://localhost:8082"
}
  1. 启动代理 server
  2. 重启 IDE

Multi-Model Support（Model Picker）：它还会“递菜单”

它提供一个交互式模型选择器 claude-pick：每次启动 Claude 时，让你从当前 provider 的模型列表里挑一个，不用再去 .env 改来改去。

1）安装 fzf

1
brew install fzf        # macOS/Linux

2）加一个 alias

1
alias claude-pick="/absolute/path/to/free-claude-code/claude-pick"

然后 source ~/.zshrc 或 source ~/.bashrc，运行 claude-pick 即可。

如果你不想选菜单，它也支持固定模型别名：

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

Install as a Package：不 clone，也能把它请进系统里

它甚至准备好了“轻装上阵”的方式：

1
2
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git
fcc-init        # creates ~/.config/free-claude-code/.env from the built-in template

编辑 ~/.config/free-claude-code/.env（填 API keys 和模型名），然后：

1
free-claude-code    # starts the server

更新方式也写得很干脆：

1
uv tool upgrade free-claude-code

How It Works：它如何把“Claude 的话”送到别处

它的工作像一条透明的管道：

1
2
3
4
5
6
┌─────────────────┐        ┌──────────────────────┐        ┌───────────────┐
│  Claude Code    │───────>│  Free Claude Code    │───────>│  LLM Provider  │
│  CLI / VSCode   │<───────│  Proxy (:8082)       │<───────│  NIM / OR / LMS │
└─────────────────┘        └──────────────────────┘        └───────────────┘
   Anthropic API                                             Native Anthropic
   format (SSE)                                             or OpenAI chat SSE

它的性格特点很鲜明：

  • 透明代理：Claude Code 发标准 Anthropic API；它负责转发到你配置的 provider
  • 按模型分流：Opus / Sonnet / Haiku 各自解析到各自后端，MODEL 兜底
  • 请求优化：拦截并本地响应一些“琐碎请求”，节省额度与延迟
  • 格式处理：OpenRouter / LM Studio / llama.cpp / Ollama 走原生 Anthropic Messages；NIM 与 DeepSeek 走 OpenAI chat 的共享翻译层
  • 思考 tokens：在 thinking 开关开启时，把 <think> / reasoning_content 转成 Claude 原生 thinking blocks

并且它暴露 Claude 兼容的探测路由：
GET /v1/models、POST /v1/messages、POST /v1/messages/count_tokens，以及常见探测端点的 HEAD/OPTIONS。

Providers：它认识的朋友们

Provider Cost Rate Limit Best For
NVIDIA NIM Free 40 req/min Daily driver, generous free tier
OpenRouter Free / Paid Varies Model variety, fallback options
DeepSeek Usage-based Varies Direct access to DeepSeek chat/reasoner
LM Studio Free (local) Unlimited Privacy, offline use, no rate limits
llama.cpp Free (local) Unlimited Lightweight local inference engine
Ollama Free (local) Unlimited Easy local LLM runtime, native Anthropic API

模型名采用前缀格式：provider_prefix/model/name。前缀错了，它会报错（它很认真，不会装作没看见）。

Provider MODEL prefix API Key Variable Default Base URL
NVIDIA NIM nvidia_nim/... NVIDIA_NIM_API_KEY integrate.api.nvidia.com/v1
OpenRouter open_router/... OPENROUTER_API_KEY openrouter.ai/api/v1
DeepSeek deepseek/... DEEPSEEK_API_KEY api.deepseek.com
LM Studio lmstudio/... (none) localhost:1234/v1
llama.cpp llamacpp/... (none) localhost:8080/v1
Ollama ollama/... (none) localhost:11434

Discord Bot：把 Claude Code 放进聊天软件里“远程驾驶”

它不满足于只在你本机乖乖工作，它还愿意当你的“远程执行者”。

你可以在 Discord（或 Telegram）发任务、看进度、管理会话，它自称能力包括：

  • 树状线程：回复某条消息就能分叉对话
  • 会话持久化：重启服务也不丢
  • 实时流式输出：thinking tokens、tool calls、结果都能直播
  • 不限并发 Claude CLI 会话（并发由 PROVIDER_MAX_CONCURRENCY 控制）
  • 语音消息：语音会被转写再当 prompt 处理
  • 命令：/stop、/clear、/stats

Discord Setup（按 README 的步骤来）

  1. 在 Discord Developer Portal 创建 Bot，拿 token，开启 Message Content Intent。
  2. 配 .env：
1
2
3
MESSAGING_PLATFORM="discord"
DISCORD_BOT_TOKEN="your_discord_bot_token"
ALLOWED_DISCORD_CHANNELS="123456789,987654321"
  1. 配 workspace（Claude 在哪里操作）：
1
2
CLAUDE_WORKSPACE="./agent_workspace"
ALLOWED_DIR="C:/Users/yourname/projects"
  1. 启动 server：
1
uv run uvicorn server:app --host 0.0.0.0 --port 8082
  1. 用 OAuth2 URL Generator 邀请 bot（scopes: bot，权限包含读写消息、管理消息、读历史）。

Telegram Setup

1
2
3
MESSAGING_PLATFORM=telegram
TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id"

Voice Notes：它还会听你说话

语音笔记支持两条路：

Backend Description API Key
Local Whisper (default) Hugging Face Whisper — free, offline, CUDA compatible not required
NVIDIA NIM Whisper/Parakeet models via gRPC NVIDIA_NIM_API_KEY

安装 voice extras（按 README 原文命令）：

1
2
3
4
5
6
7
8
9
# If you cloned the repo:
uv sync --extra voice_local          # Local Whisper
uv sync --extra voice                # NVIDIA NIM
uv sync --extra voice --extra voice_local  # Both

# If you installed as a package (no clone):
uv tool install "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"
uv tool install "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git"
uv tool install "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"

Configuration：它的开关很多，但都写在桌面上

它把配置分成了几大类：Core、Rate Limiting & Timeouts、Messaging & Voice、以及优化开关等。README 明确说：更多参数看 .env.example。

Core 里最关键的是这些（节选）：

  • MODEL：兜底模型（必须是 provider/model/name）
  • MODEL_OPUS / MODEL_SONNET / MODEL_HAIKU：按 Claude 模型层级分流
  • ENABLE_MODEL_THINKING 与 ENABLE_*_THINKING：思考块开关
  • PROVIDER_RATE_LIMIT / PROVIDER_RATE_WINDOW / PROVIDER_MAX_CONCURRENCY：限流与并发
  • LM_STUDIO_BASE_URL、LLAMACPP_BASE_URL、OLLAMA_BASE_URL：本地服务地址

它还默认开启了“请求优化”拦截开关（节选）：

  • FAST_PREFIX_DETECTION=true
  • ENABLE_NETWORK_PROBE_MOCK=true
  • ENABLE_TITLE_GENERATION_SKIP=true
  • ENABLE_SUGGESTION_MODE_SKIP=true
  • ENABLE_FILEPATH_EXTRACTION_MOCK=true

Development：如果你想看它怎么长大的

Project Structure

1
2
3
4
5
6
7
8
9
free-claude-code/
├── server.py              # Entry point
├── api/                   # FastAPI routes, API service layer, model routing, request detection, optimizations
├── core/                  # Shared Anthropic protocol helpers, SSE, conversion, parsers, token counting
├── providers/             # Provider registry, scoped runtime state, OpenAI chat + Anthropic messages transports
├── messaging/             # MessagingPlatform ABC + Discord/Telegram bots, commands, voice, session management
├── config/                # Settings, NIM config, logging
├── cli/                   # CLI session and process management
└── tests/                 # Pytest test suite

Commands（开发者日常四件套）

1
2
3
4
uv run ruff format     # Format code
uv run ruff check      # Lint
uv run ty check        # Type checking
uv run pytest          # Run tests

Extending：它欢迎新朋友加入舞会

README 给了扩展示例，像是在说：“你想加新 provider？可以，按这个姿势来。”

Adding an OpenAI-compatible provider（示例）

1
2
3
4
5
6
7
from providers.openai_compat import OpenAIChatTransport
from providers.base import ProviderConfig

class MyProvider(OpenAIChatTransport):
    def __init__(self, config: ProviderConfig):
        super().__init__(config, provider_name="MYPROVIDER",
                         base_url="https://api.example.com/v1", api_key=config.api_key)

还包括：

  • 加原生 Anthropic provider：继承 AnthropicMessagesTransport，然后在 providers.registry 注册
  • 加完全自定义 provider：继承 BaseProvider，实现 stream_response() 并注册
  • 加新消息平台：继承 MessagingPlatform，实现 start/stop/send_message/edit_message/on_message

Contributing：它想要的帮忙

它的心愿清单也写得坦白：

  • 在 Issues 报 bug 或提功能
  • 添加新的 LLM providers（Groq、Together AI 等）
  • 添加新的 messaging platforms（Slack 等）
  • 提升测试覆盖率
  • 暂时不接受 Docker 集成 PR

并且给了贡献流程：

1
2
3
git checkout -b my-feature
uv run ruff format && uv run ruff check && uv run ty check && uv run pytest
# Open a pull request

License

MIT License（MIT）。详见仓库的 LICENSE。

它还点名了自己的“搭档们”：FastAPI、OpenAI Python SDK、discord.py、python-telegram-bot。

结语：它不是在“替代 Claude”，而是在帮 Claude 找到更自由的路

Free Claude Code 更像一位礼貌但手段高明的“代理人”：
它不打扰你原本的使用习惯，不要求你重学工具，不让你改 Claude Code 的一行代码——它只是安静地站在 :8082，接住每一次请求，然后把请求送往你选的世界。

你可以让它把 Claude Code 的话交给 NVIDIA NIM 的免费额度；
也可以让它带着模型漫游 OpenRouter；
你甚至可以把这一切关进自己的电脑里，交给 LM Studio / llama.cpp / Ollama——让对话离你更近、更私密、更可控。

当 Claude Code 迈开脚步的时候，它就在旁边轻轻说一句：
“去吧，我来负责把路铺好。”