alishahryar1--free-claude-code/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

🤖 Free Claude Code

通过你自己的提供商（provider）代理，使用 Claude Code、Codex、Pi、编辑器扩展或聊天机器人。

使用免费、付费或本地模型运行你的编程代理（coding agents）。在本地 Admin UI 中选择一个提供商并完成验证。

快速开始 · 提供商 · 客户端 · 集成 · 管理

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：

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh

Windows PowerShell：

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))

需要更新时，重新运行同一条命令即可。运行前可先查看安装脚本：install.sh 和 install.ps1。

2. 启动服务

fcc-server

若要在不启动服务的情况下打印已安装的 Free Claude Code 版本， 请运行 fcc-server --version。

保持该进程持续运行。启动日志会显示 Admin UI 地址：

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

若终端显示的端口与 8082 不同，请使用终端中的端口。

3. 配置 NVIDIA NIM

1. 在 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：

fcc-claude

Codex：

fcc-codex

Pi：

fcc-pi

三个启动器均使用当前 Admin UI 设置。使用代理的模型选择器，从 FCC 暴露的模型中选择。常规 CLI 参数仍然有效，例如：

fcc-codex exec "hello"

fcc-pi 仅为该 Pi 进程注册 FCC；你现有的 Pi 设置、会话、凭据和扩展保持不变。

选择提供商

在 Admin UI 中输入所列设置，将 MODEL 设为带提供商前缀的模型 ID，然后点击 Validate 和 Apply。提供商名称链接到其密钥、模型或设置页面。

Provider	Admin UI setting	Example MODEL
NVIDIA NIM	NVIDIA_NIM_API_KEY	nvidia_nim/nvidia/nemotron-3-super-120b-a12b
OpenRouter	OPENROUTER_API_KEY	open_router/openrouter/free
Google AI Studio (Gemini)	GEMINI_API_KEY	gemini/models/gemini-3.1-flash-lite
DeepSeek	DEEPSEEK_API_KEY	deepseek/deepseek-chat
Mistral La Plateforme	MISTRAL_API_KEY	mistral/devstral-small-latest
Mistral Codestral	CODESTRAL_API_KEY	mistral_codestral/codestral-latest
OpenCode Zen	OPENCODE_API_KEY	opencode/gpt-5.3-codex
OpenCode Go	OPENCODE_API_KEY	opencode_go/minimax-m2.7
Vercel AI Gateway	AI_GATEWAY_API_KEY	vercel/openai/gpt-5.5
Hugging Face Inference Providers	HUGGINGFACE_API_KEY	huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest
Cohere	COHERE_API_KEY	cohere/command-a-plus-05-2026
GitHub Models	GITHUB_MODELS_TOKEN	github_models/openai/gpt-4.1
Wafer	WAFER_API_KEY	wafer/DeepSeek-V4-Pro
Kimi	KIMI_API_KEY	kimi/kimi-k2.5
MiniMax	MINIMAX_API_KEY	minimax/MiniMax-M3
Cerebras Inference	CEREBRAS_API_KEY	cerebras/gpt-oss-120b
Groq	GROQ_API_KEY	groq/llama-3.3-70b-versatile
SambaNova	SAMBANOVA_API_KEY	sambanova/Meta-Llama-3.3-70B-Instruct
Fireworks AI	FIREWORKS_API_KEY	fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct
Cloudflare Workers AI	CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID	cloudflare/@cf/moonshotai/kimi-k2.6
Z.ai	ZAI_API_KEY	zai/glm-5.2
LM Studio	LM_STUDIO_BASE_URL	lmstudio/<model-id>
llama.cpp	LLAMACPP_BASE_URL	llamacpp/<model-id>
Ollama	OLLAMA_BASE_URL	ollama/<model-tag>

重要提供商说明：

• 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

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. 以 JSON 格式打开 VS Code 用户设置并添加：

"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. 创建或编辑 ~/.codex/config.toml（Windows 上为 %USERPROFILE%\.codex\config.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 对应位置：

{
  "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 设置环境变量：

"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 中，勿删除其他字段：

"hasCompletedOnboarding": true

若文件不存在，请创建完整 JSON 对象：

{
  "hasCompletedOnboarding": true
}

保存文件后重启 Claude Code 或 IDE。

可选集成

在 Admin UI → Messaging 中配置集成，然后点击 Validate 与 Apply。

Discord 机器人

1. 在 Discord Developer Portal. 中创建机器人
2. 启用 Message Content Intent，并以读取、发送、 消息历史及 Manage Messages 权限邀请机器人，以便 /clear 能删除 用户提示。
3. 将 Messaging Platform 设为 discord。
4. 填写 Discord Bot Token、Allowed Discord Channels 及绝对路径的 Allowed Directory。
5. 应用设置，并按提示重启服务器。

Telegram 机器人

1. 通过 @BotFather. 创建机器人
2. 从 @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:

# 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:

# 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。

管理你的安装

更新

从 安装或更新 中重新运行对应的命令。

卸载

请先停止所有正在运行的 FCC 命令。卸载程序会移除 FCC uv 工具，确认所有 FCC 命令均已清除，然后删除 ~/.fcc/。它会保留 uv、Python、Claude Code、Codex、Pi 以及共享的 PATH 条目不变。

macOS/Linux：

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh

Windows PowerShell：

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1")))

项目链接

• 报告 Bug 或请求功能
• 架构与扩展指南
• 贡献指南

许可证

MIT 许可证。详见 LICENSE。