【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载本文以 OpenShell 仓库中的架构文档 architecture/google-vertex-ai-provider.md 为主体结合 providers/google-vertex-ai.yaml 与crates/下的相关源码实现系统讲解google-vertex-aiprovider 的设计边界、两条凭证接入流、运行时数据流与端点约束。读完本文你将掌握如何在 OpenShell 中为选定沙箱授予对 Google Vertex AIAnthropic Claude、Gemini 及第三方模型的直接访问能力同时保证长期 Google 凭证不进入沙箱运行时。一、设计目标凭证与访问分离google-vertex-aiprovider 的核心设计是让被选中的沙箱直接访问 Google Vertex AI 端点而不向沙箱暴露任何长期有效的 Google 凭证。这一目标通过职责分离实现Provider profile 拥有端点策略与凭证元数据允许访问哪些主机、刷新约束、许可哪些二进制沙箱挂载sandbox attachment决定哪个工作负载获得访问权。值得注意的是该 provider不选择模型、不改写请求体。Anthropic Claude 走 Vertex 的 publisher-modelrawPredict或streamRawPredict路径Gemini 及其它模型使用 Google 文档化的原生或 OpenAI 兼容 Vertex API。所有模型选择、请求格式、流式模式和超时设置完全由工作负载自行决定proxy 只负责策略放行与凭证替换。二、组件职责边界组件职责CLI发现 ADC 或接收服务账户引导材料并创建 provider 记录Gateway通过凭证驱动存储刷新材料并轮换短时访问令牌Provider profile声明 Vertex 主机、凭证别名、刷新约束与许可二进制Sandbox supervisor下发不透明凭证占位符仅对 profile 授权的 Vertex 请求解析为真实令牌Workload选择原生 Vertex 端点、模型、请求格式、流式模式与超时从源码看CLI 侧的职责落在 crates/openshell-cli/src/commands/provider.rs它通过discover_from_profile发现本地已有凭证crates/openshell-providers/src/discovery.rs并通过read_gcloud_adc()解析 gcloud ADC 文件VertexProvider的实现则在 crates/openshell-providers/src/providers/vertex.rs。三、凭证流两条路径汇聚于轮换令牌Vertex 接受 Google 短期 OAuth2 访问令牌。两种受支持的接入方式最终都收敛为provider 记录中存放一个由 Gateway 轮换的访问令牌。3.1 服务账户Service account由运维人员使用服务账户引导材料创建 provider并配置google-service-account-jwt刷新策略私钥保留在 Gateway 凭证库中绝不进入沙箱Gateway 铸造GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN并在其过期前刷新。该策略在 crates/openshell-server/src/provider_refresh.rs 中实现mint_google_service_account_jwt使用 RSA PEM 私钥以 RS256 算法签名 JWTclaims 含issclient_email、scope、audtoken_url、iat/exp随后以grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer向https://oauth2.googleapis.com/token换取访问令牌。源码注释明确要求google_service_account_jwt策略必须至少声明一个 scope且private_key必须是 RSA PEM 格式否则直接返回 invalid_argument 错误。示例 profile 中该策略的完整配置见 providers/google-vertex-ai.yaml- name: service_account_token description: Google Cloud access token refreshed from service account JWT material env_vars: [GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN, VERTEX_AI_SERVICE_ACCOUNT_TOKEN] required: false auth_style: bearer header_name: authorization refresh: strategy: google_service_account_jwt token_url: https://oauth2.googleapis.com/token scopes: [https://www.googleapis.com/auth/cloud-platform] refresh_before_seconds: 300 max_lifetime_seconds: 3600 material: - name: client_email # Google 服务账户邮箱必填 - name: private_key # Google 服务账户私钥必填secret: true - name: subject # 可选域级委托的委托用户邮箱refresh_before_seconds: 300表示在令牌到期前 300 秒提前刷新max_lifetime_seconds: 3600限制令牌最长寿命为 1 小时。GOOGLE_SERVICE_ACCOUNT_KEY仅是引导材料bootstrap永远不会成为沙箱运行时材料的一部分。3.2 gcloud ADC本地开发针对本地开发场景CLI 提供--from-gcloud-adc选项流程为读取授权用户authorized-user类型的 ADC 文件将刷新授权refresh grant存储到 GatewayGateway 铸造GOOGLE_VERTEX_AI_TOKENADC 文件与刷新令牌均不进入沙箱。ADC 文件的查找顺序见 crates/openshell-cli/src/commands/provider.rsGOOGLE_APPLICATION_CREDENTIALS环境变量指定的路径CLOUDSDK_CONFIG目录下的application_default_credentials.json默认的$HOME/.config/gcloud/application_default_credentials.json。读取时会做严格校验仅接受type: authorized_user的 ADC 文件若发现type: service_accountCLI 会明确报错并提示改用服务账户 JSON 密钥创建 provider缺少client_id、client_secret或refresh_token任一字段都会直接失败。创建成功后ADC 的client_id、client_secret、refresh_token三项作为oauth2_refresh_token策略的 material 存入 Gateway。对应 profile 中的配置- name: gcloud_adc_token description: Google Cloud access token refreshed via gcloud Application Default Credentials env_vars: [GOOGLE_VERTEX_AI_TOKEN, VERTEX_AI_TOKEN] required: false auth_style: bearer header_name: authorization refresh: strategy: oauth2_refresh_token token_url: https://oauth2.googleapis.com/token scopes: [https://www.googleapis.com/auth/cloud-platform] refresh_before_seconds: 300 max_lifetime_seconds: 3600 material: - name: client_id # gcloud ADC 中的 Google OAuth2 client ID必填 - name: client_secret # gcloud ADC 中的 Google OAuth2 client secret必填secret: true - name: refresh_token # gcloud ADC 中的 Google OAuth2 refresh token必填secret: truediscovery.credentials: [service_account_token, gcloud_adc_token]声明了 CLI 自动发现--from-existing/ 自动创建 provider时扫描的凭证集合两条路径铸造的访问令牌通过auth_style: bearerheader_name: authorization声明在代理层以Authorization: Bearer token头发送。四、运行时数据流占位符到真实令牌文档给出了完整的数据流逐条展开挂载运维人员将 provider 挂载到沙箱attach策略合成生效策略effective policy包含该 profile 的 Vertex 端点与二进制规则下发占位符新启动的工作负载收到当前令牌的不透明占位符外加非机密的 project/region 配置请求发起工作负载以占位符作为Authorization: Bearer头调用原生 Vertex 端点代理替换策略与端点绑定校验通过后proxy 将占位符替换为当前真实访问令牌并转发请求刷新感知令牌刷新更新解析器resolver工作负载继续使用同一个占位符无需感知轮换。这一占位符 端点绑定解析机制在 crates/openshell-core/src/provider_credentials.rs 中有清晰的实现证据ProviderCredentialState::resolver_and_body_classifier_for_endpoint会按 hostHostPattern、端口与路径EndpointPathPattern过滤static_credential_bindings只有命中授权端点的凭证才会被scoped_to_env_keys限定暴露即仅对 profile 授权的 Vertex 请求解析令牌。文档同时强调原始GOOGLE_SERVICE_ACCOUNT_KEY凭证仅用于引导永不进入沙箱运行时材料。五、端点边界与请求形态示例 profileproviders/google-vertex-ai.yaml允许四个官方 Vertex 主机全部为 443 端口、rest 协议、read-write 访问、enforcement: enforce强制 L7 检查*-aiplatform.googleapis.com区域主机如us-central1-aiplatform.googleapis.comaiplatform.googleapis.com全局主机aiplatform.us.rep.googleapis.com美国副本主机aiplatform.eu.rep.googleapis.com欧洲副本主机工作负载自行构造 project、location、publisher、model 路径proxy 不推断 publisher也不改写请求体。Claude on Vertex 的请求形态如下https://location-aiplatform.googleapis.com/v1/projects/project/locations/location/publishers/anthropic/models/model:rawPredict请求体包含 Google 要求的 Vertex Anthropic API 版本流式请求走对应的原生流式端点streamRawPredict。六、安全不变量Invariants文档列出的不变量是理解该 provider 安全模型的关键刷新引导材料仅存在于 Gateway沙箱只收到占位符永不收到真实访问令牌令牌仅在挂载的 provider profile 覆盖的端点上解析解绑detach与过期即撤销占位符解析Project ID、region、publisher、model ID 属于非机密工作负载配置当 Gateway 全局策略覆盖抑制了 provider 派生策略时挂载 provider 不会授予访问权同一沙箱挂载多个 provider 时provider 环境键与动态凭证绑定必须保持无歧义。源码层面不变量 2/3/4 由上文提到的端点绑定解析器保证不变量 5 在 crates/openshell-core/src/google_cloud.rs 中体现——STATIC_CONFIG_KEYS将GCP_PROJECT_ID、GOOGLE_CLOUD_PROJECT、CLOUD_ML_REGION、GCP_LOCATION、GOOSE_PROVIDER、ANTHROPIC_VERTEX_PROJECT_ID、VERTEX_LOCATION等非机密配置定义为必须在子环境中解析为真实值的键而机密凭证如访问令牌保持占位符形态仅允许在代理时解析。七、环境变量注入VertexProvider 的实现细节VertexProvidercrates/openshell-providers/src/providers/vertex.rs负责把非机密配置注入沙箱环境配置键VERTEX_AI_PROJECT_ID注入GCP_PROJECT_ID、GOOGLE_CLOUD_PROJECTalias 数组见 crates/openshell-core/src/google_cloud.rs 的PROJECT_ID_ENV_VARS并额外注入 Claude Code SDK 读取的ANTHROPIC_VERTEX_PROJECT_ID配置键VERTEX_AI_REGION注入CLOUD_ML_REGION、GCP_LOCATION以及VERTEX_LOCATION注入GOOSE_PROVIDERgcp_vertex_ai用于向 Goose 标识 Vertex AI 场景不覆盖已存在的环境变量or_insert_with语义且跳过空值/纯空白配置。以上行为均有对应单元测试injects_project_id_and_anthropic_alias、injects_region_and_vertex_location、does_not_overwrite_existing_env、skips_empty_config_values等。profile 头部注释还提示VERTEX_AI_PROJECT_ID与VERTEX_AI_REGION会被投影进沙箱供 SDK 与 agent CLI 自动拾取目标项目。此外为兼容沙箱内 GCP SDK 的启动期探测provider_credentials.rs中的child_env_with_gcp_resolved会注入GCE_METADATA_IP指向127.0.0.1:8174的元数据模拟器回环地址与METADATA_SERVER_DETECTIONassume-present供 Node.js 的 gcp-metadata 跳过运行时 ping并将上述非机密配置键还原为真实值而机密令牌保持占位符。八、操作实践导入 profile、创建与挂载 provider示例 profile 不会被 OpenShell 自动加载需显式导入且官方建议复制后编辑而非原样导入——因为binaries是最小权限控制的关键必须指明你镜像中实际调用 Vertex 的二进制路径SDK 解释器、curl 或 agent CLI。# 1) 校验 profile 语法 openshell provider profile lint -f providers/google-vertex-ai.yaml # 2) 导入为全局 profile openshell provider profile import -f providers/google-vertex-ai.yaml --global # 3) 用 gcloud ADC 创建 provider本地开发 openshell provider create --type google-vertex-ai --name vertex-ai --from-gcloud-adc # 或使用已存在的环境凭证自动创建 openshell provider create --type google-vertex-ai --name vertex-ai --from-existing说明CLI 对google-vertex-ai类型的凭证解析会依次查找GOOGLE_VERTEX_AI_TOKEN、VERTEX_AI_TOKEN、GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN、VERTEX_AI_SERVICE_ACCOUNT_TOKEN见 crates/openshell-cli/src/commands/provider.rs 的missing_credentials_error也可直接用--from-gcloud-adc引导。挂载到沙箱并运行端到端验证# 挂载 providersandbox 生命周期操作需在创建沙箱时或对现有沙箱执行 openshell sandbox create --provider vertex-ai -- \ curl -sS -H Authorization: Bearer $GOOGLE_VERTEX_AI_TOKEN \ https://us-central1-aiplatform.googleapis.com/v1/projects/$VERTEX_AI_PROJECT_ID/locations/us-central1/publishers/google/modelsprofile 注释中给出的 smoke test 即以上形式在沙箱内用GOOGLE_VERTEX_AI_TOKEN占位符发起原生请求由 proxy 在策略与端点绑定校验通过后替换为真实令牌。文档特别提示挂载/解绑使用常规 sandbox provider 生命周期attach/detach运行中的沙箱会观察到策略与解析器变化但必须是在挂载后启动的进程才能拿到新的环境变量直接原生请求是端到端验证路径创建 provider 不会探测模型端点也不会校验 model ID 的有效性。若想验证沙箱当前挂载的 provider可运行openshell sandbox providers list对应源码中的list_sandbox_providers路径解绑使用 detach 操作解绑后占位符解析即被撤销满足不变量 4。九、适用前提与注意事项本文描述的配置基于当前仓库providers/google-vertex-ai.yaml实际内容Token 刷新参数refresh_before_seconds、max_lifetime_seconds、scopes可按需在复制的 profile 中调整但务必理解其安全含义缩短max_lifetime_seconds可降低令牌泄漏窗口scopes决定了令牌在 Google 侧的权限面。服务账户方式适合生产与无人值守场景私钥只在 Gateway 侧gcloud ADC 方式仅适合本地开发依赖用户授权。沙箱内工作负载如需使用$VERTEX_AI_PROJECT_ID等变量前提是创建 provider 时通过VERTEX_AI_PROJECT_ID/VERTEX_AI_REGION配置键提供了值可查看openshell provider create --help了解配置键写法。若你的镜像中调用 Vertex 的客户端不在 profile 的binaries白名单内二进制级流量归属将不生效——请务必按实际镜像内容补充binaries列表这是该 profile 的最小权限基石。十、小结google-vertex-aiprovider 通过Gateway 持有长期材料、沙箱只持有占位符、代理层按端点绑定解析真实令牌的三层模型在安全与便利之间取得了平衡工作负载获得了对 Vertex 的原生、直接访问而长期 Google 凭证始终留在 Gateway 凭证库中。配合 provider profile 的端点白名单与二进制许可该机制可作为 OpenShell 中受控接入外部 AI 推理服务的参考范式。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐VoltAgent Google AI Provider 集成指南基于 Gemini API 与 Vertex AI 的 Agent 构建与迁移VoltAgent Google AI Provider 集成指南基于 Gemini API 与 Vertex AI 的 Agent 构建与迁移 volta人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音langchaingo 中 Google 模型提供者完全指南googleai、Vertex AI 与 PaLM 的架构与实战langchaingo 中 Google 模型提供者完全指南googleai、Vertex AI 与 PaLM 的架构与实战 本指南以 llms/google人工智能大模型AI AgentRAG后端ZenML Vertex AI Step Operator 实战指南将流水线单步调度到 Google Cloud Vertex AI 执行ZenML Vertex AI Step Operator 实战指南将流水线单步调度到 Google Cloud Vertex AI 执行 ZenML 的 VMLOps机器学习后端工作流自动化AI Agent上一篇如何快速检测OpenSpeedy内存问题AddressSanitizer完整使用指南下一篇Red-Teaming-Toolkit第三方依赖项目使用的外部库与工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考