Un bot de Feishu para varios Hermes: tutorial paso a paso de routing de Profile en v0.19

Antes de Hermes Agent v0.19, si querías ejecutar diferentes personalidades de Agent en distintos grupos de Feishu, la opción más simple era: crear una aplicación de bot de Feishu para cada grupo y ejecutar un Gateway de Hermes para cada una. Muchos tokens, muchos procesos y una configuración dispersa.

La combinación de multiplex_profiles + profile_routes en v0.19 te permite usar una sola aplicación de bot de Feishu y un solo proceso de Gateway para distribuir mensajes de diferentes grupos o hilos a diferentes Profile. Cada Profile tiene su propio modelo, skills, memoria y secretos, pero comparten la misma identidad de bot.

Este artículo se basa en el release oficial de Hermes v0.19.0 y en la documentación del proyecto, y ofrece un ejemplo completo y listo para usar.

¿Quieres ver el panorama general primero? Lee nuestro resumen de las notas de lanzamiento de Hermes v0.19.0 Quicksilver y las v0.19.0 release notes oficiales.

Requisitos previos

  • Hermes Agent >= v0.19.0
  • Una aplicación de bot de Feishu (Lark) creada y aprobada
  • El bot tiene habilitada la “suscripción de eventos” y puede recibir eventos como im.message.receive_v1
  • Has obtenido app_id, app_secret, encrypt_key y verification_token desde la consola de desarrollador de Feishu

Si aún no has conectado tu bot de Feishu a Hermes, puedes configurar primero las credenciales en ~/.hermes/.env:

FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx

El adaptador de Feishu de Hermes es un Gateway completo desde v0.6.0, con soporte para tarjetas de mensaje, chats grupales, adjuntos de imagen/archivo y callbacks interactivos, así que la conectividad básica no será un problema.

Conceptos clave: multiplex_profiles + profile_routes

Antes de v0.19, el Gateway de Hermes ya era “un proceso que conecta múltiples plataformas”. La novedad de v0.19 es: la misma plataforma, el mismo token de bot, y aún así enrutar por origen a diferentes Profile.

Campos clave:

  • gateway.multiplex_profiles: true — activa el modo de reutilización de múltiples Profile
  • gateway.profile_routes — define la lista de reglas de coincidencia por origen

Nota: en modo multiplex, las plataformas de enlace de puerto (webhook, api_server, feishu, etc.) solo se pueden configurar en el Profile default; los demás Profile reciben mensajes a través de las reglas de routing. Este artículo describe exactamente ese patrón: la entrada de Feishu corre en el Profile default, y profile_routes despacha los mensajes a Profile como work o personal.

Ejemplo de configuración para Feishu

Supongamos que tienes tres grupos de Feishu:

Grupo Uso Profile deseado
Grupo de guardia técnica Alertas, logs, comandos seguros ops
Grupo de producto Escribir PRDs, análisis de competencia product
Grupo personal Agenda personal, consultas personal

En ~/.hermes/config.yaml escribe algo así:

profiles:
  default:
    # La entrada de Feishu solo puede estar en el Profile default
    gateway:
      platforms:
        - platform: feishu
          app_id: "cli_xxxxxxxxxxxxxxxx"
          app_secret: "{{env.FEISHU_APP_SECRET}}"
          encrypt_key: "{{env.FEISHU_ENCRYPT_KEY}}"
          verification_token: "{{env.FEISHU_VERIFICATION_TOKEN}}"
          allowed_users:
            - "ou_xxxxxxxx"
            - "ou_yyyyyyyy"

  ops:
    model: "claude-sonnet-5"
    system_prompt: "Eres un asistente de guardia técnica, experto en logs, operaciones de contenedores y respuesta de seguridad."
    skills:
      - kubernetes
      - sentry
    approvals:
      smart_approvals: true
    deny_rules:
      - pattern: "kubectl delete.*prod"
        reason: "Las operaciones de borrado en producción están prohibidas de forma automática"

  product:
    model: "gpt-5.6-sol"
    system_prompt: "Eres un asistente de producto, experto en escribir PRDs, análisis de competencia y organización de feedback."
    skills:
      - notion
      - web_search

  personal:
    model: "grok-4.5"
    system_prompt: "Eres un asistente de productividad personal con tono relajado."

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-product
      platform: feishu
      chat_id: "oc_yyyyyyyyyyyyyyyy"
      profile: product

    - name: feishu-personal
      platform: feishu
      chat_id: "oc_zzzzzzzzzzzzzzzz"
      profile: personal

    # Fallback: todos los mensajes directos de un usuario van a personal
    - name: feishu-dm
      platform: feishu
      user_id: "ou_xxxxxxxx"
      profile: personal

Guarda y ejecuta:

hermes config validate
hermes gateway restart

Campos de routing de Feishu explicados

profile_routes en v0.19 soporta los siguientes campos para Feishu/Lark (ordenados por especificidad):

Campo Significado Ejemplo Peso de especificidad
platform Tipo de plataforma, obligatorio feishu Base
chat_id ID del chat/grupo de Feishu (empieza con oc_) oc_xxxxxxxxxxxxxxxx Alto
thread_id ID del hilo/tema de Feishu omt_xxxxxxxxxxxxxxxx Máximo
user_id ID de usuario de Feishu (empieza con ou_) ou_xxxxxxxx Medio-alto
tenant_id ID de empresa/tenant (escenarios multi-tenant) xxx Medio
profile Nombre del Profile destino ops —
name Comentario de la regla feishu-ops —

