Pi Agent 設定詳解
Pi Agent は JSON 形式の設定ファイルを使用し、グローバル設定とプロジェクトレベル設定に対応しています。
設定ファイルの場所
Pi Agent は 2 つの固定パスから設定を読み取ります。両者の優先度は異なります。
| ファイルパス | 適用範囲 | 説明 |
|---|---|---|
| ~/.pi/agent/settings.json | グローバル(すべてのプロジェクト) | すべてのプロジェクトに適用される共通設定 |
| .pi/settings.json | プロジェクトレベル | 現在のプロジェクトにのみ有効で、グローバル設定を上書きします |
JSON ファイルを直接編集するか、対話モードの/settingsコマンドを使用して一般的なオプションを変更できます。
モデルと推論設定
以下の設定項目は、デフォルトでどのプロバイダーとモデルを使用するか、および推論予算をどのように割り当てるかを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| defaultProvider | string | - | デフォルトプロバイダー。例: "anthropic"、"openai" |
| defaultModel | string | - | デフォルトモデル ID |
| defaultThinkingLevel | string | - | デフォルトの推論レベル。選択可能な値: off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | boolean | false | デフォルトで AI の推論プロセスを非表示にする |
| showCacheMissNotices | boolean | false | キャッシュミス通知を表示する |
| thinkingBudgets | object | - | 各レベルのトークン予算をカスタマイズする |
推論予算のカスタマイズ例:
例
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
なお、以下の数値は説明用の記述であり、公式のデフォルト値ではありません。
各レベルの意味とサンプル予算の対応は次のとおりです:
| レベル | 適用シナリオ | サンプル予算 |
|---|---|---|
| minimal | ほとんど推論せず、最速の応答を追求 | 1024 |
| low | 簡単な Q&A と小規模な変更 | 4096 |
| medium | 日常的なコーディングタスクのデフォルト選択 | 10240 |
| high | 複雑なリファクタリングと難易度の高い問題の調査 | 32768 |
UI と表示設定
以下の設定項目は、テーマの外観、エディターのレイアウト、起動時の動作を制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| theme | string | "dark" | テーマ名 |
| externalEditor | string | システムに応じて自動選択 | Ctrl+G で開く外部エディターのコマンド |
| quietStartup | boolean | false | 起動時のヘッダー情報を非表示にする |
| collapseChangelog | boolean | false | 更新後に折りたたまれた更新ログを表示するかどうか |
| editorPaddingX | number | 0 | エディターの水平パディング(0-3) |
| outputPad | number | 1 | メッセージ領域の水平パディング(0 または 1) |
| autocompleteMaxVisible | number | 5 | 自動補完の最大表示件数(3-20) |
VS Code ユーザーにおすすめの外部エディター設定:
例
"externalEditor": "code --wait"
}
--waitこのパラメーターにより、VS Code がファイルを閉じた後にのみ Pi Agent が実行を再開します。そうしないと、エディターを開いた後に Pi Agent がすぐに実行を継続します。
ネットワーク設定
以下の設定項目は、Pi Agent がモデル API にアクセスするときに使用するプロキシを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| httpProxy | string | - | HTTP プロキシ URL(グローバル設定のみ) |
プロキシを設定する(中国本土など、API へのプロキシアクセスが必要な環境向け):
例
"httpProxy": "http://127.0.0.1:7890"
}
コンテキスト圧縮設定
コンテキストが上限に近づくと Pi Agent は履歴メッセージを自動的に圧縮します。ここでは圧縮のトリガーと保持ポリシーを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| compaction.enabled | boolean | true | 自動圧縮を有効にする |
| compaction.reserveTokens | number | 16384 | LLM 応答用に確保するトークン |
| compaction.keepRecentTokens | number | 20000 | 圧縮せずに保持する最近のトークン数 |
リトライ設定
以下の設定項目は、リクエスト失敗後の自動リトライ動作(リトライ回数とバックオフ間隔)を決定します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| retry.enabled | boolean | true | 自動リトライを有効にする |
| retry.maxRetries | number | 3 | 最大リトライ回数 |
| retry.baseDelayMs | number | 2000 | リトライの基本遅延(ミリ秒)、指数バックオフ: 2s、4s、8s |
| retry.provider.timeoutMs | number | SDK のデフォルト | リクエストタイムアウト時間(ミリ秒) |
| retry.provider.maxRetries | number | 0 | プロバイダーレベルのリトライ回数 |
次の値をretry.provider.maxRetries実際にプロバイダーレベルのリトライが必要でない限り、0 のままにすることをお勧めします。
0 より大きい値に設定すると、使用量超過時に SDK レベルのリトライが Pi Agent をブロックし、Pi Agent レベルのリトライメカニズムが処理できなくなる可能性があります。
メッセージ送信設定
以下の設定項目は、会話中に挿入したメッセージをいつ、どのようにモデルに送信するかを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| steeringMode | string | "one-at-a-time" | steering メッセージ送信ポリシー: "all" または "one-at-a-time" |
| followUpMode | string | "one-at-a-time" | follow-up メッセージ送信ポリシー |
| transport | string | "auto" | 転送プロトコル: "sse"、"websocket"、"websocket-cached"、"auto" |
ターミナルと画像設定
以下の設定項目は、ターミナルでの画像の表示方法と、モデルに送信する前の処理ポリシーを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| terminal.showImages | boolean | true | ターミナルに画像を表示する |
| terminal.imageWidthCells | number | 60 | インライン画像の幅(ターミナルのセル数) |
| images.autoResize | boolean | true | 画像を 2000x2000 以内にスケーリングする |
| images.blockImages | boolean | false | すべての画像が LLM に送信されるのを防ぐ |
Shell 設定
以下の設定項目は、Pi Agent が bash コマンドを実行するときに使用する shell とコマンドプレフィックスを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| shellPath | string | - | カスタム shell パス |
| shellCommandPrefix | string | - | 各 bash コマンドのプレフィックス |
| npmCommand | string[] | - | npm パッケージ操作に使用するカスタムコマンド |
mise や asdf などのツールで Node.js のバージョンを管理する例:
例
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
モデル循環設定
以下の設定項目は、Ctrl+P でモデルを循環切り替えするときに表示されるモデルを制御します。
| 設定項目 | 型 | デフォルト値 | 説明 |
|---|---|---|---|
| enabledModels | string[] | - | 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 はインストール済みパッケージのフィルタリング設定で、ロードするパッケージを宣言するために使用します。
その他の拡張