Claude Proxy：基于Cloudflare Workers的API格式转换与动态路由代理

1. 项目概述一个API格式转换的“翻译官”如果你手头有一个习惯使用Claude API格式的工具比如官方的claude命令行工具但你又想让它去调用Google Gemini、Groq或者本地Ollama这类只认OpenAI API格式的服务你会怎么做手动改代码还是为每个服务都写一个适配器今天分享的这个claude_proxy项目就是一个部署在Cloudflare Workers上的“万能翻译官”它能无缝地将Claude API的“语言”翻译成OpenAI API的“语言”让你用一个工具畅游所有兼容OpenAI的AI服务。这个项目的核心价值在于它的动态路由和格式转换能力。想象一下你有一个能说多种方言的翻译代理服务器你只需要告诉它“把这句话用上海话目标API说给那个叫‘小明’模型的人听”它就能自动完成翻译和传达。你无需为每一种方言API和每一个人模型都雇佣一个专门的翻译。claude_proxy就是这个翻译它通过解析请求URL中的信息动态决定将请求转发到哪里、使用哪个模型并自动完成请求体和响应体的格式转换。2. 核心原理与架构设计解析2.1 动态路由URL即配置的魔法这个代理最巧妙的设计在于其路由机制。它没有在代码里写死任何后端服务的地址而是将目标API的地址和模型名称编码在了请求的URL路径中。这是一种“约定大于配置”的极致体现。URL结构拆解一个典型的请求URL看起来是这样的https://your-proxy.workers.dev/https/api.groq.com/openai/v1/llama3-70b-8192/v1/messages我们来分解一下https://your-proxy.workers.dev: 这是你的Cloudflare Worker代理地址。/https: 这指定了目标API使用的协议http或https。代理会使用这个协议去连接后端。/api.groq.com/openai/v1: 这是目标服务的基础路径。代理会将其与协议拼接形成完整的基础URLhttps://api.groq.com/openai/v1。/llama3-70b-8192: 这是你想要调用的模型名称。代理会把这个模型名填入转换后的OpenAI格式请求体中。/v1/messages: 这是Claude API的标准端点路径。代理接收到这个路径的请求就知道需要进行Claude到OpenAI的转换。工作流程请求接收claude客户端向代理的/v1/messages端点发送一个标准的Claude API格式请求。URL解析代理解析整个URL提取出协议、主机路径和模型名。格式转换代理将Claude格式的请求体包含messages,max_tokens,tools等字段转换为OpenAI的/chat/completions端点所期望的格式。请求转发代理将转换后的请求连同从请求头x-api-key提取的API密钥转换为Authorization: Bearer key格式一起发送到拼接好的目标API地址如https://api.groq.com/openai/v1/chat/completions。响应回转代理收到OpenAI格式的响应后再将其转换回Claude格式并返回给最初的客户端。这个过程对客户端是完全透明的。客户端始终认为自己是在和Claude API对话而实际上背后可能是任何一个AI服务。2.2 格式转换的细节与挑战格式转换并非简单的字段名映射其中涉及一些需要智能处理的细节尤其是tools函数调用和流式响应。1. 消息格式转换Claude和OpenAI的消息格式高度相似都包含role和content。代理基本可以一一对应。但需要注意Claude的system提示词是放在请求体顶层的system字段中而OpenAI则是将其作为一条role为system的消息放在messages数组的开头。代理需要正确处理这个转换。2. Tool Calling函数调用转换这是转换中的难点。Claude和OpenAI对工具的定义结构不同。Claude格式tools是一个数组每个工具包含name,description,input_schema一个JSON Schema对象。OpenAI格式tools也是一个数组但每个工具包含type固定为function,function对象。function对象内部包含name,description,parameters同样是一个JSON Schema对象。代理需要做的是将Claude的input_schema整体移动到OpenAI的parameters字段。对于某些严格的后端如Google Gemini它们可能对input_schema中的某些属性如$schema,additionalProperties有兼容性问题。因此代理在转换过程中会执行一次“清理”cleanup移除可能引发问题的属性确保转换后的Schema能被广泛接受。3. 流式响应处理两者都支持Server-Sent EventsSSE格式的流式响应。Claude的流式数据块格式是data: {...}其中包含type为content_block_delta或message_stop等。OpenAI的格式也是data: {...}但包含的是choices[0].delta。 代理需要在流式传输中实时转换每一个数据块。例如将OpenAI的delta.content转换为Claude的delta.text并封装在正确的content_block结构中。这要求代理不能一次性缓冲整个响应流而必须是一个管道一边接收、一边转换、一边发送以保持流的低延迟特性。3. 从零开始部署与配置全流程3.1 环境准备与项目获取首先你需要一个Cloudflare账户。如果没有去官网免费注册一个。然后确保你的本地开发环境已安装Node.js建议LTS版本和npm。获取项目代码最直接的方式是克隆Git仓库git clone https://github.com/tingxifa/claude_proxy.git cd claude_proxy如果你没有Git也可以直接下载项目的ZIP压缩包并解压。进入项目目录后安装必要的依赖虽然Wrangler可以全局安装但项目本地可能有特定版本要求npm install3.2 使用一键配置脚本推荐给终端用户对于只是想快速使用代理功能的用户项目提供的claude_proxy.sh脚本是最高效的方式。这个脚本本质上是一个交互式的配置向导它帮你处理了claudeCLI工具的安装和配置。脚本工作原理检查与安装脚本首先检查你的系统是否安装了claude命令行工具通常通过npm install -g anthropic-ai/claude-code安装。如果没有它会提示并帮你安装。交互式配置通过一系列提问收集以下关键信息Worker URL代理服务器地址。你可以使用作者提供的公共代理https://claude-code-proxy.suixifa.workers.dev也可以输入自己部署的地址。API Key注意这里填的是目标服务如Groq、OpenAI的API Key不是Claude的脚本会将它写入配置。OpenAI URL目标服务的API基础地址不带http://或https://。例如Groq是api.groq.com/openai/v1。Model Name你想使用的模型如llama3-70b-8192。写入配置脚本会将收集到的信息按照Claude CLI要求的格式写入到~/.claude/settings.json文件中。这个文件决定了claude命令的行为。测试验证配置完成后脚本会自动发送一个简单的测试请求例如claude “hello”来验证整个代理链路是否通畅。如果看到AI的回复说明一切就绪。执行脚本# 确保脚本有执行权限 chmod x ./claude_proxy.sh # 运行脚本并跟随提示 ./claude_proxy.sh注意脚本运行过程中如果遇到权限问题例如写入/usr/local/lib需要sudo请根据提示操作。在类Unix系统上全局安装npm包有时需要sudo权限。3.3 自托管部署到Cloudflare Workers如果你希望拥有一个完全由自己控制的代理服务避免使用公共代理可能存在的限速或隐私顾虑就需要将项目部署到自己的Cloudflare账户下。步骤1安装并登录WranglerWrangler是Cloudflare官方命令行工具。# 全局安装wrangler npm install -g wrangler # 登录你的Cloudflare账户这会在浏览器打开授权页面 npx wrangler login步骤2可选配置环境变量与Haiku快捷方式查看项目根目录下的wrangler.toml文件。在[vars]部分你可以为haiku模型预设一个快捷路由。[vars] HAIKU_MODEL_NAME gpt-4o-mini # 当请求模型为‘haiku’时实际使用的模型 HAIKU_BASE_URL https://api.openai.com/v1 # 对应的API地址 HAIKU_API_KEY sk-... # 对应的API密钥这个功能非常实用。当你或你的客户端将模型设置为haiku时代理不会去动态解析URL而是直接使用这里配置的HAIKU_BASE_URL和HAIKU_MODEL_NAME。这相当于为某个常用模型设置了一个“别名”或“默认路由”简化了调用。步骤3部署在项目根目录下运行部署命令npx wrangler deployWrangler会将你的代码打包并上传到Cloudflare。部署成功后命令行会输出你的Worker专属域名格式如https://你的项目名.你的子域.workers.dev。这个URL就是你自托管代理的地址。步骤4配置客户端使用自托管代理拿到自己的Worker URL后再次运行claude_proxy.sh脚本在提示输入Worker URL时填入你自己的地址即可。后续的API Key等信息则对应你想让这个代理去访问的后端服务。4. 高级用法与本地开发调试4.1 本地开发与测试在将代码部署到云端之前在本地进行开发和测试是更安全、更高效的做法。claude_proxy项目完全支持本地运行。1. 配置本地环境变量Cloudflare Workers在本地运行时需要通过.dev.vars文件来读取环境变量模拟云端wrangler.toml中的[vars]配置。 在项目根目录创建一个名为.dev.vars的文件内容如下HAIKU_MODEL_NAMEgpt-4o-mini HAIKU_BASE_URLhttps://api.openai.com/v1 HAIKU_API_KEYsk-your-openai-key-here请务必将HAIKU_API_KEY替换为你真实的API密钥。这个文件被.gitignore排除不会提交到代码库保证了密钥安全。2. 启动本地开发服务器npx wrangler dev执行后Wrangler会在http://localhost:8787启动一个本地服务器。它完全模拟了Cloudflare Workers的环境并且支持热重载修改代码后自动重启。3. 测试本地代理打开另一个终端窗口我们需要配置claude命令行工具让它指向本地服务器。# 设置环境变量告诉claude工具API的基础地址是本地服务器 export ANTHROPIC_BASE_URLhttp://localhost:8787 # 可选设置超时时间本地调试可能较长 export API_TIMEOUT_MS600000 # 指定使用‘haiku’模型这样请求会走我们上面配置的HAIKU_*路由 export ANTHROPIC_MODELhaiku export ANTHROPIC_SMALL_FAST_MODELhaiku现在运行一个测试命令claude Hello from local proxy!如果一切正常你将看到来自你配置的AI服务如上例中的OpenAI GPT-4o-mini的回复。这证明你的本地代理工作正常格式转换成功。4.2 深入理解配置settings.json文件剖析通过claude_proxy.sh脚本配置后你的~/.claude/settings.json文件内容大致如下{ default: { anthropicBaseUrl: https://your-proxy.workers.dev/https/api.groq.com/openai/v1/llama3-70b-8192, anthropicApiKey: your-groq-api-key } }这个文件是anthropic-ai/claude-codeCLI工具的配置文件。anthropicBaseUrl: 这是最关键的部分。它不是一个简单的域名而是包含了完整路由信息的URL。工具会向这个地址的/v1/messages端点发送请求。代理your-proxy.workers.dev会从这个URL中解析出协议(https)、目标主机路径(api.groq.com/openai/v1)和模型(llama3-70b-8192)。anthropicApiKey: 这里存放的密钥会被claude工具放在请求头的x-api-key字段中发送给代理。代理随后会将其转换为Authorization: Bearer ...格式转发给目标API如Groq。因此这里必须填写目标服务的API Key而不是Claude的Key。你可以手动编辑这个文件来切换不同的代理或后端服务。例如要换用Gemini你可以将anthropicBaseUrl改为https://your-proxy.workers.dev/https/generativelanguage.googleapis.com/v1beta/models/gemini-pro并将anthropicApiKey改为你的Google AI Studio API Key。4.3 处理复杂的Tool Calling场景当你需要让AI模型调用函数时Claude的请求体中会包含tools数组。代理的转换逻辑在这里至关重要。以下是一个转换前后的示例Claude格式请求 (发送给代理):{ model: claude-3-haiku-20240307, max_tokens: 1024, tools: [{ name: get_weather, description: 获取指定城市的天气, input_schema: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } }], messages: [...] }代理转换后的OpenAI格式请求 (发送给目标API):{ model: llama3-70b-8192, // 从URL路径中动态获取的模型名 max_tokens: 1024, tools: [{ type: function, function: { name: get_weather, description: 获取指定城市的天气, parameters: { // 注意这里是 input_schema 的内容 type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } }], messages: [...] }代理成功地将Claude的tools结构转换成了OpenAI的tools结构。在实际使用中你几乎感知不到这个转换过程claude工具发出的Tool Calling请求经过代理后能正确地在Groq、Gemini等后端服务上工作。5. 常见问题、故障排查与优化建议5.1 配置与连接问题问题1运行claude_proxy.sh脚本时提示command not found: claude。原因anthropic-ai/claude-codeCLI工具未全局安装。解决脚本通常会提示并尝试为你安装。你也可以手动安装npm install -g anthropic-ai/claude-code。如果遇到权限错误在命令前加sudoLinux/macOS或以管理员身份运行终端Windows。问题2配置成功后运行claude命令长时间无响应或超时。排查步骤检查网络确认你的网络可以访问你配置的Worker URL和目标API服务如api.groq.com。验证代理地址如果你使用的是自托管代理请确保Worker已成功部署且在线。可以在浏览器中访问你的Worker URL如果看到类似“Method Not Allowed”的提示因为GET请求不被处理说明Worker本身是运行的。检查API Key确认你在脚本中输入的API Key是目标服务的Key并且该Key有效、有余额、未被禁用。你可以尝试用curl命令直接测试目标API。检查URL路径仔细核对~/.claude/settings.json中的anthropicBaseUrl。确保其格式为https://proxy/protocol/api_host/model并且没有多余的斜杠或拼写错误。模型名必须与目标服务支持的模型列表完全一致。问题3错误信息提示“模型不存在”或“无效的请求”。原因最可能的原因是anthropicBaseUrl中的模型名称拼写错误或者该模型在你使用的API服务中不可用。解决查阅目标API服务的文档确认正确的模型名称。例如Groq的模型名是llama3-70b-8192而OpenAI的是gpt-4o。确保URL路径中的模型名与文档一致。5.2 功能与兼容性问题问题4Tool Calling功能工作不正常AI不识别工具或返回格式错误。排查步骤确认后端支持首先确认你使用的目标AI服务如Gemini, Groq是否支持OpenAI格式的Tool Calling。不是所有兼容OpenAI格式的服务都100%支持所有功能。简化Tool Schema某些后端对JSON Schema的兼容性要求比较严格。尝试简化你定义的input_schema移除$schema、additionalProperties: false等可能引发问题的属性。claude_proxy的转换逻辑已经包含了一些清理工作但极端情况下可能需要手动调整。启用调试在本地开发时你可以在代理代码中添加日志打印出转换前和转换后的tools对象对比查看转换是否正确完成。问题5流式响应Streaming中断或速度很慢。原因代理在流式转换中需要处理每一个数据块。网络延迟、代理服务器性能尤其是免费Worker的CPU时间限制或复杂的响应内容都可能影响流式体验。解决对于自托管代理可以考虑升级Cloudflare Workers套餐获得更多的CPU时间。检查是否在请求中设置了过大的max_tokens导致响应生成时间过长。在本地测试排除网络问题。5.3 安全与性能优化建议1. 保护你的API密钥永远不要将包含真实API Key的wrangler.toml或.dev.vars文件提交到公开的Git仓库。确保.gitignore文件包含了这些敏感文件。对于自托管代理考虑使用Cloudflare Workers的 秘密管理 功能来存储HAIKU_API_KEY而不是明文写在wrangler.toml中。使用wrangler secret put HAIKU_API_KEY命令来设置。2. 为代理添加访问控制可选但推荐公共的代理URL任何人都可以调用可能会消耗你的后端API额度。你可以通过以下方式增加基础防护绑定自定义域名并设置防火墙规则将Worker绑定到你自己的域名然后利用Cloudflare的WAFWeb应用防火墙规则限制只有来自特定国家、IP或携带特定请求头的请求才能访问。在Worker代码中添加简单认证修改src/index.ts在请求处理开始时检查请求头中是否包含一个你预设的令牌Token没有则直接返回403错误。这为代理增加了一层简单的密码保护。3. 监控与日志在Cloudflare Workers仪表板中你可以查看Worker的请求次数、错误率和CPU执行时间。这对于监控代理的健康状态和用量非常有用。对于更详细的调试可以在代码的关键位置如收到请求、转发请求、收到响应时使用console.log输出结构化日志。在Worker的“日志”页面可以查看这些实时日志。4. 处理速率限制你的后端API服务如OpenAI、Groq都有速率限制。当代理转发大量请求时可能会触发这些限制。一个更健壮的代理应该考虑实现简单的请求队列或失败重试逻辑注意免费Worker的CPU时间限制。更复杂的方案可能需要引入有状态存储如Durable Objects来管理请求状态但这超出了基础代理的范畴。