自身のローカルモデルとPiを併用する方法

Piはearendil-worksが提供するオープンソースのBYOK（自分のAPIキーを利用可能）型ターミナルコーディングエージェントです。OpenAIのチャット補完プロトコルに対応しており、JSON設定ファイルからプロバイダー情報を読み込みます。そのためTokiosをカスタムプロバイダーとして追加し、baseUrlをhttps://api.tokios.com/v1に指定するだけで、コネクター経由で任意のモデルを利用可能になります。しかもそのモデルのポートが外部に公開されることはありません。

前提条件

A running Tokios connector paired with your local model — see Connector install
A registered deployment — see Register a model
A Tokios API key (sk-tok-…) — see API keys
Piのインストール済み状態 — npm install -g @earendil-works/pi-coding-agent

自身のデプロイ名を確認する方法

Pi sends the deployment name — the public name you registered in the console — not the upstream model id your local backend uses. The 2 are often different strings, and confusing them is the most common cause of a 404. 自身のAPIキーでアクセス可能なデプロイ一覧：

curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

curl.exe https://api.tokios.com/v1/models `
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

レスポンス内のすべての id は、models.json で利用可能な値となります。

ご使用のモデルがすでに Playground 形式で応答する場合でもこの手順を実行してください。Playground はログイン済みのブラウザセッションで認証を行うため、そこでのテスト成功が必ずしも sk-tok-… APIキーが有効であるか、該当デプロイ向けに適切なスコープを持つことを保証するものではありません。GET /v1/models が実際にそのAPIキーを使用する最初の呼び出しとなります。

Piが設定情報を保存する場所

Pi reads 2 files from a dot-prefixed .pi directory in your home folder:

ファイル名	用途
`.pi/agent/models.json`	プロバイダーおよび各プロバイダーが提供するモデル一覧
`.pi/agent/settings.json`	デフォルトのプロバイダーとモデル

~/.pi/agent/models.json

C:\Users\<you>\.pi\agent\models.json

ディレクトリやファイルが存在しない場合は作成してください。

ディレクトリ名は .pi で、先頭にドットが付きます。pi/agent/models.json で作成されたファイルはPiによって読み込まれません。その場合は通常通り起動し、ご使用のプロバイダーは /model に表示されなくなります。

カスタムプロバイダーの設定方法

以下の内容を models.json に貼り付け、2 のプレースホルダー部分を適切な値に置き換えてください。これは断片ではなく完全なファイル内容です。Piの設定スキーマはバージョンによって変更される可能性があるため、ご使用のバージョンに合った正確なキー名を確認してください（pi.dev/docs を参照）。

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        {
          "id": "gemma-tunnel",
          "input": ["text"]
        }
      ]
    }
  }
}

一つのプロバイダーブロックでアカウント内のすべてのデプロイに対応できます。各デプロイ用に models 配列にエントリを追加してください：

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        { "id": "gemma-tunnel", "input": ["text"] },
        { "id": "qwen3-coder-tunnel", "input": ["text"] }
      ]
    }
  }
}

Replace gemma-tunnel with a deployment name from GET /v1/models — not the upstream model id your backend (Ollama, llama.cpp, vLLM, or LM Studio) serves, and not the Routes[].Model value in your connector config, which is the upstream id. Replace sk-tok-YOUR_KEY with your own key, and avoid committing models.json with a real key into version control.

baseUrl の値には末尾にスラッシュがない形で /v1 を含める必要があります。Piの openai-completions プロバイダーはこのURLを基準にリクエストパスを構築するため、https://api.tokios.com のように末尾にスラッシュがあると Tokios のAPIエンドポイントが見つからず、https://api.tokios.com/v1/ の場合は区切り文字が重複してしまいます。

コンテキストウィンドウの設定（任意）

Piはモデルのコンテキストウィンドウサイズに基づいてプロンプトの長さを決定します。Ollama、llama.cpp、LM Studio、vLLMではモデルが読み込まれた時点でのコンテキスト長が提供されるため、理論上の最大値ではありません。そのため実際の数値をPiに伝える必要があります。

{ "id": "gemma-tunnel", "input": ["text"], "contextWindow": 32768 }

数値を過大に設定すると、ローカルサーバーが受け付けられないプロンプトが生成されます。このエラーは Tokios 経由で報告されますが、実際の原因はご自身のマシン側にあります。短いプロンプトではこの不整合が目立たないため、ファイル全体を送信し始めて初めて問題が顕在化するケースが多いです。ご使用のバージョンで使われるキー名も確認してください。

デフォルト値として設定する（任意）

毎回手動で選択せずに、Piを起動した際に自動的に Tokios デプロイが利用されるようにするには、~/.pi/agent/settings.json にデフォルト値を設定します。

