Configuración¶
El archivo de configuración describe todo el bot: la
conexión con Telegram, quién puede usarlo, el menú de
botones y el registro. Se pasa con --config a run,
validate, fmt y list-functions (consulte CLI).
Todas las claves usan lower_snake_case. Las claves desconocidas se
rechazan, por lo que verá inmediatamente cualquier error al
validar.
Obligatorio significa que la validación falla si el campo falta o queda
vacío tras aplicar los valores predeterminados.
Los campos opcionales se pueden omitir; la columna Predeterminado indica el
valor usado.
Si es nuevo, empiece con Ejecutar en la CLI, que explica cómo crear una primera configuración. Consulte Conceptos para conocer el vocabulario.
Una configuración mínima¶
Solo son obligatorios telegram, con un token y un
usuario permitido, y menu. Todo lo demás tiene
un valor predeterminado:
Empezar con un usuario permitido y tres botones de estado
telegram:
bot_token: "YOUR_BOT_TOKEN"
allowed_users:
- "123456789"
menu:
- name: System Status
type: category
icon: "🖥️"
items:
- name: Uptime
type: button
icon: "🕒"
function: command
command: "uptime"
- name: Memory
type: button
icon: "🧮"
function: command
command: "free -h"
- name: Disk Space
type: button
icon: "💾"
function: command
command: "df -h /"
La carpeta config-examples/ de la versión contiene un ejemplo mínimo y otro completo.
Campos raíz¶
| Campo | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
telegram |
objeto | sí | — | Ajustes de Telegram (véase más abajo) |
menu |
lista | sí | — | Árbol del menú; al menos un nodo |
function_directory |
cadena | no | sin definir | Directorio YAML de funciones personalizadas (consulte las reglas más abajo) |
shell |
cadena | no | /bin/bash |
Shell usado como shell -c "<command>" |
timeout |
duración | no | 60s |
Tiempo máximo predeterminado de un comando |
max_output_bytes |
entero | no | 524288 |
Salida máxima guardada por comando (consulte Cuánta salida de comando verá y Controlar la salida) |
output |
auto | text | file |
no | auto |
Cómo se entrega el resultado del comando (consulte Cuánta salida de comando verá y Controlar la salida) |
max_output_messages |
entero | no | 2 |
Solo en la raíz. En modo auto, enviar un archivo .txt cuando el resultado necesitaría más de este número de mensajes (1–10). Omítalo para conservar 2. Consulte Controlar la salida |
workdir |
cadena | no | directorio de trabajo del proceso | Directorio de trabajo predeterminado para los comandos |
env |
mapa | no | vacío | Variables de entorno adicionales para los comandos |
menu_columns |
entero | no | 2 |
Botones de elementos por fila bajo el cuadro de mensajes |
page_size |
entero | no | 8 |
Elementos por página antes de paginar |
confirm_ttl |
duración | no | 5m |
Vigencia de una confirmación |
delivery_retry_backoff |
duración | no | 1s |
Solo raíz. Espera inicial antes del primer reintento tras un envío fallido. Vea Reintentos de entrega |
delivery_retry_backoff_max |
duración | no | 30s |
Solo raíz. Espera máxima entre reintentos. Vea Reintentos de entrega |
delivery_retry_ttl |
duración | no | 2m |
Solo raíz. Tiempo total que el bot sigue intentando antes de rendirse (solo se registra en el servidor). Vea Reintentos de entrega |
enable_run_command |
booleano | no | false |
Muestra un botón $ >_ Run Command que ejecuta el siguiente mensaje como comando de shell. Está desactivado de forma predeterminada. Cualquier persona que pueda usar el bot podrá ejecutar cualquier comando en el host, así que actívelo solo si confía en todos los usuarios permitidos. Esta clave no es válida bajo telegram. |
logging |
objeto | no | registrador integrado predeterminado | Registradores con nombre (consulte más abajo) |
¿Qué ocurre si omite shell?
Puede omitirlo. El bot usa /bin/bash. Lo mismo ocurre con timeout,
page_size y los demás campos raíz opcionales: si los omite, se aplican sus
valores predeterminados. Solo debe definirlos cuando quiera usar un valor
distinto, por ejemplo shell: /bin/sh.
Cuánta salida de comando verá¶
Se aplican dos límites consecutivos. max_output_bytes es su límite, además
del límite de Telegram que no puede cambiar.
1. Su límite: max_output_bytes (predeterminado 524288, es decir, 512 KB)
Mientras corre un comando, el bot guarda como máximo esta cantidad de salida,
contada por separado para la salida normal y la de error. Lo que pase de ahí se
descarta, pero el comando sigue hasta terminar o alcanzar su timeout. El
resultado empieza entonces con (output truncated).
2. Cómo se entrega el resultado: output (predeterminado auto)
Telegram admite como máximo 4096 bytes por mensaje. El bot puede partir un
resultado largo en varios mensajes de respuesta o enviar la salida completa
como archivo .txt. Elija el modo con output en la raíz o anúlelo en un
botón concreto:
| Valor | Comportamiento |
|---|---|
auto |
Usa mensajes de texto mientras el resultado quepa en max_output_messages mensajes (predeterminado 2). Si necesitara más, envía un archivo .txt. |
text |
Siempre parte en mensajes de texto. Sigue parando a los 10 mensajes y indica el recorte. |
file |
Siempre envía un archivo .txt con un pie breve (nombre del botón, código de salida, duración). |
En los modos auto y file, el archivo incluye el encabezado más stdout y
stderr, así que subir max_output_bytes sí entrega más salida. Si falla el
envío del archivo, el bot reintenta automáticamente y solo vuelve a la vía de
mensajes de texto después de rendirse. Vea Reintentos de entrega.
No hace falta escribir output ni max_output_messages. Si los omite, el bot
usa auto y 2. Un archivo que ya funciona no cambia.
max_output_messages existe solo en la raíz. En un botón, omita output para
usar el valor de la raíz; póngalo solo cuando ese botón deba enviar siempre un
archivo o quedarse siempre en texto.
Para registros largos, use output: auto (predeterminado) o output: file en
ese botón. Aun así puede acortar el propio comando si solo necesita un fragmento.
Más sobre esto: Controlar la salida
Hay una página entera dedicada a estos tres campos. Recorre una por una todas las combinaciones de raíz y botón, y muestra una imagen del chat de Telegram para cada caso.
Reglas de function_directory¶
| Situación | Resultado |
|---|---|
| Falta la clave | Registro informativo; solo funciones integradas |
La clave está presente pero vacía ("") |
Registro informativo; solo funciones integradas |
| La ruta no existe o no es accesible | Error grave; el proceso se detiene |
| La ruta existe pero el directorio está vacío | Correcto |
Una ruta incorrecta detiene el bot
Si function_directory apunta a una carpeta inexistente o ilegible, el
programa se detiene en vez de iniciarse sin sus funciones personalizadas.
telegram¶
| Campo | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
bot_token |
cadena | sí | — | Token del bot proporcionado por BotFather |
allowed_users |
lista de cadenas | sí | — | Usuarios permitidos |
api |
cadena | no | https://api.telegram.org |
URL base de la API del bot |
proxy.enabled |
booleano | no | false |
Usar un proxy para la API de Telegram |
proxy.url |
cadena | condicional | — | Obligatorio si proxy.enabled es true |
insecure |
booleano | no | false |
Omitir la verificación TLS (no recomendado) |
Los usuarios no autorizados reciben su user_id y username para solicitar
acceso. Así puede encontrar su propio id la primera vez; consulte
Ejecutar en la CLI → Paso 5.
Conectarse mediante un proxy
Para permitir comandos escritos en Telegram, añada este ajuste a la raíz
del archivo, no bajo telegram:
Menú¶
Esta sección es la referencia de campos. Para una explicación guiada, consulte Menú. Cada botón o categoría acepta:
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name |
cadena | sí | Nombre visible, único entre hermanos sin distinguir mayúsculas |
type |
category | button |
sí | Tipo de nodo |
items |
lista | si es category |
Hijos; al menos uno |
function |
cadena | si es button |
Nombre de la función |
command |
cadena | si function: command |
Comando de shell integrado |
path |
cadena | si function: script |
Ruta del script |
icon |
cadena | no | Emoji opcional |
id |
cadena | no | Identificador opcional para este nodo; puede omitirlo |
confirm |
booleano | no | Pedir confirmación, false de forma predeterminada |
timeout |
duración | no | Sustituir el tiempo máximo global |
workdir |
cadena | no | Sustituir el directorio de trabajo |
env |
mapa | no | Variables de entorno adicionales para este botón |
columns |
entero | no | Sustituir las columnas de la categoría |
output |
auto | text | file |
no | Opcional. Omítalo para usar el output de la raíz. Póngalo solo para forzar este botón a file o text (consulte Cuánta salida de comando verá y Controlar la salida) |
args |
cadena | no | Argumentos opcionales de script |
| Cualquier parámetro declarado | escalar | según la función | Valor pasado, como url, host, unit o lines |
En un botón, cualquier otra clave escalar se trata como un parámetro de
función. Su nombre debe estar declarado por la función seleccionada.
validate rechaza los nombres desconocidos y también
comprueba los valores declarados como int o bool. Las cadenas, los números
y los booleanos se pueden escribir directamente como valores YAML; los números
no necesitan comillas.
En una categoría, cualquier clave fuera de los campos anteriores es un error. Las categorías no ejecutan funciones, por lo que no pueden tener claves de parámetros.
command, path y args completan parámetros del mismo nombre. Escriba los
demás parámetros directamente en el botón, sin un mapa
params:. Consulte
Funciones → Pasar valores desde un botón.
logging¶
Es opcional. Si se omite, se usa un registrador de consola en stderr con nivel info.
Registradores con nombre:
Escribir registros normales y un archivo de auditoría
Salidas admitidas: stdout, stderr, file, discard.
El registrador audit guarda cada comando: quién lo ejecutó, qué botón, el
código de salida y la duración. Consulte
Registro de auditoría.
Páginas relacionadas¶
- Ejecutar en la CLI — cree y ejecute una primera configuración
- Menú — el árbol del menú en detalle
- Reintentos de entrega — reintento automático tras una breve caída de red
- Controlar la salida — mensajes o un archivo
.txt, con todas las combinaciones de raíz y botón - Funciones — significado de
function,command,pathyargs - CLI — valide y ejecute su configuración