# Prueba para agentes y vinculación a una cuenta

Prueba una búsqueda en Google antes de registrarte. Después, vincula una cuenta para seguir usando el mismo perfil de la CLI.

Referencia canónica: https://flashdata.dev/es/docs/guides/agent-onboarding
Revisado: 2026-11-04 por FlashData

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

## 1. Comprueba el acceso existente

Ejecuta esta comprobación gratuita en el entorno del agente. Si data.accessVerified es true y Google Search está permitido, reutiliza ese acceso y pasa al paso 3. Si no hay un perfil guardado, sigue con el paso 2. Para reanudar un acceso pendiente o bloqueado, consulta la sección de recuperación.

### Verificar este perfil

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

- [Instalar CLI](https://flashdata.dev/es/docs/guides/flashdata-cli/reference.md#install)
- [¿Ya tienes una clave?](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md#existing)
- [Recuperar el acceso](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md#help)

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

### Conserva el mismo perfil

El acceso válido muestra data.accessVerified: true, access: ready en data.identity.identity y google_search en data.identity.permittedSources.

Estos comandos usan el perfil predeterminado y funcionan en Bash y PowerShell. Si utilizas un perfil con nombre o un directorio de estado propio, añade los mismos --profile NAME y --state-dir ABSOLUTE_PATH a todos los comandos, también en una terminal nueva.

FLASHDATA_API_KEY tiene prioridad sobre la clave guardada. Deja esta variable sin definir al probar el acceso de prueba y la transferencia de credenciales de este perfil. Usa el mismo usuario del sistema y conserva el directorio privado de estado: contiene las credenciales, la prueba de registro y el historial de ejecuciones.

Consulta credentialProtection en auth status. Windows usa DPAPI; macOS, Keychain. En Linux sin interfaz gráfica, puede usarse un archivo de credenciales accesible solo por su propietario. Para exigir un almacén del sistema disponible, usa --credential-store os.


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

### Usa una clave existente del titular

Una persona puede importar una clave mediante la entrada oculta que aparece abajo y omitir el registro de prueba y la vinculación. Los agentes deben leerla de su almacén de secretos y enviarla por stdin con --api-key-stdin --non-interactive; nunca deben incluirla en argumentos ni en el chat.

Si el perfil ya contiene otro acceso, revísalo antes de usar auth login --replace. Importar otra clave no equivale a completar la vinculación. MCP OAuth también crea una conexión independiente.

#### Entrada oculta de la clave · terminal de la persona

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

- [Gestión de claves API](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md)
- [MCP y otras opciones de autenticación](https://flashdata.dev/es/docs/guides/agent-access/reference.md)

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

## 2. Inicia una única prueba si cumples los requisitos

Ejecuta discover primero. Consulta data.onboardingAvailable y la asignación de data.onboarding.trial. Si el registro está disponible, ejecuta init una vez para Google Search. El servidor comprueba los requisitos; la CLI guarda la clave temporal sin abrir el registro de usuario ni enviar consultas.

### Consulta la disponibilidad · gratis

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

### Acceso temporal

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

- [Protocolo actual](https://flashdata.dev/auth.md)

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

### Revisa el comprobante de registro

Espera ok: true, data.status: trial y google_search en data.connection.scopes. Consulta data.connection.trialExpiresAt y data.startingAllowanceCredits. La clave se guarda localmente y no se muestra. Si data.currentBalanceAvailable es false, repite la comprobación gratuita del saldo antes de consultar.

Si la configuración ya creó un acceso, reutilízalo. Para etiquetar el primer registro del agente, añade --client codex --audience coding o --client openclaw --audience personal. En los reintentos, conserva la entrada exacta; las etiquetas no conceden permisos.


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

### Créditos y límites de la prueba

Las equivalencias de solicitudes comparten el mismo saldo inicial; no representan solicitudes restantes ni cuotas independientes. Las fuentes que exigen una cuenta de titular, como YouTube Download, no pueden usar créditos de prueba.

| Límite | Qué comprobar |
| --- | --- |
| Créditos y caducidad | Valores predeterminados actuales: 1 crédito durante 72 horas. Consulta discovery para conocer la asignación y la duración; el comprobante indica la caducidad y las fuentes concedidas. |
| Registro | 3 registros por IP cada 24 horas, compartidos por quienes usan esa IP. El límite global de pruebas también puede detener nuevos registros. |
| Concurrencia | Ejecuta las tareas de prueba en secuencia: un elemento por lote y un trabajo pendiente. Revisa los límites devueltos antes de enviar más. |

- [Créditos y recuentos de solicitud](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md#estimate)
- [Acceso solo a YouTube Download](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md#download-only)

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

## 3. Prueba una búsqueda

Previsualiza primero. Exige data.estimateAvailable, un precio disponible para google_search en data.estimate.prices y un availableCredits suficiente para cubrir estimatedCredits. Detente si falla alguna comprobación. La previsualización es gratuita; el siguiente comando envía una búsqueda.

### Comprueba saldo y coste · sin enviar consultas

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

### Una búsqueda · hasta cinco resultados

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


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

### Comprueba el resultado

Espera ok: true y data.status: done. Consulta los títulos, enlaces y fragmentos en data.results[].organic, y el cargo en data.usage.credits. Un resultado organic vacío es válido. Antes de vincular la prueba, repetir esta tarea exacta con trial-search devuelve el resultado guardado. Conserva el perfil, el estado y los resultados de prueba que necesites.

#### Comprueba el saldo restante · gratis

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

- [Interpreta la respuesta de búsqueda](https://flashdata.dev/es/docs/guides/http-quickstart/reference.md#result)

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

## 4. Conserva el acceso con una cuenta de titular

Vincula la prueba antes de que caduque para continuar usándola o programar tareas recurrentes. Cuando el titular esté listo, ejecuta este comando con el perfil original. Comparte únicamente data.claimUrl y data.confirmationCode; data.expiresAt indica el plazo.

El enlace dura 15 minutos, o hasta que caduque la prueba si ocurre antes. Crear el enlace no aprueba el acceso ni compra créditos.

### Crea el enlace cuando el titular esté listo

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


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

### Aprobar en el navegador

1. El titular abre el enlace e inicia sesión, o crea una cuenta y verifica su correo. Si crea una cuenta, la vinculación se reanuda automáticamente tras la verificación.
2. Comprueba la cuenta que aparece en la página de vinculación. Para usar otra cuenta o crear una nueva, abre una sesión de navegador independiente. La cuenta conectada pagará las solicitudes posteriores.
3. Introduce el código de ocho dígitos en esa página, revisa los permisos de productos y el acceso al saldo compartido, y aprueba si todo es correcto. La persona titular completa el registro, la aceptación legal, la verificación del correo y el consentimiento.


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

### Termina en la terminal original

Tras la aprobación, ejecuta finish con el perfil original en un plazo de 24 horas. La CLI guarda la clave del titular, la verifica en un proceso nuevo y confirma su instalación. No se copia ninguna clave desde el navegador.

#### Guarda y verifica el acceso del titular

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

#### Comprueba desde una terminal nueva · mismo usuario del sistema y perfil

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


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

### Confirma la cuenta y el saldo

En auth status, verifica el accountId previsto y los permisos concedidos, junto con los campos siguientes. Consulta el saldo actualizado por separado; las solicitudes futuras usan los créditos compartidos del titular. Los créditos temporales sin usar no se transfieren. Una cuenta nueva sigue las condiciones normales del registro; vincular una prueba no concede créditos adicionales de registro.

La vinculación cambia la cuenta facturada. Para una tarea nueva con la cuenta del titular, elige un nuevo ID de ejecución. Reutilizar un ID de prueba devuelve run_account_mismatch sin enviar otra consulta; no transfiere esa ejecución al titular.

#### Campos esperados · extracto de respuesta

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

- [Configurar tareas recurrentes](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)
- [Créditos después de vincular la prueba](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md#trial)
- [Revoca esta conexión](https://flashdata.dev/es/docs/guides/agent-access/reference.md#revoke)

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

## Elige los permisos de productos

El catálogo de permisos HTTP distingue trialEligible de ownerAllowed. Antes del primer registro, solicita solo las fuentes necesarias para tu tarea. requestedScopes contiene los permisos solicitados; scopes, el acceso actual de la clave. Los productos nuevos requieren una concesión explícita.

La aprobación permite usar el saldo compartido del titular, incluidos los créditos comprados. Restringir las fuentes no establece un límite de gasto por agente. MCP OAuth crea una conexión independiente y no vincula este perfil de la CLI.

- [Catálogo de permisos y protocolo HTTP](https://flashdata.dev/auth.md)

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

## ¿Solo necesitas YouTube Download?

Importa una clave del titular con permiso youtube_download y configura el almacenamiento de destino. Download no usa créditos temporales de prueba.

La CLI 1.2.1 aún exige una fuente apta para pruebas al ejecutar init. Para configurar solo Download antes de crear una cuenta, usa el flujo de vinculación HTTP de auth.md. No añadas una fuente de prueba ajena a tu tarea para eludir esta restricción del cliente.

- [Importa una clave del titular](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md#existing)
- [Configurar almacenamiento y descarga](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md)
- [Flujo HTTP solo para Download](https://flashdata.dev/auth.md)

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

## Reanuda un flujo detenido

| Paso detenido | Siguiente acción |
| --- | --- |
| Registro | Ante un 429, respeta Retry-After. Si se pierde la respuesta, repite init con el mismo perfil, la misma prueba de registro y la entrada exacta. Conserva el estado existente; no cambies de IP ni crees otra prueba. |
| Búsqueda | Inspecciona trial-search con el comando de abajo. Un tiempo de espera agotado no demuestra que el trabajo no se aceptó; no cambies el ID de ejecución para forzar otro intento. |
| Enlace de vinculación | Si el enlace caducó pero la prueba sigue vigente, crea otro enlace con el mismo perfil cuando el titular esté listo. Verifica la cuenta conectada antes de aprobar. |
| Transferencia de credenciales | Tras la aprobación, vuelve a ejecutar auth finish con el perfil original en un plazo de 24 horas. Una aprobación pendiente, una espera interrumpida o una confirmación perdida no requieren un registro nuevo. |
| Acceso caducado o estado perdido | Si la prueba o la transferencia caducaron, o se perdió el directorio privado de estado, usa una reconexión aprobada por el titular o importa su clave. |

### Inspecciona la búsqueda guardada · sin nuevas consultas

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

- [Guía de recuperación](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)
