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

# 故障排查

> 快速修复常见 MineClawd 安装和运行问题。

如果 MineClawd 失败，请先在下方找到最接近的症状，并优先应用对应修复。

<AccordionGroup>
  <Accordion title="MineClawd 提示只有 OP 用户可以运行此命令">
    给你的玩家授予 OP 等级 2。所有 `/mineclawd` 和 `/mclawd` 命令都要求 OP 权限。
  </Accordion>

  <Accordion title="MineClawd 提示缺少 API key 或 model">
    打开配置并设置 provider 凭据。

    OpenAI 路径：

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

    Vertex 路径：

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

  <Accordion title="`/mineclawd config` 无法打开 GUI">
    你的客户端很可能没有安装 MineClawd。请改用命令配置：

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

  <Accordion title="`/mineclawd history` 提示需要客户端模组">
    在客户端安装 MineClawd。历史书 UI 使用客户端数据包通道。
  </Accordion>

  <Accordion title="这个 Session 仍有请求在运行">
    先等待当前任务完成，再开始新请求、切换 Session，或切换 persona。
  </Accordion>

  <Accordion title="重试 token 无效或已过期">
    重试 token 在 30 分钟后过期。

    请重新触发一次请求，或使用最新失败消息里的最新重试操作。
  </Accordion>

  <Accordion title="恢复、删除或修复时提示找不到 Session">
    先运行 `/mineclawd sessions list`。

    然后使用输出里的精确 Session id 或 token。
  </Accordion>

  <Accordion title="找不到 persona">
    用 `/mineclawd persona` 检查可用名称。

    如有需要，在 `mineclawd/souls/` 下创建新的 persona 文件。
  </Accordion>

  <Accordion title="动态占位符注册表被禁用">
    设置模式并重启：

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

    在专用服务器上启用后，客户端也必须安装 MineClawd。
  </Accordion>

  <Accordion title="`reload-game` 报告 KubeJS 错误">
    阅读报错行，修复 `kubejs/server_scripts/mineclawd/` 中的脚本语法或运行时问题，然后再次重载。

    持续修复，直到重载输出不再出现 KubeJS 错误。
  </Accordion>

  <Accordion title="`/mineclawd choose` 提示没有待回答问题">
    MineClawd 当前没有在等待答案。

    仅在 MineClawd 发起澄清提问后再运行 `choose`。
  </Accordion>

  <Accordion title="LLM provider 选择或 Broadcast Requests To 里只有一个选项">
    这是 YACL 的异常行为。点击该值，输入你想要选项的首字母（或前两个字母），然后在弹出的下拉里选择。

    对 LLM provider：输入 `o` 选 OpenAI，输入 `g` 选 Google Vertex AI。
    对 Broadcast Requests To：输入 `on` 选 only-me，输入 `a` 选 all，输入 `op` 选 ops。
  </Accordion>

  <Accordion title="覆盖层球体不显示">
    Assistive Touch 球体要求：

    * 客户端已安装 MineClawd。
    * OP 权限等级为 2。
    * 配置中 **Enable GUI** 为 ON（**Mod Menu** -> **MineClawd** -> **Configure**）。
    * Assistive Touch 未被关闭（可用 `/mineclawd assistivetouch` 重新启用）。

    逐项检查以上条件。如果球体仍不显示，请启用调试模式并查看日志。
  </Accordion>

  <Accordion title="在覆盖层输入时内容泄漏到聊天或背包">
    请确认你运行的是 MineClawd 最新版本。

    若问题仍存在，可能是模组冲突。请只安装 MineClawd 和它的依赖做一次最小化测试。
  </Accordion>

  <Accordion title="网页搜索提示 search 工具已禁用">
    `search` 工具需要 Tavily API key。你可以用下面命令设置：

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

    在 [tavily.com](https://tavily.com/) 获取 key。配置完成后，MineClawd 会在需要外部信息时自动使用网页搜索。
  </Accordion>

  <Accordion title="Stop 按钮或 /mineclawd stop 无法取消请求">
    Stop 会向当前活动请求发送取消信号。如果 LLM provider 已处理完成但响应仍在传输，Stop 可能不会立刻生效。

    如果停止后 Session 仍被锁定，尝试运行 `/mineclawd sessions new` 创建新的 Session。
  </Accordion>

  <Accordion title="资产传送提示找不到实体">
    实体可能已被击杀、消失或未加载。资产记录保存的是创建时最后一次已知位置，不会追踪实体移动。

    传送仅对保存了有效 UUID 和维度的实体类资产有效。
  </Accordion>
</AccordionGroup>

## 如果问题仍存在

* 开启调试日志：`/mineclawd config debug-mode true`
* 复现一次问题
* 检查 `logs/latest.log`
* 提交 issue：`https://github.com/Zhou-Shilin/MineClawd/issues`