メインコンテンツへ移動
AIチュートリアル

Pi Agentのインストール設定と初回対話チュートリアル

piの導入は難しくなく、コマンド1つで完了します。先に決めておくべきなのは認証方式だけです。既存のサブスクリプションを使うか、API Keyを使うか。ここではインストール、認証、初回対話までを一通り説明します。基本概念：2つの認証方式piをインストールした後は、LLMサービスプロバイダーの認証情報が必要です。認証方法は2つあり、この記事で押さえるべき違いは次のとおりです：サブスクリプションログイン（/login）｜API Key使用するもの｜Claude Pro/Max、ChatGPT Plus/Proなどのサブスクリプション｜プロバイダーが発行するAPI Key課金｜複雑（サブスクリプション枠 + 追加利用の可能性）｜従量制

彡爺約11分で読了
Pi Agentのインストール設定と初回対話チュートリアル

piの導入は難しくなく、コマンド1つで完了します。先に決めておくべきなのは認証方式だけです。既存のサブスクリプションを使うか、API Keyを使うか。ここではインストール、認証、初回対話までを一通り説明します。

基本概念：2つの認証方式

piをインストールした後は、LLMサービスプロバイダーの認証情報が必要です。認証方法は2つあり、この記事で押さえるべき違いは次のとおりです。

  • サブスクリプションログイン（/login）｜API Key

  • 使用するもの｜Claude Pro/Max、ChatGPT Plus/Proなどのサブスクリプション｜プロバイダーが発行するAPI Key

  • 課金｜複雑（サブスクリプション枠 + 追加利用の可能性）｜トークン単位で、使った分だけ課金

  • 認証情報の保存先｜~/.pi/agent/auth.json（OAuthトークン、自動更新）｜環境変数 または auth.json

  • 向いている人｜既存のサブスクリプションがあり、Keyを個別に管理したくない人｜費用を正確に管理したい人

一点注意してください：Anthropicのサブスクリプションログイン（Claude Pro/Max）はサードパーティのharness経由で、トークン単位で課金され、サブスクリプションプランの利用枠は消費しません。piに警告が表示されますが、正常な動作です。費用を完全に管理し、いつでも使用額を確認したいなら、API Keyのほうが手軽です。

実践

1. piをインストール

piはNode.js上で動作し、22.19.0以上が必要です。まず node --version で確認してください。インストール方法は2つあります。

# npmでグローバルインストール（--ignore-scriptsで依存関係のスクリプトをスキップし、より安全）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# またはcurlインストーラーを使用（Nodeが未インストールの場合は自動でインストール）
curl -fsSL https://pi.dev/install.sh | sh

インストール後、pi --versionで確認します。アンインストールは npm uninstall -g @earendil-works/pi-coding-agentを使用します。

2. 認証を設定

方法1：API Key（推奨）。Keyを環境変数に設定します。

export ANTHROPIC_API_KEY=sk-ant-...
pi

またはpi内で /login を実行し、API Keyプロバイダーを選択して、Keyを ~/.pi/agent/auth.json（権限0600、自分だけが読み書き可能）に保存します。よく使われるプロバイダーの環境変数は次のとおりです。

  • プロバイダー｜環境変数

  • Anthropic｜ANTHROPIC_API_KEY

  • OpenAI｜OPENAI_API_KEY

  • DeepSeek｜DEEPSEEK_API_KEY

  • Google Gemini｜GEMINI_API_KEY

  • Groq｜GROQ_API_KEY

  • xAI｜XAI_API_KEY

  • OpenRouter｜OPENROUTER_API_KEY

完全な一覧は数十社に及ぶため、公式のProvidersドキュメント[1]を参照してください。

方法2：サブスクリプションログイン。Claude ProやChatGPT Plusなどのサブスクリプションを利用している場合は、pi内で /login を実行し、対応するプロバイダーを選択してOAuthを完了します。トークンの有効期限が切れると、piが自動で更新します。選択肢：Claude Pro/Max、ChatGPT Plus/Pro(Codex)、GitHub Copilot、xAI、OpenRouter。ログアウトには /logoutを使用します。

Piのコミュニティは活発で、最新のPi AgentはすでにQwenのトークンプランにも対応しています。

モデルを設定したら、/modelで使用するモデルを選択できます。

Pi Agentにはscoped modelsという概念もあります。

scoped modelsは、複数のモデルを ctrl + p で素早く切り替えられるようにする機能です。ctrl + lで選択することもできます。対応する設定は ~/.pi/agent/settings.json ファイルの enabledModels フィールドにあります。

3. 初回起動

プロジェクトディレクトリに移動して起動します。

cd /path/to/your/project
pi

