你需要什么
- 来自 密钥页面 的 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 |
| 上游 401 | UPSTREAM_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% 的奖励,不会让余额过期。
