SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor · Actualizado 2026-10-22

Cómo alojar OpenTag para menciones @agent

Instala OpenTag v0.9.0 en un VPS para enviar menciones de Slack y GitHub a tu agente, con TLS, firmas de webhook, permisos de tokens y valores seguros.

Qué hace OpenTag cuando mencionas a un agente

OpenTag convierte una mención con @ en un hilo de Slack o una incidencia de GitHub en una ejecución de un agente de programación en una máquina que administras. Alguien comenta @opentag investigate this en una incidencia. Un listener recibe el evento de la plataforma, comprueba su firma, asocia la mención a un proyecto vinculado, inicia un agente de programación sobre un checkout local y publica el resultado en el mismo hilo.

El proyecto usa la licencia MIT y está disponible en amplifthq/opentag. En octubre de 2026, la versión etiquetada más reciente es v0.10.0, publicada el 17 de agosto de 2026. La CLI se distribuye como un paquete npm. Allí, 0.10.0 tiene la etiqueta latest y 0.11.0 tiene la etiqueta next, pero el README de v0.10.0 todavía indica 0.9.0 como la versión estable documentada, por lo que esta guía fija la versión 0.9.0. Todos los comandos siguientes fijan esa versión. OpenTag publica una imagen de contenedor oficial para el Control Plane opcional y autohospedado, añadido en 0.10.0. La imagen es ghcr.io/amplifthq/opentag-control-plane, se compila para linux/amd64 y se etiqueta con el SHA del código fuente. No tiene la etiqueta latest, por lo que debe fijarse mediante su resumen sha256. Esta guía no usa el Control Plane, así que aquí se fija la versión de npm.

Esto se convierte en un proyecto para un VPS y no para un portátil por el funcionamiento de GitHub. GitHub entrega los eventos del repositorio mediante una solicitud HTTP a una URL que se registra una vez, por lo que esa URL debe responder en la misma dirección mañana.

Las cuatro piezas móviles

El listener recibe los eventos de la plataforma, y cada plataforma tiene el suyo. El listener de GitHub es un endpoint HTTP en el puerto 3050 y la ruta /github/webhooks. El listener de Slack Events API está en el puerto 3040 y en /slack/events. Slack también puede ejecutarse en Socket Mode. En ese modo, la aplicación abre un WebSocket saliente y no necesita ningún puerto entrante.

El dispatcher es el coordinador. Escucha en el puerto 3030 de forma predeterminada, guarda el estado de las ejecuciones en el archivo de base de datos local definido por OPENTAG_DATABASE_PATH y registra un seguimiento de auditoría para cada ejecución. Nada externo debe poder acceder nunca a este puerto.

El runner es el daemon local. Consulta si hay trabajo, reclama una ejecución, mantiene un lease sobre ella y envía un heartbeat cada 15 segundos de forma predeterminada mientras la ejecución está activa. Rechaza cualquier ejecución reclamada cuyo destino de proyecto falte o esté fuera de la allowlist de su propia configuración. Esta comprobación impide que un evento de GitHub dirija el agente a un repositorio que nunca vinculó.

El ejecutor es el propio agente de programación. OpenTag lo inicia mediante ACP (agent client protocol), un protocolo JSON-RPC que se comunica a través de la entrada y la salida estándar. Por tanto, el agente se ejecuta como un proceso hijo dentro del directorio de trabajo que OpenTag le proporciona. Los nombres integrados incluyen echo, codex, claude-code, cursor, opencode, hermes y openclaw. Empiece con echo, el ejecutor incluido en la configuración de ejemplo, porque permite comprobar que todo el flujo funciona antes de que un modelo modifique el código. Si el bucle que lee una solicitud, llama a las herramientas y decide cuándo ha terminado todavía no le resulta claro, escribir primero su propio bucle de agente pequeño facilita mucho la interpretación de los modos de fallo de este flujo.

El orden nunca cambia: evento de la plataforma, comprobación de la firma, registro de la ejecución, reclamación, agente y respuesta en el hilo.

Por qué un portátil y un túnel no bastan

