Guía 03: Configuración y Autenticación del CLI Oficial de Bitwarden (@bitwarden/cli)#

1. El Problema con rbw (Cliente No Oficial)#

Al intentar utilizar clientes no oficiales como rbw para interactuar con Bitwarden desde la terminal, surgen dos problemas principales durante el proceso de registro (rbw register):

1. Bloqueo Interactivo (Screen Lock): El cliente se apropia de la pantalla de la terminal para introducir las credenciales, impidiendo cambiar de ventana para copiar y pegar claves de forma segura o cómoda.
2. Detección de Bots y Bloqueos (HTTP 503): Los servidores oficiales de Bitwarden implementan defensas severas (como Cloudflare) contra ataques automatizados. Intentar forzar el proceso de registro mediante “pipes” (printf "datos" | rbw register) frecuentemente activa estas defensas, provocando errores 503 (Servicio No Disponible) que impiden cualquier progreso temporalmente.

La solución definitiva es usar la herramienta oficial bw, la cual está diseñada nativamente para aceptar “API Keys” limpiamente, de forma silenciosa y sin alertar a los sistemas de seguridad antibots de Bitwarden.

2. Requisitos Previos: Generar Claves API#

Antes de interactuar con la terminal, es indispensable obtener las credenciales API personales desde la interfaz web de Bitwarden. Estas claves permitirán una autenticación programática segura, sin requerir el correo electrónico o la contraseña maestra durante el “login”.

1. Iniciar sesión en la bóveda web de Bitwarden (ej. vault.bitwarden.com o el servidor correspondiente a la región/empresa).
2. Ir a Opciones de la cuenta -> Seguridad -> Llaves (Keys).
3. Hacer clic en el botón “Ver API Key”.
4. Se mostrarán dos datos críticos:
   • client_id: Una cadena que siempre empieza con la palabra user..
   • client_secret: Una cadena larga y aleatoria.

(Advertencia de Seguridad: El client_secret nunca debe compartirse, pegarse en chats o guardarse en archivos de texto no encriptados).

3. Instalación de la Herramienta Oficial (@bitwarden/cli)#

En sistemas Linux/macOS con Node.js instalado, el método más directo y universal es mediante el gestor de paquetes de Node (npm).

1
# Instalar de manera global
2
npm install -g @bitwarden/cli

Verificar la instalación:

1
bw --version

4. El Proceso de Autenticación (El “Login Mágico”)#

Para evitar la introducción interactiva de credenciales y los bloqueos por bots, se utilizan las variables de entorno para pasar el client_id y el client_secret al comando de inicio de sesión de forma silenciosa.

(Consejo: Se recomienda colocar un espacio en blanco al inicio de los comandos export en la terminal de bash para evitar que los secretos queden registrados en el historial ~/.bash_history).

Ejecutar en la terminal, línea por línea:

1
 export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
2
 export BW_CLIENTSECRET="tu_cadena_secreta_larga_aqui"

A continuación, iniciar sesión utilizando explícitamente el modo API:

1
bw login --apikey

El servidor responderá con el mensaje: You are logged in!. Esto significa que la herramienta tiene permiso para comunicarse con la cuenta, pero la bóveda sigue encriptada (cerrada con llave).

5. Desbloquear la Bóveda (El Paso Crítico)#

Aunque la sesión esté iniciada mediante la API Key, los datos reales (contraseñas, notas) siguen protegidos por la contraseña maestra. Para operar con los elementos de la bóveda, se requiere “desbloquearla” y obtener una “Sesión Abierta” temporal.

1
export BW_SESSION=$(bw unlock --raw)

Este comando sí solicitará interactivamente la Contraseña Maestra (Master Password) en la terminal. Una vez ingresada correctamente, el comando descifrará la bóveda localmente, extraerá el token de sesión (BW_SESSION) y lo exportará automáticamente a la variable de entorno de la ventana actual de la terminal.

Mientras esa variable BW_SESSION exista en esa sesión de terminal específica, el cliente bw tendrá acceso completo y sin restricciones de contraseñas para ejecutar comandos de lectura y escritura.

6. Ejemplo: Crear un Elemento en la Bóveda (Guardar un ARL)#

Una vez que la bóveda está desbloqueada (BW_SESSION activa), se pueden automatizar tareas como inyectar un nuevo secreto directamente desde la línea de comandos, sin abrir un navegador.

El siguiente ejemplo demuestra cómo crear un nuevo elemento de tipo “Login” (Tipo 1) llamado “Deezer ARL” y guardar un código secreto en el campo de contraseña.

