Skip to content

Guardia de GitHub: resúmenes de PR y gestión automática de issues ​

💡 Resumen en una frase: usa OpenClaw para establecer una línea de guardia de GitHub 7×24 — el Webhook de entrada recibe los eventos, los hooks de mapeo los convierten en tareas, y el agente de guardia produce resúmenes y respuestas.

Cuando el repositorio acumula muchos PR, revisar los diff a mano se vuelve imposible; las preguntas repetidas en los issues tampoco reciben respuesta a tiempo. Esta página te guía para montar una línea de guardia de GitHub con OpenClaw: usa el Webhook de entrada para pasar los eventos del repositorio al agente de guardia; cuando entra un PR nuevo, se genera automáticamente un resumen de cambios, y los issues nuevos se clasifican automáticamente y reciben un borrador de respuesta. Antes de empezar, completa primero 《Deja que Claw escriba código: exec, parches y aprobaciones》 y confirma que tu agente puede completar una ronda de tareas con normalidad. Todos los ejemplos se basan en OpenClaw v2026.10.9.

Qué podrás hacer al terminar ​

  • En cuanto entra un PR nuevo al repositorio, el agente de guardia produce automáticamente un resumen de cambios con formato fijo: qué se modificó, qué módulos se ven afectados y dónde están los riesgos.
  • Clasificación automática de issues nuevos: determina el tipo, identifica duplicados y redacta una respuesta lista para enviar.
  • Usa curl para verificar localmente toda la línea de guardia con una prueba de humo, sin esperar a que llegue un PR real.
  • Los eventos que no son objetivo (por ejemplo, push) devuelven automáticamente 204, sin despertar al agente ni consumir una ronda de conversación.

Por qué usar OpenClaw y no una IA web ​

CapacidadIA webOpenClaw
Respuesta 7×24❌ Si no abres la página, no hace nada✅ El Gateway corre permanentemente, los eventos se procesan al llegar
Lee el contenido del repositorio❌ Pegar el diff a mano, si es largo no cabe✅ El agente tiene identidad de GitHub y obtiene por sí mismo el diff del PR y el cuerpo del issue
Impulsado por eventos❌ Copiar enlaces a mano para preguntar✅ Webhook de entrada + hooks de mapeo, los eventos se convierten automáticamente en tareas
Trazabilidad para diagnóstico❌ Cierras la conversación y ya no la encuentras✅ Cada solicitud tiene un runId, los logs permiten consultar el estado de finalización
Límites de permisos❌ Ninguno✅ allowedAgentIds restringe los agentes que pueden despertarse, las operaciones de escritura siguen usando aprobaciones

Tu situación actual ​

  • Al abrir el repositorio por la mañana, los PR e issues nuevos están en fila; abrirlos uno por uno para revisar los diff te toma toda la mañana.
  • Los issues duplicados se repiten una y otra vez; quieres clasificarlos y etiquetarlos primero, pero eso en sí mismo consume mucho tiempo.
  • ¿Pegar el diff a mano en una IA web? Los diff largos no caben completos, se pierde el contexto, y además tienes que quedarte esperando el resultado.

Cuándo usar esta técnica ​

  • El repositorio del equipo recibe PR e issues nuevos a diario, y el guardia humano no sigue el ritmo.
  • Quieres resúmenes de PR con formato uniforme, para decidir rápidamente cuál revisar primero.
  • Los issues necesitan una clasificación inicial: categorizar, identificar duplicados y darle al autor un borrador de respuesta.
  • Ya tienes una máquina 7×24 ejecutando el Gateway, y completaste el exec y las aprobaciones de la página anterior.

