# Prova per agenti e collegamento

Provare una ricerca Google prima dell'iscrizione, quindi collegare un account proprietario per continuare a utilizzare lo stesso profilo CLI.

Riferimento canonico: https://flashdata.dev/it/docs/guides/agent-onboarding
Recensito: 2026-11-04 da FlashData

<a id="access"></a>

## 1. Controllare l'accesso esistente

Esegui questo controllo gratuito nell'ambiente del tuo agente. Se data.accessVerified è true e Google Search è permesso, riutilizzare l'accesso e saltare al passo 3. Senza profilo salvato, continuare a passare 2. Riprendi l'accesso in sospeso o bloccato utilizzando la sezione di recupero qui sotto.

### Controlla questo profilo

```bash
flashdata auth status --json --non-interactive
```

- [Installare CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#install)
- [Hai gia' una chiave?](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md#existing)
- [Recuperare l'accesso](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md#help)

<a id="prepare"></a>

### Mantenere lo stesso profilo

Rapporti di accesso di lavoro data.accessVerified: true, access: ready in data.identity.identity e google_search in data.identity.permittedSources.

Questi comandi utilizzano il profilo predefinito e funzionano in Bash o PowerShell. Per un profilo di nome esistente o una directory di stato personalizzata, applica lo stesso --profile NAME e --state-dir ABSOLUTE_PATH ad ogni comando, compresi quelli in un terminale fresco.

FLASHDATA_API_KEY ha la precedenza sulla chiave salvata. Lascia questa variabile non impostata quando provi l’accesso temporaneo e il passaggio delle credenziali di questo profilo. Usa lo stesso utente del sistema e conserva la directory di stato privata: contiene credenziali, prova di registrazione e cronologia delle esecuzioni.

Ispezionare credentialProtection in auth status. Windows utilizza DPAPI, macOS utilizza Keychain e Linux senza testa può utilizzare un file di credenziali solo per il proprietario. Un negozio OS disponibile può essere richiesto con --credential-store os.


<a id="existing"></a>

### Utilizzare una chiave proprietario esistente

Una persona in un terminale può importare una chiave attraverso il prompt nascosto qui sotto e saltare la registrazione di prova e rivendicazione. Gli agenti dovrebbero fornirlo su stdin con --api-key-stdin --non-interactive dal loro negozio segreto; non mettere mai una chiave in argomenti o chat.

Se il profilo ha già un accesso diverso, verificalo prima di utilizzare auth login --replace. L'importazione di un'altra chiave non è il corrispettivo. MCP OAuth è anche una connessione host separata.

#### Segnala chiave nascosta · terminale umano

```bash
flashdata auth login
flashdata auth status --json --non-interactive
```

- [Gestione delle chiavi API](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md)
- [MCP e altre opzioni di autenticazione](https://flashdata.dev/it/docs/guides/agent-access/reference.md)

<a id="trial"></a>

## 2. Avviare una prova idoneo

Eseguire discover prima. Controllare data.onboardingAvailable e l'indennità in data.onboarding.trial. Se è disponibile l'accensione, eseguire init una volta per Google Search. Il server controlla l'ammissibilità; lo CLI salva la chiave temporanea senza aprire la registrazione o inviare una query.

### Controllare la disponibilità · gratuita

```bash
flashdata discover --json --non-interactive
```

### Avviare l'accesso temporaneo

```bash
flashdata init --name "Research assistant" --scopes google_search --json --non-interactive
```

- [Protocollo attuale](https://flashdata.dev/auth.md)

<a id="trial-receipt"></a>

### Controllare la ricevuta di registrazione

Aspettatevi ok: true, data.status: trial e google_search in data.connection.scopes. Leggi data.connection.trialExpiresAt e data.startingAllowanceCredits. La chiave viene salvata localmente, non stampata. Se data.currentBalanceAvailable è false, eseguire il controllo dell'equilibrio gratuito prima di eseguire la querying.

Se la configurazione ha già creato l'accesso, riutilizzarlo. Per etichettare la prima registrazione di un agente, aggiungere --client codex --audience coding o --client openclaw --audience personale. Mantenere l'ingresso esatto su una riprovazione; le etichette non concedere autorizzazioni.


<a id="trial-limits"></a>

### Indennità di prova e limiti

Gli equivalenti di richiesta condividono lo stesso saldo di credito iniziale; non sono richieste rimanenti o quote indipendenti. Fonti proprietarie come YouTube Download non possono spendere crediti di prova.

| Limite | Cosa controllare |
| --- | --- |
| Crediti / scadenza | Predefinizioni attuali: credito 1 per le ore 72. Leggere la scoperta per la concessione e la durata della vita; la ricevuta dà la scadenza e le fonti concesse. |
| Registrazione | Registrazioni 3 per IP per 24 ore, condivise dagli utenti di tale IP. Il berretto di prova globale può anche mettere in pausa nuove registrazioni. |
| Convalida | Mantenere il lavoro di prova sequenziale: un elemento per lotto e un lavoro in sospeso. Controllare i limiti restituiti prima di inviare di più. |

- [Crediti e conteggi delle richieste](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md#estimate)
- [Accesso solo per il download](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md#download-only)

<a id="first-task"></a>

## 3. Prova una ricerca

Prima l'anteprima. Richiedere data.estimateAvailable, un prezzo google_search disponibile in data.estimate.prices e availableCredits che copre estimatedCredits. Smettila se un assegno fallisce. L'anteprima è gratuita; il comando successivo invia una ricerca.

### Controllare l'equilibrio e il costo · nessuna domanda

```bash
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactive
```

### Una ricerca · fino a cinque risultati

```bash
flashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive
```


<a id="result"></a>

### Verifica il risultato

Aspettatevi ok: true e data.status: done. Leggi i titoli, i link e i frammenti di data.results[].organic, e la carica di data.usage.credits. I risultati organici vuoti sono validi. Prima di rivendicare, ripetendo questo compito esatto con trial-search restituisce il suo risultato salvato. Mantenere il profilo e lo stato e mantenere i risultati di prova di cui hai bisogno.

#### Controllare il saldo rimanente · gratuito

```bash
flashdata account balance --json --non-interactive
```

- [Leggi una risposta di ricerca](https://flashdata.dev/it/docs/guides/http-quickstart/reference.md#result)

<a id="claim"></a>

## 4. Mantenere l'accesso con un account proprietario

Richiedere prima della scadenza della prova se si desidera un uso continuato o ricorrente. Quando il proprietario è pronto, eseguire questo nel profilo originale. Condividere solo data.claimUrl e data.confirmationCode con loro; data.expiresAt fornisce la scadenza.

Il collegamento dura i minuti 15, o fino alla scadenza della prova, se prima. La creazione del link non approva i crediti di accesso o di acquisto.

### Creare un link di reclamo quando il proprietario è pronto

```bash
flashdata auth claim --json --non-interactive
```


<a id="owner-approval"></a>

### Approva nel browser

1. Il proprietario apre il link e i segni in, o crea un nuovo account e verifica l'e-mail. Una nuova registrazione riprende il reclamo dopo la verifica.
2. Controllare l'account mostrato nella pagina di richiesta. Per un proprietario diverso o nuovo, utilizzare una sessione del browser separata. L'account firmato è l'account che pagherà per le richieste successive.
3. Inserire il codice a otto cifre su quella pagina, rivedere le autorizzazioni del prodotto e l'accesso condiviso-equilibrio, quindi approvare. Il proprietario si occupa di registrazione, accettazione legale, verifica e-mail e consenso.


<a id="finish"></a>

### Finitura nel terminale originale

Dopo l'approvazione, eseguire finish nel profilo originale entro le ore 24. CLI salva la chiave del proprietario, la verifica in un processo fresco e riconosce l'installazione. Nessuna chiave viene copiata dal browser.

#### Salvare e verificare l'accesso del proprietario

```bash
flashdata auth finish --wait --timeout 10m --json --non-interactive
```

#### Quindi controllare da un terminale fresco · stesso utente e profilo OS

```bash
flashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive
```


<a id="owner-result"></a>

### Confermare il proprietario e l'equilibrio

In auth status, verificare la destinazione accountId e gli ambiti assegnati, oltre ai campi sottostanti. Leggere il saldo fresco separatamente; le richieste future spendono i crediti condivisi del proprietario. I crediti temporanei non utilizzati non trasferiscono. Un nuovo account segue una normale idoneità all'iscrizione; la richiesta non aggiunge alcuna sovvenzione extra per l'iscrizione.

Rivendicare cambia l'account fatturato. Per un nuovo compito sotto il proprietario, scegliere una nuova esecuzione ID. Riutilizzando un'esecuzione di prova ID restituisce run_account_mismatch senza presentare un'altra query; non trasferisce che eseguire al proprietario.

#### Campi previsti · risposta excerpt

```json
{
  "ok": true,
  "data": {
    "accessVerified": true,
    "identity": {
      "identity": {
        "accountType": "owned",
        "access": "ready",
        "installed": true,
        "recurringAllowed": true
      }
    }
  }
}
```

- [Impostare le attività ricorrenti](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)
- [Crediti dopo la richiesta](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md#trial)
- [Rivolgere questa connessione](https://flashdata.dev/it/docs/guides/agent-access/reference.md#revoke)

<a id="permissions"></a>

## Scegli le autorizzazioni del prodotto

Il catalogo dei permessi HTTP distingue trialEligible da ownerAllowed. Prima della prima registrazione, richiedi solo le fonti necessarie per la tua attività. requestedScopes contiene i permessi richiesti; scopes indica l’accesso attuale della chiave. I nuovi prodotti richiedono un’autorizzazione esplicita.

L’approvazione consente di usare il saldo condiviso del titolare, inclusi i crediti acquistati. Le restrizioni sulle fonti non creano un limite di spesa per agente. MCP OAuth è una connessione separata e non collega questo profilo della CLI all’account.

- [Catalogo delle autorizzazioni e protocollo HTTP](https://flashdata.dev/auth.md)

<a id="download-only"></a>

## Solo bisogno di YouTube Scarica?

Utilizzare una chiave del proprietario con il permesso youtube_download, importarlo, quindi configurare lo storage di destinazione. Il download non utilizza crediti di prova temporanei.

CLI 1.2.1 richiede ancora una fonte di prova-eleggibile per init. Per il download solo a bordo prima dell'iscrizione, utilizzare il flusso di rivendicazione HTTP in auth.md. Non aggiungere una fonte di prova non correlata solo per bypassare quella restrizione client.

- [Importare una chiave del proprietario](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md#existing)
- [Configurare lo storage e il download](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md)
- [Flusso HTTP](https://flashdata.dev/auth.md)

<a id="help"></a>

## Riprendi un flusso interrotto

| Che cosa si è fermato | Prossima azione |
| --- | --- |
| Registrazione | Per 429, attendere Retry-After. Per una risposta perduta, riprova init con lo stesso profilo, la prova e l'ingresso esatto. Mantenere lo stato esistente; non commutare IP o avviare una prova di sostituzione. |
| Cerca | Controlla trial-search qui sotto. Un timeout non dimostra che il lavoro non sia stato accettato; non cambiare l’ID di esecuzione per forzare un nuovo tentativo. |
| Link di richiesta | Se il link è scaduto ma la prova è valida, crea un link fresco nello stesso profilo quando il proprietario è pronto. Controllare il proprietario firmato prima dell'approvazione. |
| Manifestazione | Dopo l'approvazione, eseguire auth finish nel profilo originale entro le ore 24. In attesa di approvazione, un'attesa interrotta o un riconoscimento perso non richiede una nuova registrazione. |
| Stato scaduto / perso | Per una prova scaduto o un handoff, o una directory di stato privata perduta, utilizzare il proprietario-approvato di riconnettere o importare una chiave del proprietario. |

### Ispezionare la ricerca salvata · nessuna nuova query

```bash
flashdata runs show trial-search --json --non-interactive
```

- [Guida di recupero](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)
