Intermediario de secretos de 1Password

El plugin onepassword incluido proporciona a los agentes una herramienta controlada mediante políticas para leer un conjunto seleccionado de campos de 1Password. Está deshabilitado de forma predeterminada y no hace nada hasta que plugins.entries.onepassword.config esté presente.

Esta es una herramienta de agente, no un proveedor de SecretRef. No inyecta variables de entorno ni resuelve secretos de configuración de OpenClaw.

Modelo de seguridad

• Solo autenticación mediante cuenta de servicio. El token permanece en un archivo local de credenciales y nunca se acepta en openclaw.json.
• Solo registro seleccionado. Los agentes pueden enumerar los slugs configurados, pero el plugin nunca enumera una bóveda de 1Password.
• Política auto, approve o deny por slug.
• Las concesiones de aprobación caducan. Un valor almacenado en caché nunca elude la política vigente.
• Cada intento de acceso se registra en el estado SQLite compartido de OpenClaw. Las filas de auditoría incluyen el motivo proporcionado; los motivos no deben contener información confidencial. El intermediario nunca copia un valor obtenido ni el token de servicio en una fila de auditoría.
• Después de la ejecución actual de la herramienta, la persistencia de transcripciones gestionada por OpenClaw reemplaza un valor get correcto por metadatos censurados.
• El valor es visible para el modelo durante esa ejecución. Si el modelo lo copia en una llamada posterior a una herramienta o en una respuesta, ese registro independiente queda fuera del enlace de persistencia de este plugin. Mantenga políticas restrictivas y no pida al modelo que repita un valor.
• El plugin invoca op una vez por cada fallo de caché. No reintenta tras límites de frecuencia ni otros fallos.
• Cada llamada a op se ejecuta con un entorno mínimo que deshabilita la integración con la aplicación de escritorio de 1Password (OP_LOAD_DESKTOP_APP_SETTINGS=false, OP_BIOMETRIC_UNLOCK_ENABLED=false), de modo que una aplicación de 1Password instalada en el host del Gateway nunca active diálogos de permisos biométricos o de macOS.

Conceda a la cuenta de servicio acceso de lectura únicamente a las bóvedas y los elementos registrados en la configuración del plugin.

Antes de comenzar

Se necesita:

• la CLI de 1Password (op) instalada en el host del Gateway
• una cuenta de servicio de 1Password con acceso a los elementos seleccionados
• un archivo de token dedicado para la cuenta de servicio

Habilite el plugin incluido:

openclaw plugins enable onepassword

Cree el directorio y el archivo del token dentro del directorio de estado de OpenClaw:

mkdir -p ~/.openclaw/credentials/onepasswordchmod 700 ~/.openclaw/credentials/onepasswordprintf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \  ~/.openclaw/credentials/onepassword/service-account-tokenchmod 600 ~/.openclaw/credentials/onepassword/service-account-tokenunset OP_SERVICE_ACCOUNT_TOKEN

Cuando OPENCLAW_STATE_DIR esté definido, sustituya ~/.openclaw por ese directorio. El plugin muestra una advertencia una vez cuando el archivo del token permite la lectura o escritura al grupo o a otros usuarios.

Configurar los secretos registrados

Añada la configuración del plugin a openclaw.json:

{  "plugins": {    "entries": {      "onepassword": {        "enabled": true,        "config": {          "vault": "Automation",          "defaultPolicy": "approve",          "cacheTtlSeconds": 300,          "grantTtlHours": 720,          "opTimeoutMs": 15000,          "items": {            "repository-token": {              "item": "Repository automation token",              "field": "credential",              "policy": "approve",              "description": "Token for repository automation",            },            "model-key": {              "item": "Model provider key",              "vault": "Agent credentials",              "policy": "auto",            },          },        },      },    },  },}

Los slugs usan letras minúsculas, números y guiones, comienzan con una letra o un número y contienen como máximo 64 caracteres. Un registro puede contener hasta 32 slugs; las descripciones pueden contener hasta 200 caracteres. field acepta una etiqueta o un ID de campo, no debe contener comas y su valor predeterminado es credential. Un valor vault a nivel de elemento sustituye la bóveda predeterminada. opBin puede establecer una ruta absoluta al ejecutable op; de lo contrario, el plugin resuelve op desde PATH. Los títulos de los elementos no deben comenzar con un guion.