~/.pi/agent/settings.json

{
  "defaultProvider": "tokios",
  "defaultModel": "gemma-tunnel"
}

そうでない場合は、PiのTUI内で /model コマンドを使い実行時ごとにプロバイダーやモデルを選択できます。

AnthropicのAPIインターフェースを利用したい？（任意）

Pi also speaks the Anthropic messages protocol. To route through Tokios’s Anthropic surface instead, set api to anthropic-messages and drop the /v1 from baseUrl — Anthropic-style clients use the root base. Confirm the exact api value your Pi version expects.

"api": "anthropic-messages",
"baseUrl": "https://api.tokios.com"

ツール利用が可能なモデルを選択する

Piのエージェントはツール呼び出し機能を利用してファイルの読み取りやコマンド実行、コード編集を行います。ただしすべてのローカルモデルがツール呼び出しを確実に処理できるわけではありません。本格的な編集作業にPiを活用する場合は、ツール呼び出し機能が強力なモデルを基盤としたデプロイを選ぶべきです。タスク別モデル選定方法を参照して、エージェント型コーディング作業に適したモデルを選んでください。

トラブルシューティング

Tokiosが/modelに表示されない

Piが指定したファイルを読み込めません。ファイルが~/.pi/agent/models.jsonに存在するか確認してください。該当ディレクトリ名は.piで、先頭にドットが付きます。Windows環境ではこのパスはC:\Users\<you>\.pi\agent\models.jsonとして解釈されます。またファイル内容が有効なJSON形式であることも確認してください。providersはプロバイダー名をキーとするオブジェクト、modelsは配列である必要があります。

401エラー

Piが送信したAPIキーが存在しない、形式が不正、あるいは無効化されている可能性があります。apiKeyに余分な空白を含まず完全なsk-tok-…キーが記載されているか確認し、Keysタブでその状態を調べてください。Playgroundセッションが正常に動作しているからといって問題がないとは限りません。Playgroundでは実際にAPIキーが使用されていないためです。

404エラー

The model id under models doesn’t match a registered deployment. Run GET /v1/models and copy an id from the response exactly. A common near-miss is using the upstream model id from your connector’s Routes[].Model instead of the deployment name.

403エラー

キー自体は存在するものの、設定したデプロイ用のスコープに含まれていないか、アカウントが停止されている可能性があります。Keysタブで該当キーのモデルパターンを確認してください。

503エラー

該当デプロイ用のコネクターがオフライン状態、あるいは同時接続数の上限に達しています。Connectorsタブを確認してください。コネクターの状態がOnlineと表示されていること、またそれを実行しているマシンが正常に稼働し通信可能であることも確認が必要です。

長時間のセッションは失敗するが、短時間のものは問題なく動作する

Piから送信されるコンテキスト量が、ご使用のバックエンドで処理可能な量を上回っています。モデル設定画面で contextWindow をサーバーが実際に対応可能なコンテキスト長に設定し、Ollamaやllama.cpp、LM Studio、vLLM側でもその設定値が正しく反映されていることを確認してください。

次に行うべきこと

omp（oh-my-pi）

機能が充実したフォーク版を利用したい場合は、同様の手順でTokiosにompを接続してください。

タスクに応じてモデルを選ぶ

Piで利用する前に、ローカルにあるモデルがエージェント型コーディング作業に適しているかどうかを確認しましょう。

ハードウェアと互換性

サービングとランタイム接続

クライアント接続

比較

自身のローカルモデルとPiを併用する方法

前提条件

自身のデプロイ名を確認する方法

Piが設定情報を保存する場所

カスタムプロバイダーの設定方法

コンテキストウィンドウの設定（任意）

デフォルト値として設定する（任意）

AnthropicのAPIインターフェースを利用したい？（任意）

ツール利用が可能なモデルを選択する

トラブルシューティング

次に行うべきこと

omp（oh-my-pi）

タスクに応じてモデルを選ぶ

​前提条件

​自身のデプロイ名を確認する方法

​Piが設定情報を保存する場所

​カスタムプロバイダーの設定方法

​コンテキストウィンドウの設定（任意）

​デフォルト値として設定する（任意）

​AnthropicのAPIインターフェースを利用したい？（任意）

​ツール利用が可能なモデルを選択する

​トラブルシューティング

​次に行うべきこと

omp（oh-my-pi）

タスクに応じてモデルを選ぶ

前提条件

自身のデプロイ名を確認する方法

Piが設定情報を保存する場所

カスタムプロバイダーの設定方法

コンテキストウィンドウの設定（任意）

デフォルト値として設定する（任意）

AnthropicのAPIインターフェースを利用したい？（任意）

ツール利用が可能なモデルを選択する

トラブルシューティング

次に行うべきこと