Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Primeiros passos

Teste para agentes e vinculação

Tente uma busca Google antes de se inscrever, e conecte uma conta do proprietário para continuar usando o mesmo perfil CLI.

Nesta página

1. Verifique o acesso existente

Faça esta verificação gratuita no ambiente do seu agente. Se data.accessVerified é true e Google Search é permitido, reutilize esse acesso e pule para o passo 3. Sem nenhum perfil salvo, continue a passo 2. Retomar o acesso pendente ou bloqueado usando a seção de recuperação abaixo.

Verifique este perfil
flashdata auth status --json --non-interactive

Mantenha o mesmo perfil

Relatórios de acesso data.accessVerified: true, access: ready em data.identity.identity, e google_search em data.identity.permittedSources.

Esses comandos usam o perfil padrão e funcionam em Bash ou PowerShell. Para um perfil ou diretório de estado personalizado existente, adicione o mesmo nome --profile e --state-dir ABSOLUTE_PATH a todos os comandos, incluindo aqueles em um novo terminal.

FLASHDATA_API_KEY tem prioridade sobre a chave salva. Deixe essa variável sem definir ao testar o acesso temporário e a transferência de credenciais deste perfil. Use o mesmo usuário do sistema e preserve o diretório privado de estado; ele contém as credenciais, a prova de registro e o histórico de execuções.

Inspecione credentialProtection em auth status. Windows usa DPAPI, macOS usa Keychain, e Linux sem cabeça pode usar um arquivo credencial somente para proprietários. Uma loja OS disponível pode ser necessária com --credential-store os.

Use uma chave de proprietário existente

Uma pessoa em um terminal pode importar uma chave através do alerta escondido abaixo e pular o registro de teste e reivindicar. Os agentes devem fornecer no stdin com --api-key-stdin --non-interactive de sua loja secreta, nunca colocar uma chave em argumentos ou bate-papo.

Se o perfil já tem acesso diferente, reveja-o antes de usar auth login --replace. Importar outra chave não é a entrega da vinculação. MCP OAuth também é uma conexão de host separada.

Oculta chave prompt - terminal humano
flashdata auth login
flashdata auth status --json --non-interactive

2. Inicie um teste elegível

Faça o discover primeiro. Verifique data.onboardingAvailable e a mesada em data.onboarding.trial. Se estiver disponível, execute init uma vez para Google Search. O servidor verifica a elegibilidade, o CLI salva a chave temporária sem abrir a inscrição ou enviar uma consulta.

Verifique a disponibilidade. Livre
flashdata discover --json --non-interactive
Iniciar acesso temporário
flashdata init --name "Research assistant" --scopes google_search --json --non-interactive

Verifique o recibo de registro

Espere ok: true, data.status: trial e google_search em data.connection.scopes. Leia data.connection.trialExpiresAt e data.startingAllowanceCredits. A chave é guardada localmente, não impressa. Se data.currentBalanceAvailable é false, reexecute a verificação de equilíbrio antes de consultar.

Se a configuração já criou um acesso, reutilize-o. Para identificar a origem do primeiro cadastro do agente, adicione --client codex --audience coding ou --client openclaw --audience personal. Em uma nova tentativa, mantenha exatamente a mesma entrada; os rótulos não concedem permissões.

Créditos e limites do período de teste

Requisito equivalentes compartilhar o mesmo saldo de crédito inicial, não são pedidos ou quotas independentes. Fontes exclusivas de proprietários como YouTube Download não podem gastar créditos de teste.

LimiteO que verificar?
Créditos / expiraçãoPadrão atual: crédito 1 para horas 72. Leia a descoberta para a bolsa e a vida útil, o recibo dá o prazo de validade e fontes concedidas.
InscriçõesRegistros 3 por IP por hora 24, compartilhados por usuários desse IP. A cápsula de teste global também pode pausar novos registros.
ConcurrênciaMantenha o teste sequencial: um item por lote e um trabalho pendente. Verifique os limites devolvidos antes de enviar mais.

3. Faça uma pesquisa

Primeiro a visualização. Requer data.estimateAvailable, um preço google_search disponível em data.estimate.prices, e availableCredits cobrindo estimatedCredits. Pare se um verificação falhar. A prévia é gratuita, o próximo comando envia uma busca.

Verifique o equilíbrio e o custo. Sem perguntas
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactive
Uma busca. Até cinco resultados
flashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive

Confira o resultado

Espere ok: true e data.status: done. Leia os títulos, links e trechos em data.results[].organic e os créditos cobrados em data.usage.credits. Resultados organic vazios são válidos. Antes de vincular a conta, repetir exatamente esta tarefa com trial-search retorna o resultado salvo. Preserve o perfil, o estado e os resultados do teste de que precisar.

