free-claude-code 开源代理：让 Claude Code 接入 NVIDIA NIM 等 10 家模型后端

Claude Code running via NVIDIA NIM, completely free

Features

Quick Start

Prerequisites

1. Get an API key (or use LM Studio locally):
   • NVIDIA NIM: build.nvidia.com/settings/api-keys
   • OpenRouter: openrouter.ai/keys
   • LM Studio: No API key needed. Run locally with LM Studio
2. Install Claude Code
3. Install uv
4. Update uv if already installed: uv self update

Clone & Configure

git clone https://github.com/Rishurajgautam24/free-claude-code.git
cd free-claude-code
cp .env.example .env

Choose your provider and edit .env:

NVIDIA NIM (40 req/min free, recommended)

NVIDIA_NIM_API_KEY="nvapi-your-key-here"

MODEL_OPUS="nvidia_nim/z-ai/glm4.7"
MODEL_SONNET="nvidia_nim/moonshotai/kimi-k2-thinking"
MODEL_HAIKU="nvidia_nim/stepfun-ai/step-3.5-flash"
MODEL="nvidia_nim/z-ai/glm4.7"                     # fallback

OpenRouter (hundreds of models)

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

LM Studio (fully local, no API key)

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

Groq, Gemini, Ollama & any OpenAI-compatible API

Built-in presets only need an API key; use the provider name as the MODEL prefix:

GROQ_API_KEY="gsk_..."            # also: CEREBRAS_, GEMINI_, MISTRAL_, DEEPSEEK_, TOGETHER_API_KEY
MODEL="groq/llama-3.3-70b-versatile"
MODEL_HAIKU="gemini/gemini-2.5-flash"   # needs GEMINI_API_KEY

Local Ollama needs no key (OLLAMA_BASE_URL defaults to http://localhost:11434/v1):

MODEL="ollama/qwen3-coder"

Anything else that speaks the OpenAI chat API (vLLM, llama.cpp server, a company gateway, ...):

CUSTOM_BASE_URL="https://llm.example.com/v1"
CUSTOM_API_KEY="..."              # optional
MODEL="custom/my-model"

Mix providers (use multiple providers together)

Each MODEL_* variable can use a different provider. MODEL is the default for Claude models without their own setting.

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

Fallback chains (never get stuck on a down or rate-limited model)

Any MODEL* variable can list several models, separated by commas. They are tried in order: if a model fails before it sends any output (server error, rate limit after retries, timeout, connection error), the request is replayed on the next one. Claude Code just sees a normal answer.

MODEL_SONNET="nvidia_nim/z-ai/glm4.7,open_router/arcee-ai/trinity-large-preview:free,lmstudio/qwen3-coder"

• Mix providers freely: each one keeps its own rate limits, so a 429 on NIM doesn't slow down OpenRouter.
• An error after the answer has started, or on the last model, is shown as usual.
• The proxy logs every switch as MODEL_FALLBACK in server.log.

Run It

Terminal 1: Start the proxy server:

uv run uvicorn server:app --port 8082

Terminal 2: Run Claude Code:

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

That's it! Claude Code now uses your configured provider for free.

Remote access & security (WSL, Docker, another machine)

By default the proxy only accepts connections from this machine. To reach it from elsewhere:

PROXY_AUTH_TOKEN="pick-a-long-random-string"

uv run uvicorn server:app --host 0.0.0.0 --port 8082
ANTHROPIC_AUTH_TOKEN="pick-a-long-random-string" ANTHROPIC_BASE_URL="http://<proxy-ip>:8082" claude

When PROXY_AUTH_TOKEN is set, every API call must send it (Authorization: Bearer or x-api-key); /health stays open. Never expose the proxy without it: anyone who can reach it could spend your provider quota.

VSCode Extension Setup

1. Start the proxy server (same as above).
2. Open Settings (Ctrl + ,) and search for claude-code.environmentVariables.
3. Click Edit in settings.json and add:

"claude-code.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
]

1. Reload extensions.
2. If you see the login screen ("How do you want to log in?"): Click Anthropic Console, then authorize. The extension will start working. You may be redirected to buy credits in the browser; ignore it, the extension already works.

To switch back to Anthropic models, comment out the added block and reload extensions.

Switch models inside Claude Code (/model picker)

The proxy lists every model from your MODEL* settings (fallback chains included) at /v1/models. Turn on Claude Code's gateway model discovery and they show up in /model, labelled with the setting that uses them:

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

Picking one (its ID looks like claude-fcc/groq/llama-3.3-70b-versatile) sends that session's requests straight to that model; you can also start with it: claude --model claude-fcc/<provider>/<model>. Claude Code refreshes the list at each startup.

Multi-Model Support (Model Picker)

claude-pick is an interactive model selector that lets you choose any model from your active provider each time you launch Claude, without editing MODEL in .env.

Screen.Recording.2026-02-18.at.5.48.41.PM.mov

1. Install fzf (highly recommended for the interactive picker):