Reglas de coincidencia:

  1. Todos los campos declarados deben cumplirse (relación AND).
  2. Los campos no declarados se ignoran.
  3. Mayor especificidad gana: thread_id > chat_id > user_id > tenant_id > solo platform.
  4. Con la misma especificidad, gana la primera regla declarada.

Por eso puedes enrutar un grupo completo por chat_id y luego hacer un desvío más fino dentro de un hilo con thread_id.

Cómo obtener chat_id, thread_id y user_id de Feishu

La forma más sencilla: deja que Hermes corra primero con el Profile default, envía un mensaje y revisa el log en busca del session_key o el payload del evento. El log suele mostrar algo como:

[feishu] incoming message chat_id=oc_xxxxxxxxxxxxxxxx thread_id=omt_yyyyyyyy user_id=ou_zzzzzzzz

O añade temporalmente un skill echo en el Profile default que responda:

chat_id: oc_xxxxxxxxxxxxxxxx
thread_id: omt_yyyyyyyy
user_id: ou_zzzzzzzz

Una vez tengas los IDs, escríbelos en profile_routes y reinicia el Gateway.

Error común: no puedes configurar Feishu en varios Profile

En modo multiplex, si intentas poner en ops algo como:

profiles:
  ops:
    gateway:
      platforms:
        - platform: feishu
          ...

El arranque fallará. feishu es una plataforma de enlace de puerto, por lo que su entrada solo puede estar en el Profile default. Los Profile secundarios obtienen Feishu exclusivamente a través de profile_routes.

Si necesitas aislamiento a nivel de proceso (por ejemplo, ops no puede compartir proceso con personal), no uses multiplex. En su lugar, inicia un Gateway independiente para cada Profile con hermes -p ops gateway start.

Comandos de depuración y validación

# Ver si multiplex está activado
hermes config get gateway.multiplex_profiles

# Ver las reglas de profile_routes activas
hermes config get gateway.profile_routes

# Validar la sintaxis de la configuración
hermes config validate

# Iniciar/reiniciar el Gateway
hermes gateway start
hermes gateway restart

# Ver el estado del Gateway y qué Profile están siendo servidos
hermes status

# Ver logs en tiempo real de Feishu (en otra terminal)
hermes gateway --log-level debug

Después de enviar un mensaje de prueba, busca en los logs:

[multiplex] routed feishu chat_id=oc_xxx to profile=ops

Si no aparece, la regla no coincidió. Revisa que el chat_id no tenga espacios ni errores de copia.

Avanzado: aislamiento por hilo (thread_id)

Los hilos de Feishu son como subcanales dentro de un grupo. Puedes enrutar diferentes hilos del mismo grupo a diferentes Profile:

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops-main
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-ops-oncall
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      thread_id: "omt_yyyyyyyyyyyyyyyy"
      profile: ops-oncall

Como thread_id tiene mayor especificidad, los mensajes dentro de ese hilo irán a ops-oncall, mientras que el resto del grupo irá a ops.

Avanzado: escenario multi-tenant (tenant_id)

Si instalas la misma aplicación de bot en varias empresas de Feishu (escenario ISV), puedes enrutar por tenant_id:

gateway:
  profile_routes:
    - name: tenant-a
      platform: feishu
      tenant_id: "tenant_a_id"
      profile: customer-a

    - name: tenant-b
      platform: feishu
      tenant_id: "tenant_b_id"
      profile: customer-b

Combinado con los per-profile secret scopes de Hermes, cada cliente puede tener secretos y modelos completamente aislados.

Recomendaciones de seguridad

  1. Siempre define allowed_users: el bot de Feishu solo responde a usuarios en la lista blanca, evitando abusos si alguien lo añade a un grupo desconocido.
  2. Separa los permisos por Profile: el Profile ops puede conectar herramientas de operaciones, pero product no debería tener acceso a la ejecución en producción.
  3. Usa deny_rules como red de seguridad: incluso si un mensaje se enruta mal, las reglas de denegación pueden bloquear comandos peligrosos. Consulta nuestro tutorial anterior sobre las tres barreras de Smart Approvals en Hermes v0.19.
  4. Verifica la exactitud de chat_id: en Feishu es fácil confundir oc_ con ou_, y un error hará que los mensajes vayan al Profile default o no coincidan.

Resumen

profile_routes en Hermes v0.19 transforma un bot de Feishu de “un bot, un Agent” a “un bot, múltiples Agent”. El núcleo de la configuración son tres pasos:

  1. Configura la única entrada de Feishu en el Profile default;
  2. Activa gateway.multiplex_profiles: true;
  3. Usa gateway.profile_routes para dividir por chat_id / thread_id / user_id / tenant_id hacia diferentes Profile.

Así, el mismo bot de Feishu puede actuar como asistente de operaciones en un grupo técnico, redactor de PRDs en un grupo de producto y asistente personal en mensajes directos, sin mantener múltiples bots ni procesos de Gateway.

# Validación final y arranque
hermes config validate
hermes gateway restart
hermes status