🎒 Preparativos antes de empezar ​

  • Un Gateway en ejecución, con un agente capaz de completar una ronda de conversación con normalidad — este es el requisito previo oficial para los webhooks.
  • Un token dedicado, largo y aleatorio. La documentación oficial exige claramente: no reutilices el token de autenticación del Gateway ni las contraseñas.
  • Permisos de administrador del repositorio de GitHub, para añadir el Webhook.
  • Una entrada HTTPS pública (proxy inverso de confianza): los servidores de GitHub deben poder acceder a tu Gateway, y el encabezado de autenticación también lo añade el proxy (detallado en el paso 4).
  • La identidad con la que el agente lee el contenido de GitHub: sin configurar tools.github se usa la resolución nativa de gh; para una identidad de ejecución compartida se configura con tools.github (detallado en el paso 5).

Hazlo conmigo ​

Paso 1: habilita el Webhook de entrada y enciende con OpenClaw la línea de guardia de GitHub ​

Por qué hacer esto primero: el Webhook de entrada está desactivado por defecto; sin habilitarlo, los eventos de GitHub ni siquiera entran en OpenClaw.

Primero fusiona el bloque de configuración hooks en la configuración del Gateway. Cambia el token por tu valor aleatorio largo y dedicado, y main por el id del agente de guardia:

json5
{
  hooks: {
    enabled: true,
    token: "<long-random-hook-token>",
    path: "/hooks",
    allowedAgentIds: ["main"],
    allowRequestSessionKey: false,
  },
}

Valida la configuración, reinicia el servicio y vigila los logs:

bash
openclaw config validate
openclaw gateway restart
openclaw logs --follow

Si ejecutas el Gateway en primer plano en lugar de instalarlo como servicio, detén manualmente ese proceso y vuelve a iniciarlo.

Deberías ver: openclaw config validate pasa, y tras el reinicio no hay errores relacionados con hooks en los logs. De paso, deja claro dónde encaja este conjunto de endpoints: pertenece a la guía Automations (desde OpenClaw 2.0 Automations usa nombres unificados), con la dirección de «servicios externos que llaman a OpenClaw»; eso son tres cosas distintas de los hooks de eventos internos (controladores HOOK.md) y de la entrega de webhooks salientes de las automatizaciones. Si el token reutiliza la autenticación por secreto compartido del Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN, o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD), el log de inicio registrará una advertencia no fatal, y openclaw security audit la reportará como critical. Solución: usa openclaw doctor --fix para rotar el token reutilizado ya persistido y luego actualiza todos los remitentes externos.

Paso 2: prueba de humo local del agente de guardia ​

Por qué hacer una prueba de humo: valida primero en tu máquina que el endpoint, el token y la aceptación del agent funcionan, antes de dejar entrar tráfico externo; si algo falla, es más fácil localizarlo.

Abre otra terminal y envía un mensaje de prueba inofensivo al /hooks/agent del Gateway local:

bash
curl --include http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer <long-random-hook-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webhook-smoke-001' \
  --data '{"message":"Summarize this test event: the sample import completed.","name":"Webhook smoke test","agentId":"main","deliver":false}'

Deberías ver: HTTP 200, con el cuerpo de respuesta:

json
{ "ok": true, "runId": "<hook-request-run-id>" }

Ten en cuenta qué significa 200: solo indica que la solicitud obtuvo la aceptación de la sesión/global; no significa que el modelo haya terminado, que las herramientas hayan tenido éxito o que el mensaje se haya entregado; una sola solicitud puede esperar hasta 15 segundos antes de ser aceptada. Busca en openclaw logs --follow hook agent run completed y este runId: status=ok sin errores de entrega se registra a nivel info; estados no ok (incluidos los runs omitidos), excepciones lanzadas y errores de entrega explícitos se registran a nivel warn — status=ok pero una advertencia con deliveryError indica que la ejecución tuvo éxito pero la entrega falló.

