free-claude-code

代理工具，让 Claude Code CLI、VS Code 扩展和聊天机器人免费接入多种后端模型（NVIDIA NIM、Kimi、OpenRouter 等）。亮点是提供统一代理层，支持模型按层级路由、流式、工具调用和语音转录，且无需 Anthropic 付费 API。研究向，请遵守各提供商的使用条款。

README

🤖 Free Claude Code（自由克劳德代码）

通过你自己的 Anthropic 兼容代理，使用 Claude Code CLI、VS Code、JetBrains ACP 或聊天机器人。

Free Claude Code 将 Claude Code 的 Anthropic Messages API 流量路由到 NVIDIA NIM、Kimi、Wafer、OpenRouter、DeepSeek、LM Studio、llama.cpp 或 Ollama。它保持 Claude Code 的客户端协议稳定，同时让你选择免费、付费或本地模型。

快速开始 · 选择提供商 · 连接 Claude Code · 可选集成 · 开发

Star 历史（Star History）

你将获得

即插即用的代理，用于处理 Claude Code 的 Anthropic API 调用。
十个提供商后端：NVIDIA NIM、Kimi、Wafer、OpenRouter、DeepSeek、LM Studio、llama.cpp、Ollama、OpenCode Zen 和 Z.ai。
按模型路由：将 Opus、Sonnet、Haiku 以及回退流量发送到不同的提供商。
通过代理的 /v1/models 端点支持原生的 Claude Code /model 选择器（Claude Code 必须启用 Gateway 模型发现功能；参见模型选择器）。
流式传输、工具使用、推理/思考块处理、本地请求优化。
可选的 Discord 或 Telegram 机器人包装器，用于远程编码会话。
可选的通过 VSCode 扩展使用。
可选的通过本地 Whisper 或 NVIDIA NIM 进行语音笔记转录。
本地 管理 UI（Admin UI）位于 /admin，用于编辑支持的代理设置、验证更改并检查提供商（仅限回环访问）。

快速开始（Quick Start）

1. 安装最新版本的 Claude Code

npm install -g @anthropic-ai/claude-code

2. 安装运行时依赖

安装最新版本的 uv 和 Python 3.14。

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update
uv python install 3.14

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
uv python install 3.14

3. 获取 NVIDIA NIM API 密钥

创建一个免费的 NVIDIA NIM API 密钥，然后准备好用于管理 UI 的配置步骤。

参见 NVIDIA NIM 提供商设置。

4. 安装代理

uv tool install --force git+https://github.com/Alishahryar1/free-claude-code.git

使用相同的命令更新到最新版本。

5. 启动代理

fcc-server

启动后，Uvicorn 会打印代理绑定地址，应用程序会记录管理 URL：

INFO:     Admin UI: http://127.0.0.1:8082/admin (local-only)

许多终端中这些 URL 可点击。如果端口不是 8082，请使用你配置的 PORT。

6. 打开管理 UI 并配置 NVIDIA NIM

打开终端输出中的 Admin UI（管理 UI）URL。

将你的 NVIDIA NIM API 密钥粘贴到 NVIDIA_NIM_API_KEY 字段，然后点击 Validate（验证）和 Apply（应用）。

默认模型已设置为 nvidia_nim/z-ai/glm4.7。稍后你可以从同一个管理 UI 更改它。

7. 运行 Claude Code

fcc-claude

fcc-claude 每次启动时读取当前配置的端口和认证令牌，设置 Claude Code 环境变量（包括用于自动压缩的 190k tokens 的 CLAUDE_CODE_AUTO_COMPACT_WINDOW），然后启动真正的 claude 命令。

选择一个提供商（Choose A Provider）

选择一个提供商，在管理 UI 中输入其密钥或本地 URL，然后将 MODEL 设置为带提供商前缀的模型标识。MODEL 是回退。MODEL_OPUS、MODEL_SONNET 和 MODEL_HAIKU 可以覆盖 Claude Code 模型层次的路由。

1. NVIDIA NIM

在 build.nvidia.com/settings/api-keys 获取密钥。

在管理 UI 中，将其粘贴到 NVIDIA_NIM_API_KEY。默认的 MODEL 是 nvidia_nim/z-ai/glm4.7。

热门示例：

nvidia_nim/z-ai/glm4.7
nvidia_nim/z-ai/glm5
nvidia_nim/moonshotai/kimi-k2.5
nvidia_nim/minimaxai/minimax-m2.5