Verifique o saldo restante. Livre
flashdata account balance --json --non-interactive

4. Mantenha o acesso com uma conta do proprietário

A vinculação antes do teste expira se quiser uso contínuo ou recorrente. Quando o dono estiver pronto, faça isso no perfil original. Compartilhe apenas data.claimUrl e data.confirmationCode com eles; data.expiresAt dá o prazo.

O link dura 15 minutos, ou até o teste expirar, se antes. Criar o link não aprova acesso ou comprar créditos.

Crie um link de vinculação quando o dono estiver pronto.
flashdata auth claim --json --non-interactive

Aprovar no navegador

  1. O proprietário abre o link e se conecta, ou cria uma nova conta e verifica o e-mail. Uma nova inscrição retoma a vinculação após a verificação.
  2. Verifique a conta mostrada na página de reclamações. Para um proprietário diferente ou novo, use uma sessão de navegador separada. A conta assinada é a conta que pagará por pedidos posteriores.
  3. Digite o código de oito dígitos nessa página, reveja as permissões de produtos e o acesso ao equilíbrio compartilhado, então aprove. O dono lida com inscrição, aceitação legal, verificação por e-mail e consentimento.

Termine no terminal original

Após a aprovação, execute finish no perfil original dentro de horas 24. O CLI salva a chave do proprietário, verifica em um novo processo e reconhece a instalação. Nenhuma chave é copiada do navegador.

Salve e verifique o acesso do proprietário
flashdata auth finish --wait --timeout 10m --json --non-interactive
Então verifique de um novo terminal, o mesmo usuário e perfil do OS.
flashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive

Confirme o proprietário e o equilíbrio

Em auth status, verifique o accountId pretendido e alcances concedidos, mais os campos abaixo. Leia o novo saldo separadamente, pedidos futuros gastam os créditos compartilhados do proprietário. Créditos temporários não usados não são transferidos. Uma nova conta segue a elegibilidade normal, alegando que não acrescenta nenhum subsídio extra.

Reclamar muda a conta faturada. Para uma nova tarefa sob o proprietário, escolha uma nova corrida ID. Reusando uma execução de teste ID retorna run_account_mismatch sem enviar outra consulta; não transfere que corre para o proprietário.

"Campos esperados" "Excerto de resposta"
{
  "ok": true,
  "data": {
    "accessVerified": true,
    "identity": {
      "identity": {
        "accountType": "owned",
        "access": "ready",
        "installed": true,
        "recurringAllowed": true
      }
    }
  }
}

Escolha as permissões do produto

O catálogo de permissões HTTP separa trialEligible de ownerAllowed. Antes do primeiro registro, solicite apenas as fontes necessárias para a tarefa. requestedScopes contém os escopos solicitados; scopes contém o acesso atual da chave. Novos produtos exigem uma concessão explícita.

A aprovação permite usar o saldo compartilhado do titular, incluindo créditos comprados. Restringir as fontes não cria um limite de gastos por agente. MCP OAuth é uma conexão separada e não vincula este perfil da CLI.

Só precisa de download YouTube?

Use uma chave do proprietário com permissão youtube_download, importe-a e configure o armazenamento de destino. O download não usa créditos temporários.

CLI 1.2.1 ainda requer uma fonte trial elegível para init. Para o download somente a bordo antes da inscrição, use o fluxo de vinculação HTTP em auth.md. Não adicione uma fonte de teste não relacionada apenas para contornar a restrição do cliente.

Retomar um fluxo parado

O que parou?Próxima ação
RegistrarPara 429, espere por Retry-After. Para uma resposta perdida, tente novamente init com o mesmo perfil, prova e entrada exata. Mantenha o estado existente, não mude de IP ou inicie um teste de substituição.
PesquisarInspecione trial-search abaixo. Um timeout não prova que nenhum trabalho foi aceito; não altere o ID da execução para forçar uma nova tentativa.
Reivindicar ligaçãoSe o link expirou, mas o teste é válido, crie um novo link no mesmo perfil quando o dono estiver pronto. verificação o proprietário antes da aprovação.
DemissãoApós a aprovação, reexecute auth finish no perfil original dentro de horas 24. Até a aprovação, uma espera interrompida ou um reconhecimento perdido não requer um novo registro.
Expirado / estado perdidoPara um teste ou transferência expirado, ou um diretório privado perdido, use reconexão aprovada pelo proprietário ou importe uma chave do proprietário.
Inspecione a pesquisa salva. Não há nenhuma nova consulta
flashdata runs show trial-search --json --non-interactive