Lokalen Reverse-Proxy starten und ersten Client verbinden (/healthz + SDK-Konfiguration)

In dieser Lektion bringen wir den lokalen Reverse-Proxy (API Proxy) mit Antigravity Tools zum Laufen: Starten des Dienstes, Verbindungsprüfung mit /healthz, dann Verbindung eines SDK für die erste Anfrage.

Was Sie nach dieser Lektion können

Starten/Stoppen des lokalen Reverse-Proxy-Dienstes auf der API Proxy-Seite von Antigravity Tools
Verbindungsprüfung mit GET /healthz durchführen, um "Port richtig, Dienst läuft tatsächlich" zu bestätigen
Das Verhältnis zwischen auth_mode und API Key verstehen: welche Pfade Authentifizierung benötigen, welcher Header mitgeführt werden muss
Wählen Sie einen Client (OpenAI / Anthropic / Gemini SDK) und führen Sie die erste echte Anfrage aus

Ihre aktuelle Herausforderung

Sie haben Antigravity Tools bereits installiert und Konten hinzugefügt, wissen aber nicht, ob der Reverse-Proxy tatsächlich erfolgreich gestartet wurde
Bei der Client-Verbindung treten oft 401 (kein key mitgeführt) oder 404 (Base URL falsch zusammengesetzt/überlappende Pfade) auf
Sie möchten nicht raten, sondern den kürzesten geschlossenen Kreislauf: Start → Verbindungsprüfung → erste erfolgreiche Anfrage

Wann verwenden Sie diese Methode

Sie haben gerade installiert und möchten bestätigen, dass das lokale Gateway extern arbeiten kann
Sie haben den Port geändert, LAN-Zugriff aktiviert oder den Authentifizierungsmodus geändert und möchten schnell überprüfen, ob die Konfiguration nicht fehlerhaft ist
Sie möchten einen neuen Client / neues SDK verbinden und möchten zuerst mit einem minimalen Beispiel zum Laufen bringen

🎒 Vorbereitung vor dem Start

Voraussetzungen

Sie haben die Installation abgeschlossen und können Antigravity Tools normal öffnen.
Sie haben mindestens ein verfügbares Konto; sonst wird beim Starten des Reverse-Proxys ein Fehler zurückgegeben "Kein verfügbares Konto, bitte zuerst Konto hinzufügen" (nur wenn z.ai-Verteilung auch nicht aktiviert ist).

Begriffe, die in dieser Lektion immer wieder auftreten

Base URL: Die "Dienst-Root-Adresse", die der Client anfragt. Die Zusammensetzung unterscheidet sich je nach SDK, manche benötigen /v1, andere nicht.
Verbindungsprüfung (Health Check): Bestätigen Sie die Erreichbarkeit des Dienstes mit einer minimalen Anfrage. Der Verbindungsprüfungsendpunkt dieses Projekts ist GET /healthz, Rückgabe {"status":"ok"}.

Kernkonzept

Wenn Antigravity Tools den Reverse-Proxy startet, wird die Überwachungsadresse und der Port basierend auf der Konfiguration gebunden:
- Bei allow_lan_access=false wird 127.0.0.1 gebunden
- Bei allow_lan_access=true wird 0.0.0.0 gebunden
Sie müssen zuerst keinen Code schreiben. Verwenden Sie zuerst GET /healthz zur Verbindungsprüfung, um "Dienst läuft" zu bestätigen.
Wenn Sie Authentifizierung aktivieren:
- auth_mode=all_except_health nimmt /healthz aus
- auth_mode=strict erfordert API Key für alle Pfade

Machen Sie mit

Schritt 1: Port, LAN-Zugriff und Authentifizierungsmodus bestätigen

Warum Sie müssen zuerst bestätigen "wohin der Client verbinden soll (host/port)" und "ob key mitgeführt werden muss", sonst sind 401/404 später schwer zu beheben.

Öffnen Sie die API Proxy-Seite in Antigravity Tools und achten Sie auf diese 4 Felder:

port: Standard ist 8045
allow_lan_access: Standard deaktiviert (nur lokaler Zugriff)
auth_mode: Wahlweise off/strict/all_except_health/auto
api_key: Standard wird sk-... generiert, und die UI validiert, dass es mit sk- beginnen muss und mindestens 10 Zeichen lang ist

Sie sollten sehen

Oben rechts auf der Seite befindet sich ein Start/Stop-Button (Starten/Stoppen des Reverse-Proxys), das Port-Eingabefeld wird deaktiviert, wenn der Dienst läuft

Empfohlene Konfiguration für Einsteiger (zuerst zum Laufen bringen, dann Sicherheit hinzufügen)

