代理的作用
Claude Code 代理是你在 Anthropic 编程 CLI 和回答的模型之间运行的任何服务器。Claude Code 读取 API 地址的环境变量,并将请求发送到该地址。如果该地址是代理,代理决定实际发生的情况:它可以记录流量、添加规则,或将调用转发给不同的模型。
关键细节在于 传输格式。Claude Code 使用 Anthropic 的 Messages 格式。https://api.claudecodeproxyapi.com/v1 接口使用 OpenAI Chat Completions 格式,模型 ID 为 uncensored。两者理念相近但不可互换,因此不能直接将我们的 URL 粘贴到 Claude Code 中。翻译层必须重写每个请求和响应,包括流式输出块和工具调用。
各组件的位置
| 部分 | 支持 | 任务 |
|---|---|---|
| Claude Code CLI | Anthropic Messages 格式 | 计划编辑、调用工具、显示差异 |
| 翻译代理(本地) | 两种格式 | 转换请求并流式传输,映射模型名称 |
| 此 API | OpenAI Chat Completions | 运行开放权重模型,按 token 计费 |
中间层由社区项目处理。LiteLLM 的代理和 claude-code-router 是两个为此目的有公开文档的项目。两者均为第三方软件,因此在基于它们构建之前,请查阅其当前文档以了解支持的版本和选项(flag)。如果途中出现任何故障,代理故障排除指南是首选起点,该网站还有一篇单独的逐步设置文章。
设置前:诚实地看待模型
Claude Code 是围绕 Anthropic 自己的模型构建的。替换为其他模型会改变行为,没有任何代理能完全隐藏这一点。此处的模型是一个由独立提供商运行的开放权重模型,经过调整,可在合法成人用途中不拒绝内容。它不是 Claude,也不是 Anthropic 或其他任何供应商的官方 API。
对于智能体式工作,它能为你提供:
- 使用
tools、tool_choice和流式tool_calls进行工具调用,结果以role: "tool"消息形式返回。 - 100,000 token 的上下文窗口,包含提示词和补全。
- 使用
response_format的 JSON 模式,以及通过 SSE 进行流式输出。
你应该自己验证的内容:它在长智能体循环中的表现如何,它生成格式错误的工具调用的频率,以及它如何处理你的语言和框架。在迁移整个工作流之前,从你的仓库中运行三到四个真实任务。注册后一键领取的 $0.50 试用额度就足够了。
先测试上游 API
在接触 Claude Code 之前,确认 API 端在普通请求(包括工具调用)下是否正常工作,因为智能体依赖它:
curl https://api.claudecodeproxyapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "List the files in the src folder."}],
"tools": [{
"type": "function",
"function": {
"name": "list_files",
"description": "List files in a directory",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'
良好的回答包含一个 tool_calls 条目,其中有 list_files 和 JSON 参数字符串。如果你看到这一点,上游已就绪,任何后续问题都属于代理或 CLI 配置。
两条路径及选择时机
路径 1:用于 Claude Code 的翻译代理
如果你喜欢 Claude Code 界面、其权限提示和工作流,并希望在其背后使用不同的模型,请选择此项。你在本地运行代理,将 CLI 指向它,并将 CLI 发送的模型名称映射到 uncensored。具体变量在文档和设置文章中涵盖。
路径 2:已支持 OpenAI 协议的客户端
几个开源编码助手和编辑器扩展(包括 Aider、Continue 和 Cline)可以直接使用任何 OpenAI 兼容接口。你输入基础 URL、密钥和模型名称,无需维护翻译层。如果你不需要特定的 Claude Code 界面,这是更短的路径,且出错的部分更少。
经验法则:如果你想快速在代码上试用模型,选择路径 2;如果你的团队已经依赖 Claude Code 工作流,选择路径 1。
编码会话的成本
智能体会重新发送大量上下文,因此输入 token 占账单的大部分。取一个包含 30 次请求的会话,每次请求包含 20,000 个输入 token(文件、历史、工具输出)和 800 个输出 token:
- 输入:30 x 20,000 = 600,000 token,即 0.6 x $0.15 = $0.09
- 输出:30 x 800 = 24,000 token,即 0.024 x $0.50 = $0.012
- 总计:$0.102
价格为每 1M 输入 token $0.15,每 1M 输出 token $0.50。计费从预付额度开始,无订阅,失败或被拒绝的请求不收费,且额度不失效。充值从 $20 到 $500 不等,从 $50 起赠送 +5%,从 $100 起赠送 +10%,从 $200 起赠送 +15%。该网站接受加密货币(TRC20 上的 USDT,Base 上的 USDC)充值。定价页面有完整表格,密钥页面是你使用 Google 或电子邮件注册的地方。
影响智能体循环的限制
完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个并发和每分钟 60 个请求。分发子任务的智能体可能会先触及并发上限。API 随后返回 HTTP 429,代码为 concurrency,而请求速率上限返回 rate_limited。临时过载也返回 429,并附带 Retry-After: 5。优秀的代理会在延迟后重试 429 错误,而流式请求会占用其槽位直到流结束,因此卡住的流会消耗你的配额。
请求体最多可达 8 MB。如果你的工具将大文件粘贴到提示词中,请牢记这一点,并将整个提示词保持在 100,000 token 窗口内。
本地代理的安全注意事项
代理会保存你的上游密钥,因此请将其视为凭据对待。除非确实需要其他机器访问,否则将其绑定到 localhost,而不是所有网络接口。将密钥存储在环境变量或密钥管理器中,而不是存储在会提交到版本控制的文件中。如果在团队中共享代理,请为其分配独立的主密钥,以便你可以轮换密钥而无需更改上游密钥。
还要记住智能体发送的内容。编程 CLI 将文件内容、命令输出和你的提示词转发给模型。提示词不用于训练,但你仍应保留私钥和 .env 文件等敏感信息,使其不在智能体可以读取的工作目录中。
评估模型在代码方面表现的合理方式
从真实仓库中选择三个难度递增的任务:单文件修复、涉及三个文件的更改以及带有测试的小型重构。使用相同的提示词运行每个任务两次,一次使用当前模型,一次使用 uncensored,并记录四件事:编辑是否干净应用,工具调用是否解析,需要多少次重试,以及每次运行的成本。花一小时做这些比任何排行榜都能告诉你更多。
如果开放权重模型在最难的任务上表现不佳,你仍然可能发现它适合成本更低的任务,如起草测试、编写提交消息或解释不熟悉的代码。由于计费是从预付额度按量付费,无订阅,因此仅用于这些任务没有惩罚。
