--- title: "Pi（pi-coding-agent）をローカルLLMで動かす設定手順｜Ollama・llama.cpp・models.json【v1.1対応】" url: "https://www.issoh.co.jp/tech/details/12925/" published: 2026-07-03 updated: 2026-10-13 categories: ["AIエージェント・MCP"] publisher: "株式会社一創" --- # Pi（pi-coding-agent）をローカルLLMで動かす設定手順｜Ollama・llama.cpp・models.json【v1.1対応】 Pi（pi-coding-agent）は、Mario Zechner氏が開発し現在はEarendil Worksが公開しているMITライセンスのターミナル型コーディングエージェントです。OllamaやLM Studio、llama.cppのサーバーにつなげばAPI料金をかけずに動き、コードを社外へ送らない構成も組めます。この記事では、2026年10月7日公開のv1.1.0を実際にインストールし、ダミーのOllama互換サーバーで送信内容を記録した結果をもとに、Ollamaとllama.cppそれぞれの接続手順、models.jsonで必ず書くべき値、モデルの選び方、安全に動かす隔離の考え方までを説明します。 ## まとめ：PiをローカルLLMで動かす手順と設定の要点 - いちばん簡単なのは `ollama launch pi`。Piのインストール、Ollamaをプロバイダーにする設定、Web検索パッケージの導入までを1コマンドで行います。 - 手で設定するなら `~/.pi/agent/models.json` に `baseUrl`（`http://localhost:11434/v1`）・`api`（`openai-completions`）・ダミーの `apiKey` を書き、`settings.json` で既定のプロバイダーとモデルを指定します。 - **models.jsonには contextWindow を必ず書く**。省くとPiは128Kと見なしますが、OllamaはVRAM 24GiB未満の環境で既定4kしか確保しません。Ollama公式はエージェント用途に64000トークン以上を推奨しています。 - llama.cppは v0.81.0 から組み込みプロバイダーになりました。llama-serverをルーターモードで起動し、Pi内で `/login llama.cpp` → `/llama` → `/model` の順に操作します。 - MCPは v0.99.0（2026年9月29日）から標準搭載です。`pi mcp add` でサーバーを登録できます。 - Piはツール呼び出しのたびに承認を求めません。モデルが返したbashコマンドは、起動したユーザーの権限でそのまま実行されます。コンテナなどで隔離してから使ってください。 ## Pi（pi-coding-agent）v1.1の現状とローカルLLM向きの設計 ### read・write・edit・bashの4ツールと拡張で足す設計 Piの標準ツールはread・write・edit・bashの4つだけです。READMEは、サブエージェントやプランモードのような機能を最初から持たない方針を明記しており、必要な機能はTypeScript製の拡張、スキル、プロンプトテンプレート、またはpi.devで配布されるパッケージで足します。v1.1.0をダミーサーバーにつないで最初のリクエストを記録したところ、システムプロンプトは2,745文字、4ツールの定義は2,956文字、リクエスト本体は合計5,856バイトでした。初回のリクエストに載る固定部分はこの程度に収まります（トークン数や実モデルでの成功率は測っていません）。 ### インストール方法とパッケージ名の移転（@earendil-works） 現在のnpmパッケージは `@earendil-works/pi-coding-agent` です。npmレジストリの記録では、旧スコープ `@mariozechner/pi-coding-agent` の最終版は0.73.1、新スコープの最初の版が0.74.0で、どちらも2026年5月7日に公開されています。旧スコープの手順を載せた解説はまだ多いので、インストールコマンドは新スコープで打ってください。v1.0.0は2026年10月1日、執筆時点の最新は10月7日の1.1.0です（[earendil-works/piリポジトリ](https://github.com/earendil-works/pi)）。 ``` # インストーラー（依存関係を固定し、pi update で更新できる） curl -fsSL https://pi.dev/install.sh | sh # npm で入れる場合（Node.js 22.19 以上が必要） npm install -g --ignore-scripts @earendil-works/pi-coding-agent pi --version ``` 本体は無料で、費用がかかるのは商用モデルに接続したときのモデル側の料金だけです。 ## OllamaでPiを動かす：ollama launch piとmodels.jsonの設定 ### ollama launch piによる自動設定 [Ollama公式のPi連携ページ](https://docs.ollama.com/integrations/pi)では、次のコマンドで「必要ならPiをインストールし、Web検索ツールを含めてOllamaをプロバイダーに設定し、対話セッションを開く」と説明しています。起動せずに設定だけ書き込む `--config` と、モデルを指定して起動する `--model` もあります。 ``` ollama launch pi ollama launch pi --config ollama launch pi --model qwen3.5:cloud ``` Ollamaのソース（`cmd/launch/pi.go`）を読むと、launchはnpmが無い環境では止まり、旧スコープのPiが入っていれば新スコープへの入れ替えを試みます。models.jsonに書き込むモデルには `"_launch": true` の印を付け、印の無いモデル（自分で書いたもの）は消さずに残します。手で追加したモデル定義は残りますが、`baseUrl` と settings.json の `defaultProvider`・`defaultModel` はlaunchが書き換えます。同じ `ollama launch` でCodexをつなぐ手順は[OllamaでCodexをローカルLLM実行する方法](/tech/details/12264/)で解説しています。 ### models.jsonとsettings.jsonを手で書く設定例 launchを使わない場合は、Ollamaを起動して `ollama pull qwen3-coder` でモデルを取得し、2つのファイルを書いてから `pi` を起動します。公式の例に `contextWindow` を足した形が次のとおりです。 ``` // ~/.pi/agent/models.json { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "models": [ { "id": "qwen3-coder", "contextWindow": 65536 } ] } } } // ~/.pi/agent/settings.json { "defaultProvider": "ollama", "defaultModel": "qwen3-coder" } ``` `//` の行はファイル名の説明なので、実際には書きません。`apiKey` の値は何でも構いませんが、空にはできません。[Piのモデル設定ドキュメント](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)は、ダミーのキーがあることでモデルが利用可能として扱われると説明しています。登録できたかは `pi --list-models qwen` で確かめられ、セッション中は `/model` で切り替えます。LM StudioやvLLMも同じ形式で書けます。`baseUrl` をそれぞれのサーバー（LM Studioなら既定で `http://localhost:1234/v1`）に変え、モデルIDはそのサーバーが返す名前に、認証と `contextWindow` もそのサーバーの設定に合わせます。 ### contextWindowとOllamaのコンテキスト長の整合 ローカル構成で最初に確認したいのは、Piが想定する文脈の長さとOllamaが実際に確保する長さのずれです。v1.1.0で `contextWindow` を書かずに `pi --list-models` を実行すると、表示は「context 128K・max-out 16.4K」でした。ソースでも、models.jsonで省いた値は `contextWindow ?? 128000`、`maxTokens ?? 16384` で埋められます。 一方、[Ollamaのコンテキスト長のページ](https://docs.ollama.com/context-length)によると、既定値はVRAMで決まり、24GiB未満なら4k、24〜48GiBなら32k、48GiB以上なら256kです。同じページは、Web検索・エージェント・コーディングツールには64000トークン以上を設定するよう勧めています。Piの自動要約（compaction）は「使った文脈がcontextWindowから予約分16,384トークンを引いた値を超えたとき」に動くので、128Kと思い込んだままだと約11万トークンまで要約が始まりません。ところがOllama側は4kで打ち切るため、ファイルを数本読んだ時点で前の指示や読んだ内容が消え、ツールを呼ばなくなったり同じ作業を繰り返したりします。 ``` # Ollama 側：起動中のサーバーやアプリを終了してから、コンテキスト長を指定して起動する OLLAMA_CONTEXT_LENGTH=65536 ollama serve # 実際に確保された長さを CONTEXT 列で確認する ollama ps ``` アプリ版のOllamaなら、設定画面のスライダーでも文脈長を変えられます。`ollama ps` のCONTEXT列に出た値を、models.jsonの `contextWindow` に書きます。OllamaのOpenAI互換APIにはコンテキスト長を指定する項目が無いと[互換APIのドキュメント](https://docs.ollama.com/api/openai-compatibility)に書かれているので、Piからは変えられません。Ollama側で決めて、Piの値をそれに合わせます。 ### 推論モデルで追加するcompat設定（max\_tokens・developerロール） ダミーサーバーで記録した送信内容から、Ollama向けに直しておきたい点が2つ見つかりました。1つ目は出力上限です。Piは既定で `max_completion_tokens` を送りますが、Ollamaのソース（[openai/openai.go](https://github.com/ollama/ollama/blob/main/openai/openai.go)）のリクエスト定義にあるのは `max_tokens` だけです。このため上限の指定はOllamaに届きません。2つ目は、gpt-ossのような思考（thinking）対応モデルに `"reasoning": true` を付けたときの挙動です。Qwen3-Coderは思考モードを持たないので、この指定は不要です。システムプロンプトが `developer` ロールで送られ、`reasoning_effort: "medium"` も付きます。Ollamaはロール名をそのままモデルのチャットテンプレートへ渡すので、developerロールを解釈できるかはモデル次第になります。 ``` { "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "compat": { "maxTokensField": "max_tokens", "supportsDeveloperRole": false }, "models": [ { "id": "gpt-oss:20b", "reasoning": true, "contextWindow": 65536, "maxTokens": 8192 } ] } } } ``` この設定にすると、送信内容は `system` ロールと `max_tokens: 8192` に変わりました（v1.1.0とダミーサーバーで送信形式を確認。実モデルでの推論結果は検証していません）。Piのドキュメントは、互換フラグはエンドポイントの違いを確かめてから付けるよう求めています。応答が空になる、システムプロンプトが効いていないように見えるといった症状が出たときに試してください。 ## llama.cpp（llama-server）でPiを動かす：組み込みプロバイダーの手順 ### llama-serverのルーターモード起動 v0.81.0（2026年7月21日）から、Piはllama.cppのルーターサーバーに対応する組み込みプロバイダーを持っています。[Piのllama.cppドキュメント](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/llama-cpp.md)は、`--model`（`-m`）を付けずに起動するよう指示しています。モデルを指定するとルーターモードではなく、1モデル専用のモードで起動してしまうためです。 ``` llama-server \ --models-dir ~/models \ --no-models-autoload \ --jinja \ --host 127.0.0.1 \ --port 8080 \ -ngl 999 \ -c 32768 ``` `--jinja` はツール呼び出しに対応したチャットテンプレートを有効にするので、エージェント用途では外せません。`-c` は読み込むモデルごとの文脈長で、省くとモデル本来の長さになり、メモリを大きく使います。`--models-dir` にはGGUFファイルを置きます。複数ファイルに分かれたモデルや画像入力用のファイルを伴うモデルは、サブディレクトリに分けます。GGUFの量子化の選び方は[GGUFの仕組みとGPTQ・AWQとの違い](/tech/details/13788/)で整理しています。 ### /login llama.cppでの接続登録と/llamaでのモデル読み込み Pi内で `/login llama.cpp` を実行し、ルーターのURL（既定は `http://127.0.0.1:8080`）を登録します。`--no-models-autoload` で起動した場合、この時点では接続先を保存するだけです。続けて `/llama` でモデルを読み込み、`/model` でセッションのモデルに選びます。環境変数で設定するなら `LLAMA_BASE_URL` と `LLAMA_API_KEY` を使います。 `LLAMA_SERVER_URL`、`.pi/llama-server.json`、`/models` コマンドを使う古い解説の手順は、v1.1.0の同梱ドキュメントにはありません。接続できないときは、シェルで `curl http://127.0.0.1:8080/health` と `curl http://127.0.0.1:8080/models` を実行してルーターの状態を確かめます。 ## ローカルモデルの選び方とPCスペックの目安 ### ローカルモデルの選定条件：ツール呼び出し対応と文脈長 エージェント用のモデルは、ベンチマークの順位より先に3点を確認します。1つ目はツール呼び出し（function calling）に対応しているか。2つ目は、64Kトークン以上の文脈を確保しても載るか。3つ目は、ツールの引数を壊さず安定してJSONで返せるか。OllamaとPiの公式例に出てくるのは `qwen3-coder` です。MoE型のQwen3.6-35B-A3Bは総パラメータ35Bのうち1トークンあたり約3Bだけを使うので生成が速めですが、メモリには35B分の重みを載せる必要があります。必要量は、量子化後のモデル全体の大きさとKVキャッシュで見積もってください。必要VRAMとOllamaでの動かし方は[Qwen3.6-35B-A3Bの必要VRAMと動かし方](/tech/details/12045/)、16GB前後のGPUで試すなら[Gemma 4 12Bの必要スペックとOllamaでの使い方](/tech/details/12370/)、OpenAIのオープンウェイトなら[gpt-oss-120bと20bの必要GPU](/tech/details/8080/)を参照してください。 ### VRAM別に決まるOllamaの文脈長と実用ライン Ollamaの既定値に従うと、VRAM 24GiB未満の環境は4kしか確保されません。64Kに引き上げると、その分のKVキャッシュがモデル本体とは別にメモリを使います。目安は、モデル本体と64Kの文脈がGPUに収まることです。`ollama ps` のPROCESSOR列が「100% GPU」でなくCPUへ逃げている場合は、出力が大きく遅くなります。収まらないときは、量子化を1段下げる、文脈を32KにしてcontextWindowも32768にそろえる、重みの小さいモデルに替える、のいずれかで調整してください。 ## Web検索・MCP・Ollamaクラウドモデルを足す方法 ### @ollama/pi-web-searchによる検索ツールの追加 ローカルモデルは学習時点より新しいライブラリの変更を知りません。これを補うのが `@ollama/pi-web-search` で、`ollama_web_search` と `ollama_web_fetch` の2ツールを追加します。`ollama launch pi` 経由なら導入と更新は自動、手動なら `pi install npm:@ollama/pi-web-search` です。このパッケージはローカルのOllamaを経由してollama.comの検索APIを呼ぶため、検索語は外部へ送られ、Ollamaアカウントでのサインインが必要です。APIキーや料金の扱いは[Ollama Web Searchの使い方](/tech/details/9059/)にまとめています。SearXNGを自前で立てる方法もありますが、SearXNGは検索語を上流の検索エンジンへ中継するので、機密の検索語を外に出さない手段にはなりません。 ### 組み込みMCPによるサーバー接続（v0.99.0以降） 以前のPiはMCPを拡張で後付けする設計でしたが、v0.99.0でMCP、codemode、ツール検索が組み込み拡張になりました。[MCPのドキュメント](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md)によると、stdioとstreamable HTTPに対応し、旧来のSSE方式には対応していません。 ``` pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem . pi mcp list ``` ユーザー単位の設定は `~/.pi/agent/mcp.json`、プロジェクト単位は `.pi/mcp.json` に入ります。プロジェクト側の設定は、そのフォルダを信頼すると承認したあとにだけ読み込まれます。1回だけMCPを止めて起動するなら `--no-mcp` を付けます（v1.0.4で追加）。 ### Ollamaクラウドモデルとローカルモデルの切り替え `qwen3.5:cloud` のように末尾が `:cloud` のモデルは、ローカルのOllamaを経由してollama.comで推論されます。重い設計判断だけクラウド、日常の編集はローカルという使い分けが `/model` の切り替えでできます。クラウドモデルに切り替えた時点でコードは外部に送られるので、機密案件ではクラウドモデルを登録しないでおきます。 ## Piを安全に動かす：承認なしで実行される前提の隔離 ### bashコマンドが承認なしで実行されることの実測 ダミーサーバーから「`echo written-by-pi > proof.txt && whoami` をbashで実行せよ」というツール呼び出しを返したところ、Pi v1.1.0（`--print` モード）は確認を挟まずにファイルを作り、実行ユーザー名を次のリクエストでモデルに返しました。[Piのセキュリティ文書](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md)も、ツール呼び出しのたびに承認を求めず、起動したアカウントの権限でファイルの読み書きや実行を行うと明記しています。どのモデルを使っても、指示の取り違えや、READMEやコメントに仕込まれた指示（プロンプトインジェクション）に従ってしまう危険はなくなりません。エージェントを乗っ取る攻撃の実例は[Agentjackingの攻撃と防御設定](/tech/details/18265/)で解説しています。 ### project trustとコンテナ隔離の使い分け Piには、フォルダ内の `.pi/settings.json` や拡張を読み込む前に確認する「project trust」があります。ただしこれは読み込む設定を選ぶ仕組みで、ツールが触れる範囲は制限しません。`AGENTS.md` や `CLAUDE.md` は信頼の可否に関係なく読み込まれます。実際に被害を限定できるのは、[隔離環境のドキュメント](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/containerization.md)にあるDocker、Docker Sandboxes、OpenShellなどでPi全体を隔離する方法です。作業フォルダだけをマウントし、`~/.pi/agent`（認証情報を含む）はマウントせず、不要なら外部ネットワークも閉じます。クラウド側で隔離する選択肢は[Docker Cloud Sandboxesの手順と料金](/tech/details/18257/)を参照してください。 ## Claude Code・Codex CLI・OpenCodeとの使い分けとPiを採用すべきでない場面 | 観点 | Pi | Claude Code | Codex CLI | OpenCode | | ------- | ------------------------- | ---------------- | ---------------- | -------- | | ローカルLLM | models.json・llama.cpp組み込み | ollama launch で可 | ollama launch で可 | 設定で可 | | 本体の費用 | 無料（MIT） | サブスク／API | 無料（Apache-2.0） | 無料（MIT） | | 標準ツール | 4種＋拡張 | サブエージェント等 | サンドボックス実行 | エージェント複数 | | 実行前の承認 | なし | 許可プロンプト | 承認モードあり | 権限設定あり | | MCP | 組み込み（v0.99.0〜） | 対応 | 対応 | 対応 | Piが向くのは、機密コードを外部APIへ送れない案件、シェルスクリプトやCIに組み込んで定型作業を回す場面、ローカルとクラウドのモデルを1つのCLIで比べたい検証環境です。逆に、隔離を用意できない社内PCで、大規模な実装をエージェント任せにする用途には採用しないでください。承認なしで動くPiとローカルモデルの組み合わせは、取り違えの影響がそのまま手元の環境に出ます。権限制御が標準で揃ったツールなら[Codex CLIの承認モード](/tech/details/8157/)、同じOSSでローカルLLMにも対応するなら[OpenCodeのインストールと設定](/tech/details/10369/)と比べて選ぶのが安全です。 社内データを外に出さない生成AIの開発環境やエージェントの組み込みを検討している場合は、株式会社一創の[生成AI導入支援](/service/ai/genai/)で、モデル選定から隔離環境の設計まで相談を受けています。 ## Pi（pi-coding-agent）とローカルLLMに関するよくある質問 ### Pi（pi-coding-agent）は無料で使えますか？ 本体はMITライセンスのOSSで、ライセンス料や座席課金はありません。Ollamaやllama.cppでローカルモデルを使えばモデルの利用料もかかりません。AnthropicやOpenAIなどに接続した場合は、そのサービスのAPI料金かサブスクリプションの料金がかかります。 ### Ollamaで動かすと途中で指示を忘れたりツールを呼ばなくなったりするのはなぜですか？ 原因の一つがコンテキスト長のずれです。OllamaはVRAM 24GiB未満の環境で既定4kしか確保しない一方、models.jsonでcontextWindowを省いたPiは128Kと見なします。`OLLAMA_CONTEXT_LENGTH` で64K以上を確保し、`ollama ps` で確かめた値をcontextWindowに書いてください。 ### PiはMCPサーバーに対応していますか？ v0.99.0（2026年9月29日）から標準で対応しています。`pi mcp add` で登録し、`pi mcp list` で接続を確認します。対応する通信方式はstdioとstreamable HTTPで、旧来のSSE方式は使えません。 ### Oh My Pi（omp）とPiは何が違いますか？ Oh My Piは、can1357氏のリポジトリで開発されている別のコーディングエージェントです。Ollama公式は、IDE風のツール、言語サーバー、サブエージェントなどを最初から備えたツールとして紹介しており、`ollama launch omp` で設定できます。Piは4ツールから始めて必要な機能を足す設計なので、標準機能の多さを取るならOh My Pi、構成を自分で絞りたいならPiという選び方になります。 ### PiとClaude Codeはどちらを使うべきですか？ チームの主力として大規模な実装を任せるなら、許可プロンプトやサブエージェントが標準で揃うClaude Codeが向きます。ローカルモデルを含む複数のモデルを1つのCLIで切り替えたい場合や、機密コードを外に出せない場合、スクリプトに組み込みたい場合はPiが有力です。Piを使うときは、隔離環境を用意することが条件になります。 ## 関連記事 - [Qwen3.6-35B-A3Bとは｜必要VRAM・GGUFサイズ・Ollama/vLLMの動かし方とベンチ比較](/tech/details/12045/) - [OllamaでCodexをローカルLLM実行する方法｜ollama launch chatgpt（旧codex-app）とCLIの設定](/tech/details/12264/) - [OpenCodeとは？無料OSSのAIコーディングエージェント｜インストール・opencode.json設定・料金を解説](/tech/details/10369/) - [Ollama Web Searchの使い方｜APIキー設定・料金・Python実装【2026年9月】](/tech/details/9059/) - [Agentjackingとは？偽のSentryエラーでAIコーディングエージェントを乗っ取る攻撃と防御設定](/tech/details/18265/) --- 出典: [Pi（pi-coding-agent）をローカルLLMで動かす設定手順｜Ollama・llama.cpp・models.json【v1.1対応】]()（株式会社一創）