AIProxyServer - Anleitung

Erste Schritte

1. Starten Sie die App

Öffnen Sie AIProxyServer. Beim ersten Start wird der proxy automatisch gestartet und lauscht auf Port 8421 Ihres lokalen Rechners. Das Hauptfenster zeigt drei Bereiche:

• Proxy Server — aktueller Status, base URL und eine Schaltfläche zum Starten oder Stoppen des Listeners
• Bearer Token — optionaler Authentifizierungsschalter und token-Anzeige
• Providers — jeder unterstützte Cloud-AI-provider mit einer Set API Key-Schaltfläche pro Zeile

2. Fügen Sie Ihren ersten API Key hinzu

1. Wählen Sie einen beliebigen provider aus der Providers-Liste (zum Beispiel OpenAI (ChatGPT))
2. Klicken Sie auf Get API key, um die Konsole des providers im Browser zu öffnen, und erstellen oder kopieren Sie dann einen key
3. Klicken Sie in derselben Zeile auf Set API Key und fügen Sie den Wert in den Dialog ein
4. Klicken Sie auf Save. Die Statusbezeichnung wechselt zu Configured in Grün

3. Verbinden Sie eine Client-App

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

# Example: OpenAI Python SDK pointed at the proxy
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 niemals den echten key. AIProxyServer hängt die Upstream-Anmeldedaten an, wenn die Anfrage weitergeleitet wird.

Oberflächenübersicht

Proxy Server-Panel

Bearer Token-Panel

• Require Bearer Token authentication — Kontrollkästchen, das die Authentifizierung ein- oder ausschaltet. Standardmäßig aus für problemlose lokale Nutzung.
• Token-Feld — schreibgeschützte Anzeige des aktuellen tokens. Als Punkte dargestellt; verwenden Sie Copy, um es zu erhalten.
• Regenerate — einen neuen zufälligen token ausgeben. Bestehende Clients müssen mit dem neuen Wert aktualisiert werden.

Providers-Panel

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

• Den Anzeigenamen (zum Beispiel Claude (Anthropic))
• Konfigurationsstatus — grünes Configured, wenn ein API key gespeichert ist, sonst graues Not configured
• Den URL-Pfad, den Ihre Clients verwenden, z. B. /anthropic/v1/chat/completions
• Set API Key — öffnet einen Dialog zur Eingabe der Anmeldedaten
• Get API key — öffnet die Konsole des providers im Browser

Unterstützte Providers

Elf Cloud-AI-Dienste sind enthalten. Die meisten verwenden das OpenAI Chat Completions-Format nativ und werden unverändert per proxy weitergeleitet. Drei (Anthropic, Gemini, ERNIE) sprechen ihre eigenen Protokolle; AIProxyServer übersetzt Anfragen und Antworten im Handumdrehen, sodass Ihr Client immer nur OpenAI-Formen zu sehen bekommt.

Provider-spezifische Hinweise

• Azure OpenAI — fügen Sie den vollständigen Deployment-Endpoint in das Feld Endpoint Base URL ein, zum Beispiel https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Der proxy fügt automatisch /chat/completions?api-version=2024-02-01 an.
• ERNIE — Baidu Qianfan verwendet OAuth, daher sind sowohl API Key als auch Secret Key erforderlich. AIProxyServer fordert Access-tokens hinter den Kulissen an und speichert sie im Cache.
• Gemini — die Authentifizierung erfolgt über einen URL-Query-Parameter; der proxy fügt ihn für Sie hinzu. Free-Tier-Kontingente pro Minute gelten weiterhin.

API-Referenz

Endpoints

Streaming

Wenn der Client "stream": true sendet, antwortet der proxy mit Server-Sent Events im OpenAI-Format:

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

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

data: [DONE]

Native Streams von Anthropic und Gemini werden in dieses Format übersetzt, sodass alle Clients einen einzigen Parser verwenden können.

Authentifizierungs-Header

Wenn Require Bearer Token authentication aktiviert ist, senden Sie den token aus dem Hauptfenster mit jeder Anfrage:

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

Einstellungen

Öffnen Sie das Settings-Fenster über das Zahnradsymbol in der unteren Symbolleiste.

Client-Beispiele

cURL

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

# Claude via the same OpenAI shape
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",  # ignored when Bearer Token is off
)
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

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

Tipps

• Lassen Sie den Bearer Token aus, während Sie lokal entwickeln; schalten Sie ihn ein, sobald Sie den LAN-Zugriff aktivieren.
• Verwenden Sie in Ihrem Client-Code unterschiedliche Base URLs pro provider, damit Sie providers wechseln können, indem Sie eine Konstante ändern.
• Der proxy startet automatisch, aber Sie können ihn vorübergehend vom Hauptfenster aus stoppen, falls ein Portkonflikt auftritt.
• Wenn der Free-Tier eines providers Sie ratelimitiert, wird die Upstream-Fehlermeldung wortwörtlich weitergeleitet. Keine Retry-Logik wird vor dem Client verborgen.
• Der Endpoint /v1/providers ist nützlich, um zur Laufzeit herauszufinden, welche providers konfiguriert sind.

Fehlerbehebung

Der proxy startet nicht

• Ein anderer Prozess verwendet möglicherweise bereits Port 8421. Ändern Sie den Port in den Settings und starten Sie den proxy neu.
• Überprüfen Sie das Systemprotokoll auf die Fehlermeldung, die zum Startzeitpunkt angezeigt wird.

Eine Anfrage gibt 401 Unauthorized zurück

• Die Bearer-Token-Anforderung ist aktiviert, aber der Client hat keinen passenden Authorization: Bearer ...-Header gesendet.
• Der eigene API key des providers ist möglicherweise ungültig — der Upstream-Fehler wird weitergeleitet, prüfen Sie also den Nachrichtentext.

Eine Anfrage gibt "API key is not configured" zurück

• Öffnen Sie die Providers-Liste und klicken Sie auf Set API Key für den betreffenden provider.
• Für ERNIE müssen sowohl API Key als auch Secret Key ausgefüllt werden. Für Azure OpenAI ist auch die Endpoint Base URL erforderlich.

Mobiles Gerät kann den proxy nicht erreichen

• Aktivieren Sie Allow LAN Access in den Settings.
• Verwenden Sie die im Feld Base URL angezeigte LAN-IP, nicht localhost.
• Stellen Sie sicher, dass beide Geräte im selben Wi-Fi-Netzwerk sind und 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.
• Einige HTTP-Bibliotheken puffern SSE standardmäßig — deaktivieren Sie die Antwortpufferung auf der Client-Seite.

Datenschutz

• API keys werden mit Fernet verschlüsselt in ~/Library/Application Support/AIProxyServer/credentials.enc gespeichert. Der Verschlüsselungsschlüssel in master.key hat 0600-Berechtigungen.
• Der Bearer Token wird, wenn aktiviert, ebenfalls nur im verschlüsselten Tresor gespeichert und niemals in die normale Einstellungsdatei geschrieben.
• Der proxy leitet Anfragen nur an providers weiter, die Sie explizit konfiguriert haben. Er macht keine anderen ausgehenden Aufrufe.
• Keine Telemetrie, keine Analysen, keine Absturzberichte.
• Die Standard-Netzwerkbindung ist nur 127.0.0.1. LAN-Freigabe ist Opt-in.
• Gesprächsinhalte werden nicht gespeichert. AIProxyServer leitet Bytes weiter und vergisst sie sofort.