En el ejemplo, deliver: false es un valor razonable para la prueba de humo: el anuncio de éxito se suprime, el campo de destino se ignora y el resultado final solo se escribe en el log (un desenlace no ok seguirá produciendo un evento de fallo). Al conectar formalmente los eventos de GitHub, elige según necesidad: si quieres recibir la notificación de finalización en la sesión principal del agent de guardia, usa el deliver: true por defecto, que publica un evento de sistema de finalización en la sesión principal del agent de destino; si solo quieres ver el log, mantén false.

Paso 3: configura un hook de mapeo para convertir el payload de GitHub en una tarea del agent ​

Por qué no puedes saltarte este paso: el payload original que envía GitHub no tiene el campo message, ni puede llevar la cabecera de autenticación Authorization: Bearer; apuntar el Webhook directamente a /hooks/agent fallará. El mecanismo oficial para eventos externos es el hook de mapeo: en hooks.mappings configura un transform JS/TS de confianza para la ruta personalizada, y es él quien traduce el payload en una acción del agent.

Primero añade un mapeo en la configuración de hooks (match.path: "gh" coincide con /hooks/gh):

json5
{
  hooks: {
    enabled: true,
    token: "<long-random-hook-token>",
    path: "/hooks",
    allowedAgentIds: ["main"],
    allowRequestSessionKey: false,
    mappings: [
      {
        id: "github",
        match: { path: "gh" },
        action: "agent",
        agentId: "main",
        transform: { module: "gh.mjs" },
      },
    ],
  },
}

Luego escribe el transform. El directorio por defecto es ~/.openclaw/hooks/transforms (clave de configuración transformsDir); el transform es código de confianza del Gateway y se cachea, así que hay que reiniciar tras modificarlo para que surta efecto:

js
// ~/.openclaw/hooks/transforms/gh.mjs
export default function transform({ payload, headers }) {
  const event = headers["x-github-event"] ?? headers["X-GitHub-Event"];

  if (event === "pull_request" && payload.action === "opened") {
    const pr = payload.pull_request;
    return {
      kind: "agent",
      message:
        `新 PR #${payload.number}:${pr.title}\n` +
        `作者 ${pr.user.login},分支 ${pr.head.ref} → ${pr.base.ref}\n` +
        `请拉取该 PR 的 diff,按「PR 改动摘要」规范输出。`,
    };
  }

  if (event === "issues" && payload.action === "opened") {
    return {
      kind: "agent",
      message:
        `新 issue #${payload.number}:${payload.issue.title}\n` +
        `正文:${payload.issue.body ?? "(空)"}\n` +
        `请按「issue 分诊与回复起草」规范分类并起草回复。`,
    };
  }

  // 非目标事件(如 push):返回 null,OpenClaw 回 204,不创建 run
  return null;
}

Los nombres de los campos del payload (action, number, pull_request, etc.) siguen el formato oficial de entrega de webhooks de GitHub; antes de conectar, contrasta una vez con los eventos que realmente recibes. Si el formato del evento es simple, también puedes escribir el message con el campo de plantilla messageTemplate incluido en el mapeo sin escribir JS; los eventos de GitHub requieren ramificar por tipo y filtrar los eventos no objetivo, por eso aquí se usa un transform.

Valida, reinicia y luego simula localmente los dos tipos de eventos, uno de cada:

bash
openclaw config validate
openclaw gateway restart
bash
# 模拟新 PR:期望 200 + runId
curl --include http://127.0.0.1:18789/hooks/gh \
  -H 'Authorization: Bearer <long-random-hook-token>' \
  -H 'Content-Type: application/json' \
  -H 'X-GitHub-Event: pull_request' \
  --data '{"action":"opened","number":42,"pull_request":{"title":"Add export button","user":{"login":"alice"},"head":{"ref":"feat/export"},"base":{"ref":"main"}}}'

# 模拟 push:期望 204
curl --include http://127.0.0.1:18789/hooks/gh \
  -H 'Authorization: Bearer <long-random-hook-token>' \
  -H 'Content-Type: application/json' \
  -H 'X-GitHub-Event: push' \
  --data '{"ref":"refs/heads/main"}'

