Alishahryar1/free-claude-code

## 功能 | 功能 | 描述 | | -------------------------- | ----------------------------------------------------------------------------------------------- | | **零成本** | NVIDIA NIM 免费 40 请求/分钟。OpenRouter 上有免费模型。通过 LM Studio 完全免费本地运行 | | **即插即用** | 设置 2 个环境变量。无需修改 Claude Code CLI 或 VSCode 扩展 | | **4 种提供商** | NVIDIA NIM、OpenRouter（数百个模型）、LM Studio（本地）、llama.cpp (`llama-server`) | | **按模型映射** | 将 Opus / Sonnet / Haiku 路由到不同的模型和提供商。自由混合使用提供商 | | **思考 Token 支持** | 将 `threadshadow` 标签和 `reasoning_content` 解析为原生 Claude thinking blocks | | **启发式工具解析器** | 将作为文本输出工具调用的模型自动解析为结构化工具调用 | | **请求优化** | 5 类琐碎 API 调用在本地拦截，节省配额和延迟 | | **智能限流** | 主动滑动窗口节流 + 被动 429 指数退避 + 可选并发上限 | | **Discord / Telegram 机器人** | 远程自主编程，支持基于树的线程、会话持久化和实时进度 | | **子代理控制** | Task 工具拦截强制 `run_in_background=False`。防止子代理失控 | | **可扩展** | 简洁的 `BaseProvider` 和 `MessagingPlatform` ABCs。轻松添加新提供商或平台 | ## 快速开始 ### 前置条件 1. 获取 API key（或在本地使用 LM Studio / llama.cpp）： - **NVIDIA NIM**: [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys) - **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys) - **LM Studio**: 无需 API key。在本地运行 [LM Studio](https://lmstudio.ai) - **llama.cpp**: 无需 API key。在本地运行 `llama-server`。 2. 安装 [Claude Code](https://github.com/anthropics/claude-code) ### 安装 `uv` ``` # 安装 uv（运行项目需） pip install uv ``` 如果 uv 已安装，运行 uv self update 以获取最新版本。 ### 克隆并配置 ``` git clone https://github.com/Alishahryar1/free-claude-code.git cd free-claude-code cp .env.example .env ``` 选择你的提供商并编辑 `.env`：

NVIDIA NIM（免费 40 请求/分钟，推荐）

``` 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 # 为 thinking models（kimi, nemotron）启用。其他模型（如 Mistral）请保留 false。 NIM_ENABLE_THINKING=true ```

OpenRouter（数百个模型）

``` 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（完全本地，无需 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 ```

llama.cpp（完全本地，无需 API key）

``` 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" ```

混合使用提供商

每个 `MODEL_*` 变量可以使用不同的提供商。`MODEL` 是未识别的 Claude 模型的后备选项。 ``` 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 ```

可选身份验证（限制对你的代理的访问）

在 `.env` 中设置 `ANTHROPIC_AUTH_TOKEN` 以要求客户端进行身份验证： ``` ANTHROPIC_AUTH_TOKEN="your-secret-token-here" ``` **工作原理：** - 如果 `ANTHROPIC_AUTH_TOKEN` 为空（默认），则不需要身份验证（向后兼容） - 如果已设置，客户端必须通过 `ANTHROPIC_AUTH_TOKEN` 头提供相同的 token - 如果已配置，`claude-pick` 脚本会自动从 `.env` 读取 token **使用示例：** ``` # 使用认证 ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \ ANTHROPIC_BASE_URL="http://localhost:8082" claude # claude-pick 自动使用已配置的 token claude-pick ``` 在以下情况下使用此功能： - 在公共网络上运行代理 - 与他人共享服务器但限制访问 - 需要额外的安全层

### 运行 **终端 1：** 启动代理服务器： ``` uv run uvicorn server:app --host 0.0.0.0 --port 8082 ``` **终端 2：** 运行 Claude Code： #### Powershell ``` $env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude ``` #### Bash ``` ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude ``` 完成！Claude Code 现在可以免费使用你配置的提供商了。

VSCode 扩展设置

1. 启动代理服务器（同上）。 2. 打开设置（`Ctrl + ,`）并搜索 `claude-code.environmentVariables`。 3. 点击 **在 settings.json 中编辑** 并添加： ``` "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" } ] ``` 4. 重新加载扩展。 5. **如果你看到登录界面**：点击 **Anthropic Console**，然后授权。扩展将开始工作。你可能会在浏览器中被重定向购买积分；忽略它 —— 扩展已经可以工作了。 要切回 Anthropic 模型，请注释掉添加的块并重新加载扩展。

多模型支持（模型选择器）

