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 Prompt）：API 可能期望收到一个特定的、硬编码的系统提示词，来验证请求的上下文。在这个代理中，使用的魔法咒语是：“You are Claude Code, Anthropic's 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 格式（XML）：Claude 模型（特别是通过 Claude Code）在思考后，如果决定调用工具，会在回复内容中直接输出 XML 标签，例如<function_calls>...<invoke name=\"get_weather\">...</invoke></function_calls>。

代理的工作流是一个完美的闭环：

请求转换（Client → Anthropic）：代理收到客户端的 OpenAI 格式请求。它首先将tools数组中的函数定义，转换成一段自然的文本描述，追加到第一条用户消息的末尾。然后，它检查历史消息中是否有上一轮的工具调用结果（OpenAI 格式），如果有，则将其“反向翻译”成 Claude 上一轮输出的 XML 格式，并插入到历史消息的合适位置。最后，它附上魔法系统提示词和 Beta 头，发送给 Anthropic API。
响应解析（Anthropic → Client）：Anthropic 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检查。如果版本低，建议使用nvm（Node 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/v1
- API 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] Description=Claude Max Proxy v3.4.0 - OAuth + Full Tool Support After=network.target [Service] Type=simple WorkingDirectory=/home/yourname/claude-max-proxy ExecStart=/usr/bin/node /home/yourname/claude-max-proxy/server.js Restart=on-failure RestartSec=5 Environment=HOST=0.0.0.0 # 如果需要从其他设备访问，改为 0.0.0.0 [Install] WantedBy=default.target EOF
```
关键点：
- WorkingDirectory：必须设置为项目根目录，这样 Node.js 才能正确找到相关模块。
- ExecStart：确保/usr/bin/node路径正确，或用which node命令查看你的 Node.js 实际路径。
- Environment=HOST=0.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 version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.user.claude-max-proxy</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/node</string> <string>/path/to/claude-max-proxy/server.js</string> </array> <key>WorkingDirectory</key> <string>/path/to/claude-max-proxy</string> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>StandardOutPath</key> <string>/tmp/claude-max-proxy.log</string> <key>StandardErrorPath</key> <string>/tmp/claude-max-proxy.err.log</string> <key>EnvironmentVariables</key> <dict> <key>HOST</key> <string>0.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，这样只有本机可以访问。如果你需要在同一局域网内的另一台设备（如平板）使用，设置HOST=0.0.0.0后，务必配置防火墙，只允许特定 IP 地址访问 3456 端口。例如，在 Linux 上使用ufw：
```
sudo 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部分添加Environment=CLAUDE_ACCESS_TOKEN=你的JSON字符串。注意，JSON 字符串中的引号需要转义。
定期检查用量：虽然 Claude Max 订阅目前是固定费用，但了解使用情况是好的习惯。Anthropic 可能在未来调整策略。你可以通过 Claude 官网账户页面查看大致的用量统计。
理解服务条款：使用代理绕过官方客户端的限制，可能处于 Anthropic 服务条款的灰色地带。虽然此项目在 GitHub 上公开，且使用合法的 OAuth 令牌，但你需要知晓其中潜在的风险。建议仅用于个人学习和研究，避免大规模、自动化、商业化的滥用，以免账户被封禁。

这个项目是一个极佳的技术实践，它巧妙地利用了现有协议的缝隙，为开发者提供了更大的灵活性。它体现了开源社区“自己动手，丰衣足食”的精神。通过它，你不仅获得了一个强大的免费模型调用渠道，更可以深入理解 AI API 通信、协议转换和系统集成的细节。在享受便利的同时，保持对安全和规则的敬畏，才能让它长久、稳定地为你服务。