.pi/設定を含むプロジェクトを初めて開くと、piは信頼するかどうかを尋ねます。プロジェクトレベルのリソースには任意のコードを実行できる拡張機能が含まれる可能性があるため、piはユーザーに知らせずに読み込むことはありません。信頼設定は ~/.pi/agent/trust.json に保存され、次回からは尋ねられません。

画面は上から4つの領域に分かれています：Header（ショートカット/読み込まれたリソース）、Messages、Editor（入力欄、枠線の色は思考レベルを表す）、Footer（ディレクトリ/セッション/トークン使用量/費用/現在のモデル）。直接入力してEnterを押します。例えば：

このリポジトリの構成を確認して、チェックの実行方法を教えてください。

piはモデルにデフォルトで4つのツールを提供します：read、write、edit、bash。そのほかの読み取り専用ツール grep/find/ls はデフォルトで無効になっており、必要に応じて --tools で有効化します。例えば、piに読み取り専用でコードレビューをさせる場合：

pi --tools read,grep,find,ls -p "このリポジトリのコード品質をレビューしてください"

モデルの切り替えはCtrl+Lまたは /model、終了はCtrl+Cを2回押すか /quit、前回の会話の続きは pi -cです。

仕組みを理解する

認証情報の解決順序：環境変数、auth.json、コマンドライン引数を同時に設定した場合、piは コマンドライン --api-key > auth.json > 環境変数 > models.json の順で使用します。一時的に別のKeyを試す場合は、設定ファイルを変更せず pi --api-key xxxを実行します。

プロジェクトの信頼は入力に対する防御であり、サンドボックスではありません：信頼確認は対話モードの起動時にのみ表示されます。非対話モード（pi -p）ではデフォルトで ask が使用され、-a/-naで上書きできます。piにはデフォルトでサンドボックスがなく、モデルがbashを使用できる場合は任意のコマンドを実行できます。信頼できないリポジトリを扱う場合は、コンテナによる分離が必要です。これは後半のセキュリティ編で説明します。

よくある質問

Q：pi --version でcommand not foundと表示されますが、npmではインストール済みと表示されます。
多くの場合、npmのグローバルbinディレクトリがPATHに含まれていません。npm prefix -g でパスを確認してPATHに追加してください。nvmを使用している場合は nvm use も忘れないでください。

Q：起動時にNodeのバージョンが低すぎると表示されます。
piにはNode 22.19.0以上が必要です。バージョンマネージャー（fnm/mise/nvm）でアップグレードするか、curlインストーラーを使ってインストールしてください。

Q：Claude Proでログインした後、毎回追加利用の警告が表示されます。
Anthropicのサブスクリプションはサードパーティ経由でトークン単位に課金されます。無効にするには、~/.pi/agent/settings.jsonに次を追加します。

{ "warnings": { "anthropicExtraUsage":false } }

Q：Shift+Enterで改行できません。
piは修飾キーの認識にKittyキーボードプロトコルを使用します。iTerm2、Kitty、Ghosttyでは設定なしで使用できます。VS Code 1.109.5以降もデフォルトで対応しています。Windows Terminal、WezTerm、Alacrittyでは、キー入力を転送する設定を手動で1行追加する必要があります。ターミナル設定ドキュメント[2]を参照してください。

Q：完全にオフラインで使用し、更新確認のためにpi.devへ接続したくありません。
PI_OFFLINE=1 で起動時のすべてのネットワーク操作を無効にできます。バージョン確認だけを無効にする場合は PI_SKIP_VERSION_CHECK=1を使用します。

参考資料

  • • Piクイックスタートドキュメント[3]

  • • Pi Providersドキュメント[1] - すべてのProvider、環境変数、クラウドプロバイダーの設定

  • • Pi Custom Modelsドキュメント[4] - models.jsonによるカスタムProvider

  • • Pi Settingsドキュメント[5]

  • • Pi Terminal Setup[2] - 各ターミナルのキー設定

  • • Pi GitHubリポジトリ[6]

引用リンク

[1] 公式Providersドキュメント: https://pi.dev/docs/latest/providers
[2] ターミナル設定ドキュメント: https://pi.dev/docs/latest/terminal-setup
[3] Piクイックスタートドキュメント: https://pi.dev/docs/latest/quickstart
[4] Pi Custom Modelsドキュメント: https://pi.dev/docs/latest/models
[5] Pi Settingsドキュメント: https://pi.dev/docs/latest/settings
[6] Pi GitHubリポジトリ: https://github.com/earendil-works/pi

#AIエージェント#AIオフィス#AIデザイン#AIプログラミング#オープンソース#データ分析#大規模モデル#開発プラットフォーム