Pi Agent 設定詳解

Pi Agent は JSON 形式の設定ファイルを使用し、グローバル設定とプロジェクトレベル設定に対応しています。


設定ファイルの場所

Pi Agent は 2 つの固定パスから設定を読み取ります。両者の優先度は異なります。

ファイルパス適用範囲説明
~/.pi/agent/settings.jsonグローバル(すべてのプロジェクト)すべてのプロジェクトに適用される共通設定
.pi/settings.jsonプロジェクトレベル現在のプロジェクトにのみ有効で、グローバル設定を上書きします

JSON ファイルを直接編集するか、対話モードの/settingsコマンドを使用して一般的なオプションを変更できます。


モデルと推論設定

以下の設定項目は、デフォルトでどのプロバイダーとモデルを使用するか、および推論予算をどのように割り当てるかを制御します。

設定項目型デフォルト値説明
defaultProviderstring-デフォルトプロバイダー。例: "anthropic"、"openai"
defaultModelstring-デフォルトモデル ID
defaultThinkingLevelstring-デフォルトの推論レベル。選択可能な値: off / minimal / low / medium / high / xhigh / max
hideThinkingBlockbooleanfalseデフォルトで AI の推論プロセスを非表示にする
showCacheMissNoticesbooleanfalseキャッシュミス通知を表示する
thinkingBudgetsobject-各レベルのトークン予算をカスタマイズする

推論予算のカスタマイズ例:

例

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

なお、以下の数値は説明用の記述であり、公式のデフォルト値ではありません。

各レベルの意味とサンプル予算の対応は次のとおりです:

レベル適用シナリオサンプル予算
minimalほとんど推論せず、最速の応答を追求1024
low簡単な Q&A と小規模な変更4096
medium日常的なコーディングタスクのデフォルト選択10240
high複雑なリファクタリングと難易度の高い問題の調査32768

UI と表示設定

以下の設定項目は、テーマの外観、エディターのレイアウト、起動時の動作を制御します。

設定項目型デフォルト値説明
themestring"dark"テーマ名
externalEditorstringシステムに応じて自動選択Ctrl+G で開く外部エディターのコマンド
quietStartupbooleanfalse起動時のヘッダー情報を非表示にする
collapseChangelogbooleanfalse更新後に折りたたまれた更新ログを表示するかどうか
editorPaddingXnumber0エディターの水平パディング(0-3)
outputPadnumber1メッセージ領域の水平パディング(0 または 1)
autocompleteMaxVisiblenumber5自動補完の最大表示件数(3-20)

VS Code ユーザーにおすすめの外部エディター設定:

例

{
  "externalEditor": "code --wait"
}

--waitこのパラメーターにより、VS Code がファイルを閉じた後にのみ Pi Agent が実行を再開します。そうしないと、エディターを開いた後に Pi Agent がすぐに実行を継続します。


ネットワーク設定

以下の設定項目は、Pi Agent がモデル API にアクセスするときに使用するプロキシを制御します。

設定項目型デフォルト値説明
httpProxystring-HTTP プロキシ URL(グローバル設定のみ)

プロキシを設定する(中国本土など、API へのプロキシアクセスが必要な環境向け):

例

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

コンテキスト圧縮設定

コンテキストが上限に近づくと Pi Agent は履歴メッセージを自動的に圧縮します。ここでは圧縮のトリガーと保持ポリシーを制御します。

設定項目型デフォルト値説明
compaction.enabledbooleantrue自動圧縮を有効にする
compaction.reserveTokensnumber16384LLM 応答用に確保するトークン
compaction.keepRecentTokensnumber20000圧縮せずに保持する最近のトークン数

リトライ設定

以下の設定項目は、リクエスト失敗後の自動リトライ動作(リトライ回数とバックオフ間隔)を決定します。

設定項目型デフォルト値説明
retry.enabledbooleantrue自動リトライを有効にする
retry.maxRetriesnumber3最大リトライ回数
retry.baseDelayMsnumber2000リトライの基本遅延(ミリ秒)、指数バックオフ: 2s、4s、8s
retry.provider.timeoutMsnumberSDK のデフォルトリクエストタイムアウト時間(ミリ秒)
retry.provider.maxRetriesnumber0プロバイダーレベルのリトライ回数

次の値をretry.provider.maxRetries実際にプロバイダーレベルのリトライが必要でない限り、0 のままにすることをお勧めします。

0 より大きい値に設定すると、使用量超過時に SDK レベルのリトライが Pi Agent をブロックし、Pi Agent レベルのリトライメカニズムが処理できなくなる可能性があります。


メッセージ送信設定

以下の設定項目は、会話中に挿入したメッセージをいつ、どのようにモデルに送信するかを制御します。

設定項目型デフォルト値説明
steeringModestring"one-at-a-time"steering メッセージ送信ポリシー: "all" または "one-at-a-time"
followUpModestring"one-at-a-time"follow-up メッセージ送信ポリシー
transportstring"auto"転送プロトコル: "sse"、"websocket"、"websocket-cached"、"auto"

ターミナルと画像設定

以下の設定項目は、ターミナルでの画像の表示方法と、モデルに送信する前の処理ポリシーを制御します。

設定項目型デフォルト値説明
terminal.showImagesbooleantrueターミナルに画像を表示する
terminal.imageWidthCellsnumber60インライン画像の幅(ターミナルのセル数)
images.autoResizebooleantrue画像を 2000x2000 以内にスケーリングする
images.blockImagesbooleanfalseすべての画像が LLM に送信されるのを防ぐ

Shell 設定

以下の設定項目は、Pi Agent が bash コマンドを実行するときに使用する shell とコマンドプレフィックスを制御します。

設定項目型デフォルト値説明
shellPathstring-カスタム shell パス
shellCommandPrefixstring-各 bash コマンドのプレフィックス
npmCommandstring[]-npm パッケージ操作に使用するカスタムコマンド

mise や asdf などのツールで Node.js のバージョンを管理する例:

例

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

モデル循環設定

以下の設定項目は、Ctrl+P でモデルを循環切り替えするときに表示されるモデルを制御します。

設定項目型デフォルト値説明
enabledModelsstring[]-Ctrl+P 循環時に利用可能なモデルリスト。ワイルドカードに対応

例

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

設定のマージ規則

プロジェクト設定(.pi/settings.json)はグローバル設定(~/.pi/agent/settings.json)を上書きします。

ネストされたオブジェクトはマージではなく置換の戦略を採用しています。以下に例を使って説明します。

グローバル設定ファイル ~/.pi/agent/settings.json:

例

{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

プロジェクト設定ファイル .pi/settings.json:

例

{
  "compaction": { "reserveTokens": 8192 }
}

マージ後に実際に有効となる設定では、theme はグローバルの dark を採用し、compaction.enabled はグローバルの true を採用し、compaction.reserveTokens はプロジェクト設定により 8192 に上書きされます。

つまり、プロジェクト設定は明示的に宣言されたフィールドのみを上書きし、その他のフィールドはグローバル設定を引き継ぎます。


完全な設定例

以下は典型的なグローバル設定ファイルです:

例

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

warnings.anthropicExtraUsage はブール値で、デフォルトは true です。

これは、Anthropic サブスクリプションの認証で有料の追加使用量が発生する可能性がある場合に通知を表示します。

packages はインストール済みパッケージのフィルタリング設定で、ロードするパッケージを宣言するために使用します。

その他の拡張