トラブルシューティング
よくつまずくところと、その対処。
問題を自動診断#
Agentty は一般的な問題を自動で見つけて、修正することができます。ヘルプ → 問題を自動診断を開くか、設定 → 環境チェックで診断を開始を押してください。
診断チェックは以下を調査します:
- Claude Code や Codex がインストール済みなのに新しいターミナルから見つからない場合 — Agentty がフォルダをシェルの起動ファイルに追加できます
- 同じ CLI の複数コピーが PATH の順序を妨げている場合 — Agentty が最新版を起動し、古いコピーについて警告します
- 異常終了後に Claude Code のフルスクリーンモードが残っている場合 — Agentty が記録をクリアして、他のターミナルが影響されないようにします
- Claude Code の
settings.json、~/.claude.json、Codexconfig.tomlにシンタックスエラーがある場合 — Agentty が最後に正常だったバージョンを復元できます - シェル起動ファイルに設定された環境変数が干渉している場合 — Agentty がコメント化できます
- Agentty のターミナル統合ファイルが不足または古い場合 — Agentty が再書き込みできます
Agentty が修正できる各問題には自動修正ボタンがあります。すべて修正で一度にすべての修正を適用してください。ファイルを変更する前に、Agentty は <filename>.agentty-<timestamp> という名前でバックアップを作成します。シェル起動ファイルへの変更は、新しく開いたターミナルから適用されます。
また: 別の Claude またはエージェントプロセスがすでにフォルダで作業中で、どこで起動するか尋ねられた場合、30 秒以内に選択しなければ、現在のフォルダで自動的に起動するようになりました。
エージェントが一覧に出ない、起動しない#
Agentty はログインシェルの PATH で見つかるエージェント CLI だけを提示します。ターミナルでは動くのにここでは動かない場合、PATH が対話シェルしか読まないファイル(.zshrc、.bashrc)に設定されている可能性が高いです。ログインシェルが読む場所へ移すか、不足分を挙げて導入までしてくれる設定 → システムチェックを確認してください。
ペインの状態が空のまま#
状態は、ペインの起動時に Agentty がエージェントへ渡すフックから来ます。
- Windows では Claude Code がフックを Git Bash で実行します。Git for Windows を導入してください。
- すでに開いたシェルの中で自分でエージェントを起動した場合、フックがありません。+ メニューから開いてください。
エージェントが別のファイルを編集した#
1 つのフォルダで 2 つのセッションは衝突します。設定 → 一般 → セッションごとのワークツリーを有効にすると、2 つ目のセッションが自分の git ワークツリーとブランチを持ちます。ファイルパネルですべてのワークツリーと、そこでの変更を確認できます。
タブを閉じたのに開発サーバーが動き続ける#
設定 → 一般 → 閉じるときサーバーを停止が、ペインの起動したサーバーを一緒に終了します。モニタリング →プロセスで、まだ動いているものを確認できます。
使用量の数値がおかしい#
ディスク上の会話ファイルから計算した値で、内蔵されている価格は Claude のモデルだけです。他のモデルは ~/.agentty/pricing.json に価格を追加してください(設定リファレンス参照)。この数値は目安で、基準はプロバイダーの請求書です。
プラグインが出てこない、止まる#
- JavaScript のプラグインにはログインシェルの
PATHに Node.js 18 以降が必要です。 - フォルダ名は
agentty-plugin.jsonのidと一致している必要があります。コピーした後は再読み込みを押してください。 - プラグインカードのログに、クラッシュを含む実際の出力があります。コードを直したら再起動を押してください。
詳しくはプラグインを使うにあります。
agentty:// リンクが効かない#
リンクは導入済みのアプリケーションで動作し、開発用に起動したビルドでは動きません。リンクが指すプラグインが導入され有効になっているか確認してください。
更新できない#
更新は GitHub からダウンロードし、使用前に検証します。プロキシやブロックされたホストのせいで失敗する場合は、リリースページから手で入手してください。
それでも解決しないとき#
イシュートラッカーに知らせてください。Agentty のバージョン(設定 → Agentty について)、OS、期待していた動作を添えていただけると助かります。ログや画面を貼る前に、資格情報は伏せてください。
セキュリティの問題は、公開の issue ではなく非公開で報告してください。