远程代理认证与凭据刷新

选择 API key、HTTP、ADC 或 OAuth，理解动态值、受限主机和重试。

This page has not been translated into English yet. The original Chinese version is shown below.

远程代理的认证放在定义文件 auth 块中，与主 Gemini 模型认证是不同连接。CLI 会依据 Agent Card 的 securitySchemes 检查是否满足服务要求。

API key 与 HTTP

类型	字段
apiKey	type、key，name 默认 X-API-Key
http Bearer	type: http、scheme: Bearer、token
http Basic	type: http、scheme: Basic、username、password
其他 HTTP scheme	type: http、scheme、value；value 是原始授权值

auth:
  type: apiKey
  key: $MY_API_KEY

这段放在完整 remote 定义的 frontmatter 中。它不会创建环境变量，需要运行环境已注入值。

动态值

apiKey/http 的 key、token、username、password、value 支持 $ENV_VAR、!command 和字面字符串。命令结果会去除首尾空白；$$ 与 !! 转义前缀。

使用 !command 会执行实际 Shell 命令，并可能在刷新时再次执行；应审阅命令内容，避免有副作用的取密步骤。不要把凭据直接写入共享项目定义。

Google ADC

auth:
  type: google-credentials

默认 scopes 为 cloud-platform。*.googleapis.com 使用 access token，*.run.app 使用 identity token；两者会缓存并自动刷新。该 provider 只向这些受支持的 Google 主机发送凭据，其他域会拒绝，需改用服务支持的其他方法。

本地可先运行 gcloud auth application-default login；云端或 CI 可用服务账号或工作负载身份。Google ADC 产生 Bearer token，因此与卡片中的 HTTP Bearer scheme 兼容。

OAuth

OAuth 使用 Authorization Code + PKCE，首次交互打开浏览器，持久保存 token 并刷新。client_id 为交互认证必需；client_secret 是否必需取决于服务是否接受 public client。

卡片声明 oauth2 authorizationCode 时，可发现 authorization_url、token_url 和 scopes；否则按服务配置。首次需浏览器登录的流程不能直接当作无人值守凭据已经准备好。

401/403 与重试

官方说明所有 auth provider 在 401/403 后重新取凭据，最多重试两次。apiKey 的 !command 也会重跑。认证重试不能修复错误权限、域名或不兼容 scheme；持续失败时检查卡片声明与服务授权，不要无限重复任务。