在 build.nvidia.com 浏览模型。

2. Kimi

在 platform.moonshot.ai/console/api-keys 获取密钥。

在管理 UI 中，将其粘贴到 KIMI_API_KEY，然后将 MODEL 设置为 Kimi 的标识，例如 kimi/kimi-k2.5。

在 platform.moonshot.ai 浏览模型。

3. Wafer

从 wafer.ai 获取密钥。在管理 UI 中，将其粘贴到 WAFER_API_KEY，然后将 MODEL 设置为 Wafer Pass 模型，例如 wafer/DeepSeek-V4-Pro。

热门示例：

wafer/DeepSeek-V4-Pro
wafer/MiniMax-M2.7
wafer/Qwen3.5-397B-A17B
wafer/GLM-5.1

该提供商使用 Wafer 的 Anthropic 兼容端点 https://pass.wafer.ai/v1/messages。

4. OpenRouter

在 openrouter.ai/keys 获取密钥。

在管理 UI 中，将其粘贴到 OPENROUTER_API_KEY，然后将 MODEL 设置为 OpenRouter 标识，例如 open_router/stepfun/step-3.5-flash:free。

浏览所有模型或免费模型。

5. DeepSeek

在 platform.deepseek.com/api_keys 获取密钥。

在管理 UI 中，将其粘贴到 DEEPSEEK_API_KEY，然后将 MODEL 设置为 DeepSeek 标识，例如 deepseek/deepseek-chat。

该提供商使用 DeepSeek 的 Anthropic 兼容端点，而非 OpenAI chat-completions 端点。

6. LM Studio

启动 LM Studio 的本地服务器并加载模型。在管理 UI 中，保留或更新 LM_STUDIO_BASE_URL，然后将 MODEL 设置为 LM Studio 显示的模型标识，前缀为 lmstudio/。

优先选择支持工具使用的模型，以用于 Claude Code 工作流。

7. llama.cpp

启动 llama-server，使其提供 Anthropic 兼容的 /v1/messages 端点，并具有足够处理 Claude Code 请求的上下文。

在管理 UI 中，保留或更新 LLAMACPP_BASE_URL，然后将 MODEL 设置为本地模型标识，前缀为 llamacpp/。

对于本地编码模型，上下文大小很重要。如果 llama.cpp 对正常的 Claude Code 请求返回 HTTP 400，请增加 --ctx-size，并验证模型/服务器构建是否支持请求的特性。

8. Ollama

运行 Ollama 并拉取模型：

ollama pull llama3.1
ollama serve

在管理 UI 中，保留或更新 OLLAMA_BASE_URL，然后将 MODEL 设置为与 ollama list 显示的相同标签，前缀为 ollama/。

OLLAMA_BASE_URL 是 Ollama 服务器的根地址；不要附加 /v1。示例模型标识包括 ollama/llama3.1 和 ollama/llama3.1:8b。

9. OpenCode Zen

在 opencode.ai/auth 获取 API 密钥。

在管理 UI 中，将其粘贴到 OPENCODE_API_KEY，然后将 MODEL 设置为 OpenCode Zen 模型标识，例如 opencode/gpt-5.3-codex。

OpenCode Zen 是一个精心策划的模型网关，通过一个 API 密钥和 OpenAI 兼容端点 https://opencode.ai/zen/v1 提供对 Anthropic、OpenAI、Google、DeepSeek 等模型的访问。

热门示例：

opencode/gpt-5.3-codex
opencode/claude-sonnet-4
opencode/deepseek-v4-flash-free（免费）
opencode/gemini-3-flash
opencode/big-pickle（免费）
opencode/glm-5.1

在 opencode.ai 浏览可用模型。

10. Z.ai

在 Z.ai/manage-apikey/apikey-list 获取 API 密钥。

在管理 UI 中，将其粘贴到 ZAI_API_KEY，然后将 MODEL 设置为 Z.ai 模型标识，例如 zai/glm-5.1。

Z.ai 通过 OpenAI 兼容的 Coding Plan 端点 https://api.z.ai/api/coding/paas/v4 提供 GLM 模型。

热门示例：

zai/glm-5.1
zai/glm-5-turbo

在 Z.ai 浏览模型。

11. 按模型层次混合提供商

通过在管理 UI 中设置 MODEL_OPUS、MODEL_SONNET 和 MODEL_HAIKU，每个模型层次可以使用不同的提供商。留空某个层次则继承 MODEL。

