Pi のインストールと OmniProxy の設定

Pi は、コマンドライン上で直接対話し、ファイルを読み取ってタスクを実行できる軽量なターミナルアシスタントです。システムプロンプトは短く、標準ツールも多くありません。ほかのコマンド、ワークフロー、インターフェースが必要になったら、拡張機能で追加できます。拡張機能は Pi に能力を追加するコンポーネントで、作成後はほかの人と共有することもできます。

サブエージェントはタスクの一部を別のアシスタントに任せる機能で、プランモードは最初に手順を整理してから実行を始める機能です。この2つは標準機能には含まれていませんが、Pi 自身に作成させるか、ほかの人が共有したパッケージをインストールできます。

インストール前の準備

macOS と Linux では、ダウンロードとインストールを自動的に行う1行のコマンドであるインストールスクリプトを使用します。Windows では、Pi のトップページに掲載されている PowerShell コマンドを使用します。PowerShell は Windows に標準搭載されているコマンドライン環境です。Windows 上の Linux 環境である WSL に Pi をインストールすることもできます。

npm でインストールする場合は、Node.js 22.19 以降が必要です。npm は Node.js とともに使われるパッケージ管理ツールで、コマンドラインから Pi をインストールできます。

macOS Linux

install.sh

curl で公式スクリプトを取得
依存関係はインストーラーによって固定される
更新には pi update を使用

Windows

install.ps1

公式サイトの PowerShell コマンド
Git for Windows が Bash を提供
WSL を使用することもできる

Node 導入済み

npm

Node 22.19+ が必要
パッケージ名は pi-coding-agent
--ignore-scripts を追加

インストールスクリプトでは依存関係が固定されます。npm インストールでは間接的な依存関係は固定されず、--ignore-scripts を追加する必要があります。

インストールと初回起動

macOS または Linux でターミナルを開き、次を実行します。

curl -fsSL https://pi.dev/install.sh | sh

Windows では PowerShell を開き、次を実行します。

powershell -c "irm https://pi.dev/install.ps1 | iex"

Node.js 22.19 以降がすでにインストールされている場合は、Quickstart にある次の代替コマンドも使用できます。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

インストールスクリプトは対話型ターミナルで質問のために停止することがあるため、画面の指示に従って操作を続けてください。要件を満たす Node がすでにある場合、この npm コマンドでは質問は表示されません。別のディレクトリにインストールする場合は、--prefix /任意のディレクトリ を追加します。2026-10-09 時点では、この方法で Pi 1.1.0 がインストールされました。

通常の npm インストールでは、依存パッケージのライフサイクルスクリプト、つまりパッケージのインストール中に自動実行されるスクリプトは不要です。インストールスクリプトでは依存関係が固定され、以後は pi update で更新します。npm インストールの更新方法は、使用しているパッケージマネージャーに従います。Nix ユーザーは Pi の flake からインストールします。flake は、Nix がソフトウェアと依存関係を記述するための設定であり、Nix でインストールした Pi は pi update では更新できません。

インストールが完了したら、まずターミナルから Pi を見つけられることを確認します。

pi --version

Windows でモデルに Bash コマンドを実行させる場合、ほとんどのローカル環境では Git for Windows のインストールを推奨します。Bash は、Pi が一部のコマンドを実行するために使用するコマンド環境です。Pi は、~/.pi/agent/settings.json の shellPath、Program Files 内の Git Bash、PATH 上の bash.exe の順に検索します。shellPath は Bash の場所を指定するために使用し、PATH はシステムがコマンドを探す際に使用するディレクトリの一覧です。

起動後、!printf 'Bash is working\n' と入力して確認できます。ファイルとツールがすでに WSL 内にある場合は、その Linux 環境で Quickstart に従ってインストールしてください。

次に、Pi に確認または処理させるフォルダーへ移動してから起動します。

cd /path/to/folder
pi

このフォルダーが Pi の現在の作業範囲となり、ファイルや設定の検出、およびセッションのグループ化に使用されます。

OmniProxy から接続情報を取得する

まず OmniProxy で、次の3項目を用意します。

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: OmniProxy の現在のモデル一覧から完全な ID をコピー

baseUrl は Pi がリクエストを送信する API のアドレスで、末尾を /v1 にします。apiKey は API へのアクセスに使用するキーです。Model ID は呼び出すモデルの名前であり、OmniProxy の現在のモデル一覧から完全な形でコピーする必要があります。

api には、互換 API の例にある openai-completions を指定します。このフィールドは、どの API 形式でリクエストを送信するかを Pi に伝えます。

モデル ID は全体をコピーし、名前に含まれるスラッシュも残してください。2026-10-09 時点で、プロバイダーのドキュメントに記載されていた比較用の2つの ID は gemini-3.8-flash と grok-4.7 です。一覧にない名前はそのまま使用しないでください。

