逆向 Claude Code API：构建多平台免费替代方案的工程实践

Claude Code 作为 Anthropic 推出的 AI 编程代理工具，其闭源特性限制了开发者在模型选择和部署方式上的灵活性。通过逆向工程其底层 API 协议，开源社区成功构建了一个兼容层，使得开发者能够在保留 Claude Code 交互体验的同时，接入 NVIDIA NIM、OpenRouter、DeepSeek、Kimi 等 17 个以上的替代模型提供商，甚至本地运行的 Ollama 和 LM Studio 实例。

协议解析：Anthropic Messages API 的 SSE 流式格式

Claude Code 与后端通信采用 Anthropic Messages API，其核心是基于 Server-Sent Events (SSE) 的流式响应机制。理解这一协议是构建兼容代理层的基础。

SSE 事件流遵循严格的顺序结构：message_start 标记响应开始，随后是一系列内容块（content block），每个块包含 content_block_start、若干个 content_block_delta 以及 content_block_stop 事件。message_delta 提供顶层消息变更（如停止原因和累计 token 数），最终以 message_stop 结束。

内容块增量（content_block_delta）支持多种类型：

• text_delta：文本片段流式传输
• input_json_delta：工具调用的 JSON 参数片段（支持 Pydantic 部分解析）
• thinking_delta：扩展思考模式的推理内容
• signature_delta：用于验证推理块完整性的签名

工具调用场景下，模型可能输出多个内容块：前序块为解释性文本，后续块为 tool_use 类型的结构化数据。代理层需要正确处理块索引（index 字段）和增量累积逻辑。

架构设计：FastAPI 代理层的核心组件

free-claude-code 项目采用 FastAPI 构建 ASGI 服务器，暴露与 Anthropic 原生一致的端点集：

/v1/messages           # 核心对话接口
/v1/models             # 模型发现与选择
/v1/messages/count_tokens  # Token 计数

协议转换层是架构的关键。由于不同提供商采用各异的 API 格式（OpenAI Chat Completions、Anthropic Messages、自定义格式），代理层实现了双向转换：

• OpenAI → Anthropic：将 chat.completions 流解析为 content_block_delta 事件序列，处理 choices[].delta.content 到 text_delta 的映射
• Anthropic → OpenAI：保留原生格式，用于 Wafer、Kimi、Fireworks 等已兼容 Messages API 的提供商

模型路由支持按能力层级分流：通过配置 MODEL_OPUS、MODEL_SONNET、MODEL_HAIKU 环境变量，可将不同复杂度的请求路由至不同提供商。例如，将高复杂度任务导向 NVIDIA NIM 的 Nemotron-3-Super-120B，轻量任务使用本地 Ollama 实例。

请求优化模块拦截 Claude Code 的探测性请求（如模型能力检测），直接返回本地缓存响应，避免不必要的外部 API 调用。

多平台集成：统一配置参数与接入方式

代理层的设计目标之一是保持 Claude Code 客户端的零感知切换。通过环境变量注入，可在多个平台实现无缝接入：

终端 CLI：

export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_AUTH_TOKEN="freecc"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="190000"

VSCode 扩展：在 settings.json 中配置 claudeCode.environmentVariables 数组，上述参数自动注入扩展进程。

JetBrains ACP：编辑 ~/.jetbrains/acp.json（或 Windows 对应路径），在 acp.registry.claude-acp 的 env 字段中设置相同参数。

Discord/Telegram 机器人：代理层内置消息平台适配器，支持通过 Bot Token 和频道 ID 配置远程会话。语音转录功能通过集成 NVIDIA Riva gRPC 或本地 Whisper 实现，扩展了交互维度。

生产实践：模型路由、错误处理与性能优化

Provider 选择矩阵：

流式错误恢复：SSE 连接可能因网络中断或提供商限流（overloaded_error）而中断。对于 Claude 4.5 及更早模型，可通过捕获部分响应并构造续传请求恢复；4.6+ 模型则需要将中断内容作为用户消息重新发送，指示模型继续生成。

Token 管理：message_delta 事件中的 usage 字段提供累计输入 / 输出 token 数。代理层需聚合各提供商的计费信息，实现跨模型调用的成本追踪。

Thinking Blocks 处理：扩展思考模式产生的推理内容需要特殊处理。代理层将 thinking_delta 和 signature_delta 转换为 Claude Code 期望的格式，对于不支持推理的模型则直接省略该块。

局限与注意事项

协议适配层虽能处理大多数场景，但仍存在边界情况：

• 工具调用差异：不同提供商对并行工具调用、工具结果回调的支持程度不一，需在实际使用中验证
• Context Window：本地模型（如 llama.cpp）需显式配置 --ctx-size 以支持 Claude Code 的长上下文请求
• 功能降级：当目标模型不支持特定功能（如结构化输出、网络搜索工具）时，代理层应提供 graceful fallback

资料来源

• GitHub - Alishahryar1/free-claude-code: 开源代理层实现，支持 17+ 个模型提供商
• Anthropic Messages API Streaming Docs: 官方 SSE 流式协议规范

ai-systems