Pi Agent よくある問題のトラブルシューティング

以下は、Pi Agent の使用中によくある問題とその解決策です。

Pi Agent 启动异常排查决策树

インストール問題

このセクションでは、インストール段階で発生する典型的なエラーと対処手順を説明します。

npm install 失敗

現象: インストールコマンド実行中にエラーで途中終了する。よくあるエラーはバージョン、ネットワーク、権限の3種類に集中している。

考えられる原因調査方法解決策
Node.js のバージョンが低すぎる。Pi Agent は Node.js 22.19.0 以上を要求する。実行するnode --version現在のバージョンを確認するnvm で 22 LTS 以上のバージョンをインストールして切り替える
ネットワーク問題。国内から npm 公式レジストリにアクセスするとタイムアウトしやすい。エラーメッセージに ETIMEDOUT などのネットワークタイムアウト情報が含まれているか確認する実行するnpm config set registry https://registry.npmmirror.comミラーソースに切り替えて再インストールする
権限問題。macOS/Linux のグローバルインストールディレクトリが現在のユーザーで書き込み不可になっている。エラーメッセージに EACCES 権限エラーが含まれているか確認するnvm で Node.js を管理するか、npm のプレフィックスをユーザーディレクトリに設定して sudo の使用を避ける

インストール後に pi コマンドが見つからない

現象: インストールは成功と表示されるが、pi を入力すると command not found と表示される。

まず npm のグローバルインストールプレフィックスを確認する:

$ npm prefix -g
/usr/local

次に、そのプレフィックス配下の bin ディレクトリが PATH に含まれているか確認する:

$ echo $PATH | grep "$(npm prefix -g)/bin"
/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin

ディレクトリが PATH に含まれていない場合、このコマンドは何も出力しない:

$ echo $PATH | grep "$(npm prefix -g)/bin"

出力がない場合は、グローバルの bin ディレクトリが PATH に含まれていないことを意味し、それが pi コマンドが見つからない原因です。

考えられる原因調査方法解決策
グローバルの bin ディレクトリが PATH に追加されていない上記の grep コマンドで出力があるか確認するを$(npm prefix -g)/binの PATH に追加~/.zshrc 或 ~/.bashrcし、ターミナルを開き直すと有効になります
Node のバージョンを切り替えたため、古いシンボリックリンクが無効になっている実行するls $(npm prefix -g)/binpi がまだ存在するか確認する現在の Node バージョンでグローバルインストールを再度実行する

認証問題

このセクションでは、/login ログインと API Key 認証失敗の対処手順を説明します。

/login ログイン失敗

症状: /login を入力してもブラウザでリダイレクトが完了しない、またはインターフェースが認証待ちの状態のまま止まる。

考えられる原因調査方法解決策
サブスクリプションが有効な状態ではないプロバイダーの公式サイトにログインしてサブスクリプションが期限切れかどうか確認するサブスクリプションを更新するか、他のプロバイダーでログインする
プロバイダーの認証サーバーにアクセスできないブラウザでプロバイダーのサイトを開き、ネットワークに到達できるか確認するプロキシを設定して再試行する。設定方法は後述の「プロキシ設定」のセクションを参照
SSH リモート接続で /login を使用しているリモートマシンにブラウザがないため、OAuth コールバックが届かない認証 URL をコピーしてローカルのブラウザで開き、コールバック URL を手動で貼り付けてログインを完了する

API Key が有効にならない

現象: 環境変数を export したのに、起動時に未認証と表示されるか、古い認証情報が使われ続ける。

以下の順序で確認する:

考えられる原因調査方法解決策
環境変数が正しく設定されていない実行するecho $ANTHROPIC_API_KEY出力を確認する出力が空の場合は、シェル設定ファイルに export を追加し、再度 source する
auth.jsonに同名の認証情報がすでにあり、環境変数より優先される確認する~/.pi/agent/auth.jsonにそのプロバイダーのエントリがすでに存在するか実行する/logout古い認証情報を削除するか、auth.json を直接編集して Key を更新する
API Key の形式が正しくないコピーした内容に余分なスペースや引用符が混入していないか確認するKey を完全にコピーし直して再設定する

auth.jsonに保存されている認証情報は環境変数より優先されます。

API Key が有効にならない場合は、まず確認してください~/.pi/agent/auth.json環境変数だけに注目しないでください。

モデルが利用できない

現象: モデルリストに期待したモデルが見つからない、または呼び出し時に権限がないと表示される。

考えられる原因調査方法解決策
ローカルのモデルディレクトリが古い実行するpi update --modelsモデルディレクトリを更新する更新完了後、モデルセレクターを開き直す
現在利用可能なモデルが不明実行するpi --list-models利用可能なモデルのリストを確認するリストから現在のアカウントで利用可能なモデルを選択する
API Key に対応するモデルのアクセス権限がないプロバイダーのコンソールで、その Key のモデル認可範囲を確認するプランをアップグレードするか、認可済みのモデルに変更する
GitHub Copilot モデルに "not supported" と表示されるVS Code でそのモデルが有効化されているか確認するまず VS Code Copilot Chat でそのモデルを有効化してから、Pi Agent に戻って使用する

インターフェース問題

このセクションでは、ターミナル描画、画像表示、ショートカットキーの3種類のインターフェース異常を説明します。

インターフェース表示異常（色の異常、配置のずれ）

現象: 色が暗くなる、または歪んで見える。テーブルやテキストボックスの枠線がずれる。