Deberías ver: el PR simulado devuelve HTTP 200 y { "ok": true, "runId": "<hook-request-run-id>" }; el push simulado devuelve HTTP 204 — el transform devolvió null, el mapeo deliberadamente no produce ninguna acción, ni siquiera se crea un run.

💡 Este es el valor único de OpenClaw

El hook de mapeo es una «capa de traducción de eventos externos» genérica: hoy conectas GitHub, mañana cambias a otra plataforma de hosting de código o a alertas de monitoreo, y todo se reduce a cambiar un archivo de transform. ¿El payload no tiene message? Lo generas en el transform. ¿No quieres que eventos irrelevantes consuman una ronda de conversación? Devuelve null y OpenClaw responde 204. Esta es una capacidad de cableado a nivel de evento que las IA en versión web no pueden ofrecer.

Paso 4: monta el Webhook en el repositorio de GitHub ​

Por qué hace falta un proxy inverso: la documentación oficial exige que el endpoint del hook permanezca tras loopback, tailnet o un proxy inverso de confianza, y que las llamadas remotas vayan por HTTPS. GitHub está en la red pública y tu Gateway en la red interna; en medio, un proxy inverso de confianza reenvía y añade la cabecera de autenticación.

En la página Webhooks de la configuración del repositorio, añade un hook nuevo:

  • Payload URL: https://<你的公网域名>/hooks/gh — el proxy inverso lo reenvía al Gateway y añade la cabecera Authorization: Bearer <long-random-hook-token>.
  • Content type: elige JSON. El endpoint de hook de OpenClaw solo acepta POST Content-Type: application/json.
  • Eventos desencadenantes: marca solo Pull requests e Issues, no actives todos los eventos — aunque el transform bloquearía los eventos no objetivo con 204, no tiene sentido dejar que GitHub los entregue en balde.
  • Secret: la clave de firma de entregas del lado de GitHub @@I18N_KEEP_000025@@.

En el lado del proxy, expón solo la ruta imprescindible; no dejes el puerto completo del Gateway desnudo en la red pública.

Deberías ver: en el registro de entregas del Webhook de GitHub, los eventos objetivo devuelven 200 y los no objetivo devuelven 204; en openclaw logs --follow aparecen hook agent run completed y el runId correspondiente.

Paso 5: configura la identidad de GitHub del agent de guardia ​

Por qué hace falta este paso: el payload del webhook solo trae metadatos como título y autor; para que el resumen y el triaje sean fiables, el agent debe obtener por sí mismo el diff del PR y el cuerpo del issue, y eso requiere una identidad de GitHub.

Método A (recomendado para empezar): no configures nada. La identidad de GitHub CLI se resuelve de forma nativa por defecto — primero las variables de entorno GH_TOKEN o GITHUB_TOKEN del proceso del Gateway, y después el keyring/config de gh del usuario que lo ejecuta. Basta con completar gh auth login en la máquina donde corre el Gateway (o configurar bien las variables de entorno del proceso del Gateway).

Método B (guardia a largo plazo): configura la identidad de ejecución compartida tools.github, con credenciales gestionadas por el Gateway. En Control UI, en Settings → Profile → GitHub connections, un administrador elige For the system para iniciar la conexión: abre https://github.com/login/device, pega el código de un solo uso que muestra OpenClaw y aprueba los cuatro permisos repo, workflow, read:org, gist. Tras conectar con éxito, aparecerá en la configuración un bloque como este:

json5
{
  tools: {
    github: {
      profileId: "ghp_0123456789abcdef0123456789abcdef",
      kind: "oauth",
      gitAuthor: { name: "Automation User", email: "automation@example.com" },
    },
  },
}

Hay tres límites que debes conocer:

  • El access token de OAuth caduca en aproximadamente 8 horas y el Gateway lo refresca automáticamente antes de que expire; si el refresh token se invalida, se mostrará Reconnect required.
  • La identidad App de kind: "app-installation" solo admite lectura en sesiones de primer plano; para que el agent ejecute herramientas, elige native u OAuth.
  • Cuando un agent deba usar una identidad distinta, sobrescríbelo en agents.entries.<id>.tools.github; si no se configura, hereda la identidad del sistema; si no quieres usar OAuth, también puedes elegir Use a PAT instead, conservando la vía de configuración de tokens de acceso personal de grano fino.

Deberías ver: el agent de guardia puede obtener en la sesión el diff del PR y el cuerpo del issue; si se configuró una identidad gestionada pero faltan o han caducado las credenciales, el estado de GitHub reportará configured_unavailable, en lugar de caer silenciosamente a la cuenta local de la máquina.

📋 Prompt mágico ​

El transform solo se encarga de traducir el evento en un message; lo que hace el agent al recibir el message lo determinan las instrucciones permanentes de su workspace. Escribe los dos bloques siguientes en el AGENTS.md del agent de guardia (en una instalación personal, por defecto en ~/.openclaw/workspace) — los nombres de las dos especificaciones que el message generado por el transform referencia son precisamente estos.

📝 Resumen de cambios del PR ​

Resultado esperado: al entrar un evento de PR nuevo, el agent produce un resumen con formato fijo — qué cambió, qué módulos se ven afectados, dónde están los riesgos — para que decidas qué mirar primero sin abrir el diff.

text
Rol: eres el reviewer de guardia de este repositorio y produces un resumen de cambios para cada PR nuevo.
Tarea: obtén el diff y la descripción del PR y produce el resumen según la especificación de salida.
Información de entrada:
### Campos obligatorios
- 【Número de PR】
- 【Título del PR】
- 【Autor】
- 【Ramas (head → base)】
### Campos opcionales
- 【Descripción del PR?】
- 【Issue relacionado?】
Especificación de salida:
- Primera línea: una frase que resuma qué hace este PR.
- Lista de cambios: agrupados por módulo, una línea por elemento, marcando si es añadido/modificado/eliminado.
- Ámbito de impacto: funciones, interfaces o configuraciones afectadas.
- Riesgos: carencias de pruebas, cambios rompedores, archivos que requieren revisión manual prioritaria.
Restricciones:
✅ Basarse solo en el diff y la descripción del PR, sin adivinar intenciones no escritas
✅ El resumen no supera las 20 líneas
❌ No dar conclusiones de revisión como «se puede fusionar»; la decisión queda en manos humanas
❌ No modificar código ni hacer push de ramas

📋 Triaje de issues y redacción de respuestas ​

Efecto esperado: los nuevos issues se clasifican automáticamente por tipo, se detectan duplicados y se redacta una respuesta lista para enviar.

text
Rol: eres el triager de guardia de este repositorio, encargado de triar los nuevos issues y redactar respuestas.
Tarea: leer el título y el cuerpo del issue, determinar el tipo, buscar duplicados y redactar un borrador de respuesta.
Información de entrada:
### Campos obligatorios
- 【número del issue】
- 【título del issue】
### Campos opcionales
- 【cuerpo del issue?】
- 【lista de números de issues similares dentro del repositorio?】
Especificación de salida:
- Tipo: bug / petición de función / documentación / duda de uso / otro, elegir una de las cinco opciones.
- Detección de duplicados: si parece duplicado, indicar el número del issue existente; si no se encuentra, escribir «no se encontró duplicado».
- Borrador de respuesta: una respuesta en chino lista para enviar: confirmar la comprensión y proponer el siguiente paso.
Restricciones:
✅ Si falta información, listar en el borrador lo que el autor debe añadir
✅ Tono concreto y cortés, sin superficialidad
❌ No cerrar issues por iniciativa propia ni modificar archivos del repositorio
❌ No prometer plazos ni versiones de corrección

