Claude Max Proxy：突破OAuth限制，实现OpenAI API生态下的完整工具调用

1. 项目概述Claude Max Proxy 是什么以及它解决了什么问题如果你和我一样订阅了 Claude Max并且眼馋 OpenAI API 那种灵活、标准化的工具调用能力那你肯定也踩过同样的坑。Claude Max 的 OAuth 令牌虽然能让你免费使用顶级的 Claude Opus 4.5 模型但它有个非常恼人的限制这个令牌只能在官方的 Claude Code CLI 里用。这意味着你无法像调用 GPT-4 的 API 那样在 OpenClaw、Cursor 或者任何你喜欢的、支持 OpenAI 格式的客户端里直接让 Claude Max 模型去调用你定义好的函数工具。这感觉就像买了一辆顶级跑车却被告知只能在自家后院开上不了高速公路。市面上确实有一些变通方案比如通过子进程调用 Claude Code CLI 来中转但实测下来速度慢、不稳定尤其是在多轮对话中处理工具调用时经常陷入[Using tools...]的死循环或者直接把原始的 XML 代码吐给你体验非常糟糕。这就是NYTEMODEONLY/claude-max-proxy这个项目诞生的背景。它不是一个简单的转发器而是一个精巧的“协议转换器”和“限制破解器”。它的核心价值在于让你手中的 Claude Max OAuth 令牌能够无缝、稳定、完整地工作在标准的 OpenAI API 生态里享受完整的工具调用支持。简单来说这个代理项目做了三件关键事第一它模拟了 Claude Code CLI 与 Anthropic 官方 API 通信的“正确姿势”包括使用特定的系统提示词和请求头从而让 OAuth 令牌被 API 接受。第二它巧妙地将 OpenAI 格式的tools参数定义注入到用户消息中绕过了 OAuth 令牌直接使用tools参数的限制。第三也是 v3.4.0 版本最关键的创新它实现了“XML 历史重建”——在每次对话中将上一轮的工具调用结果从 OpenAI 格式转换回 Claude 能理解的 XML 格式再塞回历史消息里。这就彻底解决了多轮工具调用时Claude 因不认识自己之前的“行动记录”而陷入循环的问题。最终对于客户端来说它看到的始终是干净、标准的 OpenAI API 响应对于 Anthropic 的服务器来说它收到的始终是符合 Claude Code CLI 规范的请求。这个代理在中间扮演了“翻译官”和“化妆师”的角色。2. 核心原理与架构拆解为什么它能绕过限制要理解这个代理为什么有效我们需要深入看看 Claude Max OAuth 令牌的工作机制以及代理是如何“欺骗”系统的。2.1 OAuth 令牌的限制本质当你通过 Claude Code CLI 登录并获取 OAuth 令牌后这个令牌是绑定在特定“客户端身份”上的。Anthropic 的 API 后端会检查请求是否来自“合法的”Claude Code 客户端。这种合法性检查通常通过几个方面实现User-Agent 或特定 HTTP 头比如anthropic-beta: oauth-2025-04-20这个请求头很可能就是标识“这是来自新版 OAuth 认证客户端的请求”。系统提示词System PromptAPI 可能期望收到一个特定的、硬编码的系统提示词来验证请求的上下文。在这个代理中使用的魔法咒语是“You are Claude Code, Anthropics official CLI for Claude.”。这很可能就是 Claude Code CLI 内部使用的固定提示词。请求体结构直接使用tools参数的请求结构可能被服务器端标记为“来自标准 API 密钥的请求”从而拒绝 OAuth 令牌。因此代理需要把工具定义“伪装”成普通对话内容的一部分。这个代理的核心思路就是精确地复现 Claude Code CLI 发出的请求格式让 Anthropic 的服务器无法区分真假从而为我们的 OAuth 令牌“开绿灯”。2.2 工具调用的“双向翻译”机制这是整个代理最精妙的部分。OpenAI 的工具调用格式和 Claude 的工具调用格式是两套不同的语言。OpenAI 格式客户端发送一个tools数组来定义函数模型在需要时会在响应消息的tool_calls字段中返回一个包含id,type,function(含name和arguments) 的对象。Claude 格式XMLClaude 模型特别是通过 Claude Code在思考后如果决定调用工具会在回复内容中直接输出 XML 标签例如function_calls...invoke name\get_weather\.../invoke/function_calls。代理的工作流是一个完美的闭环请求转换Client → Anthropic代理收到客户端的 OpenAI 格式请求。它首先将tools数组中的函数定义转换成一段自然的文本描述追加到第一条用户消息的末尾。然后它检查历史消息中是否有上一轮的工具调用结果OpenAI 格式如果有则将其“反向翻译”成 Claude 上一轮输出的 XML 格式并插入到历史消息的合适位置。最后它附上魔法系统提示词和 Beta 头发送给 Anthropic API。响应解析Anthropic → ClientAnthropic API 返回包含 XML 工具调用的响应。代理会像外科手术一样精准地解析出这些 XML 标签将其转换为 OpenAI 格式的tool_calls数组。同时它会小心翼翼地把原始的 XML 从最终显示给用户的content字段中剥离出去确保聊天界面干净整洁。这个被剥离的 XML 内容会在下一轮请求时被用于“历史重建”。2.3 v3.4.0 的关键突破历史重建在 v3.4.0 之前很多用户遇到的最大问题是多轮工具调用卡住。比如用户“查一下东京天气。”Claude通过代理“我将为您查询东京天气。”[调用 get_weather 工具]用户或工具返回结果“东京晴25度。”Claude“[Using tools...]”[陷入循环不再输出新内容]问题根源在于当代理把工具执行结果“东京晴25度”作为一条role: tool的消息发给 Claude 时Claude 需要结合上下文来理解这个结果。但它的“上下文”里只记得自己用 OpenAI 格式说过要调用工具不记得自己曾经用 XML 格式发出过调用指令。这种认知失调导致它卡住。v3.4.0 的XML History Reconstruction功能就是为了解决这个“失忆症”。它在发送新一轮请求前会检查历史消息如果发现上一条助理消息包含tool_calls它就会在内部生成一个“假的”上一轮助理消息其内容正是当初 Claude 实际输出的 XML。这样当 Claude 看到工具结果时它回溯历史看到的是自己熟悉的 XML 调用记录一切就都连贯起来了。这个设计非常巧妙相当于代理在帮 Claude 维护“双重人格”的记忆。3. 从零开始的部署与配置实战理论讲完了我们动手把它跑起来。整个过程其实非常 straightforward但有几个细节不注意容易踩坑。3.1 环境准备与依赖安装首先确保你的系统满足基础要求Node.js 20 或更高版本这是硬性要求因为项目可能使用了较新的 JS 特性。你可以通过node --version检查。如果版本低建议使用nvmNode Version Manager来安装和管理多版本 Node.js。Git用于克隆代码仓库。Claude Max 订阅及有效的 OAuth 令牌这是服务的“燃料”没有它一切免谈。对于 macOS 用户项目支持从 macOS 钥匙串自动读取令牌这非常方便。确保你已经在当前机器上通过claude codeCLI 命令成功登录过。你可以打开“钥匙串访问”应用搜索“Claude Code-credentials”来确认令牌是否存在。对于 Linux/Raspberry Pi 用户你需要手动创建配置文件。同样你需要先在一个能运行 Claude Code CLI 的环境比如另一台 Mac或通过某些方法在 Linux 上运行 CLI获取到令牌。注意OAuth 令牌accessToken和refreshToken是高度敏感信息等同于你的账户权限。务必像保护密码一样保护它们。配置文件~/.claude-max-proxy.json创建后立即执行chmod 600命令确保只有文件所有者可读可写。3.2 获取 OAuth 令牌的详细步骤这是最关键的一步。官方 README 给出了 macOS 的命令我们展开讲讲原理和备选方案。方案一从 macOS 钥匙串提取推荐最安全security find-generic-password -s Claude Code-credentials -w | jq -r .claudeAiOauth这条命令做了两件事security find-generic-password这是 macOS 的系统命令用于访问钥匙串。-s “Claude Code-credentials”指定了要查找的条目名称-w参数表示只输出密码部分即存储的 JSON 字符串。| jq -r ‘.claudeAiOauth’将上一步输出的 JSON 字符串通过管道传给jq工具提取出claudeAiOauth字段的值-r参数表示输出纯文本去掉引号。如果你没有安装jq可以先用brew install jq安装或者手动执行第一步将输出的完整 JSON 复制出来找到claudeAiOauth字段的值。方案二从 Claude Code 的本地存储文件查找Claude Code CLI 会将令牌以加密或明文形式存储在本地配置目录。路径通常如下macOS:~/Library/Application Support/Claude Code/或~/Library/Preferences/Linux:~/.config/claude-code/或~/.local/share/claude-code/Windows:%APPDATA%\Claude Code\你可以在这些目录下寻找包含oauth、token、credentials等关键词的 JSON 或配置文件。请注意直接查看这些文件可能涉及解析加密数据且 Anthropic 可能随时更改存储格式此方法不稳定。方案三通过调试模式获取高级如果你熟悉网络调试可以在运行claude code命令时设置代理如mitmproxy或环境变量如NODE_OPTIONS“–inspect”来拦截其网络请求从请求头中提取Authorization: Bearer sk-ant-oat01-...的值。这种方法复杂但可以用于无法直接访问钥匙串的环境。获取到的claudeAiOauth字段值是一个完整的 JSON 对象它包含了accessToken、refreshToken和expiresAt。这就是你需要填入配置文件的内容。3.3 服务启动与验证克隆项目并进入目录git clone https://github.com/NYTEMODEONLY/claude-max-proxy cd claude-max-proxy对于 macOS自动钥匙串 直接运行node server.js即可。服务默认会在127.0.0.1:3456启动。你应该看到类似Claude Max Proxy v3.4.0 listening on http://127.0.0.1:3456的输出。对于 Linux/手动配置创建配置文件cat ~/.claude-max-proxy.json EOF { accessToken: sk-ant-oat01-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, refreshToken: sk-ant-ort01-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy, expiresAt: 1801509282451 } EOF chmod 600 ~/.claude-max-proxy.json请将xxxxxxxx和yyyyyyyy替换为你的真实令牌expiresAt也一并替换。启动服务node server.js。验证服务是否正常 打开另一个终端执行健康检查curl http://127.0.0.1:3456/health如果返回{“status”:”ok”, “version”:”3.4.0”, …}的 JSON说明代理服务运行正常。你也可以查询支持的模型列表curl http://127.0.0.1:3456/v1/models这会返回一个模型列表其中应该包含claude-opus-4,claude-sonnet-4,claude-haiku-4以及为了兼容 OpenAI 客户端而设置的别名gpt-4,gpt-4o等。4. 与主流客户端的集成配置代理跑起来了接下来就是让它为你心爱的客户端工作。这里以 OpenClaw 和 Cursor 为例其他任何支持自定义 OpenAI API Base URL 的客户端如 Continue.dev、开源 ChatUI 等配置思路都类似。4.1 集成 OpenClaw打造全能 AI 工作流OpenClaw 是一个功能强大的 AI 工作流工具支持多模型、多工具。将 Claude Max Proxy 集成进去意味着你可以用 OpenClaw 的统一界面免费调用最强的 Claude Opus 4.5 模型并且使用所有工具。配置步骤找到 OpenClaw 的配置文件。通常位于~/.openclaw/openclaw.json。如果不存在可以手动创建。编辑该文件将提供的配置片段合并进去。关键在于models.providers部分。你是在添加一个新的模型提供商provider命名为claude-max。配置解析“baseUrl”: “http://127.0.0.1:3456/v1”指向你本地运行的代理地址。如果你的 OpenClaw 运行在 Docker 或远程机器上需要将127.0.0.1改为代理服务器的实际 IP并确保防火墙开放了 3456 端口。“apiKey”: “not-needed”因为代理本身通过 OAuth 令牌认证所以这里任意字符串均可但不能为空。“api”: “openai-completions”告诉 OpenClaw 使用 OpenAI 的聊天补全接口格式。models数组定义了从这个提供商可以访问哪些模型。这里映射了三个 Claude 模型并设置了巨大的上下文窗口200K和输出令牌数65536以匹配 Claude 3.5 系列模型的实际能力。“cost”: {“input”: 0, “output”: 0}表示在 OpenClaw 的计费显示中将这些模型标记为免费。保存配置文件重启 OpenClaw。在模型选择列表中你应该能看到 “Claude Opus 4.5 (via Max Proxy)” 等选项。选择它现在你就可以在 OpenClaw 中像使用 GPT-4 一样使用 Claude Max 了并且工具调用会完全正常工作。4.2 集成 Cursor提升编码助手体验Cursor 是一款深受开发者喜爱的 AI 编程 IDE它底层也兼容 OpenAI API。通过配置 Claude Max Proxy你可以让 Cursor 使用 Claude Opus 来辅助编程在代码理解、重构和复杂问题解决上可能获得更好的效果。打开 Cursor进入设置Settings。找到 AI 模型配置相关部分。在较新版本的 Cursor 中通常可以在设置中搜索 “OpenAI” 或 “API”。你需要配置以下信息API Base URL: 设置为http://127.0.0.1:3456/v1API Key: 可以填写任意非空字符串如claude-max-proxy。Model: 这里需要填写代理支持的模型 ID例如claude-opus-4或gpt-4代理会将其映射到claude-opus-4。保存设置。现在当你在 Cursor 中使用 AI 功能如提问、自动补全、编辑时它就会通过你的本地代理调用 Claude Max 模型。实操心得在 Cursor 中有时模型别名gpt-4的兼容性更好因为 Cursor 的某些内部逻辑可能对gpt-开头的模型有特殊优化。如果直接使用claude-opus-4遇到问题可以尝试换成gpt-4。4.3 配置为系统服务长期运行在终端前台运行node server.js不是长久之计终端关闭服务就停了。我们需要将其配置为后台服务。对于 Linux/macOS (使用 systemd 用户服务) 这是最推荐的方式服务可以随用户登录自动启动并且有崩溃重启机制。创建服务单元文件。假设你的项目克隆在/home/yourname/claude-max-proxy。mkdir -p ~/.config/systemd/user cat ~/.config/systemd/user/claude-max-proxy.service EOF [Unit] DescriptionClaude Max Proxy v3.4.0 - OAuth Full Tool Support Afternetwork.target [Service] Typesimple WorkingDirectory/home/yourname/claude-max-proxy ExecStart/usr/bin/node /home/yourname/claude-max-proxy/server.js Restarton-failure RestartSec5 EnvironmentHOST0.0.0.0 # 如果需要从其他设备访问改为 0.0.0.0 [Install] WantedBydefault.target EOF关键点WorkingDirectory必须设置为项目根目录这样 Node.js 才能正确找到相关模块。ExecStart确保/usr/bin/node路径正确或用which node命令查看你的 Node.js 实际路径。EnvironmentHOST0.0.0.0如果你希望同一网络下的其他电脑或手机也能通过你的电脑使用这个代理比如在 iPad 上使用 OpenClaw 连接就需要绑定到0.0.0.0。注意安全仅在可信网络环境下这样做或者配合防火墙规则。重新加载 systemd 配置启用并启动服务systemctl --user daemon-reload systemctl --user enable claude-max-proxy systemctl --user start claude-max-proxy检查服务状态和日志systemctl --user status claude-max-proxy journalctl --user -u claude-max-proxy -f # 实时查看日志对于 macOS (使用 launchd) 如果你更喜欢原生的 launchd可以创建 plist 文件?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.user.claude-max-proxy/string keyProgramArguments/key array string/usr/local/bin/node/string string/path/to/claude-max-proxy/server.js/string /array keyWorkingDirectory/key string/path/to/claude-max-proxy/string keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/claude-max-proxy.log/string keyStandardErrorPath/key string/tmp/claude-max-proxy.err.log/string keyEnvironmentVariables/key dict keyHOST/key string0.0.0.0/string /dict /dict /plist将其放入~/Library/LaunchAgents/然后使用launchctl load ~/Library/LaunchAgents/com.user.claude-max-proxy.plist加载。5. 高级使用技巧与问题深度排查即使一切配置正确在实际使用中也可能遇到一些棘手的情况。下面分享一些我踩过坑后总结的经验和排查方法。5.1 工具调用失败与 “[Using tools…]” 循环这是 v3.4.0 之前版本最常见的问题。即使升级到 v3.4.0如果配置或使用不当仍可能发生。症状AI 回复“[Using tools…]”后后续对话停滞或者 AI 反复输出同样的工具调用而不处理结果。排查步骤确认版本首先运行curl http://127.0.0.1:3456/health确保version字段是“3.4.0”或更高。这是解决此问题的根本。检查代理日志启动服务时确保你在前台运行 (node server.js) 或者通过journalctl -f查看实时日志。发起一个带工具调用的请求观察代理的输入输出。关键看代理是否在发送请求前正确地将上一轮的tool_calls转换成了 XML 并插入历史。日志中通常会有[History] Reconstructing XML for tool call…之类的信息。检查工具定义确保你发送给代理的tools数组格式完全符合 OpenAI 的规范。特别是parameters字段必须是一个有效的 JSON Schema 对象。一个常见的错误是description字段缺失或过于简略Claude 有时需要清晰的描述来决定是否调用该工具。简化复现用一个最简单的工具比如一个返回固定字符串的echo函数和最简单的对话用户“请调用 echo 工具说 hello”来测试工具调用流程是否基本正常。排除复杂业务逻辑的干扰。5.2 令牌过期与刷新问题OAuth 令牌是有有效期的expiresAt字段。虽然refreshToken可以用来获取新的accessToken但代理项目本身截至我使用的版本似乎没有内置自动刷新逻辑。症状请求突然失败代理返回 401 错误或者在日志/Anthropic API 响应中看到“invalid_token”或“token expired”相关信息。解决方案手动更新令牌这是最直接的方法。重新在 Claude Code CLI 中登录如果已登录尝试claude code auth相关命令刷新然后按照3.2节的步骤重新提取最新的claudeAiOauthJSON更新你的~/.claude-max-proxy.json配置文件。重启代理服务更新配置文件后需要重启代理进程systemctl --user restart claude-max-proxy或 kill 掉旧进程重新运行node server.js新的令牌才会被加载。探索自动刷新高级你可以研究代理的源代码 (server.js)看它如何处理令牌。理论上可以在令牌即将过期时使用refreshToken向 Anthropic 的认证端点发起请求以获取新令牌并自动更新配置文件。但这需要修改代码并妥善处理文件写入权限和进程重载令牌的问题。5.3 性能调优与网络考虑代理作为中间层必然会引入少量延迟。在本地网络下这个延迟通常 50ms几乎可以忽略不计。但在某些场景下你可能需要优化。并发与超时如果你开发的客户端会同时发起大量请求需要注意 Node.js 单线程事件循环的特性。代理默认可能没有设置复杂的连接池或限流。在高压下可能出现响应变慢。可以考虑使用pm2等进程管理器以集群模式运行多个代理实例pm2 start server.js -i max。同时在客户端配置合理的请求超时时间如 120 秒。远程访问延迟如果你将代理部署在家庭服务器上从外网访问延迟和稳定性将成为主要问题。可以考虑使用内网穿透工具如 frp、ngrok或云服务器反向代理提供更稳定的公网访问入口。在云服务器上直接部署代理。但请注意你需要将令牌文件安全地传输到服务器并确保服务器环境安全使用强密码、防火墙、非 root 用户运行。对于移动端使用延迟感知会更明显复杂工具调用可能不如在本地流畅。5.4 与特定客户端的兼容性问题虽然代理遵循 OpenAI API 规范但某些客户端可能有“非标准”的行为。流式响应Streaming一些高级客户端支持流式输出。代理的 v3.2.0 版本增加了流式过滤功能。确保你的客户端在发起请求时设置了“stream”: true并且代理能正常处理。如果遇到流式输出中断或格式错误可以尝试在客户端关闭流式模式。非标准字段有些客户端可能会在请求体中发送额外的字段如temperature,top_p,frequency_penalty等。代理需要能够识别并转发这些字段或者安全地忽略它们。查看代理日志如果发现未知字段被丢弃导致行为不符预期可能需要向项目提 Issue 或自行修改代码来支持。图像/多模态输入Claude 3.5 模型支持图像输入。OpenAI API 格式中图像是以 base64 编码的 URL 形式放在messages.content数组中的。你需要确认你使用的客户端是否以标准方式发送图像数据以及代理是否正确地传递了这些数据。这是一个相对高级的功能初期可以先用纯文本工具调用测试。6. 安全实践与风险规避运行这样一个代理本质上是在你的本地网络暴露了一个 API 端点并且使用了你的个人 Claude 账户令牌。安全不容忽视。最小化网络暴露除非必要永远不要将HOST环境变量设置为0.0.0.0。坚持使用默认的127.0.0.1这样只有本机可以访问。如果你需要在同一局域网内的另一台设备如平板使用设置HOST0.0.0.0后务必配置防火墙只允许特定 IP 地址访问 3456 端口。例如在 Linux 上使用ufwsudo ufw allow from 192.168.1.100 to any port 3456 # 仅允许 IP 为 192.168.1.100 的设备保护令牌文件再次强调~/.claude-max-proxy.json文件权限必须是600。不要将此文件上传到任何公开的 Git 仓库、云盘或分享给他人。它等同于你的账户密码。使用环境变量可选代理支持通过CLAUDE_ACCESS_TOKEN环境变量传递令牌。这比配置文件稍微安全一点因为令牌不会持久化在磁盘上但可能会在 shell 历史记录中留下。你可以这样启动export CLAUDE_ACCESS_TOKEN你的完整claudeAiOauth JSON字符串 node server.js对于 systemd 服务可以在Service部分添加EnvironmentCLAUDE_ACCESS_TOKEN你的JSON字符串。注意JSON 字符串中的引号需要转义。定期检查用量虽然 Claude Max 订阅目前是固定费用但了解使用情况是好的习惯。Anthropic 可能在未来调整策略。你可以通过 Claude 官网账户页面查看大致的用量统计。理解服务条款使用代理绕过官方客户端的限制可能处于 Anthropic 服务条款的灰色地带。虽然此项目在 GitHub 上公开且使用合法的 OAuth 令牌但你需要知晓其中潜在的风险。建议仅用于个人学习和研究避免大规模、自动化、商业化的滥用以免账户被封禁。这个项目是一个极佳的技术实践它巧妙地利用了现有协议的缝隙为开发者提供了更大的灵活性。它体现了开源社区“自己动手丰衣足食”的精神。通过它你不仅获得了一个强大的免费模型调用渠道更可以深入理解 AI API 通信、协议转换和系统集成的细节。在享受便利的同时保持对安全和规则的敬畏才能让它长久、稳定地为你服务。