Verwenden Sie Pi mit Ihrem eigenen lokalen Modell

Pi ist ein quelloffener, BYOK- („Bring Your Own Key”) Terminal-Coding-Agent von earendil-works. Er spricht das OpenAI-Chat-Completions-Protokoll und liest seine Anbieter aus einer JSON-Konfigurationsdatei, sodass Sie Tokios als benutzerdefinierten Anbieter hinzufügen, baseUrl auf https://api.tokios.com/v1 verweisen und jedes Modell hinter Ihrem Connector steuern können — ohne dass der Port dieses Modells jemals freigegeben wird.

Voraussetzungen

Ein laufender Tokios-Connector, der mit Ihrem lokalen Modell gekoppelt ist — siehe Connector-Installation
Eine registrierte Deployment — siehe Modell registrieren
Ein Tokios-API-Schlüssel (sk-tok-…) — siehe API-Schlüssel
Pi installiert — npm install -g @earendil-works/pi-coding-agent

Finden Sie den Namen Ihrer Deployment

Pi sendet den Deployment-Namen — den öffentlichen Namen, den Sie in der Konsole registriert haben — nicht die Upstream-Modell-ID, die Ihr lokales Backend verwendet. Die 2 sind oft unterschiedliche Zeichenfolgen, und sie zu verwechseln, ist die häufigste Ursache für einen 404. Listen Sie die Deployments auf, auf die Ihr API-Schlüssel zugreifen kann:

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"

Jeder id in der Antwort ist ein Wert, den Sie in models.json verwenden können.

Führen Sie dies auch aus, wenn Ihr Modell bereits im Playground antwortet. Die Playground authentifiziert sich mit Ihrer angemeldeten Browsersitzung, daher beweist ein erfolgreicher Test dort nicht, dass Ihr sk-tok-…-Schlüssel gültig oder auf diese Deployment beschränkt ist. GET /v1/models ist der erste Aufruf, der den Schlüssel selbst testet.

Wo Pi seine Konfiguration speichert

Pi liest 2-Dateien aus einem dot-prefixeden .pi-Verzeichnis in Ihrem Home-Ordner:

Datei	Zweck
`.pi/agent/models.json`	Anbieter und die Modelle, die jeder Anbieter bereitstellt
`.pi/agent/settings.json`	Standardanbieter und -modell

~/.pi/agent/models.json

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

Erstellen Sie das Verzeichnis und die Datei, falls sie noch nicht vorhanden sind.

Das Verzeichnis ist .pi, mit einem führenden Punkt. Pi liest keine Datei, die unter pi/agent/models.json erstellt wurde — es startet normal, und Ihr Anbieter erscheint einfach nie in /model.

Einen benutzerdefinierten Anbieter konfigurieren

Fügen Sie dies in models.json ein und ersetzen Sie die 2-Platzhalterwerte. Es handelt sich um eine vollständige Datei, nicht um ein Fragment. Das Konfigurationsschema von Pi kann zwischen Releases variieren, daher bestätigen Sie die genauen Schlüsselnamen gegen Ihre installierte Version (siehe 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"]
        }
      ]
    }
  }
}

Ein Provider-Block kann jede Deployment auf Ihrem Konto bedienen. Fügen Sie für jede einen Eintrag in das models-Array ein:

~/.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"] }
      ]
    }
  }
}

Ersetzen Sie gemma-tunnel durch einen Deployment-Namen aus GET /v1/models — nicht die Upstream-Modell-ID, die Ihr Backend (Ollama, llama.cpp, vLLM oder LM Studio) bereitstellt, und nicht den Routes[].Model-Wert in Ihrer Connector-Konfiguration, der die Upstream-ID ist. Ersetzen Sie sk-tok-YOUR_KEY durch Ihren eigenen Schlüssel und vermeiden Sie, models.json mit einem echten Schlüssel in die Versionskontrolle zu übernehmen.

baseUrl muss /v1 enthalten, ohne abschließenden Slash. Die Pi-openai-completions-Provider bauen Anforderungspfade relativ zu dieser URL auf, sodass https://api.tokios.com die Tokios-API-Oberfläche verpasst und https://api.tokios.com/v1/ einen doppelten Separator erzeugen kann.

Das Kontextfenster abgleichen (optional)

Pi passt seine Prompts an das Kontextfenster des Modells an. Ollama, llama.cpp, LM Studio und vLLM stellen jeweils die Kontextlänge bereit, mit der das Modell geladen wurde, nicht das theoretische Maximum des Modells, also teilen Sie Pi die tatsächliche Zahl mit:

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

Wenn Sie es zu hoch einstellen, packt Pi einen Prompt, den Ihr lokaler Server ablehnt — ein Fehler, der über Tokios eintrifft, aber auf Ihrer eigenen Maschine entsteht. Kurze Prompts verbergen die Diskrepanz, sodass sie typischerweise erst dann sichtbar wird, wenn Pi beginnt, ganze Dateien zu senden. Bestätigen Sie den Schlüsselnamen gegen Ihre installierte Version.

Als Standard festlegen (optional)

Um Pi direkt auf Ihre Tokios-Deployment zu starten, anstatt sie bei jeder Sitzung auszuwählen, legen Sie einen Standardwert in ~/.pi/agent/settings.json fest:

~/.pi/agent/settings.json

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

