OpenClaw 接入 Claude Max API Proxy：用订阅额度复用 OpenAI 兼容接口的完整实战指南

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

Claude Max/Pro 订阅用户常遇到一个痛点：Anthropic 官方 API 按 token 计费，成本高昂，而订阅制套餐本身就包含充足的使用额度。claude-max-api-proxy正是为解决这一问题而生的社区工具——它把 Claude Max/Pro 订阅包装成本地 OpenAI 兼容 API 端点，让任何支持 OpenAI API 格式的工具（包括 OpenClaw）都能直接调用订阅额度。读完本文，你将掌握该代理的安装、启动、验证方法，并学会把它配置为 OpenClaw 的自定义模型端点，同时理解其底层"借道 Claude Code CLI"的工作原理与限制。

一、为什么要用 Claude Max API Proxy：订阅制 vs 按量计费的取舍

在 OpenClaw（本仓库项目，中文社区版，项目内文档与命令以openclaw-cn出现）中选择模型提供商，本质上是成本与场景的权衡。原文档给出了清晰的对比：

结论很直接：如果你已经持有 Claude Max/Pro 订阅，并且日常使用的主要是兼容 OpenAI 格式的工具，那么通过claude-max-api-proxy把订阅暴露成 API，可以在高频个人使用场景下显著节省费用。作为参考，仓库文档 docs/providers/anthropic.md 也提供了两条原生接入路径（API 密钥或 Claude Code CLI setup-token），本代理方案则是另一条完全独立的接入思路。

注意：claude-max-api-proxy 是社区工具，并非 Anthropic 或 OpenClaw 官方支持。使用前需确认你拥有有效的 Claude Max/Pro 订阅，且 Claude Code CLI 已完成登录认证。

二、工作原理：OpenAI 格式 → Claude Code CLI → 订阅额度

整个链路的示意图如下：

Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription) (OpenAI format) (converts format) (uses your login)

代理的职责分三步：

1. 接收OpenAI 格式的请求，监听地址为http://localhost:3456/v1/chat/completions；
2. 转换为 Claude Code CLI 命令，把请求体中的messages、model等字段映射为 CLI 可执行的指令；
3. 返回OpenAI 格式的响应，且完整支持流式输出（streaming）。

从 OpenClaw 仓库的实现可以印证这种"借道 CLI"的思路并非孤例：OpenClaw 本身就在 docs/gateway/cli-backends.md 中内置了claude-cli与codex-cli两类 CLI 后端，其默认参数可在 src/agents/cli-backends.ts 中看到，例如 Claude Code CLI 后端使用-p --output-format json --dangerously-skip-permissions以非交互方式调用本地 CLI。claude-max-api-proxy 的本质与这一机制同源——都是复用本机已登录的 Claude Code CLI 会话，从而把订阅额度变成可编程接口。

三、安装与前置条件

安装前需要满足两个前置条件：

• Node.js 20+；
• Claude Code CLI已安装并完成认证。

执行安装与验证：

# 全局安装代理 npm install -g claude-max-api-proxy # 验证 Claude CLI 已认证可用 claude --version

安装完成后即可启动服务：

claude-max-api # 服务默认运行在 http://localhost:3456

代理进程完全在本地运行，请求不会发送到任何第三方服务器，数据仅在本机与 Anthropic 之间流转。

四、快速验证：健康检查、模型列表与对话

服务启动后，依次用 curl 验证三个端点：

# 健康检查 curl http://localhost:3456/health # 列出可用模型 curl http://localhost:3456/v1/models # 发起一次对话补全请求 curl http://localhost:3456/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-opus-4", "messages": [{"role": "user", "content": "Hello!"}] }'

其中model字段使用代理自定义的模型 ID（见下表），请求与 OpenAI 官方/v1/chat/completions格式完全一致，这也是它能被任意 OpenAI 兼容客户端复用的关键。

五、可用模型映射

代理内置了三档模型 ID，分别对应 Claude 系列的不同规格：

在 OpenClaw 仓库的 CLI 后端实现中，src/agents/cli-backends.ts 也维护了一份类似的 Claude 模型别名表（opus/sonnet/haiku及其多版本映射），说明"短模型名映射到具体 Claude 型号"是这类工具通行的抽象方式，方便上层按档位（最强 / 均衡 / 轻量）选择模型。

六、接入 OpenClaw：把代理配置为自定义 OpenAI 兼容端点

在 OpenClaw 中，模型引用统一采用provider/model的格式（详见 docs/concepts/models.md）。针对本代理，标准做法是利用openai提供商的OPENAI_BASE_URL环境变量，把端点指到本地代理：

{ env: { OPENAI_API_KEY: "not-needed", OPENAI_BASE_URL: "http://localhost:3456/v1" }, agents: { defaults: { model: { primary: "openai/claude-opus-4" } } } }

要点说明：

