文档 · 指南

Google Vertex AI 接入 Claude Code、Codex 等 Agent

Google Vertex AI（Google 文档现在叫 Gemini Enterprise Agent Platform）在你自己的 Google Cloud 项目里提供 Gemini，费用记在这个项目上。它还提供 DeepSeek、GLM、gpt-oss 等合作方和开放模型，以及 Anthropic 的 Claude。magpie 的 google-vertex 预设把它们接到 Claude Code、Codex、OpenCode 等 Agent，不需要 API Key：每次请求都用从你的 Google 凭据换来的令牌签名。

添加

开启 API。在项目里开启 Agent Platform API（aiplatform.googleapis.com），项目需要开通结算。
登录。运行 gcloud auth application-default login，或者准备好服务账号的密钥文件。
添加并测试。填上项目 id，再测一次：

终端

gcloud auth application-default login
magpie provider add google-vertex project=my-project
magpie provider test google-vertex

应用里的编辑器问的是同样的内容：项目 ID、位置、凭据文件和服务账号。TUI 的 a 只问项目，其余用 CLI 设置。添加、列出和查看都不会访问 Google，凭据在签名请求时才读取。然后给 Agent 选模型：

终端

magpie claude google-vertex/claude-sonnet-5-5
magpie codex google-vertex/gemini-3.1-pro-preview

区域、凭据和服务账号

终端

magpie provider set google-vertex location=us-central1        # global (default), us, eu or a region
magpie provider set google-vertex credentials=~/keys/vertex.json
magpie provider set google-vertex impersonate=vertex@my-project.iam.gserviceaccount.com
magpie provider set google-vertex impersonate=                # empty clears it

location= 可以是 global（默认，留空也回到它）、us、eu，或 us-central1 这样的具体区域。
credentials= 指定一个凭据文件代替 gcloud 的登录，比如服务账号密钥；相对路径按运行命令的文件夹补全。
impersonate= 让请求以该服务账号的身份发出，你登录的账号需要在它上面有 Service Account Token Creator 角色。
API Key 和地址（url= 等）都会被拒绝：令牌只发往项目和区域决定的那一个地址。

每个区域的模型

每个区域提供的模型不同，而 Vertex AI 没有可以查询的列表，所以 magpie 给每个区域预设了它实际应答过的模型：

global：Gemini（gemini-3.8-flash、gemini-3.1-pro-preview、gemini-2.5-pro 等）、三个合作方模型，以及 claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5 等 Claude 模型。
us、eu：3.8、3.7、3.6、3.5 的 Flash，以及 gemini-3.5-flash-lite、gemini-3.1-flash-lite。
具体区域：gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite。

某个区域多提供一个模型（比如 asia-northeast1 的 gemini-3.5-flash）时，把想要的模型都填进去即可。换区域会保留已选的模型，换完请重新选。

合作方模型

合作方模型的 id 在斜杠前写着发布方，比如 deepseek-ai/deepseek-v4.1-flash-maas、zai-org/glm-5.2-maas、openai/gpt-oss-120b-maas。magpie 用同样的凭据，在你的项目里通过 Google 的 OpenAI 兼容 Chat Completions 调用它们，不用另外设置。其他合作方模型（预览版或 Google 之后上线的）按完整 id 填进去：

终端

magpie provider models google-vertex gemini-3.8-flash deepseek-ai/deepseek-v4.1-flash-maas google/gemma-4-26b-a4b-it-maas
magpie provider models google-vertex all     # back to the location's list
magpie provider test google-vertex zai-org/glm-5.2-maas

每个合作方模型都要先在项目的 Model Garden 里开启，否则 Google 会拒绝。magpie provider test google-vertex 测的是 Gemini，合作方模型要单独测：在应用里右键该模型，或者在命令后面加上模型 id。

Vertex AI 上的 Claude

id 以 claude- 开头的模型会在你的项目里走 Anthropic 的 Messages API（streamRawPredict），和 Claude Code 设置 CLAUDE_CODE_USE_VERTEX 时的调用方式一样，不需要再设置什么。不管 Agent 说的是哪种 API，都能用这些模型，Codex 和 OpenCode 也行。

global 列出当前的模型，id 和 Claude Code 在 Vertex AI 上用的一样。
旧模型用 Vertex 带日期的 id，比如 claude-sonnet-4-5@20250929，手动填入。
在 us-east5、europe-west1 等其他区域，把该区域提供的 Claude 模型填进去。
和合作方模型一样，每个 Claude 模型都要先在 Model Garden 里开启，并单独测试。

Priority PayGo 和 Flex PayGo

Google 的 Priority PayGo 和 Flex PayGo 通过请求头开启。编辑器的请求头里可以直接添加 X-Vertex-AI-LLM-Request-Type 和 X-Vertex-AI-LLM-Shared-Request-Type，值用 Google 文档给出的。命令行：

终端

magpie provider set google-vertex header.=

常见错误

no Google credentials at <file>：那里没有凭据文件。如果是你设的 credentials=，改正它或用 credentials= 清空；否则运行 gcloud auth application-default login。
GOOGLE_APPLICATION_CREDENTIALS names <file>, which isn't there 或 … not a full path：这个环境变量指向的文件读不到，也不会改用 gcloud 的凭据。写完整路径、取消这个变量，或者设置 credentials=。
the sign-in was refused：登录过期或被撤销，按提示重新运行 gcloud auth application-default login。下一次请求就会读新文件，不用重启。
403 PERMISSION_DENIED，提到 aiplatform.endpoints.predict：签名的账号（或它模拟的服务账号）不能在这个项目里用 Vertex AI。给它项目上的 Agent Platform User（roles/aiplatform.user）角色。
impersonating …: the sign-in was refused (403)：登录的账号需要在该服务账号上有 Service Account Token Creator（roles/iam.serviceAccountTokenCreator）。

常见问题

用 Vertex AI 需要 API Key 吗？

不需要。magpie 用 gcloud 的应用默认凭据、服务账号密钥文件或模拟的服务账号签名每个请求。API Key 会被拒绝。

Claude Code 能通过 magpie 用 Vertex AI 上的 Claude 吗？

能。claude- 开头的模型走 Anthropic 的 Messages API，和 CLAUDE_CODE_USE_VERTEX 的方式一样；Codex、OpenCode 等其他 Agent 也能用。先在 Model Garden 里开启该模型。

为什么换了区域后模型变了？

每个区域提供的模型不同：global 最全，us 和 eu 只有新的 Flash，具体区域是 2.5 系列。其他模型用 magpie provider models google-vertex 手动填入。

报 403 PERMISSION_DENIED 怎么办？

签名的账号需要项目上的 Agent Platform User（roles/aiplatform.user）角色；模拟服务账号时，登录的账号还要在它上面有 Service Account Token Creator。