Claude订阅代理工具：将官方CLI转为OpenAI兼容API

1. 项目概述：一个为“硬核玩家”准备的Claude订阅代理工具

如果你和我一样，已经为Claude Max或Pro订阅付了费，但总觉得官方提供的使用方式不够“自由”——比如，你希望能在自己编写的脚本里调用Claude，或者想用那些只支持OpenAI API格式的第三方工具来接入Claude的强大能力，那么你可能会对现有的方案感到束手束脚。直接使用Anthropic的官方API？那需要额外的API密钥和计费，等于为同一个能力付两次钱。寻找第三方逆向工程方案？往往伴随着账号风险、服务不稳定和复杂的配置。

claw-cli-proxy这个项目，就是在这种夹缝中诞生的一种非常规思路。它的核心目标极其明确：让你已经付费的Claude订阅，能够以一个标准的、OpenAI兼容的API端点形式提供服务。整个工具本身不持有、也不需要你的任何Anthropic账户令牌（Token），它只是一个“翻译官”和“调度员”。它的工作原理，是巧妙地利用了Anthropic官方发布的@anthropic-ai/claude-code命令行工具（CLI）。这个CLI工具本身，在你登录后，就具备了代表你与Anthropic服务器通信的合法身份。claw-cli-proxy做的事情，就是在本地启动一个HTTP服务，接收符合OpenAI API格式的请求，然后在背后悄悄地启动一个claudeCLI的子进程，将你的请求“翻译”成CLI能理解的命令，捕获CLI的输出，再“翻译”回OpenAI的格式返回给你。

从资源角度看，它追求极简：一个用Go编写的、没有任何第三方依赖的单一二进制文件，大小约8MB，运行时空闲内存占用仅10MB左右。这种设计哲学很“Go”，也意味着它几乎可以在任何地方运行，从你的开发笔记本到一台轻量级服务器。但必须强调，正如项目Disclaimer所说，使用这个工具可能存在违反Anthropic服务条款的风险，可能导致账户受到限制。这完全是一个“你知道你在做什么”的领域，适合那些希望完全掌控自己订阅使用方式的技术爱好者、研究人员进行探索。

2. 核心原理与架构拆解：为什么是“子进程”而非“令牌劫持”

理解claw-cli-proxy如何工作，是安全、有效使用它的前提。这也能帮你明白它的优势与局限性。

2.1 核心交互流程：一次请求的完整旅程

当你向claw-cli-proxy发送一个请求时，背后发生了一系列精密的协作。我们假设你发送了一个非流式（stream: false）的聊天补全请求。

1. 请求接收与解析：代理服务（运行在localhost:3456）接收到一个POST /v1/chat/completions请求，其载荷是标准的OpenAI格式，包含模型名（如claude-sonnet-4-6）、消息列表等。
2. 子进程生成：代理不会直接向api.anthropic.com发送HTTP请求。相反，它会在操作系统层面，生成一个新的claude命令行进程。这是最关键的一步。生成时，代理会将你的请求内容，经过格式转换，作为命令行参数或标准输入传递给这个子进程。具体来说，它构造了一个类似于claude --model claude-3-5-sonnet-20241022 --print '用户的问题在这里'的命令。
3. 身份认证与API调用：claudeCLI进程被启动。由于你之前已经通过claude auth login完成了认证，这个CLI进程内部持有了有效的、且是动态管理的OAuth凭证。由这个官方的CLI二进制文件代表你，向Anthropic的官方API发起HTTPS请求。从Anthropic服务器的视角看，这完全是一次来自官方客户端的、合法的用户请求，与你在终端里直接使用claude命令毫无二致。
4. 结果捕获与格式转换：CLI进程收到Anthropic API的响应后，会按照其既定格式（通常是JSON流或最终JSON）输出到标准输出（stdout）。claw-cli-proxy会实时捕获这些输出。
5. 响应重构与返回：代理解析CLI输出的原始数据，将其重新组装成OpenAI API格式的JSON对象，然后通过HTTP响应返回给你的客户端。