例如，你可以将 Opus 路由到 nvidia_nim/moonshotai/kimi-k2.5，Sonnet 路由到 open_router/deepseek/deepseek-r1-0528:free，Haiku 路由到 lmstudio/unsloth/GLM-4.7-Flash-GGUF，并将回退的 MODEL 保持在 zai/glm-5.1。

连接 Claude Code（Connect Claude Code）

1. Claude Code CLI

对于终端使用，建议使用安装的启动器：

fcc-claude

在工作时保持 fcc-server 运行。管理 UI 管理代理配置，当运行时设置更改时重启服务器，fcc-claude 每次启动时读取当前管理 UI 管理的端口和认证令牌。它还设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW 为 190000 以启用自动压缩。

2. VS Code 扩展

打开设置，搜索 claude-code.environmentVariables，选择 在 settings.json 中编辑，然后添加：

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },
  { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" }
]

重新加载扩展。如果扩展显示登录屏幕，请选择一次 Anthropic Console 路径；环境变量生效后，本地代理仍会处理模型流量。

3. JetBrains ACP

编辑已安装的 Claude ACP 配置：

Windows：C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
Linux/macOS：~/.jetbrains/acp.json

为 acp.registry.claude-acp 设置环境：

"env": {
  "ANTHROPIC_BASE_URL": "http://localhost:8082",
  "ANTHROPIC_AUTH_TOKEN": "freecc",
  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000"
}

修改文件后重启 IDE。

4. 模型选择器（Model Picker）

可选集成（Optional Integrations）

对于以下所有集成，仅在管理 UI /admin 中更改受管理的代理设置：编辑字段，点击 Validate（验证），然后点击 Apply（应用）。页脚显示受管理配置的存储位置；本 README 不会引导你手动编辑该文件。

1. Discord 和 Telegram 机器人

机器人包装器远程运行 Claude Code 会话，流式传输进度，支持基于回复的对话分支，并且可以停止或清除任务。

Discord

在 Discord Developer Portal 创建机器人。
启用 Message Content Intent（消息内容意图）。
使用读取、发送和消息历史权限邀请机器人。
复制机器人令牌和机器人应响应的数字频道 ID（或多个 ID）。

Telegram

通过 @BotFather 创建机器人并复制机器人令牌。
从 @userinfobot 获取你的数字用户 ID，以确保只有你可以使用机器人。

在管理 UI 中配置

在 fcc-server 运行时，从终端输出打开 Admin UI URL。
在侧边栏中选择 Messaging（消息）。
将 Messaging Platform（消息平台）设置为 discord 或 telegram。
对于 Discord，粘贴 Discord Bot Token（Discord 机器人令牌）和 Allowed Discord Channels（允许的 Discord 频道）。对于 Telegram，粘贴 Telegram Bot Token（Telegram 机器人令牌）和 Allowed Telegram User ID（允许的 Telegram 用户 ID）。
将 Allowed Directory（允许的目录）设置为运行代理的机器上的绝对路径——机器人可能会使用的工作区根目录。
点击 Validate（验证），然后点击 Apply（应用）。如果 UI 提示需要重启服务器，请重启。

管理 UI → Messaging（平台、机器人和语音）

有用的命令

/stop 取消任务；回复任务消息以仅停止该分支。
/clear 重置会话；回复以清除一个分支。
/stats 显示会话状态。

2. 语音笔记（Voice Notes）

语音笔记在 Discord 和 Telegram 上均可使用，但你需要使用相应的可选扩展扩展你的代理安装。重新运行 uv tool install --force 加上所需扩展（使用与快速开始相同的 Git URL）：

# NVIDIA NIM 转录（Riva gRPC）
uv tool install --force "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git"

# 本地 Whisper（CPU 或 CUDA）
uv tool install --force "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"

# 两个后端
uv tool install --force "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"

对于 cuda 本地 Whisper，在 voice_local 安装命令中添加 --torch-backend cu130。重新安装后重启 fcc-server。

在 Admin UI 中，打开 Messaging 并滚动到 Voice。启用 Voice Notes，选择 Whisper Device（Whisper 设备：cpu、cuda 或 nvidia_nim），设置 Whisper Model（Whisper 模型），并在需要时输入 Hugging Face Token（Hugging Face 令牌）。对于 nvidia_nim 转录，安装 voice 扩展并在 Providers 视图中设置 NVIDIA NIM API Key。上面的截图显示了同一视图中的 Voice 块。

