> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesslabs.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración de moderación

> Prepara moderación, roles de mute y mensajes de acción con los permisos reales de Headless.

## Flujo recomendado

Buenas prácticas: revisa al miembro con `.userinfo @Member`, aplica una acción con una razón clara y verifica el registro con `.case <ID>` o `.cases`. Las sanciones y los cambios individuales de roles crean casos y eventos de log.

> [!TIP]
>
> Usa motivos breves, conserva la evidencia necesaria y comprueba que la jerarquía
> permite actuar sobre el objetivo. No eleves el rol del bot para resolver un
> permiso aislado.

**Nota:**

Fake Permissions puede satisfacer algunas comprobaciones del moderador, pero
nunca concede permisos nativos a Headless ni sustituye en silencio sus
permisos de Discord. El permiso del bot y la jerarquía de roles sigue aplicando.

## Roles staff compartidos con Strip Staff

`.bind staff @rol` alterna un rol normal del servidor en la lista compartida por Strip Staff y Staff Roles del Dashboard. `.bind staff list` consulta los roles configurados. El comando requiere ser owner del servidor o Anti-Nuke Admin autorizado; Headless debe estar por encima del rol. No se pueden añadir `@everyone` ni roles administrados, y la lista acepta hasta 120 roles. El cambio se guarda por servidor y se registra en el log de seguridad. Esta lista no concede acceso Anti-Nuke Admin, no agrega roles a la whitelist y no evita otras protecciones.

```headless-command Syntax theme={null}
.bind staff [role]
```

```headless-command Example theme={null}
.bind staff @Moderadores
```

```headless-command Syntax theme={null}
.bind staff list
```

```headless-command Example theme={null}
.bind staff list
```