Usar la herramienta de agente

El nombre de la herramienta es onepassword.

Enumere los slugs registrados:

{ "action": "list" }

El resultado contiene únicamente el slug, la descripción, la política y si hay una concesión permanente activa. Nunca contiene un valor secreto ni consulta 1Password.

Solicite un secreto:

{  "action": "get",  "slug": "repository-token",  "reason": "Authenticate the requested repository operation"}

reason es obligatorio, no debe estar vacío y tiene un límite de 300 caracteres. Una operación get correcta devuelve el valor junto con el slug configurado, el título del elemento y la etiqueta del campo.

El esquema de la herramienta también declara un parámetro interno authorizationNonce. La capa de políticas lo inyecta después de evaluar la solicitud para transferir la autorización a la llamada de herramienta que realiza la ejecución. Nunca lo establezca manualmente: el enlace de políticas sobrescribe cualquier valor proporcionado y un valor desconocido provoca el fallo de la solicitud.

Niveles de políticas y aprobaciones

• auto: obtiene el valor inmediatamente y audita la solicitud.
• deny: bloquea y audita la solicitud.
• approve: usa una concesión permanente que no haya caducado o solicita a una persona que permita una vez, permita siempre o deniegue.

Permitir una vez autoriza únicamente la llamada actual a la herramienta. Permitir siempre escribe una concesión permanente para ese agente y slug en SQLite; los demás agentes deben recibir su propia aprobación. OpenClaw ofrece permitir siempre únicamente cuando el autor de la llamada tiene una identidad de agente concreta. La concesión caduca después de grantTtlHours, cuyo valor predeterminado es 720 horas. Una aprobación sin resolver o que agote el tiempo de espera deniega la solicitud; el tiempo máximo de espera de aprobación es de 600 segundos. El plugin conserva hasta 1.024 concesiones permanentes; al alcanzar ese límite, se elimina la concesión más antigua y su agente debe aprobar el siguiente acceso.

Cada autorización evaluada es de un solo uso y se transfiere a la llamada de herramienta que realiza la ejecución mediante el estado SQLite compartido, por lo que la transferencia también funciona cuando hay más de una instancia del plugin activa en el proceso del Gateway. Las autorizaciones sin usar caducan después del intervalo de aprobación de 600 segundos.

La caché en memoria tiene un valor predeterminado de 300 segundos y está limitada por el registro de slugs configurado. Establezca cacheTtlSeconds en 0 para deshabilitarla. La política se evalúa antes de cada consulta de caché y los aciertos de caché se auditan. Las recargas de configuración en tiempo de ejecución surten efecto en cada límite de política y ejecución; deshabilitar el plugin o eliminar, denegar o reasignar un slug invalida las autorizaciones pendientes y los valores almacenados en caché.

Inspeccionar el estado y el historial de auditoría

Muestre la disponibilidad y los recuentos del registro:

openclaw onepassword status

Esto informa de si existe el archivo del token, si se resolvió op y su ruta, el número de elementos registrados y los recuentos por política. Nunca lee ni imprime el token ni los valores secretos.

Muestre las 50 filas de auditoría más recientes:

openclaw onepassword auditopenclaw onepassword audit --limit 100

Las filas se muestran de la más reciente a la más antigua e indican la marca de tiempo, el agente, el slug, el resultado, un errorCode cuando el intento falla y un motivo truncado. El motivo se almacena tal como se proporciona; el intermediario nunca añade el valor obtenido al registro de auditoría.

Comportamiento de la CLI de 1Password

Cada fallo de caché ejecuta op item get con el elemento y la bóveda configurados, el selector de campo exacto, salida JSON, un tiempo de espera limitado y --cache=false. El proceso secundario recibe únicamente ese campo, no el elemento completo. Solo OP_SERVICE_ACCOUNT_TOKEN y HOME están presentes en el entorno del proceso secundario.

El plugin realiza un intento. Los errores RATE_LIMITED deben gestionarse esperando antes de una solicitud posterior del agente; el plugin no crea un bucle de reintentos automático.

Códigos de error

Los intentos fallidos incluyen un código de error cerrado en el resultado de la herramienta y en la fila de auditoría.

Errores de acceso a 1Password:

Errores de políticas y validación: