AIProxyServer - Anleitung

Erste Schritte

1. Die App starten

Öffnen Sie AIProxyServer. Beim ersten Start läuft der Proxy automatisch an und lauscht auf Port 8421 Ihres lokalen Rechners. Das Hauptfenster zeigt drei Bereiche:

• Proxy Server — aktueller Status, Basis-URL und eine Schaltfläche zum Starten oder Stoppen des Listeners
• Bearer Token — optionaler Schalter für die Authentifizierung und Anzeige des Tokens
• Anbieter — jeder unterstützte Cloud-KI-Anbieter, mit einer Schaltfläche Set API Key in jeder Zeile

2. Ihren ersten API-Schlüssel hinzufügen

1. Wählen Sie einen beliebigen Anbieter aus der Anbieterliste (zum Beispiel OpenAI (ChatGPT))
2. Klicken Sie auf Get API key , um die Konsole des Anbieters im Browser zu öffnen, und erstellen oder kopieren Sie dort einen Schlüssel
3. Klicken Sie auf Set API Key in derselben Zeile und fügen Sie den Wert in den Dialog ein
4. Klicken Sie auf Speichern. Die Statusanzeige wechselt zu Konfiguriert in Grün

3. Eine Client-App verbinden

Richten Sie einen beliebigen OpenAI-kompatiblen Client auf den Proxy. Die Basis-URL lautet http://localhost:8421/<provider>/v1. Das Anbietersegment bestimmt, welche Cloud die Anfrage erhält.

# Beispiel: OpenAI Python SDK auf den Proxy gerichtet
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Der Client sieht den echten Schlüssel nie. AIProxyServer hängt die Zugangsdaten erst beim Weiterleiten der Anfrage an.

Überblick über die Oberfläche

Bereich „Proxy Server“

Bereich „Bearer Token“

• Bearer-Token-Authentifizierung verlangen — Kontrollkästchen, das die Authentifizierung ein- oder ausschaltet. Standardmäßig aus, für unkomplizierte lokale Nutzung.
• Token-Feld — schreibgeschützte Anzeige des aktuellen Tokens. Wird als Punkte dargestellt; verwenden Sie Kopieren , um ihn abzurufen.
• Neu erzeugen — erzeugt ein neues zufälliges Token. Bestehende Clients müssen auf den neuen Wert aktualisiert werden.

Bereich „Anbieter“

Eine Zeile pro unterstütztem Cloud-Anbieter. Jede Zeile zeigt:

• Den Anzeigenamen (zum Beispiel Claude (Anthropic))
• Konfigurationsstatus — grün Konfiguriert wenn ein API-Schlüssel gespeichert ist, grau Nicht konfiguriert andernfalls
• Den URL-Pfad, den Ihre Clients verwenden, z. B. /anthropic/v1/chat/completions
• Set API Key — öffnet einen Dialog zur Eingabe der Zugangsdaten
• Get API key — öffnet die Konsole des Anbieters in Ihrem Browser

Unterstützte Anbieter

Elf Cloud-KI-Dienste sind enthalten. Die meisten nutzen von Haus aus das Format der OpenAI Chat Completions und werden unverändert weitergeleitet. Drei (Anthropic, Gemini, ERNIE) sprechen eigene Protokolle; AIProxyServer übersetzt Anfragen und Antworten im laufenden Betrieb, sodass Ihr Client immer nur OpenAI-Strukturen sieht.

Hinweise zu einzelnen Anbietern

• Azure OpenAI — fügen Sie den vollständigen Deployment-Endpunkt in das Feld Endpoint Base URL ein, zum Beispiel https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Der Proxy hängt /chat/completions?api-version=2024-02-01 automatisch an.
• ERNIE — Baidu Qianfan nutzt OAuth, daher werden sowohl API Key als auch Secret Key benötigt. AIProxyServer fordert Zugriffstoken im Hintergrund an und speichert sie zwischen.
• Gemini — die Authentifizierung erfolgt über einen URL-Abfrageparameter; der Proxy fügt ihn für Sie hinzu. Die Minutenkontingente des kostenlosen Tarifs gelten weiterhin.

API-Referenz

Endpunkte

Streaming

Wenn der Client "stream": truesendet, antwortet der Proxy mit Server-Sent Events im Format von OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Die nativen Streams von Anthropic und Gemini werden in diese Form übersetzt, sodass alle Clients mit einem einzigen Parser auskommen.

