**Claude Code 伴侣** 是一款本地 API 代理工具，专为 Claude Code 设计，旨在通过多端点管理、格式验证和自动切换等功能，显著提升 Claude Code 的稳定性和可观测性。它提供友好的 Web 管理界面，方便新手快速上手和维护。
## **核心功能详解**
**1. 多端点负载均衡与故障转移：**
* **问题：** Claude Code 依赖的上游服务（端点）可能会出现不稳定，导致服务中断。
* **解决方案：** Claude Code 伴侣允许配置多个上游端点，并按照优先级顺序尝试连接。一旦检测到某个端点不可用，它会自动切换到下一个可用的端点，确保服务的连续性。
* **优势：** 避免了因单个端点故障导致的服务中断，提高了整体的可用性。用户可以根据实际情况配置多个备用端点，例如来自不同地区的服务器或不同的服务提供商。
* **实现方式：** 在 Web 管理界面中，用户可以添加多个端点，并设置它们的优先级。代理会按照优先级顺序尝试连接，并在失败时自动切换。
**2. 响应格式验证：**
* **问题：** 上游服务返回的数据格式可能不符合 Claude Code 的预期，导致解析错误或程序崩溃。
* **解决方案：** Claude Code 伴侣会对上游服务返回的响应进行格式验证，确保其符合 Anthropic 协议。如果检测到异常响应，它会断开连接并触发重连机制。
* **优势：** 避免了因数据格式错误导致的程序异常，提高了系统的健壮性。通过验证响应格式，可以及时发现上游服务的问题，并采取相应的措施。
* **实现方式：** 代理内置了 Anthropic 协议的验证逻辑，可以自动检测响应格式是否正确。如果检测到错误，它会记录错误日志并尝试重连。
**3. OpenAI 兼容节点接入：**
* **功能：** 除了 Anthropic 的端点，Claude Code 伴侣还支持接入 OpenAI 兼容的节点，例如 GPT-3、GPT-4、GLM、K2 等模型。
* **优势：** 扩展了 Claude Code 的能力，使其可以使用其他 AI 模型。用户可以根据自己的需求选择最合适的模型，并灵活地切换。
* **实现方式：** 在添加端点时，选择 “OpenAI 兼容” 类型，并设置默认的模型名称。代理会将请求转发到 OpenAI 兼容的端点，并将响应转换为 Claude Code 可以理解的格式。
**4. 智能故障检测：**
* **问题：** 即使端点恢复正常，也可能需要手动干预才能重新启用。
* **解决方案：** Claude Code 伴侣会自动标记异常端点，并在后台定期检测其恢复情况。一旦检测到端点恢复正常，它会自动将其重新加入可用端点列表。
* **优势：** 减少了手动干预的需求，提高了运维效率。通过自动检测和恢复端点，可以确保服务始终处于最佳状态。
* **实现方式：** 代理会定期向被标记为异常的端点发送健康检查请求。如果请求成功，则认为端点已恢复，并将其重新启用。
**5. 智能标签路由：**
* **功能：** 根据请求的路径、头部或内容，将请求路由到不同的端点。
* **优势：** 实现了更精细的流量控制，可以根据不同的业务需求选择不同的端点。例如，可以将特定类型的请求路由到性能更高的端点，或者将来自特定用户的请求路由到指定的端点。
* **实现方式：** 用户可以定义路由规则，指定哪些请求应该被路由到哪些端点。路由规则可以基于请求的路径、头部或内容进行匹配。
**6. 请求日志与可视化管理：**
* **功能：** 记录完整的请求和响应日志，并提供 Web 管理界面，方便用户查看端点状态、日志信息和系统监控数据。
* **优势：** 提供了全面的监控和诊断能力，方便用户及时发现和解决问题。通过查看日志，可以了解请求的处理过程，并分析性能瓶颈。
* **实现方式：** 代理会将所有请求和响应信息记录到日志文件中。Web 管理界面可以实时显示端点状态、日志信息和系统监控数据。
## **快速开始指南**
**1. 下载并解压：**
* 从 Release 页面下载对应操作系统的压缩包。
* 解压压缩包到指定目录。
**2. 第一次运行：**
* 直接执行程序（Linux/Windows 下的二进制文件）。
* 程序会在当前目录生成默认配置文件 `config.yaml`。
**3. 打开管理界面：**
* 在浏览器中访问 `http://localhost:8080/admin`。
* 使用 Web 管理界面进行配置和管理。
**4. 添加上游端点：**
* 进入 `Admin → Endpoints`。
* 点击 “新增” 按钮。
* 填写上游 URL、鉴权信息和类型（例如 Anthropic 或 OpenAI 兼容）。
* 拖拽可调整端点优先级，配置实时生效。
**5. 在 Claude Code 中使用：**
* 将 `ANTHROPIC_BASE_URL` 环境变量指向代理地址（例如 `http://localhost:8080/`）。
* `ANTHROPIC_AUTH_TOKEN` 可以随便设置一个，但是不能不设置。
* 建议设置 `API_TIMEOUT_MS=600000`，防止客户端超时。
* 建议设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`，避免 Claude Code 向其公司发送不必要的流量。
## **常见使用场景**
**1. 多个号池自动切换：**
* 将多个号池提供的端点信息（Auth Token 方式认证）添加到端点列表。
* 代理会按照顺序自动尝试，并在失败时切换。
* 可以通过拖拽来调整尝试顺序，操作实时生效。
**2. 使用第三方模型：**
* 对于提供了 Anthropic 类型端点入口的第三方模型（如 GLM 和 K2），可以直接像添加号池一样添加使用。
* 对于只有 OpenAI 兼容入口的第三方模型（如 openrouter 或火山千问），添加端点时选择 OpenAI 兼容端点，并设置默认模型名称。
## **总结**
Claude Code 伴侣是一款功能强大且易于使用的 API 代理工具，可以显著提升 Claude Code 的稳定性和可观测性。它通过多端点管理、格式验证、自动切换等功能，确保 Claude Code 始终能够正常运行，并提供全面的监控和诊断能力，方便用户及时发现和解决问题。无论你是新手还是经验丰富的开发者，都可以使用 Claude Code 伴侣来优化你的 Claude Code 体验。
kxn/claude-code-companion
https://github.com/kxn/claude-code-companion
暂无评论内容