# Einrichtung: Anmeldungen, Regionen und Fernzugriff

> Dieses Kapitel erklärt die getrennten Anmeldungen für HB Code und jeden Agenten, wann die Agentenanmeldung kommt und wo Limits und Nutzung erscheinen. Es erklärt auch optionale API-Schlüssel, eine Region pro Konto, den Fernzugriff-Schalter und die verbundene Vorschau vor HB Code Pro.

Handbuch / Hier starten · Gegen den Quellcode geprüft am 2026-10-05 · https://www.hbcode.ai/de/docs/setup

## Anmeldungen und optionale Schlüssel

**Jede Anmeldung gilt für einen Teil des Wegs vom Telefon zum Modell**

Ein vom Telefon gesendeter Turn läuft über den regionalen Server und die Desktop-App zum Agenten der Session: zum Codex-Kindprozess und weiter zu OpenAI oder zum Claude-Agent-Host und weiter zu Anthropic. Das HB-Code-Konto deckt Telefon, regionalen Server und Desktop-App ab. Das ChatGPT-Konto deckt den Codex-Kindprozess und OpenAI ab, das Claude-Konto den Claude-Host und Anthropic, auch für Turns vom Telefon. Nur Pläne und Nutzungslimits gelangen zurück zum Telefon. Ein optionaler persönlicher API-Schlüssel lässt die Desktop-App OpenAI oder Gemini ohne den Codex-Kindprozess erreichen. Ohne HB-Code-Anmeldung am Desktop erreichen Telefone ihn nicht. Nach der Abmeldung von einem Agenten stoppen nur dessen neue Turns.

- **HB-Code-Konto** (Auth0 · PKCE): Jedes Gerät meldet sich selbst an, beim selben Konto in derselben Region, und der Desktop braucht das Konto nur für den Fernzugriff. Findet ein Telefon den Desktop nicht, prüfen Sie diese Anmeldung und die Region.
- **ChatGPT-Konto** (account/login/start): Der Codex-Kindprozess meldet sich über Ihren Browser an und führt jeden Turn damit aus, auch Turns vom Telefon. Startet der Agent keinen Turn, prüfen Sie diese Anmeldung und ihre Nutzungslimits.
- **Claude-Konto** (claude auth login --claudeai): Claude führt seine eigene Anmeldung im Browser aus und behält die Anmeldedaten, HB Code liest sie nie. Sie können weitere Konten hinzufügen, jedes mit eigener Anmeldung. Wenn ein Claude-Turn nicht startet, prüfen Sie diese Anmeldung und ihre Nutzungslimits.
- **Eigener API-Schlüssel** (openai_api_key · gemini_api_key): Liegt im Schlüsselbund des Desktops, für das Desktop-Diktat und mit einem Gemini-Schlüssel für die Sprach- und Video-Tools. Das Telefon-Diktat nutzt ihn nicht, prüfen Sie ihn also nur, wenn das Desktop-Diktat scheitert.

Codex-Sessions laufen mit einer ChatGPT-Anmeldung. Der Desktop bekommt die Anmeldeadresse vom Codex-Kindprozess und öffnet sie in Ihrem Browser. Der Codex-Kindprozess behält die Zugangsdaten im Home-Ordner seines Profils. Claude-Sessions laufen mit einer Claude-Anmeldung. Der Desktop führt Claudes eigenen Befehl claude auth login --claudeai aus, und Claude öffnet den Browser und behält die Zugangsdaten. HB Code liest keines der beiden Tokens. Das Claude-Standardkonto ist die Claude-Anmeldung, die auf dem Computer schon existiert.

| Schritt der Claude-Anmeldung | Regel |
| --- | --- |
| Anmelden | Es läuft immer nur eine Anmeldung. Ein zweiter Start scheitert mit „Claude sign-in is already running.“ Der Desktop beendet den Befehl nach 600 Sekunden. |
| Abbruch | Der Desktop stoppt den claude-Prozess. Das Konto bleibt abgemeldet. |
| Status und Abmelden | claude auth status --json und claude auth logout haben je ein Limit von 15 Sekunden. |
| Ein Konto entfernen | Der Desktop löscht den Ordner eines hinzugefügten Kontos. War dieses Konto aktiv, wird das Standardkonto aktiv. Das Standardkonto lässt sich nicht entfernen. |

