claudecode-vertex-proxy

Claude to GCP Vertex AI Proxy

  English | 中文

一个用于将 Claude API 请求转换为 Google Cloud Vertex AI 格式的代理服务，使 Claude Code 客户端能够通过 GCP Vertex AI 访问 Claude 模型。

声明

本项目是为 Google Cloud Vertex AI 企业客户提供的协议转换工具，旨在简化 Claude Code 客户端与 GCP Vertex AI 的集成流程。

本项目：
- ✅ 是合法的 API 协议转换工具
- ✅ 面向已具备 GCP Vertex AI Claude 模型访问权限的用户
- ✅ 遵循 Google Cloud 和 Anthropic 的服务条款
- ❌ 不提供任何绕过授权或网络监管的功能
- ❌ 不提供任何免费访问付费服务的途径

使用前提：
- 您必须拥有有效的 Google Cloud 账户
- 您必须已在 GCP 项目中启用 Vertex AI API
- 您必须具备 Claude 模型的访问权限（通过 Vertex AI Model Garden）

合规要求：
- 使用本工具时，您应遵守 Google Cloud Platform 服务条款
- 使用本工具时，您应遵守 Anthropic 使用政策
- 使用本工具时，您应遵守所在地区的法律法规

环境变量配置

本程序支持以下环境变量：

凭据配置

将 GCP 服务账户 JSON 凭据文件放置于 key/key.json（默认路径）。

如需自定义，可通过环境变量指定：

区域配置

默认使用 global 区域。如需指定其他区域：

快速开始

第一步：安装 Claude Code

1. 卸载旧版本（如有）：

2. 安装官方版本：

第二步：启动代理服务

使用启动脚本（推荐，自动创建虚拟环境并安装依赖）：

启动脚本会自动：
- 创建 Python 虚拟环境（.venv）
- 安装所需依赖
- 启动代理服务

服务将在 http://0.0.0.0:8000 启动。

第三步：配置环境变量

在新的终端窗口中设置以下环境变量：

推荐：使用 zcf 配置工具

可使用 zcf (Zero-Config Flow for Claude Code) 进行持久化配置：

按界面提示完成配置即可。

第四步：使用 Claude Code

配置完成后，即可正常使用 Claude Code，所有请求将通过代理服务转发至 GCP Vertex AI。

验证服务状态

常见问题

Q: 代理服务启动失败

请检查：
- 凭据文件是否存在于 key/key.json（或 GCP_KEY_FILE 环境变量指定的路径）
- Python 依赖是否已正确安装
- 端口 8000 是否被占用

Q: 响应延迟或超时

请检查：
- 网络连接是否稳定
- 防火墙是否阻止了出站连接
- GCP 服务状态是否正常

Q: 权限错误

请确认：
- 服务账户具有 Vertex AI 访问权限
- GCP 项目已启用 Vertex AI API
- 凭据文件权限设置正确

技术说明

API 端点

日志文件

- api_requests.log - 详细请求/响应日志
- api_requests_simple.log - 精简对话日志

兼容性处理

- 自动移除 Vertex AI 不支持的 input_examples 字段
- 支持 Claude Code 模型名称映射
- 自动添加 anthropic_version 等必需字段

安全提醒

⚠️ 重要：
- 凭据文件（key/*.json）已在 .gitignore 中排除，请勿手动提交
- 建议仅在受信任的网络环境中运行本服务
- 定期轮换服务账户密钥

许可证

本项目采用 Apache License 2.0 开源。