浏览文档
开始使用
注册前先尝试一次 Google 搜索,再连接所有者账户,继续使用同一 CLI 配置档。
本页内容
1. 检查已有访问
在智能体运行环境执行此免费检查。若 data.accessVerified 为 true 且已获 Google 搜索权限,复用并跳至第 3 步。尚无配置档时,继续第 2 步。待完成或被阻止的访问,使用下方恢复部分继续。
flashdata auth status --json --non-interactive始终使用同一配置档
有效访问显示 data.accessVerified: true、data.identity.identity 中的 access: ready,且 data.identity.permittedSources 包含 google_search。
这些命令使用默认配置档,可在 Bash 或 PowerShell 中运行。已有命名配置档或自定义状态目录时,为每条命令添加相同的 --profile NAME 和 --state-dir ABSOLUTE_PATH,新终端中的命令也一样。
FLASHDATA_API_KEY 会覆盖已保存密钥。测试此配置档的试用及交接时,不设置该变量。使用相同系统用户并保留私有状态目录,其中保存凭据、注册凭证及运行历史。
检查 auth status 中的 credentialProtection。Windows 使用 DPAPI,macOS 使用 Keychain,无桌面 Linux 可能使用仅所有者可读的凭据文件。存在系统凭据存储时,可通过 --credential-store os 强制使用。
直接使用已有所有者密钥
人在终端中可通过下方隐藏提示导入密钥,跳过试用注册及认领。智能体应从密钥存储向 --api-key-stdin --non-interactive 提供标准输入,不将密钥放入参数或聊天。
若配置档已有其他访问,先检查,再使用 auth login --replace。导入另一把密钥不是认领交接;MCP OAuth 也是独立的宿主连接。
flashdata auth login
flashdata auth status --json --non-interactive2. 开始一次符合资格的试用
先运行 discover,检查 data.onboardingAvailable 及 data.onboarding.trial 中的额度。接入可用时,为 Google 搜索运行一次 init。服务端检查资格,CLI 保存临时密钥,不打开注册页,也不提交查询。
flashdata discover --json --non-interactiveflashdata init --name "Research assistant" --scopes google_search --json --non-interactive检查注册回执
预期 ok: true、data.status: trial,且 data.connection.scopes 包含 google_search。读取 data.connection.trialExpiresAt 及 data.startingAllowanceCredits。密钥保存在本地,不会输出。若 data.currentBalanceAvailable 为 false,查询前重新运行免费余额检查。
若 setup 已创建访问,直接复用。标记智能体首次注册来源时,添加 --client codex --audience coding 或 --client openclaw --audience personal。重试时保留完全相同的输入;标签不会授予权限。
试用额度与限制
请求等价次数共享同一起始 Credits 余额,不是剩余次数或独立配额。YouTube 下载等仅限所有者的来源不能使用试用 Credits。
| 限制 | 检查内容 |
|---|---|
| Credits / 到期 | 当前默认值:1 Credit,有效期 72 小时。从 discover 读取额度及有效时长,从回执读取到期时间及已授权来源。 |
| 注册 | 每 IP 每 24 小时 3 次注册,由该 IP 的用户共享。全局试用上限也可能暂停新注册。 |
| 并发 | 试用按顺序执行:每批一项、一个待处理任务。增加提交前检查返回限制。 |
3. 尝试一次搜索
先预览。要求 data.estimateAvailable 为 true、data.estimate.prices 中 google_search 价格可用,且 availableCredits 足以支付 estimatedCredits。任一检查失败时停止。预览免费,下一条命令才会提交一次搜索。
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactiveflashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive检查结果
预期 ok: true 且 data.status: done。从 data.results[].organic 读取标题、链接和摘要,从 data.usage.credits 读取费用。organic 为空也是有效结果。认领前,以 trial-search 重复完全相同的任务会返回已保存结果。保留配置档及状态,并保存需要保留的试用结果。
flashdata account balance --json --non-interactive4. 连接所有者账户以继续使用
需要继续使用或执行周期任务时,在试用到期前认领。所有者准备好后,在原配置档运行此命令,仅向其展示 data.claimUrl 和 data.confirmationCode。截止时间见 data.expiresAt。
链接有效期为 15 分钟;试用更早到期时,以试用到期时间为准。生成链接不会批准访问,也不会购买 Credits。
flashdata auth claim --json --non-interactive在浏览器中批准
- 所有者打开链接并登录,或新建账户并验证邮箱。新注册在验证后会恢复认领。
- 检查认领页显示的账户。使用其他或新所有者时,使用独立浏览器会话。当前登录的账户将承担后续请求费用。
- 在该页面输入八位确认码,审阅产品权限及共享余额访问,然后批准。由所有者完成注册、法律条款接受、邮箱验证及授权。
在原终端中完成交接
批准后,在 24 小时内从原配置档运行 finish。CLI 保存所有者密钥,通过新进程验证并确认安装,无需从浏览器复制密钥。
flashdata auth finish --wait --timeout 10m --json --non-interactiveflashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive确认所有者及余额
在 auth status 中核对预期 accountId、已批准 scopes 及下列字段。单独读取最新余额,后续请求使用所有者共享 Credits。未用完临时 Credits 不转移。新账户按正常注册资格处理,认领不会额外发放注册额度。
认领会更换计费账户。以所有者账户执行新任务时,选择新的运行 ID。复用试用运行 ID 会返回 run_account_mismatch,不提交新查询,也不会将该运行转移给所有者。
{
"ok": true,
"data": {
"accessVerified": true,
"identity": {
"identity": {
"accountType": "owned",
"access": "ready",
"installed": true,
"recurringAllowed": true
}
}
}
}选择产品权限
HTTP 权限目录区分 trialEligible 与 ownerAllowed。首次注册前,仅申请任务所需来源。requestedScopes 是申请范围,scopes 是密钥当前访问权限。新产品需要明确授权。
批准后使用所有者共享余额,包括购买的 Credits。来源限制不会创建独立智能体消费上限。MCP OAuth 是独立连接,不会认领此 CLI 配置档。
只需要 YouTube 下载?
使用具有 youtube_download 权限的所有者密钥,导入后配置目标存储。下载不使用临时试用 Credits。
CLI 1.2.1 的 init 仍要求可试用来源。注册前仅申请下载时,使用 auth.md 中的 HTTP 认领流程。不要为绕过客户端限制而添加无关试用来源。
继续中断的流程
| 中断位置 | 下一步 |
|---|---|
| 注册 | 429 时按 Retry-After 等待;响应丢失时,使用同一配置档、凭证及完全相同的输入重试 init。保留已有状态,不切换 IP,也不创建替代试用。 |
| 搜索 | 使用下方命令检查 trial-search。超时不代表未接纳任务,不要通过更换运行 ID 强制重试。 |
| 认领链接 | 链接到期但试用仍有效时,待所有者准备好,从同一配置档创建新链接。批准前检查登录账户。 |
| 交接 | 批准后,在 24 小时内从原配置档重试 auth finish。待批准、等待中断或确认响应丢失都不需要重新注册。 |
| 到期 / 状态丢失 | 试用或交接到期,或私有状态目录丢失时,使用所有者批准的重连或导入所有者密钥。 |
flashdata runs show trial-search --json --non-interactive