Puntos de control ✅ ​

Criterios para que toda la línea de guardia funcione, verifícalos uno a uno:

  • openclaw config validate pasa, y tras el reinicio no hay errores de hooks en los logs.
  • El curl de humo del paso 2 devuelve 200 y el cuerpo de la respuesta contiene runId.
  • Paso 3: simular pull_request devuelve 200, simular push devuelve 204 (sin crear run).
  • Paso 4: en el registro de entregas del Webhook de GitHub aparecen 200/204, y en openclaw logs --follow se puede buscar hook agent run completed.
  • Paso 5: el agente de guardia puede obtener en la sesión el diff del PR y el cuerpo del issue.
  • El log de finalización es status=ok; si ves un warn con status=ok y deliveryError, la ejecución tuvo éxito pero la entrega falló: revisa el destino de la entrega.

Avisos de errores comunes ​

SíntomaCausa probableQué hacer
401El token del hook es incorrecto, o el proxy no reenvía la cabecera de autenticaciónVerificar el token de hook dedicado (no es el auth del Gateway); comprobar si el proxy reenvía tal cual la cabecera Authorization
404hooks.enabled, hooks.path o la ruta del mapping no coincideConfirmar que match.path: "gh" coincide con /hooks/gh; no llames a las rutas personalizadas agent ni wake, prioriza el endpoint directo
204El mapping deliberadamente no genera ninguna acciónNo es un error: tanto un transform que devuelve null como un fan-out vacío producen 204
200 pero no se recibe ningún mensajedeliver: false suprimió el anuncio de éxitoRevisa primero el log de finalización; si quieres que se entregue, configura en el mapping un channel y un to explícitos
500El transform lanza una excepciónMira el hook mapping failed en los logs, corrige el transform y reinicia

Tres líneas rojas de seguridad, no las omitas:

  • Token dedicado, subruta dedicada: la autenticación por token de hook va separada de la clave compartida del Gateway; / como ruta será rechazado.
  • Expón solo las rutas necesarias: coloca el endpoint tras loopback, tailnet o un proxy inverso de confianza; las llamadas remotas van por HTTPS.
  • Trata el contenido externo como datos: el payload se envuelve por defecto con safety-wrap, pero ese envoltorio no elimina el acceso del agente a sus herramientas y al workspace: usa un agente restringido para entradas no confiables y mantén allowUnsafeExternalContent desactivado.

Resumen de la lección ​

  • Una línea de guardia de OpenClaw GitHub se compone de cuatro elementos: el Webhook entrante abre la puerta, el hook de mapping traduce, el agente de guardia trabaja, y la identidad de GitHub lee el repositorio.
  • Tres cosas que vale la pena llevarse: hooks.mappings puede convertir cualquier payload externo en una acción del agente; un transform que devuelve null usa 204 para bloquear eventos no objetivo sin crear run; deliver decide si el evento de finalización se devuelve a la sesión principal.
  • Tres líneas rojas de seguridad: token dedicado, exponer solo las rutas necesarias y tratar el contenido externo como datos.
  • Tanto el resumen de PR como el triaje de issues solo producen «borradores y juicios»; las decisiones como fusionar o cerrar quedan en manos humanas: esto es guardia, no delegación de autoridad.

Avance de la próxima lección ​

Cuando la línea de guardia funcione, probablemente pensarás: la revisión de PR y el triaje de issues se aprietan en las instrucciones de un mismo agente, ¿no sería mejor contratar a un especialista para cada tarea? La próxima lección «Colaboración multiagente: un Gateway ejecutando varios especialistas» explica cómo ejecutar en un solo Gateway varios agentes aislados entre sí, cada uno con su workspace y su historial de sesiones independientes, usando bindings para enrutar mensajes distintos a especialistas distintos, y dividir la línea de guardia de hoy en un «especialista de PR + especialista de issues».

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.