(Nota importante: Si la conexión a red desde la terminal falla constantemente con errores de timeout al ejecutar comandos de Bitwarden (Ver Guía 02), es imperativo inyectar la solución de Node.js NODE_OPTIONS en el mismo comando para forzar la conectividad IPv4).

1
# Se codifica la estructura JSON base64 y se envía al comando de creación de elementos.
2
# Incluye la corrección de IPv4 por si la red del sistema presenta problemas.
3
echo '{"type":1,"name":"Deezer ARL","login":{"password":"<TU_CODIGO_ARL_SECRETO_AQUI>"}}' | bw encode | NODE_OPTIONS="--dns-result-order=ipv4first" bw create item

Al ejecutarse con éxito, el servidor devolverá una confirmación en formato JSON detallando el nuevo elemento creado en la bóveda, demostrando que la autenticación API, el desbloqueo por sesión, la configuración de red y la automatización CLI funcionan en perfecta armonía.

7. Interacción Avanzada: Delegar Control a la IA (OpenClaw)#

La herramienta oficial bw está diseñada de manera que la sesión desbloqueada (BW_SESSION) vive única y exclusivamente en la memoria de la terminal interactiva donde el usuario tecleó su contraseña maestra.

Dado que los agentes de IA (como OpenClaw) ejecutan comandos en procesos de terminal secundarios y aislados, no heredan esta sesión por defecto. Esto bloquea su acceso a la bóveda por razones de diseño y seguridad.

Para que el agente pueda operar automáticamente (ej., inyectar archivos JSON de credenciales, limpiar contraseñas duplicadas o extraer accesos de forma remota), se requiere un paso de delegación temporal:

1. Extraer la Llave de Sesión: El usuario, en su terminal interactiva ya desbloqueada, solicita visualizar su llave:

   1
   echo $BW_SESSION
   

2. Compartir la Llave: El usuario copia la cadena resultante (que actúa como un “pase VIP” temporal) y se la comparte directamente a su asistente de IA en el chat.
3. Ejecución Asistida: La IA utiliza esa llave inyectándola en sus propios procesos para ejecutar acciones complejas sobre la bóveda a nombre del usuario, aplicando siempre la corrección de red si es necesario:

   1
   export BW_SESSION="<LLAVE_PROPORCIONADA_POR_EL_USUARIO>"
   2
   export NODE_OPTIONS="--dns-result-order=ipv4first"
   3
   
   4
   # Ejemplo: Obtener una contraseña
   5
   bw get password "amazon"
   6
   
   7
   # Ejemplo: Borrar entradas obsoletas en lote
   8
   bw delete item <id-del-elemento>
   

Este método garantiza la máxima seguridad y control: la contraseña maestra original nunca abandona la mente ni el teclado del usuario, mientras que la llave delegada (BW_SESSION) caduca o se destruye al cerrar la terminal.

8. Referencias y Documentación Adicional#

La solución para evitar las restricciones de bots y utilizar el CLI oficial sin interrupciones se basó en el excelente descubrimiento de la documentación nativa de la comunidad. Para flujos de trabajo más profundos y detalles sobre esta integración, consulta:

• Bitwarden Skill para OpenClaw | Gestiona Secretos con IA

9. Automatización Total en Segundo Plano (Modo Servidor)#

El método de “delegación manual” descrito en el punto anterior es el más seguro, pero carece de practicidad si el objetivo es interactuar con el agente de IA desde una plataforma remota (como Telegram o WhatsApp), donde el usuario no tiene acceso a la terminal del servidor para generar y pegar llaves temporales (BW_SESSION).

Para lograr una autonomía total, donde el agente pueda abrir la bóveda por sí solo respondiendo a comandos remotos (ej. “Rox, dame la contraseña de Amazon por Telegram”), es necesario realizar un compromiso de seguridad: almacenar la Contraseña Maestra en el servidor.

(Advertencia Crítica: Este método guarda la contraseña maestra en un archivo de texto plano. Solo debe usarse en servidores o entornos locales altamente securizados donde el riesgo de intrusión al sistema de archivos sea aceptable frente al beneficio de la automatización total).

1
systemctl --user daemon-reload
2
openclaw gateway restart

1
# 1. Inicia sesión (silenciosamente, ignora errores si ya está logueado)
2
bw login --apikey >/dev/null 2>&1 || true
3

4
# 2. Desbloquea la bóveda usando la variable BW_PASSWORD y extrae la sesión
5
export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
6

7
# 3. Ejecuta la orden del usuario con acceso total
8
bw get password "amazon"