> ## 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 キーまたはモデルが未設定と言われる">
    設定を開いてプロバイダー認証情報を入力してください。

    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` で GUI が開かない">
    クライアントに MineClawd が入っていない可能性があります。コマンドで設定してください。

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

  <Accordion title="`/mineclawd history` で client mod が必要と言われる">
    クライアントに MineClawd をインストールしてください。history book UI はクライアント packet channel を使います。
  </Accordion>

  <Accordion title="この Session では別のリクエストがまだ実行中と言われる">
    現在の処理完了まで待ってから、新しいリクエスト開始、Session 切替、persona 切替を行ってください。
  </Accordion>

  <Accordion title="retry token が無効または期限切れ">
    retry token の有効期限は 30 分です。

    新しいリクエストを実行するか、直近の失敗メッセージから最新の retry アクションを使ってください。
  </Accordion>

  <Accordion title="resume、remove、repair 用の Session が見つからない">
    まず `/mineclawd sessions list` を実行してください。

    その出力にある正確な Session ID または token を使ってください。
  </Accordion>

  <Accordion title="persona が見つからない">
    `/mineclawd persona` で利用可能名を確認してください。

    必要なら `mineclawd/souls/` 配下に新しい soul ファイルを作成してください。
  </Accordion>

  <Accordion title="動的プレースホルダー registry が無効と言われる">
    mode を設定して再起動してください。

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

    専用サーバーでこれを有効化する場合、クライアント側にも MineClawd の導入が必要です。
  </Accordion>

  <Accordion title="`reload-game` で KubeJS エラーが出る">
    報告された行を読み、`kubejs/server_scripts/mineclawd/` のスクリプト構文または実行時エラーを修正して再読み込みしてください。

    `reload-game` の出力に KubeJS エラーが出なくなるまで修正を続けてください。
  </Accordion>

  <Accordion title="`/mineclawd choose` で pending question がないと言われる">
    MineClawd は現在回答待ちではありません。

    `choose` は MineClawd が確認質問を出した後にのみ実行してください。
  </Accordion>

  <Accordion title="LLM provider selection または Broadcast Requests To で選択肢が 1 つしか出ない">
    これは YACL の不具合です。値をクリックして、欲しい選択肢の先頭 1〜2 文字を入力し、表示されたドロップダウンから選択してください。

    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="オーバーレイのオーブが表示されない">
    Assistive Touch オーブの表示には次が必要です。

    * クライアントに MineClawd がインストールされている。
    * OP 権限レベル 2 がある。
    * 設定（**Mod Menu** -> **MineClawd** -> **Configure**）で **Enable GUI** が ON。
    * Assistive Touch がオフに切り替えられていない（`/mineclawd assistivetouch` で再有効化）。

    これらを順に確認してください。表示されない場合は debug mode を有効化してログを確認してください。
  </Accordion>

  <Accordion title="オーバーレイ入力がチャットやインベントリに漏れる">
    MineClawd を最新バージョンに更新してください。

    問題が続く場合は Mod 競合の可能性があります。MineClawd と依存 Mod だけの構成で再現確認してください。
  </Accordion>

  <Accordion title="Web 検索で search tool が無効と言われる">
    `search` ツールには Tavily API キーが必要です。次で設定してください。

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

    キーは [tavily.com](https://tavily.com/) で取得できます。設定後は、外部情報が必要な場面で MineClawd が自動で Web 検索を使います。
  </Accordion>

  <Accordion title="Stop ボタンまたは /mineclawd stop でリクエストが止まらない">
    stop はアクティブリクエストへキャンセル信号を送ります。LLM プロバイダー側の処理が既に終了しており、配信だけ続いている場合は、停止がすぐ反映されないことがあります。

    停止後も Session がロックされたままなら、`/mineclawd sessions new` で新しい Session を作成してください。
  </Accordion>

  <Accordion title="asset teleport で entity が見つからないと言われる">
    エンティティが kill、despawn、または未ロードになっている可能性があります。asset レコードは作成時点の最終既知位置だけを保持し、移動追跡はしません。

    teleport は UUID とディメンションを保存した entity-category asset でのみ機能します。
  </Accordion>
</AccordionGroup>

## 問題が続く場合

* debug ログを有効化: `/mineclawd config debug-mode true`
* 1 回再現する
* `logs/latest.log` を確認する
* Issue を報告する: `https://github.com/Zhou-Shilin/MineClawd/issues`