公開2026.07.03更新2026.10.13 94 人が閲覧（直近 30 日） AIエージェント・MCP

Pi（pi-coding-agent）をローカルLLMで動かす設定手順｜Ollama・llama.cpp・models.json【v1.1対応】

Q: PiはMCPサーバーに対応していますか？

v0.99.0（2026年9月29日）から標準で対応しています。 pi mcp add で登録し、 pi mcp list で接続を確認します。対応する通信方式はstdioとstreamable HTTPで、旧来のSSE方式は使えません。

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リポジトリ）。

# インストーラー（依存関係を固定し、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連携ページでは、次のコマンドで「必要なら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実行する方法で解説しています。

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のモデル設定ドキュメントは、ダミーのキーがあることでモデルが利用可能として扱われると説明しています。登録できたかは 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のコンテキスト長のページによると、既定値は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のドキュメントに書かれているので、Piからは変えられません。Ollama側で決めて、Piの値をそれに合わせます。

推論モデルで追加するcompat設定（max_tokens・developerロール）

ダミーサーバーで記録した送信内容から、Ollama向けに直しておきたい点が2つ見つかりました。1つ目は出力上限です。Piは既定で max_completion_tokens を送りますが、Ollamaのソース（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ドキュメントは、--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との違いで整理しています。

/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と動かし方、16GB前後のGPUで試すならGemma 4 12Bの必要スペックとOllamaでの使い方、OpenAIのオープンウェイトならgpt-oss-120bと20bの必要GPUを参照してください。

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の使い方にまとめています。SearXNGを自前で立てる方法もありますが、SearXNGは検索語を上流の検索エンジンへ中継するので、機密の検索語を外に出さない手段にはなりません。

組み込みMCPによるサーバー接続（v0.99.0以降）

以前のPiはMCPを拡張で後付けする設計でしたが、v0.99.0でMCP、codemode、ツール検索が組み込み拡張になりました。MCPのドキュメントによると、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のセキュリティ文書も、ツール呼び出しのたびに承認を求めず、起動したアカウントの権限でファイルの読み書きや実行を行うと明記しています。どのモデルを使っても、指示の取り違えや、READMEやコメントに仕込まれた指示（プロンプトインジェクション）に従ってしまう危険はなくなりません。エージェントを乗っ取る攻撃の実例はAgentjackingの攻撃と防御設定で解説しています。

project trustとコンテナ隔離の使い分け

Piには、フォルダ内の .pi/settings.json や拡張を読み込む前に確認する「project trust」があります。ただしこれは読み込む設定を選ぶ仕組みで、ツールが触れる範囲は制限しません。AGENTS.md や CLAUDE.md は信頼の可否に関係なく読み込まれます。実際に被害を限定できるのは、隔離環境のドキュメントにあるDocker、Docker Sandboxes、OpenShellなどでPi全体を隔離する方法です。作業フォルダだけをマウントし、~/.pi/agent（認証情報を含む）はマウントせず、不要なら外部ネットワークも閉じます。クラウド側で隔離する選択肢はDocker Cloud Sandboxesの手順と料金を参照してください。

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の承認モード、同じOSSでローカルLLMにも対応するならOpenCodeのインストールと設定と比べて選ぶのが安全です。

社内データを外に出さない生成AIの開発環境やエージェントの組み込みを検討している場合は、株式会社一創の生成AI導入支援で、モデル選定から隔離環境の設計まで相談を受けています。

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を使うときは、隔離環境を用意することが条件になります。