![\"LiteLLM\"](\"https://wec.wiline.com/docs/es/assets/images/litellm-wordmark-86d6f0432720b27534e05bc579dfc29c.png\")
++Así es como suele ir. Una aplicación necesita un modelo, así que pegas la clave API en\nsu .env. Luego, una segunda aplicación necesita una. Luego un script. Seis meses después, la misma\nclave está en cinco lugares, nadie recuerda cuál de ellas sigue funcionando, y no\npuedes rotarla sin romper algo que solo descubrirás cuando se rompa.
Un gateway es la solución aburrida. Un endpoint frente a cada modelo, un lugar que\nmantiene la verdadera credencial, y una clave específica por aplicación que puedes revocar por sí sola.\nEsta publicación despliega uno en una instancia WEC y lo apunta a la API de Inferencia WEC.
\n\nEl host ya ejecuta cinco otras pilas, lo cual es importante: este es el caso normal,\nno una VM limpia. Antes de agregar nada, verifica qué está escuchando y qué está libre:
\ndocker ps --format '{{.Names}}\\t{{.Ports}}'
sudo ss -tlnp | grep -E ':(4000|5432|5433)\\b'
langfuse-postgres-1 127.0.0.1:5433->5432/tcp
langfuse-clickhouse-1 127.0.0.1:8123->8123/tcp, 127.0.0.1:9000->9000/tcp
openclaw-caddy-1 100.87.239.229:80->80/tcp, 100.87.239.229:443->443/tcp
...
LISTEN 0 244 127.0.0.1:5432 users:((\"postgres\",pid=892))
LISTEN 0 4096 127.0.0.1:5433 users:((\"docker-proxy\"))
El puerto 4000 está libre. Postgres 5432 pertenece al host y 5433 a Langfuse, así que la\nbase de datos del gateway no obtiene ninguno: no publicará un puerto en absoluto.
\nLuego confirma que el backend responde antes de poner algo frente a él:
\ncurl -s https://inference.wiline.com/v1/models \\
-H \"Authorization: Bearer $WEC_API_KEY\" | jq -r '.data[].id'
whisper-large-v3
gemma4
wiline-coding
zai-org/GLM-5.2
Qwen2.5-3B-Instruct
Qwen3.5:9B
Qwen3.5-122B
kokoro
Llama3.1-8B-Instruct
bge-m3
Qwen3.5-9B
wiline-auto
wiline-cost
Trece modelos en una clave. Eso es lo que estamos a punto de dejar de repartir.
\nDos contenedores: el gateway y un Postgres para su propio estado. Crea un directorio y\nescribe el archivo de composición:
\nmkdir -p ~/llm-gateway && cd ~/llm-gateway
services:
litellm:
image: ghcr.io/berriai/litellm:main-stable
container_name: llm-gateway
restart: unless-stopped
ports:
- \"127.0.0.1:4000:4000\"
volumes:
- ./config.yaml:/app/config.yaml:ro
command: [\"--config\", \"/app/config.yaml\", \"--port\", \"4000\"]
env_file: .env
depends_on:
db:
condition: service_healthy
db:
image: postgres:17
container_name: llm-gateway-db
restart: unless-stopped
user: \"999:999\"
environment:
POSTGRES_USER: llmproxy
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: litellm
volumes:
- gateway-db:/var/lib/postgresql/data
healthcheck:
test: [\"CMD-SHELL\", \"pg_isready -U llmproxy -d litellm\"]
interval: 5s
timeout: 5s
retries: 10
volumes:
gateway-db:
Cuatro de esas líneas están haciendo trabajo real:
\n127.0.0.1:4000:4000 mantiene el gateway fuera de Internet público. Mantiene cada\ncredencial de modelo que posees, así que publicarlo en 0.0.0.0 pondría todas\ndetrás de una sola contraseña compartida. Parte 1 de la serie de endurecimiento es la versión larga de por qué\neso es un mal intercambio.
La base de datos no tiene ports: en absoluto. Nada fuera de la red de composición necesita\nalcanzarla, y 5432 ya estaba ocupado.
user: \"999:999\" ejecuta Postgres como su usuario no root incorporado desde el primer arranque.\nParte 2 cubre lo que eso te ofrece\ny cómo encontrar el UID correcto para una imagen en lugar de adivinar.
condition: service_healthy importa más de lo que parece. El gateway ejecuta migraciones de base de datos al inicio: sin esto, compite con Postgres y se reinicia en bucle.
model_list:
- model_name: qwen-small
litellm_params:
model: openai/Qwen2.5-3B-Instruct
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: qwen-mid
litellm_params:
model: openai/Qwen3.5-9B
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: qwen-large
litellm_params:
model: openai/Qwen3.5-122B
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: embeddings
litellm_params:
model: openai/bge-m3
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
store_model_in_db: true
litellm_settings:
drop_params: true
model_name es el alias que tus aplicaciones piden. model: es lo que el gateway realmente\nllama. Esa indirecta es la mayor parte del valor: cambia qwen-mid para apuntar a otro lugar\nel próximo mes y ningún cliente cambia.
El prefijo openai/ dice \"habla el protocolo OpenAI a un api_base personalizado.\" La\nAPI de Inferencia WEC es compatible con OpenAI, así que eso es todo lo que se necesita.
Genera las contraseñas en lugar de inventarlas:
\nPGPW=$(openssl rand -hex 16)
MK=\"sk-$(openssl rand -hex 20)\"
cat > .env <<EOF
POSTGRES_PASSWORD=${PGPW}
DATABASE_URL=postgresql://llmproxy:${PGPW}@db:5432/litellm
LITELLM_MASTER_KEY=${MK}
WEC_API_KEY=your-wec-key-here
EOF
chmod 600 .env
Luego pon tu verdadera clave WEC en lugar de your-wec-key-here. La clave maestra es la\ncredencial raíz del gateway: puede crear claves, eliminar claves y acceder a cada modelo,\nasí que va en tu gestor de contraseñas y en ningún otro lugar.
docker compose up -d
✔ Imagen ghcr.io/berriai/litellm:main-stable Descargada 58.2s
✔ Red llm-gateway_default Creada 0.1s
✔ Volumen llm-gateway_gateway-db Creado 0.1s
✔ Contenedor llm-gateway-db Saludable 8.8s
✔ Contenedor llm-gateway Creado 0.2s
![\"docker](\"https://wec.wiline.com/docs/es/assets/images/gw-compose-up-e741e826f043d86aa7f1a7214f71fbcb.png\")
\nFigura 1. Una descarga, dos contenedores, una red y un volumen.
Creado en lugar de Iniciado en esa última línea es normal para la salida de composición,\npero verifica de todos modos — y verifica cuánto te costó la imagen en disco mientras estás ahí:
docker compose ps -a && echo && df -h /
NAME IMAGE SERVICE STATUS PORTS
llm-gateway ghcr.io/berriai/litellm:main-stable litellm Up 3 minutes 127.0.0.1:4000->4000/tcp
llm-gateway-db postgres:17 db Up 3 minutes (healthy) 5432/tcp
Filesystem Size Used Avail Use% Mounted on
/dev/vda1 58G 54G 4.2G 93% /
Nota la columna PORTS de la base de datos: 5432/tcp sin enlace de host delante de\nella. La imagen del gateway es de 1.16GB, lo cual en una caja que ya ejecuta cinco pilas no es\nnada despreciable. Verifica que tienes espacio antes de comenzar, no después.
Dos líneas en el registro de inicio valen la pena leer, porque ambas se ven peores de lo que son:
\ndocker compose logs litellm --tail 40
✅ Diferencia de migración aplicada con éxito
INFO: Inicio de la aplicación completo.
INFO: Uvicorn ejecutándose en http://0.0.0.0:4000 (Presiona CTRL+C para salir)
register_model: model=openai/Qwen2.5-3B-Instruct no en el mapa de costos incorporado y no
se coincidió con ninguna variante de prefijo/región; los campos de costo de caché se establecerán en 0.
![\"Estado](\"https://wec.wiline.com/docs/es/assets/images/gw-ps-logs-ed50299979281a4fb3dfd6ec9c89d189.png\")
\nFigura 2. Migraciones aplicadas, inicio de la aplicación completo, y una advertencia del mapa de costos por modelo.
0.0.0.0:4000 es el enlace dentro del contenedor. La publicación del host sigue siendo\n127.0.0.1, que es lo que realmente controla el acceso. Y la advertencia del mapa de costos es\nmás específica de lo que parece: se trata de la fijación de precios de caché específicamente. La\nfijación de precios de tokens regulares sigue ocurriendo, lo cual resulta ser importante más adelante.
set -a && . ./.env && set +a
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":20}' | jq
\"finish_reason\": \"length\",
\"message\": {
\"reasoning_content\": \"Proceso de Pensamiento:\\n\\n1. **Analiza la Solicitud:**\\n * Entrada: \\\"\",
\"content\": null
}
\"usage\": {\"completion_tokens\": 20, \"prompt_tokens\": 16, \"total_tokens\": 36}
![\"Respuesta](\"https://wec.wiline.com/docs/es/assets/images/gw-reasoning-null-2d60fce2efcb8e175da27120082ac585.png\")
\nFigura 3. Una llamada exitosa sin nada en ella.
content: null. La llamada funcionó: se enruta, llegó al backend, contó tokens\n— pero no hay respuesta en ella.
Qwen3.5-9B es un modelo de razonamiento. Gastó todos los veinte tokens pensando y no le quedó\nnada para hablar. El movimiento obvio es darle más espacio:
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":200}' | jq '.choices[0].message.content, .usage'
null
{
\"completion_tokens\": 200,
\"prompt_tokens\": 16,
\"total_tokens\": 216
}
Doscientos tokens, aún nada. Y esta es la parte que vale la pena pausar: una ejecución anterior de ese mismo\ncomando sí respondió, con 192 tokens. Mismo modelo, mismo aviso,\ndiferente cantidad de pensamiento. No hay un max_tokens que puedas establecer que garantice\nuna respuesta, porque la longitud del razonamiento no es fija.
Ahora el mismo aviso a través del modelo pequeño, con los veinte tokens originales:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":20}' | jq '.choices[0].message.content, .usage'
\"gateway works\"
{
\"completion_tokens\": 3,
\"prompt_tokens\": 35,
\"total_tokens\": 38
}
![\"Modelo](\"https://wec.wiline.com/docs/es/assets/images/gw-token-contrast-922bab5aa94a6417e02dbc0d6fe0c874.png\")
\nFigura 4. Doscientos tokens y ninguna respuesta, contra tres tokens y la respuesta.
Nada está roto aquí. El modelo de razonamiento está haciendo exactamente lo que se supone que debe hacer,\nen una pregunta que no lo necesitaba. La solución no es un presupuesto de tokens más grande: no\nenviar trabajo trivial a ese modelo en primer lugar. Lo cual es todo el argumento\npara el enrutamiento, y el tema de la próxima publicación.
\nPuedes poner un gateway frente a varios modelos, dar a cada uno un alias que tus aplicaciones\nllamen en lugar de un ID de modelo de proveedor, y leer una respuesta lo suficientemente bien como para distinguir un\nmodelo de razonamiento de uno simple.
Un gateway que mantiene cada credencial que posees debería rechazar a cualquiera sin una clave.\nVale la pena verificar en lugar de asumir:
\ncurl -s -o /dev/null -w \"sin clave: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}]}'
curl -s -o /dev/null -w \"clave incorrecta: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer sk-not-a-real-key\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}]}'
curl -s -o /dev/null -w \"clave maestra: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}],\"max_tokens\":5}'
sin clave: 401
clave incorrecta: 401
clave maestra: 200
![\"Tres](\"https://wec.wiline.com/docs/es/assets/images/gw-auth-401-a9d9d89ff8432a6ec7a29486800ea82c.png\")
\nFigura 5. Tanto anónimos como falsificados rechazados, la clave real a través.
El gateway incluye una interfaz web, y está vinculada a localhost — que es el\npunto, así que accede a ella a través de SSH en lugar de abrir un puerto:
\nssh -L 4000:127.0.0.1:4000 ubuntu@your-wec-instance
Deja eso funcionando y abre http://localhost:4000/ui. Nombre de usuario admin, la contraseña\nes la clave maestra de tu .env.
![\"La](\"https://wec.wiline.com/docs/es/assets/images/gw-ui-login-94d370f9590bd022684fb80ccabb2aff.png\")
\nFigura 6. La página de inicio de sesión indica sus propias credenciales predeterminadas, lo cual es un buen\nrecordatorio de que la clave maestra es lo único que está ahí.
Haz clic en Modelos + Endpoints:
\n![\"Gestión](\"https://wec.wiline.com/docs/es/assets/images/gw-ui-models-4372c39b1bfb45a2d61782e145f1c5e2.png\")
\nFigura 7. Los cuatro alias registrados, cada uno mapeado a su objetivo openai/....
La clave maestra puede acceder a cada modelo y crear más claves. Ninguna aplicación debería\ntenerla nunca. En su lugar, emite una clave virtual específica para lo que esa aplicación realmente necesita.
\nClaves Virtuales → + Crear Nueva Clave:
\n| Campo | Valor |
|---|---|
| Propietario | Tú |
| Equipo | dejar vacío |
| Nombre de Clave | demo-app |
| Modelos | qwen-small |
| Presupuesto Máximo (USD) | 0.10 |
| Restablecer Presupuesto | diario |
Dos cosas sobre este formulario. Presupuesto Máximo vive bajo Configuraciones Opcionales,\nque comienza colapsada — fácil de perder y luego preguntarse dónde fue el campo de presupuesto. Y\ndejar Modelos vacío significa todos los modelos, lo opuesto a lo que quieres aquí.
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/gw-key-create-f440427f7d6f55ad01482ed469ff3624.png\")
\nFigura 8. Específico para un modelo, limitado a diez centavos al día.
![\"El](\"https://wec.wiline.com/docs/es/assets/images/gw-key-saved-e13c0abfcd4b4c0bfefa791764eaae50.png\")
\nFigura 9. El diálogo lo dice claramente. Créelo.
La clave generada se muestra una vez y nunca más. Cierra esto sin copiar y\ntu única opción es eliminar la clave y crear otra.
Ahora la parte que justifica todo el ejercicio. La misma clave, dos modelos:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $VK\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"di hola\"}],\"max_tokens\":20}' | jq -r '.choices[0].message.content'
¡Hola! ¿Cómo puedo ayudarte hoy?
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $VK\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-large\",\"messages\":[{\"role\":\"user\",\"content\":\"di hola\"}],\"max_tokens\":20}' | jq
{
\"error\": {
\"message\": \"clave no permitida para acceder al modelo. Esta clave solo puede acceder a modelos=['qwen-small']. Intentó acceder a qwen-large\",
\"type\": \"key_model_access_denied\",
\"param\": \"model\",
\"code\": \"403\"
}
}
![\"La](\"https://wec.wiline.com/docs/es/assets/images/gw-key-403-ff8ff7ee956b8b081dd67c4d3834ac10.png\")
\nFigura 10. Una credencial, un modelo. Filtrarla y el radio de explosión es esa línea.
Compara eso con la situación en la que comenzamos: una clave en cinco archivos .env, con acceso\na todos los trece modelos y sin forma de saber qué aplicación la está utilizando.
Puedes emitir una credencial específica por aplicación, restringirla a modelos específicos\ncon un límite de gasto, y revocarla por sí sola sin tocar nada más.
Cada llamada aterriza en un registro de gastos:
\ncurl -s http://127.0.0.1:4000/spend/logs \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
| jq '[.[] | select(.spend > 0)] | .[-3:] | .[] | {model, spend, prompt_tokens, completion_tokens}'
{
\"model\": \"openai/Qwen3.5-9B\",
\"spend\": 8.520000000000001e-05,
\"prompt_tokens\": 16,
\"completion_tokens\": 20
}
{
\"model\": \"openai/Qwen3.5-9B\",
\"spend\": 2.62e-05,
\"prompt_tokens\": 11,
\"completion_tokens\": 5
}
![\"Filas](\"https://wec.wiline.com/docs/es/assets/images/gw-spend-logs-dfdc834679299ecd1fcfcc774e83b5b3.png\")
\nFigura 11. Tokens contados por llamada, con un precio adjunto a cada uno.
Ese select(.spend > 0) no es cosmético. Las llamadas fallidas también se registran, con cero\ntokens y cero gasto: los 401 de antes están todos ahí con\nstatus: \"failure\". Útil por sí mismo: el registro de gastos también sirve como un registro de\nalguien intentando claves que no funcionan.
Los conteos de tokens son reales. Las cifras en dólares no lo son — no para ti, de todos modos. Estos son\nmodelos autoalojados en tu propia infraestructura; el gateway los está fijando precios a partir de\nuna tabla incorporada de tarifas de API públicas. El número es preciso y confiablemente incorrecto,\nlo cual es peor que en blanco. Arreglar eso significa declarar tu propio costo por token, y\nese es el tema de la cuarta publicación de esta serie.
\nDos cosas más en la entrada completa del registro, ambas útiles:
\n\"litellm_overhead_time_ms\": 36.189,
\"messages\": {},
\"response\": {}
El gateway mide su propia sobrecarga y la informa por solicitud: 36ms aquí, que\nes un número real al que puedes exigirle. Y los avisos y respuestas no se almacenan por\ndefecto: el registro sabe que ocurrió una llamada y cuánto costó, no lo que se dijo.
\nCasi siempre es la base de datos. Verifica docker compose logs litellm para errores de migración: si el gateway se levantó antes de que Postgres estuviera listo, falta la condición depends_on\no el healthcheck no está pasando.
content regresa null con finish_reason: \"length\"El modelo es un modelo de razonamiento y utilizó todo tu presupuesto de tokens pensando. Aumentar\nmax_tokens ayuda pero no garantiza nada: el mismo aviso con 200 tokens respondió en una ejecución y devolvió null en la siguiente. Para trabajos que no necesitan\nrazonamiento, envíalos a un modelo que no lo haga.
Está vinculada a 127.0.0.1, así que es inaccesible desde cualquier lugar que no sea la caja misma.\nUsa un túnel SSH. Si el túnel está activo y la página aún no carga, confirma que el\npuerto en docker compose ps coincide con el que has reenviado.
Las cadenas unidas con && se detienen en el primer comando que falla, y un grep fallido\ncuenta como un fallo. Sourcing un archivo env cuyo nombre de variable adivinaste mal\ndeja un marcador en su lugar y todo parece bien hasta un error de autenticación tres\npasos después. Verifica los marcadores explícitamente:
grep -c 'your-wec-key-here' .env
Desde la terminal, por alias:
\ncurl -s -X POST http://127.0.0.1:4000/key/delete \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"key_aliases\":[\"demo-app\"]}' | jq
Ahora tienes un endpoint, una credencial por aplicación y un registro de cada llamada. La\npregunta obvia es la que planteó la Figura 4: si el modelo pequeño responde en 3 tokens\nlo que el modelo de razonamiento gasta 200 sin responder en absoluto, ¿por qué se está enrutando\ncualquier cosa al costoso por defecto?
\nLa próxima publicación pone al gateway a cargo de esa decisión y mide lo que cuesta pedirle.
\nParte 1 de esta serie auditó una caja multi-agente en vivo y encontró cada pregunta sobre exposición de red que valía la pena hacer. Una línea de esa auditoría no se siguió: \"el Postgres, ClickHouse y Redis detrás de Langfuse estaban publicados en 127.0.0.1 en lugar del mundo — alguien tomó una buena decisión allí. Mantén ese pensamiento.\"
Aquí está la otra mitad de ese pensamiento: conseguir la red correcta no dice nada sobre lo que sucede después de que alguien ya esté dentro de un contenedor. Si el proceso que se ejecuta allí es root, un compromiso comienza con las llaves de todo el sistema de archivos. Así que verificamos — en la misma caja, la misma pila de Langfuse que la Parte 1 ya alabó — si \"red correcta\" también significaba \"privilegio correcto.\" No lo era, para dos de los seis contenedores. Aquí está cómo se veía realmente la solución, incluyendo la parte que se rompió.
\n\nDocker no te dice esto por defecto — un contenedor puede estar publicado correctamente, saludable y ejecutándose como root todo el tiempo, sin que nada en docker ps lo sugiera. La única forma de saberlo es preguntar directamente al contenedor:
docker exec langfuse-postgres-1 id -u
docker exec langfuse-redis-1 id -u
0
0
![\"Ambas](\"https://wec.wiline.com/docs/es/assets/images/privsec-root-confirmed-9af63f21bf8c07c7554a6cbab4f02929.png\")
\nFigura 1. La verificación que la mayoría de las configuraciones nunca ejecutan: ambas llamadas a id -u regresan 0. Saludables, publicados correctamente, y root todo el tiempo.
0 es root. Ambos estaban ejecutándose como root, y al mirar el archivo de composición se explica por qué — ninguno de los servicios tiene una directiva user: en absoluto:
redis:
image: docker.io/redis:7
restart: always
command: >
--requirepass ${REDIS_AUTH:-myredissecret}
--maxmemory-policy noeviction
...
postgres:
image: docker.io/postgres:${POSTGRES_VERSION:-17}
restart: always
...
Nadie decidió que estos debían ejecutarse como root. Es simplemente lo que sucede cuando no configuras nada — la misma forma que el hallazgo de la Parte 1 de que una contraseña de Redis no configurada predetermina la falta de autenticación. El servicio clickhouse en el mismo archivo muestra la solución ya medio hecha, sentada justo allí para comparación:
clickhouse:
image: docker.io/clickhouse/clickhouse-server
restart: always
user: \"101:101\"
Una línea. Alguien lo configuró para ClickHouse y nunca llegó a los otros dos.
\nNo inventes un UID — ambas imágenes oficiales ya incluyen un usuario no root construido para exactamente esto, y adivinar mal significa un error de permisos o, peor aún, un UID que silenciosamente no coincide con el que los propios archivos de la imagen son propiedad:
\ndocker exec langfuse-postgres-1 id postgres
docker exec langfuse-redis-1 id redis
uid=999(postgres) gid=999(postgres) groups=999(postgres),101(ssl-cert)
uid=999(redis) gid=999(redis) groups=999(redis)
Ambas imágenes utilizan 999:999 para su usuario no root incorporado. Agrégalo al archivo de composición:
redis:
image: docker.io/redis:7
user: \"999:999\"
restart: always
...
postgres:
image: docker.io/postgres:${POSTGRES_VERSION:-17}
user: \"999:999\"
restart: always
...
docker compose up -d --force-recreate postgres redis
✔ Contenedor langfuse-postgres-1 recreado
✔ Contenedor langfuse-redis-1 recreado
sleep 5
docker compose ps
docker exec langfuse-postgres-1 id -u
docker exec langfuse-redis-1 id -u
langfuse-postgres-1 Up 34 seconds (healthy) 127.0.0.1:5433->5432/tcp
langfuse-redis-1 Up 34 seconds (healthy) 127.0.0.1:6379->6379/tcp
999
999
![\"docker](\"https://wec.wiline.com/docs/es/assets/images/privsec-nonroot-healthy-2aa6142e51931837aa80ee308e8be448.png\")
\nFigura 2. Los mismos dos contenedores, segundos después de --force-recreate: ambos healthy, ambos id -u ahora 999 en lugar de 0.
Sin errores de permisos, sin dramas de propiedad, ambos saludables en segundos. Eso vale la pena decirlo claramente porque no siempre es cierto — si estos volúmenes se hubieran inicializado como root en algún lugar upstream y nunca se les hubiera hecho chown, este comando exacto puede fallar con permission denied en el directorio de datos. No falló aquí, pero revisa tus propios registros después de recrear, no asumas que \"sin salida\" significa \"sin problema.\"
Puedes verificar si un contenedor en ejecución es realmente root (docker exec <container> id -u), encontrar el usuario no root previsto de su imagen en lugar de adivinar un UID (docker exec <container> id <username>), y convertirlo con una línea user: en la composición.
Todo lo anterior fue limpio. Luego, los registros de un contenedor completamente diferente contaron una historia diferente:
\ndocker logs langfuse-langfuse-worker-1 --tail 20
Error: getaddrinfo ENOTFOUND redis
at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:122:26)
Error de Redis getaddrinfo ENOTFOUND redis
Error de Redis connect ECONNREFUSED 172.19.0.5:6379
El trabajo de cola mixpanel-integration-processing-queue falló: Error: Tiempo de espera de socket.
Esperando datos, pero no se recibió ninguno en 30000ms.
El trabajo de cola trace-delete falló: Error: Tiempo de espera de socket. Esperando datos, pero no se recibió ninguno en 30000ms.
![\"registros](\"https://wec.wiline.com/docs/es/assets/images/privsec-worker-broken-e776f29e677755bd8a5e61864dbe22bc.png\")
\nFigura 3. Un contenedor que nadie tocó, fallando de todos modos — cada trabajo de cola con el mismo tiempo de espera de socket de 30 segundos contra Redis, mucho después de la recreación que lo causó.
langfuse-worker nunca tocó la propiedad de Postgres o Redis — solo mantiene una conexión activa a Redis, y --force-recreate derribó el contenedor al que apuntaba esa conexión. La propia verificación de salud de Docker decía que Redis estaba healthy de nuevo mucho antes de que el trabajador se rindiera al reintentar; ioredis simplemente no se reconecta limpiamente por sí mismo aquí, y siguió fallando con tiempos de espera de socket de 30 segundos mucho después de que la dependencia de la que dependía volvió.
La solución es el reinicio del propio servicio dependiente, no otra mirada a Redis:
\ndocker compose restart langfuse-worker langfuse-web
2026-08-10T19:40:22.505Z info La conexión a Redis se ha cerrado.
2026-08-10T19:40:22.769Z info Apagado completo, saliendo del proceso...
sleep 10
docker logs langfuse-langfuse-worker-1 --tail 15
experiment-create-queue executor started: true
posthog-integration-queue executor started: true
data-retention-queue executor started: true
webhook-queue executor started: true
Listening: http://21caf9a28775:3030
![\"registros](\"https://wec.wiline.com/docs/es/assets/images/privsec-worker-recovered-ca07f68b5e4cb0994524f20c497f41ca.png\")
\nFigura 4. El mismo contenedor, un reinicio después — cada ejecutor de cola comienza limpio, sin errores de Redis en ninguna parte del registro.
Inicio limpio de la cola, sin errores de Redis. Esa es toda la lección: endurecer un contenedor no se limita a ese contenedor. Cualquier cosa que mantenga una conexión activa con la cosa que acabas de recrear necesita su propio reinicio, a propósito, no como un pensamiento posterior que descubres a partir de un registro de errores veinte minutos después.
\n--force-recreate en una dependencia compartida (una base de datos, una cola, un caché) puede romper silenciosamente cada servicio que ya tenía una conexión abierta a ella — incluso después de que la dependencia misma informe que está saludable de nuevo. Reinicia explícitamente a los dependientes; no asumas que lo notarán por sí mismos.
| Contenedor | Antes | Solución | ¿Rompe algo? |
|---|---|---|---|
langfuse-postgres-1 | root (uid 0) | user: \"999:999\" | No — recreado limpio |
langfuse-redis-1 | root (uid 0) | user: \"999:999\" | No — recreado limpio |
langfuse-clickhouse-1 | ya 101:101 | ninguna necesaria | — |
langfuse-langfuse-worker-1 | intocable | ninguna — solo necesitaba un reinicio | Sí — perdió su conexión a Redis después de que los otros dos contenedores fueron recreados |
Dos soluciones de una línea. El costo real no fue la solución — fue notar que el tercer contenedor que nadie tocó fue el que se rompió.
\ndocker compose restart dijo \"no se proporcionó archivo de configuración: no encontrado\"No estás en el directorio del proyecto que Compose espera — solo encuentra docker-compose.yml relativo a tu directorio de trabajo actual (o a través de -f). Primero, cd en la carpeta de la pila; este error exacto significa que Compose nunca miró siquiera a tus contenedores.
Reiniciar la dependencia no ayuda — la conexión que se rompió pertenece al servicio dependiente. Reinicia la cosa que mantiene la conexión (aquí, langfuse-worker), no la cosa a la que se conecta.
docker exec <container> id <username> devuelve \"no existe tal usuario\"La imagen no incluye un usuario no root dedicado bajo ese nombre — consulta la documentación de la imagen, o docker exec <container> cat /etc/passwd para ver qué está realmente disponible antes de elegir un UID.
El privilegio es la segunda capa: el endurecimiento de la red evita que un compromiso se propague entre pilas, el no root evita que un compromiso posea todo el contenedor. La última capa en esta serie es la identidad — poner autenticación real frente a los puertos que deben permanecer expuestos, que es donde NetBird y Caddy entran en juego.
\nComienzas con un agente. Luego necesita una base de datos. Después agregas un segundo agente, un puente de mensajería, una pila de observabilidad. Seis meses después, una única instancia de WEC está ejecutando cinco proyectos de compose, veinte y tantos contenedores, y nadie recuerda qué puertos están abiertos al mundo.
\nEso no es un hipotético — esa es la caja en la que se escribió este tutorial. Así que en lugar de teorizar, lo investigamos: ¿pueden los contenedores alcanzarse entre sí a través de pilas? ¿Pueden alcanzar las bases de datos? ¿Está el firewall realmente protegiendo algo?
\nTres de las respuestas me sorprendieron. Una de ellas fue una base de datos sentada allí sin contraseña. Y el firewall — el firewall estaba mintiendo.
\n\nCinco proyectos de compose independientes, desplegados durante meses, cada uno con su propia red (host, none y bridge son los integrados de Docker, más uno sobrante de un servicio que no está en ejecución):
docker network ls
NETWORK ID NAME DRIVER SCOPE
655850b24125 bridge bridge local
05e5d49e7e9d evolution-api_default bridge local
e8bd75ecbb0a host host local
ce697baac173 langfuse_default bridge local
ead3e0822ce6 nlp-evaluation-service_nlp-net bridge local
5d0ab32d14d7 none null local
9a6727150f2b openclaw_default bridge local
ec77b98f457b rag-service_default bridge local
5f88cabf97f0 remark42_default bridge local
Y aquí está lo que se publica al mundo:
\ndocker ps --format '{{.Names}}\\t{{.Ports}}' | grep '0.0.0.0'
remark42-remark42-1 0.0.0.0:8082->8080/tcp, [::]:8082->8080/tcp
evolution-api-evolution-api-1 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp
langfuse-langfuse-web-1 0.0.0.0:3001->3000/tcp, [::]:3001->3000/tcp
langfuse-minio-1 0.0.0.0:9090->9000/tcp, [::]:9090->9000/tcp, 127.0.0.1:9091->9001/tcp
![\"La](\"https://wec.wiline.com/docs/es/assets/images/netsec-exposure-audit-904ef03d2c7552d9b1b8c9d9e69218dd.png\")
\nFigura 1. El inicio de cualquier auditoría. Nueve redes: tres integradas de Docker (bridge, host, none), cinco proyectos de compose, y uno sobrante. Cuatro servicios publicados en 0.0.0.0 — cada interfaz, incluida la pública.
Cuatro servicios escuchando en cada interfaz. Nota lo que no está en esa lista: los Postgres, ClickHouse y Redis detrás de Langfuse. Esos fueron publicados en 127.0.0.1 en su lugar — alguien tomó una buena decisión allí. Mantén ese pensamiento.
La preocupación clásica: OpenClaw es comprometido, y el atacante entra en la base de datos de Langfuse al lado. Vamos a averiguarlo en lugar de adivinar. Obtén las IPs de los contenedores:
\nfor c in langfuse-postgres-1 evolution-api-evolution-postgres-1; do
docker inspect -f '{{.Name}} {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $c
done
/langfuse-postgres-1 172.19.0.5
/evolution-api-evolution-postgres-1 172.23.0.4
Ahora intenta alcanzar ambos desde dentro del contenedor de OpenClaw, por IP — sin DNS, sin atajos:
\ndocker exec openclaw-openclaw-gateway-1 node -e '
const net=require(\"net\");
[[\"langfuse-postgres\",\"172.19.0.5\",5432],[\"evolution-postgres\",\"172.23.0.4\",5432]]
.forEach(([n,ip,p])=>{
const s=net.connect({host:ip,port:p,timeout:4000});
s.on(\"connect\",()=>{console.log(`ALCANZADO ${n}`);s.destroy()});
s.on(\"timeout\",()=>{console.log(`bloqueado ${n}`);s.destroy()});
s.on(\"error\",e=>console.log(`error ${n} ${e.code}`));
});'
bloqueado langfuse-postgres
bloqueado evolution-postgres
![\"Las](\"https://wec.wiline.com/docs/es/assets/images/netsec-isolation-blocked-52d0644c0dbd63427ca62b09eb5b9947.png\")
\nFigura 2. Conectando por IP cruda desde el contenedor de una pila a la base de datos de otra pila: ambos se agotan. Las reglas de aislamiento de Docker están haciendo su trabajo.
Bloqueado. Las instalaciones modernas de Docker instalan reglas de DOCKER-ISOLATION-STAGE que eliminan el tráfico entre redes de puente definidas por el usuario, y funcionan. Si has leído que \"las redes Docker no realmente aíslan\", pruébalo en tu propia caja antes de creerlo — en Docker actual, sí lo hacen.
Puedes verificar el aislamiento de red empíricamente en lugar de confiar en el folclore: obtén la IP del objetivo con docker inspect, luego conecta por IP desde dentro de otro contenedor.
Así que el aislamiento entre pilas está bien. Lo que significa que el verdadero riesgo está en otro lugar.
\nCada proyecto de compose coloca todos sus servicios en una red. Esa es la predeterminada, y significa que el contenedor de la aplicación puede alcanzar cada servicio de respaldo — lo cual es intencionado. La pregunta es cómo se ve realmente ese acceso. Desde el contenedor de puente de Evolution API:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket
for name, host, port in [(\"postgres\",\"evolution-postgres\",5432),
(\"redis\",\"evolution-redis\",6379),
(\"api\",\"evolution-api\",8080)]:
s=socket.socket(); s.settimeout(4)
try:
s.connect((host,port)); print(f\"ALCANZADO {name}:{port}\")
except Exception as e:
print(f\"bloqueado {name}:{port} -- {type(e).__name__}\")
finally: s.close()'
ALCANZADO postgres:5432
ALCANZADO redis:6379
ALCANZADO api:8080
Alcanzable es esperado. No autenticado no lo es. Verifica si esos servicios realmente piden credenciales — primero Redis:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(5); s.connect((\"evolution-redis\",6379))
s.sendall(b\"INFO server\\r\\n\")
print(s.recv(200).decode(errors=\"replace\")[:120])'
$625
# Server
redis_version:7.4.9
redis_git_sha1:00000000
redis_git_dirty:0
redis_build_id:b61b4eb609520881
redis_
![\"Redis](\"https://wec.wiline.com/docs/es/assets/images/netsec-redis-noauth-22e25e2b5bbf007d514a914ec9ec8b91.png\")
\nFigura 3. El hallazgo: INFO server respondió sin credenciales (salida truncada a 120 caracteres por la sonda). Cualquier contenedor en esta red puede leer o borrar el almacén de sesiones.
Eso es un comando INFO respondido sin AUTH — el Redis que mantiene el estado de sesión de este despliegue no tiene contraseña. Cualquier cosa que obtenga ejecución de código en cualquier contenedor en esa red puede leerlo, escribir en él, o FLUSHALL en él.
Postgres, en la misma pila, se comporta correctamente:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket,struct
s=socket.socket(); s.settimeout(5); s.connect((\"evolution-postgres\",5432))
msg=b\"user\\x00postgres\\x00database\\x00postgres\\x00\\x00\"
s.sendall(struct.pack(\"!ii\",len(msg)+8,196608)+msg)
print(s.recv(64))'
b'R\\x00\\x00\\x00\\x17\\x00\\x00\\x00\\nSCRAM-SHA-256\\x00\\x00'
Exige SCRAM-SHA-256. La misma caja, la misma red, dos servicios de respaldo — uno pide una contraseña, el otro no. Nadie decidió eso; es simplemente lo que las imágenes predeterminan cuando no estableces una contraseña.
\nLa lección: \"red interna\" no es un límite de seguridad. Es una conveniencia. Trata cada servicio como si el atacante ya estuviera en esa red, porque si un contenedor cae, ellos están.
\nAhora lo grande. Activa UFW y deniega todo lo entrante excepto SSH:
\nsudo ufw allow 22/tcp # SIEMPRE primero, o te bloqueas
sudo ufw default deny incoming
sudo ufw --force enable
sudo ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip
To Action From
-- ------ ----
60000:61000/udp ALLOW IN Anywhere
22/tcp ALLOW IN Anywhere
60000:61000/udp (v6) ALLOW IN Anywhere (v6)
22/tcp (v6) ALLOW IN Anywhere (v6)
Denegar entrante — solo SSH y el rango UDP de mosh permitido. Ahora, desde una máquina diferente, abre la interfaz de usuario de Langfuse y la API de Evolution:
\nhttp://<instance-ip>:3001 -> La interfaz de usuario de Langfuse se carga normalmente
http://<instance-ip>:8080 -> {\"status\":200,\"message\":\"Bienvenido a la API de Evolution...\"}
![\"La](\"https://wec.wiline.com/docs/es/assets/images/netsec-ufw-bypass-130569873d3680226c3534f016c4756a.png\")
Figura 4. El firewall dice que deniega todo lo entrante. La API de Evolution en :8080 responde de todos modos — estado 200, directamente desde un navegador en otra máquina.
Ambos completamente abiertos, a través de un firewall configurado para bloquearlos. Esta es la sorpresa de seguridad más común en Docker auto-alojado, y no es un error.
\nMira el orden de la cadena FORWARD:
sudo iptables -L FORWARD -n --line-numbers | head -8
Chain FORWARD (policy DROP)
num target prot opt source destination
1 DOCKER-USER all -- 0.0.0.0/0 0.0.0.0/0
2 DOCKER-FORWARD all -- 0.0.0.0/0 0.0.0.0/0
3 ACCEPT all -- 0.0.0.0/0 0.0.0.0/0 ctstate RELATED,ESTABLISHED
4 ACCEPT all -- 0.0.0.0/0 0.0.0.0/0
5 ufw-before-logging-forward all -- 0.0.0.0/0 0.0.0.0/0
6 ufw-before-forward all -- 0.0.0.0/0 0.0.0.0/0
![\"UFW](\"https://wec.wiline.com/docs/es/assets/images/netsec-ufw-chains-7a5553d8ce1882eb415c7e12e1beb065.png\")
\nFigura 5. La explicación completa en una pantalla: el firewall dice denegar entrante, y las cadenas de Docker están en las posiciones 1-2 mientras que las de UFW comienzan en 5.
Las cadenas de Docker están en las posiciones 1 y 2. Las de UFW no aparecen hasta 5 y 6. Y publicar un puerto no es un oyente en el host — es una regla de NAT:
\nsudo iptables -t nat -L DOCKER -n | grep -E '3001|8080'
DNAT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:8080 to:172.23.0.3:8080
DNAT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:3001 to:172.19.0.2:3000
El paquete llega, el NAT de Docker reescribe el destino al contenedor, y se convierte en tráfico reenviado que la propia cadena de Docker acepta — mucho antes de que se consulte cualquier regla de UFW. Tus reglas de UFW no son ignoradas; simplemente nunca se alcanzan.
\nufw deny no protege un puerto Docker publicado. Si has estado confiando en UFW frente a -p 8080:8080, ese puerto ha estado abierto todo el tiempo.
La solución más limpia no es una regla de firewall; es no abrir la puerta. Si un servicio solo es consumido por otros contenedores, no necesita ninguna entrada ports: — el tráfico de servicio a servicio funciona a través de la red de compose por nombre.
Si necesitas que sea accesible desde el host (un puerto de depuración, un psql local), enlázalo explícitamente al loopback:
\nservices:
postgres:
# prefijo 127.0.0.1 = solo host, nunca la interfaz pública
ports:
- \"127.0.0.1:5433:5432\"
Eso es exactamente lo que la pila de Langfuse en esta caja ya hace — su Postgres, ClickHouse y Redis están todos en 127.0.0.1, que es por qué nunca aparecieron en nuestra auditoría de exposición. El predeterminado \"5433:5432\" significa 0.0.0.0 — cada interfaz, incluida la pública.
internalUna red por proyecto de compose es la predeterminada, no un diseño. Da a los servicios de respaldo su propia red, y coloca solo la aplicación en ambas:
\nservices:
app: # habla con el mundo Y con la base de datos
image: your-agent
networks: [frontend, backend]
db:
image: redis:7
command: redis-server --requirepass ${REDIS_PASSWORD}
networks: [backend] # solo backend — sin ruta hacia afuera
public: # por ejemplo, un receptor de webhook
image: your-public-thing
networks: [frontend] # no puede ver la base de datos en absoluto
networks:
frontend:
backend:
internal: true # sin gateway: sin entrada, sin salida
Verificado en la misma caja:
\n# el contenedor solo de frontend intenta alcanzar la base de datos
docker exec netsecdemo-public-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(4)
try: s.connect((\"db\",6379)); print(\"ALCANZADO db <- fuga\")
except Exception as e: print(f\"bloqueado: {type(e).__name__}\")'
# la app, que está en ambas redes
docker exec netsecdemo-app-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(4)
try: s.connect((\"db\",6379)); print(\"ALCANZADO db <- correcto, lo necesita\")
except Exception as e: print(f\"bloqueado: {type(e).__name__}\")'
# y puede la base de datos alcanzar Internet?
docker exec netsecdemo-db-1 timeout 6 getent hosts pypi.org >/dev/null \\
&& echo \"resuelto DNS externo\" || echo \"sin salida a Internet <- interno funcionando\"
bloqueado: gaierror
ALCANZADO db <- correcto, lo necesita
sin salida a Internet <- interno funcionando
![\"La](\"https://wec.wiline.com/docs/es/assets/images/netsec-internal-demo-6231d6936686cf9d282c7f494797a185.png\")
Figura 6. Tres propiedades probadas en una ejecución — el contenedor de cara pública ni siquiera puede resolver la base de datos, la app puede alcanzarla, y la base de datos no tiene ruta a Internet.
\nTres propiedades a la vez: el contenedor de cara pública ni siquiera puede resolver la base de datos, la app puede, y la base de datos no puede comunicarse — lo cual importa el día que una dependencia tuya se vuelva maliciosa.
\nNuestra auditoría encontró a Redis respondiendo INFO sin credenciales. Una línea lo soluciona:
db:
image: redis:7
command: redis-server --requirepass ${REDIS_PASSWORD}
-NOAUTH Authentication required.
Esa es la salida real de esta caja, después de aplicar la solución — el hallazgo de la Prueba 2 está cerrado. Si estableces una contraseña en un Redis que algo ya usa, recuerda actualizar la cadena de conexión del cliente también (redis://:<password>@host:6379/0), o cambiarás una base de datos abierta por una rota.
Haz esto incluso para servicios que no están publicados. La defensa en profundidad significa que la segunda capa se mantiene cuando la primera falla.
\nDOCKER-USERA veces un puerto realmente tiene que ser de cara pública pero restringido por origen. La cadena a usar es DOCKER-USER — Docker garantiza que se ejecute antes de sus propias reglas de aceptación, y nunca la sobrescribe:
# solo 203.0.113.0/24 puede abrir nuevas conexiones al puerto 3000 del contenedor
sudo iptables -I DOCKER-USER 1 -p tcp --dport 3000 \\
-m conntrack --ctstate NEW ! -s 203.0.113.0/24 -j DROP
Probado en vivo en el puerto de Langfuse, desde un navegador en otra máquina:
\nhttp://<instance-ip>:3001 -> La interfaz de usuario de Langfuse se carga
ERR_CONNECTION_TIMED_OUT
![\"La](\"https://wec.wiline.com/docs/es/assets/images/netsec-docker-user-blocked-8e34c54fd3b4552806e49bf87aed7cfb.png\")
Figura 7. Misma URL, mismo firewall, una regla en la cadena correcta — y el puerto está finalmente cerrado. Nota la propia sugerencia de Chrome: \"Verificando el proxy y el firewall.\" Esta vez el firewall realmente es la respuesta.
\nMientras tanto, la API de Evolution en :8080, que deliberadamente dejamos sola, siguió respondiendo. La regla es quirúrgica, y funciona exactamente donde UFW no pudo.
iptables -I no es persistente. Usa iptables-persistent (netfilter-persistent save), o coloca la regla en una pequeña unidad de systemd que se ejecute después de docker.service. Una regla de firewall que desaparece al reiniciar es peor que ninguna, porque pensarás que estás protegido.
Puedes auditar y asegurar un host Docker multi-pila: prueba qué es alcanzable, enlaza o divide lo que no debería ser, autentica los backends, y filtra los puertos publicados en la única cadena que Docker respeta.
Ejecuta estos cuatro comandos en cualquier caja que poseas. Toman un minuto y te dicen más que cualquier diagrama de arquitectura:
\n# 1. ¿Qué está expuesto al mundo?
docker ps --format '{{.Names}}\\t{{.Ports}}' | grep '0.0.0.0'
# 2. ¿Están tus reglas de firewall incluso en la ruta? (Las cadenas de Docker antes de ufw = no lo están)
sudo iptables -L FORWARD -n --line-numbers | head -8
# 3. ¿Qué puede alcanzar un contenedor comprometido en su propia red?
docker exec <container> python3 -c \"import socket;s=socket.socket();s.settimeout(3);s.connect(('<svc>',<port>));print('alcanzado')\"
# 4. ¿Ese servicio de respaldo pide una contraseña?
docker exec <container> python3 -c \"
import socket;s=socket.socket();s.settimeout(4);s.connect(('redis',6379))
s.sendall(b'INFO server\\r\\n');print(s.recv(60))\"
| Hallazgo | Severidad | Solución |
|---|---|---|
| El aislamiento entre redes funciona | ✅ ninguno | nada — Docker ya hace esto |
| Cada servicio en una red, mutuamente alcanzable | ⚠️ medio | dividir por zona de confianza, internal: true |
Redis respondiendo sin AUTH | 🔴 alto | una línea: --requirepass |
ufw deny no aplicado a puertos publicados | 🔴 alto | enlazar a 127.0.0.1, o regla DOCKER-USER |
Bases de datos de respaldo en 127.0.0.1 (Langfuse) | ✅ ninguno | ya correcto — copia este patrón |
Ninguna de las soluciones tomó más de una línea de YAML. La parte costosa fue saber qué línea — y la única manera de saberlo es sondear tu propia caja en lugar de confiar en el diagrama en tu cabeza.
\nDOCKER-USER y nada cambióDos causas habituales. Primero, --dport debe ser el puerto del contenedor, no el publicado — el DNAT ya reescribió el destino para cuando DOCKER-USER ve el paquete (en nuestro caso 3000, no 3001). Segundo, las conexiones existentes no se ven afectadas: la coincidencia --ctstate NEW solo toca las nuevas, así que una pestaña de navegador ya abierta sigue funcionando.
sudo ufw allow 22/tcp antes de ufw enable, siempre. Si ya estás bloqueado, la mayoría de los proveedores te dan una consola serial/VNC — úsala para ejecutar ufw disable.
internal: true rompió la instalación de paquetes de mi contenedorEso es que está funcionando. Una red interna no tiene gateway, así que no hay salida en absoluto — sin pip install, sin DNS, sin llamar a una API externa. Los servicios de respaldo no deberían necesitar nada de eso; si un contenedor lo hace, también pertenece a la red de frontend.
El DNS de Compose solo resuelve nombres dentro de una red compartida. Si app y db están en diferentes redes sin nada en común, db no se resolverá. La app tiene que ser miembro de ambas, como en la Solución 2.
El endurecimiento de la red es la capa que evita que un contenedor comprometido se convierta en un host comprometido. Las siguientes capas, en el orden en que las haría: ejecutar contenedores como no-root (user: en compose) para que una ruptura comience con menos privilegios, y poner un proveedor de identidad frente a los puertos que debes exponer — una malla privada con\nNetBird más autenticación es la combinación natural con todo lo anterior.
![\"Hermes](\"https://wec.wiline.com/docs/es/assets/images/hermesagent-c76bbe81610ae2e70b0950e0f96bec8a.png\")
+En Parte 1 alojaste Hermes con\nmemoria persistente. Esta parte lo conecta al mismo bot de Telegram de la\nserie OpenClaw — el chat que\ntus usuarios ya conocen sigue funcionando exactamente como antes, solo que con un agente diferente respondiendo detrás. No hay un nuevo bot que anunciar, ni un canal al que migrar a la gente.
\n\nContinúa en la misma instancia WEC que la Parte 1. El gateway de Hermes ya está\ninstalado y funcionando como un servicio de usuario systemd — esta parte es configuración,\nno instalación. Cada comando y error a continuación es de la ejecución real.
El autoalojamiento solo vale la pena si no te ata al agente con el que comenzaste. El bot en sí — su nombre, su historial de chat, las personas que ya hablan con él — es el activo. El agente detrás de él es reemplazable. Cambiar OpenClaw por Hermes en el mismo bot prueba eso: misma puerta de entrada de Telegram, mismo hilo de conversación, nuevo cerebro.
\nhermes gateway setup
Selecciona Telegram de la lista de plataformas, luego elige cómo conectarlo:
\n◆ Telegram
¿Cómo te gustaría crear tu bot de Telegram?
[1] Automático (recomendado)
Escanea un código QR → confirma en Telegram → listo.
No se necesita copiar y pegar el token.
[2] Manual
Crea un bot a través de @BotFather tú mismo y pega el token.
Opción [1/2] [1]: 2
Crear un bot a través de @BotFather en Telegram
Token de bot de Telegram: **********************************************
✓ Token de Telegram guardado
Toma la opción 2 — la opción 1 crea un bot completamente nuevo a través de un código QR, lo cual derrota el propósito si estás reutilizando uno existente.
\nA continuación, el asistente pregunta quiénes pueden usar el bot:
\n🔒 Seguridad: Restringir quién puede usar tu bot
Para encontrar tu ID de usuario de Telegram:
1. Envía un mensaje a @userinfobot en Telegram
2. Te responderá con tu ID numérico (por ejemplo, 123456789)
IDs de usuario permitidos (separados por comas, deja vacío para acceso abierto):
Si no tienes tu ID a mano, déjalo en blanco y continúa — puedes restringir esto más tarde. Pero el aviso es engañoso: dejarlo vacío no abre el acceso por defecto. Los registros del gateway contaron la verdadera historia después del reinicio:
\nWARNING gateway.run: No se han configurado listas de permitidos de usuarios. Todos los usuarios no autorizados
serán denegados. Establece GATEWAY_ALLOW_ALL_USERS=true en ~/.hermes/.env para permitir
acceso abierto, o configura listas de permitidos de plataforma (por ejemplo,
TELEGRAM_ALLOWED_USERS=tu_id).
Una lista de permitidos vacía significa denegar a todos, no acceso abierto. Si deseas acceso abierto (bien para un bot personal, no para nada público), necesitas un paso más:
\necho 'GATEWAY_ALLOW_ALL_USERS=true' >> ~/.hermes/.env
El asistente también pregunta por un Canal Principal — donde Hermes entrega resultados de cron\ny mensajes entre plataformas. Déjalo en blanco también; puedes configurarlo más tarde\ndesde dentro del chat con /sethome.
Termina el asistente y deja que reinicie el gateway:
\n¿Reiniciar el gateway para recoger cambios? [Y/n]: Y
✓ Servicio de usuario reiniciado
![\"Terminal](\"https://wec.wiline.com/docs/es/assets/images/hermes-gateway-setup-wizard-7293ce9021ee147b93bad2dcb7a72a53.png\")
\nFigura 1. Todo el asistente, de principio a fin — token, la advertencia de la lista de permitidos, y el reinicio.
Si agregaste GATEWAY_ALLOW_ALL_USERS después de que el asistente ya reinició\nuna vez (como arriba), reinicia de nuevo para que recoja el cambio en .env:
systemctl --user restart hermes-gateway.service
Envía un mensaje a tu bot. No a @BotFather — a tu bot, por el nombre de usuario que le diste\ncuando lo creaste. Es fácil confundirse: BotFather responde todo con\nsu propio menú de comandos fijo, así que si ves eso en lugar de una respuesta real,\nestás en el chat equivocado.
\nEl primer mensaje puede recibir un empujón del sistema en lugar de una respuesta de chat — eso es\nHermes notando que aún no hay un canal principal, no un fallo:
\n📬 No se ha establecido un canal principal para Telegram. Un canal principal es donde Hermes
entrega resultados de trabajos cron y mensajes entre plataformas.
Escribe /sethome para hacer de este chat tu canal principal, o ignora para omitir.
Envía otro mensaje y responde de verdad:
\n![\"Chat](\"https://wec.wiline.com/docs/es/assets/images/hermes-telegram-verified-17c22677d5e1e6a1d6147099b58fdc53.png\")
\nFigura 2. El mismo bot de la serie OpenClaw, ahora respondiendo a través de Hermes.
Pregúntale algo con profundidad real, y entrega una respuesta estructurada real\n— no solo una respuesta estándar:
\n![\"Chat](\"https://wec.wiline.com/docs/es/assets/images/hermes-telegram-sky-blue-139494c527c4075440bf7afa25c14039.png\")
\nFigura 3. Mismo agente, una pregunta real — explicación completa, no una línea.
Mismo bot, mismo historial de chat, nuevo agente.
\n\"No se han configurado listas de permitidos de usuarios. Todos los usuarios no autorizados serán denegados.\" —\ndejar el aviso de la lista de permitidos vacío no significa acceso abierto; significa\ndenegar a todos. Establece GATEWAY_ALLOW_ALL_USERS=true en ~/.hermes/.env y reinicia\nel gateway.
\"Conflicto de sondeo de Telegram... asegúrate de que solo una instancia de bot esté\nejecutándose\" — aparece durante unos segundos justo después de un reinicio, mientras\nlos servidores de Telegram terminan de liberar la sesión anterior. Intenta de nuevo y\nse limpia solo dentro de los 20 segundos; no se necesita acción a menos que siga\nrepitiéndose más allá del 5to intento, lo que significa que otro proceso realmente está sondeando\nel mismo token.
\nEl bot no responde en absoluto — verifica que estás enviando un mensaje al bot mismo, no\na @BotFather. BotFather siempre responde con su propia lista de comandos independientemente de\nlo que le envíes.
\nEl bot responde — lo siguiente es ponerlo en un horario: un informe matutino o un\nchequeo de salud del servicio entregado a este mismo chat, sin necesidad de sondeo.
\n![\"SearXNG\"](\"https://wec.wiline.com/docs/es/assets/images/searxng-mark-1b536bb949960590cea598d56becda08.png\")
+Supón que has construido un chatbot de soporte o un asistente RAG en WEC. Es sólido en tus documentos y\nen lo que el modelo ya sabe, pero pregúntale algo actual (\"¿cuál es la última\nversión de X?\", precios de hoy, un cambio reciente) y o bien adivina o te dice que su\nconocimiento está desactualizado. Para cualquier cosa que necesite estar al día, eso es una verdadera brecha.
\nWEC Inference ahora tiene una herramienta de búsqueda web integrada. Agrégala a una llamada normal\n/v1/chat/completions y el modelo puede buscar cosas en la web en vivo: la búsqueda\nse realiza en la propia infraestructura de WiLine (SearXNG), por lo que nada se envía a un proveedor de búsqueda de terceros. Vamos a probarlo.
Las llamadas llegan a https://inference.wiline.com/v1/chat/completions con tu clave API de WEC Inference,\nmodelo Qwen3.5-9B. No hay nada que instalar: la herramienta es parte de la API.
Una llamada normal, preguntando algo reciente:
\ncurl -sS https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen3.5-9B\",
\"messages\": [{\"role\": \"user\", \"content\": \"¿Cuál es la última versión estable de Docker Engine, y cuándo fue lanzada?\"}]
}'
![\"El](\"https://wec.wiline.com/docs/es/assets/images/websearch-without-aeaee1a5d9a326ccb92d56a8ec08bdc5.png\")
\nFigura 1. Sin herramienta, el modelo no se compromete a una versión — dice que su conocimiento está\nlimitado a su fecha de corte de entrenamiento y te señala las notas de la versión en su lugar.
La misma solicitud, más una herramienta web_search y tool_choice: auto:
curl -sS https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen3.5-9B\",
\"messages\": [{\"role\": \"user\", \"content\": \"¿Cuál es la última versión estable de Docker Engine, y cuándo fue lanzada?\"}],
\"tools\": [{
\"type\": \"function\",
\"function\": {
\"name\": \"litellm_web_search\",
\"description\": \"Buscar en la web información actual\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {\"query\": {\"type\": \"string\", \"description\": \"La consulta de búsqueda\"}},
\"required\": [\"query\"]
}
}
}],
\"tool_choice\": \"auto\"
}'
![\"El](\"https://wec.wiline.com/docs/es/assets/images/websearch-with-ae28b4b9dbd33effc4676a36ce37a4e0.png\")
\nFigura 2. Mismo modelo, misma pregunta, más la herramienta — ahora devuelve una versión concreta\ny fecha de lanzamiento obtenida de la web en vivo. El modelo decidió buscar, WEC ejecutó la consulta,\ny alimentó los resultados antes de responder.
Esa es toda la función: una herramienta en el cuerpo de la solicitud, respuestas actuales saliendo.
\nLa búsqueda web inyecta los resultados en tu aviso, por lo que una llamada con búsqueda cuesta más tokens que\nuna simple (en nuestra prueba, los tokens de aviso pasaron de ~26 a ~2,776). Mantén tool_choice: auto\npara que el modelo solo busque cuando realmente lo necesita — omitirá la búsqueda para preguntas que\nya puede responder.
auto se encarga de eso por ti.Dirígete a un asistente RAG o un chatbot y puede mantenerse actualizado sin que tengas que configurar un\nservicio de búsqueda separado.
\nUn agente que llama a herramientas hace dos cosas muy diferentes: razona (\"Debería buscar en la documentación\") y actúa (realmente llama a la herramienta). Cuando algo sale mal, la primera pregunta siempre es qué capa falló — ¿pensó mal o se rompió la acción? Un registro plano no puede responder eso. Un trazado puede.
\nEn este tutorial, construirás un pequeño agente que llama a herramientas en WEC Inference, lo instrumentarás con Langfuse para que cada paso de razonamiento y cada llamada a la herramienta se conviertan en un nodo inspeccionable, y luego depurarás dos fallos reales del árbol de trazado — incluyendo el peor tipo: una respuesta incorrecta y confiada que nunca lanza un error. Cada comando, error y captura de pantalla a continuación proviene de una ejecución real.
\n\nConstruido en una instancia de WEC con Docker, contra WEC Inference (Qwen3.5-122B) y un Langfuse autoalojado del\ntutorial de observabilidad. Las herramientas del agente incluyen el servicio RAG del\ntutorial de RAG — así que esta pieza une toda la serie. Todas las llamadas al modelo permanecen en WEC; nada sale hacia una API de terceros.
Las líneas punteadas son el punto: cada paso se informa a Langfuse, por lo que el razonamiento del agente y sus acciones se presentan como nodos separados e inspeccionables.
\nRequisitos previos: una instancia de WEC con Docker, una clave API de WEC Inference, un Langfuse en funcionamiento (clave pública + clave secreta, URL del host) y una herramienta que el agente pueda llamar — aquí el servicio RAG /ask. Todos los comandos se ejecutan en ~/agent-tracing.
Regla: nunca instrumentes antes de haber visto el comportamiento en bruto. Así que v1 hace lo mínimo — pregunta al modelo una cuestión con una definición de herramienta, y muestra lo que regresa. Configura el espacio de trabajo y la clave de WEC:
\nmkdir -p ~/agent-tracing && cd ~/agent-tracing
grep '^WEC_API_KEY=' ~/evolution-api/.env > .env
agent.py (v1):
import os, requests
WEC_URL = \"https://inference.wiline.com/v1/chat/completions\"
WEC_API_KEY = os.environ[\"WEC_API_KEY\"]
MODEL = \"Qwen3.5-122B\"
TOOLS = [{
\"type\": \"function\",
\"function\": {
\"name\": \"search_docs\",
\"description\": \"Buscar en la documentación de WEC una respuesta a una pregunta.\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {\"query\": {\"type\": \"string\"}},
\"required\": [\"query\"],
},
},
}]
def call_model(messages):
r = requests.post(WEC_URL,
headers={\"Authorization\": f\"Bearer {WEC_API_KEY}\"},
json={\"model\": MODEL, \"messages\": messages, \"tools\": TOOLS, \"tool_choice\": \"auto\"},
timeout=120)
r.raise_for_status()
return r.json()[\"choices\"][0][\"message\"]
if __name__ == \"__main__\":
msg = call_model([{\"role\": \"user\", \"content\": \"¿Cómo creo una instancia de cómputo en WEC?\"}])
print(\"=== CAPA DE RAZONAMIENTO (lo que pensó) ===\")
print(msg.get(\"reasoning_content\") or \"(ninguno)\")
print(\"\\n=== CAPA DE ACCIÓN (lo que decidió hacer) ===\")
for tc in msg.get(\"tool_calls\") or []:
print(f\"herramienta: {tc['function']['name']} args: {tc['function']['arguments']}\")
Ejecuta en un contenedor (mismo patrón que el resto de la serie):
\nFROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir requests
COPY agent.py .
CMD [\"python\", \"agent.py\"]
services:
agent:
build: .
env_file: .env
docker compose run --rm --build agent
![\"El](\"https://wec.wiline.com/docs/es/assets/images/agent-reasoning-action-56b6f9e7c5b8aef031cd06c04187e291.png\")
\nFigura 1. WEC Inference devuelve las dos capas en una respuesta: reasoning_content\n(el pensamiento) y tool_calls (la decisión). No tenemos que inferir la división — la API nos la entrega.
Qwen3.5-122B devuelve finish_reason: tool_calls con un arreglo tool_calls adecuado, más un campo reasoning_content que contiene la cadena de pensamiento del modelo antes de actuar. Ese campo de razonamiento es exactamente lo que hace visible la separación entre razonamiento y acción más adelante.
v1 decidió buscar pero no lo hizo. Ahora llama realmente a la herramienta (el servicio RAG /ask), alimenta el resultado de vuelta y deja que el modelo escriba la respuesta final. Agrega la herramienta + el bucle:
import json
RAG_URL = \"http://<tu-ip-vm>:8000/ask\" # el servicio RAG = nuestra única herramienta
def search_docs(query):
r = requests.post(RAG_URL, json={\"question\": query}, timeout=120)
r.raise_for_status()
return r.json()[\"answer\"]
def run(user_input):
messages = [{\"role\": \"user\", \"content\": user_input}]
while True:
msg = call_model(messages)
if not msg.get(\"tool_calls\"):
print(\"\\n=== RESPUESTA FINAL ===\\n\" + (msg.get(\"content\") or \"\"))
return msg.get(\"content\")
messages.append({\"role\": \"assistant\", \"content\": msg.get(\"content\") or \"\",
\"tool_calls\": msg[\"tool_calls\"]})
for tc in msg[\"tool_calls\"]:
args = json.loads(tc[\"function\"][\"arguments\"])
print(f\"[razonamiento] {(msg.get('reasoning_content') or '').strip()[:140]}\")
print(f\"[acción] {tc['function']['name']}({args})\")
result = search_docs(args[\"query\"])
print(f\"[resultado de la herramienta] {result[:140]}...\")
messages.append({\"role\": \"tool\", \"tool_call_id\": tc[\"id\"], \"content\": result})
docker compose run --rm --build agent
![\"El](\"https://wec.wiline.com/docs/es/assets/images/agent-loop-b09953660869437421c9222da3f9b135.png\")
\nFigura 2. El bucle completo — el modelo razona, llama a search_docs, obtiene el resultado de RAG y escribe una respuesta fundamentada. Funciona. Pero un terminal que funciona no te dice nada sobre si el razonamiento fue sólido — eso es lo que arreglamos a continuación.
El terminal aplana todo en un solo flujo. Langfuse convierte cada función en un nodo para que puedas ver la estructura. Reutiliza las claves de Langfuse del tutorial de observabilidad (mismo proyecto que tus trazas de RAG):
\ngrep -E '^LANGFUSE_(PUBLIC_KEY|SECRET_KEY|HOST)=' ~/rag-service/.env >> .env
Agrega el SDK (pip install ... langfuse) y decora tres funciones — esa es toda la instrumentación. @observe envuelve una función como un span; as_type=\"generation\" marca las llamadas LLM para que Langfuse capture modelo, tokens y costo:
from langfuse import observe, get_client
@observe(as_type=\"generation\")
def call_model(messages):
...
data = r.json()
get_client().update_current_generation(model=MODEL, usage_details=data.get(\"usage\"))
return data[\"choices\"][0][\"message\"]
@observe()
def search_docs(query):
...
@observe()
def run(user_input):
...
if __name__ == \"__main__\":
run(\"¿Cómo creo una instancia de cómputo en WEC?\")
get_client().flush() # script de corta duración: empujar trazas antes de salir
docker compose run --rm --build agent
Abre Langfuse → Trazado → Trazas. Lo primero que notarás: hay dos trazas por pregunta.
\n![\"La](\"https://wec.wiline.com/docs/es/assets/images/trace-list-3a0d985919db7d12160c4109ab85dede.png\")
\nFigura 3. Trazado distribuido, gratis: la traza run de tu agente y la propia traza ask del servicio RAG son separadas — cada servicio se instrumenta a sí mismo. Ver ambas es cómo sigues una solicitud a través de los límites del servicio.
Abre la más nueva run:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/trace-tree-green-c19c35d6b1ba42189355bdd0e79d96f8.png\")
\nFigura 4. El turno del agente como un árbol: run → call_model (decidir) → search_docs (actuar) → call_model (respuesta). Langfuse también capturó latencia, uso de tokens (801→306) y una puntuación de corrección — todo por tres decoradores.
Haz clic en el primer call_model y abre su salida:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/trace-reasoning-content-c5e9876f6e9a640d45e9f5f54c5594cc.png\")
\nFigura 5. La capa de razonamiento, capturada: reasoning_content (\"Debería buscar en la documentación de WEC…\") se encuentra justo al lado de los tool_calls que produjo. Este es el registro contra el que depuras.
Planta un error realista: la API de RAG espera {\"question\": ...}, pero es natural enviar {\"query\": ...} porque el parámetro de la herramienta se llama query. Una clave incorrecta:
sed -i 's/{\"question\": query}/{\"query\": query}/' agent.py
docker compose run --rm --build agent
Se bloquea:
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/agent-422-crash-af97e2fe3ae5709ec3fe6d5f859095a0.png\")
\nFigura 6. El terminal te da un rastreo de pila — te dice dónde se rompió el código. No te dice si el agente pensó correctamente. Para eso, ve al trazado.
Abre la run fallida y haz clic en el span rojo search_docs:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/trace-error-span-ddca621bf15a8cc64c96371cd6a42e1a.png\")
\nFigura 7. Todo el diagnóstico en una imagen: call_model es verde (el razonamiento fue correcto — eligió correctamente buscar), search_docs es rojo, murió en 0.04s, y el panel muestra el 422 más la carga útil exacta que envió. Un fallo instantáneo es un rechazo, no un tiempo de espera — apuntando directamente a una mala solicitud.
Arregla la línea y confirma el verde:
\nsed -i 's/{\"query\": query}/{\"question\": query}/' agent.py
docker compose run --rm --build agent
![\"El](\"https://wec.wiline.com/docs/es/assets/images/trace-fixed-green-c3b4677676dc40f861fca6dafe1594bb.png\")
\nFigura 8. De vuelta al verde — search_docs tiene éxito y se produce la respuesta final. Diagnosticaste y verificaste la corrección desde el trazado.
Ese fue el fallo ruidoso — se bloqueó, así que lo habrías atrapado eventualmente incluso sin un trazado. El peligroso es el siguiente.
\nLos agentes reales tienen más de una herramienta, y las decisiones interesantes ocurren cuando el modelo elige entre ellas. Agrega una herramienta get_pricing junto a search_docs, y enruta las llamadas a través de una tabla de despacho indexada por el nombre de la herramienta:
TOOLS = [
{\"type\": \"function\", \"function\": {
\"name\": \"search_docs\",
\"description\": \"Buscar en la documentación de WEC preguntas sobre cómo hacer y configurar.\",
\"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}},
{\"type\": \"function\", \"function\": {
\"name\": \"get_pricing\",
\"description\": \"Obtener el precio de un recurso de WEC (por ejemplo, 'instancia de cómputo', 'almacenamiento en bloque', 'inferencia').\",
\"parameters\": {\"type\": \"object\", \"properties\": {\"resource\": {\"type\": \"string\"}}, \"required\": [\"resource\"]}}},
]
PRICES = {
\"instancia de cómputo\": \"$0.03 / hora-vCPU\",
\"almacenamiento en bloque\": \"$0.10 / GB-mes\",
\"inferencia\": \"$0.50 por 1M tokens\",
}
@observe()
def get_pricing(resource):
return PRICES.get(resource.lower().strip(), f\"No se encontró precio para '{resource}'.\")
TOOL_FUNCS = {\"search_docs\": search_docs, \"get_pricing\": get_pricing}
# en run(), despachar por la herramienta que el modelo realmente eligió:
for tc in msg[\"tool_calls\"]:
name = tc[\"function\"][\"name\"]
args = json.loads(tc[\"function\"][\"arguments\"])
print(f\"[acción] {name}({args})\")
result = str(TOOL_FUNCS[name](**args))
messages.append({\"role\": \"tool\", \"tool_call_id\": tc[\"id\"], \"content\": result})
Haz una pregunta de precio (run(\"¿Cuánto cuesta una instancia de cómputo en WEC?\")) y ejecútala. El agente debería elegir get_pricing, no search_docs:
![\"Traza](\"https://wec.wiline.com/docs/es/assets/images/trace-two-tools-ba891f9c0ec4d99aea2e499dcbba3189.png\")
\nFigura 9. Selección genuina de herramientas: dado dos herramientas, el agente eligió get_pricing y respondió $0.03/hora-vCPU, Corrección 1.00. La elección en sí misma es ahora algo que puedes ver en el trazado.
Ahora un error que no se bloquea. Alguien refactoriza el despacho y codifica en duro la antigua herramienta única, olvidando la nueva — así que cada llamada ejecuta search_docs sin importar lo que eligió el modelo:
sed -i 's/result = str(TOOL_FUNCS\\[name\\](\\*\\*args))/result = str(search_docs(list(args.values())[0])) # ERROR/' agent.py
docker compose run --rm --build agent
[action] get_pricing({'resource': 'instancia de cómputo'})
=== RESPUESTA FINAL ===
Basado en la información de precios disponible, la categoría de instancia de cómputo más cara en WEC es $1,586.77. ...
Lee eso cuidadosamente. El modelo eligió get_pricing (correcto). La respuesta es confiada, detallada — y completamente incorrecta (el precio real es $0.03/hora-vCPU). No hay error, ni rastreo. Un registro se vería perfectamente saludable. Este es el modo de fallo que se envía a producción y miente silenciosamente a los usuarios.
El trazado es lo único que lo atrapa. Abre la run:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/trace-silent-failure-162a3ce9394bad7caca0e908be683b67.png\")
\nFigura 10. Tres indicios que un registro no puede mostrar: (1) el span ejecutado es search_docs — no hay span de get_pricing, a pesar de que el modelo lo eligió: decisión ≠ acción; (2) el nodo de razonamiento puntuó Corrección 0.00 — el juez LLM marcó automáticamente la respuesta incorrecta; (3) la salida muestra al modelo confundido por un resultado de herramienta que no coincidía con lo que pidió. Arregla el despacho de vuelta a TOOL_FUNCS[name](**args) y el precio es correcto nuevamente.
Instrumentaste un agente que llama a herramientas para que su razonamiento y sus acciones sean nodos de trazado separados e inspeccionables — y depuraste dos fallos reales desde el trazado: el ruido del bloqueo y la respuesta silenciosa, confiada pero incorrecta que ningún rastreo de pila revelaría jamás.
get_client().flush() antes de que el proceso termine (ya está en v3).search_docs faltante. Solo las funciones decoradas con @observe se convierten en nodos —\ndecora la función, no el sitio de llamada.usage_details=data.get(\"usage\") a través de\nupdate_current_generation; sin ello, Langfuse no puede calcular el costo.tool_calls del modelo (lo que eligió)\ncontra los spans ejecutados (lo que realmente se ejecutó). Un desajuste es un error de despacho/ruteo — y una puntuación de corrección en el trazado lo señalará automáticamente.Ahora puedes ver a un agente pensar, actuar y fallar silenciosamente — y atraparlo. Apunta la misma instrumentación a un agente real de múltiples pasos, agrega puntuación de corrección automatizada en cada trazado, y tendrás una observabilidad de producción que revela fallos silenciosos antes de que lo hagan tus usuarios.
\ncd ~/agent-tracing && docker compose down --rmi local
![\"WhatsApp\"](\"https://wec.wiline.com/docs/es/assets/images/whatsapp_logo-cc34546fcff90d36128c7230c48c496f.png\"){kind=logo}
++![\"Evolution\"](\"https://wec.wiline.com/docs/es/assets/images/0_hT2ECga7Z67dEbYz-62f9ab60d339ae8868fee46475e505bc.png\")
La mayoría de las guías de \"autoalbergar un asistente de IA para WhatsApp\" se detienen en \"el contenedor se inició\". Esta va hasta el final: despliegas una puerta de enlace de WhatsApp programable real (API de Evolution), luego escribes el puente tú mismo — las ~50 líneas que convierten un mensaje entrante en una respuesta de LLM y la envían de vuelta. Ese puente (webhook → modelo → respuesta) es el patrón reutilizable detrás de cada integración de chat-AI: SMS, Slack, Telegram, voz — cambia el canal, la forma es idéntica.
\nY porque esto es una construcción real, encontramos — y solucionamos — cada detalle: una imagen que movió a los editores, un bucle de versión de Baileys, un bucle de respuesta infinito, spam en grupos de chat, la nueva dirección LID de WhatsApp, y una genuina pared de entrega que la mayoría de los tutoriales pretenden que no existe. Cada comando, error y salida a continuación es de una ejecución real.
\n\nEvolution se vincula a un número de WhatsApp como un dispositivo compañero (como WhatsApp Web) — el bot actúa como esa cuenta y puede leer cada DM y grupo que recibe. Para una demostración en un número que controlas está bien; para cualquier cosa real, usa un número dedicado. Y consulta la limitación de entrega al final antes de construir esto en producción.
Cuatro contenedores: Evolution + su Postgres + Redis, y el puente que escribirás. El puente es el objetivo principal — todo lo demás es estándar.
\nRequisitos previos: una instancia WEC con Docker + Compose, una clave de API de Inferencia WEC (Inferencia → Claves de API), un número de WhatsApp para la demostración, y ~2 GB de espacio libre en disco.
\nEvolution necesita su propio Postgres y Redis. Le damos un conjunto dedicado en una red interna y exponemos solo el puerto de la API (8080). docker-compose.yml:
services:
evolution-api:
image: evoapicloud/evolution-api:v2.2.3
restart: unless-stopped
ports:
- \"8080:8080\"
env_file: .env
volumes:
- evolution_instances:/evolution/instances
depends_on: [evolution-postgres, evolution-redis]
logging:
driver: json-file
options: { max-size: \"50m\", max-file: \"3\" }
evolution-postgres:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_USER: evolution
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: evolution
volumes:
- evolution_pgdata:/var/lib/postgresql/data
evolution-redis:
image: redis:7
restart: unless-stopped
volumes:
- evolution_redis:/data
volumes:
evolution_instances:
evolution_pgdata:
evolution_redis:
El bloque logging: limita los logs del contenedor a 3×50 MB. Si lo omites, un contenedor ruidoso puede llenar el disco y hacer que la máquina se caiga — una lección aprendida de la manera difícil en esta VM. Configúralo antes de necesitarlo.
El archivo .env (secretos generados, URIs de conexión y — lo más importante — una versión de WhatsApp-Web de Baileys fijada):
cd ~/evolution-api && cat > .env << EOF
AUTHENTICATION_API_KEY=$(openssl rand -hex 24)
SERVER_URL=http://<tu-ip-vm>:8080
POSTGRES_PASSWORD=$(openssl rand -hex 16)
DATABASE_ENABLED=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:\\${POSTGRES_PASSWORD}@evolution-postgres:5432/evolution?schema=public
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://evolution-redis:6379/0
CACHE_REDIS_PREFIX_KEY=evolution
CACHE_LOCAL_ENABLED=false
QRCODE_LIMIT=30
EOF
Levántalo:
\ndocker compose up -d
sleep 15
curl -s http://localhost:8080 | jq
{
\"status\": 200,
\"message\": \"¡Bienvenido a la API de Evolution, está funcionando!\",
\"version\": \"2.2.3\",
...
}
![\"La](\"https://wec.wiline.com/docs/es/assets/images/wa-evolution-up-680a7f5fe9e4a450cacf33f1df5ed6f7.png\")
\nFigura 1. La pila está activa: Evolution responde en :8080 con su versión y estado.
(1) El editor se mudó. La imagen a la que la mayoría de las guías hacen referencia — atendai/evolution-api — ahora devuelve \"acceso denegado al pull / el repositorio no existe.\" La imagen actual es evoapicloud/evolution-api. La lista de etiquetas del antiguo repositorio aún se resuelve, lo que te envía por un camino sin salida; confirma con un pull fresco de hello-world que no está limitando la tasa.\n(2) Fija una etiqueta real. v2.1.1 (de un blog popular) nunca fue publicada — verifica https://hub.docker.com/v2/repositories/evoapicloud/evolution-api/tags y fija una que exista (usamos v2.2.3).
Establece tu clave de API como una variable de shell (cada solicitud la necesita en un encabezado apikey:):
APIKEY=$(grep '^AUTHENTICATION_API_KEY=' .env | cut -d= -f2)
Crea la instancia:
\ncurl -s -X POST http://localhost:8080/instance/create \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" \\
-d '{\"instanceName\":\"wec-demo\",\"integration\":\"WHATSAPP-BAILEYS\",\"qrcode\":true}' | jq '.instance'
Luego abre el Administrador integrado en http://<tu-ip-vm>:8080/manager, ingresa tu URL de servidor + clave de API, haz clic en wec-demo, y escanea el QR desde WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo. Confirma que está conectado:
curl -s http://localhost:8080/instance/fetchInstances -H \"apikey: $APIKEY\" \\
| jq '.[] | {name, connectionStatus}'
{ \"name\": \"wec-demo\", \"connectionStatus\": \"open\" }
![\"El](\"https://wec.wiline.com/docs/es/assets/images/wa-manager-connected-d91fda82b98c6238d0d747b47636645b.png\")
\nFigura 2. El panel de control del Administrador de Evolution una vez que la instancia se vincula: Conectado, con conteos de contactos, chats y mensajes en vivo.
Si la instancia nunca sale de conectando y los logs muestran ChannelStartupService reinicializándose cada pocos segundos con una línea Baileys version env: 2,3000,..., la versión de WhatsApp-Web fijada está obsoleta y WhatsApp rechaza el apretón de manos antes de que se genere un QR. Obtén la versión actual y fíjala, luego recrea:
curl -s \"https://raw.githubusercontent.com/WhiskeySockets/Baileys/master/src/Defaults/baileys-version.json\"
# {\"version\":[2,3000,1035194821]}
echo \"CONFIG_SESSION_PHONE_VERSION=2.3000.1035194821\" >> .env
docker compose up -d --force-recreate evolution-api
Ahora la parte que realmente escribes. Regla: nunca conectes la lógica antes de haber visto los datos reales. Así que v1 no hace nada más que imprimir lo que Evolution envía.
\nEl puente se ejecuta como otro contenedor en el mismo Compose, por lo que Evolution lo alcanza por nombre (http://bridge:8090) y el puente alcanza a Evolution en http://evolution-api:8080. Crea bridge/main.py:
from fastapi import FastAPI, Request
app = FastAPI()
@app.post(\"/webhook\")
async def webhook(request: Request):
data = await request.json()
print(\"=== WEBHOOK RECIBIDO ===\", flush=True)
print(data, flush=True)
return {\"received\": True}
flush=True es importanteSin él, la salida de print se almacena en búfer y nunca aparece en docker compose logs — estarás mirando un log vacío convencido de que está roto.
bridge/Dockerfile:
FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir fastapi uvicorn requests
COPY main.py .
CMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8090\"]
Agrega el servicio a docker-compose.yml (dentro de services:), luego constrúyelo:
bridge:
build: ./bridge
restart: unless-stopped
env_file: .env
depends_on: [evolution-api]
logging:
driver: json-file
options: { max-size: \"10m\", max-file: \"3\" }
docker compose up -d --build bridge
Ahora registra el webhook para que Evolution envíe mensajes al puente:
\ncurl -s -X POST \"http://localhost:8080/webhook/set/wec-demo\" \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" \\
-d '{\"webhook\":{\"enabled\":true,\"url\":\"http://bridge:8090/webhook\",\"webhookByEvents\":false,\"events\":[\"MESSAGES_UPSERT\"]}}' | jq '.enabled, .url'
Sigue los logs (docker compose logs -f bridge) y envíate un mensaje de WhatsApp. La carga real aparece:
{'event': 'messages.upsert', 'instance': 'wec-demo',
'data': {'key': {'remoteJid': '123456789012345@lid', 'fromMe': False, 'id': '...'},
'pushName': 'Contacto de Prueba',
'message': {'conversation': 'Oii'},
'messageType': 'conversation'},
'sender': '5511988887777@s.whatsapp.net', ...}
Tres cosas que ahora sabemos — y cada una impulsa el código siguiente:
\ndata.message.conversation (plano) o data.message.extendedTextMessage.text (citado)data.key.fromMe — True para nuestros propios mensajes (el guardia de bucle)remoteJid termina en @lid — el identificador de privacidad de WhatsApp, no un número de teléfono (esta es una saga; Paso 5)Dale al puente la clave de Inferencia WEC para que pueda llamar al modelo:
\necho \"WEC_API_KEY=<tu-clave-de-inferencia-wec>\" >> ~/evolution-api/.env
Ahora la lógica — main.py v2:
import os, requests
from fastapi import FastAPI, Request
app = FastAPI()
EVOLUTION_URL = \"http://evolution-api:8080\"
INSTANCE = \"wec-demo\"
EVOLUTION_APIKEY = os.environ[\"AUTHENTICATION_API_KEY\"]
WEC_API_KEY = os.environ[\"WEC_API_KEY\"]
WEC_URL = \"https://inference.wiline.com/v1/chat/completions\"
MODEL = \"Qwen2.5-3B-Instruct\"
def ask_llm(text: str) -> str:
r = requests.post(WEC_URL,
headers={\"Authorization\": f\"Bearer {WEC_API_KEY}\"},
json={\"model\": MODEL, \"messages\": [{\"role\": \"user\", \"content\": text}]},
timeout=60)
r.raise_for_status()
return r.json()[\"choices\"][0][\"message\"][\"content\"]
def send_whatsapp(number: str, text: str):
r = requests.post(f\"{EVOLUTION_URL}/message/sendText/{INSTANCE}\",
headers={\"apikey\": EVOLUTION_APIKEY, \"Content-Type\": \"application/json\"},
json={\"number\": number, \"text\": text}, timeout=60)
print(f\"ENVIAR -> {r.status_code}\", flush=True)
@app.post(\"/webhook\")
async def webhook(request: Request):
data = (await request.json()).get(\"data\", {})
key = data.get(\"key\", {})
if key.get(\"fromMe\"): # (1) GUARDIA DE BUCLE
return {\"skipped\": \"fromMe\"}
msg = data.get(\"message\", {}) # (2) extraer texto
text = msg.get(\"conversation\") or msg.get(\"extendedTextMessage\", {}).get(\"text\")
if not text:
return {\"skipped\": \"no text\"}
to = key.get(\"remoteJid\")
print(f\"ENTRADA {to}: {text}\", flush=True)
answer = ask_llm(text) # (3) pensar
send_whatsapp(to, answer) # (4) responder
print(f\"SALIDA {to}: {answer[:60]}...\", flush=True)
return {\"ok\": True}
La única línea que los principiantes siempre pasan por alto es (1) el guardia de bucle. Cuando el puente envía una respuesta, ese mensaje saliente dispara otro webhook MESSAGES_UPSERT con fromMe: true — sin el guardia, el puente se responde a sí mismo, para siempre. Reconstruye:
docker compose up -d --build bridge
![\"El](\"https://wec.wiline.com/docs/es/assets/images/wa-bridge-logs-53cb3cf64a3d62d69794ee3a0bf3742b.png\")
\nFigura 3. v2 en acción: un DM llega, el modelo responde, la respuesta se envía.
Ahora responde a DMs. Pero observa lo que sucede a continuación.
\nSigue los logs con el bot en vivo y verás que intenta responder a cada grupo en el que estás, incluidos grupos de promoción/spam, y Evolution se agota al enviarles — errores de inundación:
\nENTRADA 120363040812472138@g.us: *ALÔ CORREDORES 🏃 ... pechin.co/135449*
requests.exceptions.ReadTimeout: HTTPConnectionPool(host='evolution-api', port=8080): Read timed out.
Una cuenta compañera recibe todo. Solución: responder solo a DMs — los grupos terminan en @g.us:
to = key.get(\"remoteJid\", \"\")
if to.endswith(\"@g.us\") or \"broadcast\" in to: # Solo DMs
return {\"skipped\": \"not a DM\"}
Ahora la pared más sutil. Con los grupos filtrados, un DM real llega — pero la respuesta es rechazada:
\n{\"status\":400,\"error\":\"Bad Request\",\"response\":{\"message\":[
{\"exists\":false,\"jid\":\"123456789012345@lid\",\"name\":\"Contacto de Prueba\",\"number\":\"123456789012345@lid\"}]}}
![\"Evolution](\"https://wec.wiline.com/docs/es/assets/images/wa-lid-400-84cc0430abac7bdd5aa6d29cf1c100b5.png\")
\nFigura 4. La pared LID en los logs: el DM entrante llega como @lid, y la respuesta es rechazada con exists:false.
exists: false. Esta es la dirección LID de WhatsApp (un cambio de privacidad de 2025): los DMs entrantes llegan con un identificador @lid, y no puedes enviar de vuelta a un @lid — Evolution necesita el verdadero JID de teléfono @s.whatsapp.net. Sin embargo, el almacén de contactos de Evolution tiene ambos:
curl -s -X POST \"http://localhost:8080/chat/findContacts/wec-demo\" \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" -d '{}' \\
| jq '[.[] | select(.pushName==\"Contacto de Prueba\")]'
[ { \"remoteJid\": \"123456789012345@lid\", \"pushName\": \"Contacto de Prueba\" },
{ \"remoteJid\": \"5511999999999@s.whatsapp.net\", \"pushName\": \"Contacto de Prueba\" } ]
![\"findContacts](\"https://wec.wiline.com/docs/es/assets/images/wa-findcontacts-275c01bee94ec0da990f2cdd0ec6acf2.png\")
\nFigura 5. Evolution almacena ambas identidades para la misma persona — el @lid y el verdadero JID de teléfono. Esa es la clave para resolver la dirección de respuesta.
Así que resolvemos el @lid al número de teléfono antes de responder. Agrega un resolvedor y úsalo:
def resolve_number(remote_jid: str, push_name: str):
if remote_jid.endswith(\"@s.whatsapp.net\"):
return remote_jid.split(\"@\")[0]
# LID: encontrar el número real del contacto haciendo coincidir el nombre
contacts = requests.post(f\"{EVOLUTION_URL}/chat/findContacts/{INSTANCE}\",
headers={\"apikey\": EVOLUTION_APIKEY, \"Content-Type\": \"application/json\"},
json={}, timeout=30).json()
for c in contacts:
if c.get(\"pushName\") == push_name and c.get(\"remoteJid\", \"\").endswith(\"@s.whatsapp.net\"):
return c[\"remoteJid\"].split(\"@\")[0]
return None
En el manejador, resuelve antes de enviar:
\n number = resolve_number(to, data.get(\"pushName\", \"\"))
if not number:
return {\"skipped\": \"unresolved lid\"}
...
send_whatsapp(number, answer)
Ahora ENVIAR -> 201. (Hacer coincidir por nombre es un heurístico — dos contactos que comparten un nombre colisionarían; la producción mantiene un mapa adecuado LID→teléfono. Pero funciona, y es el estado honesto del soporte LID de Evolution en v2.2.3.)
Los LLM emiten Markdown (**negrita**, [texto](url)), pero WhatsApp tiene su propio formato: la negrita es *asterisco simple*, y los enlaces de Markdown no se renderizan. Así que **Compute** aparece con asteriscos literales. Traduce la salida del modelo antes de enviar, y agrega las fuentes del RAG como URLs simples:
import re
def to_whatsapp(md: str) -> str:
md = re.sub(r\"\\*\\*(.+?)\\*\\*\", r\"*\\1*\", md) # **negrita** -> *negrita*
md = re.sub(r\"\\[([^\\]]+)\\]\\((https?://[^)]+)\\)\", r\"\\1 (\\2)\", md) # [t](url) -> t (url)
md = re.sub(r\"(?m)^#{1,6}\\s*\", \"\", md) # eliminar encabezados #
return md
Verificado contra una respuesta real — exactamente lo que WhatsApp renderizará:
\nPara crear una instancia de computación en WiLine Edge Cloud (WEC), sigue estos pasos:
1. Inicia sesión en WiLine Edge Cloud.
2. En la barra lateral, haz clic en *Compute*.
3. Selecciona *Instances*.
4. Haz clic en el asistente \"Launch Virtual Machine\" para comenzar el proceso de despliegue.
_Fuentes:_
https://wec.wiline.com/docs/cloud_portal/platform/compute/instances/compute_instance/
![\"La](\"https://wec.wiline.com/docs/es/assets/images/wa-formatted-output-766cfd620ca72685d8f37110da283d56.png\")
\nFigura 6. La salida del modelo después de to_whatsapp(): negrita con asterisco simple, enlaces simples, fuentes añadidas.
Todo hasta ahora usa el modelo en bruto, así que una pregunta de WEC obtiene una respuesta general. Para hacer que responda desde tu documentación, cambia ask_llm para llamar al servicio RAG de la serie de evals — una función, nada más cambia:
RAG_URL = \"http://<tu-ip-vm>:8000/ask\"
def ask_llm(text: str) -> str:
r = requests.post(RAG_URL, json={\"question\": text}, timeout=120)
r.raise_for_status()
d = r.json()
answer = to_whatsapp(d[\"answer\"])
sources = d.get(\"sources\", [])[:2]
if sources:
answer += \"\\n\\n_Fuentes:_\\n\" + \"\\n\".join(sources)
return answer
Ese es el beneficio del patrón de puente: cambia el cerebro, mantén la plomería. Ahora WhatsApp responde a preguntas de WEC desde la documentación real, con fuentes:
\n![\"WhatsApp](\"https://wec.wiline.com/docs/es/assets/images/wa-bridge-reply-bf0eaa9a06721ee1396cbf44fd96ae3a.png\")
\nFigura 7. Un mensaje real en → el puente → RAG sobre la documentación de WEC → una respuesta fundamentada entregada en WhatsApp, fuentes incluidas.
Has autoalbergado una puerta de enlace programable de WhatsApp y escribiste el puente que lo convierte en un asistente de IA — webhook entrante, modelo saliente, respuesta de vuelta — fundamentado en tu propia documentación.
Aquí está la parte que otros tutoriales no te dirán. Incluso con ENVIAR -> 201, las respuestas a una cuenta migrada a LID frecuentemente llegan como \"Esperando este mensaje\" en el teléfono del destinatario — WhatsApp aceptó el texto cifrado pero ningún dispositivo puede descifrarlo. Es una limitación conocida del dispositivo compañero de Baileys, y el despliegue de LID de WhatsApp lo empeora.
Lo que observamos, honestamente:
\n\"Esperando este mensaje\" regresa — aunque cada envío aún informa 201.Así que el puente es correcto de extremo a extremo; el transporte no oficial de Baileys es el eslabón débil. Si estás construyendo esto para algo real:
\nEvolution brilla para automatización saliente a números que controlas (notificaciones, alertas, flujos). Como asistente de IA bidireccional en una cuenta personal de LID, trata la entrega como un esfuerzo mejor.
\nacceso denegado al pull en atendai/evolution-api → imagen movida a evoapicloud/evolution-api.conectando, bucle de reinicio → versión de Baileys obsoleta; fija CONFIG_SESSION_PHONE_VERSION.fromMe.@g.us; responde solo a DMs.ENVIAR -> 400 exists:false ...@lid → resuelve el LID al JID de teléfono a través de findContacts.**asteriscos** en respuestas → traduce Markdown al formato de WhatsApp.cd ~/evolution-api && docker compose down # agrega -v para también borrar la DB/sesión
Desvincula el dispositivo en WhatsApp → Dispositivos vinculados si has terminado.
\nHas construido el patrón de puente reutilizable — webhook → resolver → modelo → respuesta. Apúntalo a un cerebro diferente, a un canal diferente, o agrega herramientas. Si deseas un agente de IA en WhatsApp sin las advertencias de Baileys, el canal nativo de WhatsApp de OpenClaw es el camino gestionado; para respuestas fundamentadas en documentos, la serie de evals y observabilidad construye el servicio RAG en el que se conecta este tutorial.
", "url": "https://wec.wiline.com/docs/es/tutorials/whatsapp-ai-assistant-evolution-api/", "title": "Crea un asistente de IA para WhatsApp desde cero con Evolution y la API de WEC", "summary": "Autoalberga una puerta de enlace programable de WhatsApp (API de Evolution) y escribe el puente de ~50 líneas que lo convierte en un asistente de IA: webhook entrante, LLM saliente, respuesta de vuelta. Cada detalle es real: la imagen que movió a los editores, el bucle de la versión de Baileys, el guardia de bucle, el spam en grupos, la dirección LID de WhatsApp y la pared de entrega de la que nadie te advierte.", "date_modified": "2026-07-21T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "self-hosting", "whatsapp", "evolution-api", "docker", "inference" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/add-whatsapp-channel-openclaw/", "content_html": "![\"OpenClaw\"](\"https://wec.wiline.com/docs/es/assets/images/openclaw-wordmark-003352a1a7f02afc3bd877ae6f2dc175.png\")
+Telegram (Parte 3) le dio a tu agente un bot.\nWhatsApp le da una línea telefónica — la aplicación que ~3 mil millones de personas ya usan, accesible sin fricción. Una advertencia que vale la pena entender desde el principio: WhatsApp no tiene cuenta de bot, así que OpenClaw se vincula a un número real como un dispositivo compañero (como WhatsApp Web) y el agente actúa como esa cuenta. Cada comando y error a continuación proviene de una ejecución real.
\n\nCualquiera envía un mensaje al número; la puerta de enlace — vinculada como un dispositivo compañero — lo procesa a través de tu modelo y responde desde el número mismo. Sin puertos de entrada, sin cuenta de bot.
\n\nRequisitos previos: Partes 1–4 completadas (OpenClaw en ~/openclaw), una cuenta de WhatsApp en tu\nteléfono, ~1 GB de espacio libre en disco. Todos los comandos se ejecutan en ~/openclaw.
OpenClaw trata las aplicaciones de mensajería como canales; WhatsApp es uno de primera clase:
\ndocker compose run --rm openclaw-cli channels add --channel whatsapp
Plugin de WhatsApp instalado
Cuenta de WhatsApp \"default\" añadida.
requires plugin API >=2026.7.1? Estás en una versión anterior de OpenClaw — actualiza primero.El canal de WhatsApp es un plugin restringido a versiones más nuevas:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/wa-version-wall-db236509ca6e250b19147327473e0932.png\")
\nFigura 1. La pared de versión — el plugin de WhatsApp necesita OpenClaw ≥2026.7.1.
Haz una copia de seguridad, descarga, recrea y confirma que tus canales existentes sobrevivieron (:latest no\nse actualiza automáticamente — debes descargar deliberadamente):
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d)
docker compose pull openclaw-gateway
docker compose run --rm openclaw-cli --version # espera 2026.7.1+
docker compose up -d --force-recreate openclaw-gateway
docker compose run --rm openclaw-cli channels status # Telegram debería seguir conectado
![\"La](\"https://wec.wiline.com/docs/es/assets/images/wa-version-check-b1b98be0f2990d46e5686130b2722d3b.png\")
\nFigura 2. Después de descargar, la imagen informa 2026.7.1 — se cumple el requisito.
Luego vuelve a ejecutar el channels add anterior.
Verifica el estado y el canal está detenido con un error críptico:
\n![\"WhatsApp](\"https://wec.wiline.com/docs/es/assets/images/wa-trust-error-7a8033b008450d82190f783b79998f71.png\")
\nFigura 3. detenido — un plugin no confiable no puede usar openKeyedStore, por lo que el canal no se iniciará.
Esa es una característica de seguridad: OpenClaw aísla los plugins de terceros, y uno no confiable no puede usar openKeyedStore (el almacenamiento que WhatsApp necesita para su sesión). Confía en él —\nincluye cualquier otro plugin no empaquetado que ya esté cargando (aquí codex) para que no lo bloquees\n— y recrea:
docker compose run --rm openclaw-cli config set \\
--batch-json '[{\"path\":\"plugins.allow\",\"value\":[\"codex\",\"whatsapp\"]}]'
docker compose up -d --force-recreate openclaw-gateway
docker compose run --rm openclaw-cli channels status
![\"plugins.allow](\"https://wec.wiline.com/docs/es/assets/images/wa-trust-fix-503842c5815cf95dc4bde07dc3b4a6ee.png\")
\nFigura 4. Confiado — plugins.allow ahora lista whatsapp (y codex).
El reinicio es importante — la puerta de enlace lee plugins.allow antes de inicializar el\nplugin. Ahora está en funcionamiento:
![\"WhatsApp](\"https://wec.wiline.com/docs/es/assets/images/wa-connected-d4ec6a75486c355d24570487f62305c8.png\")
\nFigura 5. En vivo — WhatsApp funcionando, conectado, saludable, y Telegram sigue activo.
docker compose run --rm openclaw-cli channels login
Escanea el QR del terminal desde WhatsApp → Configuración → Dispositivos Vinculados → Vincular un Dispositivo.
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/wa-qr-544d7332e052ce0469c77d7e60fec42a.png\")
\nFigura 6. Escanea para vincular; ✅ Vinculado después del reinicio maneja la reconexión del código 515.
código 515 es normalWhatsApp obliga a una reconexión justo después del emparejamiento; OpenClaw lo maneja automáticamente. Este\nes exactamente el lugar donde las configuraciones manuales se quedan atrapadas en un bucle — aquí simplemente funciona.
Desde otro teléfono, envía un mensaje al número:
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/wa-reply-08f4125cb353af3cff9a2418928be7ec.png\")
\nFigura 7. Una pregunta enviada, la respuesta del agente — enviada desde el número, como la cuenta.
Responde — pero nota que responde desde tu número, como tú. Eso es el modo compañero:\nel agente es la cuenta. Genial para un asistente personal, y la razón de la advertencia\na continuación.
\nTu agente de OpenClaw responde en WhatsApp — de forma nativa, sin puente, sin cuenta de bot.
Procesa cada DM y grupo que recibe la cuenta (Escuchando ... DM + todos los grupos). Para cualquier cosa real: vincula un número dedicado (una SIM prepago barata — los números virtuales son a menudo rechazados), y establece una lista de permitidos antes de exponerlo.
Estaciona el canal cuando termines de probar (Telegram sigue funcionando; tu enlace permanece guardado):
\ndocker compose run --rm openclaw-cli config set \\
--batch-json '[{\"path\":\"channels.whatsapp.accounts.default.enabled\",\"value\":false}]'
docker compose up -d --force-recreate openclaw-gateway
openKeyedStore solo está disponible para plugins confiables — el canal se instala pero permanece\ndetenido. Agrega el id a plugins.allow y recrea la puerta de enlace (Paso 2). Un cambio de configuración en vivo no es suficiente una vez que ya ha fallado al iniciar.código 515 — reinicio normal después del emparejamiento. Si nunca se estabiliza, elimina\nentradas obsoletas en WhatsApp → Dispositivos Vinculados y escanea un QR nuevo.Parte 5 completada — tu agente llega a Telegram y WhatsApp desde una caja privada y reforzada.
\ndocker compose run --rm openclaw-cli channels remove --channel whatsapp
docker compose restart openclaw-gateway
Y desvincula el dispositivo en WhatsApp → Dispositivos Vinculados si has terminado.
", "url": "https://wec.wiline.com/docs/es/tutorials/add-whatsapp-channel-openclaw/", "title": "Agregar un canal de WhatsApp a OpenClaw", "summary": "Coloca tu agente autoalojado en WhatsApp. Agrega el canal, confía en el plugin, escanea un QR — y entiende por qué un enlace de compañero hace que el agente actúe como tu cuenta. Cada comando y error de una ejecución real.", "date_modified": "2026-07-20T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "self-hosting", "openclaw", "whatsapp", "chatbot" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/deepeval-regression-testing-wiline-inference/", "content_html": "Nuestro análisis de economía de tokens de GPT-5.6 terminó con un desafío:\nlas promesas de referencia son una hipótesis, no una razón — ejecuta la evaluación en tu carga de trabajo antes de que\ncreas en un reclamo de \"menos tokens por tarea\". Este tutorial es nosotros siguiendo nuestro propio consejo.
\nTomamos el asistente de documentos RAG de parte 5,\nlo envolvemos en una suite de regresión DeepEval — en contenedor, juzgada por gemma4 en la API de\nInferencia WEC, sin dependencia de OpenAI — y luego usamos esa suite para responder a una pregunta genuinamente abierta:\n¿deberíamos cambiar el modelo de generación del servicio? Qwen2.5-3B-Instruct (actual) vs\ngemma4 (candidato), tasa de aprobación y tokens por tarea, medidos cara a cara.
Spoiler: la evaluación nos salvó de una migración innecesaria. Y en el camino encontramos cuatro fallos reales\nde producción: un espiral mortal por disco lleno, una condición de carrera en el arranque, una trampa de variable de Docker Compose\nque evaluó silenciosamente el modelo incorrecto, y la solución que hace que esa clase de\nerror sea imposible. Cada comando, número y error a continuación proviene de una ejecución real.
\n\nTres decisiones de diseño desde el principio:
\ndocker compose run eval en ambos lugares. (Nuestro primer intento fue un\nvenv. Murió por un disco lleno antes de instalar nada; consulta Solución de problemas.)tests.csv de promptfoo incrusta cada\nhecho de referencia dentro de una cadena llm-rubric — una expresión regular lo extrae. Tus datos de evaluación\nsobreviven a tu marco de evaluación.rag-api respondiendo en :8000, eval/tests.csv presente).df -h / ahora. El nuestro leía 100% y la historia de por qué\nestá en Solución de problemas.Nunca evalúes un servicio que no hayas probado manualmente primero:
\ncurl -s -X POST localhost:8000/ask \\
-H \"Content-Type: application/json\" \\
-d '{\"question\": \"¿Cómo creo una instancia de cómputo en WEC?\"}' | python3 -m json.tool
![\"El](\"https://wec.wiline.com/docs/es/assets/images/deepeval-smoke-test-98290b8dda1f2a3f5e57a82fa43c2dfa.png\")
\nFigura 1. El sistema bajo prueba, vivo: /ask responde del corpus de documentos de WEC y cita\nsus fuentes. Nunca evalúes un servicio que no hayas probado manualmente primero.
eval/Dockerfile:
FROM python:3.12-slim
WORKDIR /eval
RUN pip install --no-cache-dir deepeval==3.*
# El código de la suite se monta en tiempo de ejecución para que las ediciones no necesiten una reconstrucción
CMD [\"deepeval\", \"test\", \"run\", \"test_rag_regression.py\"]
Agrega el servicio a docker-compose.yml dentro del bloque services: (el archivo de la parte 5 termina\ncon una sección volumes: de nivel superior — agregar ciegamente coloca tu servicio en el bloque incorrecto;\ndocker compose config --quiet lo detecta):
eval:
build: ./eval
profiles: [\"eval\"]
env_file: .env
environment:
RAG_API_URL: http://rag-api:8000
volumes:
- ./eval:/eval
depends_on:
- rag-api
profiles: [\"eval\"] lo mantiene fuera de un docker compose up normal — solo se ejecuta cuando lo pides.\nConstruyelo:
docker compose --profile eval build eval
![\"docker](\"https://wec.wiline.com/docs/es/assets/images/deepeval-eval-build-58810296ef048e28edf1a9f90735d2eb.png\")
\nFigura 2. El ejecutor de evaluación se construye en ~42s: python:3.12-slim más DeepEval 3.x. Esta imagen exacta\nes la que CI ejecuta más tarde — sin venv, sin desviaciones.
Las métricas de LLM-como-juez de DeepEval quieren una clave de OpenAI. No tenemos una y no queremos una.\neval/wec_judge.py:
\"\"\"Juez personalizado de DeepEval respaldado por WiLine Inference (compatible con OpenAI).\"\"\"
import os
from openai import OpenAI
from deepeval.models.base_model import DeepEvalBaseLLM
WEC_BASE_URL = os.getenv(\"WEC_BASE_URL\", \"https://inference.wiline.com/v1\")
class WECJudge(DeepEvalBaseLLM):
def __init__(self, model: str | None = None):
self.model_name = model or os.getenv(\"JUDGE_MODEL\", \"gemma4\")
self.client = OpenAI(
base_url=WEC_BASE_URL,
api_key=os.environ[\"WEC_API_KEY\"],
)
def load_model(self):
return self.client
def generate(self, prompt: str) -> str:
response = self.client.chat.completions.create(
model=self.model_name,
messages=[{\"role\": \"user\", \"content\": prompt}],
temperature=0,
)
return response.choices[0].message.content
async def a_generate(self, prompt: str) -> str:
return self.generate(prompt)
def get_model_name(self):
return f\"WEC/{self.model_name}\"
Prueba que responde desde dentro de la red de compose antes de construir nada sobre ello:
\ndocker compose --profile eval run --rm eval \\
python -c \"from wec_judge import WECJudge; j = WECJudge(); print('el juez dice:', j.generate('Responde exactamente: juez WEC en línea'))\"
el juez dice: juez WEC en línea
![\"Verificación](\"https://wec.wiline.com/docs/es/assets/images/deepeval-judge-online-c5844beb37c759e19f698f4ea927ec8c.png\")
\nFigura 3. \"juez WEC en línea\" — gemma4 respondiendo a través del contenedor, en la misma red de compose que el servicio que juzgará. Sin clave de OpenAI en ninguna parte de la pila.
Una advertencia honesta que llevamos a través del resto de este tutorial: en la comparación de modelos más adelante,\ngemma4 es tanto juez como concursante. La mitigación es estructural: el juez solo compara\nrespuesta frente a hecho de referencia, nunca \"qué modelo escribió esto\" — y observamos sus veredictos en los\ncasos conocidos difíciles para favoritismo. (No mostró ninguno: cada caso en el que falló gemma4 es un caso en el que también falla Qwen.)
\nPuedes apuntar las métricas juzgadas por LLM de DeepEval a cualquier punto final compatible con OpenAI. Tus veredictos de evaluación — preguntas, respuestas, razonamiento — nunca salen de tu infraestructura.
El /ask de la parte 5 devolvió answer y sources — y desechó el uso de tokens que venía con cada finalización. Para la economía de tokens lo necesitamos, y para el A/B necesitamos que el modelo sea intercambiable. Tres variables de entorno y dos campos de respuesta en app/main.py (montado en volumen; uvicorn\nrecarga en caliente, sin reconstrucción):
# El modelo de generación es configurable para que la suite de evaluación pueda A/B modelos.
# Los valores predeterminados preservan la configuración del tutorial-5.
GEN_MODEL = os.getenv(\"GEN_MODEL\", \"Qwen2.5-3B-Instruct\")
GEN_BASE_URL = os.getenv(\"GEN_BASE_URL\", \"https://inference.wiline.com/v1\")
GEN_API_KEY = os.getenv(\"GEN_API_KEY\", os.environ[\"WEC_API_KEY\"])
generate() ahora también devuelve resp.usage, y /ask informa ambos:
{
\"answer\": \"Para ver tus estados de cuenta ...\",
\"sources\": [\"...\"],
\"model\": \"Qwen2.5-3B-Instruct\",
\"usage\": {
\"prompt_tokens\": 1238,
\"completion_tokens\": 122,
\"total_tokens\": 1360
}
}
![\"/ask](\"https://wec.wiline.com/docs/es/assets/images/deepeval-ask-usage-b1a5b036ae1af43fa37d1c91c9d2f092.png\")
\nFigura 4. Los nuevos campos model y usage: 1,238 tokens de prompt + 122 tokens de finalización para una\npregunta de facturación. Este es el número del debate sobre economía de tokens.
Ese bloque usage es el número del marketing de GPT-5.6 — medido en tu carga de trabajo,\npor solicitud. Pasa la variable a través de compose (GEN_MODEL: ${GEN_MODEL:-Qwen2.5-3B-Instruct}\nbajo rag-api's environment:) y recuerda esta línea — vuelve a morder en\nSolución de problemas.
eval/test_rag_regression.py. Lee el tests.csv de la parte 5, extrae el hecho de referencia de\ncada rúbrica de promptfoo, pregunta al servicio en vivo, registra el uso de tokens y afirma una métrica de corrección\nde GEval juzgada por WECJudge:
\"\"\"Suite de regresión DeepEval para el servicio RAG de documentos WEC.
Reutiliza el conjunto dorado de promptfoo (tests.csv) del tutorial anterior:
el hecho de referencia se analiza de cada cadena llm-rubric.
\"\"\"
import csv, json, os, re
import pytest
import requests
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, LLMTestCaseParams
from wec_judge import WECJudge
RAG_API_URL = os.getenv(\"RAG_API_URL\", \"http://rag-api:8000\")
USAGE_LOG = os.getenv(\"USAGE_LOG\", \"usage_log.jsonl\")
MAX_CASES = int(os.getenv(\"MAX_CASES\", \"0\")) # 0 = todos
FACT_RE = re.compile(r'Hecho de referencia de los documentos oficiales: \"(.*?)\"')
def load_cases():
with open(\"tests.csv\", newline=\"\") as f:
for row in csv.DictReader(f):
m = FACT_RE.search(row[\"__expected\"])
yield row[\"question\"], (m.group(1) if m else \"\")
CASES = list(load_cases())
if MAX_CASES:
CASES = CASES[:MAX_CASES]
judge = WECJudge()
correctness = GEval(
name=\"Correctness\",
criteria=(
\"La salida real debe abordar correctamente la pregunta de entrada y no debe \"
\"contradecir el hecho de referencia dado como salida esperada. Diferente redacción \"
\"está bien. Fallar solo si la respuesta es incorrecta, contradice el hecho de referencia, \"
\"o no responde a la pregunta.\"
),
evaluation_params=[
LLMTestCaseParams.INPUT,
LLMTestCaseParams.ACTUAL_OUTPUT,
LLMTestCaseParams.EXPECTED_OUTPUT,
],
model=judge,
threshold=0.5,
)
@pytest.mark.parametrize(
\"question,reference\", CASES, ids=[q[:50] for q, _ in CASES]
)
def test_rag_regression(question, reference):
r = requests.post(f\"{RAG_API_URL}/ask\", json={\"question\": question}, timeout=120)
r.raise_for_status()
data = r.json()
expect = os.getenv(\"EXPECT_MODEL\")
assert not expect or data[\"model\"] == expect, (
f\"la suite esperaba {expect} pero el servicio está ejecutando {data['model']}\"
)
with open(USAGE_LOG, \"a\") as f:
f.write(json.dumps({
\"model\": data.get(\"model\"),
\"question\": question,
**data.get(\"usage\", {}),
}) + \"\\n\")
assert_test(
LLMTestCase(
input=question,
actual_output=data[\"answer\"],
expected_output=reference,
),
[correctness],
)
(Esa afirmación EXPECT_MODEL no estaba en la primera versión. Existe debido a un error que encontrarás en un momento.)
Primera ejecución, limitada a 5 casos para fallar rápido:
\ndocker compose --profile eval run --rm \\
-e MAX_CASES=5 -e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
eval
4 de 5 pasaron en 2:37 — y tanto los pases como la falla valen la pena leer. La\nfalla (\"¿Cuál es el punto de partida para la facturación?\", puntuación 0.3) no es un error del servicio: la\nrespuesta era factualmente correcta, pero la etiqueta dorada es un título de sección (\"Cómo Funciona la Facturación\")\ny el juez quería que se nombrara. Recuerda este caso — parpadea entre pasar y fallar durante todo el tutorial, y ese parpadeo se convierte en un hallazgo. Mientras tanto, en \"número total de eventos\"\nel juez puntuó un 0.6, un pase límite con el razonamiento exactamente correcto (el servicio\ndescribió la característica en lugar de dar pasos). Veredictos matizados de un juez autoalojado —\nla cosa que la gente asume que necesitas modelos de clase GPT-4 para.
\n![\"Primera](\"https://wec.wiline.com/docs/es/assets/images/deepeval-first-run-cabfff276f20b525d0c7c20bb52c1a6a.png\")
\nFigura 5. Primera ejecución: 4 de 5 pasaron en 2:37, cada veredicto con razonamiento escrito del\njuez gemma4 — incluyendo la única falla, un veredicto estricto sobre una etiqueta de título de sección\nen lugar de un error del servicio.
Nota la línea de resumen de DeepEval: costo de token: Ninguno. No puede calcular el precio de un juez autoalojado — que es\nexactamente por qué la suite escribe su propio usage_log.jsonl.
![\"Registro](\"https://wec.wiline.com/docs/es/assets/images/deepeval-usage-log-65042f9bd05652b9ff3814cd52b37270.png\")
\nFigura 6. La contabilidad propia de la suite: una línea JSON por pregunta — modelo, prompt, finalización,\ntotal — los datos en bruto de cada comparación en este tutorial se construyen a partir de esto.
Tienes una suite de regresión que califica un servicio RAG en vivo — reutilizando el conjunto dorado del último tutorial\nsin cambios, juzgada por un modelo autoalojado, con contabilidad de tokens por pregunta que el marco\nmismo no puede proporcionarte.
La pregunta que la suite existe para responder: nuestro servicio genera con Qwen2.5-3B-Instruct —\n¿debería hacerlo? gemma4 es más nuevo, bien considerado, ya está en el catálogo de WEC. Se siente como una mejora.\nSe siente. Vamos a medir.
\nLínea base, todos los 16 casos:
\ndocker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e USAGE_LOG=usage_qwen.jsonl \\
eval
14/16 (87.5%) en 8:50. Las dos fallas son artefactos de etiqueta, no errores de RAG: los hechos dorados\nde la parte 5 son títulos de sección (\"Cómo Funciona la Facturación\"), y el juez penalizó respuestas que eran\nfactualmente correctas pero no repetían el título; y mp3 frente a la etiqueta audio/mpeg — el mismo hecho en\ndos niveles de abstracción, dictaminado como una contradicción. Lee tus fallas antes de confiar en tu tasa de aprobación. Dejamos ambas: son una deuda de etiqueta honesta, y se convierten en nuestro canario de favoritismo del juez en el A/B.
![\"Línea](\"https://wec.wiline.com/docs/es/assets/images/deepeval-qwen-baseline-5b61265199e0d615241bbbfdb30d7a81.png\")
\nFigura 7. La línea base: 87.5% en 8:50. Ambas fallas son artefactos de etiqueta, no errores de RAG —\nlee tus fallas antes de confiar en tu tasa de aprobación.
Desafiante — misma suite, una variable de entorno (prefíjela en cada comando de compose; Solución de problemas\nexplica por qué en sangre):
\nGEN_MODEL=gemma4 docker compose up -d rag-api
until curl -sf localhost:8000/health > /dev/null; do echo \"esperando...\"; sleep 3; done
curl -s -X POST localhost:8000/ask -H \"Content-Type: application/json\" -d '{\"question\": \"ping\"}' \\
| python3 -c \"import json,sys; print('>>> el modelo es:', json.load(sys.stdin)['model'])\"
GEN_MODEL=gemma4 docker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e USAGE_LOG=usage_gemma4.jsonl \\
-e EXPECT_MODEL=gemma4 \\
eval
Y verifica el registro, porque las etiquetas de ejecución mienten:
\nsort <(cat eval/usage_gemma4.jsonl | python3 -c \"import json,sys; [print(json.loads(l)['model']) for l in sys.stdin]\") | uniq -c
# 16 gemma4
![\"Cambiando](\"https://wec.wiline.com/docs/es/assets/images/deepeval-gemma4-run-6a7c64183ec8b68e6d5e5ff76dd0924a.png\")
\nFigura 8. Cambiando el desafiante: GEN_MODEL=gemma4, espera por /health, luego confirma\n>>> el modelo es: gemma4 desde la propia respuesta — antes de gastar un solo minuto de evaluación.
![\"Resumen](\"https://wec.wiline.com/docs/es/assets/images/deepeval-gemma4-verified-8d7291e9dfcda2f337f83ca7e4988071.png\")
\nFigura 9. La ejecución de gemma4: 81.25% en ~13 minutos — y sus tres fallas son los mismos\ncasos de artefactos de etiqueta en los que Qwen parpadea. Sin favoritismo del juez gemma4 hacia el concursante gemma4.
Un script sobre los registros de uso:
\n| ejecución | tasa de aprobación | tokens promedio de prompt | tokens promedio de finalización | tokens totales |
|---|---|---|---|---|
| Qwen2.5-3B (ejecución 1) | 87.5% | 1,126 | 75 | 19,225 |
| Qwen2.5-3B (ejecución 2) | 81.25% | 1,126 | 75 | 19,225 |
| gemma4 | 81.25% | 1,199 | 415 | 25,834 |
![\"Tabla](\"https://wec.wiline.com/docs/es/assets/images/deepeval-verdict-table-fc9c10d332e08f09d63c768e48c1b23c.png\")
\nFigura 10. El veredicto en cinco líneas: misma tasa de aprobación, 5.5× los tokens de finalización. La evaluación\njusto previno una migración innecesaria.
Dos hallazgos, uno esperado y uno no:
\nEl veredicto: no cambies. Misma calidad efectiva, mismos casos de falla — pero gemma4 usa\n5.5× los tokens de finalización (415 frente a 75 por respuesta) y se ejecuta ~45% más lento por pregunta. En una\ncarga de trabajo RAG donde el contexto recuperado de ~1,100 tokens domina el prompt, la columna de finalización es toda la diferencia de costo. \"Modelo más nuevo\" perdió ante \"mídelo\" en una tarde. Esta es precisamente la evaluación que el post de noticias de GPT-5.6 dijo que ejecutarías — y es la misma evaluación que ejecutarías\ncontra GPT-5.6 mismo: cambia GEN_MODEL, GEN_BASE_URL, y GEN_API_KEY, nada más.
El juez tiene un umbral de ruido. Mira las dos filas de Qwen: cuentas de tokens idénticas —\n19,225 en ambas ejecuciones, porque la generación con temperatura 0 es determinista — sin embargo 87.5% frente a 81.25%.\nLas respuestas no cambiaron; solo los veredictos del juez lo hicieron (un límite de 0.6 se convirtió en un 0.3).\nEso aísla limpiamente la no determinación del juez del comportamiento del modelo, y establece tu umbral de CI:\nuna puerta en \"≥ 87.5%\" fallaría. El nuestro tolera un veredicto cambiado y falla en dos o más\nregresiones reales.
\n![\"Ejecución](\"https://wec.wiline.com/docs/es/assets/images/deepeval-qwen-run2-48156c484cd782d1e346e0938b1080b9.png\")
\nFigura 11. Ejecución 2 de Qwen: las mismas 16 respuestas deterministas, 81.25% esta vez — el juez, no\nel modelo, es donde vive la variación.
Puedes resolver un debate sobre el cambio de modelo con datos medidos — tasa de aprobación y tokens por tarea — y\nconoces el umbral de ruido de tu juez, así que puedes establecer un umbral de CI que no falle.
La recompensa de contenerizar todo: el trabajo de CI es el comando que has estado ejecutando todo\nel tiempo. .github/workflows/eval.yml:
name: rag-regression-eval
on:
pull_request:
paths: [\"app/**\", \"eval/**\"]
workflow_dispatch:
jobs:
eval:
runs-on: [self-hosted, wec] # corredor con acceso a inference.wiline.com
steps:
- uses: actions/checkout@v4
- name: Ejecutar suite de regresión
env:
WEC_API_KEY: ${{ secrets.WEC_API_KEY }}
run: |
docker compose up -d rag-api
docker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e EXPECT_MODEL=Qwen2.5-3B-Instruct \\
eval
- name: Desmontar
if: always()
run: docker compose down
Cualquier PR que toque la aplicación o la evaluación debe sobrevivir a 16 preguntas juzgadas contra el servicio en vivo — con la identidad del modelo afirmada — antes de que se fusione.
\nTu evaluación es una puerta de CI. El contenedor que ejecutaste localmente es byte por byte lo que CI ejecuta — sin\n\"funciona en mi máquina\" brecha entre desarrollo y la tubería.
[Errno 28] No hay espacio en el dispositivo — y volvióNuestra primera pip install deepeval falló: disco 100% lleno, 58G de 58G. Liberamos 2 GB de registros de diario\ny caché de construcción… y estaba lleno de nuevo minutos después. El culpable:
7.9G /var/lib/docker/containers/10281d.../10281d...-json.log
langfuse-clickhouse-1 estaba en un bucle de error, rociando trazas de pila en un registro json de Docker con\nsin rotación configurada — un espiral mortal, porque un disco lleno causa más errores que causa más\nregistros. Había estado \"no saludable\" durante 8 días. La solución, en orden (el orden importa — truncar mientras\nel contenedor se ejecuta simplemente vuelve a llenar):
docker stop langfuse-clickhouse-1
sudo sh -c \"truncate -s 0 /var/lib/docker/containers/10281d*/*-json.log\"
Luego hazlo permanente — rotación de registros en la sobrecarga de compose, aplicada a cada servicio:
\nx-logging: &default-logging
logging:
driver: json-file
options:
max-size: \"50m\"
max-file: \"3\"
services:
clickhouse:
<<: *default-logging
# ... cada otro servicio
docker compose up -d para recrear. ClickHouse se volvió saludable por primera vez en 8 días.\nEl controlador json-file de Docker no rota por defecto; en una caja que ejecuta infraestructura LLM\nque registra entusiastamente, los registros de contenedor sin límites son una bomba de tiempo.
Conexión rechazada, luego 3 pasanCambiar GEN_MODEL recrea rag-api, y la aplicación tarda ~3 minutos en arrancar (Chroma +\ncarga del modelo de incrustación). Nuestra suite comenzó a golpear /ask inmediatamente: 13 fallas\nde conexión rechazadas seguidas, luego la API cobró vida a mitad de ejecución y las últimas 3 pasaron. Flaky de la peor manera — la\nfalla depende del tiempo de reloj de pared.
Soluciona esto en la suite, no en la disciplina humana — eval/conftest.py:
\"\"\"Rechaza iniciar la suite hasta que la API RAG esté saludable.\"\"\"
import os, time
import requests
RAG_API_URL = os.getenv(\"RAG_API_URL\", \"http://rag-api:8000\")
READY_TIMEOUT = int(os.getenv(\"READY_TIMEOUT\", \"300\"))
def pytest_configure(config):
deadline = time.time() + READY_TIMEOUT
while time.time() < deadline:
try:
requests.get(f\"{RAG_API_URL}/health\", timeout=3).raise_for_status()
return
except requests.RequestException:
time.sleep(3)
raise RuntimeError(f\"rag-api no saludable después de {READY_TIMEOUT}s — abortando evaluación\")
La más desagradable, porque nada falló. ${GEN_MODEL:-Qwen…} en compose se interpola\ndesde tu shell en cada invocación. Comenzamos el servicio con\nGEN_MODEL=gemma4 docker compose up -d — correcto. Luego ejecutamos la evaluación sin el prefijo.\nCompose resolvió la variable de nuevo al valor predeterminado de Qwen, vio el contenedor en ejecución como un desvío de configuración\ny — a través de depends_on — silenciosamente recreó rag-api con Qwen. La ejecución se completó,\nel resumen decía \"gemma4\" en cada veredicto (el juez era gemma4), y cada respuesta había sido\nescrita por Qwen.
Solo lo atrapamos porque la suite registra el modelo desde la respuesta:
\nsort <(... usage_gemma4.jsonl ...) | uniq -c
# 16 Qwen2.5-3B-Instruct ← la ejecución \"gemma4\"
Nunca confíes en la etiqueta de una ejecución; verifica desde los datos que el sistema bajo prueba informa sobre sí mismo.\nLa solución permanente es la afirmación EXPECT_MODEL en la suite (Paso 4). Prueba que funciona — la\nprueba de fallo deliberado:
FAILED ... AssertionError: la suite esperaba gemma4 pero el servicio está ejecutando Qwen2.5-3B-Instruct
1 falló en 2.44s
Menos de tres segundos, antes de gastar una sola llamada de juez — frente a los 10+ minutos que cada ejecución mal etiquetada\nnos costó.
\n![\"Guardia](\"https://wec.wiline.com/docs/es/assets/images/deepeval-expect-model-ccc34be3d936ecfd93823c565073b405.png\")
\nFigura 12. La guardia en acción: modelo incorrecto → fallo ruidoso en menos de tres segundos, antes de que se gaste una\nsola llamada de juez. Compara con los 10+ minutos que cada ejecución mal etiquetada nos costó.
sleep 5 no es una verificación de disponibilidadPequeño bono: después de recrear el contenedor, canalizamos la salida de /ask a un analizador JSON 5\nsegundos después y obtuvimos json.decoder.JSONDecodeError: Esperando valor: línea 1 columna 1 — el\nservidor no estaba arriba, curl devolvió vacío, el analizador se ahogó en nada. Sondea /health en un bucle;\nnunca duermas un número adivinado.
gemma4 + GEval): veredictos con razonamiento, sin clave de OpenAIEXPECT_MODEL que convierte la evaluación silenciosa del modelo incorrecto en un fallo ruidoso en menos de tres segundosLa suite juzga respuestas. Las trazas de Langfuse de la parte 4 saben por qué — qué fragmentos fueron recuperados,\ncuánto costó el rango de generación, dónde se oculta la latencia. Conectar fallas de evaluación de vuelta a sus trazas\n(ID de prueba de DeepEval ↔ ID de traza de Langfuse) convierte \"la prueba falló\" en \"aquí está la recuperación que\nlo causó.\" Esa es la historia de depuración a nivel de componente, y es hacia donde va esta serie a continuación.
\n![\"Promptfoo\"](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-avatar-31b32c657d72dac0a7edbd77c24ec717.jpg\"){kind=avatar}
+Everything in this series was building to this. You can prove a model works\n(part 1), make its output machine-reliable\n(part 2), generate real test data\n(part 3), and observe production\n(part 4). Now we spend all four skills at once on\nthe pattern behind almost every serious LLM product: RAG — retrieval-augmented generation.
\nWe'll build a docs assistant: a containerized HTTP service that answers customer questions\nfrom WEC's own documentation. Not a notebook — a service, Docker-first, the shape you'd actually\ndeploy. And because this series doesn't do happy-path demos: along the way our RAG hallucinates a\nGPU price, we root-cause it to our own scraper, fix it, and pin the fix with a regression\ntest. Every command, number, and error below is from a real run.
\n\nOne architecture decision up front: we split the work. Embeddings run locally (a small ONNX\nmodel — fast, free, no GPU needed) and generation runs on WEC. This is a completely standard\nproduction split: retrieval is cheap and latency-sensitive, so keeping it next to your vector\nstore saves a network round-trip per query — while generation is where the big model earns its\nkeep.
\nThe WEC catalog now ships bge-m3 (1024-dim, multilingual, batch input) on\n/v1/embeddings:
curl -s https://inference.wiline.com/v1/embeddings \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"bge-m3\",\"input\":[\"first chunk\",\"second chunk\"]}' | jq '.data | length'
Swapping this tutorial over is a two-function change — replace the fastembed calls in\ningest.py and main.py with the same OpenAI client pointed at /v1/embeddings\n(wec.embeddings.create(model=\"bge-m3\", input=chunks)), and re-ingest (the vector dimension\nchanges from 384 to 1024, so drop and rebuild the collection). We keep the local path below\nbecause it's free, offline, and every number in this guide was measured with it — but both are\nproduction-legitimate; pick per your latency and ops preferences.
df -h /. Our box was at 99% and survived, but\ntight disk is the #1 silent killer of Docker builds.Real RAG features ship as services, so we start as one: a FastAPI app in a container, code\nbind-mounted so uvicorn --reload picks up every edit — no rebuild per change.
mkdir -p ~/rag-service/app && cd ~/rag-service
cat > requirements.txt <<'EOF'
fastapi==0.115.6
uvicorn==0.34.0
chromadb==0.5.23
fastembed==0.4.2
openai==1.59.7
langfuse
requests==2.32.3
beautifulsoup4==4.12.3
EOF
cat > Dockerfile <<'EOF'
FROM python:3.12-slim
WORKDIR /srv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ app/
EXPOSE 8000
CMD [\"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\", \"--reload\"]
EOF
cat > docker-compose.yml <<'EOF'
services:
rag-api:
build: .
ports:
- \"8000:8000\"
volumes:
- ./app:/srv/app # live code - edit on host, uvicorn reloads
- chroma-data:/data # persisted vector index
- model-cache:/root/.cache # embedding model cache (survives rebuilds)
environment:
ANONYMIZED_TELEMETRY: \"False\"
WEC_API_KEY: ${WEC_API_KEY}
LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY}
LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY}
LANGFUSE_HOST: ${LANGFUSE_HOST}
volumes:
chroma-data:
model-cache:
EOF
Secrets live in an .env file next to the compose (compose loads it automatically — keys never\nenter the YAML). Keep it out of version control from the start:
cat > .env <<'EOF'
WEC_API_KEY=sk-your-wec-key
LANGFUSE_PUBLIC_KEY=pk-lf-…
LANGFUSE_SECRET_KEY=sk-lf-…
LANGFUSE_HOST=http://<your-langfuse-host>:3000
EOF
echo \".env\" >> .gitignore
A minimal app so the container has something to serve:
\ncat > app/main.py <<'EOF'
from fastapi import FastAPI
app = FastAPI(title=\"WEC docs RAG\")
@app.get(\"/health\")
def health():
return {\"status\": \"ok\"}
EOF
docker compose up -d --build
curl -s localhost:8000/health
{\"status\":\"ok\"}
![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-deploy-health-850c74e1ed3eff7a20368db371456f79.png\")
\nFigure 1. One command each: the container up, /health answering, and the disk check\n(ours reads 99% — this box lives dangerously). The build takes ~90s and a ~700 MB image.
In the real world, the knowledge base you'll want your assistant to answer from usually isn't a\ntidy folder of markdown — it's a live website: product docs, a wiki, a help center. So the\ncorpus-acquisition skill worth learning is real scraping, not file loading.
\nFor this tutorial we scrape WEC's own documentation site. It's built with Docusaurus, and\nDocusaurus (like most site generators) publishes a sitemap.xml — which means you can discover\nevery page programmatically instead of guessing URLs. The same approach works on any site that\nships a sitemap:
curl -s https://wec.wiline.com/docs/sitemap.xml | grep -c \"<loc>\" # 109 URLs on the whole site
We filter to the product docs (/docs/cloud_portal/), pull each page, and keep only the\n<article> element — Docusaurus wraps the actual content in it, so nav/sidebar/footer never reach\nthe index:
cat > app/ingest.py <<'EOF'
\"\"\"Scrape the WEC docs site -> chunk -> embed locally -> Chroma.\"\"\"
import re, requests, chromadb
from bs4 import BeautifulSoup
from fastembed import TextEmbedding
SITEMAP = \"https://wec.wiline.com/docs/sitemap.xml\"
FILTER = \"/docs/cloud_portal/\" # product docs only
CHUNK, OVERLAP = 700, 100 # chars
def discover():
xml = requests.get(SITEMAP, timeout=30).text
urls = re.findall(r\"<loc>([^<]+)</loc>\", xml)
return [u for u in urls if FILTER in u]
def scrape(url):
html = requests.get(url, timeout=30).text
art = BeautifulSoup(html, \"html.parser\").find(\"article\") # Docusaurus main content
return art.get_text(\"\\n\", strip=True) if art else \"\"
def chunk(text):
out, i = [], 0
while i < len(text):
out.append(text[i:i + CHUNK])
i += CHUNK - OVERLAP
return out
if __name__ == \"__main__\":
urls = discover()
print(f\"sitemap -> {len(urls)} product-doc pages\")
docs, metas = [], []
for u in urls:
for c in chunk(scrape(u)):
docs.append(c)
metas.append({\"url\": u})
print(f\"scraped -> {len(docs)} chunks\")
embedder = TextEmbedding(\"BAAI/bge-small-en-v1.5\") # local, ~66MB ONNX, no GPU needed
vectors = [v.tolist() for v in embedder.embed(docs)]
print(f\"embedded -> {len(vectors)} vectors (dim {len(vectors[0])})\")
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
col.add(ids=[str(i) for i in range(len(docs))],
documents=docs, metadatas=metas, embeddings=vectors)
print(f\"indexed -> collection 'wec-docs' now has {col.count()} chunks\")
EOF
docker compose exec rag-api python -m app.ingest
sitemap -> 37 product-doc pages
scraped -> 281 chunks
model_optimized.onnx: 100%|████████████| 66.5M/66.5M [00:03<00:00, 16.9MB/s]
embedded -> 281 vectors (dim 384)
indexed -> collection 'wec-docs' now has 281 chunks
![\"Ingest](\"https://wec.wiline.com/docs/es/assets/images/rag-ingest-2a1ffde1c98f1968bbf60532fa0a0a00.png\")
\nFigure 2. The whole product-doc corpus indexed in under a minute. The embedding model caches in\nthe model-cache volume, so it downloads exactly once.
You can turn any documentation website into a queryable vector index — sitemap discovery, content\nextraction, chunking, local embeddings.
get_text(\"\\n\", …)Our first version used get_text(\" \") — a single space as the separator. It looked harmless and\ncaused a genuine hallucination you'll see in Step 4. Keep the newline; we'll come back to this.\n(Want to watch the bug happen on your own box? Change \"\\n\" back to \" \" in scrape(), re-run\nthe ingest, and ask the Step-4 question — then put the newline back and re-ingest.)
You may see Failed to send telemetry event ClientStartEvent: capture() takes 1 positional argument… — a known chromadb/posthog version clash. It's harmless (your data is fine), and the\nANONYMIZED_TELEMETRY: \"False\" env in the compose silences it.
/ask endpoint: retrieve, generate, traceNow the service itself. Three design choices worth stating:
\nsources is deterministic.langfuse.openai (part 4's drop-in), and each stage gets an\n@observe span — so every request produces a ask → retrieve → generate tree in Langfuse.timeout=60 on the client. Part 4's lesson: no default timeout means a stalled backend hangs\nyour service silently.cat > app/main.py <<'EOF'
import os, chromadb
from fastapi import FastAPI
from pydantic import BaseModel
from fastembed import TextEmbedding
from langfuse import observe, get_client
from langfuse.openai import openai # auto-traces the WEC call
app = FastAPI(title=\"WEC docs RAG\")
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
embedder = TextEmbedding(\"BAAI/bge-small-en-v1.5\")
wec = openai.OpenAI(
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
timeout=60,
)
class Ask(BaseModel):
question: str
@observe() # span: retrieve
def retrieve(question: str, k: int = 4):
qv = list(embedder.embed([question]))[0].tolist()
res = col.query(query_embeddings=[qv], n_results=k)
chunks = res[\"documents\"][0]
sources = sorted({m[\"url\"] for m in res[\"metadatas\"][0]})
return chunks, sources
@observe() # span: generate (WEC call nested inside)
def generate(question: str, chunks: list[str]) -> str:
context = \"\\n---\\n\".join(chunks)
resp = wec.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\", # small on purpose: cheap + fast per query,
# and its failures teach (see Step 5)
name=\"rag-generate\",
messages=[{\"role\": \"user\", \"content\":
\"Answer the question using ONLY the context below. \"
\"If the context doesn't contain the answer, say so. \"
\"When quoting a price or number, copy it VERBATIM with its unit and the item \"
\"it belongs to; never combine numbers from different lines and never compute \"
\"new numbers from examples.\\n\\n\"
f\"Context:\\n{context}\\n\\nQuestion: {question}\"}],
)
return resp.choices[0].message.content
@app.post(\"/ask\")
@observe() # root span: the whole request
def ask(body: Ask):
chunks, sources = retrieve(body.question)
answer = generate(body.question, chunks)
get_client().flush()
return {\"answer\": answer, \"sources\": sources}
@app.get(\"/health\")
def health():
return {\"status\": \"ok\"}
EOF
docker compose up -d --build
Ask it a real customer question:
\ncurl -s localhost:8000/ask -H \"Content-Type: application/json\" \\
-d '{\"question\": \"How do I create an API key for the Inference API?\"}' | python3 -m json.tool
{
\"answer\": \"To create an API key for the Inference API, follow these steps:\\n1. Log in to the WiLine Edge Cloud.\\n2. Expand the \\\"Inference\\\" section in the left sidebar.\\n3. Click on the \\\"API Keys\\\" tab.\\n4. Click the \\\"+ Create Key\\\" button located above the keys table. ...\",
\"sources\": [
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/api/wiline-edge-cloud-inference-api/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/api_keys/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/examples/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/models_hub/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/overview/\"
]
}
![\"First](\"https://wec.wiline.com/docs/es/assets/images/rag-first-ask-301b6dfc7a64a463e0eb1e6d93b53837.png\")
\nFigure 3. First try: the exact API-key flow from the docs, with the right page cited. Scrape →\nembed → retrieve → generate, end to end.
Open Langfuse → Tracing and you'll find the request as a span tree — ask → retrieve → generate → rag-generate — with per-step latency and tokens. When an answer is bad, this is how you\ntell bad retrieval from bad generation (part 4's skill, now on a real app).
![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-trace-tree-769e5224814989dedc4896f9e4e1873f.png\")
\nFigure 4. Every /ask becomes a tree: retrieval and generation each have an address.
You have a traced, containerized RAG service answering from live-scraped documentation.
A good RAG must refuse what the docs don't cover. Probe it:
\ncurl -s localhost:8000/ask -H \"Content-Type: application/json\" \\
-d '{\"question\": \"Does WEC offer a free GPU tier for students?\"}' | python3 -m json.tool
Our first version (the get_text(\" \") scraper) answered:
\"No, WEC does not offer a free GPU tier specifically for students. The pricing for
GPU hourly is listed as $0.66/GPU-hr with a 25% off annual prepay option at
$0.10/GB-mo for block storage. There is no mention of a free GPU tier in the
provided information.\"
The refusal is right. But read the pricing sentence again: \"$0.66/GPU-hr with a 25% off annual\nprepay option at $0.10/GB-mo for block storage\" — that's three different facts welded into one\nfalse statement, gluing a storage rate onto the GPU prepay option. Check the actual pricing page\nand you find they're simply three adjacent items:
\nThe model stitched a storage price onto \"GPU\". Why? Look at the chunk we fed it. Our\nspace-separated scrape had flattened the pricing cards into one undifferentiated line:
\n... $1.44 /mo Starting at $0.66 /GPU-hr GPU hourly 25 % off Annual prepay $0.10 /GB-mo Block storage ...
The hallucination was manufactured by our own ingestion. The model conflated prices because we\ndestroyed the structure before embedding it. This is the most classic RAG failure there is —\ngarbage in, garbage out — and you only catch it by probing with questions and reading the\nretrieved chunks.
\n![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-hallucination-18e9fb70cb217a347f31057d36b774e8.png\")
\nFigure 5. The bug in the wild: correct refusal, garbled pricing — a storage rate glued onto the\nGPU prepay option. The sources look perfectly plausible. This is why \"it cites sources\" is not the\nsame as \"it's grounded.\"
Two fixes, both already in the code above:
\nget_text(\"\\n\", strip=True) keeps line boundaries, so price\ncards stay separate lines instead of one soup.After re-ingesting with the fix, the storage-price conflation is gone. Residual ambiguity remains —\nthe pricing strip still contains fragments like \"$1.44/mo\" (a compute-instance price) near the GPU\nline, and truly fixing that needs table-aware extraction (see What's next). Which is exactly why\nthe next step exists: pin the fixed bug so it can never quietly return.
\nThis step took four rounds of fixes to get an honest number — and the journey from 39% to 87%\nis the best lesson in the series, because almost nothing we fixed along the way was the RAG itself.
\nWe reuse part 3's skill — generate a QA dataset from the corpus itself — and grade the live\nHTTP endpoint with Promptfoo. The first generator version asked for one question per page with a\nkey_fact the answer must contain, and got 37/37 pairs back. Some labels already smelled — a vague\n\"All paid\", menu paths instead of answers — but let's run it naively first and let the failures\nteach us. Convert to a Promptfoo dataset with plain substring assertions (icontains: + the key\nfact) and point it at the running service. The provider is HTTP — we grade the real API,\nexactly what a CI gate would do:
mkdir -p eval
{ echo 'question,__expected'; jq -r '[.question, (\"icontains:\" + .key_fact)] | @csv' app/qa.jsonl; } > eval/tests.csv
cat > eval/promptfooconfig.yaml <<'EOF'
description: \"RAG service eval — QA set generated from the scraped docs + regression\"
providers:
- id: https
config:
url: http://localhost:8000/ask
method: POST
headers:
Content-Type: application/json
body:
question: \"{{question}}\"
transformResponse: json.answer
tests:
- file://tests.csv
# regression: the storage-price-as-GPU-price conflation from Step 4
- vars:
question: \"What is the pricing model for GPU hourly usage in Edge Cloud?\"
assert:
- type: not-icontains
value: \"0.10\"
- type: not-icontains
value: \"GB-mo\"
EOF
cd eval && npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Results:
✓ 15 passed (39.47%)
✗ 23 failed (60.53%)
Duration: 40s (concurrency: 4)
That 39.5% is what we measured during development, while the Step-4 bug was still live. Re-run\nthe same naive eval against the finished service and it lands much higher — 27/38:
\n![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-eval-icontains-284e4ea4fa5a8f2dec99a5079c84c4f7.png\")
\nFigure 6. The same naive eval against the finished service: 71.05%. Better service, same\nnoisy labels — the 30-point gap between these two runs is all service quality, and both numbers\nmean little until you read the rows.
Read the failures before you panic. From the development run's 23 failures, most are not RAG\nfailures:
\n| Failure | What actually happened |
|---|---|
| \"Balance due\" answer: \"the amount that remains due… $0.00\" | Correct answer; the label demanded the phrase All paid — bad label |
| Payment Information: gives the exact right menu path | Correct; label phrasing doesn't substring-match — brittle assertion |
| GPU pricing: \"$0.10 per GB-month\" | Real failure — the Step-4 conflation, reproducing systematically |
| TTS default format: \"not specified in the context\" | Real retrieval miss — the chunk with the default wasn't retrieved |
Substring matching (icontains) was perfect for part 2's single JSON field and is too brittle\nfor long-form RAG answers. The obvious upgrade is part 4's skill: an LLM judge grading\nsemantic consistency (llm-rubric: assertions + a judge model in defaultTest). We did exactly\nthat — same 37 labels, judge instead of substrings — and got:
Results:
✓ 17 passed (44.74%)
✗ 21 failed (55.26%)
Duration: 8m 21s (concurrency: 4)
39.5% → 44.7%. Barely moved — because the judge faithfully enforces bad labels. Rows with\ngarbage key_facts still fail: the reference is wrong, not the answer. A better grader cannot\nrescue a bad dataset. The bottleneck was never the assertion type.
So fix the data (part 3's discipline, now enforced by code). Generator v2 demands the label be\nthe answer — not a menu path, not a section name — and adds a curation gate: the key_fact\nmust exist verbatim in the source text, or the row is rejected on the spot:
cat > app/gen_qa.py <<'EOF'
\"\"\"Generate a QA eval set from the indexed docs — v2, curated labels.\"\"\"
import os, json, chromadb
from openai import OpenAI
wec = OpenAI(base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"], timeout=60)
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
data = col.get(include=[\"documents\", \"metadatas\"])
pages = {}
for doc, meta in zip(data[\"documents\"], data[\"metadatas\"]):
pages.setdefault(meta[\"url\"], []).append(doc)
kept, skipped = 0, 0
with open(\"/srv/app/qa.jsonl\", \"w\") as f:
for url, chunks in sorted(pages.items()):
ctx = \"\\n\".join(chunks[:2])[:2000]
resp = wec.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\", temperature=0.3,
messages=[{\"role\": \"user\", \"content\":
\"From this documentation excerpt, write ONE question a customer would ask, \"
\"and the fact that ANSWERS it. Return ONLY JSON with keys:\\n\"
\"question (string), key_fact (string).\\n\"
\"Rules for key_fact: it must be THE ANSWER to the question (not a menu path, \"
\"not a section name), a short phrase copied VERBATIM from the excerpt, \"
\"max 8 words.\\n\\n\"
f\"Excerpt:\\n{ctx}\"}],
)
raw = resp.choices[0].message.content
try:
start, end = raw.index(\"{\"), raw.rindex(\"}\") + 1
row = json.loads(raw[start:end])
# curation gate: the label must literally exist in the source text
if row[\"key_fact\"].lower().strip() not in ctx.lower():
print(f\"SKIP {url.split('/docs/')[1]}: key_fact not verbatim in source\")
skipped += 1
continue
row[\"url\"] = url
f.write(json.dumps(row) + \"\\n\")
kept += 1
print(f\"ok {url.split('/docs/')[1]}: {row['question'][:50]} -> {row['key_fact'][:40]}\")
except Exception as e:
print(f\"SKIP {url}: {e}\")
skipped += 1
print(f\"done -> {kept} kept, {skipped} rejected by curation gate\")
EOF
docker compose exec rag-api python -m app.gen_qa
ok cloud_portal/management/billing/how_billing_works/: What is the starting point ... -> How Billing Works
SKIP cloud_portal/management/billing/overview/: key_fact not verbatim in source
ok cloud_portal/platform/inference/api/wiline-edge-cloud-inference-api/: What is the base URL ... -> https://inference.wiline.com/v1
SKIP cloud_portal/platform/inference/api_keys/: key_fact not verbatim in source
...
done -> 15 kept, 22 rejected by curation gate
15 kept, 22 rejected. That rejection rate is the point: more than half of what the generator\nproduced would have graded the RAG against wrong references. A smaller, trustworthy dataset beats\na bigger, poisoned one.
\nThe generator samples at temperature 0.3, so the exact tally shifts slightly between runs — here's\na later regeneration that kept 16 of 37; the rejection rate stays brutal either way:
\n![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-qa-gen-8dfb631c47f8fc4cb9c506fef0f651d2.png\")
\nFigure 7. The gate at work: 16 kept, 21 rejected on this run. Every surviving label is provably\nin the docs — real answer-facts like audio/mpeg and the API base URL, not menu paths. (The\ndocumented eval runs below use our first curated set: 15 pairs + the regression = 16 tests.)
Rebuild tests.csv with a rubric that gives the judge the question and the verified\nreference, plus explicit PASS/FAIL rules (different wording is fine; contradiction fails):
{ echo 'question,__expected'; jq -r '[.question, (\"llm-rubric:Question asked: \\\"\" + .question + \"\\\". Reference fact from the official docs: \\\"\" + .key_fact + \"\\\". PASS if the answer correctly addresses the question and does not contradict the reference fact — different wording is fine. FAIL only if the answer is wrong, contradicts the reference, or fails to answer the question.\")] | @csv' ../app/qa.jsonl; } > tests.csv
Results:
✓ 12 passed (75.00%)
✗ 4 failed (25.00%)
Duration: 2m 47s (concurrency: 4)
75%. Better — but before celebrating, read the four failures. And here the series' habit pays\noff one more time, because three of them weren't RAG failures either.
\nThe three failures whose grader reason was just \"No output\" all shared two tells:\ngraderError: true, and a completion of exactly 1024 tokens — Promptfoo's default\nmax_tokens. Our judge is a thinking model: it spent the whole budget reasoning and got cut off\nbefore emitting the verdict JSON, which Promptfoo counts as FAIL. The fourth \"failure\" got a\nverdict — but the small judge had literally echoed the schema placeholder (reason: \"string\")\ninstead of grading. Both answers were actually correct.
Two config lines fix it — a bigger judge, and room to think:
\ndefaultTest:
options:
provider:
id: openai:chat:Qwen3.5-122B
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
# thinking models spend tokens on reasoning before the verdict JSON;
# the 1024 default silently truncated the judge and failed 3 tests
max_tokens: 4096
Results:
✓ 14 passed (87.50%)
✗ 2 failed (12.50%)
And the row that matters most:
\n│ What is the pricing model for GPU hourly usage in Edge Cloud? │ [PASS] ... starting at $0.66/GPU-hour. │
The regression is green — the Step-4 conflation is pinned and cannot quietly return. (One\ncosmetic note: the 122B judge sometimes keeps its reason text to a terse ... — the verdicts\nthemselves are correct, which is what the gate reads.)
You can gate a live RAG service in CI: generated + gate-curated QA, a judge for semantics,\ndeterministic regressions for known bugs — and you know how to debug the judge itself.
One habit this series drills: re-run before you believe. We did — and got 75%, with\ndifferent rows failing than before. Billing, which had just passed, now failed with a circular\necho; the TTS answer said \"mp3\" one run and \"unspecified\" the next. The score was a lottery\nbecause the service itself was non-deterministic: generate() passed no temperature, so\nevery eval graded a different roll of the dice at the default 1.0.
One line ends the lottery — add to the create() call in generate():
temperature=0, # determinism: same question -> same answer
Re-run twice. 13/16 — 81.25% — both times, with the same three failures. The number went\ndown and that's the win: 87.5% was partly luck (the flaky rows happened to land right that run);\n81.25% is reproducible. A reader who re-runs your eval should get your number.
\nAfter four rounds of fixing the measurement, what's left is signal — stable across runs, and\neach one is a different classic RAG failure type:
\n\"iated with subnets\\nData Transfer…\"). Fixed-size character chunking\nsplit the fact across a boundary, and the half with the answer doesn't rank. Fix class: larger\noverlap, bigger k, or structure-aware chunking.A trustworthy eval isn't the goal; it's the map. It just told us two of three failures are the\nsame class — facts that don't reach the top-4 retrieved chunks. The cheapest fix in that class is\none character, in retrieve():
def retrieve(question: str, k: int = 6): # was 4 — two misses said \"not enough context\"
Re-run. Then re-run again, because that's the habit now:
\nResults:
✓ 14 passed (87.50%)
✗ 2 failed (12.50%)
14/16 — 87.5% — twice, same two failures. Read what happened with each:
\nk=6 the chunk with the stats block doesn't rank: this miss is\nsemantic, not budgetary — the boundary-mangled text (\"iated with subnets…\") embeds poorly.\nMore k can't fix what chunking broke; this one genuinely needs structure-aware chunking.The number is back to 87.5% — the same as the lucky run — but this time it reproduces, and\nevery point of it has an explanation.
\n![\"Final](\"https://wec.wiline.com/docs/es/assets/images/rag-eval-final-eb3776d3a5abed5af34d6896bbee06d0.png\")
\nFigure 8. The final run: 14/16, the same two failures every time, regression PASS.
39.5% → 44.7% → 75% → 87.5% (lucky) → 81.25% (honest) → 87.5% (earned). Until the very\nlast step, the RAG barely changed — what changed was the measurement: assertions (substrings →\njudge), labels (curation gate), the judge's own config (truncation), determinism (temperature).\nOnly then did one retrieval parameter, chosen by the eval, actually move quality. That's the\nlast lesson of the series:
\nPOST /ask with\ndeterministic citations.Parts 1–4 were the toolkit. This is what the toolkit is for.
\n/ask returns nothing after re-indexingIf you drop and recreate the Chroma collection while the API is running, the service holds a\nstale collection handle and every query throws:
\nchromadb.errors.InvalidCollectionException: Collection 9b486740-… does not exist.
The running process cached the old collection's UUID. Restart the service\n(docker compose restart rag-api) — or resolve the collection per-request instead of at startup.
![\"The](\"https://wec.wiline.com/docs/es/assets/images/rag-stale-handle-1639bfb9ef1938577ff551daa191a889.png\")
\nFigure 9. Re-indexing invalidates open handles — a classic \"works until you rebuild the index\"\nproduction trap.
Failed to send telemetry event … capture() takes 1 positional argumentHarmless chromadb/posthog version clash. Set ANONYMIZED_TELEMETRY: \"False\" in the environment\n(already in our compose).
graderError: true)Check the grading record's completion tokens: if it's exactly 1024 — Promptfoo's default\nmax_tokens — your thinking-model judge spent the whole budget reasoning and was cut off before\nthe verdict JSON. Set max_tokens: 4096 on the judge provider. Related tell: a small judge\nreturning reason: \"string\" is echoing the schema placeholder instead of grading — use a bigger\njudge.
Reasoning judges are slow (~minutes for a dozen rows) and imperfect — expect occasional verdict\nflips between runs. Keep deterministic assertions for known bugs (they're free and never flip)\nand treat the judge score as a trend, not a truth. If a judge row hangs entirely, it's usually a\ntransient network hiccup, not your config — retry before debugging.
\nThe image needs ~1 GB (chromadb + onnxruntime are the heavy layers). Check df -h / first and\ndocker system df for reclaimable space — but never prune blindly on a shared box: \"reclaimable\"\nlies when other projects' containers are running.
The honest limitations are the roadmap, and each one traces to a failure you watched happen:\nstructure-aware chunking (the subnets miss survived k=6 — the boundary-mangled chunk embeds\npoorly, so no retrieval budget rescues it), prompt or model work on generation (the billing\necho: force the model to name the page it's citing, or use a stronger generator), table-aware\nextraction (the pricing strip is still fragment soup — the regression passes, but \"$1.44/mo\"\nstill bleeds near the GPU line; add a positive assert for the correct figure, not just\nnot-icontains for the wrong ones), and judge calibration (grade the judge against a handful\nof human verdicts). Each one moves the pass rate for a reason you can name — which, after five\nparts, is the whole point: you don't guess whether your AI works. You measure it, watch it, and\nmake it prove itself.
Un cliente dice que tu bot de soporte les prometió una política de reembolso que no existe. Tu función\nhizo dos llamadas LLM — clasificar, luego responder. ¿Cuál de ellas la inventó? Si no puedes responder eso,\ntu aplicación es una caja negra — y esta guía soluciona exactamente eso.
\nAhora puedes probar que un modelo funciona (parte 1),\nhacer que su salida sea confiable para máquinas (parte 2),\ny generar un conjunto de pruebas real para verificarlo\n(parte 3). Pero todo eso se ejecuta fuera de línea,\nen CI, con entradas que elegiste. La producción no juega de la misma manera.
\nEsta guía cierra la brecha. Autoalojaremos Langfuse — la alternativa de código abierto y autoalojable\na LangSmith — rastrearemos cada llamada real, evaluaremos automáticamente el tráfico en vivo con un juez LLM,\nprofundizaremos en el paso exacto que falla, y retroalimentaremos las fallas para que tu conjunto de datos de la parte 3 se vuelva\nmás fuerte. La evaluación fuera de línea te dice que funcionó en tu conjunto de pruebas; esto te dice que funciona en el mundo real.
\n\nAl final podrás tomar cualquier función WEC y: ver dentro de cada llamada, evaluar la calidad en tráfico real automáticamente, encontrar la llamada exacta que falló y por qué, y convertir fallas en producción en nuevos casos de prueba. Esa es la diferencia entre \"pasó CI\" y \"se mantiene en producción.\"
\nMantendremos el ejemplo en ejecución de la parte 3 — un clasificador de tickets de soporte en la API de Inferencia WEC — y lo pondremos bajo observación.
\nTu aplicación llama a la API WEC como de costumbre; Langfuse (autoalojado) captura silenciosamente cada llamada como un\nrastreo, un juez LLM evalúa cada una, y las fallas fluyen de vuelta a tu conjunto de datos de la parte 3 — para que la producción siga fortaleciendo tus evaluaciones:
\n\nUsamos Langfuse porque es el líder de código abierto en observabilidad LLM (con licencia MIT,\nautoalojable), su SDK es compatible con OpenAI por lo que apunta a la API WEC sin cambios, y — la\nrazón por la que encaja en esta serie — tiene conjuntos de datos, evaluación y evaluadores LLM-como-juez integrados.\nEso permite que tu conjunto de datos de la parte 3 y el bucle de \"evaluar producción, retroalimentar fallas\" sean\nde primera clase en lugar de añadidos.
\nEl compromiso: la pila de producción es pesada (Postgres + ClickHouse). Si no necesitas las características de evaluación\ny quieres algo más ligero, alternativas razonables son Arize Phoenix (nativa de OpenTelemetry,\nfuerte para evaluación fuera de línea), Helicone (un proxy de una línea — pero sin evaluaciones), o OpenLIT\n(un solo binario, nativa de OTEL). Para un flujo de trabajo impulsado por evaluaciones como este, los contenedores adicionales valen la pena; para un simple rastreo, uno de esos puede ser más adecuado para ti.
\nLa pila autoalojada de Langfuse consta de seis servicios (web + trabajador, ClickHouse, Postgres, Redis, almacenamiento de objetos), así que dale una Instancia WEC con ~15 GB de disco y 4 GB+ de RAM — no lo metas en una máquina que ya esté ocupada.
\ngit clone https://github.com/langfuse/langfuse.git && cd langfuse
Genera tres secretos y colócalos en un .env (la ENCRYPTION_KEY debe ser hex, o el contenedor web no arrancará):
cat > .env <<EOF
NEXTAUTH_SECRET=$(openssl rand -base64 32)
SALT=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
NEXTAUTH_URL=http://<tu-ip-de-instancia>:3000
EOF
docker compose up -d
docker compose ps
![\"La](\"https://wec.wiline.com/docs/es/assets/images/langfuse-deploy-ps-597bc541cd07b60e848e6c0dfe6246fc.png\")
\nFigura 1. docker compose ps — los seis servicios (web, trabajador, ClickHouse, Postgres, Redis, MinIO) en funcionamiento y saludables.
Si la máquina ya ejecuta algo en el puerto 3000 o 5432, Langfuse no arrancará (\"dirección ya en uso\"). Las bases de datos de respaldo no necesitan puertos de host en absoluto — edita docker-compose.yml para mover langfuse-web a un puerto de host libre (por ejemplo, 3001:3000) y elimina el mapeo del host de Postgres. Mantener tus bases de datos fuera de la red del host es una buena práctica de todos modos. Consulta Solución de problemas.
Abre http://<ip-de-instancia>:3000, crea una cuenta (el primer usuario es el propietario), luego una\nOrganización → Proyecto, y bajo Configuración → Claves API crea un par de claves\n(pk-lf-… / sk-lf-…).
Apunta el SDK de Langfuse a tu instancia y usa su OpenAI drop-in — rastrea automáticamente cualquier\nllamada compatible con OpenAI, incluida la API de Inferencia WEC, sin código adicional alrededor de cada solicitud:
\npython3 -m venv ~/lf-env && source ~/lf-env/bin/activate
pip install langfuse openai
export LANGFUSE_PUBLIC_KEY=\"pk-lf-…\"
export LANGFUSE_SECRET_KEY=\"sk-lf-…\"
export LANGFUSE_HOST=\"http://<ip-de-instancia>:3000\" # usa el puerto que expusiste — 3001 si lo remapeaste en el Paso 1
export WEC_API_KEY=\"sk-tu-clave-wec\"
import os
from langfuse.openai import openai # drop-in: rastrea automáticamente cada llamada
from langfuse import get_client
client = openai.OpenAI(
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
timeout=30, # SIEMPRE establece esto — un backend lento cuelga para siempre de lo contrario
)
def classify(ticket: str) -> str:
resp = client.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\",
name=\"ticket-classify\", # nombra el rastreo en Langfuse
messages=[{\"role\": \"user\", \"content\":
\"Clasifica este ticket de soporte. Devuelve SOLO JSON con claves \"
\"categoría (facturación/técnico/cuenta/otro), prioridad (baja/media/alta), \"
f\"resumen. Ticket: {ticket}\"}],
)
return resp.choices[0].message.content
if __name__ == \"__main__\":
print(classify(\"Me cobraron dos veces este mes.\"))
get_client().flush() # empuja los rastros antes de que el proceso termine
Ejecuta el código, luego abre Rastreo — la llamada aparecerá en segundos con entrada, salida, latencia, conteos de tokens, y (una vez que agreguemos precios) costo.
\n![\"Un](\"https://wec.wiline.com/docs/es/assets/images/langfuse-first-trace-f013e891fddc5d65b3525d5e1ad59fb7.png\")
\nFigura 2. Una llamada ticket-classify en Langfuse: el prompt, la salida JSON, latencia (~1.2s),\ny conteos de tokens — capturada sin código adicional alrededor de la solicitud.
El cliente de OpenAI no tiene un tiempo de espera predeterminado. Si el modelo es lento o el backend se detiene, tu\naplicación se cuelga indefinidamente — sin error, sin rastreo. timeout=30 convierte eso en un fallo rápido y visible.
Una llamada es fácil de registrar; no necesitas Langfuse para eso. El rastreo se justifica en funciones de múltiples pasos,\ndonde muestra toda la cadena como un solo árbol para que puedas ver qué paso falló. Hagamos\nque la función sea realista — clasifica el ticket, luego redacta una respuesta de esa categoría (dos llamadas WEC) —\ny agrúpalas en un solo rastreo con el decorador @observe:
from langfuse import observe, get_client
from app import client, classify # reutiliza el cliente WEC rastreado + clasificador
def draft_reply(ticket: str, category: str) -> str:
resp = client.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\",
name=\"draft-reply\",
messages=[{\"role\": \"user\", \"content\":
f\"Un cliente envió este ticket de {category}. Escribe una respuesta corta y útil.\\nTicket: {ticket}\"}],
)
return resp.choices[0].message.content
@observe() # agrupa todo lo que está debajo en UN solo rastreo
def handle_ticket(ticket: str) -> str:
category = classify(ticket) # child span 1
reply = draft_reply(ticket, category) # child span 2
return reply
if __name__ == \"__main__\":
print(handle_ticket(\"Me cobraron dos veces este mes.\"))
get_client().flush()
Abre ese rastreo y obtendrás un árbol: handle_ticket → ticket-classify → draft-reply, cada\nhijo con su propia entrada, salida, latencia y tokens. Ahora un fallo tiene una dirección — puedes\nseñalar el paso exacto que falló en lugar de adivinar (usamos esto en el Paso 5).
Ahora puedes ver dentro de cualquier llamada LLM en producción — entrada, salida, latencia, tokens — sin\nescribir una línea de código de registro.
Para obtener una señal real (no una llamada), empuja tu conjunto de datos de la parte 3 a través del clasificador para que el\ntablero tenga tráfico para analizar:
\nimport os, json
from langfuse.openai import openai
from langfuse import get_client
from app import classify # reutiliza la función rastreada
for line in open(os.path.expanduser(\"~/tickets_dataset.jsonl\")):
if line.strip():
classify(json.loads(line)[\"ticket\"])
get_client().flush()
Ahora el Tablero de inicio muestra rastreos a lo largo del tiempo, una distribución de latencia (p50/p95), tokens por\nmodelo, y un total de costos — la vista de \"observa en producción\".
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/langfuse-scores-dashboard-e46938c8695864fa98dc8afa0e488b3a.png\")
\nFigura 3. Después de reproducir el conjunto de datos de la parte 3: rastreos a lo largo del tiempo, una distribución de latencia, tokens\npor modelo, y un total de costos — la vista de \"observa en producción\".
Langfuse calcula automáticamente el costo para los modelos que conoce (OpenAI, Anthropic), pero la API de Inferencia WEC\nno devuelve costo en dólares y Langfuse no conoce los precios de los modelos de WEC — así que el costo muestra $0. Esta es\nla misma brecha que encontramos en parte 1. Soluciona esto una vez:\nConfiguración → Modelos → agregar un modelo que coincida con Qwen2.5-3B-Instruct con tus precios por token de entrada/salida.\nAhora cada rastreo y el tablero muestran el gasto real — el seguimiento de costos que Promptfoo\nno pudo darnos.
La evaluación de CI verifica un conjunto fijo. Aquí evaluamos cada llamada real automáticamente con un LLM-como-juez.\nEste paso parece pura configuración — también es donde encontramos y solucionamos el mejor error de la\nserie.
\nCrea el evaluador a través de Evaluadores → + Nuevo evaluador. Es un asistente de 3 pasos:
\n1. Seleccionar Evaluador — elige la plantilla de Correctitud LLM-como-juez.
\n2. Configurar conexión LLM — el juez necesita un modelo para llamar, y aún no hay ninguno, así que haz clic\n+ Agregar conexión LLM. El diálogo tiene más campos de los que esperarías — aquí está exactamente lo que necesita cada\nuno:
\nopenaiwec-judge) — solo el nombre de la conexión en Langfusehttps://inference.wiline.com/v1 — crítico; si se deja en blanco, golpea a OpenAI realQwen3.5:9B — la elección del modelo importa mucho aquí, como veráswec-judge y el modelo Qwen3.5:9B → Guardar.![\"El](\"https://wec.wiline.com/docs/es/assets/images/langfuse-llm-connection-e83545064c144db968575c7d85d0c809.png\")
\nFigura 4. El diálogo de Nueva Conexión LLM: adaptador openai, la URL base de la API WEC, modelos predeterminados apagados, y un modelo personalizado agregado — esto es lo que apunta al juez a WEC en lugar de\nOpenAI real.
3. Ejecutar Evaluador — agrega un filtro Nombre = ticket-classify, activa Ejecutar en observaciones entrantes en vivo para que evalúe el nuevo tráfico, y Ejecutar.
![\"La](\"https://wec.wiline.com/docs/es/assets/images/langfuse-evaluator-config-328cb01c6a061467eca223c1d7266d31.png\")
\nFigura 5. El evaluador de Correctitud — nombre de la evaluación, el filtro ticket-classify, y \"ejecutar en\nobservaciones entrantes en vivo.\"
Configuramos todo, enviamos tráfico fresco… y nada. Sin puntuación en ningún rastreo. Así es como lo\nrastreamos — puedes encontrar la misma pared:
\nRequest timed out after 120000ms. Cada ejecución, exactamente 120s — así que el juez sí se estaba activando, su\nllamada LLM simplemente nunca regresó.Qwen2.5-3B-Instruct, rechazó las llamadas a herramientas de inmediato\n(400 instantáneo — una configuración vLLM faltante en el backend; más sobre eso a continuación). Cambiamos a\nQwen3.5:9B, que responde a una llamada directa a la herramienta en ~3s. Aún así, se agotó el tiempo.curl desde el host: 200 en medio segundo. La misma solicitud de estilo juez desde dentro del contenedor trabajador: ~3s. Modelo, red, contenedor — todo bien.response_format) para que la puntuación regrese en un formato legible por máquina. Reproducir esa forma exacta de llamada expuso el problema: en este backend, las solicitudes de estilo juez al modelo de razonamiento son increíblemente lentas e impredecibles — la solicitud idéntica varió de 3 a 95 segundos en diferentes ejecuciones (el modelo \"piensa\" durante mucho tiempo, y el modo JSON añade sobrecarga). Con el prompt más largo del juez, las ejecuciones superaron el tiempo de espera predeterminado de 120s. Nada estaba roto — simplemente era más lento que el tiempo de espera.La solución son dos líneas de configuración. Langfuse lee su tiempo de espera LLM de\nLANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS (predeterminado 120000). Dale espacio:
services:
langfuse-worker:
environment:
LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: \"600000\"
langfuse-web:
environment:
LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: \"600000\"
docker compose up -d langfuse-worker langfuse-web
# verifica que se haya aplicado dentro del contenedor:
docker compose exec langfuse-worker env | grep TIMEOUT
Envía un nuevo rastreo a través de app.py, espera un par de minutos, y:
![\"La](\"https://wec.wiline.com/docs/es/assets/images/langfuse-score-on-trace-99653e359fac7e126dc097103602a4e5.png\")
\nFigura 6. Ahí está — Correctitud: 1.00 adjunta a un rastreo ticket-classify en vivo, con\nel razonamiento del juez a un clic de distancia. Cada nueva llamada ahora se evalúa automáticamente.
Ahora puedes evaluar automáticamente el tráfico real en producción — y depurar un evaluador que produce\nsilencio: verifica sus Registros, aísla modelo vs. red vs. contenedor, ajusta el tiempo de espera a la realidad.
El juez necesita llamadas a herramientas. Si tu modelo devuelve un 400 en cualquier solicitud de tools, eso\ngeneralmente es la configuración de servicio, no el modelo — en vLLM son las banderas --enable-auto-tool-choice y\n--tool-call-parser. Ese fue nuestro caso: lo informamos, el equipo de la plataforma habilitó las\nbanderas en Qwen2.5-3B-Instruct el mismo día, y el 400 desapareció. Solo la conexión del juez se ve afectada — tu aplicación mantiene su modelo.
La puntuación es lenta (~2 min/puntuación) y eso es el backend, no tú. El modelo de razonamiento \"piensa\"\ndurante mucho tiempo en los prompts del juez — vale la pena informarlo a tu equipo de plataforma (límites de presupuesto de razonamiento, o un backend de decodificación guiada como xgrammar en vLLM). El tiempo de espera elevado mantiene la puntuación confiable mientras tanto.
Una vez que se habilitó la llamada a herramientas en Qwen2.5-3B, lo intentamos como juez — las puntuaciones regresaron en\n2–10 segundos en lugar de ~2 minutos. Pero eran basura: el mismo tipo de respuesta correcta obtuvo\n1, 1, 0, y 0.05 en cuatro ejecuciones, con racionales casi idénticos adjuntos a puntuaciones opuestas. El modelo pequeño llena perfectamente el formato de puntuación; simplemente no puede evaluar realmente.\nImagen espejo del hallazgo de parte 3: el modelo pequeño gana en clasificación y pierde en evaluación — la evaluación es una tarea de razonamiento. Mantén el juez en Qwen3.5:9B: lento pero coherente.
Aquí es donde el árbol de spans da sus frutos. Abre un rastreo handle_ticket y no obtienes un solo blob opaco — obtienes la cadena completa como un árbol, cada paso con su propia entrada, salida, latencia y\ntokens:
![\"Profundizando](\"https://wec.wiline.com/docs/es/assets/images/langfuse-failing-trace-8fcb77412fc10f743dad85e747382695.png\")
\nFigura 7. El árbol handle_ticket — handle_ticket → ticket-classify → draft-reply — con\nlatencia y tokens por paso. Cada paso tiene una dirección que puedes inspeccionar.
Esa estructura es lo que hace que las fallas en producción sean depurables. Supongamos que un cliente recibe una respuesta sin sentido.\nSin rastreo solo sabrías \"la respuesta fue mala.\" Con el árbol lo expandes y lees cada paso — por ejemplo:
\nticket-classify → categoría: \"facturación\" ✅ correcto — así que el clasificador no es el problema.draft-reply → inventó una política de reembolso que no existe ❌ — el error está en el paso 2.Has localizado la falla en el paso exacto, entrada y salida — deberías corregir el prompt de draft-reply,\nno perder tiempo en el clasificador. La evaluación fuera de línea te dice que la tasa de aprobación cayó; el rastreo\nte dice qué llamada, con qué entrada, produjo qué salida incorrecta, en qué paso. Y ahora que el Paso 4 evalúa cada llamada, ni siquiera tienes que buscar: filtra el Rastreo por puntuación baja y los rastreos sospechosos emergen por sí mismos — a menudo una redacción que tu conjunto de datos de la parte 3 nunca cubrió, que es exactamente lo que capturas de vuelta a continuación.
Ahora puedes asignar una falla en producción al paso exacto, entrada y salida — no más adivinanzas\nsobre qué llamada inventó esa política de reembolso.
Una falla en producción es un caso de prueba faltante — y Langfuse hace que capturarlo sea un clic. Crea\nel conjunto de datos una vez (Conjuntos de datos → + Nuevo conjunto de datos, por ejemplo, fallas-en-producción), luego en cualquier rastreo haz clic en + Agregar a conjuntos de datos y selecciónalo. La entrada y salida del rastreo se completan automáticamente como un nuevo ítem:
![\"Agregando](\"https://wec.wiline.com/docs/es/assets/images/langfuse-dataset-loop-9e09a4627451a945e4df5245e6018fe7.png\")
\nFigura 8. \"Agregar a conjuntos de datos\" convierte un rastreo de producción en un nuevo caso de prueba — entrada y salida esperada completadas automáticamente — alimentándolo directamente de vuelta a tu conjunto de datos de la parte 3.
Para automatizarlo, extrae los rastreos que has marcado o agregado a un conjunto de datos a través del SDK de Langfuse, escribe\nfilas {ticket, categoría, prioridad} en tickets_dataset.jsonl, y vuelve a ejecutar la evaluación de Promptfoo de la parte 1/parte 3 — ahora cubre el caso del mundo real.
Ahora tu evaluación de CI es más fuerte porque la producción encontró un hueco en ella. Ese es el ciclo:\nevaluación fuera de línea → enviar → observar y evaluar tráfico real → capturar fallas → la evaluación fuera de línea se vuelve\nmás fuerte.
\nHas cerrado el ciclo: las fallas en producción ahora hacen que tus evaluaciones sean más fuertes — el ciclo que\nmantiene una función de IA buena después de que se envía.
Esa es la escalera de \"mantenerlo bien después del envío\". La evaluación fuera de línea (partes 1–3) prueba que funciona antes\ndel lanzamiento; esto prueba — y mantiene — que sigue funcionando después.
\ndocker compose upOtro servicio ocupa el puerto 3000 (web) o 5432 (Postgres). Las bases de datos no necesitan puertos de host —\nen docker-compose.yml, remapea langfuse-web a un puerto libre (3001:3000) y elimina el mapeo del host de Postgres. Compose fusiona las listas de ports, así que un archivo de anulación con ports: [] no las eliminará; edita el compose directamente.
Casi siempre ENCRYPTION_KEY — debe ser openssl rand -hex 32 (64 caracteres hexadecimales), no base64.\nVerifica docker compose logs langfuse-web.
$0Langfuse no tiene precio para los modelos de WEC por defecto. Agrega el modelo + precios por token bajo\nConfiguración → Modelos (Paso 3).
\nVerifica Evaluadores → tu evaluador → Registros primero — un error allí te dice que está ejecutándose y\nfallando, no inactivo. Luego empareja el error:
\ntool_choice — la llamada a herramientas no está habilitada para ese modelo en\nel backend de servicio (en vLLM: las banderas --enable-auto-tool-choice / --tool-call-parser).\nDos formas de salir: apunta la Conexión LLM del juez a un modelo donde funcione (Qwen3.5:9B), o pide\na tu equipo de plataforma que habilite las banderas — eso es lo que solucionó Qwen2.5-3B-Instruct para nosotros. De cualquier manera, solo cambia el juez — tu aplicación mantiene su modelo.Request timed out after 120000ms — la llamada de salida estructurada del juez es más lenta que\nel tiempo de espera predeterminado de Langfuse. Aumenta LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS (Paso 4) y\nconfirma con docker compose exec langfuse-worker env | grep TIMEOUT. Si curl simple es rápido\npero la puntuación aún se agota, no persigas la red — la ruta de salida estructurada es lo que es\nlento, y eso es una solución del backend.Eso no es un colapso — es el modelo de razonamiento generando una larga cadena de pensamiento oculta en los prompts del juez (altamente variable: la misma solicitud puede tardar 3s o 95s), además de la sobrecarga de salida estructurada.\nAumentar el tiempo de espera hace que la puntuación sea confiable pero no rápida — la verdadera solución está del lado de la plataforma\n(límites de presupuesto de razonamiento, backend de decodificación guiada).
\nAhora puedes construir, probar, observar y mejorar una sola función WEC. La última escalera es el verdadero\npatrón de aplicación: RAG — recuperación + generación — con todo de las partes 1–4 integrado\n(salida verificada por esquema, un conjunto de datos de evaluación, y rastreo de Langfuse sobre todo el pipeline). Ahí es donde todo se une.
\n++Tu evaluación pasa el 100% — de los dos casos de prueba que escribiste a mano. Los usuarios reales no expresarán las cosas como tú lo hiciste.
\nEn parte 1 y\nparte 2 construimos un arnés de evaluación real —\nafirmaciones, validación de esquema, una matriz de modelos. Pero dos casos no pueden decirte si tu aplicación funciona;\nsolo pueden decirte que no se bloqueó con dos entradas.
\nEsta guía soluciona eso. La habilidad es producir un conjunto de datos en el que realmente puedas confiar: usamos la\nAPI de Inferencia de WEC para generar tickets etiquetados, luego validarlos y curarlos — porque\nlas etiquetas generadas no son automáticamente correctas, y tratarlas como verdad solo mueve el error.\nEl resultado es datos de prueba reales a gran escala. Cuando finalmente lo ejecutes a través del arnés de la parte 2, la cobertura\nrevela las fallas — malas clasificaciones genuinas y etiquetas debatibles — que dos casos seleccionados a mano ocultan.
\n\nCada paso alimenta al siguiente, terminando en un conjunto de datos que se conecta directamente a la evaluación de la parte 2:
\n\nUna clave de API de Inferencia de WEC — consulta Inferencia → Claves de API.
\njq, curl, y Node.js 22+ (Promptfoo se ejecuta a través de npx).
Tu clave exportada y saneada (una clave pegada a menudo lleva caracteres invisibles):
\nexport WEC_API_KEY='sk-your-key'
export WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
Si una llamada devuelve un 401 / \"clave de API inválida\", tu clave ha expirado o ha sido revocada — genera una\nnueva en Inferencia → Claves de API. Consulta Solución de problemas.
Pide al modelo tickets con sus respuestas — las etiquetas son lo que lo convierte en un conjunto de datos, no\nsolo entradas. Reutilizamos el esquema exacto de la parte 2 (category + priority enums):
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen2.5-3B-Instruct\",
\"temperature\": 0.7,
\"messages\": [{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]
}' | jq -r '.choices[0].message.content'
{\"ticket\":\"Nuestro servidor se cayó inesperadamente y no estamos seguros de qué lo causó.\",\"category\":\"technical\",\"priority\":\"high\"}
{\"ticket\":\"Necesitamos actualizar nuestro plan pero el sistema muestra un mensaje de error al intentar cambiar de planes.\",\"category\":\"account\",\"priority\":\"medium\"}
{\"ticket\":\"Estamos teniendo problemas para acceder a nuestra base de datos y no podemos iniciar sesión.\",\"category\":\"technical\",\"priority\":\"high\"}
... 5 líneas más ...
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/dataset-gen-batch-adc9c63dcd4af4c2991e7581ea5908ec.png\")
\nFigura 1. Una única generación: 8 tickets diversos, cada uno ya llevando su etiqueta de category y priority.
JSONL limpio, etiquetas válidas, verdadera diversidad — y regresó en segundos. Elegimos deliberadamente un\nmodelo pequeño y no razonador (Qwen2.5-3B-Instruct) para la generación. Aquí está el porqué de su importancia.
Los modelos razonadores devuelven su cadena de pensamiento en un campo separado reasoning_content — tokens\npor los que pagas pero que nunca usas. Pide a un modelo razonador como Qwen3.5:9B algunos tickets y compara el\nrazonamiento oculto con la respuesta real:
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen3.5:9B\",\"temperature\":0.7,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 3 tickets de soporte al cliente realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL, claves: ticket, category, priority. Sin markdown, sin cercas.\"}]}' \\
| jq '{model, completion_tokens: .usage.completion_tokens, reasoning_chars: (.choices[0].message.reasoning_content|length), answer_chars: (.choices[0].message.content|length)}'
{
\"model\": \"Qwen3.5:9B\",
\"completion_tokens\": 2000,
\"reasoning_chars\": 7116,
\"answer_chars\": 412
}
![\"La](\"https://wec.wiline.com/docs/es/assets/images/dataset-gen-usage-5ee23a331ab19ce10dfddd509162743d.png\")
\nFigura 1b. Para solo 3 tickets, Qwen3.5:9B escribió 7,116 caracteres de razonamiento oculto para\nproducir 412 de respuesta — pagas por todos los ~2,000 tokens de finalización. (Los conteos varían por llamada; la\nasimetría no.) Por eso generamos con el pequeño y no razonador Qwen2.5-3B — y es la misma razón por la que esos modelos razonadores tropiezan con la salida estructurada en la matriz de la Parte 5.
Nunca trates los datos generados como verdad absoluta sin verificarlos. Guarda un lote y valida tres\ncosas: cada línea se analiza, cada etiqueta está en el enum, y las clases están razonablemente equilibradas.
\ncurl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen2.5-3B-Instruct\",\"temperature\":0.7,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]}' \\
| jq -r '.choices[0].message.content' > tickets.jsonl
# 1) ¿todas las líneas se analizan como JSON?
jq -e . tickets.jsonl > /dev/null && echo \"todas las líneas son JSON válidos\" || echo \"JSON INVÁLIDO presente\"
# 2) ¿hay etiquetas fuera del enum? (sin filas impresas = todas válidas)
jq -c 'select((.category|IN(\"billing\",\"technical\",\"account\",\"other\")|not) or (.priority|IN(\"low\",\"medium\",\"high\")|not))' tickets.jsonl
# 3) distribución de clases
jq -rs 'group_by(.category)[] | \"\\(.[0].category): \\(length)\"' tickets.jsonl
todas las líneas son JSON válidos
account: 2
billing: 2
other: 1
technical: 3
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/dataset-validate-9b1201646866c2062c5e9aa3d093cfd2.png\")
\nFigura 2. Salida de validación — cada línea se analiza, sin etiquetas fuera del enum, y una distribución de clases razonable.
El intuitivo [\"billing\",...] | index(.category) falla con \"No se puede indexar un array con\ncadena\" — dentro del pipe, . es el array, así que .category intenta indexarlo. Usa\n.category | IN(\"billing\", ...) en su lugar. Consulta Solución de problemas.
Un lote de 8 no es suficiente. Repite la llamada varias veces (temperatura más alta para variedad entre\nlotes), concatena, y luego elimina duplicados por texto del ticket:
\nfor i in $(seq 1 5); do
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen2.5-3B-Instruct\",\"temperature\":0.9,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]}' \\
| jq -r '.choices[0].message.content // empty'
echo \"lote $i hecho\" >&2
done > tickets_raw.jsonl
# eliminar duplicados por texto del ticket
jq -sc 'unique_by(.ticket)[]' tickets_raw.jsonl > tickets_dataset.jsonl
echo \"crudo: $(wc -l < tickets_raw.jsonl) → deduplicado: $(wc -l < tickets_dataset.jsonl)\"
crudo: 40 → deduplicado: 40
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/dataset-scale-dedupe-74ac55864b3da488aa334816e11ede4a.png\")
\nFigura 3. Escalando: 5 lotes → 40 filas después de la eliminación de duplicados exactos.
Cero duplicados exactos en 5 lotes — una buena señal de que el modelo no se está repitiendo.
\nunique_by(.ticket) solo captura texto idéntico. Dos tickets \"el servidor está caído\" redactados de manera diferente son duplicados semánticos y se deslizarán — capturarlos requiere agrupamiento basado en incrustaciones, un paso más avanzado. Para un conjunto de datos inicial, la deduplicación exacta está bien.
Nota el // empty en el filtro jq. Si una llamada falla (clave revocada, tiempo de espera del modelo), la\nrespuesta no tiene contenido y .choices[0].message.content es null — un simple jq -r escribiría la palabra literal null en tu conjunto de datos, envenenándolo silenciosamente. // empty elimina esos,\nasí que una llamada fallida agrega nada en lugar de una fila basura. Siempre verifica el conteo de filas después.\nConsulta Solución de problemas.
Valida las 40 completas de la misma manera que en el Paso 2 (jq -e ., la verificación del enum, y ambas distribuciones).\nLas nuestras resultaron equilibradas: técnico 15 · cuenta 10 · facturación 10 · otro 5; prioridad alta 13 ·\nmedia 14 · baja 13.
Ahora tienes un pipeline repetible para datos de prueba reales — 40 filas etiquetadas, validadas y deduplicadas\ndonde antes tenías dos.
Promptfoo lee casos de prueba desde un CSV: cada columna se convierte en una variable, y la columna especial\n__expected contiene una afirmación por fila. Mapeamos ticket → la variable de prompt y\n__expected → icontains:<la categoría correcta>. jq @csv maneja las comas y comillas\ndentro del texto del ticket:
{ echo 'ticket,__expected'; jq -r '[.ticket, (\"icontains:\" + .category)] | @csv' tickets_dataset.jsonl; } > tests.csv
wc -l tests.csv # 41 = encabezado + 40 filas
El conjunto de datos es el entregable — todo desde aquí es lo que desbloquea. Primer beneficio: una comparación de modelos\nen la que realmente puedes confiar. En dos casos escritos a mano, un ranking es ruido; en 40 filas reales,\netiquetadas es una medición. Agrega cada modelo WEC como proveedor y ejecuta todo el conjunto:
\ncat > promptfooconfig.yaml <<'EOF'
description: \"Clasificador de tickets — matriz de modelos sobre el conjunto de datos sintético de 40 filas\"
providers:
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen3.5-122B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"category\" (uno de: billing, technical, account, other),
\"priority\" (uno de: low, medium, high),
\"summary\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
const m = output.match(/\\{[\\s\\S]*?\\}/);
return m ? m[0] : output;
assert:
- type: is-json
value:
type: object
required: [category, priority, summary]
properties:
category: { type: string, enum: [billing, technical, account, other] }
priority: { type: string, enum: [low, medium, high] }
summary: { type: string }
tests: file://tests.csv
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
El resultado es lo opuesto a lo que \"más grande es mejor\" predeciría:
\n| Modelo | Precisión | Tokens de finalización / ticket |
|---|---|---|
Qwen2.5-3B-Instruct (no razonador) | 85% (34/40) | ~30 |
Qwen3.5:9B (razonador) | 47.5% (19/40) | ~965 |
Qwen3.5-122B (razonador) | 15% (6/40) | ~1,013 |
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/dataset-eval-matrix-9ffe20345f2040803fce117f6803a6ff.png\")
\nFigura 4. Mismo conjunto de datos, tres modelos — el pequeño modelo no razonador gana por mucho.
El pequeño modelo no razonador gana decisivamente — y cuanto más grande es el modelo razonador, peor\nlo hace. Los modelos razonadores no son más tontos al clasificar; enterraron el JSON en su\ncadena de pensamiento. Qwen3.5:9B filtra Thinking: … en la salida; Qwen3.5-122B a menudo devuelve\nuna respuesta vacía por completo — todos los ~1,000 tokens gastados razonando, nada parseable queda. También\nqueman ~30× más tokens por ticket, razón por la cual la matriz completa tomó 12m 31s, casi todo\nel tiempo esperando a los dos grandes modelos. Para salida estructurada, pensar en voz alta es una desventaja,\nno una ventaja — un hallazgo contraintuitivo que nunca obtendrías de una tabla de clasificación.
Pero nota lo que realmente hizo posible ese hallazgo: el conjunto de datos. Con dos casos escritos a mano esos\nporcentajes serían lanzamientos de moneda; 40 filas etiquetadas son lo que convierte \"¿qué modelo?\" de una suposición en una\nmedición. La comparación es la recompensa por construir los datos — no un sustituto de ellos.
\nAhora puedes elegir un modelo con evidencia en lugar de sensaciones — algo que ninguna tabla de clasificación puede hacer por\nti, porque no conoce tu tarea.
(El transform captura el primer bloque {…} con una coincidencia no codiciosa *? — un seguro barato para\nmodelos que envuelven JSON en prosa, exactamente como en parte 2.)
category aquí — priority es tu próxima afirmaciónLa columna __expected califica solo la categoría predicha contra la etiqueta. El conjunto de datos también\nlleva una etiqueta de priority que aún no calificamos. Para calificar ambos campos a la vez, agrega una\nafirmación de javascript que analice la salida JSON y compare también priority — el mismo patrón exacto, una verificación más.\nCalificar más de lo que generaste es la forma más barata de hacer una evaluación más estricta.
Toma el ganador — Qwen2.5-3B con 85% (34/40) — y extrae sus 6 tickets fallidos, comparando cada uno\ncon su etiqueta. (__expected no se almacena como una variable — Promptfoo lo consume como la afirmación —\nasí que lee la verdad de la fuente de datos). Debido a que los datos son recién generados, tus fallas exactas\ndiferirán, pero se dividen consistentemente en dos tipos reconocibles — y ninguno es solo \"el modelo es tonto\". Ejemplos representativos:
![\"El](\"https://wec.wiline.com/docs/es/assets/images/dataset-report-541b1a9921d846d5338c1b1547c49bd5.png\")
\nFigura 5. El informe web facilita escanear qué filas fallaron y abrir cada una.
| Ticket | Etiqueta | Por qué es complicado |
|---|---|---|
| \"descuentos educativos para startups…\" | other | Debatible — se trata de precios, así que billing es defensible |
| \"otorgar acceso IAM a S3 a un desarrollador junior…\" | account | Debatible — control de acceso vs infraestructura |
| \"comentarios sobre la documentación de la API…\" | other | Debatible — comentarios vs technical |
| \"actualizar la tarjeta y agregar un usuario…\" | account | Multi-intención — genuinamente dos categorías a la vez |
El resto son malas clasificaciones ordinarias. Las lecciones reales, del día a día:
\nCompromete tickets_dataset.jsonl y tests.csv junto a tu configuración de evaluación, y regenera/crece\nel conjunto de datos a medida que tu producto cambia.
{ \"error\": { \"message\": \"Error de autenticación, clave de API inválida\", \"code\": \"401\" } }
La clave ha expirado, ha sido revocada o está mal formada. Genera una nueva en Inferencia → Claves de API,\nreexporta y vuelve a sanear (tr -cd '[:print:]') en caso de que el pegado haya llevado un carácter invisible.
Esto proviene de [\"billing\", ...] | index(.category) — dentro del pipe, . es el array, así que\n.category indexa el array. Usa el idiom IN() en su lugar:
jq -c 'select((.category|IN(\"billing\",\"technical\",\"account\",\"other\")|not))' tickets.jsonl
![\"El](\"https://wec.wiline.com/docs/es/assets/images/dataset-ts-jq-index-ec85a2581780363d791db73ff2f03fd0.png\")
\nFigura 6. El error de index(.field) — dentro del pipe, jq intenta indexar el array con una cadena.
nullUna fila null significa que una llamada de generación falló pero el bucle aún escribió su resultado (vacío). Causas habituales: una clave de API expirada/revocada, o el modelo que se agota. Soluciones: extraer con\n.choices[0].message.content // empty para que una llamada fallida escriba nada en lugar de null;\nvuelve a verificar wc -l después de cada ejecución de generación; y si las llamadas se cuelgan, agrega un tiempo de espera por solicitud\n(curl -m 60) y considera un modelo más ligero y rápido para la generación masiva.
__expected es null en el JSON de resultadosEso es esperado — Promptfoo consume la columna __expected del CSV como la afirmación de la fila, así que\nno se mantiene como una variable. Para inspeccionar las etiquetas de verdad para las filas que fallan, léelas de tu\nconjunto de datos fuente (tickets_dataset.jsonl) en lugar del archivo de resultados.
Ahora tienes un conjunto de datos real — pero se ejecuta en CI, fuera de línea. El siguiente paso es observar tu aplicación en\nproducción: autoalojar Langfuse para rastrear cada llamada, seguir la latencia y el costo, y ejecutar\nevaluaciones (usando este conjunto de datos) contra el tráfico en vivo. Ahí es donde las pruebas fuera de línea se convierten en\nuna verdadera observabilidad — y es la próxima publicación de la serie.
", "url": "https://wec.wiline.com/docs/es/tutorials/synthetic-eval-datasets-wiline-inference/", "title": "Deja de escribir casos de prueba a mano: genera un conjunto de evaluación con la API de WEC", "summary": "Dos casos de prueba escritos a mano no son una evaluación. Usa la API de Inferencia de WEC para generar un conjunto de datos de evaluación etiquetado — luego valídalo y curátalo, porque las etiquetas generadas no son automáticamente correctas. El resultado es datos de prueba reales a gran escala; aliméntalo a tu arnés y la cobertura revela las malas clasificaciones y las etiquetas debatibles que dos casos ocultarían. Cada comando y resultado es real.", "date_modified": "2026-07-06T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "evals", "promptfoo", "inference", "datasets", "synthetic-data", "observability" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/structured-output-evals-wiline-inference/", "content_html": "++\"Devuelve solo JSON\" es una de las instrucciones más comunes en aplicaciones LLM en producción — y una de las menos fiables. Los modelos envuelven JSON en cercas de markdown, añaden una frase amigable, o (si son modelos de razonamiento) narran todo su proceso de pensamiento alrededor de ello. Cualquiera de esos casos rompe un estricto JSON.parse, y tu pipeline se cae.
En esta guía construimos una evaluación de Promptfoo que hace que los modelos de API de Inferencia WEC clasifiquen tickets de soporte en JSON validado por esquema, luego lo endurecemos contra el desorden del mundo real — y lo usamos para elegir un modelo en el que realmente puedes confiar. Esta es la parte 2 de la serie de evaluaciones (consulta parte 1 para la configuración inicial). Todo aquí se ejecutó en vivo contra https://inference.wiline.com.
Cada prueba pasa por el mismo pipeline. El detalle que más importa: el transform se ejecuta en la salida del modelo antes de que la afirmación la vea — eso es lo que nos permite recuperar JSON desordenado antes de validarlo.
Una clave de API de Inferencia WEC — consulta Inferencia → Claves de API.
\nLos nombres de los modelos utilizados aquí (GLM-5.2, gemma4, Qwen2.5-3B-Instruct, qwen3.5:9B) provienen del Hub de Modelos — intercambia por lo que hayas habilitado.
Node.js 22+ y tu clave exportada (Promptfoo se ejecuta a través de npx):
nvm use 24
export WEC_API_KEY='sk-tu-clave'
Si tu primera ejecución da error con Cannot convert argument to a ByteString, tu clave pegada tiene un carácter invisible — consulta Solución de problemas al final.
Haremos algo más cercano a una carga de trabajo real que \"capital de Francia\": clasificar un ticket de soporte en categoría, prioridad y un breve resumen. La mejora clave sobre una verificación básica es el Esquema JSON — impone enums, por lo que un modelo que inventa una categoría falla.
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — salida estructurada (esquema JSON)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
El resultado — 50%, y el fallo es instructivo:
\nticket [zai-org/GLM-5.2]
Me cobraron dos veces por mi instancia… [FALLIDO] ```json
{ \"categoría\": \"facturación\", \"prioridad\": \"alta\", … }
```
Mi VM no arranca después de la última… [APROBADO] { \"categoría\": \"técnica\", … }
✓ 1 aprobado (50%) ✗ 1 fallido (50%)
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-step1-schema-fail-dc2b9c12c0ee29b0086499d5c76f2fd6.png\")
\nFigura 1. Mismo modelo, mismo aviso, temperatura 0 — una respuesta es limpia, la otra está envuelta en ```json cercas, por lo que is-json no puede analizarla.
El contenido es correcto; el formato no lo es. is-json valida tanto \"¿es JSON analizable?\" como \"¿cumple con el esquema?\" — y la salida cercada falla la primera prueba.
transformUn transform se ejecuta en la salida del modelo antes de las afirmaciones. Aquí eliminamos las cercas.\n(Este bloque utiliza cuatro comillas porque la configuración en sí contiene tres comillas).
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — transformación de eliminación de cercas\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
return output.replace(/```json\\n?|\\n?```/g, '').trim();
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Ahora ambos pasan — 2/2. Las cercas se eliminan antes de que is-json vea la salida.
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-step2-transform-pass-14cb388c6725d0aacffeee1bb320f553.png\")
\nFigura 2. El transform elimina las cercas de código, por lo que el ticket que antes fallaba se analiza.
transform necesita un return explícitoUn transform de varias líneas es un cuerpo de función, no una expresión — omite return y obtienes Transform function did not return a value. Consulta Solución de problemas.
En lugar de limpiar después del modelo, pide a la API que emita solo JSON válido a través de response_format. Sin transform esta vez:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — modo JSON (response_format)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
response_format: { type: json_object }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
2/2 APROBADO sin transformación — parece que el modo JSON funciona.
\n![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-step3-jsonmode-6cabcc01d214aaa3b14b1a0842eeb720.png\")
\nFigura 3. Con response_format: json_object, GLM-5.2 devuelve JSON limpio, sin necesidad de transformación.
Pero antes de confiar en response_format, necesitamos probarlo en todos los modelos — porque un solo resultado verde puede ser suerte, no cumplimiento.
Ejecuta la configuración en modo JSON contra los cuatro modelos de chat. Este es el beneficio — una comparación de fiabilidad específica de WEC que no puedes obtener de una tabla de clasificación genérica.
\ncat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — fiabilidad en modo JSON entre modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
4/8. GLM-5.2 y Qwen2.5-3B pasan limpiamente; gemma4 y qwen3.5:9B vierten su razonamiento\n(\"Proceso de Pensamiento…\") en lugar de JSON — a pesar de que response_format está configurado.
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-matrix-responseformat-d227b3a1ca8bffbf85f89ca2da11eb87.png\")
\nFigura 4. response_format configurado en los cuatro — pero los dos modelos orientados al razonamiento lo ignoran.
| Modelo | Resultado | Tokens (2 llamadas) |
|---|---|---|
zai-org/GLM-5.2 | ✅✅ | 202 |
Qwen2.5-3B-Instruct | ✅✅ | 243 |
gemma4 | ❌❌ (razonamiento) | 251 |
qwen3.5:9B | ❌❌ (razonamiento) | 1,757 |
Ahora puedes medir qué modelos realmente honran el modo JSON — en lugar de confiar en la bandera.
response_format haciendo algo?No asumas que el razonamiento fue causado por el modo JSON. Vuelve a ejecutar la misma matriz sin\nresponse_format (usando la transformación de eliminación de cercas en su lugar) y compara:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — matriz sin response_format\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
return output.replace(/```json\\n?|\\n?```/g, '').trim();
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Sigue siendo 4/8 — los mismos modelos fallan. Así que response_format no cambió nada: en WEC hoy es efectivamente un no-op (el backend no está haciendo cumplir el modo JSON). El comportamiento de razonamiento pertenece a los modelos, no a la bandera.
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-matrix-transform-77179c366ad47c9eb5b00fe2b5d92381.png\")
\nFigura 5. Resultado idéntico sin modo JSON — la bandera no estaba haciendo nada.
Lección que merece su propio llamado: no atribuyas un resultado a un cambio hasta que hayas probado el cambio en aislamiento. Una ejecución adicional convirtió una conclusión incorrecta en la correcta.
Los modelos de razonamiento sí emiten JSON — simplemente está enterrado en prosa. En lugar de eliminar cercas,\nextrae el primer bloque { … } de cualquier parte de la salida:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — transformación de extracción de JSON\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
const m = output.match(/\\{[\\s\\S]*\\}/);
return m ? m[0] : output;
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
7/8 — un gran salto. gemma4 y Qwen2.5 recuperan completamente; qwen3.5:9B recupera uno de dos. El\núnico fallo restante es revelador: esa respuesta emitió JSON y luego siguió razonando (con\nmás llaves), por lo que la coincidencia codiciosa { … } capturó en exceso y produjo JSON inválido.
![\"Paso](\"https://wec.wiline.com/docs/es/assets/images/json-matrix-extraction-3b34ee4a32f6990e447d9590d51d8911.png\")
\nFigura 6. Extraer el bloque JSON recupera los modelos habladores — pero es una heurística, no una garantía (nota el único fallo por captura excesiva).
La tabla del terminal está bien para una lectura rápida, pero el informe web es donde una matriz como esta cobra vida:
\nnpx -y promptfoo@latest view
El panel en la parte superior te da la imagen de fiabilidad del modelo de un vistazo — las barras de Tasa de Aprobación (%) son las que debes observar aquí: tres modelos altos, qwen3.5:9B sentado en 50%.\nA continuación, cada proveedor es una columna que puedes expandir para ver la salida completa (así es como obtuvimos el fallo por captura excesiva en Figura 10 — el terminal lo trunca).
![\"El](\"https://wec.wiline.com/docs/es/assets/images/json-view-report-3739e5abd8419ffc8ece8271ff559851.png\")
\nFigura 7. El panel del informe — las barras de Tasa de Aprobación convierten la matriz de modelos en un ranking de un vistazo, y cualquier celda se expande a la salida completa.
Los otros gráficos del informe (el dispersor de aviso frente a aviso) brillan cuando estás A/B-testando\navisos, no modelos — un buen tema para una publicación posterior. Para una ejecución de un solo aviso y múltiples modelos como esta, las barras de Tasa de Aprobación son el gráfico que importa.
Promptfoo sale con un código no cero cuando las pruebas fallan, así que una línea es una puerta (ponlo en un script o\nMakefile, nunca en tu shell interactivo):
npx -y promptfoo@latest eval -c promptfooconfig.yaml \\
&& echo \"✅ aprobado\" \\
|| { echo \"❌ evaluación fallida — bloqueando\"; exit 1; }
![\"La](\"https://wec.wiline.com/docs/es/assets/images/json-ci-gate-71912b506157c96cfd7daa8e5c81f300.png\")
\nFigura 8. Un fallo real bloquea: 7/8 aprobados, pero la captura excesiva de qwen3.5:9B (del Paso 6)\ndispara la puerta — el código de salida no cero es la señal que CI usa para bloquear un PR.
En GitLab:
\neval:
image: node:22
script:
- npx -y promptfoo@latest eval -c promptfooconfig.yaml
# WEC_API_KEY configurada como una variable CI/CD enmascarada — nunca comprometida.
JSON validado por esquema es ahora una puerta CI — un cambio en el modelo o aviso que rompe el análisis nunca se envía.
GLM-5.2 y Qwen2.5-3B producen JSON válido por esquema de manera fiable\ny son ~8× más baratos que los modelos de razonamiento. Para salida estructurada en WEC, comienza allí.qwen3.5:9B, y gemma4 en el día que probamos) narran su pensamiento\ny cuestan mucho más — malas opciones para JSON estricto.transform es tu red de seguridad — la eliminación de cercas recupera el caso común; la extracción de JSON\nrecupera la mayoría de las salidas habladoras — pero la extracción es una heurística que puede capturar en exceso.response_format es un no-op en WEC hoy — verificado al aislarlo. No confíes en ello;\nvalida en su lugar.Un transform de varias líneas se compila como un cuerpo de función, por lo que necesita un return explícito. output.replace(...) por sí solo no devuelve nada.
options:
transform: |
return output.replace(/.../g, '').trim(); # nota el `return`
![\"El](\"https://wec.wiline.com/docs/es/assets/images/json-ts-transform-return-764896c26bc05d65d37eac7808ee06fb.png\"){kind=spacer}
\nFigura 9. Sin return, Promptfoo da error en lugar de transformar.
Si is-json falla con \"Se esperaba que la salida fuera JSON válido\" y la respuesta contiene una\nnarración de \"Proceso de Pensamiento…\" / \"Revisión Final…\", estás usando un modelo de razonamiento. A veces emite solo razonamiento; a veces — como a continuación — emite JSON válido y luego sigue hablando, por lo que incluso la extracción del Paso 6 captura en exceso y el análisis falla. Opciones: cambia a\nGLM-5.2 / Qwen2.5-3B, o acepta que la transformación de extracción es un esfuerzo de buena fe, no una garantía.
![\"El](\"https://wec.wiline.com/docs/es/assets/images/json-ts-reasoning-dump-dbfebf9e8d4f5f89e6b2e14b8e0edf50.png\")
\nFigura 10. El caso fallido expandido en el informe: qwen3.5:9B devolvió JSON válido y\ndespués siguió razonando (\"7. Revisión Final…\"), por lo que la extracción capturó en exceso y la afirmación informa \"Se esperaba que la salida fuera JSON válido.\"
Tu clave de API pegada contiene un carácter Unicode invisible. Elimínalo:
\nexport WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
![\"El](\"https://wec.wiline.com/docs/es/assets/images/json-ts-bytestring-0bb4979ce94f0775f1fe314315b38e01.png\")
\nFigura 11. Un carácter extraño en la clave activa el encabezado HTTP antes de que se envíe cualquier solicitud.
¿Tienes un caso de salida estructurada que aún se escapa? Esa es la próxima prueba que agregar.
", "url": "https://wec.wiline.com/docs/es/tutorials/structured-output-evals-wiline-inference/", "title": "JSON confiable: valida el esquema de la salida estructurada de tu modelo", "summary": "Los LLM prometen JSON y entregan cercas de markdown y razonamiento. Construye una evaluación de Promptfoo que clasifique tickets de soporte en JSON validado por esquema en la API de Inferencia WEC — con transformaciones para recuperar salidas desordenadas, una matriz de fiabilidad del modelo y una puerta CI. Cada comando y resultado es real.", "date_modified": "2026-07-01T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "evals", "promptfoo", "inference", "json", "structured-output", "observability" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/eval-models-promptfoo-wiline-inference/", "content_html": "\n+No enviarías código sin pruebas — pero la mayoría de los equipos envían funciones LLM con \"se ve bien para mí.\" Evaluaciones (evals) solucionan eso: defines casos de prueba y criterios de aprobación/fallo, luego mides tu modelo objetivamente — detectando regresiones, comparando modelos y bloqueando despliegues.
\nEn esta guía construirás un verdadero arnés de evaluación con Promptfoo apuntando a la API de Inferencia WEC — el mismo punto final compatible con OpenAI que llamas desde tus aplicaciones. Todo aquí se ejecutó en vivo contra https://inference.wiline.com; las salidas son reales.
Una cuenta de WEC (WiLine Edge Cloud) y una clave API de Inferencia — consulta Inferencia → Claves API.
\nNode.js 22+. Promptfoo considera que Node 20 está al final de su vida útil; con nvm:
nvm install 24 # 24 LTS preferido
nvm use 24
node -v # v24.x
Ejecutaremos Promptfoo con npx — nada que instalar globalmente.
![\"La](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-api-key-a1aca6bfffa7335651ab59ec1c07d8f4.png\")
\nFigura 1. Crea una clave en Inferencia → Claves API, luego cópiala.
Pon tu clave en la terminal:
\nexport WEC_API_KEY='sk-your-key-here'
Si tu primera evaluación falla con Cannot convert argument to a ByteString, consulta Solución de problemas #1 a continuación.
La API es compatible con OpenAI, por lo que la lista de modelos es un simple GET /v1/models:
curl -s https://inference.wiline.com/v1/models \\
-H \"Authorization: Bearer $WEC_API_KEY\" | jq -r '.data[].id'
zai-org/GLM-5.2
gemma4
Qwen2.5-3B-Instruct
qwen3.5:9B
whisper-large-v3
whisper-medium
whisper-base
Los modelos whisper-* son de voz a texto; el resto son modelos de chat. Evaluaremos los modelos de chat, comenzando con zai-org/GLM-5.2.
Crea una configuración. apiBaseUrl apunta Promptfoo a WEC; apiKeyEnvar le dice qué variable de entorno contiene tu clave:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-first-eval-42c0a9a515e6a1e5af7a6cf5c6a30118.png\")
\nFigura 4. Tu primera evaluación aprobada contra la API de Inferencia WEC.
icontains es una afirmación determinista — una verificación de subcadena que no distingue entre mayúsculas y minúsculas. Barata, rápida y perfecta para hechos con una respuesta conocida.
npx -y promptfoo@latest view
Esto abre una interfaz web local con cada aviso, salida y aprobación/fallo — mucho más fácil de escanear que la terminal una vez que tienes más de unos pocos casos.
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-view-report-b93aa9bcadc4c60e008df1bb5effcd3c.png\")
\nFigura 5. promptfoo view — los mismos resultados en el navegador.
Agregar un proveedor es un bloque adicional. Aquí agregamos Qwen2.5-3B-Instruct junto a GLM-5.2 y ejecutamos los mismos dos casos de prueba contra ambos:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — comparación de modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
- id: openai:chat:Qwen2.5-3B-Instruct
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-two-model-3c6c51ea8839c03dd51d270c78648ec9.png\")
\nFigura 6. Ambos modelos aprueban. Los resultados de GLM-5.2 se sirven desde caché (0 nuevas solicitudes); solo Qwen2.5 realiza llamadas en vivo.
Las verificaciones de subcadenas no pueden juzgar una respuesta abierta. Una afirmación llm-rubric calificada por el modelo utiliza un modelo para puntuar la salida contra criterios — y el calificador puede ejecutarse en WEC también, por lo que no necesitas un proveedor externo:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — calificación por modelo (rúbrica LLM)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
defaultTest:
options:
provider: # el modelo calificador
id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
prompts:
- \"Explica qué es un {{topic}} en dos oraciones, para un principiante.\"
tests:
- vars: { topic: VPC }
assert:
- type: llm-rubric
value: \"Describe una VPC como una red virtual privada e aislada en la nube, y es comprensible para un principiante.\"
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-llm-rubric-f969ad98a43427eacf9f83f13f2e6dde.png\")
\nFigura 7. La ejecución muestra dos líneas de tokens — Eval (75) y Grading (350) — porque la verificación de rúbrica es en sí misma una llamada de modelo.
Las verificaciones calificadas por el modelo son poderosas, pero no son gratuitas.
\nUna respuesta correcta que toma 30 segundos sigue siendo un problema de producción. Agrega un límite de latencia a defaultTest (se aplica a cada caso). Siempre ejecuta con --no-cache — las respuestas en caché informan ~0 ms y pasarían la puerta gratis:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — límite de latencia\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
defaultTest:
assert:
- type: latency
threshold: 5000 # fallar cualquier cosa más lenta que 5 s
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Esto falló — las respuestas eran correctas (Paris, Tokyo) pero ambas llamadas tomaron ~33 s, activando la puerta de 5 s:
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-latency-fail-ab40e8dc4386c6acd496942ee3a490aa.png\")
\nFigura 8. La línea de defensa se activa: respuestas correctas, latencia incorrecta. Duración: 33s.
Aumenta el umbral a algo realista y vuelve a ejecutar:
\nsed -i 's/threshold: 5000/threshold: 60000/' promptfooconfig.yaml
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-latency-pass-f3fa1a1c9cb0a11a87328b2a15ef1f31.png\")
\nFigura 9. Con un umbral de 60 s, las mismas llamadas pasan fácilmente — Duración: 2s.
Las llamadas consecutivas al mismo modelo variaron de ~2 s a ~33 s en el mismo día. Ejecuta algunos pases --no-cache para obtener una línea base realista antes de fijar tu umbral.
La afirmación de cost no funciona contra WEC (consulta Solución de problemas #2). Usa latencia + max_tokens juntos como tu línea de defensa de producción en su lugar:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — líneas de defensa (latencia + límite de tokens)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
max_tokens: 16
defaultTest:
assert:
- type: latency
threshold: 30000
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-latency-token-cap-968bf5b53dd3edf6d77129f011e4a66f.png\")
\nFigura 11. Con un umbral de 30 s y un límite de 16 tokens, ambos casos aprueban.
Las aplicaciones reales quieren JSON, no prosa. is-json verifica que la salida sea un JSON válido y coincida con un esquema en una afirmación:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — validación de esquema JSON\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- 'Devuelve SOLAMENTE un objeto JSON (sin markdown, sin prosa) con claves \"capital\" (cadena) y \"population_millions\" (número) para el país {{country}}.'
defaultTest:
assert:
- type: is-json
value:
type: object
required: [capital, population_millions]
properties:
capital: { type: string }
population_millions: { type: number }
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-json-schema-82dcc59881029f9bc0134dcf5a5c5ea2.png\")
\nFigura 12. GLM-5.2 devuelve JSON compacto y válido según el esquema en el primer intento.
Aquí está lo que no puedes obtener en ningún otro lugar — la misma prueba estricta de JSON a través de todos los modelos de chat en tu cuenta:
\ncat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — matriz de modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- 'Devuelve SOLAMENTE un objeto JSON (sin markdown, sin prosa) con claves \"capital\" (cadena) y \"population_millions\" (número) para el país {{country}}.'
defaultTest:
assert:
- type: is-json
value:
type: object
required: [capital, population_millions]
properties:
capital: { type: string }
population_millions: { type: number }
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
- vars: { country: Brazil }
assert: [{ type: icontains, value: Bras }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-model-matrix-table-fcebe135ddd276ef881fc83a726c6b96.png\")
\nFigura 13a. 12 casos de prueba a través de 4 modelos — 9 aprobados, 3 fallidos. qwen3.5:9B emite su cadena de pensamiento en lugar de JSON.
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-model-matrix-summary-96e3ce6b439ae8d487aef486120dbe97.png\")
\nFigura 13b. La descomposición de tokens cuenta la verdadera historia: el modelo de razonamiento costó 13× más para la misma tarea.
| Modelo | ¿JSON Estricto? | Notas | Tokens (3 llamadas) |
|---|---|---|---|
zai-org/GLM-5.2 | ✅ todos aprueban | JSON compacto | 177 |
gemma4 | ✅ todos aprueban | poblaciones enteras | 207 |
Qwen2.5-3B-Instruct | ✅ todos aprueban | JSON bien formateado, preciso | 262 |
qwen3.5:9B | ❌ todos fallan | modelo de razonamiento — emite su \"pensamiento\" en lugar de JSON crudo | 2,650 |
Dos lecciones se desprenden de inmediato:
\nqwen3.5:9B es un modelo de razonamiento. \"Piensa en voz alta\", por lo que rompe el JSON estricto a menos que elimines el razonamiento o uses una restricción de formato de respuesta. Elegirlo para salida estructurada fallaría silenciosamente.Esa es una decisión de selección de modelo que ahora puedes defender con datos — para tus cargas de trabajo, no una tabla de clasificación genérica.
\nAhora puedes comparar cada modelo en tu punto final con números objetivos y repetibles — precisión, latencia y costo lado a lado.
Promptfoo sale no cero (100) cuando cualquier prueba falla. Verifica esto primero:
npx -y promptfoo@latest eval -c promptfooconfig.yaml > /dev/null 2>&1; echo \"código de salida: $?\"
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-exit-code-a3471bde65e7ebf24feaf0d964a3b7eb.png\")
\nFigura 14. El código de salida 100 confirma que Promptfoo señala fallos de manera confiable — exactamente lo que necesita CI.
Conéctalo como una puerta:
\nnpx -y promptfoo@latest eval -c promptfooconfig.yaml \\
&& echo \"✅ evaluación aprobada\" \\
|| { echo \"❌ evaluación fallida — bloqueando\"; exit 1; }
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-ci-gate-table-7067b62a9b737ed79e3906b6da54ea2a.png\")
\nFigura 15a. La puerta vuelve a ejecutar la evaluación de matriz desde caché — mismo resultado 9/3.
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-ci-gate-result-8765593b4f037c480e7fcef844ff6eb4.png\")
\nFigura 15b. Promptfoo sale no cero, se activa la rama ||, y la puerta bloquea.
Nunca ejecutes la variante exit 1 en tu terminal interactiva — consulta Solución de problemas #3.
En CI, ni siquiera necesitas el exit 1 — la salida no cero falla el trabajo. En GitLab:
eval:
image: node:22
script:
- npx -y promptfoo@latest eval -c promptfooconfig.yaml
# WEC_API_KEY se establece como una variable CI/CD enmascarada — nunca la cometas.
Ahora un cambio de aviso que silenciosamente rompe la salida JSON, o un cambio de modelo que duplica la latencia, falla la canalización antes de que llegue a los usuarios.
\nTu evaluación es ahora una puerta de despliegue — las regresiones fallan CI en lugar de llegar a los usuarios.
Error de llamada a la API: TypeError: Cannot convert argument to a ByteString because
the character at index 32 has a value of 8232 which is greater than 255.
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-invisible-char-error-540ad4b2ab9242c120ae80870319df01.png\")
\nFigura 2. Cada llamada a la API falla antes de llegar al servidor — la clave nunca siquiera sale de la máquina.
Causa: La clave pegada contiene un carácter Unicode invisible — U+2028 (separador de línea). Algunos terminales y administradores de portapapeles lo insertan silenciosamente al copiar de ciertas fuentes.
\nSolución: Elimina los caracteres no imprimibles de la clave:
\nexport WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
printf 'len=%s\\n' \"$(printf %s \"$WEC_API_KEY\" | wc -c)\"
# len=25
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-key-strip-1a9c78d8c230c69db3e89eecfdfa24ca.png\")
\nFigura 3. Después de eliminar, la longitud de la clave confirma que no quedan caracteres adicionales. Vuelve a ejecutar la evaluación — pasa.
Error: La afirmación de costo no admite proveedores que no devuelven costo
![\"Terminal:](\"https://wec.wiline.com/docs/es/assets/images/promptfoo-cost-error-1615b4a5c8b0973274d32c6d658a2e12.png\")
\nFigura 10. La API de Inferencia WEC no devuelve un campo de costo en sus respuestas.
Causa: Promptfoo calcula el costo buscando un precio por token para el modelo en su lista de precios incorporada y multiplicando por los tokens utilizados. Tiene precios para los grandes modelos alojados pero no para los nombres de modelos autoalojados de WEC, por lo que no tiene un precio que aplicar y la afirmación falla. (La mayoría de las API, incluida OpenAI, no devuelven un costo en dólares en la respuesta — las herramientas lo calculan).
\nSolución: Omite la afirmación de cost por completo. Realiza un seguimiento del gasto desde la línea Total Tokens que Promptfoo imprime al final de cada ejecución, y usa max_tokens en la configuración del proveedor para limitar el uso de tokens por llamada.
exit 1 cierra tu sesión SSH❌ evaluación fallida — bloqueando
logout
Conexión a 10.80.4.212 cerrada.
Causa: Ejecutar || { echo \"❌ evaluación fallida — bloqueando\"; exit 1; } directamente en una terminal interactiva cierra el proceso de la terminal en sí — lo que, a través de SSH, cierra la conexión.
Solución: Coloca la puerta en un contexto no interactivo: un objetivo de Makefile, un script de npm, un gancho pre-commit de git, o un trabajo de CI. En esos entornos, exit 1 falla el trabajo sin tocar tu terminal. Si necesitas probar la puerta localmente, usa || echo \"❌ evaluación fallida\" (sin exit 1) para ver la salida de forma segura.
Has pasado de \"se ve bien para mí\" a un verdadero arnés de evaluación automatizable en WEC — con verificaciones deterministas, líneas de defensa, validación de esquemas, rúbricas calificadas por modelos, una matriz de modelos, y una puerta CI.
\nPróximamente en esta serie:
\nllm-rubric, puntuación de factualidad, y verificaciones de múltiples jueces para que tu calificador sea confiable.+A través de Partes 1–4 implementaste\nOpenClaw, lo aseguraste con HTTPS, añadiste Telegram y lo hiciste privado a través de una\nmalla NetBird — todo apuntando a OpenAI. Esta parte intercambia el modelo por debajo:\napunta el mismo agente a Modelos WEC — la inferencia compatible con OpenAI de WiLine —\ny ejecútalo en un modelo de peso abierto, Llama 3.1 8B Instruct. Misma caja, sin reconstrucción\n— solo un cambio de base-URL, clave y modelo a través de la CLI de OpenClaw.
\n\nContinúa en la misma Instancia WEC de las Partes 1–4. Modelos WEC es un\npunto final compatible con OpenAI en https://inference.wiline.com/v1; cada comando\na continuación se ejecutó contra un contenedor de puerta de enlace OpenClaw en vivo\n(openclaw-openclaw-gateway-1).
Si autoalojaste el agente para empezar, ya te importa el control — no\ndepender de la nube de otra persona, no estar a un correo de la página de precios de\nreconstrucción. Pero hay una brecha en esa historia: el agente se ejecuta en tu caja, y cada\nmensaje que maneja todavía se envía a OpenAI para que lo procese. Autoalojar\nel agente y externalizar el modelo es solo la mitad del trabajo. Esta parte lo cierra.
\nTambién es más barato. El catálogo propio de WEC fija el precio de Llama3.1-8B-Instruct en\n$0.15 / 1M tokens de entrada · $0.20 / 1M tokens de salida. OpenAI no publica una\ntarifa independiente para gpt-5.5 (el modelo que OpenClaw utiliza por defecto en\nParte 1) más, pero su miembro familiar más cercano\nactual — GPT-5.6 \"Terra\", presentado por OpenAI como\n\"competitivo en rendimiento con GPT-5.5\" — se lista en\n$2.50 / 1M en · $15 / 1M fuera. Esa es una comparación aproximada, no un\nbenchmark de manzanas a manzanas — el movimiento honesto, como siempre en este blog, es\nevalúalo en tu propia carga de trabajo\nen lugar de confiar en el número de ningún proveedor. Pero la dirección es lo suficientemente clara como para valer los diez minutos que esto toma.
openclaw-openclaw-gateway-1.Consulta Inferencia → Claves API si no\ntienes una (la misma clave de\nParte 1 de la serie de evaluaciones\nfunciona bien aquí).
\n\nFigura 1. Crea una clave en Inferencia → Claves API, luego cópiala.
Mantenla fuera de tu historial de terminal — ponla en un archivo en lugar de exportarla\ndirectamente:
\necho 'WEC_API_KEY=sk-wec-...' >> env.local
source <(grep -v '^#' env.local | sed 's/^/export /')
Consulta el punto final compatible con OpenAI /v1/models para ver qué está activo en tu Instancia WEC:
curl -s -H \"Authorization: Bearer $WEC_API_KEY\" https://inference.wiline.com/v1/models
La respuesta lista cada modelo disponible para tu clave, junto con el id que\nutiliza este tutorial:
\n{\"data\":[
...,
{\"id\":\"Llama3.1-8B-Instruct\",\"object\":\"model\",\"created\":1677610602,\"owned_by\":\"openai\"},
...
]}
Los ids de modelo en WEC no siempre son el nombre de visualización mostrado en el portal — siempre toma\nel id exacto de esta respuesta, no una suposición.
No edites manualmente openclaw.json — usa openclaw config set. Valida el\narchivo completo en cada escritura, por lo que un error tipográfico falla ruidosamente en lugar de romper\nsilenciosamente la puerta de enlace. Un proveedor personalizado necesita su base URL, su estilo de API y su lista de modelos declarados juntos, en una sola escritura — el esquema rechaza un proveedor que\nfalta alguno de los tres, así que construye el objeto completo desde el principio:
docker exec openclaw-openclaw-gateway-1 openclaw config set models.providers.wec '{
\"baseUrl\": \"https://inference.wiline.com/v1\",
\"api\": \"openai-completions\",
\"models\": [
{\"id\": \"Llama3.1-8B-Instruct\", \"name\": \"Llama 3.1 8B Instruct\"}
]
}' --strict-json
Updated models.providers.wec. Change will apply without restarting the gateway.
Eso registra WEC como un proveedor, pero aún no está autenticado. No pongas la\nclave directamente en ese JSON — la configuración de composición de OpenClaw mantiene las claves API fuera de\nlas variables de entorno por completo y las almacena en un directorio de secretos dedicado respaldado por archivos en su lugar (OPENCLAW_AUTH_PROFILE_SECRET_DIR, montado en el\ncontenedor). Pasa la clave al propio almacén de autenticación de OpenClaw y deja que haga la conexión:
echo \"$WEC_API_KEY\" | docker exec -i openclaw-openclaw-gateway-1 openclaw models auth paste-api-key --provider wec
Updated config: $OPENCLAW_HOME/.openclaw/openclaw.json
Backup: $OPENCLAW_HOME/.openclaw/openclaw.json.bak
Auth profile: wec:manual (wec/api_key)
Verifica que el proveedor y su autenticación se resolvieron juntos, luego haz que el modelo\nsea el predeterminado para que cada agente lo recoja sin configuración adicional:
\ndocker exec openclaw-openclaw-gateway-1 openclaw models list
docker exec openclaw-openclaw-gateway-1 openclaw models set wec/Llama3.1-8B-Instruct
Modelo Entrada Ctx Autenticación Local Etiquetas
wec/Llama3.1-8B-Instruct texto 200k no sí configurado
openai/gpt-5.5 texto 200k no sí configurado,alias:GPT
...
Updated config: $OPENCLAW_HOME/.openclaw/openclaw.json
Backup: $OPENCLAW_HOME/.openclaw/openclaw.json.bak
Modelo predeterminado: wec/Llama3.1-8B-Instruct
![\"Terminal](\"https://wec.wiline.com/docs/es/assets/images/openclaw-wec-models-list-bb96e6c9a1dfe7d0c98be4a6b5b40ae6.png\")
\nFigura 2. wec/Llama3.1-8B-Instruct, autenticado y establecido como el modelo predeterminado.
OpenClaw puede ejecutar más de un agente por puerta de enlace, así que cada mensaje necesita un\nobjetivo — pasa --agent, coincidiendo con lo que openclaw agents list llama tu\nagente (main, a menos que lo hayas renombrado):
docker exec openclaw-openclaw-gateway-1 openclaw agents list
Agentes:
- main (predeterminado)
Espacio de trabajo: $OPENCLAW_HOME/.openclaw/workspace
Modelo: wec/Llama3.1-8B-Instruct
Reglas de enrutamiento: 0
Envíale un mensaje y ve quién responde:
\ndocker exec openclaw-openclaw-gateway-1 openclaw agent --agent main --message \"¿Cuál es la capital de Francia?\"
París es la capital de Francia.
Eso es WEC, en Llama 3.1, sin OpenAI en el circuito.
\n![\"Terminal](\"https://wec.wiline.com/docs/es/assets/images/openclaw-wec-agent-verified-e5125e1d417f258ba73f9d11b78244ff.png\")
\nFigura 3. El agente, ejecutándose en Llama 3.1 8B Instruct a través de WEC.
¿Quieres que sea más rápido? Desactiva el modo de pensamiento — es un comando de barra dentro del\nchat, no un comando de terminal:
\ndocker exec openclaw-openclaw-gateway-1 openclaw agent --agent main --message \"/think off\"
El modo de pensamiento ha sido desactivado.
O haz que se mantenga para cada sesión:
\ndocker exec openclaw-openclaw-gateway-1 openclaw config set agents.defaults.thinkingDefault \"off\"
Updated agents.defaults.thinkingDefault. No se necesita reiniciar la puerta de enlace.
\"los proveedores de modelos personalizados deben declarar modelos\" — declara baseUrl, api,\ny models juntos, en una sola llamada config set. Un proveedor personalizado que\nfalta alguno de los tres es rechazado; no puedes añadir models en una escritura posterior.
\"models.providers.wec.apiKey no está resuelto en la instantánea de tiempo de ejecución activa\"\n— no establezcas apiKey en el objeto del proveedor; deja que models auth paste-api-key\nlo posea (Paso 3). ¿Ya estableciste uno? Elimínalo:
docker exec openclaw-openclaw-gateway-1 openclaw config unset models.providers.wec.apiKey
\"No se seleccionó ninguna sesión de destino\" — siempre pasa --agent <id> con\nopenclaw agent. Verifica el id con openclaw agents list primero si no estás\nseguro (main, a menos que lo hayas renombrado).
-bash: /think: No such file or directory — /think es un comando de barra\npara dentro del chat, no un comando de terminal. Pásalo a través de --message en su lugar,\ncomo en el Paso 5.
Con el agente ejecutándose en nuestro propio modelo, el siguiente paso es medirlo —\nevaluando la calidad de las respuestas con Promptfoo + Modelos WEC.
\n+![\"SQLite\"](\"https://wec.wiline.com/docs/es/assets/images/SQLite370-e02c30e84f9e098787bb57701b0b7232.png\")
Hermes Agent es el agente de IA de código abierto\n(MIT) de Nous Research — \"el agente que crece contigo.\" Su característica destacada es\nmemoria persistente: aprende sobre tus proyectos y no olvida entre reinicios. Esta guía lo despliega en la misma Instancia WEC que ya usas para\nOpenClaw, lo apunta a un modelo y prueba que la memoria sobrevive a un reinicio completo.
\n\nFunciona en la misma Instancia WEC de la serie OpenClaw — sin nueva VM. El instalador\ndescarga su propio Python (a través de uv), herramientas de navegador Node.js y un Chromium\nde Playwright automáticamente. El estado se guarda en ~/.hermes/. La puerta de enlace de mensajería se ejecuta como un servicio de usuario systemd, por lo que coexiste con la pila Docker de OpenClaw. Capturado en vivo en Ubuntu\n22.04 con hermes v0.17.0.
Un agente que olvida en cada reinicio es un juguete. Hermes mantiene un almacenamiento duradero en\ndisco bajo ~/.hermes/:
~/.hermes/memories/MEMORY.md — un archivo legible por humanos de hechos que el agente ha\ndecidido recordar.~/.hermes/state.db — una base de datos SQLite que contiene cada sesión y mensaje,\ncon índices de búsqueda de texto completo FTS5 superpuestos para que el agente pueda buscar su propia\nhistoria.Un despliegue, un fallo o un reinicio no borran lo que aprendió. Esa es la diferencia entre\nuna demostración de chat y un agente en el que puedes confiar día a día — y es exactamente lo que probamos al\nfinal.
\nTodo se ejecuta en una Instancia WEC. Hermes se comunica con un modelo a través de la API de Inferencia WEC,\nmantiene su memoria en disco local y se ejecuta como un servicio de usuario systemd — por lo que se reinicia solo\ndespués de un reinicio y su memoria sigue ahí:
\n\nglm-5.2 también funcionan).curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
![\"Ejecutando](\"https://wec.wiline.com/docs/es/assets/images/hermes-install-start-1f3d29fcdd9d66dd1e5c1bc28b3c9e5d.png\")
El instalador resuelve un entorno virtual de Python con uv, instala las herramientas de navegador de Node.js, descarga un Chromium de Playwright, sincroniza las habilidades empaquetadas y coloca un\nlanzador hermes en ~/.local/bin:
✓ Paquete principal instalado (verificado por hash a través de uv.lock)
✓ Todas las dependencias instaladas
✓ Configuración del motor de navegador completa
✓ Lanzador hermes instalado → ~/.local/bin/hermes
✓ Directorio de configuración listo: ~/.hermes/
→ Iniciando asistente de configuración...
Luego lanza automáticamente el asistente de configuración. Recarga tu shell después para que el\ncomando hermes esté en tu PATH:
source ~/.bashrc
El asistente guía a través del tipo de configuración, backend de terminal y mensajería. En una caja que\nya ejecutó OpenClaw, ofrece importar la configuración antigua primero — puedes previsualizar\nlo que se migraría antes de que cambie algo.
\nLa primera elección es cómo configurar Hermes:
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/hermes-setup-choice-0db3a3f64faec3d72e3477b075af1901.png\")
Elegimos Configuración Rápida primero. El inicio de sesión en el Portal mostró un código de dispositivo y se quedó en\n\"Esperando aprobación (sondeando)\" — necesita una suscripción activa al Portal, que esta\ncuenta no tenía. Presionamos Ctrl+C para cancelar y en su lugar trajimos nuestro propio\nmodelo en el Paso 3 (a continuación) con una clave de OpenAI. Si tienes un plan de Portal, completa\nel inicio de sesión aquí y puedes omitir el Paso 3.
Para el resto del asistente:
\nhermes setup gateway).El asistente aplica valores predeterminados sensatos para el agente (máximo de iteraciones, un umbral de compresión de contexto del 50%) y termina con un resumen de disponibilidad de herramientas.
\nFuera de la caja, el modelo predeterminado se enruta a través del Nous Portal / OpenRouter y necesita\nuna clave. Para usar tu propio proveedor en su lugar, ejecuta:
\nhermes setup model
Luego selecciona OpenAI ▸ OpenAI API, pega tu clave de API cuando se te pida (se escribe en\n~/.hermes/.env — nunca se muestra), acepta la URL base predeterminada\nhttps://api.openai.com/v1, y elige un modelo — usamos gpt-5.5:
Clave de API guardada.
URL base [https://api.openai.com/v1]:
Seleccionar modelo predeterminado:
→ (●) gpt-5.5
![\"Eligiendo](\"https://wec.wiline.com/docs/es/assets/images/hermes-model-select-2b0c5452d2e217ff8692c022badd9b28.png\")
Para ejecutar inferencias en el propio endpoint de WiLine, elige Endpoint personalizado, establece la URL base\nen https://inference.wiline.com/v1, pega tu clave de API de WEC y usa un modelo como\nglm-5.2. Mismo flujo compatible con OpenAI.
Confirma que el modelo y la clave están saludables:
\nhermes doctor
◆ Archivos de configuración
✓ El archivo ~/.hermes/.env existe
✓ Clave de API o endpoint personalizado configurado
...
◆ Proveedor de memoria
✓ Memoria incorporada activa (no se configuró proveedor externo — esto está bien)
Las líneas restantes ⚠ en doctor son integraciones de herramientas opcionales (búsqueda web,\nDiscord, generación de imágenes) — no necesarias para esta guía.
Inicia una sesión interactiva:
\nhermes
![\"La](\"https://wec.wiline.com/docs/es/assets/images/hermes-tui-welcome-842b22f5c733599e17b84cde75db4933.png\")
Envíale un hecho y pídele que lo recuerde — observa cómo se activa la herramienta 🧠 memory:
● Por favor guarda en tu memoria a largo plazo: mi nombre en clave del proyecto WEC es
Bluefin-7, ejecutándose en la caja de OpenClaw.
┊ 🧠 memory ? 0.0s
╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
Guardado en la memoria a largo plazo: tu nombre en clave del proyecto WEC es Bluefin-7,
ejecutándose en la caja de OpenClaw.
╰─────────────────────────────────────────────────────────────────────╯
![\"Hermes](\"https://wec.wiline.com/docs/es/assets/images/hermes-memory-save-458cefa8aaf46e0d1cc554418a3acc38.png\")
Esa escritura crea ~/.hermes/memories/MEMORY.md. Sal con /exit o Ctrl+D.
El TUI envía al presionar enter, por lo que pegar texto de varias líneas puede enviar un mensaje medio escrito.\nSi un prompt solo captura un fragmento, escríbelo en una línea a mano.
Este es el objetivo principal. La puerta de enlace de Hermes está instalada como un servicio de usuario systemd\ncon linger habilitado, por lo que vuelve automáticamente después de un reinicio — sin necesidad de iniciar sesión.\nReinicia el servicio y luego reinicia toda la caja para hacer la prueba a prueba de fallos:
\nsystemctl --user restart hermes-gateway # reinicia solo el servicio de puerta de enlace
sudo reboot # luego reinicia toda la caja
![\"Reiniciando](\"https://wec.wiline.com/docs/es/assets/images/hermes-reboot-ae228254579427ae3018547803f83c62.png\")
Reconéctate una vez que la caja esté activa y confirma que el servicio se reinició por sí mismo:
\nsystemctl --user status hermes-gateway --no-pager
● hermes-gateway.service - Puerta de enlace del Agente Hermes - Integración de Plataforma de Mensajería
Loaded: loaded (...; enabled; vendor preset: enabled)
Active: active (running) since Thu 2026-06-25 21:21:54 UTC; 1min 36s ago
![\"systemctl](\"https://wec.wiline.com/docs/es/assets/images/hermes-gateway-status-4da5472c10ec41fe81cfc64298589f10.png\")
Ahora abre una sesión nueva y pregunta — sin contexto previo, ID de sesión completamente nuevo:
\nhermes
● ¿Cuál es mi nombre en clave del proyecto WEC, y en qué caja se ejecuta?
╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
Tu nombre en clave del proyecto WEC es Bluefin-7, y se ejecuta en la
caja de OpenClaw.
╰─────────────────────────────────────────────────────────────────────╯
![\"Una](\"https://wec.wiline.com/docs/es/assets/images/hermes-reboot-recall-eac2b093a48d12569fa730340f5751d3.png\")
Recordó el hecho desde el disco después de un reinicio completo. Inspecciona dónde vive ese estado duradero:
\ncat ~/.hermes/memories/MEMORY.md
file ~/.hermes/state.db && du -h ~/.hermes/state.db
El nombre en clave del proyecto WEC del usuario es Bluefin-7, ejecutándose en la caja de OpenClaw.
/home/ubuntu/.hermes/state.db: base de datos SQLite 3.x, ...
176K\t/home/ubuntu/.hermes/state.db
Un MEMORY.md en texto plano que puedes leer y editar, respaldado por un state.db de SQLite para\nsesiones. Esa es la memoria persistente — y acaba de sobrevivir a un reinicio.
Cuando le pides a Hermes que recuerde algo, escribe el hecho en\n~/.hermes/memories/MEMORY.md — Markdown plano que puedes abrir, leer e incluso editar a mano. Por separado, tu historial completo de conversación se guarda en\n~/.hermes/state.db, una base de datos SQLite. Ambos viven en disco, por lo que un\nreinicio no los pierde.
La forma más sencilla de ver lo que sabe el agente es simplemente leer el Markdown:
cat ~/.hermes/memories/MEMORY.md
Para mirar dentro de la base de datos, ten en cuenta que el motor de SQLite está integrado en Python, por lo que Hermes\nlo usa sin ninguna instalación adicional. La opcional herramienta de línea de comandos sqlite3 — para\nnavegar por la base de datos a mano — no está instalada por defecto. Si la quieres:
sudo apt install -y sqlite3
sqlite3 ~/.hermes/state.db '.tables'
![\"Salida](\"https://wec.wiline.com/docs/es/assets/images/hermes-sqlite-tables-dbdc5016a3514137534038cac3f6298d.png\")
Verás tablas sessions y messages que contienen la conversación, además de una familia de\ntablas messages_fts*. Esos son índices de texto completo FTS5 de SQLite — incluyendo una\nvariante de trigramas para coincidencias difusas — que permiten a Hermes buscar sus propias conversaciones pasadas:
CREATE VIRTUAL TABLE messages_fts USING fts5(content);
CREATE VIRTUAL TABLE messages_fts_trigram USING fts5(content, tokenize='trigram');
Y cada sesión es una fila que puedes inspeccionar — aquí están las dos de esta guía, la\nsegunda creada después del reinicio:
sqlite3 -header -column ~/.hermes/state.db \\
\"SELECT substr(id,1,15) AS id, model, message_count FROM sessions ORDER BY started_at;\"
id model message_count
--------------- ------- -------------
20260625_211227 gpt-5.5 8
20260625_212333 gpt-5.5 2
Nunca necesitas la CLI para que Hermes funcione — es solo para inspeccionar la base de datos\ntú mismo. Día a día, el MEMORY.md legible por humanos es todo lo que tienes que mirar.
Ahora ejecutas un agente cuya memoria sobrevive a los reinicios — y sabes exactamente dónde vive esa\nmemoria en disco.
La tabla messages contiene el texto real de cada turno. Cada fila tiene un role —\nuser (lo que escribiste), assistant (la respuesta de Hermes), o tool (el resultado de una herramienta) — para que\npuedas reproducir todo el intercambio:
sqlite3 -header -column ~/.hermes/state.db \\
\"SELECT substr(session_id,10,6) AS sess, role, substr(content,1,55) AS content
FROM messages ORDER BY timestamp;\"
sess role content
------ --------- -------------------------------------------------------
211227 user hello, can you hear me?
211227 assistant Yes — I can hear you. How can I help?
211227 user Please save to your long-term memory: my WEC project...
211227 tool {\"success\": true, \"done\": true, \"target\": \"memory\", ...
211227 assistant Saved to long-term memory: your WEC project codename...
212333 user What's my WEC project codename, and which box does...
212333 assistant Your WEC project codename is Bluefin-7, and it runs...
![\"La](\"https://wec.wiline.com/docs/es/assets/images/hermes-sqlite-messages-12ab80eeb7db27fbf02d5c73b075d553.png\")
La parte interesante es cómo se escribió la memoria. El asistente no editó un archivo\ndirectamente — emitió una llamada a la herramienta memory, y esa herramienta es la que escribió\nMEMORY.md. Puedes ver la llamada exacta registrada en el historial:
sqlite3 ~/.hermes/state.db \\
\"SELECT tool_calls FROM messages WHERE tool_calls LIKE '%memory%' LIMIT 1;\"
{\"function\": {\"name\": \"memory\", \"arguments\":
\"{\\\"target\\\":\\\"memory\\\",\\\"operations\\\":[
{\\\"action\\\":\\\"add\\\",
\\\"content\\\":\\\"El nombre en clave del proyecto WEC del usuario es Bluefin-7, ejecutándose en la caja de OpenClaw.\\\"}]}\"}}
![\"La](\"https://wec.wiline.com/docs/es/assets/images/hermes-sqlite-memory-toolcall-53bc3762b14f9ca8e30715118341b792.png\")
Así que la cadena completa es: tú escribes → el agente decide que vale la pena mantenerlo → llama a la\nherramienta memory con action: add → eso escribe el hecho en MEMORY.md, mientras que\ntoda la conversación se mantiene en state.db, completamente buscable a través de FTS5. Dos almacenes, una\nmemoria duradera.
Una memoria que sobrevive a los reinicios solo importa por lo que el agente hace con ella.\nCon Hermes en funcionamiento, la misma instalación ofrece estas capacidades (las viste en la\nlista de herramientas de hermes doctor) — aquí está lo que desbloquean día a día:
terminal y code_execution le permiten actuar,\nno solo chatear — por ejemplo, \"clona este repositorio, instala dependencias y ejecuta las pruebas,\" o \"verifica\npor qué se está llenando el disco.\" Lo hace en la Instancia WEC y reporta de vuelta.cronjob ejecuta trabajos recurrentes: un informe matutino,\nun informe semanal de uso del disco, o vigila un servicio y avísame cuando falle — entregado a tu canal de mensajería. (Parte 3.)hermes setup tools.)El resto de esta serie convierte cada una de estas en una guía práctica (consulta ¿Qué sigue?).
\nLa Configuración Rápida (Nous Portal) se queda colgada en \"Esperando aprobación (sondeando)\". El inicio de sesión en el Portal\nnecesita una suscripción/crédito activo. Si no tienes uno, Ctrl+C y usa\nConfiguración completa con tu propia clave en su lugar (Paso 3).
doctor muestra \"No se encontró clave de API en ~/.hermes/.env\". El modelo predeterminado apunta a\nPortal/OpenRouter. Ejecuta hermes setup model, elige tu proveedor y pega la\nclave — doctor luego informa \"Clave de API o endpoint personalizado configurado.\"
Advertencia de .env obsoleta al iniciar la puerta de enlace (por ejemplo, MESSAGING_CWD). Inofensiva;\nsigue la sugerencia para mover la configuración a config.yaml cuando sea conveniente.
Repetidos WARNING [Telegram] … en los registros de la puerta de enlace. Si seguiste las partes anteriores\nde OpenClaw y agregaste un canal de Telegram, la configuración de Hermes detectó OpenClaw y\nimportó esas configuraciones de mensajería en ~/.hermes/.env. Como omitimos\nterminar la mensajería aquí, la puerta de enlace tiene un token pero no una configuración completa, por lo que sigue\nreintentando y registrando esta advertencia. (Una caja nueva sin configuración de Telegram de OpenClaw no\nlo verá.) Elimina las entradas sobrantes y reinicia:
sed -i '/^TELEGRAM_ALLOWED_USERS=/d; /^TELEGRAM_BOT_TOKEN=/d' ~/.hermes/.env
systemctl --user restart hermes-gateway
Si ese token alguna vez fue expuesto, revócalo en @BotFather de Telegram y emite uno nuevo.
\nAhora que Hermes está funcionando con memoria duradera, el resto de la serie convierte cada\ncapacidad anterior en una guía práctica:
\nhermes setup gateway, listas de permitidos, verifica que el bot\nresponda), para que puedas darle tareas desde tu teléfono.Los enlaces aparecerán aquí a medida que cada parte se publique.
", "url": "https://wec.wiline.com/docs/es/tutorials/self-host-hermes-agent/", "title": "Autoalojar el Agente Hermes con memoria persistente", "summary": "Despliega el Agente Hermes de código abierto de Nous Research en tu Instancia WEC — con memoria persistente respaldada por SQLite que sobrevive a un reinicio completo. Instalación real, configuración del modelo y una prueba de memoria que sobrevive al reinicio.", "date_modified": "2026-06-25T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "hermes", "agentes", "memoria" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/netbird-mesh-vpn-openclaw/", "content_html": "+![\"NetBird\"](\"https://wec.wiline.com/docs/es/assets/images/netbird-dark-0d2ba9c783792904def84b7e687b8f95.png\")
En Artículo 2 colocamos Caddy frente a\nOpenClaw para HTTPS, y en Artículo 3\nagregamos un canal de Telegram. La puerta de enlace funciona — pero Caddy sigue escuchando en\n0.0.0.0, accesible por cualquier cosa que pueda enrutar hacia la caja. Este es el proyecto final\nde la serie: unimos el servidor y tu laptop a una malla NetBird,\nredirigimos openclaw.local a la IP de la malla y cerramos los puertos públicos. La misma\nURL https://openclaw.local/chat sigue funcionando — pero solo para tus dispositivos.\nCada comando y error a continuación proviene de la ejecución real.
Continúa desde los Artículos 1–3 en la misma Instancia WEC — Ubuntu, OpenClaw detrás de\nCaddy 2. Usamos NetBird gestionado (el nivel gratuito en\napp.netbird.io) con el agente 0.73.2 tanto en el\nservidor (Linux, núcleo WireGuard) como en el cliente (macOS, espacio de usuario). NetBird es\nWireGuard-basado y de código abierto; también puedes\nautoalojar el plano de control, que es un tema más amplio para otro día.
NetBird tiene dos partes, y la distinción es el punto principal:
\nAsí que estás construyendo una malla donde Peer A (tu laptop) alcanza a Peer B (la caja OpenClaw) por su dirección privada 100.x — y openclaw.local apunta allí, con Caddy vinculado solo a esa interfaz. El lado público/LAN no tiene nada escuchando.
La idea clave para más adelante: la malla no está limitada a dos pares. Autentica una vez, y cada nuevo servicio — Ollama, un VDI, WordPress — se une como otro par con su propia dirección 100.x, accesible de forma privada sin puertos públicos que abrir. Configuras el modelo de autenticación una vez; agregas servicios para siempre.
El internet público solo llega a el plano de control de NetBird — y eso solo\nautentica pares, nunca transporta tu tráfico de aplicación. Tus servicios no están\n\"protegidos\" tanto como invisibles: OpenClaw no tiene IP pública, así que simplemente\nno hay ruta hacia él desde internet. La única forma de entrar es ser un\npar autenticado en la malla.
\nEn este tutorial conectamos los primeros dos pares — tu laptop y la\ncaja OpenClaw. Los otros servicios hacen el punto: una vez que la autenticación está configurada,\nOllama, un VDI, WordPress simplemente se unen a la misma malla como otro par 100.x\n— sin puertos públicos, sin exposición por servicio.
Cada malla de NetBird tiene dos roles: pares — tus máquinas, es decir, la caja OpenClaw\nde las Partes 1–3 y tu laptop — y un plano de control que autentica esos\npares y emite sus claves de unión. Ya tienes el par (tu caja OpenClaw);\nahora necesitas un plano de control al que unirse. Dos formas de obtener uno:
\nCon la Opción A ejecutarás dos instancias: tu caja OpenClaw (Partes 1–3,\nsin cambios) y una segunda caja de plano de control dedicada (esta plantilla). Esa es la\ntopología correcta — un plano de control debe ser su propia máquina, nunca compartiendo con una\ncarga de trabajo. Con la Opción B solo hay tu una caja OpenClaw. De cualquier manera nunca\nreconstruyes la caja OpenClaw — en Inscribir tus máquinas\nsolo instalas el agente de NetBird en ella y se une a la malla como un par.
Los pasos a continuación configuran la Opción A. WEC ejecuta la instalación; le das un correo electrónico y una\nIP pública, y unos minutos después tienes tu propio panel de NetBird en\nhttps://<your-ip>.apps.wiline.cloud con un certificado válido.
El panel necesita una dirección pública. Bajo Redes → IPs Elásticas, asigna una\nnueva IP o elige una libre, y anota su valor (la nuestra: 108.60.112.165). Debe estar\nen la VPC y zona en la que desplegarás. Pasos completos:\nConfigurar IPs Elásticas.
![\"Una](\"https://wec.wiline.com/docs/es/assets/images/netbird-eip-available-b4ec56b4c4946226b7c9e199bd540f61.png\")
Esta nueva instancia se convierte en tu plano de control de NetBird — una caja separada de tu\ninstancia OpenClaw, que permanece intacta. Abre Desplegar → Desplegar una VM (guía completa:\nDesplegar una Máquina Virtual).\nLas elecciones que importan aquí:
\nSubred Local en Princeton-VPC), para que la IP pueda adjuntarse después.![\"Configuración](\"https://wec.wiline.com/docs/es/assets/images/netbird-template-config-e03939727bf27b7f6ce4ceb4fc5acdf1.png\")
Termina el asistente y despliega.
\nLa IP no está vinculada en el momento del despliegue — la adjuntas una vez que la VM esté activa. Ve a\nRedes → IPs Elásticas → tu IP → ⋯ → Asignar, y selecciona tu nueva instancia\n(netbird-tutorial). Solo las VMs en la misma VPC aparecen en la lista.
![\"Asignando](\"https://wec.wiline.com/docs/es/assets/images/netbird-eip-allocate-620e7b57084f55e9e8ca3323494cda6d.png\")
La instancia muestra Ejecutándose en Cómputo → Instancias en un minuto — pero la\nplantilla sigue trabajando durante unos minutos después de eso, descargando e iniciando los\ncontenedores de NetBird y levantando el panel. No esperes que la URL responda\ninmediatamente.
\nVerifica desde tu laptop a través de HTTPS (no ping — ICMP está bloqueado, así que un\nping fallido no significa que esté caída):
curl -skS -m 10 -o /dev/null -w \"%{http_code}\\n\" https://<your-ip>.apps.wiline.cloud
000 / conexión rechazada → aún en provisión; espera un minuto y vuelve a intentar.301 luego 200 → está activa (HTTP redirige a HTTPS).Para verlo directamente, accede por SSH (ssh ubuntu@<your-ip>) y confirma que los contenedores están\nejecutándose y los puertos están vinculados:
cloud-init status
sudo docker ps
sudo ss -tlnp | grep -E ':(80|443)'
Está listo una vez que netbird-dashboard, netbird-traefik, y netbird-server muestran\nArriba y 80/443 están escuchando.
Abre https://<your-ip>.apps.wiline.cloud — haz clic en la advertencia del certificado\nsi recibes una (el mismo clic de paso de certificado autofirmado que en\nArtículo 2).
Este es tu propio plano de control de NetBird, ejecutándose en tu Instancia WEC. En la\nprimera visita te pide que crees la cuenta de administrador — ingresa un nombre, correo\nelectrónico y contraseña, haz clic en Crear, luego inicia sesión con esas mismas credenciales.\n(Esa pantalla de configuración aparece solo una vez; después el panel muestra una página normal de\nIniciar sesión.)
\nLlegas al panel de NetBird — tu plano de control privado en tu propio dominio:
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/netbird-dashboard-c98eca329c445df75fee98ca55f230e9.png\")
Haz clic en Agregar Par y NetBird te entrega el comando de inscripción para tu servidor —\nnota el --management-url apuntando a tu propio dominio:
![\"Agregar](\"https://wec.wiline.com/docs/es/assets/images/netbird-add-peer-09fd78007bcc0279cae91217c1786221.png\")
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --management-url https://<your-ip>.apps.wiline.cloud
(Ese segundo comando abre un inicio de sesión SSO en el navegador. Para un servidor sin cabeza,\nagrega --setup-key <KEY> desde la página de Claves de Configuración de tu panel en su lugar — igual que el flujo gestionado, solo que con --management-url agregado.)
Este es el panel donde creas las claves de configuración que inscriben máquinas — que es exactamente lo que hacemos a continuación.
\nTienes un plano de control (tu propio panel de plantilla, o NetBird gestionado). Ahora coloca\nlas dos máquinas en la malla — la caja OpenClaw de las Partes 1–3 y tu\nlaptop — y luego cierra los puertos públicos de la caja. Estos pasos son los mismos sin importar qué plano de control elegiste.
\nLos comandos a continuación utilizan NetBird gestionado (app.netbird.io) como ejemplo. Si\ndesplegaste la plantilla de WEC en su lugar, es idéntico excepto: crea la clave de configuración\nen tu propio panel (https://<your-ip>.apps.wiline.cloud) y agrega\n--management-url https://<your-ip>.apps.wiline.cloud a netbird up, para que el\nagente apunte a tu servidor en lugar de a la nube gestionada.
Requisitos previos: OpenClaw ejecutándose detrás de Caddy de\nArtículos 1–3 (accesible en\nhttps://openclaw.local), un plano de control del paso anterior, y acceso a la shell en\nla caja más administrador en tu laptop.
Esta es la caja de las Partes 1–3 (una Instancia WEC) — la estamos inscribiendo como un par,\nque es separado de cualquier servidor de plano de control. NetBird envía un instalador de una línea:
\ncurl -fsSL https://pkgs.netbird.io/install.sh | sh
Problema (real): en Ubuntu la instalación activa el diálogo needrestart —\nuna caja azul \"¿Qué servicios deberían reiniciarse?\". Tab entre botones puede ser\nabsorbido por algunas configuraciones de SSH/terminal; usa las teclas de flecha para moverte,\nEspacio para alternar, Enter para confirmar (<Ok> es el predeterminado). El paquete ya está\nen su lugar para cuando aparece esta caja, así que incluso si sales con Ctrl+C, el agente\nestá instalado — volver a ejecutar el instalador solo te lo dirá:
NetBird parece estar ya instalado, por favor elimínalo antes de continuar
(Si vuelves a ejecutar el instalador después de este tutorial, verás en su lugar\nEl servicio de NetBird está en ejecución, por favor deténlo antes de continuar — el agente ya está\nactivo, así que no hay nada que reinstalar.)
Confirma la versión:
\nnetbird version
# 0.73.2
Una clave de configuración es el token que inscribe un dispositivo en tu malla — ideal para un\nservidor sin cabeza (sin necesidad de SSO en el navegador).
\nAlgunas cosas intentarán enviarte en la dirección equivocada en una cuenta nueva — aquí está la\nlínea directa:
https://app.netbird.io/setup-keys.https://app.netbird.io/setup-keys.openclaw-tutorial, alterna Reutilizable (para que funcione también para la laptop), por defecto de otro modo.![\"Creando](\"https://wec.wiline.com/docs/es/assets/images/netbird-setup-key-ade9af748bded2998a18890a1ebde93b.png\")
Conecta la VM (reemplaza con tu clave):
\nsudo netbird up --setup-key <YOUR_SETUP_KEY>
Cualquiera con una clave reutilizable puede agregar dispositivos a tu red. No la pegues en\nchats o commits, y elimínala del panel una vez que tus dispositivos estén\ninscritos (los pares existentes permanecen conectados).
Verifica la conexión:
\nnetbird status
![\"estado](\"https://wec.wiline.com/docs/es/assets/images/netbird-vm-status-8e8088e406d7392203f1eb5da63b4258.png\")
Esa IP de NetBird (100.87.239.229) es la dirección a la que apunta todo lo que sigue.\nConteo de Pares: 0/0 es esperado — nada más se ha unido aún.
Instala el cliente de NetBird en lo que estés usando, luego conéctate con la\nmisma clave de configuración reutilizable. El comando de conexión (netbird up --setup-key …) es\nidéntico en cada SO — solo la instalación difiere.
La salida capturada a continuación es de un Mac. Las pestañas de Windows y Linux dan la\ninstalación equivalente; los pasos de netbird up, netbird status, y ping son los\nmismos en todas partes (Windows usa ping -n en lugar de -c).
Instala a través de Homebrew, luego inicia el servicio y conéctate:
brew install netbirdio/tap/netbird
sudo netbird service install
sudo netbird service start
netbird up --setup-key <YOUR_SETUP_KEY>
Puede que veas una advertencia de gRPC única mientras el socket del daemon se activa un momento después\nde que el cliente lo llama — termina en Conectado, así que es inofensivo:
WARNING: ... dial unix /var/run/netbird.sock: connect: no such file or directory
Connected
Descarga y ejecuta el instalador de NetBird para Windows desde\napp.netbird.io (Agregar Par → Windows) o\npkgs.netbird.io. Instala una aplicación en la bandeja del sistema y el\nCLI netbird. Luego, en PowerShell como Administrador, conéctate con tu clave:
netbird up --setup-key <YOUR_SETUP_KEY>
(También puedes hacer clic en Conectar desde el icono de la bandeja y autenticarte a través de SSO, pero\nla clave de configuración es el mismo flujo de un solo uso que en las otras plataformas.)
El mismo instalador de una línea que la VM, luego conéctate:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key <YOUR_SETUP_KEY>
Verifica que los dos nodos se vean entre sí, y que el túnel transporte tráfico:
\nnetbird status
ping -c 3 100.87.239.229 # Windows: ping -n 3 100.87.239.229
![\"Estado](\"https://wec.wiline.com/docs/es/assets/images/netbird-mac-status-857d291924930e23af4e6550b1845ec7.png\")
Conteo de Pares: 1/1 — ese par es la VM. En el panel, ambas máquinas ahora\naparecen bajo Pares (porque las inscribimos con una clave de configuración en lugar de un\ninicio de sesión SSO, aparecen bajo Servidores en lugar de Dispositivos de Usuario):
![\"La](\"https://wec.wiline.com/docs/es/assets/images/netbird-peers-a54440db77e8715febacc8d410c24da5.png\")
Este camino está pasando por un relay de NetBird (nota Tipo de Interfaz: Espacio de Usuario\nen el Mac). Está bien para una interfaz web, y NetBird a menudo actualizará a un enlace directo\nde par a par cuando las redes lo permitan. La latencia a un par retransmitido no es una\nbandera roja.
openclaw.local a la IP de la mallaDesde Artículo 2, tu archivo de hosts mapea\nopenclaw.local a la IP LAN de la VM (10.80.4.212). Cámbiala por la IP de la malla\n(100.87.239.229). La ruta del archivo y el comando de edición difieren según el SO:
sed en macOS necesita el vacío -i '':
grep openclaw /etc/hosts
# 10.80.4.212 openclaw.local
sudo sed -i '' 's/^10\\.80\\.4\\.212 openclaw\\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local
GNU sed toma -i sin argumento:
grep openclaw /etc/hosts
sudo sed -i 's/^10\\.80\\.4\\.212 openclaw\\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local
El archivo de hosts está en C:\\Windows\\System32\\drivers\\etc\\hosts y necesita admin.\nEn PowerShell como Administrador:
$h = \"$env:WINDIR\\System32\\drivers\\etc\\hosts\"
(Get-Content $h) -replace '^10\\.80\\.4\\.212 openclaw\\.local','100.87.239.229 openclaw.local' | Set-Content $h
Select-String openclaw $h
(O abre ese archivo en Notepad ejecutado como Administrador y cambia la IP a mano.)
Prueba a través de la malla — antes de tocar ningún puerto:
\ncurl -kI https://openclaw.local/
HTTP/2 200
...
via: 1.1 Caddy
via: 1.1 Caddy a través de la IP de la malla — el chat ahora fluye a través de NetBird. Carga\nhttps://openclaw.local/chat?session=main en el navegador para confirmar que se comporta\nexactamente como antes. El certificado TLS sigue coincidiendo porque el nombre de host no ha cambiado;\nsolo la IP detrás de él se movió.
![\"El](\"https://wec.wiline.com/docs/es/assets/images/netbird-chat-mesh-409321edd81ea8d59656891246bc0558.png\")
Aquí está el estado que estamos corrigiendo. En la VM:
\nsudo ss -tlnp | grep -E ':(80|443)'
LISTEN 0 4096 0.0.0.0:443 ... docker-proxy
LISTEN 0 4096 0.0.0.0:80 ... docker-proxy
Caddy escucha en 0.0.0.0 — todas las interfaces, incluyendo la LAN (y cualquier NAT\ndelante de ella).
Tu primer instinto es ufw deny 443. No funcionará. Los puertos de Caddy son\npublicados por Docker, que escribe sus propias reglas de iptables que evitan la\ncadena INPUT de ufw. Agregarías reglas de ufw, te sentirías seguro, y 443 seguiría abierto. En\nesta caja ufw estaba incluso inactivo — y habilitarlo no habría cambiado nada\npara los puertos publicados por Docker.
La solución confiable es vincular los puertos publicados a la IP de la malla en lugar de\n0.0.0.0, para que Caddy solo escuche en wt0. Edita el servicio de Caddy en\ndocker-compose.override.yml (la sobreescritura del Artículo 2):
cd /home/ubuntu/openclaw
cp docker-compose.override.yml docker-compose.override.yml.bak
Cambia el bloque de puertos de:
\n ports:
- \"80:80\"
- \"443:443\"
a vincular a la IP de la malla:
\n ports:
- \"100.87.239.229:80:80\"
- \"100.87.239.229:443:443\"
Recrea solo Caddy y vuelve a verificar:
\ndocker compose up -d caddy
sudo ss -tlnp | grep -E ':(80|443)'
![\"ss](\"https://wec.wiline.com/docs/es/assets/images/netbird-ss-after-0172e6fc62bc667a141b1f6528526e73.png\")
Los puertos han desaparecido de 0.0.0.0 — ahora viven solo en la interfaz de malla.
Debido a que el enlace apunta a la IP de la malla, NetBird debe estar activo antes de que Caddy inicie\n(por ejemplo, después de un reinicio, wt0 necesita su IP antes de que Docker se vincule a ella). La\npolítica restart: unless-stopped ya cubre esto — Caddy reintenta hasta que\nla interfaz exista — pero vale la pena saberlo si alguna vez ves a Caddy en un bucle de\ncrash justo después del arranque.
Ambas direcciones, de la ejecución real.
\nAún accesible a través de la malla (laptop):
\ncurl -kI https://openclaw.local/
# HTTP/2 200 ... via: 1.1 Caddy
Ya no accesible en la LAN (VM, golpeando su propia IP LAN):
\ncurl -kI --connect-timeout 5 --resolve openclaw.local:443:10.80.4.212 https://openclaw.local/
![\"En](\"https://wec.wiline.com/docs/es/assets/images/netbird-refused-0944b25666489470ae7b961e2d6243c8.png\")
Ese es el resultado: la misma URL, accesible solo a través de tu malla, rechazada\nen todas partes.
\nAhora puedes sacar cualquier servicio autoalojado de internet público sin romper cómo lo\nusas.
Elimina la clave de configuración reutilizable ahora que ambos dispositivos están inscritos —\nClaves de Configuración → eliminar en el panel. Tus pares permanecen conectados; solo\nestás cerrando la puerta que usaste para agregarlos. Para eliminar un dispositivo más tarde, elimínalo bajo\nPares → Dispositivos de Usuario y ejecuta netbird down en esa máquina.
needrestart no acepta Tab. Usa teclas de flecha / Espacio / Enter. El paquete ya está instalado para cuando aparece la caja.netbird.sock en el primer up. El socket del daemon se retrasa un momento respecto al cliente. Si termina en Conectado, ignórala.ufw no bloquean la puerta de enlace. Los puertos publicados por Docker evitan ufw — vincula el puerto a una IP específica (como arriba) o usa la propia cadena DOCKER-USER de Docker.wt0 tuviera la IP de la malla. restart: unless-stopped lo recupera; o ordena Docker después de netbird.service.Tipo de Interfaz y el detalle del par de NetBird para el tipo de conexión.Eso cierra la serie de Autoalojamiento de OpenClaw:
\nAhora tienes un agente autoalojado que está cifrado en tránsito, emparejado con tus\ndispositivos, accesible desde tu teléfono, e invisible para el internet público — todo en\nuna pequeña Instancia WEC.
\n¿Listo para un agente que recuerda? Comienza la serie de Autoalojamiento de Hermes —\nAutoalojar el Agente Hermes con memoria persistente —\ndesplegado en esta misma Instancia WEC, con contexto que sobrevive a los reinicios.
", "url": "https://wec.wiline.com/docs/es/tutorials/netbird-mesh-vpn-openclaw/", "title": "Haz que OpenClaw sea privado con una VPN de malla NetBird", "summary": "Coloca OpenClaw en una malla privada con NetBird, redirige tu nombre de host a la IP de la malla y cierra los puertos públicos — así la misma URL de chat funciona solo para tus dispositivos. Comandos reales y problemas de una ejecución en vivo.", "date_modified": "2026-06-24T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "openclaw", "netbird", "vpn", "malla", "seguridad" ] }, { "id": "https://wec.wiline.com/docs/es/tutorials/add-telegram-channel-openclaw/", "content_html": "+Has desplegado OpenClaw y\nlo has asegurado detrás de HTTPS. Ahora hazlo\nutilizable — habla con tu agente desde tu teléfono a través de Telegram. Creamos un bot,\nlo conectamos, limpiamos la puerta de emparejamiento de OpenClaw y obtenemos una respuesta real. Cada comando y\ndetalle a continuación proviene de una ejecución real.
\n\nContinúa desde las Partes 1–2 en la misma Instancia WEC — OpenClaw 2026.6.8. Telegram\nusa polling (la puerta de enlace consulta la API de Telegram), por lo que no se requiere un webhook o dominio público — esto funciona en una caja privada.
Tu teléfono habla con un bot de Telegram; la puerta de enlace de OpenClaw consulta Telegram para\nmensajes, los procesa a través de tu modelo y responde — no se necesitan puertos de entrada.
\n\n~/openclawweb.telegram.org. (No puedes crear un bot desde la página web pública t.me; consulta Solución de problemas.)En la aplicación de Telegram, toca buscar y escribe BotFather, luego abre la cuenta oficial — la que tiene el check azul.
![\"Buscando](\"https://wec.wiline.com/docs/es/assets/images/tg-step1a-search-922bcf2cacaf250ac10c1a03546f240b.png\")
Toca Iniciar — BotFather responde con los comandos que entiende (verás\nopciones como /newbot, /mybots, /token, y más). Envía /newbot, luego\nsigue sus dos indicaciones:
Mi Agente OpenClawbot, por ejemplo, wiline_openclaw_botBotFather confirma con \"¡Listo! Felicitaciones por tu nuevo bot\" y te da el\ntoken — la línea después de Usa este token para acceder a la API HTTP:, como\n1234567890:AA....
![\"BotFather](\"https://wec.wiline.com/docs/es/assets/images/tg-step1c-token-0bec47ec554ad66500f6d053bd0a4810.png\")
Cualquiera que lo tenga controla tu bot. Difumínalo en la captura de pantalla anterior, y /revoke\nen BotFather si alguna vez se filtra.
En la VM, en ~/openclaw, registra el canal con tu token:
docker compose run --rm openclaw-cli channels add --channel telegram --token \"<tu-token-de-bot>\"
# Cuenta de Telegram \"default\" añadida.
Reinicia la puerta de enlace para que reconozca el canal, luego verifica el estado:
\ndocker compose restart openclaw-gateway
docker compose run --rm openclaw-cli channels status
# - Telegram default: habilitado, configurado, en ejecución, modo:polling, token:config
modo:polling significa que la puerta de enlace está consultando activamente Telegram — no se requiere puerto de entrada o webhook.
![\"estado](\"https://wec.wiline.com/docs/es/assets/images/tg-step3-status-6393f1690ec9b270312c2f5e3a25f137.png\")
Abre tu bot (t.me/<tu-nombre-de-bot>), toca Iniciar, y envía un mensaje.
OpenClaw trata a los remitentes desconocidos como no confiables — así que en lugar de responder, el bot\ndevuelve un código de emparejamiento y tu id de usuario de Telegram. Este es el mismo patrón de seguridad\nque el emparejamiento de dispositivos en la Parte 2.
\n![\"Bot](\"https://wec.wiline.com/docs/es/assets/images/tg-step4-pairing-94e777f1790fbeadab0cd42be384b80b.png\")
En la VM, aprueba el código del mensaje del bot:
\ndocker compose run --rm openclaw-cli pairing approve telegram <código-de-emparejamiento>
# Remitente de telegram aprobado <id>.
# Propietario del comando configurado telegram:<id> (commands.ownerAllowFrom estaba vacío).
Aprobar al primer usuario como propietario del comando cambia la configuración que requiere un\nreinicio de la puerta de enlace — OpenClaw lo hace automáticamente (verás\ncambio de configuración requiere reinicio de la puerta de enlace luego el reinicio del proveedor de Telegram en los\nregistros). Espera unos segundos para que vuelva antes de enviar otro mensaje.
De vuelta en Telegram, simplemente habla con él — no se necesita configuración adicional; OpenClaw con tu modelo\nresponde de manera conversacional desde el principio. Prueba algo como:
\nEn una oración, ¿cuál es el objetivo de poner un proxy inverso frente a mi agente?
Responde con una respuesta real — la cadena completa está activa: tu teléfono → Telegram →\npuerta de enlace → OpenAI → respuesta. Tu agente autoalojado ahora está en tu bolsillo. (Proporcionarle\nherramientas y habilidades vendrá en guías posteriores; el chat conversacional funciona de inmediato.)
\n![\"El](\"https://wec.wiline.com/docs/es/assets/images/tg-step6-working-7acac4effbd1c03d0657534125e3ea3b.png\")
Tu agente ahora está en tu bolsillo — una línea privada de Telegram a tu propia IA, sin necesidad de un webhook público.
Abrir t.me/BotFather en un navegador web simple muestra un botón de Iniciar que no hace\nnada — esa página es solo la tarjeta pública del bot y necesita un cliente de Telegram conectado\npara poder transferir. Usa la aplicación de escritorio/teléfono, o inicia sesión en\nweb.telegram.org (vincula un dispositivo de escritorio escaneando el QR desde tu teléfono:\nConfiguración → Dispositivos → Vincular dispositivo de escritorio), luego envía un mensaje a BotFather allí.
No es un error — es la puerta de emparejamiento. Los remitentes desconocidos deben ser aprobados primero\n(Paso 5). Después de la aprobación, el bot chatea normalmente.
\nProxy headers detected from untrusted addressSi seguiste la Parte 2, la puerta de enlace registra esto porque Caddy está delante de ella.\nEs una advertencia, no un fallo. Para silenciarlo y restaurar la detección correcta del cliente,\nconfigura gateway.trustedProxies a la red de tu proxy.
event loop degraded bajo carga.\nPara un bot ocupado, dale más CPU/RAM.Has terminado Parte 3 de la serie Autoalojamiento de OpenClaw. A continuación:
\nLuego comienza la serie Autoalojamiento de Hermes — Autoalojar el Agente Hermes con memoria persistente — para un agente cuyo contexto sobrevive a los reinicios.
\nLos archivos complementarios para la serie se encuentran en el repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
\nElimina el canal de Telegram (mantiene el resto de OpenClaw en funcionamiento):
\ndocker compose run --rm openclaw-cli channels remove --channel telegram
docker compose restart openclaw-gateway
Y /revoke el token del bot en BotFather si has terminado con él.
+En Artículo 1 hicimos funcionar OpenClaw —\npero solo a través de HTTP sin cifrar, con un workaround allowInsecureAuth. Aquí colocamos\nCaddy frente a él como un proxy inverso: verdadero HTTPS,\nautenticación emparejada por dispositivo, y los puertos del gateway cerrados para que el proxy sea la única\nforma de acceso. Cada comando y error a continuación proviene de la implementación real.
Continúa desde el Artículo 1 en la misma instancia WEC — Ubuntu 22.04.5 LTS, OpenClaw\n2026.6.8. Usamos Caddy 2 (caddy:2). Debido a que esta máquina no tiene un dominio público,\nusamos la CA interna de Caddy (tls internal) para HTTPS autofirmado; la\nsección Pasando a producción muestra el cambio de una línea a certificados reales de\nLet's Encrypt una vez que tengas un dominio.
Caddy termina HTTPS y hace un proxy inverso al gateway de OpenClaw a través de la\nred interna de Docker. El gateway deja de publicar sus propios puertos — el único punto de entrada\nse convierte en Caddy en :443.
~/openclawopenclaw.local + una entrada en hosts.cd ~/openclaw
docker compose ps
Deberías ver openclaw-gateway Up (healthy), publicando 18789/18790/3978.\nEse es nuestro estado inicial: funcionando, pero solo HTTP.
La configuración de Caddy: servir HTTPS y hacer proxy a todo al gateway. tls internal\nusa la propia CA local de Caddy — no se necesita un dominio público.
cat > Caddyfile <<'EOF'
# Caddy selecciona su certificado por SNI (el nombre de host en el apretón de manos TLS).
# Una IP desnuda no envía SNI, así que usamos un nombre de host. Con un dominio público, coloca tu
# dominio aquí y elimina `tls internal` para Let's Encrypt automático.
openclaw.local {
tls internal
reverse_proxy openclaw-gateway:18789
}
EOF
El objetivo del proxy es openclaw-gateway:18789 — Caddy accede al gateway por su\nnombre de servicio de Compose a través de la red compartida de Docker.
docker compose fusiona automáticamente un docker-compose.override.yml, así que agregamos un servicio caddy\nsin tocar el archivo de compose oficial de OpenClaw:
cat > docker-compose.override.yml <<'EOF'
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- \"80:80\"
- \"443:443\"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
EOF
caddy_data persiste la CA local + certificados a través de reinicios.
docker compose up -d
docker compose ps
Caddy se inicia junto al gateway con 443 publicado, y genera su\nCA interna + un certificado en la primera ejecución.
![\"Contenedor](\"https://wec.wiline.com/docs/es/assets/images/caddy-step4-up-d53a3b63c4e346428a8e733249b2049a.png\")
docker compose up -d también inicia el ayudante de un solo uso openclaw-cli; su inactividad\naquí es inofensiva — lo invocamos con docker compose run --rm cuando es necesario.
Accede al endpoint de salud del gateway a través de Caddy. --resolve hace que curl envíe\nel nombre de host (SNI) mientras apunta a la máquina:
curl -k --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz
# {\"ok\":true,\"status\":\"live\"}
tlsv1 alert internal error?Eso sucede si usaste una IP desnuda como dirección del sitio — consulta\nSolución de problemas #1. Usa un nombre de host.
Ahora el tráfico llega a través de https://openclaw.local. Dos cambios de configuración:
allowedOrigins (la UI de Control rechaza orígenes desconocidos).allowInsecureAuth — HTTPS es un contexto seguro, por lo que el\nworkaround del Artículo 1 ya no es necesario.docker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js config set --batch-json '[{\"path\":\"gateway.controlUi.allowedOrigins\",\"value\":[\"https://openclaw.local\"]},{\"path\":\"gateway.controlUi.allowInsecureAuth\",\"value\":false}]'
docker compose restart openclaw-gateway
Abre https://openclaw.local/ en tu navegador (en una máquina privada, primero mapea\n10.80.4.212 openclaw.local en el archivo hosts de tu máquina — /etc/hosts en\nmacOS/Linux, o C:\\Windows\\System32\\drivers\\etc\\hosts editado como Administrador\nen Windows).
Primero recibirás una advertencia de certificado — \"Tu conexión no es privada\"\n(NET::ERR_CERT_AUTHORITY_INVALID). Esto es esperado con tls internal: el\ncertificado está firmado por la CA local de Caddy, que tu sistema operativo no\nconfía. Haz clic en Avanzado → Proceder a openclaw.local (inseguro) para continuar. (Con un\ndominio real + Let's Encrypt, el certificado es públicamente confiable y esta advertencia\nnunca aparece — consulta Pasando a producción.)
![\"Advertencia](\"https://wec.wiline.com/docs/es/assets/images/caddy-step7-cert-warning-f6015d4f4498bdd7f495c01e08e91cf5.png\")
Ahora la página se carga — pero con allowInsecureAuth desactivado, el gateway requiere\nemparejamiento de dispositivo antes de que este navegador pueda usar la UI de Control. Ese es el flujo seguro haciendo su trabajo. La pantalla muestra un id de solicitud; apruébalo en el host:
docker compose run --rm openclaw-cli devices approve <request-id-from-the-screen>
![\"Pantalla](\"https://wec.wiline.com/docs/es/assets/images/caddy-step7-pairing-95202988ec2160fdef5dcd2e33fce67f.png\")
De vuelta en el navegador, haz clic en Conectar nuevamente — se empareja y carga el panel.
\nEl gateway aún publica 18789 al host, por lo que http://<vm-ip>:18789 es\ntodavía accesible en HTTP sin cifrar, eludiendo a Caddy. Ciérralo: deja de publicar los\npuertos del gateway para que Caddy en :443 sea la única puerta. Caddy aún puede acceder a él a través\nde la red interna.
cat > docker-compose.override.yml <<'EOF'
services:
openclaw-gateway:
# Deja de publicar los puertos del host del gateway — Caddy accede a él internamente, así que el
# único punto de entrada es HTTPS en :443.
ports: !reset []
caddy:
image: caddy:2
restart: unless-stopped
ports:
- \"80:80\"
- \"443:443\"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
EOF
docker compose up -d
ports: !reset [] limpia los puertos que el compose base publicó.
curl -s -m 5 http://<vm-ip>:18789/healthz ; echo \" <- HTTP directo (debería FALLAR)\"
curl -sk --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz ; echo \" <- a través de Caddy (debería funcionar)\"
El primero no devuelve nada (conexión rechazada) — la puerta insegura ha desaparecido. El\nsegundo aún devuelve {\"ok\":true,\"status\":\"live\"}.
Tu OpenClaw ahora es accesible solo a través de HTTPS, emparejado por dispositivo.
\n![\"UI](\"https://wec.wiline.com/docs/es/assets/images/caddy-control-ui-https-814c25fc8dd38568d2226856190421ba.png\")
Ahora puedes poner verdadero HTTPS y autenticación frente a cualquier servicio autoalojado — y probar que\nla puerta trasera está cerrada.
tlsv1 alert internal errorOcurre cuando la dirección del sitio en el Caddyfile era una IP desnuda (https://10.80.4.212):
curl: (35) error:0A000438:SSL routines::tlsv1 alert internal error
Los registros de Caddy mostraron que el certificado se obtuvo correctamente. Causa: TLS selecciona un certificado\npor SNI (el nombre de host en el apretón de manos), pero las conexiones a una IP desnuda no envían SNI — así que Caddy no puede\ncoincidir un certificado y aborta. Solución: usa una dirección de sitio con nombre de host\n(Paso 2). Un lector con un dominio real nunca enfrenta esto — el dominio es el SNI.
\nEn la primera conexión HTTPS después de desactivar allowInsecureAuth:
Se requiere emparejamiento de dispositivo — Este navegador necesita una aprobación única del host del Gateway
antes de que pueda usar la UI de Control.
Causa: este es el flujo seguro correcto — con la autenticación insegura desactivada, cada nuevo\nnavegador debe ser aprobado. Solución: docker compose run --rm openclaw-cli devices approve <request-id>. (El CLI puede registrar scope upgrade pending approval … using local fallback pero aún completa la aprobación.)
NET::ERR_CERT_AUTHORITY_INVALIDEsperado con tls internal — el certificado está firmado por la CA local de Caddy, que tu\nsistema operativo no confía. Haz clic para continuar en una máquina privada. Con un dominio público + Let's\nEncrypt (a continuación), el certificado es confiable y no hay advertencia.
Con un dominio real, intercambia dos líneas en el Caddyfile — apúntalo a tu dominio y\nelimina tls internal:
- openclaw.local {
- tls internal
+ openclaw.example.com {
reverse_proxy openclaw-gateway:18789
}
Luego apunta el registro A del dominio a la IP pública de la VM y abre 80 + 443\na Internet. Caddy automáticamente provisiona y renueva un certificado de Let's Encrypt\n— confiable, sin advertencias, sin --resolve o /etc/hosts necesarios. Actualiza\nallowedOrigins a https://openclaw.example.com.
:443 de Caddy está expuesto; el gateway no tiene puertos de host\n(Paso 8).openclaw devices).https://openclaw.local.OPENCLAW_GATEWAY_TOKEN si alguna vez ha sido\nmostrado (capturas de pantalla, comparticiones de pantalla).Has terminado Parte 2 de la serie Autoalojamiento de OpenClaw. A continuación:
\nLos archivos complementarios (Caddyfile, docker-compose.override.yml) se encuentran en el repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
Para eliminar solo Caddy y reabrir los puertos directos, elimina docker-compose.override.yml\ny Caddyfile, luego docker compose up -d. Para detener todo:
docker compose down
Tu asistente de IA no tiene que vivir en la nube de otra persona.
\nDespliega un agente de IA OpenClaw autoalojado en una instancia WEC con\nDocker Compose — desde iniciar la VM hasta un agente que realmente responde, usando\ntu propia clave de API de modelo. Cada comando, versión y error a continuación fue capturado\nde un despliegue real en una instancia WEC.
\n\nTraes tu propia clave de API de modelo (OpenAI en esta guía); WiLine maneja el\nalojamiento. Esto se reprodujo en una instancia WEC — Ubuntu 22.04.5 LTS, 8 vCPU,\n15 GiB RAM, 25 GB de disco libre. Versión de OpenClaw 2026.6.8, imagen\nghcr.io/openclaw/openclaw:latest.
Un único contenedor gateway de OpenClaw, configurado con tu proveedor de modelo,\naccesible a través de su interfaz de Control UI web y CLI.
\n\n~/.ssh/id_ed25519 o similar)Inicia una VM de WiLine que cumpla con estos requisitos:
\n| Requisito | Valor |
|---|---|
| SO | Ubuntu 22.04 LTS (o 24.04 LTS) |
| Cómputo | ≥ 2 vCPU / 4 GB RAM — OpenClaw necesita ≥ 2 GB; la primera ejecución puede ser OOM-killed (salida 137) en hosts de 1 GB |
| Disco | 30 GB NVMe — 10 GB se llena rápido una vez que las imágenes de Docker y los registros se almacenan |
| Acceso | Tu clave pública SSH añadida en el momento del despliegue, para que puedas iniciar sesión sin contraseña |
La guía del portal ya está documentada — sigue estos pasos y vuelve:
\n\nUna vez que esté en funcionamiento, inicia sesión por SSH:
\nssh ubuntu@<tu-ip-vm>
Antes de instalar cualquier cosa, confirma con qué estás trabajando — la versión del SO y\nlos recursos disponibles. Toma nota de estos números; son útiles cuando compares\nel rendimiento o abras un ticket de soporte.
\nlsb_release -a
nproc
free -h
df -h /
En nuestra instancia WEC: Ubuntu 22.04.5 LTS, 8 vCPU, ~15 GiB RAM, 25 GB de disco libre.
![\"Terminal](\"https://wec.wiline.com/docs/es/assets/images/step2-box-specs-c821280774bf4f5ec9205092f6646004.png\")
Verifica si Docker ya está presente:
\ndocker --version
docker compose version
Si no está instalado, sigue la guía oficial de Docker para tu distribución —\nInstalar Docker Engine en Ubuntu.\nEl camino más rápido es el\nscript de conveniencia de Docker,\nseguido de añadir tu usuario al grupo docker para que puedas ejecutarlo sin\nsudo:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
Necesitas Docker Compose v2 (el subcomando docker compose, no el binario legado\ndocker-compose).
Si Docker ya está presente, el script get.docker.com lo detecta y advierte\nen lugar de reinstalar — no lo fuerces en una máquina con contenedores en ejecución. En una\nVM limpia se instala desde cero. Este despliegue se realizó en un host donde Docker\n29.1.3 / Compose v5.0.2 ya estaba instalado.
Crea un directorio de proyecto y descarga el docker-compose.yml oficial de OpenClaw:
mkdir openclaw && cd openclaw
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -o docker-compose.yml
El archivo define dos servicios — openclaw-gateway (el gateway de agente de larga duración)\ny openclaw-cli (una CLI de un solo uso que comparte la red del gateway).\nPor defecto, se construye desde el código fuente; en su lugar, lo apuntaremos a la imagen preconstruida.
.envCrea un .env junto al archivo compose. Fija la imagen preconstruida y establece un\ntoken de panel:
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<pega la salida de: openssl rand -hex 32>
.env fuera de gitContiene tu token de gateway (y cualquier clave). Agrégalo a .gitignore. En su lugar, compromete un\n.env.example con valores de marcador de posición.
Descarga la imagen:
\ndocker compose pull
OpenClaw monta ~/.openclaw en el contenedor. Créalo como tu propio\nusuario primero — de lo contrario, Docker lo crea como root y el contenedor (que\nse ejecuta como usuario node, uid 1000) no puede escribir en él:
mkdir -p ~/.openclaw ~/.openclaw-auth-profile-secrets
Si omites esto, recibirás un error de permisos en la primera ejecución — consulta\nSolución de problemas.
\nAquí es donde traes tu propio modelo — la incorporación solicita tu proveedor y\nclave de API. Esta guía utiliza OpenAI, pero Anthropic y modelos locales funcionan de la misma manera.
\nEjecuta la incorporación de OpenClaw a través del contenedor gateway. Es interactivo — solicita\ntu proveedor y clave de API y escribe la configuración:
\ndocker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js onboard --mode local --no-install-daemon
Sigue los pasos:
\nopenai/gpt-5.5)skip → Saltar por ahora (los canales de mensajería son una guía posterior)openclaw configure)Termina con Incorporación completa.
La incorporación escribió tu proveedor y modelo. Ahora establece las opciones de tiempo de ejecución del gateway —\nmodo de ejecución, enlace de red y los orígenes de Control UI que aceptará — y luego inícialo\ncomo un servicio en segundo plano.
\ndocker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js config set --batch-json '[{\"path\":\"gateway.mode\",\"value\":\"local\"},{\"path\":\"gateway.bind\",\"value\":\"lan\"},{\"path\":\"gateway.controlUi.allowedOrigins\",\"value\":[\"http://localhost:18789\",\"http://127.0.0.1:18789\"]}]'
docker compose up -d openclaw-gateway
Salud del contenedor:
\ndocker compose ps
Quieres Up ... (healthy). Luego accede al endpoint de salud:
curl http://127.0.0.1:18789/healthz
# {\"ok\":true,\"status\":\"live\"}
![\"docker](\"https://wec.wiline.com/docs/es/assets/images/step9-health-2a25a28bc6b53dd20c385259373d72a5.png\")
Confirma que tu clave de proveedor es utilizable:
\ndocker compose run --rm openclaw-cli models status
# openai ... api_key=1 ... status=usable
models status imprime un prefijo de clave enmascarado (sk-proj-…). Recorta o difumina antes de\npublicar la captura de pantalla.
Ahora la verdadera prueba de extremo a extremo. El comando agent necesita un objetivo, así que lista los agentes\nprimero, luego envía un mensaje al predeterminado (main):
docker compose run --rm openclaw-cli agents list
# - main (predeterminado)
docker compose run --rm openclaw-cli agent --agent main \\
--message \"Responde con exactamente una palabra: funcionando\"
# funcionando
Si responde funcionando, toda la cadena — gateway → OpenAI → respuesta — está activa.
![\"El](\"https://wec.wiline.com/docs/es/assets/images/step9-agent-working-91514c6b42235714c1348d5ce9f6e9b9.png\")
La Control UI está en http://<tu-ip-instancia>:18789/; pega tu\nOPENCLAW_GATEWAY_TOKEN en Configuración para iniciar sesión.
Los navegadores bloquean la Control UI a través de HTTP simple en una IP remota (\"Se requiere contexto de navegador seguro\"). Accede a ella a través de un túnel SSH para que se cargue como 127.0.0.1 — consulta\nSolución de problemas #3.
![\"Interfaz](\"https://wec.wiline.com/docs/es/assets/images/step9-control-ui-fe1df8b0971ad1a8192ff40d2ea6856e.png\")
Estos son errores que realmente encontramos durante este despliegue — no hipotéticos.
\nEACCES: permiso denegado, mkdir '/home/node/.openclaw/state'Ocurrió en la primera ejecución de incorporación cuando ~/.openclaw no existía previamente:
[openclaw] El comando CLI falló.
[openclaw] Razón: Falló al abrir la base de datos de estado del plugin.
| EACCES: permiso denegado, mkdir '/home/node/.openclaw/state' | EACCES
Causa: Docker creó automáticamente la fuente de montaje vinculada ~/.openclaw propiedad de\nroot (0:0). El contenedor se ejecuta como usuario node (uid 1000), por lo que no puede escribir\ndentro de ese directorio de propiedad de root.
Solución: da el directorio al uid 1000 (que también es tu usuario ubuntu):
sudo chown -R 1000:1000 ~/.openclaw
Precrear el directorio tú mismo (Paso 6) evita esto por completo.
\n![\"Error](\"https://wec.wiline.com/docs/es/assets/images/error1-eacces-fbbf355224203ecfccd68552fcf0bcb3.png\")
No se seleccionó sesión de destinoLa primera vez que ejecutamos agent sin especificar a quién hablar:
Error: No se seleccionó sesión de destino. Usa --agent <id>, --session-key <key>,
--session-id <id>, o --to <E.164>. Ejecuta openclaw agents list para ver agentes.
Causa: openclaw agent ejecuta un turno contra un agente/sesión específica; sin\nun canal configurado no hay un objetivo implícito.
Solución: lista los agentes y pasa el id explícitamente:
\ndocker compose run --rm openclaw-cli agents list # muestra: main (predeterminado)
docker compose run --rm openclaw-cli agent --agent main --message \"...\"
![\"El](\"https://wec.wiline.com/docs/es/assets/images/error2-no-session-c405ca89ca87bd411080165c514046e5.png\")
Abrir la Control UI desde otra máquina (por ejemplo, macOS) en la IP de la VM a través de\nHTTP simple, la página se niega a conectar:
\nSe requiere contexto de navegador seguro
Esta página se está ejecutando a través de HTTP simple, por lo que el navegador no puede crear la
identidad del dispositivo que espera el Gateway.
Causa: los navegadores solo exponen las API criptográficas que OpenClaw necesita en un contexto seguro — HTTPS, o localhost/127.0.0.1. Un http://<ip>:18789 remoto no es ninguno de los dos, por lo que está bloqueado en el navegador, independientemente de la bandera del lado del servidor\ngateway.controlUi.allowInsecureAuth.
Solución: tunela el puerto a través de SSH para que el navegador hable con 127.0.0.1 (un contexto seguro). En tu máquina local:
ssh -L 18789:127.0.0.1:18789 ubuntu@<tu-ip-vm>
Luego abre http://127.0.0.1:18789/#token=<tu-token> localmente. La solución adecuada a largo plazo es HTTPS a través de un proxy inverso — la próxima guía.
![\"El](\"https://wec.wiline.com/docs/es/assets/images/error3-secure-context-3e5792a56fae6a2ea2a8f9e0f0aa4c3f.png\")
Al iniciar, el gateway registró advertencias que vale la pena actuar antes de cualquier exposición pública:
\ngateway.controlUi.allowInsecureAuth=true — marcado como peligroso. Ejecuta\ndocker compose run --rm openclaw-cli security audit.plugins.allow está vacío — los plugins no empaquetados (por ejemplo, codex) pueden\ncargarse automáticamente. Establece una lista de permitidos explícita de ids de plugins de confianza.Endurecer esto detrás de un proxy inverso con HTTPS es el tema de la próxima guía.
\nAhora puedes desplegar y operar tu propio agente de IA en una máquina que controlas.
Pasaste de una instancia WEC vacía a un agente de IA autoalojado en funcionamiento:
\nEl agente es tuyo: tu clave, tu máquina, tus datos. A partir de aquí se trata de hacerlo\nseguro, accesible y útil.
\nOpenClaw no es un chatbot — es un agente autónomo que puede actuar en tu máquina. Ahora\nque está en funcionamiento, aquí hay lo que desbloquea (algunas funciones necesitan configuración adicional, y\ncubrimos las más importantes más adelante en esta serie):
\nUsos reales típicos que la gente realiza: gestión de bandejas de entrada y calendarios, procesamiento de documentos,\ntareas de infraestructura en la máquina, tuberías de contenido y pruebas de código autónomas.
\nEsta es Parte 1 de la serie Autoalojamiento de OpenClaw sobre cómo ejecutar infraestructura de IA de calidad de producción en una instancia WEC. Próximamente:
\nallowInsecureAuth y acceder a la Control UI desde cualquier lugar, de forma segura.Los archivos complementarios para esta guía — docker-compose.yml y .env.example — se encuentran en\nel repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
docker compose down # detener + eliminar contenedores
docker compose down --rmi all -v # también eliminar la imagen y volúmenes
Para eliminar la configuración/estado en el host:\nrm -rf ~/.openclaw ~/.openclaw-auth-profile-secrets. Para detener la facturación por completo,\nelimina la VM desde el portal de WiLine.