对于流式请求（stream: true），流程类似，但代理需要处理Server-Sent Events（SSE），将CLI的流式输出实时地、分块地翻译并推送回客户端。

2.2 关键设计优势：安全性与隐蔽性分析

这种“子进程代理”模式带来了几个传统逆向工程或令牌提取方案所不具备的优势：

• 零令牌暴露：你的Anthropic账户凭证（通常是OAuth refresh token）始终只存在于官方claudeCLI的认证缓存中（通常位于~/.config/@anthropic-ai/claude-code目录下）。claw-cli-proxy进程本身完全接触不到这些敏感信息。它只是启动了另一个程序，这极大地降低了因代理工具本身漏洞导致令牌泄露的风险。
• 对抗检测能力强：由于实际API调用是由官方的、持续维护的claudeCLI发出的，其网络请求的TLS指纹、HTTP头、重试逻辑、甚至心跳包都与正常客户端行为一致。这比用curl或自定义HTTP库模拟的请求要“真实”得多，更难被服务器端的异常流量检测机制识别。
• 自动维护性：claudeCLI自身会处理令牌刷新、API端点更新、模型列表同步等琐事。这意味着只要Anthropic更新了其官方CLI，你通过npm update升级CLI后，claw-cli-proxy就能自动获得与新API的兼容性，无需修改代理代码。
• 责任分离清晰：代理只负责协议转换和进程管理。所有与Anthropic服务条款直接相关的操作（认证、调用）都由官方CLI完成。这在技术架构上划清了一道界限。

2.3 固有局限性：你必须接受的妥协

当然，这种设计也引入了一些限制和额外考量：

• 性能开销：每个请求都需要启动一个新的操作系统进程。进程创建、销毁以及进程间通信（IPC）都会带来额外的开销，尤其是在高并发或频繁请求的场景下，这比纯内存中的HTTP客户端连接要慢，也会消耗更多CPU资源。
• 状态管理复杂：HTTP服务本质是无状态的，但每个CLI子进程都是独立的。这意味着跨请求的“对话记忆”无法由代理在CLI层面天然维护。如果你需要多轮对话，必须在每个请求的messages数组里携带完整的历史记录，由Anthropic的API在服务端处理上下文。代理本身不提供会话管理。
• 功能子集：你只能使用claudeCLI命令行所支持的功能。如果CLI本身不支持某个API参数（比如特定的温度设置范围、某些实验性功能），那么代理也无法提供。目前，代理主要映射了聊天补全这一核心功能。
• 错误处理耦合：代理需要正确解析CLI可能输出的各种信息，包括错误信息、进度提示等，并将其转化为有意义的HTTP状态码和错误体。如果CLI的输出格式发生变化，代理可能需要相应调整。

注意：启动子进程意味着你的系统必须已经正确安装并配置了claudeCLI，且其可执行文件位于系统的PATH环境变量中。这是代理能工作的绝对前提。

3. 从零开始：环境准备与部署实操

理论清楚了，我们来看看如何把它实际跑起来。整个过程可以分为几个清晰的步骤。

3.1 前置条件检查：确保基础环境就绪

首先，你需要一个有效的Claude订阅（Pro或Max），这是能力的源头。其次，准备你的工作环境：

1. 安装Node.js与npm：claudeCLI是一个Node.js包。你需要Node.js 16或更高版本。可以通过node --version和npm --version来检查。
2. 安装并认证Claude Code CLI：这是核心依赖。

   # 全局安装CLI npm install -g @anthropic-ai/claude-code # 进行认证，这会打开浏览器引导你登录Anthropic账户 claude auth login

   安装后，强烈建议在终端直接运行一次claude，随便问个问题，确保CLI能正常工作并返回结果。这验证了从安装、认证到网络连接的整个链路是通的。
3. 安装Go（仅从源码构建时需要）：如果你打算从源码编译claw-cli-proxy，需要Go 1.21或更高版本。通过go version检查。如果只使用预编译二进制，则不需要Go。

