トラブルシューティング
エージェントが Studio に接続できないとき、フォルダーの許可を待っているときの対処と、各拒否コードの意味
エージェントが接続できない
まず設定 → エージェント連携を確認します。アドレスの下には、エンドポイントの提供中は待ち受け中、オフのときは停止中、起動に失敗したときは 起動できませんでした: に続けて理由が表示されます。
| 症状 | 原因 | 対処 |
|---|---|---|
| エージェントに NarraLeaf のツールがない | Studio が起動していない、またはエージェントの接続を許可がオフ | Studio を開いてオンにし、エージェントを再起動するか接続し直す |
| 接続が拒否される | エージェントを設定した後にポートを変えた | アドレスのポートとエージェントの設定を見比べ、設定をコピーし直してエージェントを再起動する |
| アドレスに 起動できなかった：ポート … は他のプログラムが使用している または …はシステムによって予約されている と表示される | ほかのプログラムがそのポートを使っているか、Windows が Hyper-V、WSL、Docker 用に予約している。Studio は自分で別のポートに移らない | エンドポイントのポートに空いているポートを入力し、設定をコピーし直してエージェントを再起動する |
| トークンがない、または誤っているとエージェントが報告する | トークンを再生成した、または設定を手で入力した | 設定をコピーし直す |
| Web ページからのリクエストは受け付けないとエージェントが報告する | クライアントがブラウザのように Origin ヘッダーを送っている | コンピューター上でプログラムとして動くクライアントを使う |
| いつまでも接続できない、または HTTP 405 で失敗する | クライアントが古い HTTP+SSE トランスポートで設定されている | Streamable HTTP で設定する |
| Claude Code で、ツールが 1 つのフォルダーにしかない | --scope user を付けずにサーバーを追加した | そのフォルダーで claude mcp remove narraleaf -s local を実行し、設定をコピー → Claude Code のコマンドを実行する |
| エージェント連携がオフだと Claude Desktop が言う | stdio ブリッジは Studio に到達したが、エージェントの接続を許可がオフ | オンにする。ブリッジの再起動は不要 |
| Claude Desktop がしばらく待ってから、Studio が動いていない、または時間内に起動しなかったと報告する | Studio が 1 分以内に提供を始めなかった、またはブリッジに --user-data-dir が付いていて、Studio を起動せず接続だけを行った | Studio を開き、設定 → エージェント連携を確認してから接続し直す |
| エージェントが別のプロジェクトで作業している | 複数のプロジェクトを開いている | エージェントにプロジェクトフォルダーを指定させるか、ほかのプロジェクトを閉じる |
エージェントにプラグインのツールが見えない
プラグインのツールは、そのプラグインを読み込むプロジェクトが開いている間だけ存在します。agent_status は、開いている各プロジェクトが提供するプラグインのツールを示します。
| 原因 | 対処 |
|---|---|
| クライアントがプラグインの読み込み前にツールの一覧を取得し、古い一覧を使い続けている | エージェントにツールの一覧を取り直させるか、接続し直す。Studio の通知ストリームを開いたままのクライアントは一覧の変化を知らされ、それ以外は次に一覧を取得したときに変化が反映される |
| プラグインを使うプロジェクトが開いていない | そのプロジェクトを開く。閉じたプロジェクトのプラグインのツールは提供されない |
| プロジェクトでプラグインが有効になっていない、または読み込みに失敗した | プロジェクトで有効にし、コンソールで読み込みのエラーを確認する |
| プラグインのツールがオフになっている | 設定 → エージェント連携 → プラグインのツールでオンにする。オフのツールの呼び出しは unavailable で拒否される |
| 複数のプロジェクトを開いていて、呼び出しがプラグインを読み込んでいないプロジェクトに届いた | 拒否は unknown_tool で、そのツールを提供するプロジェクトが示される。エージェントにそのどれかを指定させる |
フォルダーの確認
エージェントがプロジェクトと許可したフォルダーの外のファイルを必要とすると、Studio はエージェントにフォルダーの読み取りを許可する？で作者に尋ねます。そのフォルダーが許可されるまで、呼び出しは path_not_allowed で拒否され、エージェントログには許可されていないフォルダーと表示されます。その行の対処に、どの場合に当たるかが書かれています。プロジェクト外のフォルダーを参照してください。
| エージェントの報告 | 原因 | 対処 |
|---|---|---|
Waiting for the author: に続くフォルダー、または答え pending | 確認が開いていて、まだ答えていない。呼び出しは約 50 秒待ってから戻り、確認は開いたまま残る | 確認に答える。許可すれば、エージェントの次の試行は通る。確認が見当たらなければ、エージェントが作業しているプロジェクトのウィンドウを確認する。そのとき Studio の Dock アイコン（macOS）が弾むか、タスクバーのボタン（Windows、Linux）が点滅している。ほかの確認の後ろで待っているものは、前の確認に答えると開く |
| Declined by the author: に続くフォルダー | 拒否を選んだ、確認を閉じた、または Escape キーを押した。エージェントにはもう求めないよう伝えられている | やはり許可するなら、素材を読み込めるフォルダーのフォルダーを追加… でそのフォルダーを追加し、エージェントに再試行させる。拒否から 60 秒間は、同じフォルダーには確認を出さずに拒否済みと答えるので、すぐに再試行させても新しい確認は出ない |
| Not allowed: に続くフォルダーと理由があり、確認は出ない | そのフォルダーはドライブのルート、ホームフォルダー全体、ホームフォルダーを含むフォルダー、Studio 自身のフォルダーのいずれかで、決して開放されない | ファイルが実際にあるフォルダーをエージェントに指定させるか、ファイルをプロジェクトフォルダーにコピーする |
| 5 つを超えるフォルダーを求め、一部だけに答えが返る | 1 つの確認に示せるフォルダーは 5 つまで | 何もしなくてよい。エージェントが残りを改めて求める |
フルアクセスがオンの間は、Studio はどのフォルダーについても尋ねません。決して開放されないフォルダーは閉じたままです。
拒否コード
Studio が呼び出しを拒否すると、エージェントはコード、メッセージ、多くの場合は次の手順を受け取り、エージェントログの該当行にはそのコードの名前が表示されます。各コードへのエージェントの対応はガイドに書かれています。下の表は作者がすることです。
| コード | エージェントログの表示 | 意味 | 作者がすること |
|---|---|---|---|
writes_disabled | 変更は許可されていない | エージェントによる変更を許可とフルアクセスがどちらもオフ | 編集させるならエージェントによる変更を許可をオンにする。読み取りはそのままできる |
paused | 一時停止中 | このプロジェクトでエージェントを一時停止した | 続けてよいときにエージェントを再開を選ぶ |
frozen | プロジェクトは凍結中 | プロジェクトが変更を受け付けない状態。過去のバージョンの表示中、手動での凍結、未完了のマージ、リカバリーモード、別のウィンドウによる引き継ぎ | その状態を終えるか抜ける。エージェントは再試行する |
live_session | ライブセッション中 | プロジェクトで Team のライブセッションが行われている | セッションを抜けるか、終わるまでエージェントに読み取りだけで作業させる |
stale_revision | 読み取り後に変更あり | エージェントが読んだ後にページやシーンが変わった。たいていは作者が編集した | 何もしなくてよい。エージェントが読み直し、作者の版の上で変更をやり直す |
check_failed | チェック不合格 | エージェントが送ったテキストがコンパイルできない、またはチェックでエラーが見つかった。何も書き込まれていない | 繰り返さない限り何もしなくてよい。エージェントが指摘を直して書き直す |
not_found | 見つからない | 呼び出しが指すシーン、ページ、要素、アセット、キャラクターが存在しない | 繰り返さない限り何もしなくてよい。エージェントが存在するものを一覧して再試行する |
path_not_allowed | 許可されていないフォルダー | プロジェクトと許可したフォルダーの外のファイルの読み取りが許可されていない。確認への答えを待っている、作者が拒否した、または決して開放されないフォルダー | フォルダーの確認を参照する |
untrusted | 信頼されていないプロジェクト | プロジェクトが信頼されておらず、テストプレイ、テスト、ビルドができない | 入手元を信頼できるなら、ステータスバーの未信頼から信頼する |
no_workspace | 開いているプロジェクトがない | プロジェクトが開いていない、または複数開いていて呼び出しがどれかを指定していない | プロジェクトを開くか、エージェントにフォルダーを指定させる |
invalid_args | 引数が無効 | 引数がツールに合っていない | 何もしなくてよい。エージェントが呼び出しを直す |
unknown_tool | 不明なツール | その名前のツールがない | 何もしなくてよい。エージェントがツールの一覧を取り直す |
unavailable | 実行できない | 呼び出し自体は正しいが、今の状態では実行できない。たとえば動いていないゲームを進めようとした、まだ使われているページ、シーン、チャプター、アセットを削除しようとした、プロジェクトのウィンドウが時間内に応答しなかった、オフになっているプラグインのツールを呼び出した | エージェントログのメッセージを読む。足りないものが書かれている |
internal | 内部エラー | エージェントのせいではない、Studio 内部の失敗 | 繰り返すなら、コンソールでエラーを確認して報告する |
writes_disabled、paused、path_not_allowed のように、エージェントが自分では対処できないコードを受け取ると、エージェントは作業を止めて作者に尋ねます。