openclaw-cn 接入 Google Antigravity：google-antigravity-auth 插件 OAuth 认证全指南

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

本篇指南聚焦 openclaw-cn 官方内置的google-antigravity-auth提供商插件，讲解如何通过一条命令启用插件、使用models auth login完成 Google OAuth（PKCE）登录，并深入剖析插件源码中的授权码流程、本地回调服务、令牌刷新与模型路由细节。读完本文，你将能够在自己部署的 openclaw-cn Gateway 上完成 Google Antigravity（Cloud Code Assist）的接入与排障。

一、插件是什么：面向 Google Antigravity 的 OAuth 提供商

google-antigravity-auth是 openclaw-cn 内置（bundled）的 OAuth 提供商插件，为Google Antigravity（Cloud Code Assist）提供认证能力。它本质上是一个ClawdbotPlugin，通过插件 SDK 的api.registerProvider()在运行时注册一个 id 为google-antigravity的模型提供商（见 插件主实现）。

插件元信息定义在 openclaw.plugin.json：

{ "id": "google-antigravity-auth", "providers": ["google-antigravity"], "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } }

• providers声明该插件负责的提供商 ID；
• configSchema为空对象，说明该插件不需要任何额外的配置项，认证所需信息（Client ID、Scopes 等）全部内置于源码常量中；
• 包清单 package.json 通过clawdbot.extensions字段声明入口文件./index.ts。

注册的提供商信息（源码 index.ts）：

api.registerProvider({ id: "google-antigravity", label: "Google Antigravity", docsPath: "/providers/models", aliases: ["antigravity"], auth: [{ id: "oauth", label: "Google OAuth", hint: "PKCE + localhost callback", kind: "oauth", run: ... }], });

可以看到，该提供商支持别名antigravity，其唯一的认证方法是oauth（提示语为 "PKCE + localhost callback"，即 PKCE 授权码 + 本地回环回调）。registerProvider的底层注册逻辑位于 src/plugins/registry.ts，插件加载后该提供商会被写入 openclaw-cn 的提供商注册表，随后即可被模型选择、models auth login等命令识别。

二、启用插件：两步命令

openclaw-cn 的 bundled 插件默认处于禁用状态，google-antigravity-auth也不例外。官方文档 docs/concepts/model-providers.md 与插件 README 给出了相同的启用步骤：

openclaw-cn plugins enable google-antigravity-auth

启用后需要重启 Gateway才能生效（README 明确要求 "Restart the Gateway after enabling."）。

从实现层面看，plugins enable最终调用的是 src/plugins/enable.ts 中的enablePluginInConfig，它会对配置做三件事：

1. 若全局plugins.enabled === false，直接拒绝启用（返回reason: "plugins disabled"）；
2. 若插件位于plugins.deny拒绝列表，同样拒绝（reason: "blocked by denylist"）；
3. 否则在plugins.entries[pluginId]中写入enabled: true，并自动把插件 ID 追加到plugins.allow白名单（ensureAllowlisted），确保插件真正被加载器允许加载。

三、执行认证：models auth login

插件启用并重启 Gateway 后，执行登录：

openclaw-cn models auth login --provider google-antigravity --set-default

各参数含义（对应 src/cli/models-cli.ts 中的 auth login 子命令）：

• --provider <id>：指定提供商 ID，这里即插件注册的google-antigravity；
• --method <id>：可选的认证方法 ID，缺省时使用该提供商唯一的方法oauth；
• --set-default：认证成功后自动应用该提供商的默认模型推荐。插件登录成功会返回defaultModel: "google-antigravity/claude-opus-4-6-thinking"，并写入agents.defaults.models配置补丁，因此这条命令也是"登录 + 一键设为默认模型"的快捷方式。

需要说明的是，登录过程无需把任何 Client ID / Secret 填进openclaw.json。正如 docs/concepts/model-providers.md 所述，CLI 登录流程会把令牌存入 Gateway 主机上的 auth profiles（认证配置文件）中，Client 凭据由插件内部常量提供。

四、OAuth 流程源码剖析：PKCE + 本地回调

google-antigravity-auth采用PKCE（RFC 7636）授权码流程。整个loginAntigravity()核心实现见 index.ts，可拆解为以下阶段。

4.1 内置常量与 Scopes

源码顶部定义了 OAuth 所需常量（index.ts）：

const CLIENT_ID = decode("...base64..."); // Google OAuth Client ID const CLIENT_SECRET = decode("...base64..."); // Client Secret（服务端换码用） const REDIRECT_URI = "http://localhost:51121/oauth-callback"; const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"; const TOKEN_URL = "https://oauth2.googleapis.com/token"; const DEFAULT_PROJECT_ID = "rising-fact-p41fc"; const DEFAULT_MODEL = "google-antigravity/claude-opus-4-6-thinking";

其中 Client ID / Secret 以 base64 编码硬编码在源码中，并注释说明"从 pi-ai 的 base64 编码值解码以保持同步"，REDIRECT_URI固定指向本机回环地址127.0.0.1的51121端口。

申请的 OAuth Scopes 共 5 个：

const SCOPES = [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/cclog", "https://www.googleapis.com/auth/experimentsandconfigs", ];

cloud-platform用于访问 Google Cloud 项目资源，cclog与experimentsandconfigs是 Cloud Code Assist（Antigravity）内部服务所需的授权域，userinfo.email/profile用于拉取用户邮箱信息。

4.2 生成 PKCE 挑战码与授权 URL

generatePkce()（index.ts）生成 32 字节随机verifier（hex 编码），并对其做 SHA-256 后以base64url得到challenge；buildAuthUrl()（index.ts）拼装授权 URL，包含：

• client_id、response_type=code、redirect_uri；
• scope（上面 5 个 Scope 空格连接）；
• code_challenge+code_challenge_method=S256（PKCE 核心参数）；
• state（16 字节随机 hex，用于防 CSRF，登录成功后会被校验）；
• access_type=offline（申请刷新令牌）与prompt=consent（强制展示同意页，保证能拿到 refresh_token）。

4.3 两种回调方式：本地服务器与手动粘贴

loginAntigravity根据运行环境自动选择回调方式（index.ts）：

function shouldUseManualOAuthFlow(isRemote: boolean): boolean { return isRemote || isWSL2(); }

• 本机运行（非远程、非 WSL2）：调用startCallbackServer()在本机127.0.0.1:51121启动一个 HTTP 回调服务器（index.ts），随后自动用系统浏览器打开授权 URL，等待 Google 把授权码回调到/oauth-callback。回调成功后服务器立即返回一个 "Authentication complete" HTML 页面并自动关闭；整个等待超时时间为 5 分钟。
• 远程环境或 WSL2：因为远端/虚拟化环境无法访问本地localhost:51121回调，插件改为手动流程：在终端打印授权 URL（params.log会把 URL 原样输出，便于复制，源码注释提到这是修复 #1772 的做法），等待用户登录完成后把完整重定向 URL 粘贴回终端。parseCallbackInput()（index.ts）会校验粘贴内容必须是合法 URL 且包含code与state参数，否则报错并提示"请粘贴完整重定向 URL（不只是 code）"。

WSL 检测逻辑（index.ts）通过读取/proc/version判断是否包含microsoft/wsl（WSL）以及wsl2/microsoft-standard（WSL2），从而决定是否走手动流程。

4.4 校验 state 并换取令牌

无论走哪种回调，拿到code后都会先做state 校验：若回调返回的state与本地生成的state不一致，立即抛错 "OAuth state mismatch. Please try again."（index.ts）。

随后exchangeCode()（index.ts）向https://oauth2.googleapis.com/token发起表单 POST，携带client_id、client_secret、code、grant_type=authorization_code、redirect_uri与 PKCE 的code_verifier，换取access_token、refresh_token和expires_in。实现上有几个值得注意的细节：

• 强校验：缺少access_token或refresh_token都会分别抛错，绝不静默接受不完整响应；
• 过期时间预留缓冲：expires = Date.now() + expiresIn * 1000 - 5 * 60 * 1000，即把有效期提前 5 分钟视为过期，避免令牌在边缘时间失效导致请求失败。

4.5 拉取用户信息与项目 ID

换码成功后，插件并行完成两项信息补充：

1. fetchUserEmail()（index.ts）：调用https://www.googleapis.com/oauth2/v1/userinfo?alt=json获取用户邮箱，失败时静默返回undefined；
2. fetchProjectId()（index.ts）：依次向CODE_ASSIST_ENDPOINTS中的两个 Cloud Code Assist 端点发起v1internal:loadCodeAssist请求，从响应中的cloudaicompanionProject字段解析 Antigravity 绑定的 Google Cloud 项目 ID；两个端点都失败时回退到默认项目rising-fact-p41fc。

const CODE_ASSIST_ENDPOINTS = [ "https://cloudcode-pa.googleapis.com", "https://daily-cloudcode-pa.sandbox.googleapis.com", ];

4.6 登录成功后的落盘与配置补丁

整个run返回的认证结果会交给 openclaw-cn 的认证基础设施（index.ts）：

• profileId：google-antigravity:<email>，邮箱缺失时回退为google-antigravity:default。这与 docs/concepts/model-failover.md 描述的 OAuth 多账号失效转移约定一致——provider:<email>形式的 profile 可用于按账号区分与故障切换；
• credential：记录type: "oauth"、provider、access、refresh、expires、email、projectId等字段，令牌持久化到 Gateway 主机的 auth profiles 存储中；
• configPatch：把google-antigravity/claude-opus-4-6-thinking写入agents.defaults.models，并通过defaultModel字段声明默认模型——这就是--set-default的落点；
• notes：向用户提示 "Antigravity uses Google Cloud project quotas." 与 "Enable Gemini for Google Cloud on your project if requests fail."。

五、令牌的后续使用与自动刷新

登录只是开始。openclaw-cn 的 OAuth 令牌消费逻辑在 src/agents/auth-profiles/oauth.ts：

• buildOAuthApiKey()（oauth.ts）特别指出：google-gemini-cli与google-antigravity两个提供商需要projectId，因此会把{ token: access, projectId }序列化为 JSON 作为 API Key 使用；
• refreshOAuthTokenWithLock()（oauth.ts）在每次调用前检查Date.now() < cred.expires，未过期直接复用；过期则通过getOAuthApiKey()走刷新流程，并且整个读写过程使用proper-lockfile对 auth store 加锁，避免多进程并发刷新互相踩踏。

六、运行时模型侧集成：工具净化与模型兼容

接入 Antigravity 后，openclaw-cn 在模型运行时侧也做了针对性适配，这些代码位于 src/agents/pi-embedded-runner/ 与 src/agents/pi-embedded-helpers/google.ts：

• 工具 Schema 净化：sanitizeToolsForGoogle()针对google-antigravity与google-gemini-cli提供商，剔除 Antigravity 后端不支持的 JSON Schema 关键字（如minProperties、maxProperties），避免工具调用被拒；logToolSchemasForGoogle()还会在运行时输出净化后的工具索引便于调试；
• Thinking 块净化：sanitizeAntigravityThinkingBlocks()通过 base64 风格签名正则（ANTIGRAVITY_SIGNATURE_RE）识别并处理 Antigravity 返回的思考块，保持助手消息内容合法；
• 模型目录前向兼容：resolveAntigravityOpus46ForwardCompatModel()（model.ts）针对 pi-ai 模型目录可能滞后于真实平台的问题——当google-antigravity的模型 ID 包含opus-4-6（或opus-4.6）但注册表中还没有时，会克隆claude-opus-4-5模板以保证google-gemini-cli的 API 与 baseUrl 正确沿用；
• Claude 模型识别：pi-embedded-helpers/google.ts 通过modelId是否包含claude判断是否需要对 Antigravity 模型启用 Claude 相关的特殊处理。

这些适配说明google-antigravity不只是一个"能登录"的提供商，openclaw-cn 在模型路由、工具序列化、思维链解析层面都对其做了深度兼容。

七、注意事项与故障排查

结合插件 README 的 Notes 与源码实现，接入时请重点核对以下几点：

1. 配额与启用检查（README 原文）：
   • "Antigravity uses Google Cloud project quotas." —— Antigravity 消费的是 Google Cloud 项目配额，登录绑定的项目配额不足时请求会失败；
   • "If requests fail, ensure Gemini for Google Cloud is enabled." —— 若请求失败，请先在 Google Cloud 控制台确认该项目已启用Gemini for Google Cloud服务。
2. 启用插件后必须重启 Gateway，否则注册的提供商不可见；同时确认全局未设置plugins.enabled: false、插件未被加入plugins.deny（见 src/plugins/enable.ts）。
3. 远程服务器 / WSL2 环境：OAuth 回调走手动粘贴流程。登录完成后浏览器地址栏会显示形如http://localhost:51121/oauth-callback?code=...&state=...的 URL，请把完整 URL粘贴回终端，而不是只粘贴code（parseCallbackInput会严格校验）。
4. 回调端口冲突：回调服务器固定监听127.0.0.1:51121，若该端口被占用，插件会自动降级为手动粘贴流程（startCallbackServer失败时callbackServer = null），不影响最终完成登录。
5. 令牌过期：插件在exchangeCode阶段就把过期时间提前了 5 分钟，之后由 src/agents/auth-profiles/oauth.ts 的加锁刷新流程在过期后自动续期，日常使用通常无需手动重新登录。

八、延伸阅读

• 官方模型提供商总览：docs/concepts/model-providers.md，其中 "Google Vertex / Antigravity / Gemini CLI" 一节给出了与本文一致的启用与登录命令；
• OAuth 多账号与模型失效转移：provider:<email>profile 约定见 docs/concepts/model-failover.md；
• 认证健康检查与诊断：src/agents/auth-health.test.ts 与 src/agents/auth-profiles/ 中包含了 auth store 的读写与刷新行为测试；
• 同类插件对照：Gemini CLI 的 OAuth 插件google-gemini-cli-auth（见 extensions/google-gemini-cli-auth/），两者的启用、登录与令牌存储方式一致，可互为参考。

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音