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

# Solución de problemas

> Corrige rápido problemas comunes de setup y runtime de MineClawd.

Si MineClawd falla, busca el síntoma más cercano abajo y aplica primero esa solución.

<AccordionGroup>
  <Accordion title="MineClawd dice que solo usuarios OP pueden ejecutar este comando">
    Dale a tu jugador permisos OP nivel 2. Todos los comandos `/mineclawd` y `/mclawd` requieren acceso OP.
  </Accordion>

  <Accordion title="MineClawd dice que falta API key o modelo">
    Abre configuración y define credenciales del proveedor.

    Ruta OpenAI:

    * `provider openai`
    * `api-key <key>`
    * `model <model>`

    Ruta Vertex:

    * `provider vertex-ai`
    * `vertex-api-key <key>`
    * `vertex-model <model>`
  </Accordion>

  <Accordion title="`/mineclawd config` no abre la GUI">
    Es probable que tu cliente no tenga MineClawd instalado. Usa configuración por comando:

    ```bash theme={null}
    /mineclawd config <key> <value>
    ```
  </Accordion>

  <Accordion title="`/mineclawd history` dice que se requiere mod de cliente">
    Instala MineClawd en tu cliente. La UI del libro de historial usa un canal de paquetes de cliente.
  </Accordion>

  <Accordion title="Otra solicitud sigue en ejecución para esta Session">
    Espera a que termine la tarea actual antes de iniciar una nueva, cambiar de Session o cambiar de persona.
  </Accordion>

  <Accordion title="El token de reintento no es válido o expiró">
    Los tokens de reintento expiran tras 30 minutos.

    Lanza una solicitud nueva o usa la acción de reintento más reciente de un mensaje de error fresco.
  </Accordion>

  <Accordion title="Session no encontrada para resume, remove o repair">
    Ejecuta primero `/mineclawd sessions list`.

    Después usa el id de Session exacto o el token de esa salida.
  </Accordion>

  <Accordion title="Persona no encontrada">
    Revisa los nombres disponibles con `/mineclawd persona`.

    Si hace falta, crea un archivo soul nuevo en `mineclawd/souls/`.
  </Accordion>

  <Accordion title="El registro de placeholders dinámicos está deshabilitado">
    Define el modo y reinicia:

    ```bash theme={null}
    /mineclawd config dynamic-registry-mode enabled
    ```

    En servidores dedicados, los clientes también deben instalar MineClawd cuando esto esté habilitado.
  </Accordion>

  <Accordion title="`reload-game` reporta errores de KubeJS">
    Lee las líneas reportadas, corrige errores de sintaxis o runtime en `kubejs/server_scripts/mineclawd/` y luego recarga.

    Sigue corrigiendo hasta que la salida de recarga no reporte errores de KubeJS.
  </Accordion>

  <Accordion title="`/mineclawd choose` dice que no hay pregunta pendiente">
    MineClawd no está esperando una respuesta.

    Ejecuta `choose` solo después de que MineClawd haga una pregunta de aclaración.
  </Accordion>

  <Accordion title="Solo hay una opción en la selección de proveedor LLM/Broadcast Requests To">
    Es un bug raro de YACL. Haz clic en el valor e introduce la primera (o primeras dos) letra(s) de la opción, luego selecciónala del desplegable que aparece.

    Para proveedor LLM: escribe `o` para OpenAI o `g` para Google Vertex AI.
    Para Broadcast Requests To: escribe `on` para only-me, `a` para all o `op` para ops.
  </Accordion>

  <Accordion title="El orbe de superposición no aparece">
    El orbe Assistive Touch requiere:

    * MineClawd instalado en el cliente.
    * Permiso OP nivel 2.
    * `Enable GUI` en ON en configuración (**Mod Menu** -> **MineClawd** -> **Configure**).
    * Assistive Touch no desactivado (`/mineclawd assistivetouch` para volver a activarlo).

    Revisa cada punto. Si el orbe todavía no aparece, habilita modo debug y revisa logs.
  </Accordion>

  <Accordion title="Escribir en la superposición se filtra al chat o al inventario">
    Asegúrate de estar en la versión más reciente de MineClawd.

    Si el problema continúa, puede ser un conflicto entre mods. Prueba con solo MineClawd y sus dependencias instaladas.
  </Accordion>

  <Accordion title="Búsqueda web dice que la herramienta search está deshabilitada">
    La herramienta `search` requiere una Tavily API key. Configúrala con:

    ```bash theme={null}
    /mineclawd config tavily-api-key <your-tavily-key>
    ```

    Obtén una clave en [tavily.com](https://tavily.com/). Cuando se configura, MineClawd usa búsqueda web automáticamente cuando necesita información externa.
  </Accordion>

  <Accordion title="El botón Stop o /mineclawd stop no cancela la solicitud">
    Stop envía una señal de cancelación a la solicitud activa. Si el proveedor LLM ya terminó de procesar pero la respuesta todavía se está entregando, stop puede no surtir efecto de inmediato.

    Si la Session sigue bloqueada después de detener, intenta crear una Session nueva con `/mineclawd sessions new`.
  </Accordion>

  <Accordion title="Asset teleport dice que no se puede encontrar la entidad">
    Puede que la entidad haya muerto, desaparecido o quedado descargada. Los registros de assets guardan la última ubicación conocida al crearse y no siguen el movimiento de la entidad.

    Teleport solo funciona para assets de categoría entidad con UUID y dimensión almacenados.
  </Accordion>
</AccordionGroup>

## Si los problemas continúan

* Habilita logs de debug: `/mineclawd config debug-mode true`
* Reproduce el problema una vez
* Revisa `logs/latest.log`
* Abre un issue: `https://github.com/Zhou-Shilin/MineClawd/issues`