3.2 获取claw-cli-proxy：两种部署方式

项目提供了两种获取方式，推荐大多数用户使用一键安装脚本。

方式一：一键安装脚本（推荐）这是最快捷的方式。脚本会自动从GitHub Releases下载适用于你操作系统和CPU架构的最新预编译二进制文件，并放置到系统路径（如/usr/local/bin）。

curl -fsSL https://raw.githubusercontent.com/eltrovert/claw-cli-proxy/main/install.sh | bash

执行后，你应该可以直接在终端中运行claw-cli-proxy --help来验证安装。如果提示命令未找到，可能需要手动将二进制文件所在目录加入PATH，或者重启终端。

方式二：从源码编译适合开发者、或需要修改代码、或在一键脚本不支持的平台上部署。

git clone https://github.com/eltrovert/claw-cli-proxy.git cd claw-cli-proxy # 编译，生成名为 claw-cli-proxy 的二进制文件 go build -o claw-cli-proxy . # 编译完成后，当前目录下就会生成可执行文件

你可以将编译好的claw-cli-proxy文件移动到任何方便的地方，比如~/bin/或/usr/local/bin/。

3.3 启动与基础测试：验证服务运行

无论哪种方式，启动代理服务都非常简单。

1. 默认启动：在终端中直接运行二进制文件。

   ./claw-cli-proxy

   默认情况下，它会监听127.0.0.1:3456。你会看到类似Server listening on http://127.0.0.1:3456的日志输出。

2. 自定义配置启动：通过环境变量可以调整绑定地址和端口。

   # 监听在8080端口 PORT=8080 ./claw-cli-proxy # 监听在所有网络接口的9000端口（允许同一网络内其他设备访问） HOST=0.0.0.0 PORT=9000 ./claw-cli-proxy

   如果你需要代理在后台长期运行，可以使用nohup或系统服务（如systemd）进行管理，这里不展开。

3. 基础连通性测试：打开另一个终端标签页，使用curl测试健康检查端点。

   curl http://localhost:3456/health

   如果返回{"status":"ok"}，说明代理服务本身运行正常。

4. 核心功能测试：尝试发送一个简单的聊天请求。

   curl http://localhost:3456/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "stream": false, "messages": [{"role": "user", "content": "Hello, how are you?"}] }'

   你应该会收到一个格式类似OpenAI API的JSON响应。如果遇到错误，请检查：

   • 代理服务是否正在运行。
   • claudeCLI是否已安装并认证。
   • 模型名称是否拼写正确（支持多种别名，如claude-sonnet-4-6,sonnet,claw-son-4.6）。

4. 深度集成指南：以OpenClaw为例的客户端配置

claw-cli-proxy提供的是标准的OpenAI API兼容接口，这意味着理论上任何支持OpenAI API的客户端都可以接入。这里以功能强大的开源AI工作流工具OpenClaw为例，展示如何进行深度集成。OpenClaw本身支持多模型聚合和路由，配置稍复杂但功能完整，其他客户端（如LangChain、自定义脚本）的配置思路类似。

4.1 理解OpenClaw的Provider模型

OpenClaw通过“Provider”来管理不同的模型后端。每个Provider对应一个API端点（如OpenAI、Anthropic、本地模型等）。我们需要将claw-cli-proxy定义为一个新的Provider。

1. 定位配置文件：OpenClaw的全局配置通常位于~/.openclaw/openclaw.json。如果文件不存在，可以创建它。

