> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/Alishahryar1/free-claude-code) · [上游 README](https://github.com/Alishahryar1/free-claude-code/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# 🤖 Free Claude Code
通过你自己的提供商（provider）代理，使用 Claude Code、Codex、Pi、编辑器扩展或聊天机器人。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/uv)
[](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)
[](https://pypi.org/project/ty/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/Delgan/loguru)
使用免费、付费或本地模型运行你的编程代理（coding agents）。在本地 Admin UI 中选择一个提供商并完成验证。
[快速开始](#quick-start) · [提供商](#choose-a-provider) · [客户端](#connect-your-client) · [集成](#optional-integrations) · [管理](#manage-your-installation)
Claude Code 通过 Free Claude Code 代理运行。
Codex CLI 使用本地 FCC Responses 提供商。
Claude Code 原生 /model 选择器，展示 FCC 网关模型。
Codex 原生 /model 选择器，展示生成的 FCC 模型目录。
## Star History
## 你将获得什么
- 使用 `fcc-claude` 启动 Claude Code，使用 `fcc-codex` 启动 Codex，或使用 `fcc-pi` 启动 Pi。
- 在 Admin UI 中在 24 个云端与本地提供商之间切换。
- 使用各编程代理原生的模型选择器。
- 将 Opus、Sonnet、Haiku 及回退流量路由到不同模型。
- 在兼容模型上保持流式输出、工具调用和推理支持。
- 在 VS Code 中连接 Claude Code 和 Codex，或通过 JetBrains ACP 使用 Claude Code。
- 可选通过 Discord 或 Telegram 运行 Claude Code 会话，并支持语音笔记转写。
- 使用可选的令牌（token）认证保护本地代理。
## 快速开始
### 1. 安装或更新
macOS/Linux：
```bash
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh
```
Windows PowerShell：
```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))
```
需要更新时，重新运行同一条命令即可。运行前可先查看安装脚本：[install.sh](scripts/install.sh) 和 [install.ps1](scripts/install.ps1)。
### 2. 启动服务
```bash
fcc-server
```
若要在不启动服务的情况下打印已安装的 Free Claude Code 版本，
请运行 `fcc-server --version`。
保持该进程持续运行。启动日志会显示 Admin UI 地址：
```text
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
```
若终端显示的端口与 `8082` 不同，请使用终端中的端口。
### 3. 配置 NVIDIA NIM
1. 在 [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys). 创建 API 密钥。
2. 打开服务日志中的 Admin UI URL。
3. 将密钥粘贴到 `NVIDIA_NIM_API_KEY`。
4. 将 `MODEL` 保留为默认的 `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`，或选择其他模型。
5. 点击 **Validate**，然后点击 **Apply**。
### 4. 运行你的编程代理
Claude Code：
```bash
fcc-claude
```
Codex：
```bash
fcc-codex
```
Pi：
```bash
fcc-pi
```
三个启动器均使用当前 Admin UI 设置。使用代理的模型选择器，从 FCC 暴露的模型中选择。常规 CLI 参数仍然有效，例如：
```bash
fcc-codex exec "hello"
```
`fcc-pi` 仅为该 Pi 进程注册 FCC；你现有的 Pi 设置、会话、凭据和扩展保持不变。
## 选择提供商
在 Admin UI 中输入所列设置，将 `MODEL` 设为带提供商前缀的模型 ID，然后点击 **Validate** 和 **Apply**。提供商名称链接到其密钥、模型或设置页面。
| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
| [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
| [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
| [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
| [Mistral La Plateforme](https://console.mistral.ai/) | `MISTRAL_API_KEY` | `mistral/devstral-small-latest` |
| [Mistral Codestral](https://console.mistral.ai/) | `CODESTRAL_API_KEY` | `mistral_codestral/codestral-latest` |
| [OpenCode Zen](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode/gpt-5.3-codex` |
| [OpenCode Go](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode_go/minimax-m2.7` |
| [Vercel AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers) | `AI_GATEWAY_API_KEY` | `vercel/openai/gpt-5.5` |
| [Hugging Face Inference Providers](https://huggingface.co/settings/tokens) | `HUGGINGFACE_API_KEY` | `huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest` |
| [Cohere](https://dashboard.cohere.com/api-keys) | `COHERE_API_KEY` | `cohere/command-a-plus-05-2026` |
| [GitHub Models](https://github.com/marketplace?type=models) | `GITHUB_MODELS_TOKEN` | `github_models/openai/gpt-4.1` |
| [Wafer](https://wafer.ai/) | `WAFER_API_KEY` | `wafer/DeepSeek-V4-Pro` |
| [Kimi](https://platform.moonshot.ai/console/api-keys) | `KIMI_API_KEY` | `kimi/kimi-k2.5` |
| [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` |
| [Cerebras Inference](https://cloud.cerebras.ai/) | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b` |
| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [SambaNova](https://cloud.sambanova.ai/apis) | `SAMBANOVA_API_KEY` | `sambanova/Meta-Llama-3.3-70B-Instruct` |
| [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` |
| [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` | `cloudflare/@cf/moonshotai/kimi-k2.6` |
| [Z.ai](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` |
| [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/` |
| [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/` |
| [Ollama](https://ollama.com/) | `OLLAMA_BASE_URL` | `ollama/` |
重要提供商说明：
- Mistral Codestral 使用的密钥与 Mistral La Plateforme 不同。
- OpenCode Zen 与 OpenCode Go 共用 `OPENCODE_API_KEY`，但使用不同的模型前缀。
- Cloudflare 需要同时提供 API token 与 account ID。
- 编程智能体（coding agents）请优先选用支持工具调用的模型。本地模型还需具备足够上下文，以容纳智能体的 system prompt 与工具定义。
本地提供商配置
### LM Studio
启动 LM Studio 本地服务器，加载支持工具调用的模型，并使用 LM Studio 显示的模型标识符，并加上 `lmstudio/` 前缀。默认 URL 为 `http://localhost:1234/v1`。
### llama.cpp
启动 `llama-server`，启用其 OpenAI 兼容的 Chat Completions API，并确保模型具备足够上下文。使用本地模型 ID，并加上 `llamacpp/` 前缀。`LLAMACPP_BASE_URL` 默认为 `http://localhost:8080/v1`；FCC 接受服务器根路径或显式的 `/v1` 后缀。
### Ollama
```bash
ollama pull llama3.1
ollama serve
```
使用 `ollama list` 显示的标签，并加上 `ollama/` 前缀。`OLLAMA_BASE_URL` 默认为 `http://localhost:11434`；FCC 接受根 URL 或显式的 `/v1` 后缀。
### 可选模型层级路由
`MODEL` 是所有请求的兜底项。设置 `MODEL_OPUS`、`MODEL_SONNET` 或 `MODEL_HAIKU` 可覆盖各 Claude Code 层级；将某一层级留空则继承 `MODEL`。
例如，将 Opus 路由到 `nvidia_nim/moonshotai/kimi-k2.6`，Sonnet 到 `open_router/openrouter/free`，Haiku 到 `lmstudio/qwen3.5-coder`，并将 `MODEL` 保持在 `zai/glm-5.2`。
## 连接客户端
在终端中使用时，先启动 `fcc-server`，再运行 `fcc-claude`、`fcc-codex` 或 `fcc-pi`。编辑器集成请参考下方指南。
VS Code 中的 Claude Code
安装 [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). 以 JSON 格式打开 VS Code 用户设置并添加：
```json
"claudeCode.disableLoginPrompt": true,
"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" },
{ "name": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": "1" }
]
```
将端口与认证 token 与 Admin UI 保持一致，然后重新加载扩展。
VS Code 中的 Codex
安装 [Codex extension](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt). 创建或编辑 `~/.codex/config.toml`（Windows 上为 `%USERPROFILE%\.codex\config.toml`）：
```toml
model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
[model_providers.fcc]
name = "Free Claude Code"
base_url = "http://127.0.0.1:8082/v1"
env_key = "FCC_CODEX_API_KEY"
wire_api = "responses"
```
将 Admin UI 认证 token 保存在 `~/.codex/auth.json` 或其 Windows 对应位置：
```json
{
"FCC_CODEX_API_KEY": "freecc"
}
```
将 `model`、端口与 token 与 Admin UI 保持一致，然后重启 VS Code。若 Codex 运行在 WSL 上，请在 WSL 内编辑相应文件。
JetBrains ACP 中的 Claude Code
编辑已安装的 Claude ACP 配置：
- Windows: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json`
- Linux/macOS: `~/.jetbrains/acp.json`
为 `acp.registry.claude-acp` 设置环境变量：
```json
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:8082",
"ANTHROPIC_AUTH_TOKEN": "freecc",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
}
```
将端口与 token 与 Admin UI 保持一致，然后重启 IDE。
Claude Code 仍要求登录
若在配置 FCC URL 与 token 后 Claude Code 仍要求登录，请打开其状态文件：
- Windows: `%USERPROFILE%\.claude.json`
- macOS/Linux/WSL: `~/.claude.json`
将该属性合并到现有 JSON 中，勿删除其他字段：
```json
"hasCompletedOnboarding": true
```
若文件不存在，请创建完整 JSON 对象：
```json
{
"hasCompletedOnboarding": true
}
```
保存文件后重启 Claude Code 或 IDE。
## 可选集成
在 **Admin UI → Messaging** 中配置集成，然后点击 **Validate** 与 **Apply**。
Discord 机器人
1. 在 [Discord Developer Portal](https://discord.com/developers/applications). 中创建机器人
2. 启用 **Message Content Intent**，并以读取、发送、
消息历史及 **Manage Messages** 权限邀请机器人，以便 `/clear` 能删除
用户提示。
3. 将 **Messaging Platform** 设为 **discord**。
4. 填写 **Discord Bot Token**、**Allowed Discord Channels** 及绝对路径的 **Allowed Directory**。
5. 应用设置，并按提示重启服务器。
Telegram 机器人
1. 通过 [@BotFather](https://t.me/BotFather). 创建机器人
2. 从 [@userinfobot](https://t.me/userinfobot). 获取你的数字用户 ID。
在群组中，授予机器人删除消息的权限。
3. 将 **Messaging Platform** 设为 **telegram**。
4. 填写 **Telegram Bot Token**、**Allowed Telegram User ID** 及绝对路径的 **Allowed Directory**。
5. 应用设置，并按提示重启服务器。
### 消息命令
| 用法 | 行为 |
| --- | --- |
| `/stats` | 显示会话状态。 |
| 单独发送 `/stop` | 取消全部工作。 |
| 回复 `/stop` | 仅取消所选请求，其余排队请求继续执行。 |
| 单独发送 `/clear` | 重置该聊天的全部 FCC 状态，并删除所有已跟踪消息，包括用户提示、语音消息、FCC 回复、Telegram 在线通知及清除命令本身。 |
| 回复 `/clear` | 删除所选消息及其在平台上的字面回复子树，同时保留其祖先与兄弟消息。 |
语音消息
使用所需语音后端重新运行安装程序。
macOS/Linux:
```bash
# NVIDIA NIM transcription
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-nim
# Local Whisper on CPU or CUDA
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local
# Both backends
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-all
# Local Whisper with the CUDA 13.0 PyTorch backend
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local --torch-backend cu130
```
Windows PowerShell:
```powershell
# NVIDIA NIM transcription
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceNim
# Local Whisper on CPU or CUDA
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal
# Both backends
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceAll
# Local Whisper with the CUDA 13.0 PyTorch backend
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal -TorchBackend cu130
```
重启 `fcc-server`。在 **Admin UI → Messaging → Voice** 中启用语音消息，选择 `cpu`、`cuda` 或 `nvidia_nim`，并选择 Whisper 模型。本地 gated 模型需要 `HUGGINGFACE_API_KEY`；NVIDIA NIM 转写需要 `NVIDIA_NIM_API_KEY`。
## 管理你的安装
### 更新
从 [安装或更新](#install) 中重新运行对应的命令。
### 卸载
请先停止所有正在运行的 FCC 命令。卸载程序会移除 FCC uv 工具，确认所有 FCC 命令均已清除，然后删除 `~/.fcc/`。它会保留 uv、Python、Claude Code、Codex、Pi 以及共享的 PATH 条目不变。
macOS/Linux：
```bash
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh
```
Windows PowerShell：
```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1")))
```
## 项目链接
- [报告 Bug 或请求功能](https://github.com/Alishahryar1/free-claude-code/issues)
- [架构与扩展指南](ARCHITECTURE.md)
- [贡献指南](CONTRIBUTING.md)
## 许可证
MIT 许可证。详见 [LICENSE](LICENSE)。
