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

# Troubleshooting

> Fix common MineClawd setup and runtime problems quickly.

If MineClawd fails, find the closest symptom below and apply that fix first.

<AccordionGroup>
  <Accordion title="MineClawd says only OP users can run this command">
    Give your player OP level 2 permissions. Every `/mineclawd` and `/mclawd` command requires OP access.
  </Accordion>

  <Accordion title="MineClawd says API key or model is missing">
    Open config and set provider credentials.

    OpenAI path:

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

    Vertex path:

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

  <Accordion title="`/mineclawd config` does not open GUI">
    Your client likely does not have MineClawd installed. Use command configuration:

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

  <Accordion title="`/mineclawd history` says client mod is required">
    Install MineClawd on your client. The history book UI uses a client packet channel.
  </Accordion>

  <Accordion title="Another request is still running for this session">
    Wait for current task completion before starting a new one, switching sessions, or switching persona.
  </Accordion>

  <Accordion title="Retry token is invalid or expired">
    Retry tokens expire after 30 minutes.

    Trigger a new request or use the latest retry action from a fresh failure message.
  </Accordion>

  <Accordion title="Session not found for resume, remove, or repair">
    Run `/mineclawd sessions list` first.

    Then use exact session id or token from that output.
  </Accordion>

  <Accordion title="Persona not found">
    Check available names with `/mineclawd persona`.

    If needed, create a new soul file under `mineclawd/souls/`.
  </Accordion>

  <Accordion title="Dynamic placeholder registry is disabled">
    Set mode and restart:

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

    On dedicated servers, clients must also install MineClawd when this is enabled.
  </Accordion>

  <Accordion title="`reload-game` reports KubeJS errors">
    Read the reported lines, fix script syntax or runtime issues in `kubejs/server_scripts/mineclawd/`, then reload again.

    Keep fixing until reload output reports no KubeJS errors.
  </Accordion>

  <Accordion title="`/mineclawd choose` says no pending question">
    MineClawd is not waiting for an answer.

    Run `choose` only after MineClawd asks a clarification question.
  </Accordion>

  <Accordion title="There's only one option in LLM provider selection/Broadcast Requests To">
    It's a weird bug of YACL. Click on the value and enter the first (two) letter(s) of the option you want, then select it from the dropdown that appears.

    For LLM provider: type `o` for OpenAI or `g` for Google Vertex AI.
    For Broadcast Requests To: type `on` for only-me, `a` for all, or `op` for ops.
  </Accordion>

  <Accordion title="The overlay orb does not appear">
    The AssistiveTouch orb requires:

    * MineClawd installed on the client.
    * OP permission level 2.
    * **Enable GUI** set to ON in config (**Mod Menu** -> **MineClawd** -> **Configure**).
    * AssistiveTouch not toggled off (`/mineclawd assistivetouch` to re-enable).

    Check each of these. If the orb still does not appear, enable debug mode and check logs.
  </Accordion>

  <Accordion title="Typing in the overlay leaks into chat or inventory">
    Make sure you are running the latest version of MineClawd.

    If the issue persists, it may be a mod conflict. Test with only MineClawd and its dependencies installed.
  </Accordion>

  <Accordion title="Web search says search tool is disabled">
    The `search` tool requires a Tavily API key. Set one with:

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

    Get a key from [tavily.com](https://tavily.com/). Once configured, MineClawd uses web search automatically when it needs external information.
  </Accordion>

  <Accordion title="Stop button or /mineclawd stop does not cancel the request">
    Stop sends a cancellation signal to the active request. If the LLM provider has already finished processing but the response is still being delivered, stop may not take effect immediately.

    If the session remains locked after stopping, try creating a new session with `/mineclawd sessions new`.
  </Accordion>

  <Accordion title="Asset teleport says the entity cannot be found">
    The entity may have been killed, despawned, or unloaded. Asset records store the last known location at creation time and do not track entity movement.

    Teleport works only for entity-category assets with a stored UUID and dimension.
  </Accordion>
</AccordionGroup>

## If problems continue

* Enable debug logs: `/mineclawd config debug-mode true`
* Reproduce once
* Check `logs/latest.log`
* File an issue: `https://github.com/Zhou-Shilin/MineClawd/issues`