工作原理（How It Works）

图表来源：assets/how-it-works.mmd。

重要部分：

FastAPI 暴露 Anthropic 兼容的路由，例如 /v1/messages、/v1/messages/count_tokens 和 /v1/models。
模型路由将 Claude 模型名称解析为 MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 或 MODEL。
NIM、OpenCode Zen、Z.ai 使用转换为 Anthropic SSE 的 OpenAI 聊天流式传输。
Wafer、OpenRouter、DeepSeek、LM Studio、llama.cpp 和 Ollama 使用 Anthropic Messages 风格传输。
代理将思考块、工具调用、令牌使用元数据和提供商错误规范化为 Claude Code 期望的格式。
请求优化会在本地处理简单的 Claude Code 探测，以减少延迟和配额消耗。

开发（Development）

1. 项目结构

free-claude-code/
├── server.py              # ASGI 入口点
├── api/                   # FastAPI 路由、服务层、路由、优化
├── core/                  # 共享的 Anthropic 协议辅助和 SSE 工具
├── providers/             # 提供商传输、注册、速率限制
├── messaging/             # Discord/Telegram 适配器、会话、语音
├── cli/                   # 包入口点和 Claude 进程管理
├── config/                # 设置、提供商目录、日志
└── tests/                 # 单元测试和契约测试

2. 从源码运行

如果你正在开发或希望直接从检出目录运行，使用此路径：

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
uv run uvicorn server:app --host 0.0.0.0 --port 8082

3. 命令

uv run ruff format
uv run ruff check
uv run ty check
uv run pytest

在推送之前按此顺序运行它们。CI 会强制进行相同的检查。

4. 包脚本

pyproject.toml 安装以下可执行文件：

fcc-server：使用配置的主机和端口启动代理。
fcc-init：可选的 ~/.fcc/.env 高级脚手架；日常配置请使用 Admin UI。
fcc-claude：使用配置的本地代理 URL、认证令牌、模型发现标志以及用于自动压缩的 190k CLAUDE_CODE_AUTO_COMPACT_WINDOW 启动 Claude Code。
free-claude-code：fcc-server 的兼容别名。

5. 扩展

通过扩展 OpenAIChatTransport 添加兼容 OpenAI 的提供商。
通过扩展 AnthropicMessagesTransport 添加 Anthropic Messages 提供商。
在 config.provider_catalog 中注册提供商的元数据，并在 providers.registry 中注册工厂接线。
通过实现 messaging/ 中的 MessagingPlatform 接口添加消息平台。

贡献（Contributing）

.env.example 列出了作为贡献者只读参考的环境变量键名；请使用 Admin UI 更改受管理的代理设置。
在 Issues 中报告错误和功能请求。
保持更改范围小，并附带集中的测试。
不要提交 Docker 集成的 PR。
不要提交仅修改 README 的 PR，只为此提交 Issue。
在提交拉取请求之前运行完整的检查序列。
语法 except X, Y 将在 Python 3.14 最终版本（而非 3.14 alpha）中恢复。在提交 PR 前请注意这一点。

许可证（License）

MIT 许可证。详情见 LICENSE。

开源项目Alishahryar12026-05-19原文

打开互动版

free-claude-code

README

🤖 Free Claude Code（自由克劳德代码）

Star 历史（Star History）

你将获得

快速开始（Quick Start）

1. 安装最新版本的 Claude Code

2. 安装运行时依赖

3. 获取 NVIDIA NIM API 密钥

4. 安装代理

5. 启动代理

6. 打开管理 UI 并配置 NVIDIA NIM

7. 运行 Claude Code

选择一个提供商（Choose A Provider）

1. NVIDIA NIM

2. Kimi

3. Wafer

4. OpenRouter

5. DeepSeek

6. LM Studio

7. llama.cpp

8. Ollama

9. OpenCode Zen

10. Z.ai

11. 按模型层次混合提供商

连接 Claude Code（Connect Claude Code）

1. Claude Code CLI

2. VS Code 扩展

3. JetBrains ACP

4. 模型选择器（Model Picker）

可选集成（Optional Integrations）

1. Discord 和 Telegram 机器人

2. 语音笔记（Voice Notes）

工作原理（How It Works）

开发（Development）

1. 项目结构

2. 从源码运行

3. 命令

4. 包脚本

5. 扩展

贡献（Contributing）

许可证（License）

相关内容

warp

sim

superpowers

skills

skills