Monitorizar agentes Codex: las cuatro señales que realmente dicen algo

«El proceso está corriendo» no es una respuesta útil

Un agente Codex que lleva dos horas corriendo puede estar en tres estados muy distintos. Puede estar avanzando, triturando un refactor y tocando un archivo cada pocos minutos. Puede estar en bucle — releyendo los mismos archivos, repitiendo las mismas preguntas, quemando tokens sin avanzar. O puede estar esperando un rate limit, técnicamente vivo pero sin producir nada.

Cualquier herramienta de monitoreo normal — htop, systemctl status, pings de uptime — dirá lo mismo para los tres: el proceso está arriba. Esa respuesta es peor que inútil, porque te hace creer que todo va bien cuando dos de los tres desenlaces significan que estás pagando por nada.

Monitorizar un agente de código es un problema distinto al de monitorizar un servidor web. Estas son las señales que observamos en Office Claws, por qué importan y qué dice cada una que ps aux no dice.

Señal 1: actividad — qué está haciendo el agente ahora mismo

Lo más útil que se puede saber de un agente en marcha es si en este instante está pensando, escribiendo o inactivo. No «logró una línea en los últimos cinco minutos» — eso es un indicador a posteriori. Hablamos del estado en vivo: ¿está fluyendo el stream de tokens?, ¿está leyendo un archivo?, ¿espera a un comando de shell?

En Office Claws cada agente tiene su escritorio en la oficina pixel-art, y el personaje sentado está en uno de tres estados animados: caminando, escribiendo o inactivo. La animación no es adorno — es una proyección en vivo del estado real del agente, alimentada por el mismo stream RPC que nutre el feed de actividad. Miras la oficina y sabes sin leer un log qué agentes trabajan y cuáles están aparcados.

Los equivalentes en texto también funcionan. La Codex CLI emite eventos mientras corre — llamadas a herramientas, lecturas de archivo, turnos de modelo. Hacerle tail a ese stream de eventos dice lo mismo que un spinner, solo que en terminal. Lo importante es distinguir «proceso vivo» de «proceso haciendo algo».

Señal 2: output — ¿están cambiando los archivos de verdad?

Un agente que «escribe» en su terminal pero no ha modificado ningún archivo en treinta minutos no está trabajando. Está conversando consigo mismo. Es el modo de fallo más común que vemos en tareas largas — el modelo entra en discusión con su propio scratchpad, no produce diffs y quema una hora antes de que nadie se dé cuenta.

La forma barata de cazarlo: vigilar el working tree.

# On the VPS, log file changes every minute
while true; do
  find /repo -type f -newer /tmp/last-check 2>/dev/null | wc -l
  touch /tmp/last-check
  sleep 60
done

Si ese número es cero durante tres ventanas seguidas en una tarea que debería producir diffs, el agente está atascado. Interrúmpelo, resume lo que haya aprendido y reinicia con un prompt más ajustado. Dejarlo continuar casi siempre es malgastar.

Una señal relacionada: cadencia de commits. Pedimos a nuestros builder agents que commiteen tras cada cambio lógico. Un agente que lleva una hora sin commit en una tarea que empezó con «refactoriza estos 20 archivos» te dice algo — casi siempre que la tarea estaba subespecificada.

Señal 3: coste — tokens, mensajes y el acantilado del rate limit

Codex por suscripción (ChatGPT Plus o Pro) no cobra por token, pero pone tope a mensajes por ventana móvil. Codex vía API cobra por token sin tope. A ambos les importa el volumen, por razones distintas.

El caso de suscripción es el peligroso para el monitoreo, porque un agente con rate limit parece estar corriendo. El proceso está arriba, el terminal abierto, la CLI esperando. Pero cada petición nueva llega throttled y no vuelve nada. Sin un indicador de rate limit no te enterarás hasta revisar el output y ver seis horas de nada.

En Office Claws mostramos los mensajes restantes directamente en el feed de actividad — cuando el contador baja del 10% el badge del agente se pone ámbar. Se puede cablear lo mismo en cualquier setup: la Codex CLI expone los headers de límite y un pequeño script jq puede lanzar una notificación cuando el contador cruce un umbral.

Señal 4: estado de bloqueo — el fallo silencioso

La clase de fallo más difícil de cazar es el agente que técnicamente produce output pero no avanza. Vemos tres formas de esto con frecuencia:

• Bucle de lectura. El agente lee los mismos cinco archivos una y otra vez, resumiendo cada vez de forma algo distinta, sin escribir nada. El gasto de tokens es real, el progreso cero
• Espiral test-fix-test. El agente corre los tests, ve un fallo, lo «arregla» de forma que crea otro fallo, vuelve a correr los tests, eternamente. Cada ciclo produce un diff, así que el monitoreo ingenuo de output no lo caza
• Tormenta de reintentos por rate limit. El agente toca el tope, reintenta cada pocos segundos, loggea «retrying...» indefinidamente. CPU baja, memoria baja, los logs corren, nada pasa

La pista para los tres es la repetición. El log de un agente sano es una secuencia de acciones distintas — lee este archivo, luego otro, luego escribe aquel, luego ejecuta este comando. El log de un agente bloqueado son las mismas tres líneas intercaladas durante una hora. La alarma más simple que pilla esto de forma fiable es la métrica «llamadas únicas a herramientas en los últimos 20 minutos». Si la respuesta es dos o tres, el agente está en bucle.

Cómo Office Claws expone estas señales

Cada uno de los puntos anteriores está implementado en la app de escritorio este mes:

• Feed de actividad — stream en vivo de cada llamada a herramienta, lectura de archivo, comando y turno de modelo de cada agente, unificado en un panel
• Estados del pixel office — caminando / escribiendo / inactivo, alimentados por el stream RPC del VPS del agente
• Stream de logs — stdout/stderr completo por agente, con scrollback, filtrable por agente
• Badges de rate limit — indicador de color por agente cuando los mensajes restantes bajan del umbral de aviso
• Detección de inactividad — los agentes que no han producido output en una ventana configurable quedan marcados en la oficina; la animación del personaje cambia a idle y el badge del escritorio se pone amarillo

La cuestión no es que tengas que usar Office Claws para conseguir esto. La cuestión es que estas cuatro señales son lo que un dashboard de agentes de código debe mostrar, y cualquier montaje casero que se salte una dejará pasar el modo de fallo correspondiente.

Qué no monitorizar

Tres cosas que parecen importar y casi nunca importan:

1. CPU y memoria del VPS. Una sesión de Codex CLI usa ~200MB de RAM y casi nada de CPU — el trabajo ocurre en el modelo, no en el droplet. Si tu agente está al 100% de CPU algo falla en tu código, no en el agente
2. Uptime de red. Tailscale gestiona los reconnects solo. Una caída de 30 segundos no afecta a una sesión de agente en marcha. Alertar sobre eso solo genera ruido
3. «Sigue corriendo tras N horas» como señal de éxito. El tiempo de ejecución por sí solo es una trampa — un agente bloqueado correrá feliz 24 horas. Combina tiempo con output para obtener algo con sentido

Un montaje casero mínimo

Si no usas Office Claws y quieres el equivalente, este es el camino más corto:

# /etc/systemd/system/codex-watch.service (simplified)
# Logs activity, tracks file changes, alerts on stuck state
 
*/5 * * * * /opt/codex-watch/check.sh >> /var/log/codex-watch.log

Dentro de check.sh:

1. Parsea los últimos 20 minutos del event log de Codex y cuenta las invocaciones únicas de herramientas
2. Cuenta los archivos modificados bajo /repo en los últimos 20 minutos
3. Lee el header de rate limit de la respuesta de API más reciente
4. Si unique-tools ≤ 2 y files-changed = 0 durante dos ventanas seguidas, dispara un webhook

Eso es todo. Cuarenta líneas de shell, un cron, un webhook hacia donde leas notificaciones. Tosco, pero caza los tres modos de fallo que importan. El pixel office es más bonito de ver, pero resuelve el mismo problema.

La versión de una línea

Monitorizar un agente de código no va de si el proceso está vivo — va de si el trabajo avanza. Actividad dice está haciendo algo, output dice está produciendo algo, coste dice puede seguir, estado de bloqueo dice de verdad progresa. Observa las cuatro. No te fíes de ninguna por separado.

Lecturas relacionadas

• How to Run Multiple Codex Agents at Once — monitorizar se complica en proporción al número de agentes
• Long-Running Codex Tasks — por qué las tareas nocturnas necesitan las cuatro señales, no solo uptime
• Cutting AI Agent Costs — la señal de coste en detalle, incluido cuándo saltar de Plus a Pro