La guía de configuración de GitHub indica ejecutar ngrok http 3050 y pegar el host del túnel en el webhook del repositorio. Esto funciona durante los primeros diez minutos. La dirección ya no es el problema: el plan gratuito de ngrok proporciona a cada cuenta un dominio de desarrollo estable, y ngrok http lo reutiliza cada vez que reinicia. El problema es el túnel. Sólo responde mientras el proceso del agente se ejecuta en un portátil encendido, y deja de existir cuando el portátil entra en suspensión. GitHub sigue intentando enviar la carga útil a la URL, por lo que la pestaña Recent Deliveries de la configuración del webhook se llena de errores mientras el hilo permanece en silencio. Nadie lo detecta durante una semana, porque un webhook que no hace nada parece exactamente un bot del que nadie habló.

Un VPS corrige el problema. El nombre DNS es suyo, por lo que la URL de carga útil que pega una vez sigue siendo correcta sin depender de un proveedor de túneles. El equipo no entra en suspensión, así que un comentario publicado a las 02:00 recibe respuesta. Configure primero el servidor correctamente: los primeros diez minutos en un VPS nuevo cubre el usuario de inicio de sesión y el firewall que da por supuestos esta guía.

Slack es la excepción. En Socket Mode, se conecta hacia fuera y no necesita una URL pública, por lo que una implementación que sólo use Slack puede permanecer cerrada. GitHub no tiene un equivalente. Los webhooks de los repositorios son solicitudes HTTP entrantes, lo que implica un endpoint público y, por tanto, TLS (transport layer security) y una comprobación de la firma.

Alojar OpenTag en Ubuntu desde una versión fijada

OpenTag v0.9.0 requiere Node.js 22 o una versión posterior, y v0.10.0 eleva ese requisito a 22.14. Ubuntu 24.04 incluye Node 18 en su propio repositorio, así que debe instalarlo desde NodeSource.

curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node -v

node -v debe mostrar v22 o una versión posterior. En Node 20, la instalación muestra una advertencia EBADENGINE y la CLI puede fallar cuando se inicia.

Asigne al servicio una cuenta propia. El agente se ejecuta con los permisos de este usuario, por lo que no debe ser su cuenta de inicio de sesión ni root. Usuarios con privilegios mínimos en un VPS explica por qué merece la pena realizar este paso adicional.

sudo adduser --disabled-password --gecos "" opentag
sudo loginctl enable-linger opentag
sudo npm install -g @opentag/cli@0.9.0
command -v opentag

command -v opentag debe mostrar una ruta como /usr/bin/opentag. La configuración de linger es importante en Linux: OpenTag instala su servicio en segundo plano mediante systemd, y un servicio de usuario sin linger se detiene en cuanto se cierra la sesión SSH.

Ejecute la configuración con ese usuario.

sudo -iu opentag opentag setup

El asistente de configuración solicita seis datos: el idioma de la CLI, la dirección de escucha local, el agente de programación, el proyecto local en el que debe trabajar, las credenciales de la plataforma que debe guardar y el modo de ejecución. Mantenga la dirección de escucha en 127.0.0.1, porque nginx termina TLS y reenvía las conexiones a ella. Así, los listeners no tienen que ser accesibles desde el exterior. Para GitHub, también solicita el repositorio en formato owner/repo, si puede abrir pull requests, el puerto del webhook (3050 de forma predeterminada) y el token. Al final, seleccione el modo de servicio en segundo plano. Si ya tiene una configuración y quiere instalar el servicio sin preguntas, opentag setup --service lo hace.

La configuración se guarda en /home/opentag/.config/opentag/config.json y el estado de ejecución en /home/opentag/.local/state/opentag. Conviene revisar manualmente estas claves después de que el asistente escriba el archivo.

{
  "runnerId": "runner_local",
  "dispatcherUrl": "http://localhost:3030",
  "runnerToken": "...",
  "approvalMode": "ask",
  "repositories": []
}

Prefiera runnerToken, el bearer token limitado al runner, frente al pairingToken compartido más antiguo. El archivo de configuración contiene las credenciales en texto plano, a menos que las sustituya por una referencia a un secreto. Esta referencia obtiene el valor del entorno o de un archivo del disco al iniciar. En cualquier caso, este archivo es el elemento más sensible del servidor: debe tener permisos 600, pertenecer a opentag y no estar nunca dentro de un repositorio git. La explicación más amplia está en mantener los secretos fuera de los agentes de IA.

Compruebe la instalación antes de exponerla.

sudo -iu opentag opentag doctor
sudo -iu opentag opentag status

opentag doctor comprueba el dispatcher, los bindings, los checkouts y los executors. opentag status muestra la configuración y el estado de ejecución, y puede limitarse a una sola ejecución cuando ya existan ejecuciones. Corrija todo lo que indique doctor antes de conectar una plataforma a este servidor.

Coloque TLS delante y abra sólo dos rutas

nginx termina TLS y reenvía exactamente dos rutas. Todo lo demás devuelve 404, por lo que un escáner que encuentre el host no obtiene información sobre lo que se ejecuta detrás.

Escriba un bloque de servidor sencillo para el puerto 80 en /etc/nginx/sites-available/opentag con las dos ubicaciones siguientes y deje que Certbot añada la parte TLS.

sudo apt install -y nginx certbot python3-certbot-nginx
sudo ln -s /etc/nginx/sites-available/opentag /etc/nginx/sites-enabled/opentag
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d opentag.example.com

nginx -t muestra syntax is ok y test is successful. Es el único elemento entre un error tipográfico y una recarga que deja el sitio fuera de servicio. Certbot en Ubuntu 24.04 con nginx explica la renovación y las formas en que puede fallar un desafío ACME (entorno de gestión automática de certificados). El bloque terminado es el siguiente.

server {
    listen 443 ssl;
    server_name opentag.example.com;

    ssl_certificate     /etc/letsencrypt/live/opentag.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/opentag.example.com/privkey.pem;

    client_max_body_size 2m;

    location = /github/webhooks {
        proxy_pass http://127.0.0.1:3050;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location = /slack/events {
        proxy_pass http://127.0.0.1:3040;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location / {
        return 404;
    }
}

El = de location = /github/webhooks es una coincidencia exacta, y proxy_pass sin nada después del puerto pasa la URI original sin modificar. Si elimina =, también se reenvía cada ruta bajo /github/webhooks/, lo que expone más superficie de la que necesita el listener.

El firewall debe mantenerse restringido.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Los puertos 3030, 3040 y 3050 nunca se abren. Confirme que estén asociados a loopback y no a todas las interfaces.

sudo ss -tlnp

Todas las líneas de OpenTag deben mostrar 127.0.0.1:3030 o algo similar. Una línea que muestre 0.0.0.0:3050 significa que el listener se ofrece a toda Internet y que sólo ufw lo está bloqueando. Un error en el firewall bastaría para activar un agente expuesto. conceptos básicos del firewall ufw explica qué hace realmente esa denegación predeterminada.

Dos comprobaciones confirman la puerta de entrada. curl -I https://opentag.example.com/ devuelve 404 desde nginx, lo que demuestra que el certificado es válido y que el bloque catch-all está cerrado. Una petición a /slack/events o /github/webhooks sin firma nunca debe devolver 200.

Verifique todas las firmas, porque la URL es pública

Cualquiera puede encontrar la URL de carga útil. Está en la configuración del repositorio, en el historial del navegador o en una captura de pantalla pegada en un ticket. La firma es lo único que distingue una entrega real de GitHub de una petición escrita manualmente por otra persona.

GitHub firma cada entrega con el secreto del webhook y envía el resultado en la cabecera x-hub-signature-256. OpenTag verifica esa cabecera con platforms.github.webhookSecret. Las notas de endurecimiento del proyecto establecen la regla directamente: no acepte eventos de origen sin firma en /github/webhooks. Slack firma cada petición con SLACK_SIGNING_SECRET e incluye una marca de tiempo, por lo que un cuerpo capturado no se puede reproducir varias horas después.

Omitir esta comprobación no supone un riesgo menor. Un endpoint sin verificar acepta una carga útil issue_comment escrita manualmente que contiene @opentag. OpenTag ejecuta entonces un agente de programación, con su token, en su checkout y siguiendo instrucciones de un desconocido. La respuesta se envía al hilo que indique la carga útil falsa.