Erstes Laufen: allow_lan_access=false + auth_mode=off
Wenn LAN-Zugriff benötigt wird: zuerst allow_lan_access=true aktivieren, dann auth_mode auf all_except_health umschalten (zumindest nicht das gesamte LAN als "nackte API" freigeben)

Schritt 2: Reverse-Proxy-Dienst starten

Warum Start in der GUI ruft das Backend-Kommando auf, um den Axum-Server zu starten und den Konto-Pool zu laden; dies ist die Voraussetzung dafür, "API nach außen bereitzustellen".

Klicken Sie oben rechts auf der Seite auf Start.

Sie sollten sehen

Status ändert sich von stopped zu running
Daneben wird die Anzahl der aktuell geladenen Konten angezeigt (active accounts)

Wenn der Start fehlschlägt, die häufigsten beiden Fehlerarten

"Kein verfügbares Konto, bitte zuerst Konto hinzufügen": Der Konto-Pool ist leer und z.ai-Verteilung ist nicht aktiviert.
"Starten des Axum-Servers fehlgeschlagen: Adresse <host:port> Bindung fehlgeschlagen: ...": Port belegt oder keine Berechtigung (anderen Port versuchen).

Schritt 3: Mit /healthz Verbindungsprüfung durchführen (kürzester geschlossener Kreislauf)

Warum/healthz ist die stabilste "Erreichbarkeitsbestätigung". Es hängt nicht vom Modell, Konto oder Protokollkonvertierung ab, sondern validiert nur, ob der Dienst erreichbar ist.

Ersetzen Sie <PORT> durch den Port, den Sie in der UI sehen (Standard 8045):

macOS/LinuxWindows

bash

curl -sS "http://127.0.0.1:<PORT>/healthz"

powershell

curl.exe -sS "http://127.0.0.1:<PORT>/healthz"

Sie sollten sehen

json

{"status":"ok"}

Wie testen, wenn Authentifizierung erforderlich ist?

Wenn Sie auth_mode auf strict umschalten, benötigen alle Pfade einen key (einschließlich /healthz).

bash

curl -sS "http://127.0.0.1:<PORT>/healthz" \
  -H "Authorization: Bearer <API_KEY>"

Empfohlene Schreibweise des Authentifizierungs-Headers (kompatibel mit mehr Formen):

Authorization: Bearer <proxy.api_key> oder Authorization: <proxy.api_key>
x-api-key: <proxy.api_key>
x-goog-api-key: <proxy.api_key>

Schritt 4: Ihren ersten Client verbinden (OpenAI / Anthropic / Gemini, wählen Sie eines aus)

Warum/healthz zeigt nur "Dienst erreichbar"; die echte Verbindungserfolgserfolg basiert darauf, dass das SDK eine echte Anfrage startet.

OpenAI SDK (Python)Claude Code / Anthropic CLIGemini SDK (Python)

python

import openai

client = openai.OpenAI(
    api_key="<API_KEY>",
    base_url="http://127.0.0.1:8045/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-flash",
    messages=[{"role": "user", "content": "Hallo, bitte stellen Sie sich vor"}],
)

print(resp.choices[0].message.content)

bash

export ANTHROPIC_API_KEY="<API_KEY>"
export ANTHROPIC_BASE_URL="http://127.0.0.1:8045"
claude

python

import google.generativeai as genai

genai.configure(
    api_key="<API_KEY>",
    transport="rest",
    client_options={"api_endpoint": "http://127.0.0.1:8045"},
)

model = genai.GenerativeModel("gemini-3-flash")
resp = model.generate_content("Hello")
print(resp.text)

Sie sollten sehen

Der Client kann eine nicht-leere Textantwort erhalten
Wenn Sie Proxy Monitor aktiviert haben, sehen Sie auch diesen Anfragedatensatz in der Überwachung

Prüfpunkt ✅

