在构建免费 AI 编程助手的工程实践中，如何高效路由请求、管理 API 配额并支持多终端接入是关键挑战。free-claude-code 项目通过透明的代理层设计，将 Claude Code 的 Anthropic API 调用重定向至多个免费或本地推理后端，同时实现了细粒度的速率控制与请求优化。本文从代理架构、速率限制策略和多客户端接入三个维度，解析其核心工程实现。
代理层架构与按模型路由
free-claude-code 的核心定位是充当 Claude Code 与各类 LLM 提供商之间的透明代理。代理服务器监听本地端口 8082，接收来自 Claude Code CLI、VSCode 扩展或 Discord 机器人的请求，然后根据配置将请求转发至目标提供商。整个转发过程对 Claude Code 透明 —— 它只需要设置两个环境变量 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，无需修改客户端本身。
按模型路由是架构中最具工程价值的特性之一。项目支持为 Claude Code 的三个主要模型系列（Opus、Sonnet、Haiku）分别指定不同的后端提供商。例如可以在 .env 中配置 MODEL_OPUS="nvidia_nim/z-ai/glm4.7" 使用 NVIDIA NIM 的 glm4.7 模型处理 Opus 级别任务，同时让 MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free" 通过 OpenRouter 的免费模型处理 Sonnet 级别请求。这种设计允许开发者根据任务复杂度动态分配资源 —— 复杂推理任务交给能力较强的模型，简单对话则使用免费模型，从而在有限配额内最大化吞吐量。
代理层的请求转换逻辑也值得注意。由于不同提供商采用不同的 API 格式，项目内部实现了请求格式的双向转换：接收端将 Anthropic 格式的请求转换为 OpenAI 兼容格式，响应端则需要处理提供商返回的流式输出并还原为 Claude 兼容的 SSE 格式。特别地，当 ENABLE_THINKING=true 时，项目能够解析 reasoning_content 字段并将其转换为 Claude 原生的 <think> thinking block，确保思维链输出正确展示。
速率限制的双层策略
免费的 LLM API 通常设有严格的请求频率限制，NVIDIA NIM 提供每分钟 40 次请求的免费配额，OpenRouter 的免费模型也有各自的限制。free-claude-code 实现了主动预防与被动容错相结合的双层速率限制策略。
主动预防层面，项目采用滚动窗口限速机制。默认配置下 PROVIDER_RATE_LIMIT=40 且 PROVIDER_RATE_WINDOW=60，这意味着系统会追踪过去 60 秒内的请求计数，一旦超过阈值则立即返回 429 错误而不是等到实际调用提供商时才失败。这种设计避免了无效的 API 调用，保护了开发者的配额不被浪费。与此同时，PROVIDER_MAX_CONCURRENCY=5 参数限制了同时打开的流式连接数，防止突发流量冲垮免费后端。
被动容错层面，项目在收到提供商的 429 响应时自动执行指数退避重试。HTTP 超时也做了精细配置：HTTP_READ_TIMEOUT=120 秒给予长推理足够的响应时间，而 HTTP_CONNECT_TIMEOUT=2 秒则快速失败无效连接，HTTP_WRITE_TIMEOUT=10 秒确保请求发送不会无限阻塞。
请求优化是另一种形式的配额保护。项目内置了 5 类 trivial API 调用的本地拦截器，包括配额探测请求（quota probes）、标题生成请求（title generation）、前缀检测（prefix detection）、代码补全建议（suggestions）和文件路径提取（filepath extraction）。这些请求虽然来自 Claude Code 正常工作流程，但实际上不涉及真正的模型推理，完全可以由代理层直接响应。通过设置 ENABLE_TITLE_GENERATION_SKIP=true、ENABLE_NETWORK_PROBE_MOCK=true 等标志，这些请求会被拦截并返回模拟响应，从而在不牺牲功能的前提下显著节省 API 配额。
多终端接入与子代理控制
free-claude-code 支持三种主要的客户端接入方式，每种方式对应不同的配置路径。
终端用户通过环境变量即可切换到代理后端。bash 用户执行 ANTHROPIC_BASE_URL="http://localhost:8082" claude 即可启动免费模式，PowerShell 用户则通过 $env:ANTHROPIC_BASE_URL="http://localhost:8082" 设置。VSCode 扩展的配置稍显复杂，需要在扩展设置的 claudiCode.environmentVariables 中以 JSON 数组形式注入环境变量，然后重启扩展。如果看到登录界面，点击 Anthropic Console 授权后即可正常使用，浏览器中的付费提示可以忽略。
对于远程或协作场景，项目提供了 Discord 和 Telegram 机器人接入。机器人基于树形消息线程设计 —— 用户回复某条消息即创建对话分支，支持同时运行多个并发的 Claude CLI 会话。关键配置包括 CLAUDE_WORKSPACE 指定机器人的工作目录、ALLOWED_DIR 限制可访问的目录路径，以及 MESSAGING_RATE_LIMIT 控制消息频率。语音消息也被支持，本地 Whisper 模型或 NVIDIA NIM 的 Parakeet 模型可以转录音频后作为提示处理。
子代理控制是生产环境中不可忽视的安全特性。Claude Code 支持通过 Task 工具创建后台子代理执行并行任务，但在免费配额场景下，子代理可能快速耗尽有限资源。项目通过拦截 Task 工具调用并强制设置 run_in_background=False 来确保所有任务在前台串行执行，配合并发数上限参数 PROVIDER_MAX_CONCURRENCY=5 形成双重保护。
工程参数清单
对于计划部署 free-claude-code 的开发者，以下配置参数是调优的关键入口：速率限制相关将 PROVIDER_RATE_LIMIT 根据所用提供商的配额调整，NVIDIA NIM 保持默认 40，OpenRouter 免费模型建议降至 20 以预留缓冲；PROVIDER_MAX_CONCURRENCY 在网络条件不佳时可降至 3 以减少超时重试；HTTP_READ_TIMEOUT 在使用长思考模型（如 deepseek-reasoner）时可考虑增至 180 秒。请求优化相关生产环境建议保持所有优化标志开启（默认均为 true），仅在调试阶段逐个关闭以定位问题。认证安全方面若在公网暴露代理服务，务必设置 ANTHROPIC_AUTH_TOKEN 并通过环境变量传递给客户端。
免费 Claude Code 代理方案的核心价值在于将顶级 AI 编程助手的使用门槛降至零。通过多提供商路由、精细的速率控制和广泛的终端兼容，开发者可以在不产生 API 费用的前提下构建完整的 AI 智能体开发环境。