Historial de auditoría

El Gateway mantiene un registro de auditoría acotado y compuesto únicamente por metadatos en la base de datos de estado compartida de OpenClaw. Permite responder preguntas operativas como «qué agente se ejecutó, cuándo y cómo finalizó», «qué acciones de herramientas ejecutó una ejecución» y, cuando la auditoría de mensajes está habilitada, «si un mensaje entrante aceptado llegó al despacho» y «si un mensaje saliente alcanzó un estado terminal de entrega».

El registro almacena identidad, orden, procedencia, acción, estado y códigos de resultado normalizados. Nunca almacena prompts, cuerpos de mensajes, argumentos ni resultados de herramientas, archivos adjuntos, nombres de archivo, URLs, salida de comandos ni texto de error sin procesar.

Familias de registros

Los eventos de ejecuciones y herramientas se registran siempre que la auditoría está habilitada (valor predeterminado). Los eventos del ciclo de vida de los mensajes son opcionales y están deshabilitados de forma predeterminada.

Cada registro contiene un id. de evento estable, una secuencia monotónica del registro, una marca temporal del ciclo de vida, el actor, la acción, el estado, schemaVersion: 1 y redaction: "metadata_only". Consulte Registros de auditoría para ver la referencia completa de los campos y los filtros de consulta.

Eventos del ciclo de vida de los mensajes

Configure audit.messages para elegir qué se registra y, a continuación, reinicie el Gateway:

• off (valor predeterminado): no se registran mensajes.
• direct: solo se registran mensajes de conversaciones directas.
• all: se registran mensajes directos, grupales y de canales.

Dos límites autoritativos generan registros de mensajes:

• Las filas entrantes se escriben cuando un mensaje aceptado llega al despacho del núcleo, incluidos los resultados de procesamiento duplicados y terminales.
• Las filas salientes se escriben cuando la entrega duradera compartida alcanza un resultado terminal: enviado, suprimido, fallido o un valor unknown explícito para envíos ambiguos debido a un bloqueo. Se incluyen la recuperación de la cola y los resultados de la cola de mensajes no entregados. Cada carga útil original de respuesta lógica genera una fila terminal; la fragmentación y la distribución en abanico del adaptador se agregan en resultCount.

Clasificación del tipo de conversación

El modo direct constituye un límite de privacidad, por lo que un mensaje solo se clasifica como una conversación directa cuando los datos del destino lo demuestran: la ruta de envío declaró el tipo de conversación de destino o la ruta de sesión de entrega nombra exactamente el canal y el par al que se realiza la entrega. Las señales más débiles, como el estado de las políticas o la conversación de origen, pueden clasificar un mensaje como group (lo que lo excluye de la recopilación en modo direct), pero nunca pueden atribuirle el tipo direct. Los mensajes cuya naturaleza directa no pueda demostrarse se clasifican como unknown y no se registran en el modo direct. Por lo tanto, los canales que no declaren tipos de chat pueden registrar menos filas en el modo direct que en el modo all.

Modelo de privacidad

Las filas de mensajes nunca almacenan identificadores de plataforma sin procesar. Cuando se dispone de correlación, los identificadores de cuenta, conversación, mensaje y destino se exportan únicamente como seudónimos con clave locales de la instalación (hmac-sha256:v1:<keyId>:<digest>):

• La clave HMAC se genera durante el primer uso, se separa por dominio para cada tipo de identificador y reside en la misma base de datos de estado que el registro.
• Los seudónimos son estables dentro de una instalación, por lo que las filas relativas a una misma conversación pueden correlacionarse sin revelar el identificador de la plataforma.
• Esto es correlación, no anonimización: cualquier persona con acceso de lectura a la base de datos de estado también dispone de la clave y puede comprobar identificadores sin procesar candidatos frente a los seudónimos. Las exportaciones mediante RPC y CLI nunca incluyen la clave.
• Si el material de la clave falta o está dañado mientras se conservan filas de mensajes, el Gateway adopta un cierre seguro y descarta los nuevos registros de mensajes en lugar de rotar silenciosamente a una clave nueva, lo que dividiría la correlación.

Los registros de ejecuciones y herramientas conservan sessionKey y sessionId para permitir la correlación; las claves de sesión canónicas pueden contener por sí mismas ids. de cuentas o pares de la plataforma. Los registros de mensajes omiten ambos intencionadamente.

Las exportaciones de auditoría siguen siendo metadatos operativos sensibles incluso sin contenido: los tiempos, canales, resultados y seudónimos estables pueden permitir correlacionar la actividad. Proteja las exportaciones con los mismos controles de acceso y prácticas de retención que los demás registros operativos.

Límites de cobertura y prueba

El registro funciona con el máximo esfuerzo y está acotado deliberadamente. Considérelo evidencia de lo que se registró, no una prueba de lo que ocurrió:

• La ausencia de una fila no demuestra nada. Los descartes entrantes previos a la admisión, los envíos desde procesos de CLI sin un registrador del Gateway en ejecución y las rutas locales de plugins o de envío directo que eluden la entrega duradera compartida no dejan ningún registro.
• Las escrituras pasan por un trabajador en segundo plano con capacidad limitada; los fallos del trabajador o la saturación de la cola provocan el descarte de registros y generan una advertencia operativa.
• Los envíos salientes ambiguos debido a un bloqueo se registran como unknown en lugar de inventar resultados.

Este registro facilita la depuración y la revisión operativa. No es un archivo de cumplimiento sin pérdidas; si necesita uno, utilice un sistema externo alimentado por OpenTelemetry o herramientas del canal.

Almacenamiento, retención y migración

Los registros residen en la base de datos de estado compartida (state/openclaw.sqlite) y se escriben fuera de la ruta crítica de entrega. Las consultas nunca devuelven registros con más de 30 días de antigüedad y el registro está limitado a 100,000 filas; las filas caducadas se eliminan durante el inicio, el mantenimiento cada hora y las escrituras posteriores. El mantenimiento de la retención continúa ejecutándose incluso cuando la recopilación está deshabilitada.

Al actualizar desde un Gateway con el registro anterior limitado a ejecuciones y herramientas, el esquema se migra automáticamente durante el inicio (o mediante openclaw doctor --fix); se conservan las filas existentes y sus secuencias del registro.

Consultas

• CLI: openclaw audit, con filtros por agente, sesión, ejecución, tipo, estado, dirección, canal, límites temporales y paginación mediante cursor.
• RPC del Gateway: audit.activity.list (requiere operator.read) devuelve la unión versionada de eventos de actividad V1; el RPC audit.list publicado no cambia para los clientes anteriores de ejecuciones y herramientas. Consulte Protocolo del Gateway.

Contenido relacionado

• CLI de registros de auditoría
• Referencia de configuración
• Protocolo del Gateway
• OpenTelemetry