中文 ▾

首页指南

Claude Code 代理设置:使用 OpenAI 兼容 API

此 Claude Code 代理设置分为五步:获取密钥、编写 LiteLLM 配置、启动代理、设置两个环境变量并运行测试。大约需要十分钟。

五块发光的垫脚石,从终端通向服务器,展示分步代理设置

要点

  1. 运行本地 LiteLLM 代理,将请求转发至 https://api.claudecodeproxyapi.com/v1
  2. 通过 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 将 Claude Code 指向代理
  3. 将 Claude Code 发送的模型名称映射到上游模型 uncensored
  4. 在启动 CLI 之前,使用 curl 测试代理

你需要什么

  • 来自 密钥页面 的 API 密钥。使用 Google 或邮箱密码注册,然后点击一次即可领取 $0.50 免费试用额度。
  • Python 3.9 或更高版本,用于安装代理。
  • 已在你的机器上安装并运行 Claude Code。

为什么需要代理?Claude Code 使用 Anthropic Messages 格式,而我们的 API 使用 OpenAI Chat Completions 格式,模型 ID 为 uncensored。代理负责在两者之间进行转换。如果你想先了解背景知识,请阅读 代理故障排除指南。该模型是开放权重模型,而非 Claude,因此在处理复杂的多步任务时,预期行为会有所不同。

步骤 1:安装代理

使用虚拟环境,使代理的依赖项与你的项目隔离:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM 是第三方开源软件。以下命令和配置键在编写时与其公共文档一致,但如果标志位发生变化,请查阅其最新文档。

步骤 2:编写配置

创建 config.yaml。model_name 是客户端发送的名称。litellm_params 块指定转发目标。openai/ 前缀告诉 LiteLLM 与 OpenAI 兼容的服务器通信。

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

别名 claude-sonnet 仅为示例,并非必需。Claude Code 可能会发送多种不同的模型名称,例如主模型和用于后台任务的小模型。在代理日志中看到的每个名称都添加一个 model_list 条目,所有条目均指向同一个上游。将所有别名指向 uncensored 是可以的,因为只有一个模型。

密钥从环境变量读取,因此不会落入你可能提交的文件中。

步骤 3:启动代理

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

保持此终端窗口打开。你应该看到服务器正在监听 4000 端口。现在从代理侧检查上游路径,发送一个 Anthropic 格式的测试请求,这正是 Claude Code 将发送的格式:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

如果 JSON 回复的内容包含单词 "ready",说明端到端转换正常:Anthropic 格式输入,转换为 OpenAI 格式发送至 https://api.claudecodeproxyapi.com/v1,然后返回。如果在 LiteLLM 配置中设置了主密钥,请使用它替换 sk-local-anything。

步骤 4:将 Claude Code 指向代理

Claude Code 从环境变量读取 API 地址和令牌。在启动 CLI 的 shell 中设置它们:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

此处使用代理地址,不要加 /v1 后缀,因为 CLI 会自带路径。Token 只需满足代理要求,因为真正的上游密钥是你导出的 UPSTREAM_KEY。如果使用 CLI 设置文件而非 shell 来存放环境变量,请将这三个名称也填入其中。Claude Code 的环境变量名在不同版本间可能变化,若被忽略,请对照最新文档核实。

步骤 5:运行首个任务并查看日志

从小处着手。让 CLI 解释一个文件或给函数添加注释。在代理终端中,你会看到每一步的请求。记录出现的每个模型名称;如果某个模型不在你的 model_list 中,代理会报错,因此请将其添加并重启。

此处工具调用很重要,因为 CLI 通过工具读取文件和编辑代码。API 支持 tools、tool_choice 和流式 tool_calls,代理会进行转换。对工具模式的遵循度较低会导致编辑失败或步骤重复。遇到这种情况时,先缩短任务再试,再判断是否为配置故障。

上下文窗口为 100,000 token,包含提示词和输出。超出此长度的长会话会失败,因此请为新任务开启新会话。成本极低:输入 token 每 1M 为 $0.15,输出 token 每 1M 为 $0.50:一次请求输入 20,000 token 且输出 800 token,费用为 $0.003 + $0.0004 = $0.0034。查看 定价页面 进行充值,本网站支持加密货币(TRC20 上的 USDT,Base 上的 USDC)支付。

故障排除

你看到的内容原因修复方法
连接被拒绝代理未运行或端口不同启动它,并在 ANTHROPIC_BASE_URL 中匹配端口
代理 404 或 "模型未找到"CLI 发送的模型名称未在配置中将该名称添加到 model_list
上游 401UPSTREAM_KEY 错误或为空在代理的 shell 中重新导出密钥并重启
429 错误对应 concurrency 限制超过 8 个并发请求(试用期间为 2 个)减少并发代理
429 带有rate_limited每分钟超过 300 个请求(试用版为 60 个)退避并重试
429 且 Retry-After: 5临时过载五秒后重试
流式输出停滞流式请求会占用其槽位直到结束在 CLI 中取消它以释放槽位

对于此处未涵盖的内容,在联系支持时请包含 X-Request-Id 响应头。文档 列出了所有支持的参数。

使其永久生效

每次手动输入 export 很繁琐。将代理启动放入一个小脚本中,将客户端变量放入别名中,这样一条命令即可启动所有服务:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

由于变量仅针对该命令设置,你的常规 claude 命令仍会按默认设置运行。将别名添加到你的 shell 配置文件中。使用 chmod 700 等文件权限保护脚本,因为它包含你的密钥。

切换回原状

如果你在当前的 shell 中导出了变量,请运行 unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL 并重新启动 CLI。API 端没有任何更改,因此无需撤销任何操作。

查看余额和支出

API 的每条响应都携带 X-Balance-USD,即你密钥中剩余的额度。在某些配置下,LiteLLM 可以透传上游的 HTTP 头,但查看余额最可靠的方法是直接调用上游服务:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

Agent 会话会悄悄增长。每一步都会重新发送工作上下文,因此长会话每次请求的成本高于短会话。为每个任务开启新会话可保持输入量小且账单低。按公布的价格(输入每 1M token $0.15,输出每 1M token $0.50),一次请求输入 50,000 token、输出 1,000 token 的成本为 50,000 x $0.15 / 1M = $0.0075 加上 $0.0005,即 $0.008。20 次此类请求总计 $0.16。

充值金额为 $20 至 $500的整数,通过本网站使用 TRC20 上的 USDT 或 Base 上的 USDC 支付。额度永不失效,因此大额充值附带 +5%、+10% 或 +15% 的奖励,不会让余额过期。

问答

Claude Code 代理需要哪些环境变量?

代理地址使用 ANTHROPIC_BASE_URL,代理接受的令牌使用 ANTHROPIC_AUTH_TOKEN。ANTHROPIC_MODEL 可以指定你定义的别名。请查看最新的 Claude Code 文档以获取变更说明。

我需要在 ANTHROPIC_BASE_URL 后面加上 /v1 吗?

不需要。使用代理地址(如 http://localhost:4000),因为 CLI 会自动附加其自己的路径。/v1 仅应出现在代理配置的上游 api_base 中。

我可以使用 LiteLLM 以外的代理吗?

可以。任何能将 Anthropic Messages 请求转换为 OpenAI Chat Completions 的代理均可使用,例如 claude-code-router。将其上游指向 https://api.claudecodeproxyapi.com/v1,模型设为 uncensored。

我的上游密钥在配置文件中安全吗?

请将其保存在环境变量中,而不是文件中,如上述配置所示。不要将密钥提交到代码仓库。

只差一张表单,即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。