跳转到正文
中文
获取 API 密钥
浏览文档

开始使用

智能体试用与认领

注册前先尝试一次 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-interactive

2. 开始一次符合资格的试用

先运行 discover,检查 data.onboardingAvailable 及 data.onboarding.trial 中的额度。接入可用时,为 Google 搜索运行一次 init。服务端检查资格,CLI 保存临时密钥,不打开注册页,也不提交查询。

检查可用性 · 免费
flashdata discover --json --non-interactive
开始临时访问
flashdata 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-interactive
一次搜索 · 最多五条结果
flashdata 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-interactive

4. 连接所有者账户以继续使用

需要继续使用或执行周期任务时,在试用到期前认领。所有者准备好后,在原配置档运行此命令,仅向其展示 data.claimUrl 和 data.confirmationCode。截止时间见 data.expiresAt。

链接有效期为 15 分钟;试用更早到期时,以试用到期时间为准。生成链接不会批准访问,也不会购买 Credits。

所有者准备好后生成认领链接
flashdata auth claim --json --non-interactive

在浏览器中批准

  1. 所有者打开链接并登录,或新建账户并验证邮箱。新注册在验证后会恢复认领。
  2. 检查认领页显示的账户。使用其他或新所有者时,使用独立浏览器会话。当前登录的账户将承担后续请求费用。
  3. 在该页面输入八位确认码,审阅产品权限及共享余额访问,然后批准。由所有者完成注册、法律条款接受、邮箱验证及授权。

在原终端中完成交接

批准后,在 24 小时内从原配置档运行 finish。CLI 保存所有者密钥,通过新进程验证并确认安装,无需从浏览器复制密钥。

保存并验证所有者访问
flashdata auth finish --wait --timeout 10m --json --non-interactive
再从新终端检查 · 相同系统用户及配置档
flashdata 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