Authentifizierungs-Header

Wenn Bearer-Token-Authentifizierung verlangen aktiv ist, senden Sie das Token aus dem Hauptfenster bei jeder Anfrage mit:

Authorization: Bearer <token-shown-in-app>

Einstellungen

Öffnen Sie das Einstellungsfenster über das Zahnradsymbol in der unteren Werkzeugleiste.

Client-Beispiele

cURL

# OpenAI (Durchreichen)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude über dieselbe OpenAI-Struktur
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # wird ignoriert, wenn Bearer Token aus ist
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Mit einem beliebigen OpenAI-kompatiblen Dart-Client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // ungenutzt, wenn Bearer Token aus ist
);

Tipps

• Lassen Sie das Bearer Token aus, solange Sie lokal entwickeln; schalten Sie es ein, sobald Sie den LAN-Zugriff aktivieren.
• Verwenden Sie in Ihrem Client-Code je Anbieter eigene Basis-URLs, damit Sie den Anbieter durch Ändern einer einzigen Konstante wechseln können.
• Der Proxy startet automatisch, lässt sich bei einem Portkonflikt aber vorübergehend im Hauptfenster stoppen.
• Wenn der kostenlose Tarif eines Anbieters Sie ausbremst, wird die Fehlermeldung der Gegenstelle wortgetreu weitergereicht. Es gibt keine versteckte Wiederholungslogik.
• Der Endpunkt /v1/providers ist nützlich, um zur Laufzeit herauszufinden, welche Anbieter konfiguriert sind.

Fehlerbehebung

Der Proxy startet nicht

• Möglicherweise belegt ein anderer Prozess bereits Port 8421. Ändern Sie den Port in den Einstellungen und starten Sie den Proxy neu.
• Sehen Sie im Systemprotokoll nach der beim Start angezeigten Fehlermeldung.

Eine Anfrage liefert 401 Unauthorized

• Die Bearer-Token-Pflicht ist aktiv, aber der Client hat keinen passenden Header Authorization: Bearer ... gesendet.
• Auch der API-Schlüssel des Anbieters selbst kann ungültig sein — der Fehler der Gegenstelle wird weitergereicht, prüfen Sie also den Nachrichtentext.

Eine Anfrage liefert „API key is not configured“

• Öffnen Sie die Anbieterliste und klicken Sie bei dem betreffenden Anbieter auf Set API Key .
• Für ERNIE müssen sowohl API Key als auch Secret Key ausgefüllt sein. Für Azure OpenAI wird zusätzlich die Endpoint Base URL benötigt.

Das Mobilgerät erreicht den Proxy nicht

• Aktivieren Sie LAN-Zugriff erlauben in den Einstellungen.
• Verwenden Sie die im Feld „Basis-URL“ angezeigte LAN-IP, nicht localhost.
• Achten Sie darauf, dass beide Geräte im selben WLAN sind und dass Ihre Firewall eingehende Verbindungen auf dem Proxy-Port zulässt.

Streaming-Antworten kommen alle auf einmal an

• Stellen Sie sicher, dass Ihr Client "stream": true im JSON-Body sendet.
• Manche HTTP-Bibliotheken puffern SSE standardmäßig — deaktivieren Sie die Antwortpufferung auf Client-Seite.

Datenschutz

• API-Schlüssel werden mit Fernet verschlüsselt gespeichert, in ~/Library/Application Support/AIProxyServer/credentials.enc. Der Verschlüsselungsschlüssel in master.key hat die Berechtigungen 0600.
• Das Bearer Token wird, sofern aktiviert, ebenfalls nur im verschlüsselten Tresor abgelegt und nie in die normale Einstellungsdatei geschrieben.
• Der Proxy leitet Anfragen ausschließlich an Anbieter weiter, die Sie ausdrücklich konfiguriert haben. Er stellt keine weiteren ausgehenden Verbindungen her.
• Keine Telemetrie, keine Analysedaten, keine Absturzberichte.
• Standardmäßig bindet sich der Dienst nur an 127.0.0.1 . Die Freigabe im LAN erfolgt nur auf ausdrücklichen Wunsch.
• Gesprächsinhalte werden nicht gespeichert. AIProxyServer leitet Bytes weiter und vergisst sie sofort.