OpenTag añade dos capas más. Las entregas de origen se registran mediante el ID de entrega, por lo que volver a entregar el mismo evento no inicia una segunda ejecución. Las llamadas del runner aceptan claves de idempotencia, por lo que repetir una llamada devuelve éxito sin añadir otro evento de auditoría.

Los límites de tasa se pueden configurar y deben estar activados. OPENTAG_RATE_LIMIT_WINDOW_MS y OPENTAG_RATE_LIMIT_MAX_REQUESTS limitan la tasa de peticiones, OPENTAG_MAX_REQUEST_BODY_BYTES limita el tamaño del cuerpo y las cargas útiles demasiado grandes se rechazan con 413 request_body_too_large. OPENTAG_RATE_LIMIT_DISABLED=true existe para el desarrollo local y no debe utilizarse en un servidor público. Otra regla de las mismas notas: una URL de relay pública debe usar HTTPS, y la CLI sólo permite HTTP sin cifrar para localhost.

¿Qué ámbitos de token necesita realmente el bot?

En GitHub, OpenTag usa un token de acceso personal de permisos específicos en lugar de una GitHub App. La documentación indica que la opción de la App está prevista y que hoy no es la configuración predeterminada de la CLI. Esto tiene una consecuencia que suele pasarse por alto: el bot publica comentarios como la persona que creó el token. Créelo con una cuenta cuyo nombre esté dispuesto a ver citado en cada respuesta de triaje.

Limite los permisos exactamente como indica la guía de configuración. Seleccione Only select repositories y elija uno. Conceda Issues: Read and write y Pull requests: Read and write. Esto basta para leer una mención y responder en el hilo.

Observe lo que falta: acceso de escritura al código. OpenTag no publica ramas a menos que preparePullRequestBranch esté establecido en true, y existe un githubApplyToken independiente para que el token que escribe código no sea el mismo que publica comentarios. Manténgalos separados y no active el token de escritura hasta que el flujo de lectura y comentarios haya funcionado durante varias semanas.

La configuración que debe evitar es un token con Contents: Read and write en All repositories. Cualquier persona que pueda comentar en alguno de esos repositorios puede dirigir ahora un agente con permisos para crear commits, y el registro de auditoría atribuirá la acción al propietario del token. Amplíe el ámbito a un repositorio cada vez, después de que el agente haya demostrado que lo merece.

En Slack, los ámbitos del bot son app_mentions:read, chat:write, reactions:write y channels:history. Los canales privados también necesitan groups:history y una suscripción al evento message.groups. Socket Mode necesita un token de nivel de aplicación con connections:write, cuyo valor empieza por xapp-. channels:history lee el historial de mensajes de los canales públicos a los que se ha añadido el bot. Por tanto, añada el bot sólo a los canales donde se necesite, no a todos.

Enrutar un problema de principio a fin

El webhook es el primer paso. En el repositorio, abra Settings, después Webhooks y, por último, Add webhook. La URL de carga útil es https://opentag.example.com/github/webhooks, el tipo de contenido es application/json y el secreto es el que generó la configuración. Suscríbase a Issue comments y Pull request review comments, y a ningún otro evento.

GitHub envía una entrega de prueba en cuanto guarda la configuración. Abra Recent Deliveries y compruebe que la solicitud llegó al servidor. Un 502 indica que nginx no pudo llegar al proceso que escucha, por lo que el problema es local y no de GitHub.

Ahora úselo. Abra una incidencia que describa un error y escriba este comentario:

@opentag triage this. Reproduce the report against the current main branch, then reply with the file and function most likely responsible, plus the test you would write first.

Esto es lo que debe ocurrir, en orden. Recent Deliveries registra la entrega issue_comment con una respuesta 2xx. El dispatcher registra una ejecución. El runner la reclama y empieza a enviar señales de actividad. El executor abre el checkout y trabaja. La respuesta llega como comentario en el mismo hilo de la incidencia. sudo -iu opentag opentag status muestra la ejecución mientras está en curso, para que pueda supervisarla en lugar de hacer suposiciones.