• OPENAI_API_KEY填任意占位值（如"not-needed"）即可，因为代理本身不需要密钥校验；
• OPENAI_BASE_URL指向代理的/v1根路径；
• 默认模型写成openai/claude-opus-4，其中openai是提供商前缀，claude-opus-4是代理暴露的模型 ID。

如果希望用更精细的自定义提供商方式（而非全局覆盖openai端点），OpenClaw 还支持在models.providers中注册一个独立命名的提供商，docs/gateway/configuration-reference.md 中给出了完整的结构示例（baseUrl、apiKey、api: "openai-completions"、models列表等字段），同样适用于任何 OpenAI 兼容代理，包括本代理：

{ models: { mode: "merge", // merge（默认）| replace providers: { "claude-max": { baseUrl: "http://localhost:3456/v1", apiKey: "not-needed", api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai models: [ { id: "claude-opus-4", name: "Claude Opus 4", reasoning: false, input: ["text"] }, { id: "claude-sonnet-4", name: "Claude Sonnet 4", reasoning: false, input: ["text"] }, { id: "claude-haiku-4", name: "Claude Haiku 4", reasoning: false, input: ["text"] } ] } } } }

配置后即可用openclaw-cn models list/openclaw-cn models status校验模型是否进入目录（模型管理命令的完整用法见 docs/concepts/models.md）。

七、macOS 开机自启动：LaunchAgent 方案

为了让代理常驻运行，原文档提供了 macOS LaunchAgent 配置。将以下 plist 写入~/Library/LaunchAgents/com.claude-max-api.plist并加载：

cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF' <?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.claude-max-api</string> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>ProgramArguments</key> <array> <string>/usr/local/bin/node</string> <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string> </array> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string> </dict> </dict> </plist> EOF launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist

配置说明：

• RunAtLoad与KeepAlive均为true，保证开机即启动、进程退出后自动拉起；
• ProgramArguments中node的路径需与你机器上的实际安装位置一致（Homebrew 常见于/usr/local/bin/node或/opt/homebrew/bin/node）；
• EnvironmentVariables中的PATH同时覆盖了 Intel 与 Apple Silicon 的 Homebrew 前缀，确保claude等依赖命令可被找到。

提示：如果通过 launchd/systemd 等守护进程方式运行 OpenClaw 网关，其运行环境 PATH 往往被裁剪，无法找到claude命令。OpenClaw 的 CLI 后端文档 docs/gateway/cli-backends.md 中专门提到这种情况——建议在agents.defaults.cliBackends中为claude-cli配置command的完整路径，本代理的 LaunchAgent 配置同样遵循这一思路，为PATH显式补齐了常用目录。

八、使用注意与限制

结合原文档与 OpenClaw 仓库的 CLI 后端设计（docs/gateway/cli-backends.md），使用本方案前应明确以下几点：

1. 社区工具性质：claude-max-api-proxy 不受 Anthropic 或 OpenClaw 官方支持，遇到问题应在其 GitHub Issues 反馈；
2. 订阅依赖：必须持有有效的 Claude Max/Pro 订阅，且本机 Claude Code CLI 已登录认证，代理本质上是 CLI 会话的 HTTP 化封装；
3. 本地运行：代理监听localhost，不向第三方服务器转发数据；如需跨机器访问，需自行处理网络与安全策略；
4. 流式支持：代理完整支持 streaming 响应，适合需要打字机效果的聊天场景；
5. 能力边界：作为对照，OpenClaw 内置的 CLI 后端模式（claude-cli后端）明确不传递工具调用、不提供流式输出（见 docs/gateway/cli-backends.md 的 Limitations 一节）。claude-max-api-proxy 同样建立在 CLI 执行之上，若需要 OpenClaw 的工具调用、多模型故障转移等完整能力，官方支持的 Anthropic 提供商（docs/providers/anthropic.md） 与 OpenAI 提供商（docs/providers/openai.md） 仍是更完整的接入方式。

九、相关接入路径一览

若本代理不满足需求，仓库文档还提供了其他可行路径：

• Anthropic 提供商（docs/providers/anthropic.md）：原生集成，支持 API 密钥或 Claude Code CLI setup-token/OAuth 认证，可配置 Prompt 缓存；
• OpenAI 提供商（docs/providers/openai.md）：支持 OpenAI/Codex 订阅，可复用 Codex CLI 登录凭证；
• 模型提供商总览（docs/concepts/model-providers.md）：按提供商逐一的配置示例与 CLI 引导命令；
• CLI 后端（docs/gateway/cli-backends.md）：直接以claude-cli/...模型引用复用本机 Claude Code CLI，无需额外代理。

小结

claude-max-api-proxy 为"已有订阅、想用 OpenAI 兼容工具"的用户提供了一条低成本的本地桥接方案：一条命令安装、一条命令启动，通过OPENAI_BASE_URL即可接入 OpenClaw。理解其"订阅 → Claude Code CLI → 本地 API"的链路，能帮你判断它是否适合你的个人开发场景，也能在遇到问题时快速定位是订阅认证、CLI 环境还是配置指向出了问题。

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音