考えられる原因調査方法解決策
ターミナルが True Color をサポートしていない実行するecho $COLORTERM、truecolor または 24bit と出力されればサポートしているTrue Color をサポートするターミナル（iTerm2、Windows Terminal など）に変更する
VS Code がターミナルのコントラストを自動調整している設定項目を確認するterminal.integrated.minimumContrastRatioその項目を 1 に設定する
現在のターミナルの描画互換性が低い別のターミナルで実行し、問題が再現するか確認するターミナルを変更する。iTerm2 または Windows Terminal を推奨

画像が表示されない

現象: 画像を送信または貼り付けても、ターミナルにはプレースホルダーか空白しか表示されない。

考えられる原因調査方法解決策
ターミナルが画像表示プロトコルをサポートしていないターミナルが iTerm2 の imgcat または Kitty の icat をサポートしているか確認する画像プロトコルをサポートするターミナルに変更する
画像表示が設定で無効になっている確認するterminal.showImagesが true かどうかtrue に変更した後、実行する/reload設定を有効にする

ショートカットキーが機能しない

現象: ドキュメントに記載されたショートカットキーを押しても反応がない、またはターミナル自身の機能が実行される。

考えられる原因調査方法解決策
ターミナルがそのショートカットキーを横取りしているターミナル設定のショートカットキーバインド一覧を確認するターミナル内で競合しているバインドを変更または解除する
現在のショートカットキーを覚え間違えている実行する/hotkeys現在のすべてのショートカットキーバインドを確認するリストに記載された実際のバインドで操作する
個人の習慣に合わせて調整する必要がある設定ファイル~/.pi/agent/keybindings.jsonが存在するか確認するこのファイルを編集してショートカットキーをカスタマイズする

セッション問題

このセクションでは、セッションファイルの肥大化と履歴セッションが見つからないという2種類の問題を扱います。

セッションファイルが大きすぎる

現象：コンテキストの使用量が増え続け、応答が遅くなるか、早期に圧縮がトリガーされる。

考えられる原因調査方法解決策
会話履歴が長すぎる実行/sessionメッセージ数とトークン使用量を確認する実行/compact会話履歴を圧縮する
自動圧縮が有効になっていない確認compaction.enabledが true かどうかtrue に設定して pi を再起動すると有効になる
単一セッションの累積時間が長すぎる用 /sessionセッションファイルのサイズ増加を観察する定期的に使用する/new新しいセッションを開始し、タスクごとにセッションを分割する

以前のセッションが見つからない

現象：pi -r のリストに以前の作業記録が表示されない。

考えられる原因調査方法解決策
復元エントリを使用していない実行pi -rまたは対話モードで /resume を入力してセッションリストを閲覧するリストで目的のセッションを選択して復元する
sessionDir設定が変更されたsettings.json のsessionDirの現在値を確認する元のディレクトリに戻すか、元のディレクトリ内のファイルを新しいディレクトリに移行する
セッションディレクトリの権限が異常実行ls ~/.pi/agent/sessions/読み書き可能か確認する実行chmod -R u+rw ~/.pi/agent/sessions権限を修復する

パフォーマンス問題

このセクションでは、応答が遅いという問題と、長いコンテキストでのパフォーマンス低下という2種類のパフォーマンス問題を扱います。

AI の応答が遅い

現象：リクエストを送信しても最初の文字が長時間出力されない、または全体の所要時間が通常より明らかに長い。

考えられる原因調査方法解決策
ネットワーク遅延が高い、またはリンクが不通実行ping api.anthropic.com遅延とパケットロスを確認するネットワークを切り替えるか、以下のプロキシ設定に従ってプロキシを構成する
推論レベルが高すぎて、思考時間が長引いているステータスバーの現在の推論レベルを確認するShift+Tab を押して推論レベルを下げる
システムプロンプトまたはコンテキストファイルの内容が多すぎるAGENTS.md などのコンテキストファイルのサイズを確認するシステムプロンプトを短くし、AGENTS.md の内容を簡素化する
単一リクエストのトークン消費が大きすぎる実行/sessionトークン使用量と所要時間の分布を確認する実行/compact 或 /newコンテキストを短くしてから再試行する

プロキシ環境を使用している場合は、curl -x $HTTP_PROXY https://api.anthropic.comでテストする。

プロキシ環境で ping が通らないことは、API が利用できないことを意味しない。

ping は ICMP を使用し、API は HTTPS を使用する。この場合、curl を使用して実際のリンクを検証する必要がある。

大量のコンテキスト後に AI の性能が低下する

現象：会話のラウンドが増えると、AI が以前の約束を忘れ始めたり、重複した回答を返したりする。

考えられる原因調査方法解決策
コンテキストがウィンドウの上限に近づき、初期の内容が圧縮されてしまう実行/session現在のトークン使用量を確認する手動で実行する/compactコンテキストを圧縮する
履歴メッセージに大量の無効な試行が混入している用 /treeブランチと無効な会話を確認する用 /new新しいセッションを開始し、結論を AGENTS.md に書き込む
参照されるファイルの内容が現在のタスクと無関係@参照とコンテキストファイルに無関係な内容が含まれていないか確認する不要なコンテキストファイルの内容を減らし、現在のタスクに必要な部分だけを残す

プロキシ設定

このセクションでは、制限されたネットワーク環境で Pi Agent が API に正常にアクセスする方法を説明します。

中国国内で API にアクセスする

settings.json で HTTP プロキシを構成する：

{
  "httpProxy": "http://127.0.0.1:7890"
}

または環境変数を設定して起動する：

$ export HTTP_PROXY=http://127.0.0.1:7890
$ export HTTPS_PROXY=http://127.0.0.1:7890
$ pi
その他の拡張