`claude-pick` 是一个交互式模型选择器，让你在每次启动 Claude 时从活动的提供商中选择任何模型，而无需在 `.env` 中编辑 `MODEL`。 https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645 **1. 安装 [fzf](https://github.com/junegunn/fzf)**： ``` brew install fzf # macOS/Linux ``` **2. 将别名添加到 `~/.zshrc` 或 `~/.bashrc`：** ``` alias claude-pick="/absolute/path/to/free-claude-code/claude-pick" ``` 然后重新加载 shell（`source ~/.zshrc` 或 `source ~/.bashrc`）并运行 `claude-pick`。 **或者使用固定模型别名**（无需选择器）： ``` alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude' ```

### 作为包安装（无需克隆） ``` 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 ``` 使用你的 API key 和模型名称编辑 `~/.config/free-claude-code/.env`，然后： ``` free-claude-code # starts the server ``` ## 工作原理 ``` ┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │ Claude Code │───────>│ Free Claude Code │───────>│ LLM Provider │ │ CLI / VSCode │<───────│ Proxy (:8082) │<───────│ NIM / OR / LMS │ └─────────────────┘ └──────────────────────┘ └──────────────────┘ Anthropic API OpenAI-compatible format (SSE) format (SSE) ``` - **透明代理**：Claude Code 发送标准 Anthropic API 请求；代理将其转发到你配置的提供商 - **按模型路由**：Opus / Sonnet / Haiku 请求解析为其特定模型的后端，`MODEL` 作为后备 - **请求优化**：5 类琐碎请求（配额探测、标题生成、前缀检测、建议、文件路径提取）在本地拦截并响应，无需使用 API 配额 - **格式转换**：请求从 Anthropic 格式转换为提供商的 OpenAI 兼容格式并流式传回 - **思考 token**：`threadshadow` 标签和 `reasoning_content` 字段被转换为本机 Claude thinking blocks ## 提供商 | 提供商 | 成本 | 速率限制 | 最佳用途 | | -------------- | ------------ | ---------- | ------------------------------------ | | **NVIDIA NIM** | 免费 | 40 请求/分钟 | 日常主力，慷慨的免费层 | | **OpenRouter** | 免费 / 付费 | 不定 | 模型多样性，后备选项 | | **LM Studio** | 免费（本地） | 无限制 | 隐私，离线使用，无速率限制 | | **llama.cpp** | 免费（本地） | 无限制 | 轻量级本地推理引擎 | 模型使用前缀格式：`provider_prefix/model/name`。无效前缀会导致错误。 | 提供商 | `MODEL` 前缀 | API Key 变量 | 默认 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` | | LM Studio | `lmstudio/...` | (无) | `localhost:1234/v1` | | llama.cpp | `llamacpp/...` | (无) | `localhost:8080/v1` |

NVIDIA NIM 模型

热门模型（完整列表见 [`nvidia_nim_models.json`](nvidia_nim_models.json)）： - `nvidia_nim/minimaxai/minimax-m2.5` - `nvidia_nim/qwen/qwen3.5-397b-a17b` - `nvidia_nim/z-ai/glm5` - `nvidia_nim/moonshotai/kimi-k2.5` - `nvidia_nim/stepfun-ai/step-3.5-flash` 浏览：[build.nvidia.com](https://build.nvidia.com/explore/discover) · 更新列表：`curl "https://integrate.api.nvidia.com/v1/models" > nvidia_nim_models.json`

OpenRouter 模型

热门免费模型： - `open_router/arcee-ai/trinity-large-preview:free` - `open_router/stepfun/step-3.5-flash:free` - `open_router/deepseek/deepseek-r1-0528:free` - `open_router/openai/gpt-oss-120b:free` 浏览：[openrouter.ai/models](https://openrouter.ai/models) · [免费模型](https://openrouter.ai/collections/free-models)

LM Studio 模型

使用 [LM Studio](https://lmstudio.ai) 在本地运行模型。在 Chat 或 Developer 标签页中加载模型，然后将 `MODEL` 设置为其标识符。 支持原生工具调用的示例： - `LiquidAI/LFM2-24B-A2B-GGUF` - `unsloth/MiniMax-M2.5-GGUF` - `unsloth/GLM-4.7-Flash-GGUF` - `unsloth/Qwen3.5-35B-A3B-GGUF` 浏览：[model.lmstudio.ai](https://model.lmstudio.ai)

llama.cpp 模型

使用 `llama-server` 在本地运行模型。确保你有支持工具调用的 GGUF。将 `MODEL` 设置为你喜欢的任意名称（例如 `llamacpp/my-model`），因为 `llama-server` 通过 `/v1/messages` 运行时会忽略模型名称。 有关详细说明和支持的模型，请参阅 Unsloth 文档： [https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b](https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b)

## Discord 机器人 从 Discord（或 Telegram）远程控制 Claude Code。发送任务，观看实时进度，并管理多个并发会话。 **功能：** - 基于树的消息线程：回复消息以分叉对话 - 服务器重启后的会话持久化 - 思考 token、工具调用和结果的实时流式传输 - 无限并发 Claude CLI 会话（并发由 `PROVIDER_MAX_CONCURRENCY` 控制） - 语音笔记：发送语音消息；它们会被转录并作为常规提示处理 - 命令：`/stop`（取消任务；回复消息仅停止该任务），`/clear`（重置所有会话，或回复以清除分支），`/stats` ### 设置 1. **创建 Discord 机器人**：前往 [Discord Developer Portal](https://discord.com/developers/applications)，创建应用程序，添加机器人，并复制 token。在 Bot 设置下启用 **Message Content Intent**。 2. **编辑 `.env`：** ``` MESSAGING_PLATFORM="discord" DISCORD_BOT_TOKEN="your_discord_bot_token" ALLOWED_DISCORD_CHANNELS="123456789,987654321" ``` 3. **配置工作区**（Claude 将在其中操作）： ``` CLAUDE_WORKSPACE="./agent_workspace" ALLOWED_DIR="C:/Users/yourname/projects" ``` 4. **启动服务器：** ``` uv run uvicorn server:app --host 0.0.0.0 --port 8082 ``` 5. **邀请机器人** 通过 OAuth2 URL 生成器（作用域：`bot`，权限：Read Messages、Send Messages、Manage Messages、Read Message History）。 ### Telegram 设置 `MESSAGING_PLATFORM=telegram` 并配置 ``` TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ" ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id" ``` 从 [@BotFather](https://t.me/BotFather) 获取 token；通过 [@userinfobot](https://t.me/userinfobot) 查找你的用户 ID。 ### 语音笔记 在 Discord 或 Telegram 上发送语音消息；它们会被转录并作为常规提示处理。 | 后端 | 描述 | API Key | | --------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- | | **Local Whisper**（默认） | [Hugging Face Whisper](https://huggingface.co/openai/whisper-large-v3-turbo) — 免费、离线、CUDA 兼容 | 不需要 | | **NVIDIA NIM** | 通过 gRPC 的 Whisper/Parakeet 模型 | `NVIDIA_NIM_API_KEY` | **安装语音扩展：** ``` # 如果你克隆了 repo： uv sync --extra voice_local # Local Whisper uv sync --extra voice # NVIDIA NIM uv sync --extra voice --extra voice_local # Both # 如果你作为 package 安装（未克隆）： 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" ``` 通过 `WHISPER_DEVICE`（`cpu` | `cuda` | `nvidia_nim`）和 `WHISPER_MODEL` 进行配置。有关所有语音变量和支持的模型值，请参阅 [配置](#configuration) 表。 ## 配置 ### 核心 | 变量 | 描述 | 默认值 | | -------------------- | --------------------------------------------------------------------- | ------------------------------------------------- | | `MODEL` | 后备模型（`provider/model/name` 格式；前缀无效 → 错误） | `nvidia_nim/stepfun-ai/step-3.5-flash` | | `MODEL_OPUS` | Claude Opus 请求的模型（回退到 `MODEL`） | `nvidia_nim/z-ai/glm4.7` | | `MODEL_SONNET` | Claude Sonnet 请求的模型（回退到 `MODEL`） | `open_router/arcee-ai/trinity-large-preview:free` | | `MODEL_HAIKU` | Claude Haiku 请求的模型（回退到 `MODEL`） | `open_router/stepfun/step-3.5-flash:free` | | `NVIDIA_NIM_API_KEY` | NVIDIA API key | NIM 必需 | | `NIM_ENABLE_THINKING` | 在 NIM 请求上发送 `chat_template_kwargs` + `reasoning_budget`。为思考模型启用；对于其他模型（例如 Mistral）保持 `false` | `false` | | `OPENROUTER_API_KEY` | OpenRouter API key | OpenRouter 必需 | | `LM_STUDIO_BASE_URL` | LM Studio 服务器 URL | `http://localhost:1234/v1` | | `LLAMACPP_BASE_URL` | llama.cpp 服务器 URL | `http://localhost:8080/v1` | ### 速率限制与超时 | 变量 | 描述 | 默认值 | | -------------------------- | ----------------------------------------- | ------- | | `PROVIDER_RATE_LIMIT` | 每个 LLM API 请求窗口的请求数 | `40` | | `PROVIDER_RATE_WINDOW` | 速率限制窗口（秒） | `60` | | `PROVIDER_MAX_CONCURRENCY` | 最大同时打开的提供商流 | `5` | | `HTTP_READ_TIMEOUT` | 提供商请求的读取超时（秒） | `120` | | `HTTP_WRITE_TIMEOUT` | 提供商请求的写入超时（秒） | `10` | | `HTTP_CONNECT_TIMEOUT` | 提供商请求的连接超时（秒） | `2` | ### 消息与语音 | 变量 | 描述 | 默认值 | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `MESSAGING_PLATFORM` | `discord` 或 `telegram` | `discord` | | `DISCORD_BOT_TOKEN` | Discord 机器人 token | `""` | | `ALLOWED_DISCORD_CHANNELS` | 逗号分隔的频道 ID（空 = 不允许任何频道） | `""` | | `TELEGRAM_BOT_TOKEN` | Telegram 机器人 token | `""` | | `ALLOWED_TELEGRAM_USER_ID` | 允许的 Telegram 用户 ID | `""` | | `CLAUDE_WORKSPACE` | 代理操作的目录 | `./agent_workspace` | | `ALLOWED_DIR` | 代理允许的目录 | `""` | | `MESSAGING_RATE_LIMIT` | 每个窗口的消息数 | `1` | | `MESSAGING_RATE_WINDOW` | 消息窗口（秒） | `1` | | `VOICE_NOTE_ENABLED` | 启用语音笔记处理 | `true` | | `WHISPER_DEVICE` | `cpu` \| `cuda` \| `nvidia_nim` | `cpu` | | `WHISPER_MODEL` | Whisper 模型（本地：`tiny`/`base`/`small`/`medium`/`large-v2`/`large-v3`/`large-v3-turbo`；NIM：`openai/whisper-large-v3`、`nvidia/parakeet-ctc-1.1b-asr` 等） | `base` | | `HF_TOKEN` | Hugging Face token，用于更快的下载（本地 Whisper，可选） | — |

高级：请求优化标志

这些默认启用，并在本地拦截琐碎的 Claude Code 请求以节省 API 配额。 | 变量 | 描述 | 默认值 | | --------------------------------- | ------------------------------ | ------- | | `FAST_PREFIX_DETECTION` | 启用快速前缀检测 | `true` | | `ENABLE_NETWORK_PROBE_MOCK` | 模拟网络探测请求 | `true` | | `ENABLE_TITLE_GENERATION_SKIP` | 跳过标题生成请求 | `true` | | `ENABLE_SUGGESTION_MODE_SKIP` | 跳过建议模式请求 | `true` | | `ENABLE_FILEPATH_EXTRACTION_MOCK` | 模拟文件路径提取 | `true` |

有关所有支持的参数，请参阅 [`.env.example`](.env.example)。 ## 开发 ### 项目结构 ``` free-claude-code/ ├── server.py # Entry point ├── api/ # FastAPI routes, request detection, optimization handlers ├── providers/ # BaseProvider, OpenAICompatibleProvider, NIM, OpenRouter, LM Studio, llamacpp │ └── 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 ``` ### 命令 ``` uv run ruff format # Format code uv run ruff check # Lint uv run ty check # Type checking uv run pytest # Run tests ``` ### 扩展 **添加 OpenAI 兼容提供商**（Groq、Together AI 等）——扩展 `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) ``` **添加完全自定义的提供商** ——直接扩展 `BaseProvider` 并实现 `stream_response()`。 **添加消息平台** ——在 `messaging/` 中扩展 `MessagingPlatform` 并实现 `start()`、`stop()`、`send_message()`、`edit_message()` 和 `on_message()`。 ## 贡献 - 通过 [Issues](https://github.com/Alishahryar1/free-claude-code/issues) 报告错误或建议功能 - 添加新的 LLM 提供商（Groq、Together AI 等） - 添加新的消息平台（Slack 等） - 改进测试覆盖率 - 暂不接受 Docker 集成 PR ``` git checkout -b my-feature uv run ruff format && uv run ruff check && uv run ty check && uv run pytest # 提交 pull request ``` ## 许可证 MIT 许可证。详情见 [LICENSE](LICENSE)。 使用 [FastAPI](https://fastapi.tiangolo.com/)、[OpenAI Python SDK](https://github.com/openai/openai-python)、[discord.py](https://github.com/Rapptz/discord.py) 和 [python-telegram-bot](https://python-telegram-bot.org/) 构建。

标签：AI 编程助手, Anthropic API, API 转换, Beacon Object File, Claude Code, Discord 机器人, IP 地址批量处理, llama.cpp, LM Studio, NVIDIA NIM, OpenRouter, PE 加载器, Python, VSCode 扩展, 云资产清单, 免费代理, 大模型网关, 开源, 无后门, 本地大模型, 终端工具, 轻量级代理, 逆向工具, 逆向工程