Andernfalls wählen Sie den Provider und das Modell zur Laufzeit mit dem /model-Befehl in der TUI von Pi.

Die Anthropic-Oberfläche bevorzugen? (optional)

Pi spricht auch das Anthropic-Nachrichtenprotokoll. Um über die Anthropic-Oberfläche von Tokios zu routen, stellen Sie api auf anthropic-messages und entfernen Sie das /v1 aus baseUrl — Anthropic-ähnliche Clients verwenden die Root-Basis. Bestätigen Sie den genauen api-Wert, den Ihre Pi-Version erwartet.

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

Wählen Sie ein Tool-fähiges Modell

Pi-Agent nutzt Tool-Calling, um Dateien zu lesen, Befehle auszuführen und Code zu bearbeiten. Nicht jedes lokale Modell unterstützt Tool-Calls zuverlässig — wählen Sie vor der Nutzung von Pi für echte Änderungen eine Deployment, das von einem Modell mit starker Tool-Calling-Unterstützung angetrieben wird. Weitere Hinweise zur Auswahl eines Modells für agentic Coding finden Sie unter Modell nach Aufgabe auswählen.

Fehlerbehebung

Tokios wird in /model nicht angezeigt

Pi liest Ihre Datei nicht. Bestätigen Sie, dass sie sich unter ~/.pi/agent/models.json befindet — das Verzeichnis ist .pi, mit einem führenden Punkt, und unter Windows wird dies zu C:\Users\<you>\.pi\agent\models.json aufgelöst. Bestätigen Sie außerdem, dass die Datei gültiges JSON ist, wobei providers ein Objekt ist, das nach Anbietername keyt, und models ein Array.

401-Fehler

Der von Pi gesendete API-Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen. Bestätigen Sie, dass apiKey den vollständigen sk-tok-…-Schlüssel ohne zusätzliche Leerzeichen enthält, und prüfen Sie dessen Status auf der Keys-Registerkarte. Eine funktionierende Playground-Sitzung schließt dies nicht aus — der Playground verwendet Ihren API-Schlüssel nicht.

404-Fehler

Das Modell id unter models stimmt nicht mit einem registrierten Deployment überein. Führen Sie GET /v1/models aus und kopieren Sie ein id exakt aus der Antwort. Ein häufiger Fehler ist die Verwendung der Upstream-Modell-ID Ihres Connectors aus Routes[].Model anstelle des Deployment-Namens.

403-Fehler

Der Schlüssel existiert, ist aber nicht auf das konfigurierte Deployment beschränkt, oder Ihr Konto ist gesperrt. Prüfen Sie die Mustervorgaben des Schlüssels auf der Keys-Registerkarte.

503-Fehler

Der Connector für dieses Deployment ist offline oder hat sein gleichzeitiges Limit erreicht. Prüfen Sie die Connectors-Registerkarte — der Connector muss als Online angezeigt werden, und der Rechner, der ihn ausführt, muss weiterhin online und erreichbar sein.

Lange Sitzungen schlagen fehl, kurze funktionieren

Pi sendet mehr Kontext, als Ihr Backend geladen hat. Legen Sie contextWindow für den Modelleintrag auf die Kontextlänge fest, die Ihr Server tatsächlich bereitstellt, und bestätigen Sie die Ladezeit-Einstellung in Ollama, llama.cpp, LM Studio oder vLLM.

Nächste Schritte

omp (oh-my-pi)

Bevorzugen Sie die batteries-included-Fork? Richten Sie omp gegenüber Tokios auf die gleiche Weise ein.

Wählen Sie ein Modell nach Aufgabe

Ordnen Sie ein lokales Modell der agentic coding-Arbeit zu, bevor Sie es in Pi übernehmen.

Hardware und Kompatibilität

Runtime bereitstellen und verbinden

Client oder App verbinden

Vergleich

Verwenden Sie Pi mit Ihrem eigenen lokalen Modell

Voraussetzungen

Finden Sie den Namen Ihrer Deployment

Wo Pi seine Konfiguration speichert

Einen benutzerdefinierten Anbieter konfigurieren

Das Kontextfenster abgleichen (optional)

Als Standard festlegen (optional)

Die Anthropic-Oberfläche bevorzugen? (optional)

Wählen Sie ein Tool-fähiges Modell

Fehlerbehebung

Nächste Schritte

omp (oh-my-pi)

Wählen Sie ein Modell nach Aufgabe

​Voraussetzungen

​Finden Sie den Namen Ihrer Deployment

​Wo Pi seine Konfiguration speichert

​Einen benutzerdefinierten Anbieter konfigurieren

​Das Kontextfenster abgleichen (optional)

​Als Standard festlegen (optional)

​Die Anthropic-Oberfläche bevorzugen? (optional)

​Wählen Sie ein Tool-fähiges Modell

​Fehlerbehebung

​Nächste Schritte

omp (oh-my-pi)

Wählen Sie ein Modell nach Aufgabe

Voraussetzungen

Finden Sie den Namen Ihrer Deployment

Wo Pi seine Konfiguration speichert

Einen benutzerdefinierten Anbieter konfigurieren

Das Kontextfenster abgleichen (optional)

Als Standard festlegen (optional)

Die Anthropic-Oberfläche bevorzugen? (optional)

Wählen Sie ein Tool-fähiges Modell

Fehlerbehebung

Nächste Schritte