"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.

Cómo funciona la evaluación​

Cada test pasa por la misma tubería. El detalle más importante: el transform se ejecuta sobre la salida del modelo antes de que la aserción la vea — así es como recuperamos JSON desordenado antes de validarlo.

Requisitos previos​

• Una clave de API de Inferencia WEC — consulta Inferencia → Claves de API.

• Los 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-your-key'
  

Paso 1 — Un esquema estricto y un fallo real​

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, otro),
    "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, otro] }
          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:

ticket                                    [zai-org/GLM-5.2]
Me cobraron dos veces por mi instancia…      [FAIL] ```json
                                          { "categoría": "facturación", "prioridad": "alta", … }
                                          ```
Mi VM no arranca después de la última…        [PASS] { "categoría": "técnica", … }

✓ 1 aprobado (50%)   ✗ 1 fallido (50%)

Figura 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.

Paso 2 — Recuperar salida cercada con un transform​

Un transform se ejecuta en la salida del modelo antes de las afirmaciones. Aquí eliminamos las cercas. (Este bloque utiliza cuatro comillas invertidas porque la configuración en sí contiene tres comillas invertidas.)

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, otro),
    "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, otro] }
          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.

Figura 2. El transform elimina las cercas de código, por lo que el ticket que falló anteriormente se analiza.

Paso 3 — La solución más limpia: modo JSON​

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, otro),
    "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, otro] }
          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.

Figura 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.

Paso 4 — Matriz de fiabilidad entre modelos WEC​

Ejecuta la configuración en modo JSON contra los cuatro modelos de chat. Esta es la recompensa — una comparación de fiabilidad específica de WEC que no puedes obtener de una tabla de clasificación genérica.

cat > 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, otro),
    "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, otro] }
          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 ("Proceso de Pensamiento…") en lugar de JSON — a pesar de que response_format esté configurado.

Figura 4. response_format configurado en los cuatro — pero los dos modelos orientados al razonamiento lo ignoran.

Paso 5 — Verificar: ¿está response_format haciendo algo?​

No asumas que el razonamiento fue causado por el modo JSON. Vuelve a ejecutar la misma matriz sin response_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, otro),
    "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, otro] }
          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.

Figura 5. Resultado idéntico sin modo JSON — la bandera no estaba haciendo nada.

Paso 6 — Una transformación más robusta: extraer el JSON​

Los modelos de razonamiento sí emiten JSON — simplemente está enterrado en prosa. En lugar de eliminar cercas, extrae 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, otro),
    "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, otro] }
          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 se recuperan completamente; qwen3.5:9B recupera uno de dos. El único fallo restante es revelador: esa respuesta emitió JSON y luego siguió razonando (con más llaves), por lo que la codificación codiciosa { … } capturó en exceso y produjo JSON inválido.

Figura 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).

Paso 7 — Verlo en el navegador​

La tabla del terminal está bien para una lectura rápida, pero el informe web es donde una matriz como esta cobra vida:

npx -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%. Abajo, cada proveedor es una columna que puedes expandir para ver la respuesta completa (así es como obtuvimos el fallo por captura excesiva en Figura 10 — el terminal lo trunca).

Figura 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.

Paso 8 — Protegerlo en CI​

Promptfoo sale con un código no cero cuando las pruebas fallan, así que una línea es una puerta (ponla en un script o Makefile, nunca en tu shell interactivo):

npx -y promptfoo@latest eval -c promptfooconfig.yaml \
  && echo "✅ aprobado" \
  || { echo "❌ evaluación fallida — bloqueando"; exit 1; }

Figura 8. Un fallo real bloquea: 7/8 aprobados, pero la captura excesiva de qwen3.5:9B (del Paso 6) activa la puerta — el código de salida no cero es la señal que CI usa para bloquear un PR.

En GitLab:

eval:
  image: node:22
  script:
    - npx -y promptfoo@latest eval -c promptfooconfig.yaml
  # WEC_API_KEY configurada como una variable CI/CD enmascarada — nunca comprometida.

Lo que aprendimos​

• La elección del modelo domina. GLM-5.2 y Qwen2.5-3B producen JSON válido según el esquema de manera fiable y son ~8× más baratos que los modelos de razonamiento. Para salida estructurada en WEC, comienza allí.
• Los modelos de razonamiento (qwen3.5:9B, y gemma4 el día que probamos) narran su pensamiento y cuestan mucho más — malas opciones para JSON estricto.
• Un transform es tu red de seguridad — la eliminación de cercas recupera el caso común; la extracción de JSON recupera 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; valida en su lugar.
• La evaluación es el punto. Cada una de estas sorpresas fue capturada automáticamente, antes de que llegara a producción.

Solución de problemas​