Jedes hinzugefügte Claude-Konto ist ein Ordner unter claude/accounts in den HB-Code-Anwendungsdaten, benannt mit einer UUID. Fünf Einträge bleiben in diesem Ordner privat: .claude.json, .claude.json.lock, .credentials.json, backups und statsig. Jeder andere Eintrag des Claude-Hauptordners ist ein Link, und der Ordner projects mit den Transkripten ist immer geteilt. Der Hauptordner ist ~/.claude oder der Ordner in CLAUDE_CONFIG_DIR, wenn diese Variable gesetzt ist. So liest jedes Konto dieselben Sessions und dieselben Einstellungen, und ein Wechsel ändert nur, welches Konto den nächsten Run bezahlt. Ein Run behält das Konto, das bei seinem Start aktiv war.

- [Codex-Profile und Anmeldung](https://www.hbcode.ai/de/docs/codex-app-server.md#accounts): Das Profilpaar, der Anmeldeablauf und welches Profil eine Session nutzt.
- [Claude-Konten und Nutzung](https://www.hbcode.ai/de/docs/claude-agent-sdk.md#accounts): Kontoordner, Verknüpfungen zum Hauptordner von Claude und das Lesen der Nutzung.

## Agentenanmeldung bei der ersten Session

Der Desktop öffnet ohne Agentenanmeldung. Die Anmeldung kommt, wenn Sie eine neue Session anlegen. Ist der gewählte Agent abgemeldet, öffnet sich ein Anmeldedialog für diesen Agenten, und die Session startet nach der Anmeldung. Schließen Sie den Dialog, wird keine Session angelegt. Eine fortgesetzte Unterhaltung öffnet ohne Anmeldung.

| Zustand des Agenten | Ergebnis |
| --- | --- |
| Der Agent ist angemeldet | Die Session startet sofort. |
| Codex ist abgemeldet | Der Dialog fragt nach der ChatGPT-Anmeldung oder nach der Wahl eines ChatGPT-Kontos, das schon auf diesem Computer ist. |
| Claude ist abgemeldet | Der Dialog fragt nach der Claude-Anmeldung. Der Desktop behält eine bestätigte Claude-Anmeldung, bis sich ein Claude-Konto auf diesem Desktop ändert. |

Der vorgewählte Agent ist der Wert plantocode:new-session-agent:v1 im lokalen Speicher des Desktop-Fensters. Ohne gespeicherten Wert ist die Wahl Codex. Ein HB-Code-Konto ist nicht Teil dieser Anmeldung.

## Limits, Nutzung und Kontowechsel

Auf dem Desktop zeigt Settings → Agents beide Agenten nebeneinander. Jeder Agent hat seine Kontozeilen, die Limit-Anzeigen des aktiven Kontos, eine Detailansicht der Nutzung und Diagramme der Nutzung über die Zeit. Claude meldet ein rollierendes Fünf-Stunden-Fenster und Wochenfenster. Codex meldet ein primäres und ein sekundäres Fenster. Der Desktop speichert jeden frischen Messwert der Fenster für alle Modelle und behält ihn 35 Tage.

| Aufgabe vom Telefon | Methode |
| --- | --- |
| Codex-Profile auflisten | system.codexAuthProfiles |
| Claude-Konten auflisten | system.claudeAccounts. Das Ergebnis enthält die Nutzungsfenster jedes Kontos. |
| Codex-Profil wechseln | system.activateCodexAuthProfile mit profileId |
| Claude-Konto wechseln | system.activateClaudeAccount mit accountId |
| Codex-Limits lesen | system.codexUsageLimits, für das aktive Profil |
| Nutzung über die Zeit lesen | system.agentUsageHistory. Für beide Agenten liefert die Methode die Messwerte des Wochenlimits der letzten 14 Tage. Für Codex liefert sie auch die Tokens pro Tag. |

Der Desktop speichert das aktive Codex-Profil in der Einstellung agent.chat.codex_profile_id und das aktive Claude-Konto in agent.chat.claude_account_id. Ohne Claude-Wert ist das Standardkonto aktiv.

Ein Telefon kann lesen und wechseln. Es kann kein Konto hinzufügen, anmelden, abmelden oder entfernen. Diese Aktionen gibt es nur auf dem Desktop.

- [Agent-Konten vom Telefon aus](https://www.hbcode.ai/de/docs/accounts-and-auth.md#agent-accounts): Die sechs Relay-Methoden, ihre Ergebnisse, die Wechselregeln und die Aktualität jedes Messwerts.
- [Limits pro Agent](https://www.hbcode.ai/de/docs/agents.md#limits): Die Limit-Fenster jedes Agenten, die Messwerte für 60 Sekunden und die Tabelle der gespeicherten Werte.

## Eine Region pro Konto

Ein HB-Code-Konto lebt in einer von zwei Regionen, Vereinigte Staaten oder Europäische Union, jede mit eigenem API-Host, Relay-Prozess, PostgreSQL und Redis. Die Geräteerkennung ist auf ein Konto in einer Region begrenzt, also müssen beide Geräte dieselbe wählen, und ein Regionswechsel auf einem Gerät meldet es zuerst ab. Die Telefone verwenden standardmäßig die Vereinigten Staaten, wenn nichts gespeichert ist.

## Fernzugriff und die Geräteliste

1. Öffnen Sie auf dem Desktop Settings → Connections.
2. Schalten Sie in der Karte Mobile Connection die Option Allow Remote Access ein.
3. Wenn der Desktop nach einem Serverstandort fragt, wählen Sie die Region Ihres HB-Code-Kontos.
4. Wenn der Desktop Sie zur Anmeldung auffordert, melden Sie sich im Browser mit Ihrem HB-Code-Konto an.
5. Notieren Sie den Serverstandort, den die Karte zeigt.
6. Wählen Sie auf dem Telefon dieselbe Region.
7. Melden Sie sich mit demselben HB-Code-Konto an.
8. Wählen Sie Ihren Desktop in der Geräteliste.
9. Wählen Sie ein Projekt und eine Session.

**Ein Desktop in der Liste antwortet nicht immer**

Vier Beispiel-Desktops durchlaufen von oben nach unten drei Prüfungen. Die Geräteliste zeigt jeden Desktop mit einer Gerätezeile in der Region des Kontos, verbunden oder nicht. Ein Desktop antwortet nur, solange der Socket lebt, den er zum Relay geöffnet hat. Ein wacher Desktop beantwortet den Ping des Telefons, und das Telefon lädt Projekte, Sessions und die Timeline. Ein Laptop mit zugeklapptem Deckel bleibt als online gelistet, bis das Relay seinen stummen Socket nach etwa 3 Minuten trennt, zählt dann 90 Sekunden als reconnecting und danach als offline. Ein Desktop, dessen Fernzugriff-Schalter ausgeschaltet wurde, bleibt in der Liste, ist aber sofort offline. Ein Desktop in einer anderen Region oder einem anderen Konto steht nicht in der Liste.

- **Gerätezeile** (POST /api/devices/register): Wird mit X-Client-Type: desktop angelegt, wenn der Fernzugriff zum ersten Mal eingeschaltet ist, in der Region, die der Desktop gewählt hat. Ruhezustand und Schalter lassen sie bestehen, daher bleibt der Desktop gelistet.
- **Desktop-Socket** (/ws/device-link): Der Desktop baut die Verbindung zum Relay selbst auf, und Telefone verbinden sich nie direkt mit dem Computer. Ein stummer Socket wird nach etwa 3 Minuten getrennt und zählt 90 s als reconnecting, das Ausschalten des Schalters schließt ihn dagegen sofort.
- **Ping** (system.ping): Das Telefon öffnet einen eigenen Socket für diesen Desktop und pingt über das Relay. Erst eine Antwort lässt es Projekte, Sessions und die Timeline laden.

Die Geräte-UUID im WebSocket-register muss zu Besitzer und Rolle der Zeile passen. Der Schalter braucht einen gewählten Serverstandort und eine HB-Code-Anmeldung. Diese Anmeldung existiert nur für den Fernzugriff, und jede andere Desktop-Funktion arbeitet ohne Konto. Eine beeinträchtigte gespeicherte Anmeldung pausiert die mobile Verbindung.

## Die verbundene Vorschau und HB Code Pro

Das erste Telefon eines Kontos, das einen Desktop erreicht, startet eine 10-tägige verbundene Vorschau für das ganze Konto. Danach braucht jedes Telefon HB Code Pro, gekauft über den App Store oder Google Play für seine Plattform. Das Abonnement deckt nur das Telefon ab. Programmieren auf dem Desktop braucht nichts außer der eigenen Anmeldung des Agenten, und ein iPhone-Abonnement schaltet weder Android frei noch umgekehrt.

**Ein Vorschauzeitraum gilt für das Konto, und Sie kaufen Pro für jede Telefonplattform einzeln**

Ein Beispielkonto mit einem iPhone und einem Android-Telefon. Das iPhone bekommt an Tag 0 die erste Antwort eines Desktops, und der regionale Server schreibt einen Vorschau-Datensatz, der nach der Datenbankuhr 10 Tage später endet. Das Android-Telefon erreicht an Tag 4 zum ersten Mal einen Desktop und bekommt denselben Datensatz, seine Vorschau endet also ebenfalls an Tag 10. Danach läuft das iPhone mit einem App-Store-Abonnement, das das Android-Telefon nicht freischaltet, und das Android-Telefon braucht ein eigenes Google-Play-Abonnement, hier an Tag 12 gekauft. Der Datensatz bleibt abgelaufen und startet nie neu.

- **Vorschau-Datensatz** (account_workspace_previews): Wird geschrieben, wenn ein Telefon des Kontos zum ersten Mal eine Antwort von einem Desktop bekommt, mit started_at nach der Datenbankuhr und expires_at 10 Tage später. Spätere Telefone bekommen denselben Datensatz, und der Server kann ihn weder ändern noch löschen.
- **Identitätsschlüssel** (HMAC-SHA256): Der Datensatz liegt unter schlüsselbasierten Hashes des Auth0-Subjects und der verifizierten E-Mail, die miteinander verknüpft sind. Eine Abfrage folgt den Verknüpfungen und nimmt den frühesten Start.
- **HB Code Pro** (StoreKit · Google Play): Wird je Plattform gekauft. Das iPhone prüft StoreKit auf dem Gerät, und Android schickt den Kauf zur Prüfung an den regionalen Server. Keines schaltet das andere frei.

Der Server speichert die Vorschau unter schlüsselbasierten Hashes des Auth0-Subjects und der verifizierten E-Mail und zählt die 10 Tage ab Datenbankzeit.

> **Plattformvoraussetzungen** iPhone mit iOS 18 oder neuer. Android 8.0 oder neuer. Chrome 120 oder neuer für die Browser-Bridge-Erweiterung. Ein Mac- oder Windows-Computer, der wach bleibt, solange ein Telefon verbunden ist, denn auf dem Desktop läuft alles.

- [iOS: StoreKit, die verbundene Vorschau und Push](https://www.hbcode.ai/de/docs/ios/media.md#purchases): Wie Käufe auf dem Gerät geprüft werden.
- [Android: Google Play Billing und die verbundene Vorschau](https://www.hbcode.ai/de/docs/android/media.md#billing): Wie der regionale Server einen Kauf prüft.