brew install fzf        # macOS/Linux

2. Add the alias to ~/.zshrc or ~/.bashrc:

# Use the absolute path to your cloned repo
alias claude-pick="/absolute/path/to/free-claude-code/claude-pick"

Then reload your shell (source ~/.zshrc or source ~/.bashrc) and run claude-pick to pick a model and launch Claude.

Under the hood the picker sends the model in the token as <token>:provider/model (the token is PROXY_AUTH_TOKEN, or freecc when that's unset), which overrides the model from .env for that session.

Skip the picker with a fixed model (no picker needed):

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

How It Works

┌─────────────────┐        ┌──────────────────────┐        ┌──────────────────┐
│  Claude Code    │───────>│  Free Claude Code    │───────>│  LLM Provider    │
│  CLI / VSCode   │<───────│  Proxy (:8082)       │<───────│  NIM / OR / LMS  │
└─────────────────┘        └──────────────────────┘        └──────────────────┘
   Anthropic API                     │                       OpenAI-compatible
   format (SSE)              ┌───────┴────────┐                format (SSE)
                             │ Optimizations  │
                             ├────────────────┤
                             │ Quota probes   │
                             │ Title gen skip │
                             │ Prefix detect  │
                             │ Suggestion skip│
                             │ Filepath mock  │
                             └────────────────┘

• Transparent proxy: Claude Code sends standard Anthropic API requests to the proxy server
• Per-model routing: Opus / Sonnet / Haiku requests are resolved to their model-specific backend and provider, with the default MODEL as fallback
• Request optimization: 5 categories of trivial requests (quota probes, title generation, prefix detection, suggestions, filepath extraction) are intercepted and responded to instantly without using API quota
• Format translation: real requests are translated from Anthropic format to the provider's OpenAI-compatible format and streamed back. Mid-conversation system messages that current Claude Code sends become user turns, since many models only accept a leading system prompt
• Thinking tokens: <think> tags and reasoning_content fields are converted into native Claude thinking blocks so Claude Code renders them correctly. Reasoning is only switched on (NIM, OpenRouter) when Claude Code asks for thinking (adaptive or enabled), so side requests like compaction don't spend reasoning tokens
• Output limits: Claude Code asks for up to 128k output tokens, more than many models allow. When a provider rejects that and states its limit (Groq, DeepSeek, OpenAI-style errors), the request is retried with that limit and the model is remembered. To pick a lower value yourself, set CLAUDE_CODE_MAX_OUTPUT_TOKENS when starting Claude Code
• Images: pasted images are sent as OpenAI image_url parts. If a model rejects them, the request is retried once without images and that model is remembered as text-only. Images inside tool results (e.g. Read on a PNG) become a short placeholder instead of raw base64
• Tool calls: native tool calls and tool calls a model writes as text become Anthropic tool_use blocks; a turn with tool calls always ends with stop_reason: tool_use
• Fallback chains: a model that fails before answering is skipped for the next model in its MODEL* chain
• Keepalive: the stream carries an SSE ping every 15s, so Claude Code's idle watchdog never cuts off a slow model

Providers

Switch providers by changing MODEL in .env. Use the prefix format provider/model/name. Invalid prefix causes an error. A provider whose key is missing answers with a clear error naming the variable to set.

LM Studio runs locally. Start the server in the Developer tab or via lms server start, load a model, and set MODEL to the model identifier.

Discord Bot

Control Claude Code remotely from Discord. Send tasks, watch live progress, and manage multiple concurrent sessions. Telegram is also supported.

Capabilities:

• Tree-based message threading: reply to a message to fork the conversation
• Session persistence across server restarts, crash-safe: sessions.json (in CLAUDE_WORKSPACE) is written atomically, and an unreadable file is kept as sessions.json.corrupt-<time> instead of being overwritten
• Live streaming of thinking tokens, tool calls, and results
• Unlimited concurrent Claude CLI sessions (provider concurrency controlled by PROVIDER_MAX_CONCURRENCY)
• Voice notes: send voice messages; they are transcribed and processed like regular prompts (see Voice Notes)
• Commands: /stop (cancel tasks; reply to a message to stop only that task), /clear (standalone: reset all sessions; reply to a message to clear that branch downwards), /stats

Setup

1. Create a Discord Bot: Go to Discord Developer Portal, create an application, add a bot, and copy the token. Enable Message Content Intent under Bot settings.

2. Edit .env:

MESSAGING_PLATFORM="discord"
DISCORD_BOT_TOKEN="your_discord_bot_token"
ALLOWED_DISCORD_CHANNELS="123456789,987654321"

Enable Developer Mode in Discord (Settings → Advanced), then right-click a channel and "Copy ID" to get channel IDs. Comma-separate multiple channels. If empty, no channels are allowed.

1. Configure the workspace (where Claude will operate):

CLAUDE_WORKSPACE="./agent_workspace"
ALLOWED_DIR="C:/Users/yourname/projects"

1. Start the server:

uv run uvicorn server:app --port 8082

1. Invite the bot (OAuth2 URL Generator, scopes: bot, permissions: Read Messages, Send Messages, Manage Messages, Read Message History). Send a task to an allowed channel and Claude responds with live thinking tokens and tool calls. Use commands above to cancel or clear.

Telegram (Alternative)

To use Telegram instead, set MESSAGING_PLATFORM=telegram and configure:

TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id"

Get a token from @BotFather; find your user ID via @userinfobot.

Voice Notes

Send voice messages on Telegram or Discord; they are transcribed to text and processed as regular prompts. Two transcription backends are available:

• Local Whisper (default): Uses Hugging Face transformers Whisper — free, no API key, works offline, CUDA compatible. No ffmpeg required.
• NVIDIA NIM: Uses NVIDIA NIM Whisper/Parkeet models via gRPC — requires NVIDIA_NIM_API_KEY.

Install the optional voice extras:

# For local Whisper (cpu/cuda)
uv sync --extra voice_local

# For NVIDIA NIM transcription
uv sync --extra voice

# Install both
uv sync --extra voice --extra voice_local

Configuration:

Supported WHISPER_MODEL values:

Models

NVIDIA NIM

Full list in nvidia_nim_models.json.

Popular models:

• nvidia_nim/minimaxai/minimax-m2.5
• nvidia_nim/qwen/qwen3.5-397b-a17b
• nvidia_nim/z-ai/glm5
• nvidia_nim/stepfun-ai/step-3.5-flash
• nvidia_nim/moonshotai/kimi-k2.5

Browse: build.nvidia.com

Update model list:

curl "https://integrate.api.nvidia.com/v1/models" > nvidia_nim_models.json

OpenRouter

Hundreds of models from StepFun, OpenAI, Anthropic, Google, and more.

Popular models:

• open_router/stepfun/step-3.5-flash:free
• open_router/deepseek/deepseek-r1-0528:free
• open_router/openai/gpt-oss-120b:free

Browse: openrouter.ai/models

Browse free models: https://openrouter.ai/collections/free-models

LM Studio

Run models locally with LM Studio. Load a model in the Chat or Developer tab, then set MODEL to its identifier.

Examples (native tool-use support):

• LiquidAI/LFM2-24B-A2B-GGUF
• unsloth/MiniMax-M2.5-GGUF
• unsloth/GLM-4.7-Flash-GGUF
• unsloth/Qwen3.5-35B-A3B-GGUF
• LocoreMind/LocoOperator-4B

Browse: model.lmstudio.ai

Configuration

See .env.example for all supported parameters.

Development

Project Structure

free-claude-code/
├── server.py              # Entry point
├── api/                   # FastAPI routes, request detection, optimization handlers
├── providers/             # BaseProvider, OpenAICompatibleProvider, NIM, OpenRouter, LM Studio
│   └── common/            # Shared utils (SSE builder, message converter, parsers, error mapping)
├── messaging/             # MessagingPlatform ABC + Discord/Telegram bots, session management
├── config/                # Settings, NIM config, logging
├── cli/                   # CLI session and process management
└── tests/                 # Pytest test suite

Commands

uv run ruff format     # Format code
uv run ruff check      # Code style checking
uv run ty check        # Type checking
uv run pytest          # Run tests

Extending

Adding a Provider

For OpenAI-compatible APIs (Groq, Together AI, etc.), extend OpenAICompatibleProvider:

from providers.openai_compat import OpenAICompatibleProvider
from providers.base import ProviderConfig

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

    def _build_request_body(self, request):
        return build_request_body(request)  # Your request builder

For fully custom APIs, extend BaseProvider directly:

from providers.base import BaseProvider, ProviderConfig

class MyProvider(BaseProvider):
    async def stream_response(self, request, input_tokens=0, *, request_id=None):
        # Yield Anthropic SSE format events
        ...

Adding a Messaging Platform

Extend MessagingPlatform in messaging/ to add Slack or other platforms:

from messaging.base import MessagingPlatform

class MyPlatform(MessagingPlatform):
    async def start(self):
        # Initialize connection
        ...

    async def stop(self):
        # Cleanup
        ...

    async def send_message(self, chat_id, text, reply_to=None, parse_mode=None, message_thread_id=None):
        # Send a message
        ...

    async def edit_message(self, chat_id, message_id, text, parse_mode=None):
        # Edit an existing message
        ...

    def on_message(self, handler):
        # Register callback for incoming messages
        ...

Contributing

• Report bugs or suggest features via Issues
• Add new LLM providers (Groq, Together AI, etc.)
• Add new messaging platforms (Slack, etc.)
• Improve test coverage
• Not accepting Docker Integration for now
• New and interesting features

# Fork the repo, then:
git checkout -b my-feature
# Make your changes
uv run ruff format && uv run ruff check && uv run ty check && uv run pytest
# Open a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Built with FastAPI, OpenAI Python SDK, discord.py, and python-telegram-bot.