2. 添加claw-cli Provider：在配置文件的providers对象下，新增一个名为claw-cli的配置块。关键点在于baseUrl要指向你运行的代理地址。

   { "providers": { // ... 你可能已有其他provider配置 ... "claw-cli": { "baseUrl": "http://localhost:3456/v1", // 注意结尾的 /v1 "apiKey": "not-needed", // 代理不需要API Key，但字段必须存在，可填任意值 "api": "openai-completions", // 声明使用OpenAI兼容接口 "models": [ { "id": "claw-opus-4.6", // 模型ID，与代理返回的列表一致 "name": "Claude Opus 4.6 (Claw CLI)", "reasoning": false, // 是否支持推理模式（本项目不支持） "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, // 成本设为0，因为走的是订阅 "contextWindow": 200000, "maxTokens": 32768 }, { "id": "claw-son-4.6", "name": "Claude Sonnet 4.6 (Claw CLI)", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 200000, "maxTokens": 16384 }, { "id": "claw-haiku-4.5", "name": "Claude Haiku 4.5 (Claw CLI)", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 200000, "maxTokens": 8192 } ] } } }

   为什么模型ID要用claw-opus-4.6而不是claude-opus-4-6？这是一个重要的实践细节。OpenClaw内部有一个模型查找链。如果你使用claude-opus-4-6这种通用ID，当你在其他Provider（比如官方的Anthropic API Provider）也配置了同名模型时，OpenClaw可能无法正确路由到claw-cli这个Provider。使用claw-前缀的点分版本ID（claw-opus-4.6），确保了ID在全局范围内的唯一性，避免了路由冲突。

4.2 配置代理与模型别名

为了让OpenClaw的Agent（智能体）能方便地使用这些模型，我们还需要在Agent配置中注册它们并设置别名。

1. 编辑Agent配置：Agent配置通常在另一个文件，或位于~/.openclaw/下的agents.json，也可能嵌套在主配置的agents字段下。请根据你的OpenClaw版本调整。这里假设在主配置中修改。

   { "agents": { "defaults": { "model": { "primary": "claw-cli/claw-son-4.6" }, // 设置默认模型 "models": { "claw-cli/claw-opus-4.6": { "alias": "cco46" }, // 设置短别名 "claw-cli/claw-son-4.6": { "alias": "ccs46" }, "claw-cli/claw-haiku-4.5": { "alias": "cch45" } } } } }

   模型的全名格式是{provider名称}/{模型ID}，即claw-cli/claw-son-4.6。为其设置一个简短的别名（如ccs46）可以极大地方便在命令行或脚本中调用。

2. 应用配置：保存配置文件后，需要重启OpenClaw的网关服务以使配置生效。

   openclaw gateway restart

3. 验证集成：现在，你可以在OpenClaw中使用新配置的模型了。例如，在OpenClaw的REPL或通过其CLI：

   # 使用别名调用模型 openclaw agent run --model ccs46 --prompt "你好，世界" # 或者使用全名 openclaw agent run --model claw-cli/claw-son-4.6 --prompt "Hello, world"

   如果一切配置正确，OpenClaw会将请求发送到你本地的claw-cli-proxy，代理调用claudeCLI，并返回结果。

4.3 其他客户端集成思路

对于其他客户端，配置的核心原则相同：将其OpenAI API的Base URL指向http://localhost:3456/v1，并提供一个任意的API Key（因为代理不验证）。

• LangChain (Python):

  from langchain_openai import ChatOpenAI llm = ChatOpenAI( base_url="http://localhost:3456/v1", api_key="not-needed", # 任意字符串 model="claude-sonnet-4-6", # 使用代理支持的模型别名 temperature=0.7, ) response = llm.invoke("Hello!") print(response.content)

• 自定义脚本 (cURL/HTTP库)：就像前面测试环节一样，直接向http://localhost:3456/v1/chat/completions发送POST请求即可。

5. 高级配置、调优与故障排查

基础运行和集成之后，我们来看看如何让它更稳定、更高效地工作，以及遇到问题时如何解决。

5.1 环境变量与运行参数

claw-cli-proxy的运行时行为主要通过环境变量控制：

启动示例：

# 在后台运行，开启调试，监听所有网卡端口9000，日志输出到文件 DEBUG=1 HOST=0.0.0.0 PORT=9000 ./claw-cli-proxy > proxy.log 2>&1 &

5.2 性能考量与优化建议

由于每个请求都涉及进程创建，性能是主要瓶颈。以下是一些优化思路：

• 请求合并与批处理：如果你的应用场景允许，尽量将多个短问题合并成一个稍长的请求，或者设计客户端进行简单的请求队列和批处理，减少进程创建/销毁的频率。
• 连接池与Keep-Alive：确保你的HTTP客户端（如OpenClaw、自定义脚本）启用了HTTP Keep-Alive。虽然代理本身是无状态的，但保持TCP连接可以避免为每个请求重建连接的开销。
• 资源监控：使用top,htop或ps aux监控claw-cli-proxy和claude进程的内存和CPU占用。在高负载下，注意系统是否有足够的资源（特别是文件描述符和进程数限制）。
• 避免高频轮询：不要用它来实现需要每秒多次查询的“实时”应用。它的设计更适合异步任务、批处理或交互频率不高的人机对话。

5.3 常见问题与排查清单

遇到问题，可以按照以下步骤排查：

问题1：启动代理失败，提示address already in use

• 原因：默认端口3456被其他程序占用。
• 解决：更改端口PORT=8080 ./claw-cli-proxy，或找出并停止占用3456端口的进程（如lsof -i :3456）。

问题2：健康检查通过，但发送聊天请求返回错误（如500 Internal Server Error）

• 第一步：设置DEBUG=1重启代理，重现错误，查看代理日志。日志中很可能会显示claudeCLI子进程输出的错误信息。
• 可能原因及解决：
  • claude: command not found：claudeCLI未安装或不在PATH中。确保已通过npm install -g安装，并能在终端直接运行claude。
  • Error: Not authenticated：CLI的认证已过期或无效。在终端运行claude auth login重新认证。
  • Error: Subscription required：当前登录的Anthropic账户没有有效的Pro或Max订阅。
  • FetchError: network timeout：网络问题导致CLI无法连接Anthropic服务器。检查你的网络连接，特别是能否正常访问Anthropic服务。
  • 模型名称错误：请求中model字段的值不在代理支持的列表内。使用GET /v1/models端点查看当前支持的模型列表。

问题3：请求响应非常慢

• 原因：进程启动开销、网络延迟、或Anthropic API本身响应慢。
• 排查：
  1. 在终端直接运行claude --model claude-3-5-sonnet-20241022 --print 'test'，看速度如何。这排除了代理的影响。
  2. 如果直接运行也慢，可能是网络或API服务问题。
  3. 如果直接运行快但通过代理慢，可能是代理所在机器性能不足，或并发请求时资源竞争。

问题4：OpenClaw或其他客户端无法连接

• 检查代理地址：确认客户端配置的baseUrl完全正确，包括http://和端口号。如果客户端和代理不在同一台机器，确保代理的HOST设置为0.0.0.0，并且防火墙放行了对应端口。
• 检查代理运行状态：在代理运行的机器上，用curl http://localhost:3456/health测试是否正常。
• 检查客户端日志：查看OpenClaw或其他客户端的详细日志，通常会有连接失败的明确原因。

问题5：流式响应（stream: true）不工作或提前中断

• 原因：流式响应对网络稳定性和客户端处理要求较高。代理需要持续读取CLI的子进程输出，并转换为SSE格式。任何一端的缓冲区满、连接中断或处理超时都可能导致问题。
• 解决：
  • 首先测试非流式请求是否正常，以确定不是基础功能问题。
  • 使用一个简单的SSE客户端（如curl命令）测试流式端点，观察输出是否持续。
  • 检查客户端代码是否正确处理了SSE连接的关闭和重连。
  • 在代理启动时加入DEBUG=1，观察流式过程中是否有错误日志。

重要提示：由于这个工具的工作机制高度依赖claudeCLI的稳定性和输出格式，任何Anthropic对CLI的更新都可能潜在影响代理的兼容性。保持claudeCLI更新到最新版本 (npm update -g @anthropic-ai/claude-code)，并关注claw-cli-proxy项目的更新，是维持长期稳定运行的关键。