Establezca approvalMode en ask antes de la primera ejecución real. En el modo ask, la ejecución se pausa y espera a que una persona la autorice antes de realizar cualquier cambio de estado. Los modos auto y autonomous también están disponibles y son opciones razonables más adelante, en un repositorio cuyos registros de conversaciones haya revisado durante un mes.

En Slack, la misma ejecución comienza con /bind owner/repo en el canal y, después, con una mención. El bot también responde a /help, /status, /doctor, /stop y /unbind confirm. Restrinja quién puede modificar las vinculaciones con OPENTAG_SLACK_BINDING_ADMIN_USER_IDS, una lista de Slack user IDs separada por comas, porque una vinculación es el mapeo entre un canal público y un checkout en su servidor.

Triage es una buena primera opción porque lee datos y no escribe en ellos, y la respuesta es fácil de evaluar. Review es el siguiente paso, donde el agente comenta un diff en lugar de una incidencia: un agente de revisión de pull requests autoalojado usa esta misma arquitectura orientada a pull requests. Si quiere que el agente acceda a sus propios sistemas mientras trabaja, esa es la función de los servidores MCP en un VPS. La búsqueda web es la otra capacidad que Triage suele necesitar, y conectar el agente a su propia instancia de SearXNG mantiene esas consultas en hardware que usted administra, a cambio de añadir otro canal por el que el texto de un tercero llega al agente.

¿Qué ocurre cuando el agente se equivoca delante de todos?

Se equivocará. La cuestión es cuánto cuesta.

Una respuesta incorrecta en una incidencia pública es un comentario publicado con un nombre que el equipo reconoce, y GitHub envía un correo a todas las personas suscritas en cuanto se publica. Eliminar el comentario no retira el correo. Lo mismo ocurre con una notificación de Slack. Planifique para que la respuesta sea incorrecta en público, no para que sea correcta en privado.

Cuatro decisiones limitan el daño y son más importantes que cualquier prompt que escriba.

  • Ejecútelo en modo ask, para que el agente proponga, una persona apruebe y un plan incorrecto cueste un clic.
  • Mantenga preparePullRequestBranch con su valor predeterminado de false, para que el peor resultado de una ejecución incorrecta sea un comentario equivocado y no una rama incorrecta.
  • Vincule un repositorio y un canal al principio. El runner rechaza cualquier ejecución cuyo destino de proyecto esté fuera de su allowlist local, por lo que un repositorio no vinculado no puede activar el agente por sí mismo.
  • Mantenga separado el token de comentarios de cualquier token de aplicación, para que revocar el acceso de escritura no interrumpa el triage.

Slack tiene un comando /stop para una ejecución que avanza en la dirección equivocada. Cada ejecución también deja un registro de auditoría con la mención que la inició y las acciones del agente. Ese registro es lo que se revisa después para determinar dónde se produjo el error.

La parte social es tan importante como la configuración. Coloque el bot en un canal donde las personas esperen interactuar con una máquina y sepan que puede equivocarse. Una respuesta incorrecta expresada con seguridad en un canal de cuarenta personas que dan por hecho que una persona la revisó cuesta más que el tiempo ahorrado en el triage. Indique en la descripción del canal quién es responsable del bot y quién revisa sus resultados.

Copias de seguridad, actualizaciones y fijación de versión

Dos rutas contienen todo: /home/opentag/.config/opentag/config.json y /home/opentag/.local/state/opentag. La primera contiene las credenciales y la segunda contiene el historial de ejecuciones y el archivo de base de datos. Haga copias de seguridad de ambas con el modo 600 y guárdelas fuera del servidor. Perderlas implica volver a crear los tokens y las vinculaciones, no reconstruir un servidor.

Las actualizaciones consisten en cambiar la versión y reiniciar.

sudo npm install -g @opentag/cli@0.9.0
sudo -iu opentag opentag service stop
sudo -iu opentag opentag service start
sudo -iu opentag opentag doctor

