Claude Code 是 Anthropic 推出的 AI 编程助手，但使用官方 API 需要付费。对于希望在终端和 VSCode 中免费使用 Claude Code 的开发者而言，一个名为 free-claude-code 的开源项目提供了可行的替代方案。该项目通过透明的代理架构，在不修改 Claude Code 客户端的前提下，将其请求重定向到多种免费或本地模型提供者，实现零成本使用。
核心设计：透明代理与模型路由
free-claude-code 的设计理念是作为 Claude Code 与下游模型提供者之间的透明代理。项目采用 FastAPI 构建 HTTP 服务，监听 8082 端口，模拟 Anthropic 的 API 端点。Claude Code 发送的标准 Anthropic API 请求会被代理拦截并转发到配置的下游提供者，整个过程对客户端完全透明。
项目支持五种模型提供者，分别是 NVIDIA NIM、OpenRouter、DeepSeek、LM Studio 和 llama.cpp。这些提供者覆盖了从云端免费 API 到完全本地部署的各种场景。NVIDIA NIM 提供每分钟 40 次请求的免费额度，是最推荐的日常使用方案；OpenRouter 聚合了数百种模型，其中部分模型免费开放；DeepSeek 提供直接 API 访问；LM Studio 和 llama.cpp 则支持完全本地部署，无需任何 API 密钥。
模型路由机制是项目的核心特性之一。由于 Claude Code 内部使用 Opus、Sonnet、Haiku 等模型层级，代理允许为每个层级配置不同的后端提供者。通过设置 MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 环境变量，可以将 Opus 请求路由到高端模型，Sonnet 请求路由到中端免费模型，Haiku 请求路由到轻量级本地模型。这种灵活的路由策略使得用户可以根据任务复杂度选择合适的模型，优化成本与效果的平衡。
请求优化与本地拦截
除了模型路由，free-claude-code 还实现了请求优化功能，进一步降低 API 调用成本。Claude Code 在运行过程中会发送多种探测性请求，用于获取模型能力、生成会话标题、提取文件路径等。项目识别出五类常见请求并选择性地在本地响应，无需调用下游 API。
具体优化包括：快速前缀检测（Fast Prefix Detection）用于判断模型是否支持特定前缀；网络探测模拟（Network Probe Mock）响应健康检查请求；标题生成跳过（Title Generation Skip）避免为简单会话调用 API；建议模式跳过（Suggestion Mode Skip）拦截代码建议类请求；文件路径提取模拟（Filepath Extraction Mock）直接在本地处理文件列表请求。这些优化不仅节省了宝贵的 API 配额，还显著降低了请求延迟。
智能速率限制是另一个关键技术特性。代理采用主动式滑动窗口节流机制，当请求速率接近提供者限制时自动排队等待；同时实现被动式指数退避策略，当收到 429 错误时自动重试；还提供可选的并发控制，通过 PROVIDER_MAX_CONCURRENCY 参数限制同时打开的流数量。默认配置下，速率限制为每分钟 40 个请求，最大并发数为 5，这些参数可根据具体提供者进行调整。
思考令牌与工具调用处理
使用非 Anthropic 模型时，一个重要挑战是如何正确处理思考令牌（Thinking Tokens）。Claude Code 的消息格式包含 <think> 标签和 reasoning_content 字段，这些是 Anthropic 模型的特有输出格式。free-claude-code 通过 ENABLE_THINKING 环境变量全局控制思考令牌的解析与转换。当启用时，代理会将下游模型输出的 reasoning 内容转换为 Claude 原生思考块格式，确保客户端能够正确显示思考过程。
工具调用处理同样需要适配。不同模型输出工具调用的方式各异：部分模型直接输出结构化 JSON，部分则输出纯文本格式。项目的启发式工具解析器（Heuristic Tool Parser）能够自动识别文本格式的工具调用并转换为结构化请求。此外，针对子代理控制，代理拦截任务工具调用并强制设置 run_in_background=False，防止失控的子代理消耗额外资源。
部署配置与使用方式
项目提供极简的部署流程。开发者需要首先获取所选提供者的 API 密钥（本地部署除外），然后克隆仓库并复制环境配置文件。配置过程仅需编辑 .env 文件，设置对应的 API 密钥和环境变量。启动代理服务器后，在终端中设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个环境变量，即可让 Claude Code 指向本地代理。
对于 VSCode 扩展，用户需要打开设置搜索 claude-code.environmentVariables，添加 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两个变量后重新加载扩展。值得注意的是，即使看到登录界面或购买积分的引导，也可以忽略并直接使用，因为代理已经正常工作。
项目还提供了消息平台集成功能，支持通过 Discord 或 Telegram 远程控制 Claude Code。这基于 MessagingPlatform 抽象类实现，允许用户发送任务指令、接收实时进度反馈、管理多个并发会话。语音消息也会被转录后作为常规提示处理，可选本地 Whisper 或 NVIDIA NIM 作为转录后端。
可扩展性与技术栈
free-claude-code 的架构设计具有良好的可扩展性。项目定义了 BaseProvider 抽象基类，任何新的模型提供者只需继承该基类并实现 stream_response 方法即可接入。类似地，MessagingPlatform 抽象基类允许添加新的消息平台支持。这种插件化设计降低了新功能添加的门槛，社区可以轻松贡献新的提供者或平台集成。
技术栈选择上，项目使用 FastAPI 作为 Web 框架，充分利用其异步能力和自动 API 文档生成；采用 OpenAI Python SDK 与兼容 OpenAI API 的提供者交互；Discord 和 Telegram 机器人分别使用 discord.py 和 python-telegram-bot 库；类型检查使用 Ty，代码格式化使用 Ruff，测试使用 pytest。这些工具确保了代码质量和维护性。
总结
free-claude-code 通过透明代理架构实现了 Claude Code 的免费使用，其核心价值在于多提供者路由、请求优化、智能速率限制以及对非 Anthropic 模型的适配。对于希望在终端和 IDE 中使用 AI 编程辅助但不想产生 API 费用的开发者，这个项目提供了实用的解决方案。其模块化设计也为技术爱好者提供了学习和扩展的基础。