ツール設定を入力する

Pi のユーザーレベルのカスタムモデル設定は models.json に記述します。このファイルは agent ディレクトリにあり、既定のディレクトリは ~/.pi/agent なので、完全なパスは ~/.pi/agent/models.json です。環境変数 PI_CODING_AGENT_DIR を設定すると、Pi はその変数で指定されたディレクトリを使用します。環境変数とは、プログラムが読み取るためにシステムから提供される設定値です。

互換 API の例に従って入力します。

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers には接続するサービスを、models には選択可能なモデルを列挙します。各モデルの id は、OmniProxy の現在のモデル一覧にある完全な Model ID と一致させる必要があります。input は、ここで設定するのがテキスト入力であることを示します。

apiKey には値を直接記述できるほか、$NAME または ${NAME} と書いて、Pi に環境変数から読み取らせることもできます。! で始まる値はコマンドとして扱われ、リクエストのたびに実行されます。実際のキーをリポジトリへコミットしないでください。ゲートウェイがキーを検証しない場合は、ローカル環境だけで使用するプレースホルダー文字列を入力できます。2026-10-09 時点では、この方法でファイルが読み込まれました。

/model を開くと、このファイルが再読み込みされます。/model は、Pi でモデルを確認して選択するための画面です。カスタムモデルは、Pi が認証情報を解決できるようになるまで /model に表示されません。モデルを選択して Ctrl+S を押すと、新しいセッションの既定モデルとして保存できます。

ファイル

models.json

デフォルトのディレクトリは ~/.pi/agent
providers に項目を追加
api には completions を使用

アドレス

baseUrl

/v1 まで含める
apiKey には変数を指定可能
モデル id は正確に記述

選択

/model

開くとファイルが再読み込みされる
先ほどのモデルを選択
Ctrl+S でデフォルトとして保存可能

ファイルを変更した後、Pi で /model を開き、モデルが表示されていることを確認します。

実際のタスクで確認する

設定が完了したら、ファイルがあるディレクトリで非対話型の確認を実行できます。非対話型とは、継続的な対話を開始せず、Pi が1つのタスクを完了した時点で終了する実行方法です。--model の後ろを、OmniProxy の現在の一覧にある完全な ID に置き換えてください。

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "指定したファイルの1行目を読み取り、ファイルは変更しないでください。"

ここでは --tools read によって読み取りツールだけを許可し、タスクの内容でもファイルを変更しないよう明示しています。2026-10-09 に Pi 1.1.0 を使用したテストでは、ファイルの内容を読み取れました。最初の応答には約2分かかりました。

対話形式も使用できます。ディレクトリへ移動して pi を実行し、/model でモデルを選択します。Quickstart にあるタスク例の1つは、このリポジトリがどのように構成され、チェックをどのように実行するかを Pi に説明させるものです。Pi がファイルを読み取り、説明を返すことを確認してから、OmniProxy の呼び出し履歴で呼び出し元とモデル ID を確認します。

起動

pi が起動する

先に cd でフォルダーへ移動
pi --version に出力がある
画面下部にモデル名がある

タスク

ディレクトリを読み取った

リポジトリの構成について質問する
一覧表示されたファイルを確認する
設定の保存成功だけで判断しない

記録

ゲートウェイで確認できる

送信元は Pi
モデル ID が一致している
キーはローカルに保持

画面下部にモデル名が表示された後、実際のタスクも1回完了させる必要があります。

よくあるエラー

pi が見つからない：ターミナルを開き直し、pi --version をもう一度実行します。npm でインストールした場合は、グローバル bin が PATH に含まれていることを確認します。
/model にカスタムモデルが表示されない：models.json が ~/.pi/agent/ にあり、apiKey を解決できることを確認してから、/model を開き直します。
Windows で Bash が見つからないと表示される：Git for Windows をインストールするか、~/.pi/agent/settings.json で shellPath を設定します。JSON 内のバックスラッシュは2つ重ねて記述します。
リクエストが拒否される：api が openai-completions になっているか、baseUrl が /v1 で終わっているかを確認します。相手側が互換性をうたっているという理由だけで、追加の互換オプションを有効にしないでください。
モデル ID が無効：OmniProxy の現在の一覧からもう一度コピーします。

公式リファレンス

インストールコマンドについては、Pi 公式サイトとQuickstartを参照してください。モデルファイルについては、Choose a ModelとConfigurationを参照してください。Windows のコマンド環境については、Run Pi on Windowsを参照してください。例で使用したモデル ID については、Gemini モデル一覧とxAI モデルページを参照してください。

プレースホルダーをすべて独自の設定値に置き換えてください。実際のキーを公開しないでください。

保存された結果や HTTP 200 だけでは完全なエージェント互換性が証明されません。OmniProxy の呼び出し記録でソースとモデルを確認してください。

公式ソース · Pi ↗