![Respuesta de Headless que confirma que un rol quedó configurado como rol staff; las menciones del servidor se ocultaron.](https://mintcdn.com/headless-labs/ZF85v3KoGVX7saRn/images/headless-replies/moderation-bind-staff-redacted.png?fit=max\&auto=format\&n=ZF85v3KoGVX7saRn\&q=85\&s=d26849efb51443f179922a2cbce0a273)

Confirmación real de Headless al añadir un rol staff; se ocultaron las menciones del miembro y del rol.

## Sanciones de miembros

Ban, kick y timeout tienen comandos de prefijo y slash. La razón es opcional y, si se omite, Headless registra `No reason provided`. El objetivo no puede ser el owner del servidor ni el propio bot; debe estar por debajo del moderador y de Headless. El owner puede superar solo la comparación de jerarquía del moderador. Timeout admite `30m`, `2h` o `1d`, hasta 28 días.

En comandos slash, selecciona el miembro y la razón opcional en el selector de opciones de Discord; no escribas esos campos como texto después del nombre.

> [!WARNING]
>
> Headless necesita `Ban Members`, `Kick Members` o `Moderate Members`, según
> la acción. Los permisos predeterminados de un comando slash no sustituyen los
> permisos reales del bot.

### Ban

```headless-command Syntax theme={null}
.ban <user_query> [reason=No reason provided]
```

```headless-command Example theme={null}
.ban @Member spam repetido
```

```headless-command Syntax theme={null}
/ban member:<member> [reason:<reason>]
```

```headless-command Example theme={null}
/ban
```

### Kick

```headless-command Syntax theme={null}
.kick <user_query> [reason=No reason provided]
```

```headless-command Example theme={null}
.kick @Member conducta disruptiva
```

```headless-command Syntax theme={null}
/kick member:<member> [reason:<reason>]
```

```headless-command Example theme={null}
/kick
```

### Timeout

```headless-command Syntax theme={null}
.timeout <user_query> <duration> [reason=No reason provided]
```

```headless-command Example theme={null}
.timeout @Member 30m flood repetido
```

```headless-command Syntax theme={null}
/timeout member:<member> duration:<duration> [reason:<reason>]
```

```headless-command Example theme={null}
/timeout
```

## Configuración inicial

**1. Comprueba permisos y jerarquía**

Para `.setup` necesitas ser owner o tener `Manage Server` / `Administrator`; Headless necesita `Manage Roles` y `Manage Channels`, o `Administrator`. La jerarquía sigue aplicando.

**2. Prepara Jail y los registros**

Ejecuta `.setup` y revisa los resultados `Created`, `Existing` y `Failed` antes de usar Jail.

**3. Configura los roles de mute**

Ejecuta `.setupmute`; revisa los canales con errores y corrige permisos o jerarquía antes de repetirlo.

**4. Personaliza los mensajes si hace falta**

`.invoke` permite ajustar confirmaciones y DMs por acción; no es necesario para activar las sanciones.

> [!NOTE]
>
> `.setupmute` también requiere owner, `Manage Server` o `Administrator` para
> quien lo ejecuta. Headless necesita `Manage Roles` o `Administrator`, y su rol
> debe quedar por encima de cada rol de mute.

> **Qué crea `.setup`**
>
> Usa el canal de logs configurado si existe y Headless puede verlo, enviar
> mensajes y publicar embeds. Si no se puede resolver, reutiliza `#jail-log` o
> crea un canal privado. Si el canal configurado existe pero faltan permisos,
> informa el error y no lo sustituye en silencio. También crea o reutiliza el rol
> `Jailed` y el canal privado `Jail`; al completar, activa Jail y guarda la
> configuración por servidor. Un fallo parcial no significa que los cambios previos se hayan revertido automáticamente.

> **Roles y resultado de `.setupmute`**
>
> Crea o reutiliza `Muted` (mensajes e hilos: impide escribir y crear hilos públicos o privados), `Image Muted` (impide adjuntar archivos) y `Reaction Muted` (impide añadir reacciones). Aplica overwrites a categorías y canales
> compatibles; los canales con permisos sincronizados usan el overwrite de su
> categoría. No acepta `@everyone`, roles gestionados, roles con
> `Administrator` ni roles al nivel o por encima del bot. La respuesta separa
> roles creados, reutilizados y canales fallidos; los IDs quedan guardados por
> servidor.

## Casos, registros y límites

> **Casos, logs y límites**
>
> Los rechazos de los comandos de prefijo por permisos o acceso se envían al
> registro de denegaciones cuando hay un destino disponible. Otros errores de
> Discord y los comandos slash pueden usar otra respuesta o ruta de log. La
> autoeliminación de mensajes de comando depende de configuración de runtime;
> no se encontró un control publicado en Dashboard. Los cooldowns se definen
> por comando y tampoco tienen un control de Dashboard verificado.

> **Personalizar respuestas con `.invoke`**
>
> Acepta `jail`, `kick`, `ban`, `hardban`, `timeout` y `warn`. `message`
> personaliza la respuesta del comando; `dm` personaliza el mensaje privado al
> objetivo. Cada combinación se guarda por separado; `.invoke list` muestra
> cuáles difieren del valor predeterminado y `.invoke <acción> reset` borra
> solo esa acción.
> Los templates se validan antes de guardarse. Requiere owner, `Administrator`
> o `Manage Server`. `tempban` y `softban` no están implementados.

## Apodos forzados

`.forcenickname <usuario> <apodo>` guarda una regla por servidor y la reaplica cuando Discord notifica un cambio de apodo. El primer apodo previo se conserva para poder restaurarlo.

```headless-command Syntax theme={null}
.forcenickname <user_query> [nickname]
```

```headless-command Example theme={null}
.forcenickname @Member Equipo-Azul
```

```headless-command Syntax theme={null}
.unforcenickname <user_query>
```

```headless-command Example theme={null}
.unforcenickname @Member
```

```headless-command Syntax theme={null}
/forcenickname member:<member> [nickname:<nickname>]
```

```headless-command Example theme={null}
/forcenickname
```

> [!WARNING]
>
> Quitar la regla restaura el apodo guardado, no necesariamente el nombre
> visible más reciente. Headless no puede aplicarla si pierde `Manage
>     Nicknames` o queda por debajo del miembro.

> **Aliases, permisos y límites del apodo**
>
> La regla se reaplica best-effort cuando Discord notifica un cambio de apodo.
> Los aliases de prefijo incluyen `.fnick`, `.fn`, `.forcenick`,
> `.forzarnombre`, `.forcenames` y `.locknick`. `.unforcenickname <usuario>` o
> `.forcenickname <usuario> off` quitan la regla; sin apodo, el comando de
> prefijo también se interpreta como retirada. `/fnick` acepta el apodo
> opcional. `.forcednames` y `/forcednames` muestran hasta 25 reglas; el slash
> responde de forma privada. Quien ejecuta y Headless necesitan `Manage Nicknames`; el apodo admite hasta 32 caracteres y no puede dirigirse al owner
> ni al bot. La regla y el apodo original se guardan por servidor.

## Gestión manual de roles

`.role @usuario @rol` alterna un rol. Los cambios individuales validan el miembro y el rol, y crean un caso y un log cuando se aplican.

`.role add` acepta varios roles separados por coma, punto y coma, `|` o `+`; el texto final `--reason <texto>` registra el motivo. `--reason` forma parte del contenido interpretado por ese subcomando, no de los argumentos del framework de comandos.

#### `.role`

```headless-command Syntax theme={null}
.role [rest]
```

```headless-command Example theme={null}
.role @Member @Helper
```

```headless-command Syntax theme={null}
/role user:<user> role:<role> [reason:<reason>]
```

```headless-command Example theme={null}
/role
```

#### `.role add`

```headless-command Syntax theme={null}
.role add <rest>
```

```headless-command Example theme={null}
.role add @Member Helper, Trial --reason Acceso aprobado
```

#### `.roleall`

```headless-command Syntax theme={null}
.roleall [role_query]
```

```headless-command Example theme={null}
.roleall @Verified
```

**Nota:**

Cambiar roles requiere `Manage Roles` del moderador (nativo o mediante Fake
Permissions compatible) y `Manage Roles` nativo de Headless. La jerarquía de
roles sigue aplicando; no se pueden cambiar `@everyone` ni roles administrados. Los
roles con `Administrator` requieren `Administrator` nativo, el owner del
servidor o el owner de Headless.

> [!CAUTION]
>
> `.rolesadmin delete` elimina el rol del servidor y puede quitárselo a todos
> sus miembros; ese callback no pide confirmación ni crea caso/log. Verifica el
> rol antes de ejecutarlo.

**Advertencia adicional:**

`.roleall` modifica a muchos miembros sin confirmación y solo recorre los
miembros disponibles en la caché. Omite bots, miembros que ya tienen el rol,
el owner y objetivos fuera de la jerarquía; informa agregados, omisiones y
fallos. El comando de prefijo tiene un cooldown de 30 segundos por servidor;
`/roleall` no registra ese cooldown.

> **Variantes de `.rolesadmin`**
>
> El grupo ofrece `add`, `remove`, `toggle`, `list` y `delete`; `.ra` / `.roleadd`
> añaden roles y `.roleremove` / `.removerol` los retiran. Consulta [Roles](/docs/server/roles.md)
> para restauración y paneles de selección por miembros.

## Acciones masivas y hardban

> **Limpiar timeouts**
>
> `.cleartimeouts [razón]` y `/cleartimeouts reason:...` limpian los timeouts activos y procesan en lotes los miembros disponibles en la caché. Tanto el
> moderador como Headless necesitan
> `Moderate Members`. Omite objetivos fuera de la jerarquía, registra un
> resumen y puede completar parcialmente; no revierte las acciones ya
> aplicadas.

> **Unban y hardban**
>
> `.unban <ID> [razón]` y `/unban user_id:<ID> reason:...` requieren un ID
> numérico y `Ban Members` de quien ejecuta y de Headless. No se puede usar el
> unban normal para un miembro en la lista persistente de hardban. `.hardban`
> requiere `Ban Members` y acceso Anti-Nuke Admin; presenta controles de
> aprobar/rechazar y valida la jerarquía. Al confirmar, elimina hasta siete
> días de mensajes y vuelve a aplicar el ban si alguien desbanea al usuario
> mientras el registro siga activo. Usa `.hardban remove <ID>` para retirar
> el registro y desbanear; si Discord devuelve un error de permisos o HTTP,
> Headless conserva el registro. `.unban` no es un sustituto. Para una retirada normal:
> `.unban 123456789012345678 motivo`.

### Recrear un canal con `.nuke`

> [!WARNING]
>
> `.nuke` clona el canal de texto actual y, tras confirmar, elimina el original.
> El historial de mensajes no se copia y la acción no se puede deshacer. Por
> Headless publica el mensaje literal `first` en el canal nuevo al completar
> el reemplazo.

Quien ejecuta necesita `Manage Channels` y acceso Anti-Nuke Admin (el owner
también cumple ese control). Headless necesita `Manage Channels`, `View
Channel` y `Send Messages`; el comando de prefijo además comprueba que Headless
tenga `Manage Messages`. El canal se clona con su configuración y posición. Si
un paso de Discord falla después de eliminar el original, el canal nuevo puede
quedar creado aunque la acción no termine con una confirmación normal.

**1. Abre el comando en el canal objetivo**

Ejecuta `.nuke` dentro del canal de texto que quieras recrear. También existe `/nuke`.

**2. Revisa la confirmación**

Verifica el canal y la pérdida irreversible del historial antes de elegir **Approve**.

**3. Comprueba el reemplazo**

Headless conserva la configuración del canal, registra un caso y un log; no restaura los mensajes anteriores.

```headless-command Syntax theme={null}
.nuke [reason]
```

```headless-command Example theme={null}
.nuke replace a compromised channel
```

## Casos y verificación

`.cases @Member` permite revisar los casos del miembro; `.case <ID>` muestra un caso individual. Para seguimiento operativo, confirma primero qué permisos nativos tienen el moderador y Headless, y revisa el registro después de una acción.

> [!NOTE]
>
> El prefijo de texto público es `.`. El [catálogo Commands](https://headlesslabs.xyz/commands/) mantiene la sintaxis y los aliases registrados; las 45 entradas de Moderation se contrastaron con el registro y los callbacks actuales.

## Páginas relacionadas

* [Permisos de Headless](/docs/permissions.md)
* [Anti-Nuke](/docs/security/anti-nuke.md)
* [Advertencias](/docs/security/warnings.md)
* [Jail](/docs/security/jail.md)
* [Casos](/docs/moderation/cases.md)
* [Canales y lockdown](/docs/server/channels.md)
* [Variables de mensajes](/docs/resources/scripting/variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.