"La función de transformación no devolvió un valor"​

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`

Figura 9. Sin return, Promptfoo da error en lugar de transformar.

Un modelo devuelve razonamiento alrededor del JSON​

Si is-json falla con "Se esperaba que la salida fuera JSON válido" y la respuesta contiene una narració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 GLM-5.2 / Qwen2.5-3B, o acepta que el transformador de extracción es un esfuerzo de buena fe, no una garantía.

Figura 10. El caso fallido expandido en el informe: qwen3.5:9B devolvió JSON válido y luego 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."

"No se puede convertir el argumento a un ByteString"​

Tu clave de API pegada contiene un carácter Unicode invisible. Elimínalo:

export WEC_API_KEY=$(printf '%s' "$WEC_API_KEY" | LC_ALL=C tr -cd '[:print:]')

Figura 11. Un carácter errante en la clave activa el encabezado HTTP antes de que se envíe cualquier solicitud.

¿Qué sigue?​

• Conjuntos de regresión DeepEval — convierte estas verificaciones en una ejecución de regresión versionada y con puerta de CI.
• Trazado — ve por qué una respuesta salió mal, no solo que falló.

¿Tienes un caso de salida estructurada que aún se escapa? Esa es la próxima prueba que agregar.

No enviarías código sin pruebas — pero la mayoría de los equipos envían características de LLM con "se ve bien para mí." Evaluaciones (evals) solucionan eso: defines casos de prueba y criterios de aprobación/rechazo, luego mides tu modelo de manera objetiva — detectando regresiones, comparando modelos y bloqueando despliegues.

En 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.

Requisitos previos​

• Una cuenta de WEC (WiLine Edge Cloud) y una clave de API de Inferencia — ver Inferencia → Claves API.

• Node.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.

Figura 1. Crea una clave en Inferencia → Claves API, luego cópiala.

Pon tu clave en la terminal:

export WEC_API_KEY='sk-your-key-here'

Paso 1 — Ver qué modelos tienes​

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.

Paso 2 — Tu primera evaluación​

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

Figura 4. Tu primera evaluación aprobada contra la API de Inferencia WEC.

icontains es una afirmación determinista — una verificación de subcadena sin distinción de mayúsculas. Barata, rápida y perfecta para hechos con una respuesta conocida.

Paso 3 — El informe visual​

npx -y promptfoo@latest view

Esto abre una interfaz web local con cada aviso, salida y aprobación/rechazo — mucho más fácil de escanear que la terminal una vez que tienes más de unos pocos casos.

Figura 5. promptfoo view — los mismos resultados en el navegador.

Paso 4 — Agregar un segundo modelo​

Agregar un proveedor es un bloque extra. 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

Figura 6. Ambos modelos aprueban. Los resultados de GLM-5.2 se sirven desde caché (0 nuevas solicitudes); solo Qwen2.5 realiza llamadas en vivo.

Paso 5 — Califica calidad, no subcadenas (rúbrica LLM)​

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

Figura 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.

Paso 6 — Líneas de defensa: latencia​

Una respuesta correcta que tarda 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:

Figura 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:

sed -i 's/threshold: 5000/threshold: 60000/' promptfooconfig.yaml
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

Figura 9. Con un umbral de 60 s, las mismas llamadas pasan fácilmente — Duración: 2s.

Paso 7 — Líneas de defensa: latencia + límite de tokens​

La afirmación de cost no funciona contra WEC (ver 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

Figura 11. Con un umbral de 30 s y un límite de 16 tokens, ambos casos aprueban.

Paso 8 — Validar salida estructurada (validación de esquema JSON)​

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

Figura 12. GLM-5.2 devuelve JSON compacto y válido según el esquema en el primer intento.

Paso 9 — La recompensa: compara todos los modelos WEC​

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:

cat > 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

Figura 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.

Figura 13b. El desglose de tokens cuenta la verdadera historia: el modelo de razonamiento costó 13× más para la misma tarea.

Dos lecciones se desprenden de inmediato:

• qwen3.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.
• El costo varía ~13×. El modelo de razonamiento consumió 2,650 tokens para la misma tarea que los demás hicieron en ~200. Para un trabajo de extracción de JSON, los modelos más pequeños son correctos y mucho más baratos.

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.

Paso 10 — Hazlo una puerta​

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: $?"

Figura 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:

npx -y promptfoo@latest eval -c promptfooconfig.yaml \
  && echo "✅ evaluación aprobada" \
  || { echo "❌ evaluación fallida — bloqueando"; exit 1; }

Figura 15a. La puerta vuelve a ejecutar la evaluación de matriz desde caché — mismo resultado 9/3.

Figura 15b. Promptfoo sale no cero, se activa la rama ||, y la puerta bloquea.

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 comités.

Ahora un cambio de aviso que silenciosamente rompe la salida JSON, o un cambio de modelo que duplica la latencia, falla la tubería antes de que llegue a los usuarios.

Solución de problemas (errores reales)​

1. Error de ByteString en la primera evaluación​

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.

Figura 2. Cada llamada a la API falla antes de llegar al servidor — la clave ni 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 desde ciertas fuentes.

Solución: Elimina los caracteres no imprimibles de la clave:

export 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

Figura 3. Después de eliminar, la longitud de la clave confirma que no quedan caracteres extra. Vuelve a ejecutar la evaluación — pasa.

2. Errores de afirmación de costo inmediatamente​

Error: La afirmación de costo no admite proveedores que no devuelven costo

Figura 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).

Solució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.

3. 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 afectar tu terminal. Si necesitas probar la puerta localmente, usa || echo "❌ evaluación fallida" (sin exit 1) para ver la salida de manera segura.

¿Qué sigue?​

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 de CI.

Próximamente en esta serie:

• JSON confiable: valida el esquema de la salida estructurada de tu modelo — ahora disponible (parte 2): recupera la salida envuelta en cercas y razonamiento con transformaciones, compara modelos por confiabilidad de JSON, y bloquea todo en CI.
• Evaluaciones calificadas por modelo bien hechas — calibrando llm-rubric, puntuación de factualidad y verificaciones de múltiples jueces para que tu calificador sea confiable.
• Capturando alucinaciones — emparejando estas técnicas con la evaluación de alucinaciones RAG de WEC.
• Evaluando audio — puntuando la precisión de la transcripción de Whisper en la API de Inferencia WEC.

Hermes Agent es el agente de IA de código abierto (MIT) de Nous Research — "el agente que crece contigo." Su característica destacada es memoria persistente: aprende sobre tus proyectos y no olvida entre reinicios. Esta guía lo despliega en la misma Instancia WEC que ya usas para OpenClaw, lo apunta a un modelo y prueba que la memoria sobrevive a un reinicio completo.

Por qué la memoria persistente es importante​

Un agente que olvida en cada reinicio es un juguete. Hermes mantiene un almacenamiento duradero en disco bajo ~/.hermes/:

• ~/.hermes/memories/MEMORY.md — un archivo legible por humanos de hechos que el agente ha decidido recordar.
• ~/.hermes/state.db — una base de datos SQLite que contiene cada sesión y mensaje, con índices de búsqueda de texto completo FTS5 superpuestos para que el agente pueda buscar su propia historia.

Un despliegue, un fallo o un reinicio no borran lo que aprendió. Esa es la diferencia entre una demostración de chat y un agente en el que puedes confiar día a día — y es exactamente lo que probamos al final.

Las piezas​

Todo corre en una sola WEC Instance. Hermes habla con un modelo a través de la WEC Inference API, guarda su memoria en disco local y corre como servicio de usuario de systemd — así se reinicia solo tras un reinicio y su memoria sigue ahí:

Requisitos previos​

• Una Instancia WEC existente con acceso a la terminal (la caja de OpenClaw funciona).
• Un modelo: ya sea un inicio de sesión en Nous Portal, o tu propia clave API de proveedor (usamos una clave de OpenAI aquí; Modelos WEC con glm-5.2 también funcionan).
• Nada que preinstalar — el instalador maneja Python, Node.js y el motor del navegador.

Paso 1 — Instalar Hermes​

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

El instalador resuelve un entorno virtual de Python con uv, instala las herramientas de navegador de Node.js, descarga un Playwright Chromium, sincroniza las habilidades empaquetadas y coloca un lanzador 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 el asistente de configuración...

Luego lanza automáticamente el asistente de configuración. Recarga tu terminal después para que el comando hermes esté en tu PATH:

source ~/.bashrc

Paso 2 — Ejecutar el asistente de configuración​

El asistente guía a través del tipo de configuración, backend de terminal y mensajería. En una caja que ya ejecutó OpenClaw, ofrece importar la configuración antigua primero — puedes previsualizar lo que se migraría antes de que cambie algo.

La primera elección es cómo configurar Hermes:

• Configuración rápida (Nous Portal) — un inicio de sesión OAuth, sin claves API. El Portal agrupa un modelo y una puerta de enlace de herramientas. Requiere una suscripción activa a Nous Portal.
• Configuración completa (trae tus propias claves) — configuras proveedores y pegas tus propias claves.

Para el resto del asistente:

• Backend de terminal: Local — los comandos se ejecutan directamente en esta máquina.
• Mensajería: Omitir por ahora (puedes conectar Telegram/Discord más tarde con hermes 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.

Paso 3 — Conectar un modelo​

Fuera de la caja, el modelo predeterminado se enruta a través del Nous Portal / OpenRouter y necesita una clave. Para usar tu propio proveedor en su lugar, ejecuta:

hermes setup model

Luego selecciona OpenAI ▸ OpenAI API, pega tu clave API cuando se te pida (se escribe en ~/.hermes/.env — nunca se muestra), acepta la URL base predeterminada https://api.openai.com/v1, y elige un modelo — usamos gpt-5.5:

Clave API guardada.
URL base [https://api.openai.com/v1]:
Seleccionar modelo predeterminado:
 → (●) gpt-5.5

Confirma que el modelo y la clave están saludables:

hermes doctor

◆ Archivos de configuración
  ✓ El archivo ~/.hermes/.env existe
  ✓ Clave 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, Discord, generación de imágenes) — no necesarias para esta guía.

Paso 4 — Chatear y guardar una memoria​

Inicia una sesión interactiva:

hermes

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.
╰─────────────────────────────────────────────────────────────────────╯

Esa escritura crea ~/.hermes/memories/MEMORY.md. Sal con /exit o Ctrl+D.

Paso 5 — Probar que la memoria sobrevive a un reinicio​

Este es el objetivo principal. La puerta de enlace de Hermes se instala como un servicio de usuario systemd con linger habilitado, por lo que vuelve automáticamente después de un reinicio — sin necesidad de iniciar sesión. Reinicia el servicio y luego reinicia toda la caja para hacer la prueba a prueba de fallos:

systemctl --user restart hermes-gateway   # reinicia solo el servicio de puerta de enlace
sudo reboot                               # luego reinicia toda la caja

Reconéctate una vez que la caja esté activa y confirma que el servicio se reinició por sí mismo:

systemctl --user status hermes-gateway --no-pager

● hermes-gateway.service - Hermes Agent Gateway - Integración de Plataforma de Mensajería
     Cargado: cargado (...; habilitado; ajuste de proveedor: habilitado)
     Activo: activo (en ejecución) desde el jue 2026-06-25 21:21:54 UTC; hace 1min 36s

Ahora abre una sesión nueva y pregunta — sin contexto previo, ID de sesión completamente nuevo:

hermes

● ¿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.
╰─────────────────────────────────────────────────────────────────────╯

Recordó el hecho desde el disco después de un reinicio completo. Inspecciona dónde vive ese estado duradero:

cat ~/.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	/home/ubuntu/.hermes/state.db

Un MEMORY.md en texto plano que puedes leer y editar, respaldado por un state.db de SQLite para sesiones. Esa es la memoria persistente — y acaba de sobrevivir a un reinicio.

cat ~/.hermes/memories/MEMORY.md

sudo apt install -y sqlite3
sqlite3 ~/.hermes/state.db '.tables'

CREATE VIRTUAL TABLE messages_fts USING fts5(content);
CREATE VIRTUAL TABLE messages_fts_trigram USING fts5(content, tokenize='trigram');

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

Bonificación — leer la conversación que el agente almacenó​

La tabla messages contiene el texto real de cada turno. Cada fila tiene un role — user (lo que escribiste), assistant (la respuesta de Hermes), o tool (el resultado de una herramienta) — así que puedes 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 parte interesante es cómo se escribió la memoria. El asistente no editó un archivo directamente — emitió una llamada a la herramienta memory, y esa herramienta es la que escribió MEMORY.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.\"}]}"}}

Así que la cadena completa es: tú escribes → el agente decide que vale la pena conservar → llama a la herramienta memory con action: add → eso escribe el hecho en MEMORY.md, mientras que toda la conversación permanece en state.db, completamente buscable a través de FTS5. Dos almacenes, una memoria duradera.

¿Qué puedes hacer con ello?​

Una memoria que sobrevive a los reinicios solo importa por lo que el agente hace con ella. Con Hermes en funcionamiento, la misma instalación ofrece estas capacidades (las viste en la lista de herramientas de hermes doctor) — aquí está lo que desbloquean día a día:

• Realiza trabajo real en la caja. Las herramientas terminal y code_execution le permiten actuar, no solo chatear — por ejemplo, "clona este repositorio, instala dependencias y ejecuta las pruebas," o "verifica por qué se está llenando el disco." Lo hace en la Instancia WEC y reporta de vuelta.
• Controla desde tu teléfono. Una puerta de enlace de mensajería (Telegram, Discord, Slack, y más) significa que puedes darle una tarea desde cualquier lugar — sin SSH. (Configuración en la Parte 2.)
• Ponlo en un horario. La herramienta cronjob ejecuta trabajos recurrentes: un informe matutino, un informe semanal de uso del disco, o vigila un servicio y avísame cuando falle — entregado a tu canal de mensajería. (Parte 3.)
• Navega y busca en la web. Con las herramientas de navegador y búsqueda web puede obtener información en vivo y actuar en páginas reales. (Estas necesitan claves API de proveedor — consulta hermes setup tools.)
• Desarrolla habilidades reutilizables y delega. Puede construir habilidades a partir de lo que aprende y delegar subtareas a subagentes — la parte "agente que crece contigo".
• Recuerda a través de todo ello. Todo lo anterior está respaldado por la memoria persistente que acabas de configurar, por lo que el contexto se lleva de una tarea — y un día — al siguiente.

El resto de esta serie convierte cada una de estas en una guía práctica (consulta Qué sigue).

Solución de problemas (real)​

• La Configuración rápida (Nous Portal) se queda atascada en "Esperando aprobación (sondeando)". El inicio de sesión en el Portal necesita una suscripción/crédito activo. Si no tienes uno, presiona Ctrl+C y usa Configuración completa con tu propia clave en su lugar (Paso 3).

• doctor muestra "No se encontró clave API en ~/.hermes/.env". El modelo predeterminado apunta a Portal/OpenRouter. Ejecuta hermes setup model, elige tu proveedor y pega la clave — doctor luego informa "Clave API o endpoint personalizado configurado."

• Advertencia de .env obsoleta al iniciar la puerta de enlace (por ejemplo, MESSAGING_CWD). Inofensiva; sigue 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 de OpenClaw y agregaste un canal de Telegram, la configuración de Hermes detectó OpenClaw y importó esas configuraciones de mensajería en ~/.hermes/.env. Como omitimos terminar la mensajería aquí, la puerta de enlace tiene un token pero no una configuración completa, por lo que sigue reintentando y registrando esta advertencia. (Una caja nueva sin configuración de Telegram de OpenClaw no lo 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.

Qué sigue​

Ahora que Hermes está funcionando con memoria duradera, el resto de la serie convierte cada capacidad anterior en una guía práctica:

• Parte 2 — Controla a Hermes desde Telegram. Termina de migrar el canal de Telegram que Hermes ya importó de OpenClaw (hermes setup gateway, listas de permitidos, verifica que el bot responda), para que puedas darle tareas desde tu teléfono.
• Parte 3 — Ponlo en un horario. Usa la herramienta cron para un informe matutino, un informe semanal, y una alerta de salud del servicio entregada a tu canal.
• Parte 4 — Habilidades personalizadas y subagentes. Enséñale habilidades reutilizables y delega trabajo.

Los enlaces aparecerán aquí a medida que cada parte se publique.

En el Artículo 2 pusimos Caddy delante de OpenClaw para HTTPS, y en el Artículo 3 añadimos un canal de Telegram. El gateway funciona — pero Caddy sigue escuchando en 0.0.0.0, alcanzable por cualquier cosa que pueda enrutar hasta la máquina. Esta es la chave de ouro de la serie: unimos el servidor y tu laptop a una mesh de NetBird, reapuntamos openclaw.local a la IP de la mesh y cerramos los puertos públicos. La misma URL https://openclaw.local/chat sigue funcionando — pero solo para tus dispositivos. Cada comando y error de abajo proviene de la ejecución real.

Cómo funciona NetBird (y qué vas a construir)​

NetBird tiene dos partes, y la distinción es justamente el punto:

1. El control plane (el servicio gestionado de management + signal de NetBird) — esto es lo único con presencia pública. Cada dispositivo que quiere unirse se autentica contra él (con tu setup key o login SSO), y él intermedia el intercambio de la clave pública WireGuard de cada peer.
2. El data plane — una vez autenticados, los peers se hablan directamente entre sí, cifrados de extremo a extremo sobre WireGuard. Tu tráfico real nunca pasa por un puerto público que tú gestiones; el control plane solo hizo las presentaciones.

Así que estás construyendo una mesh donde el Peer A (tu laptop) alcanza al Peer B (la máquina de OpenClaw) por su dirección privada 100.x — y openclaw.local apunta ahí, con Caddy ligado solo a esa interfaz. El lado público/LAN no tiene nada escuchando.

La idea clave para más adelante: la mesh no se limita a dos peers. Autentícate una vez, y cada nuevo servicio — Ollama, un VDI, WordPress — se une como otro peer con su propia dirección 100.x, alcanzable de forma privada con ningún puerto público que abrir. Configuras el modelo de auth una vez; añades servicios para siempre.

La internet pública solo alcanza al control plane de NetBird — y eso solo autentica peers, nunca lleva el tráfico de tu app. Tus servicios no están "bloqueados por firewall" tanto como invisibles: OpenClaw no tiene IP pública, así que simplemente no hay ruta hacia él desde internet. La única forma de entrar es ser un peer autenticado en la mesh.

En este tutorial conectamos los dos primeros peers — tu laptop y la máquina de OpenClaw. Los demás servicios dejan claro el punto: una vez configurada la auth, Ollama, un VDI, WordPress simplemente se unen a la misma mesh como otro peer 100.x — sin puertos públicos, sin exposición por servicio.

Levanta un control plane de NetBird​

Toda mesh de NetBird tiene dos roles: peers — tus máquinas, es decir la máquina de OpenClaw de las Partes 1–3 y tu laptop — y un control plane que autentica esos peers y emite sus claves de inscripción. Ya tienes el peer (tu máquina de OpenClaw); ahora necesitas un control plane al que se una. Dos formas de conseguirlo:

• Opción A — autoalójalo en WiLine (recomendada). Despliega la plantilla NetBird del Marketplace de WEC: una Instancia WEC dedicada que corre tu propio control plane de NetBird — dashboard, certificado de confianza, sin shell. Así tu red privada completa vive en WiLine — la máquina de OpenClaw y su control plane — sin depender de un tercero.
• Opción B — NetBird gestionado (sin máquina extra). ¿No quieres correr tu propio control plane? Usa el tier gratuito en app.netbird.io — inicia sesión y listo; el control plane es la nube de NetBird. Luego salta a Ahora inscribe tus máquinas.

Los pasos de abajo configuran la Opción A. WEC ejecuta la instalación; tú aportas un email y una IP pública, y unos minutos después tienes tu propio dashboard de NetBird en https://<your-ip>.apps.wiline.cloud con un certificado válido.

1. Obtén una IP pública (Elastic)​

El dashboard necesita una dirección pública. En Networks → Elastic IPs, asigna una IP nueva o elige una libre, y anota su valor (la nuestra: 108.60.112.165). Debe estar en la VPC y zona en la que vas a desplegar. Pasos completos: Configurar Elastic IPs.

2. Despliega una VM con la plantilla​

Esta nueva instancia se convierte en tu control plane de NetBird — una máquina aparte de tu instancia de OpenClaw, que queda intacta. Abre Deploy → Deploy a VM (recorrido completo: Desplegar una máquina virtual). Las elecciones que importan aquí:

• Network — elige la red en la misma VPC/zona que tu Elastic IP (nosotros usamos Local Subnet en Princeton-VPC), para que la IP pueda adjuntarse después.
• Template → Marketplace → Ubuntu 24.04 LTS Netbird.
• Template Configuration — tu email de Let's Encrypt y la Elastic IP del paso 1 como dirección externa.

Termina el asistente y despliega.

3. Adjunta la Elastic IP a la nueva instancia​

La IP no queda ligada al momento de desplegar — la adjuntas una vez que la VM está arriba. Ve a Networks → Elastic IPs → tu IP → ⋯ → Allocate, y selecciona tu nueva instancia (netbird-tutorial). Solo aparecen en la lista las VMs de la misma VPC.

4. Espera al primer arranque, luego verifica que está arriba​

La instancia muestra Running en Compute → Instances en menos de un minuto — pero la plantilla sigue trabajando unos minutos más después de eso, descargando e iniciando los contenedores de NetBird y levantando el dashboard. No esperes que la URL responda de inmediato.

Comprueba desde tu laptop por HTTPS (no con ping — ICMP está bloqueado por firewall, así que un ping fallido no significa que esté caído):

curl -skS -m 10 -o /dev/null -w "%{http_code}\n" https://<your-ip>.apps.wiline.cloud

• 000 / connection refused → aún aprovisionando; espera un minuto y reintenta.
• 301 luego 200 → está arriba (HTTP redirige a HTTPS).

Para verlo directamente, entra por SSH (ssh ubuntu@<your-ip>) y confirma que los contenedores están corriendo y que los puertos están ligados:

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 Up y 80/443 están escuchando.

5. Abre el dashboard y crea tu cuenta​

Abre https://<your-ip>.apps.wiline.cloud — haz clic a través de la advertencia del certificado si aparece (el mismo click-through de certificado autofirmado que el Artículo 2).

Este es tu propio control plane de NetBird, corriendo en tu Instancia WEC. En la primera visita te pide que crees la cuenta de admin — introduce un nombre, email y contraseña, haz clic en Create, luego inicia sesión con esas mismas credenciales. (Esa pantalla de configuración aparece solo una vez; después el dashboard muestra una página normal de Sign in.)

Llegas al dashboard de NetBird — tu control plane privado en tu propio dominio:

Haz clic en Add Peer y NetBird te entrega el comando de inscripción para tu servidor — fíjate en el --management-url apuntando a tu propio dominio:

curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --management-url https://<your-ip>.apps.wiline.cloud

(Ese segundo comando abre un login SSO en el navegador. Para un servidor headless, añade --setup-key <KEY> desde la página Setup Keys de tu dashboard — igual que el flujo gestionado, solo con --management-url añadido.)

Este es el dashboard donde creas las setup keys que inscriben máquinas — que es exactamente lo que hacemos a continuación.

Ahora inscribe tus máquinas​

Ya tienes un control plane (tu propio dashboard de la plantilla, o NetBird gestionado). Ahora pon las dos máquinas en la mesh — la máquina de OpenClaw de las Partes 1–3 y tu laptop — y luego cierra los puertos públicos de la máquina. Estos pasos son los mismos sin importar qué control plane hayas elegido.

Requisitos previos: OpenClaw corriendo detrás de Caddy desde los Artículos 1–3 (alcanzable en https://openclaw.local), un control plane del paso anterior, y acceso por shell a la máquina además de admin en tu laptop.

Paso 1 — Instala el agente de NetBird en la máquina de OpenClaw​

Esta es la máquina de las Partes 1–3 (una Instancia WEC) — la estamos inscribiendo como peer, lo cual es independiente de cualquier servidor de control plane. NetBird trae un instalador de una línea:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Trampa (real): en Ubuntu la instalación dispara el diálogo needrestart — una caja azul de "Which services should be restarted?". El Tab entre botones puede ser tragado por algunas configuraciones de SSH/terminal; usa las flechas para moverte, Espacio para alternar, Enter para confirmar (<Ok> es el predeterminado). El paquete ya está en su lugar para cuando aparece esta caja, así que aunque salgas con Ctrl+C, el agente queda instalado — volver a ejecutar el instalador solo te lo dice:

NetBird seems to be installed already, please remove it before proceeding

(Si vuelves a ejecutar el instalador después de este tutorial, verás en cambio NetBird service is running, please stop it before proceeding — el agente ya está arriba, así que no hay nada que reinstalar.)

Confirma la versión:

netbird version
# 0.73.2

Paso 2 — Crea una setup key y une la máquina de OpenClaw​

Una setup key es el token que inscribe un dispositivo en tu mesh — ideal para un servidor headless (sin necesidad de SSO en navegador).

1. Abre https://app.netbird.io/setup-keys.
2. Create Setup Key → nombre openclaw-tutorial, activa Reusable (para que sirva también para la laptop), por lo demás los valores predeterminados.
3. Copia la key.

Conecta la VM (reemplaza con tu key):

sudo netbird up --setup-key <YOUR_SETUP_KEY>

Comprueba la conexión:

netbird status

Esa NetBird IP (100.87.239.229) es la dirección a la que apunta todo lo de abajo. Peers count: 0/0 es lo esperado — nada más se ha unido todavía.

Paso 3 — Une tu laptop​

Instala el cliente de NetBird en lo que estés usando, luego conéctate con la misma setup key reutilizable. El comando de conexión (netbird up --setup-key …) es idéntico en todos los SO — solo difiere la instalación.

brew install netbirdio/tap/netbird
sudo netbird service install
sudo netbird service start
netbird up --setup-key <YOUR_SETUP_KEY>

WARNING: ... dial unix /var/run/netbird.sock: connect: no such file or directory
Connected

netbird up --setup-key <YOUR_SETUP_KEY>

curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key <YOUR_SETUP_KEY>

Verifica que los dos nodos se ven entre sí, y que el túnel lleva tráfico:

netbird status
ping -c 3 100.87.239.229   # Windows: ping -n 3 100.87.239.229

Peers count: 1/1 — ese peer es la VM. En el dashboard, ambas máquinas ahora aparecen bajo Peers (como las inscribimos con una setup key en lugar de un login SSO, aparecen bajo Servers en vez de User Devices):

Paso 4 — Reapunta openclaw.local a la IP de la mesh​

Desde el Artículo 2, tu archivo hosts mapea openclaw.local a la IP de LAN de la VM (10.80.4.212). Cámbialo por la IP de la mesh (100.87.239.229). La ruta del archivo y el comando de edición difieren por SO:

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

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

$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

Prueba sobre la mesh — antes de tocar ningún puerto:

curl -kI https://openclaw.local/

HTTP/2 200
...
via: 1.1 Caddy

via: 1.1 Caddy sobre la IP de la mesh — el chat ahora fluye a través de NetBird. Carga https://openclaw.local/chat?session=main en el navegador para confirmar que se comporta exactamente como antes. El cert TLS sigue coincidiendo porque el hostname no cambió; solo se movió la IP detrás de él.

Paso 5 — Cierra los puertos públicos​

Aquí está el estado que estamos arreglando. En la VM:

sudo 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, incluida la LAN (y cualquier NAT delante de ella).

El arreglo fiable es ligar los puertos publicados a la IP de la mesh en lugar de a 0.0.0.0, para que Caddy solo escuche en wt0. Edita el servicio de Caddy en docker-compose.override.yml (el override del Artículo 2):

cd /home/ubuntu/openclaw
cp docker-compose.override.yml docker-compose.override.yml.bak

Cambia el bloque de ports de:

    ports:
      - "80:80"
      - "443:443"

para ligarlo a la IP de la mesh:

    ports:
      - "100.87.239.229:80:80"
      - "100.87.239.229:443:443"

Recrea solo Caddy y vuelve a comprobar:

docker compose up -d caddy
sudo ss -tlnp | grep -E ':(80|443)'

Los puertos ya no están en 0.0.0.0 — viven solo en la interfaz de la mesh.

Paso 6 — Demuestra el bloqueo​

Ambas direcciones, de la ejecución real.

Aún alcanzable sobre la mesh (laptop):

curl -kI https://openclaw.local/
# HTTP/2 200 ... via: 1.1 Caddy

Ya no alcanzable en la LAN (VM, golpeando su propia IP de LAN):

curl -kI --connect-timeout 5 --resolve openclaw.local:443:10.80.4.212 https://openclaw.local/

Ese es el resultado: la misma URL, alcanzable solo a través de tu mesh, rechazada en todas las demás partes.

Limpieza​

Elimina la setup key reutilizable ahora que ambos dispositivos están inscritos — Setup Keys → delete en el dashboard. Tus peers siguen conectados; solo estás cerrando la puerta que usaste para añadirlos. Para quitar un dispositivo más adelante, elimínalo bajo Peers → User Devices y ejecuta netbird down en esa máquina.

Solución de problemas (real)​

• El diálogo needrestart no acepta Tab. Usa las flechas / Espacio / Enter. El paquete ya está instalado para cuando aparece la caja.
• Advertencia gRPC de netbird.sock en el primer up. El socket del daemon va un instante por detrás del cliente. Si termina en Connected, ignórala.
• Las reglas de ufw no bloquean el gateway. Los puertos publicados por Docker evitan ufw — liga el puerto a una IP específica (como arriba) o usa la propia cadena DOCKER-USER de Docker.
• Caddy en crash-loop tras reiniciar. Arrancó antes de que wt0 tuviera la IP de la mesh. restart: unless-stopped lo recupera; o ordena Docker después de netbird.service.
• Ping alto hacia un peer. Estás con relay, no directo — funcional, solo más lento. Revisa el Interface type y el detalle del peer en NetBird para el tipo de conexión.

Qué sigue​

Eso cierra la serie Self-hosting OpenClaw:

1. Desplegar OpenClaw en una Instancia WEC con Docker Compose
2. Asegurar OpenClaw con un proxy inverso Caddy + HTTPS
3. Añadir un canal de Telegram a OpenClaw
4. Haz OpenClaw privado con una VPN mesh de NetBird ← estás aquí

Ahora tienes un agente autoalojado que está cifrado en tránsito, emparejado con tus dispositivos, accesible desde tu móvil e invisible para la internet pública — todo en una sola Instancia WEC pequeña.

Continúa el viaje​

¿Listo para un agente que recuerda? Empieza la serie Self-hosting Hermes — Autoaloja el Hermes Agent con memoria persistente — desplegado en esta misma Instancia WEC, con contexto que sobrevive a los reinicios.

Ya desplegaste OpenClaw y lo aseguraste detrás de HTTPS. Ahora hazlo usable — habla con tu agente desde el móvil vía Telegram. Creamos un bot, lo conectamos, superamos la barrera de emparejamiento de OpenClaw y obtenemos una respuesta real. Cada comando y tropiezo de abajo proviene de un despliegue real.

Lo que vas a construir​

Tu móvil habla con un bot de Telegram; el gateway de OpenClaw consulta a Telegram en busca de mensajes, los procesa con tu modelo y responde — sin necesidad de puertos entrantes.

Requisitos previos​

• Parte 1 + Parte 2 completas — OpenClaw en marcha en ~/openclaw
• Una cuenta de Telegram y un cliente de Telegram con sesión iniciada — la app del móvil/escritorio, o web.telegram.org. (No puedes crear un bot desde la página web pública de t.me; mira la Solución de problemas.)

Paso 1 — Crear un bot de Telegram​

En la app de Telegram, toca buscar y escribe BotFather, luego abre la cuenta oficial — la que tiene el tilde azul.

Toca Start — BotFather responde con los comandos que entiende (verás opciones como /newbot, /mybots, /token y más). Envía /newbot y luego sigue sus dos indicaciones:

1. Name — un nombre para mostrar, p. ej. My OpenClaw Agent
2. Username — debe ser único y terminar en bot, p. ej. wiline_openclaw_bot

BotFather confirma con "Done! Congratulations on your new bot" y te da el token — la línea después de Use this token to access the HTTP API:, como 1234567890:AA....

Paso 2 — Conectar el bot a OpenClaw​

En la VM, dentro de ~/openclaw, registra el canal con tu token:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<your-bot-token>"
# Added Telegram account "default".

Paso 3 — Activar y verificar​

Reinicia el gateway para que tome el canal, luego comprueba el estado:

docker compose restart openclaw-gateway
docker compose run --rm openclaw-cli channels status
# - Telegram default: enabled, configured, running, mode:polling, token:config

mode:polling significa que el gateway está consultando activamente a Telegram — sin puerto entrante ni webhook.

Paso 4 — Enviar un mensaje al bot (barrera de emparejamiento)​

Abre tu bot (t.me/<your-bot-username>), toca Start y envía un mensaje.

OpenClaw trata a los remitentes desconocidos como no confiables — así que en lugar de responder, el bot devuelve un código de emparejamiento y tu id de usuario de Telegram. Es el mismo patrón de seguridad que el emparejamiento de dispositivos de la Parte 2.

Paso 5 — Aprobar el emparejamiento​

En la VM, aprueba el código del mensaje del bot:

docker compose run --rm openclaw-cli pairing approve telegram <pairing-code>
# Approved telegram sender <id>.
# Command owner configured telegram:<id> (commands.ownerAllowFrom was empty).

Paso 6 — Chatear con tu agente​

De vuelta en Telegram, simplemente háblale — no hace falta más configuración; OpenClaw con tu modelo responde de forma conversacional desde el primer momento. Prueba con algo como:

In one sentence, what's the point of putting a reverse proxy in front of my agent?

Responde con una respuesta real — toda la cadena está activa: tu móvil → Telegram → gateway → OpenAI → respuesta. Tu agente autoalojado ya cabe en tu bolsillo. (Darle herramientas y skills llega en guías posteriores; el chat conversacional funciona de inmediato.)

Solución de problemas (errores reales)​

1. El botón "Start" de BotFather no hace nada en un navegador​

Abrir t.me/BotFather en un navegador web normal muestra un botón Start que no hace nada — esa página es solo la tarjeta pública del bot y necesita un cliente de Telegram con sesión iniciada al que delegar. Usa la app de escritorio/móvil, o inicia sesión en web.telegram.org (vincula un dispositivo de escritorio escaneando el QR desde tu móvil: Settings → Devices → Link Desktop Device), y luego escríbele a BotFather ahí.

2. El bot devuelve un código de emparejamiento en lugar de responder​

No es un error — es la barrera de emparejamiento. Los remitentes desconocidos deben aprobarse primero (Paso 5). Tras la aprobación, el bot chatea con normalidad.

3. Proxy headers detected from untrusted address​

Si seguiste la Parte 2, el gateway registra esto porque Caddy está por delante de él. Es una advertencia, no un fallo. Para silenciarla y restaurar la detección correcta del cliente, establece gateway.trustedProxies con la red de tu proxy.

Notas de seguridad y dimensionamiento​

• El emparejamiento es la barrera — solo los usuarios de Telegram aprobados llegan al agente; el primer usuario aprobado se convierte en command owner.
• Polling, no webhooks — no se abre ningún puerto entrante, lo que mantiene intacto el endurecimiento de la Parte 2.
• Dimensionamiento — en una máquina de 2 vCPU el gateway registró event loop degraded bajo carga. Para un bot con mucho tráfico, dale más CPU/RAM.

Qué sigue​

Terminaste la Parte 3 de la serie Self-hosting OpenClaw. Sigue:

• Parte 4 — Haz OpenClaw privado con una VPN mesh NetBird (siguiente) — pon tu agente en una mesh privada y cierra los puertos públicos.

Después empieza la serie Self-hosting Hermes — Autoaloja el Hermes Agent con memoria persistente — para un agente cuyo contexto sobrevive a los reinicios.

Los archivos complementarios de la serie viven en el repo de manifiestos de WiLine (enlace pendiente con el repo).

Desmontaje​

Elimina el canal de Telegram (mantiene en marcha el resto de OpenClaw):

docker compose run --rm openclaw-cli channels remove --channel telegram
docker compose restart openclaw-gateway

Y haz /revoke del token del bot en BotFather si ya terminaste con él.

En el Artículo 1 pusimos OpenClaw en marcha — pero solo sobre HTTP plano, con el truco de allowInsecureAuth. Aquí ponemos Caddy por delante como reverse proxy: HTTPS de verdad, auth con emparejamiento de dispositivos y los puertos crudos del gateway cerrados para que el proxy sea la única vía de entrada. Cada comando y error que aparece abajo es del despliegue real.

Lo que vas a construir​

Caddy termina el HTTPS y hace de reverse proxy hacia el gateway de OpenClaw por la red interna de Docker. El gateway deja de publicar sus propios puertos — el único punto de entrada pasa a ser Caddy en :443.

Requisitos previos​

• Artículo 1 completado — OpenClaw corriendo en ~/openclaw
• Acceso por shell a la VM
• Un hostname para el gateway. Con un dominio público, úsalo (y obtén certificados reales de Let's Encrypt). En una máquina privada, usamos openclaw.local + una entrada en el archivo hosts.

Paso 1 — Confirmar el punto de partida​

cd ~/openclaw
docker compose ps

Deberías ver openclaw-gateway Up (healthy), publicando 18789/18790/3978. Ese es nuestro estado de partida: funcionando, pero solo HTTP.

Paso 2 — Escribir el Caddyfile​

La config de Caddy: servir HTTPS y hacer proxy de todo hacia el gateway. tls internal usa la propia CA local de Caddy — no hace falta dominio público.

cat > Caddyfile <<'EOF'
# Caddy selects its certificate by SNI (the hostname in the TLS handshake).
# A bare IP sends no SNI, so we use a hostname. With a public domain, put your
# domain here and drop `tls internal` for automatic Let's Encrypt.
openclaw.local {
    tls internal
    reverse_proxy openclaw-gateway:18789
}
EOF

El destino del proxy es openclaw-gateway:18789 — Caddy alcanza el gateway por su nombre de servicio de Compose a través de la red compartida de Docker.

Paso 3 — Añadir Caddy a Compose​

docker compose fusiona automáticamente un docker-compose.override.yml, así que añadimos un servicio caddy sin tocar el archivo 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 + los certificados entre reinicios.

Paso 4 — Iniciar Caddy​

docker compose up -d
docker compose ps

Caddy arranca junto al gateway con 443 publicado, y genera su CA interna + un certificado en la primera ejecución.

Paso 5 — Verificar HTTPS​

Consulta el endpoint de salud del gateway a través de Caddy. --resolve hace que curl envíe el hostname (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"}

Paso 6 — Volver a asegurar el gateway​

Ahora el tráfico llega por https://openclaw.local. Dos cambios de config:

1. Añade el origen HTTPS a allowedOrigins (la Control UI rechaza orígenes desconocidos).
2. Vuelve a desactivar allowInsecureAuth — HTTPS es un contexto seguro, así que el truco del Artículo 1 ya no hace falta.

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

Paso 7 — Emparejar tu navegador​

Abre https://openclaw.local/ en tu navegador (en una máquina privada, primero mapea 10.80.4.212 openclaw.local en el archivo hosts de tu máquina — /etc/hosts en macOS/Linux, o C:\Windows\System32\drivers\etc\hosts editado como Administrador en Windows).

Primero te toparás con una advertencia de certificado — "Tu conexión no es privada" (NET::ERR_CERT_AUTHORITY_INVALID). Esto es esperado con tls internal: el certificado está firmado por la CA local de Caddy, en la que tu sistema operativo no confía. Haz clic en Avanzado → Continuar a openclaw.local (no seguro) para seguir. (Con un dominio real + Let's Encrypt, el certificado tiene confianza pública y esta advertencia nunca aparece — mira Pasar a producción.)

Ahora la página carga — pero con allowInsecureAuth desactivado, el gateway exige emparejamiento de dispositivo antes de que este navegador pueda usar la Control UI. 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>

De vuelta en el navegador, haz clic en Connect otra vez — empareja y carga el dashboard.

Paso 8 — Cerrar el acceso directo (el endurecimiento de verdad)​

El gateway todavía publica 18789 en el host, así que http://<vm-ip>:18789 sigue siendo alcanzable en HTTP plano, saltándose a Caddy. Ciérralo: deja de publicar los puertos del gateway para que Caddy en :443 sea la única puerta. Caddy sigue alcanzándolo por la red interna.

cat > docker-compose.override.yml <<'EOF'
services:
  openclaw-gateway:
    # Unpublish the gateway's host ports — Caddy reaches it internally, so the
    # only entry point is HTTPS on :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 publicaba el compose base.

Paso 9 — Comprobar que está cerrado​

curl -s -m 5 http://<vm-ip>:18789/healthz ; echo " <- direct HTTP (should FAIL)"
curl -sk --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz ; echo " <- via Caddy (should work)"

El primero no devuelve nada (conexión rechazada) — la puerta insegura desapareció. El segundo todavía devuelve {"ok":true,"status":"live"}.

Tu OpenClaw ahora es alcanzable solo por HTTPS, con dispositivo emparejado.

Solución de problemas (errores reales)​

1. tlsv1 alert internal error​

Aparece cuando la dirección del sitio en el Caddyfile era una IP pelada (https://10.80.4.212):

curl: (35) error:0A000438:SSL routines::tlsv1 alert internal error

Los logs de Caddy mostraban que el certificado se obtuvo bien. Causa: TLS elige un certificado por SNI (el hostname en el handshake), pero las conexiones a una IP pelada no envían SNI — así que Caddy no puede emparejar un certificado y aborta. Solución: usa un hostname como dirección del sitio (Paso 2). Un lector con un dominio real nunca se topa con esto — el dominio es el SNI.

2. Emparejamiento de dispositivo requerido​

En la primera conexión HTTPS tras desactivar allowInsecureAuth:

Device pairing required — This browser needs one-time approval from the Gateway
host before it can use the Control UI.

Causa: este es el flujo seguro correcto — con la auth insegura desactivada, cada navegador nuevo debe ser aprobado. Solución: docker compose run --rm openclaw-cli devices approve <request-id>. (La CLI puede registrar scope upgrade pending approval … using local fallback pero igual completa la aprobación.)

3. NET::ERR_CERT_AUTHORITY_INVALID​

Esperado con tls internal — el certificado está firmado por la CA local de Caddy, en la que tu SO no confía. Haz clic para continuar en una máquina privada. Con un dominio público + Let's Encrypt (abajo), el certificado tiene confianza y no hay advertencia.

Pasar a producción​

Con un dominio real, cambia dos líneas en el Caddyfile — apúntalo a tu dominio y quita tls internal:

- openclaw.local {
-     tls internal
+ openclaw.example.com {
      reverse_proxy openclaw-gateway:18789
  }

Luego apunta el registro A del DNS del dominio a la IP pública de la VM y abre 80 + 443 a internet. Caddy aprovisiona y renueva automáticamente un certificado de Let's Encrypt — con confianza, sin advertencia, sin --resolve ni /etc/hosts. Actualiza allowedOrigins a https://openclaw.example.com.

Notas de seguridad​

• Punto de entrada único — solo el :443 de Caddy queda expuesto; el gateway no tiene puertos en el host (Paso 8).
• Emparejamiento de dispositivo — cada navegador necesita aprobación de una sola vez (openclaw devices).
• Lista de orígenes permitidos — la Control UI solo acepta https://openclaw.local.
• Rota los secretos — regenera OPENCLAW_GATEWAY_TOKEN si alguna vez se mostró (capturas de pantalla, pantallas compartidas).

Qué sigue​

Terminaste la Parte 2 de la serie Self-hosting OpenClaw. Sigue:

• Parte 3 — Añade un canal de Telegram (siguiente) — habla con tu agente, ya asegurado, desde el móvil.
• Parte 4 — Haz OpenClaw privado con una VPN mesh NetBird — ponlo en una mesh privada y cierra los puertos públicos.

Los archivos complementarios (Caddyfile, docker-compose.override.yml) viven en el repo de manifiestos de WiLine (enlace pendiente con el repo).

Desmontaje​

Para eliminar solo Caddy y reabrir los puertos directos, borra docker-compose.override.yml y Caddyfile, luego docker compose up -d. Para detener todo:

docker compose down

Despliega un agente de IA autoalojado de OpenClaw en una Instancia WEC con Docker Compose — desde levantar la VM hasta un agente que de verdad responde, usando tu propia clave de API del modelo. Cada comando, versión y error que aparece abajo fue capturado de un despliegue real en un Instancia WEC.

Lo que vas a construir​

Un único contenedor gateway de OpenClaw, configurado con tu proveedor de modelo, accesible a través de su Control UI web y de la CLI.

Requisitos previos​

• Una cuenta de WiLine Edge Cloud
• Una clave de API de un modelo — esta guía usa OpenAI; Anthropic y los modelos locales también funcionan
• Un par de claves SSH en tu máquina (~/.ssh/id_ed25519 o similar)
• Unos 20 minutos

Paso 1 — Aprovisionar la VM en WiLine​

Levanta una VM de WiLine que cumpla estos requisitos:

El recorrido por el portal ya está documentado — sigue estos pasos y vuelve:

• Desplegar una máquina virtual →
• Configurar una clave SSH →

Cuando esté en marcha, conéctate por SSH:

ssh ubuntu@<ip-de-tu-vm>

Paso 2 — Verificar la máquina​

Antes de instalar nada, confirma con qué estás trabajando — la versión del SO y los recursos disponibles. Anota estos números; son útiles cuando luego compares rendimiento o abras un ticket de soporte.

lsb_release -a
nproc
free -h
df -h /

En nuestra Instancia WEC: Ubuntu 22.04.5 LTS, 8 vCPU, ~15 GiB de RAM, 25 GB de disco libre.

Paso 3 — Instalar Docker + Compose​

Comprueba si Docker ya está presente:

docker --version
docker compose version

Si no está instalado, sigue la guía oficial de Docker para tu distribución — Instalar Docker Engine en Ubuntu. La vía más rápida es el script de conveniencia de Docker, seguido de añadir tu usuario al grupo docker para poder ejecutarlo sin sudo:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Necesitas Docker Compose v2 (el subcomando docker compose, no el antiguo binario docker-compose).

Paso 4 — Obtener el archivo Compose​

Crea un directorio para el 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 del agente de larga duración) y openclaw-cli (una CLI de un solo uso que comparte la red del gateway). Por defecto compila desde el código fuente; en su lugar lo apuntaremos a la imagen precompilada.

Paso 5 — Configurar .env​

Crea un .env junto al archivo compose. Fija la imagen precompilada y establece un token para el panel:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<pega la salida de: openssl rand -hex 32>

Descarga la imagen:

docker compose pull

Paso 6 — Crear de antemano el directorio de configuración​

OpenClaw monta ~/.openclaw dentro del contenedor mediante bind-mount. Créalo primero con tu propio usuario — de lo contrario Docker lo crea como root y el contenedor (que se ejecuta como el usuario node, uid 1000) no puede escribir en él:

mkdir -p ~/.openclaw ~/.openclaw-auth-profile-secrets

Si te lo saltas, te toparás con un error de permisos en la primera ejecución — mira la Solución de problemas.

Paso 7 — Onboarding​

Aquí es donde aportas tu propio modelo — el onboarding te pide tu proveedor y tu clave de API. Esta guía usa OpenAI, pero Anthropic y los modelos locales funcionan igual.

Ejecuta el onboarding de OpenClaw a través del contenedor gateway. Es interactivo — te pregunta tu proveedor y clave de API y escribe la configuración:

docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

Avanza por las preguntas:

• Continuar tras el aviso de seguridad de uso personal → Yes
• Setup mode → QuickStart
• Provider → OpenAI (o tu proveedor), luego pega tu clave de API
• Default model → mantén el sugerido (openai/gpt-5.5)
• Channel → busca skip → Skip for now (los canales de mensajería son una guía posterior)
• Skills / Hooks → No / Skip for now (configúralos luego con openclaw configure)
• Hatch your agent → Hatch later (a continuación iniciamos el gateway como servicio)

Termina con Onboarding complete.

Paso 8 — Aplicar la configuración del gateway e iniciarlo​

El onboarding escribió tu proveedor y modelo. Ahora establece las opciones de ejecución del gateway — modo de ejecución, bind de red y los orígenes que aceptará la Control UI — y luego inícialo como servicio en segundo plano.

docker 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

Paso 9 — Comprobación de funcionamiento​

Salud del contenedor:

docker compose ps

Quieres ver Up ... (healthy). Luego consulta el endpoint de salud:

curl http://127.0.0.1:18789/healthz
# {"ok":true,"status":"live"}

Confirma que tu clave del proveedor es utilizable:

docker compose run --rm openclaw-cli models status
# openai ... api_key=1 ... status=usable

Ahora la prueba real de extremo a extremo. El comando agent necesita un destino, así que primero lista los agentes y luego envía un mensaje al predeterminado (main):

docker compose run --rm openclaw-cli agents list
# - main (default)

docker compose run --rm openclaw-cli agent --agent main \
  --message "Reply with exactly one word: working"
# working

Si responde working, toda la cadena — gateway → OpenAI → respuesta — está activa.

La Control UI está en http://<ip-de-tu-instancia>:18789/; pega tu OPENCLAW_GATEWAY_TOKEN en Ajustes para iniciar sesión.

Solución de problemas (errores reales)​

Estos son errores que realmente encontramos durante este despliegue — no son hipotéticos.

1. EACCES: permission denied, mkdir '/home/node/.openclaw/state'​

Apareció en la primera ejecución del onboarding cuando ~/.openclaw no existía de antemano:

[openclaw] The CLI command failed.
[openclaw] Reason: Failed to open the plugin state database.
| EACCES: permission denied, mkdir '/home/node/.openclaw/state' | EACCES

Causa: Docker creó automáticamente el origen del bind-mount ~/.openclaw con propietario root (0:0). El contenedor se ejecuta como el usuario node (uid 1000), por lo que no puede escribir dentro de ese directorio propiedad de root.

Solución: asigna el directorio al uid 1000 (que también es tu usuario ubuntu):

sudo chown -R 1000:1000 ~/.openclaw

Crear el directorio tú mismo de antemano (Paso 6) evita esto por completo.

2. No target session selected​

La primera vez que ejecutamos agent sin especificar con quién hablar:

Error: No target session selected. Use --agent <id>, --session-key <key>,
--session-id <id>, or --to <E.164>. Run openclaw agents list to see agents.

Causa: openclaw agent ejecuta un turno contra un agente/sesión específico; sin ningún canal configurado no hay un destino implícito.

Solución: lista los agentes y pasa el id explícitamente:

docker compose run --rm openclaw-cli agents list          # muestra: main (default)
docker compose run --rm openclaw-cli agent --agent main --message "..."

3. Control UI: "Secure browser context required"​

Al abrir la Control UI desde otra máquina (p. ej. macOS) en la IP de la instancia sobre HTTP plano, la página se niega a conectar:

Secure browser context required
This page is running over plain HTTP, so the browser cannot create the
device identity the Gateway expects.

Causa: los navegadores solo exponen las APIs de cifrado que OpenClaw necesita en un contexto seguro — HTTPS, o localhost/127.0.0.1. Un http://<ip>:18789 remoto no es ninguno, así que el navegador lo bloquea, independientemente del flag del servidor gateway.controlUi.allowInsecureAuth.

Solución: tuneliza el puerto por 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@<ip-de-tu-vm>

Luego abre http://127.0.0.1:18789/#token=<tu-token> localmente. La solución definitiva a largo plazo es HTTPS mediante un proxy inverso — la próxima guía.

Notas de seguridad​

Al arrancar, el gateway registró advertencias que conviene atender antes de cualquier exposición pública:

• Bind a una dirección no-loopback — el gateway escucha en la LAN. No expongas el puerto 18789 a la Internet pública sin autenticación por delante.
• gateway.controlUi.allowInsecureAuth=true — marcado como peligroso. Ejecuta docker compose run --rm openclaw-cli security audit.
• plugins.allow está vacío — pueden autocargarse plugins no incluidos (p. ej. codex). Define una lista 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.

Lo que has logrado​

Pasaste de una Instancia WEC a un agente de IA autoalojado y funcional:

• Aprovisionaste y verificaste una VM Ubuntu en WEC
• Levantaste el gateway de OpenClaw con Docker Compose y la imagen precompilada oficial
• Conectaste tu propio proveedor de modelo (OpenAI) y lo confirmaste de extremo a extremo — el agente respondió por la CLI y por la Control UI
• Te topaste con (y resolviste) los problemas reales de permisos, sesión y contexto seguro por el camino

El agente es tuyo: tu clave, tu máquina, tus datos. A partir de aquí se trata de hacerlo seguro, accesible y útil.

¿Qué puedes hacer con ello?​

OpenClaw no es un chatbot — es un agente autónomo que puede actuar en tu máquina. Ahora que está en marcha, esto es lo que desbloquea (algunas funciones necesitan configuración adicional, y cubrimos las principales más adelante en esta serie):

• Ejecuta trabajo real en la máquina. Puede ejecutar comandos de shell y leer/escribir archivos — "revisa qué está ocupando el disco," "muestra los logs y resume los errores" — con sandboxing configurable para cuánto le permites tocar.
• Háblale desde tu teléfono. OpenClaw se conecta a WhatsApp, Telegram, Discord, Slack, Signal e iMessage, así que delegas tareas conversando, sin SSH. (Conectamos Telegram en la siguiente guía.)
• Navega y actúa en la web. La automatización de navegador integrada le permite navegar sitios, rellenar formularios y extraer datos de forma autónoma.
• Escribe y ejecuta código. Se integra con Claude Code para programación autónoma — escribir y modificar código, ejecutar pruebas e incluso abrir PRs.
• Trabaja en segundo plano, de forma proactiva. Funciona 24/7, puede ejecutar tareas en segundo plano y hace "latidos" (heartbeat) en vez de solo reaccionar cuando le escribes.
• Crece contigo. Una biblioteca comunitaria de habilidades (ClawHub), herramientas autogeneradas y orquestación multiagente lo hacen más capaz con el tiempo — respaldado por memoria persistente que mantiene el contexto entre conversaciones.

Usos reales típicos: gestión de correo y calendario, procesamiento de documentos, tareas de infraestructura en la máquina, pipelines de contenido y pruebas de código autónomas.

Qué sigue​

Esta es la Parte 1 de la serie Self-hosting OpenClaw sobre ejecutar infraestructura de IA de nivel producción en una Instancia WEC. Próximamente:

• Parte 2 — Asegura OpenClaw con un proxy inverso Caddy + HTTPS (siguiente) — pon HTTPS por delante del gateway para eliminar el truco de allowInsecureAuth y acceder a la Control UI desde cualquier lugar, de forma segura.
• Parte 3 — Añade un canal de Telegram — habla con tu agente desde el móvil.
• Parte 4 — Haz OpenClaw privado con una VPN mesh NetBird — ponlo en una mesh privada y cierra los puertos públicos.

Los archivos complementarios de esta guía — docker-compose.yml y .env.example — viven en el repo de manifiestos de WiLine (enlace pendiente con el repo).

Desmontaje​

docker compose down              # detiene y elimina los contenedores
docker compose down --rmi all -v # también elimina la imagen y los volúmenes

Para eliminar la configuración/estado del host: rm -rf ~/.openclaw ~/.openclaw-auth-profile-secrets. Para detener la facturación por completo, elimina la VM desde el portal de WiLine.