Fije la versión en lugar de seguir @latest. Este software ejecuta un agente de código contra su repositorio con un token activo, por lo que una versión publicada durante la noche representa un cambio no revisado en ese comportamiento. La política de seguridad indica que las correcciones se dirigen a la versión más reciente y a la rama main actual, y que las versiones antiguas pueden no recibir correcciones retroportadas. Una versión fijada en 0.9.0 ya está una versión por detrás de v0.10.0, por lo que fijar una versión implica leer el registro de cambios y actualizar de forma deliberada. No significa permanecer en v0.9.0 para siempre. El historial hasta julio de 2026 muestra varias versiones al mes, y v0.10.0 llegó el 17 de agosto. Esto es un buen motivo para leer las notas de la versión antes de cada actualización. v0.10.0 también establece como comportamiento predeterminado la finalización gobernada para las ejecuciones de solicitudes de incorporación de cambios de GitHub, y OPENTAG_GITHUB_DEFAULT_COMPLETION=compat restaura el comportamiento anterior.

A partir de ahora, lea atentamente las notas. En octubre de 2026, la sección no publicada del registro de cambios en main describe un reinicio pre-1.0 intencionadamente incompatible que elimina GitHub como aplicación de origen y el dispatcher SQLite integrado del que depende esta guía. Ninguna versión etiquetada lo contiene todavía, pero cuando lo haga, la ruta del webhook de GitHub anterior no sobrevivirá a esa actualización.

FAQ

¿Necesito un VPS para ejecutar OpenTag o basta con un portátil?

Un portátil basta para Slack, porque Socket Mode abre un WebSocket saliente y no necesita ningún puerto entrante. GitHub funciona de otra forma. Los webhooks del repositorio se entregan mediante HTTP entrante a una URL que se registra una vez. Por tanto, la dirección debe mantenerse igual y responder mientras usted duerme. Una cuenta gratuita de ngrok mantiene ahora el mismo dominio de desarrollo entre reinicios, por lo que la dirección no cambia. El túnel no permanece activo, porque sólo responde mientras el portátil está encendido y el agente está en ejecución. Cuando no lo está, las entregas de GitHub fallan. Esto aparece como entradas fallidas en la pestaña Recent Deliveries del repositorio y como silencio en el hilo. Un VPS con un nombre DNS fijo y un certificado elimina ese problema.

¿Qué permisos de GitHub necesita OpenTag?

Un personal access token con permisos detallados, limitado a Only select repositories, con Issues: Read and write y Pull requests: Read and write. Esto permite leer una mención y responder en el hilo. No se necesita acceso de escritura al código, salvo que establezca preparePullRequestBranch en true para que OpenTag envíe ramas. Además, existe un githubApplyToken independiente para mantener separado el token que escribe código del token que publica comentarios. Evite un token para todos los repositorios con permiso contents write, porque cualquiera que pueda comentar en alguno de esos repositorios podría dirigir un agente con capacidad para hacer commits.

¿Cómo detengo una ejecución que está yendo mal?

Slack tiene un comando /stop específico para esto. En el servidor, opentag status muestra lo que está en ejecución y opentag service stop detiene el daemon, lo que finaliza todo el pipeline en lugar de una sola ejecución. Para no depender de ninguna de estas acciones, establezca approvalMode en ask para que las ejecuciones se pausen y requieran la intervención de una persona antes de cambiar nada. Mantenga preparePullRequestBranch en false para que una ejecución incorrecta produzca un comentario en lugar de una rama.

¿Por qué mi webhook devuelve 502 mientras el hilo permanece en silencio?

El código 502 procede de nginx, no de OpenTag, y significa que el proxy no pudo llegar al listener. /var/log/nginx/error.log mostrará connect() failed (111: Connection refused) while connecting to upstream. El listener está detenido o utiliza un puerto diferente del que indica la línea proxy_pass. Ejecute sudo ss -tlnp y confirme que hay un proceso escuchando en 127.0.0.1:3050 para GitHub y en 127.0.0.1:3040 para Slack. Después, ejecute opentag doctor para comprobar los bindings y los ejecutores.

¿Te resultó útil este artículo?

#opentag#ai-agents#slack#github#webhooks#self-hosting