GET /healthz gibt `{"status":"ok"} zurück
API Proxy-Seite zeigt running
Eines der SDK-Beispiele, die Sie gewählt haben, kann Inhalte zurückgeben (nicht 401/404, auch keine leere Antwort)

Warnung vor häufigen Problemen

401: Meistens Authentifizierung nicht abgestimmt

Sie haben auth_mode aktiviert, aber der Client hat keinen key mitgeführt.
Sie haben key mitgeführt, aber der Header-Name ist falsch: Dieses Projekt ist gleichzeitig kompatibel mit Authorization / x-api-key / x-goog-api-key.

404: Meistens Base URL falsch zusammengesetzt oder "überlappende Pfade"

OpenAI SDK benötigt normalerweise base_url=.../v1; während die Beispiele von Anthropic/Gemini ohne /v1 sind.
Manche Clients fügen Pfade doppelt zu ähnlich wie /v1/chat/completions/responses, was zu 404 führt (im Projekt README wurde das Problem der überlappenden Pfade im OpenAI-Modus von Kilo Code speziell erwähnt).

LAN-Zugriff ist nicht "einschalten, fertig"

Wenn Sie allow_lan_access=true aktivieren, bindet der Dienst an 0.0.0.0. Das bedeutet, dass andere Geräte im selben LAN über Ihre Maschinen-IP + Port zugreifen können.

Wenn Sie dies so verwenden möchten, aktivieren Sie mindestens auth_mode und setzen Sie einen starken api_key.

Zusammenfassung dieser Lektion

Nach dem Starten des Reverse-Proxys, zuerst mit /healthz Verbindungsprüfung durchführen, dann SDK konfigurieren
auth_mode bestimmt, welche Pfade einen key benötigen; all_except_health nimmt /healthz aus
Bei der SDK-Verbindung ist das am leichtesten falsch zu machen, ob die Base URL /v1 benötigt

Vorschau auf die nächste Lektion

In der nächsten Lektion klären wir die Details der OpenAI-kompatiblen API: einschließlich der Kompatibilitätsgrenze von /v1/chat/completions und /v1/responses.
Gehen Sie zu OpenAI-kompatible API: Implementierungsstrategie für /v1/chat/completions und /v1/responses.

Anhang: Quellcode-Referenz

Klicken Sie, um Quellcode-Positionen anzuzeigen

Aktualisierungszeit: 2026-01-23

Thema	Dateipfad	Zeilennummer
---	---	---
---	---	---
---	---	---
`/healthz` Rückgabewert	`src-tauri/src/proxy/server.rs`	266-272
---	---	---
---	---	---
---	---	---
---	---	---
---	---	---
---	---	---
README Claude Code / Python Verbindungsbeispiele	`README.md`	197-227

Loslegen

Umgang mit Fehlern

Upgrade Leitfaden

Verbinde deine KI Plattformen

System auf Produktionsniveau bringen

Technisches Wörterbuch

Lokalen Reverse-Proxy starten und ersten Client verbinden (/healthz + SDK-Konfiguration)

Was Sie nach dieser Lektion können

Ihre aktuelle Herausforderung

Wann verwenden Sie diese Methode

🎒 Vorbereitung vor dem Start

Kernkonzept

Machen Sie mit

Schritt 1: Port, LAN-Zugriff und Authentifizierungsmodus bestätigen

Schritt 2: Reverse-Proxy-Dienst starten

Schritt 3: Mit /healthz Verbindungsprüfung durchführen (kürzester geschlossener Kreislauf)

Schritt 4: Ihren ersten Client verbinden (OpenAI / Anthropic / Gemini, wählen Sie eines aus)

Prüfpunkt ✅

Warnung vor häufigen Problemen

Zusammenfassung dieser Lektion

Vorschau auf die nächste Lektion

Anhang: Quellcode-Referenz

Lokalen Reverse-Proxy starten und ersten Client verbinden (/healthz + SDK-Konfiguration) ​

Was Sie nach dieser Lektion können ​

Ihre aktuelle Herausforderung ​

Wann verwenden Sie diese Methode ​

🎒 Vorbereitung vor dem Start ​

Kernkonzept ​

Machen Sie mit ​

Schritt 1: Port, LAN-Zugriff und Authentifizierungsmodus bestätigen ​

Schritt 2: Reverse-Proxy-Dienst starten ​

Schritt 3: Mit /healthz Verbindungsprüfung durchführen (kürzester geschlossener Kreislauf) ​

Schritt 4: Ihren ersten Client verbinden (OpenAI / Anthropic / Gemini, wählen Sie eines aus) ​

Prüfpunkt ✅ ​

Warnung vor häufigen Problemen ​

Zusammenfassung dieser Lektion ​

Vorschau auf die nächste Lektion ​

Anhang: Quellcode-Referenz ​

Lokalen Reverse-Proxy starten und ersten Client verbinden (/healthz + SDK-Konfiguration)

Was Sie nach dieser Lektion können

Ihre aktuelle Herausforderung

Wann verwenden Sie diese Methode

🎒 Vorbereitung vor dem Start

Kernkonzept

Machen Sie mit

Schritt 1: Port, LAN-Zugriff und Authentifizierungsmodus bestätigen

Schritt 2: Reverse-Proxy-Dienst starten

Schritt 3: Mit /healthz Verbindungsprüfung durchführen (kürzester geschlossener Kreislauf)

Schritt 4: Ihren ersten Client verbinden (OpenAI / Anthropic / Gemini, wählen Sie eines aus)

Prüfpunkt ✅

Warnung vor häufigen Problemen

Zusammenfassung dieser Lektion

Vorschau auf die nächste Lektion

Anhang: Quellcode-Referenz