---

## Interne Codex-Integration ohne oeffentliche Gateway-Exposition

**Stand:** 2026-05-23
**Grundlage:** Analyse des Hermes-Source-Codes im Container (/opt/hermes/)
**Ergebnis:** Integration moeglich — zwei Pfade, ein klarer Empfehlung

---

### 10.1 Zielarchitektur (intern)

```
Hermes Workspace (Browser-UI)
        |
        v  HTTP API (Port 3010/8642 intern)
Hermes Agent Container (hermes-carlo)
        |
        +-- LLM-Aufruf: GPT-5.5 via Provider-Adapter
        |
        +-- MCP gateway-read: POST http://hermes-gateway:8000/...
        |     (Docker-internes Netz struktur-net)
        |
        v
Hermes Tool Gateway (hermes-gateway, 127.0.0.1:8645)
        |
        v
VPS: Dateisystem / Docker / Obsidian / Graphiti
```

Gateway bleibt intern. Kein oeffentlicher Endpunkt. Keine Firewall-Aenderung.

---

### 10.2 Wie Hermes aktuell Sonnet 4.6 / DeepSeek anbindet

**Aktuelle Konfiguration (config.yaml):**
```yaml
model:
  default: deepseek-chat
  provider: custom
  base_url: https://api.deepseek.com/v1
```

**Was das bedeutet:**
- `provider: custom` = kein eingebauter Provider-Alias, direkte URL-Verbindung
- Transport: `openai_chat` (Chat Completions Format — OpenAI-kompatibel)
- API-Key: `DEEPSEEK_API_KEY` im Container-Env gesetzt
- DeepSeek spricht OpenAI-kompatible Chat Completions API → kein Format-Umbau noetig

**Delegation (Sub-Agents):**
```yaml
delegation:
  model: deepseek/deepseek-v3.2
  provider: openrouter
```
Sub-Agents laufen via OpenRouter (separater Key: OPENROUTER_API_KEY im Env)

---

### 10.3 Provider-Adapter Architektur (Hermes intern)

Hermes kennt drei Transport-Protokolle:

| Transport | API-Format | Genutzt fuer |
|---|---|---|
| `openai_chat` | OpenAI Chat Completions (`/v1/chat/completions`) | DeepSeek, Llama, OpenRouter, LiteLLM, Kimi, etc. |
| `anthropic_messages` | Anthropic Messages API | Claude direkt, MiniMax /anthropic |
| `codex_responses` | OpenAI Responses API (`/v1/responses`) | GPT-5.x via api.openai.com, xAI, openai-codex OAuth |

**Auto-Detection:** Hermes erkennt `api.openai.com` in der base_url → setzt automatisch `codex_responses`

**Provider-Aliase (relevant):**
```
"openai"  →  Alias fuer "openrouter"  (nicht direktes api.openai.com!)
"openai-codex"  →  OAuth-Flow via chatgpt.com/backend-api/codex (ChatGPT Pro)
```

**Achtung:** `provider: openai` in config.yaml leitet durch OpenRouter, nicht direkt zu OpenAI.

---

### 10.4 Drei Integrationspfade fuer GPT-5.5

#### Pfad A: GPT-5.5 direkt via OpenAI API

**Konfiguration:**
```yaml
model:
  default: gpt-5.5
  provider: custom
  base_url: https://api.openai.com/v1
```
Env: `OPENAI_API_KEY=<key>` (aktuell leer im Container)

**Was Hermes macht:**
- Erkennt `api.openai.com` → setzt Transport auf `codex_responses` (Responses API)
- Responses API hat anderen Request-/Response-Shape als Chat Completions
- Tool-Call-Format unterscheidet sich strukturell

**Risiko:** HOCH
- `codex_responses` ist ein anderer Transport als der aktuelle `openai_chat`
- System-Prompts und Retrieval-Pipeline sind fuer Chat-Completions-Format optimiert
- Tool-Call-Handling unter `codex_responses` ist in dieser Hermes-Instanz ungetestet
- Streaming-Format unterscheidet sich (Responses API SSE vs Chat Completions SSE)

**Aufwand:** Mittel — Konfiguration einfach, aber Transport-Unterschiede erfordern Tests

#### Pfad B: GPT-5.5 via LiteLLM-Proxy (auf VPS, bereits deployed)

**Vorteil:** LiteLLM laeuft bereits als Container (`litellm`, Port 4000)
LiteLLM uebersetzt intern zwischen Chat Completions (Eingang) und Responses API (Ausgang)

**Konfiguration LiteLLM** (Ergaenzung in /opt/struktur/litellm/config.yaml):
```yaml
- model_name: gpt-5.5
  litellm_params:
    model: openai/gpt-5.5
    api_key: os.environ/OPENAI_API_KEY
```

**Hermes config.yaml:**
```yaml
model:
  default: gpt-5.5
  provider: custom
  base_url: http://litellm:4000
```

**Was Hermes macht:**
- LiteLLM-URL (`litellm:4000`) wird nicht als `api.openai.com` erkannt
- Transport bleibt `openai_chat` (Chat Completions) — keine Format-Aenderung
- LiteLLM uebernimmt die API-Format-Translation transparent

**Risiko:** NIEDRIG
- Hermes-Transport unveraendert
- Retrieval-Pipeline, System-Prompts, Tool-Calls: keine Anpassung
- LiteLLM-Kompatibilitaet mit GPT-5.5 Responses API muss geprueft werden (LiteLLM unterstuetzt es)

**Aufwand:** Gering — 3 Zeilen in LiteLLM config + 2 Zeilen in Hermes config

#### Pfad C: openai-codex OAuth (ChatGPT Pro)

**Was es ist:** Hermes nutzt OAuth-Flow via `chatgpt.com/backend-api/codex`
Gibt Zugang zu gpt-5.3-codex-spark (ChatGPT Pro exklusiv)

**Voraussetzung:** ChatGPT Pro Subscription + einmaliger Browser-OAuth-Flow
**Transport:** `codex_responses` (selbes Risiko wie Pfad A)
**Risiko:** HOCH — OAuth-Token lauft ab, schwer zu automatisieren

**Aufwand:** Hoch

---

### 10.5 Modellneutrale Komponenten (bereits kompatibel)

| Komponente | Status | Begruendung |
|---|---|---|
| Hermes Workspace UI | kompatibel | Modell-agnostisch, spricht Hermes Gateway API |
| Tool-Gateway (127.0.0.1:8645) | kompatibel | Reines HTTP, kein Modellbezug |
| MCP gateway-read Server | kompatibel | stdio-MCP, unabhaengig vom LLM |
| Retrieval-Pipeline (Obsidian + Graphiti) | kompatibel | HTTP-Calls, modellneutral |
| Audit-Logging | kompatibel | agent-Feld, nicht modellabhaengig |
| Session-Memory Layer | kompatibel | Gateway HTTP-Endpunkte, modellneutral |
| config.yaml Struktur | kompatibel | model.default / provider / base_url unveraendert |
| Docker-Netzwerk (struktur-net) | kompatibel | Container-Namen unveraendert |
| CODEX_GATEWAY_KEY | kompatibel | Bereits implementiert |

---

### 10.6 Modellabhaengige Komponenten (Anpassung noetig)

| Komponente | Anpassung | Aufwand | Pfad |
|---|---|---|---|
| `model.default` in config.yaml | deepseek-chat → gpt-5.5 | Minimal | A, B, C |
| `model.base_url` in config.yaml | deepseek API → OpenAI/LiteLLM | Minimal | A, B |
| `OPENAI_API_KEY` im Container | aktuell leer — muss gesetzt werden | Minimal | A, B |
| `delegation.provider` | openrouter → angepasst | Minimal | A, B |
| Transport-Handling | openai_chat vs codex_responses | Mittel (nur Pfad A, C) | A, C |
| System-Prompts (Personalities) | DeepSeek-optimiert → GPT-5.5 anpassen | Klein | A, B, C |
| Tool-Call-Format in Prompts | Chat Completions Format | Kein Umbau bei Pfad B | B |
| LiteLLM config.yaml | GPT-5.5 Modell-Eintrag ergaenzen | Minimal | B |

---

### 10.7 Konkrete Unterschiede Claude / DeepSeek ↔ GPT-5.5

| Aspekt | DeepSeek (aktuell) | GPT-5.5 |
|---|---|---|
| API-Format | Chat Completions (OpenAI-kompatibel) | Responses API (neu, strukturell anders) |
| Transport in Hermes | `openai_chat` | `codex_responses` (direkt) oder `openai_chat` (via LiteLLM) |
| Tool-Calls | `tool_calls` Array in Chat Completions | `tool_use` in Responses API (andere Struktur) |
| Streaming | SSE `data: {"choices":[...]}` | SSE mit anderen Event-Typen in Responses API |
| Kontextfenster | 128k (deepseek-chat) | offen (Eintrag in Hermes Models-Katalog leer) |
| Systemrolle | `system` Message | `developer` Role in Responses API (!)  |
| Reasoning | deepseek-reasoner separates Modell | integriert in GPT-5.5 |
| Kosten | Sehr guenstig (direkt DeepSeek) | Teurer — Pricing noch nicht veroeffentlicht |

**Kritischer Unterschied:**
GPT-5.5 ueber `api.openai.com` verwendet die **Responses API**, nicht Chat Completions.
Die Responses API hat eine andere `system`-Rolle (`developer`), andere Tool-Call-Struktur, und
andere Streaming-Chunks. Hermes' `codex_responses` Transport handhabt das — aber dieser
Pfad ist in dieser Instanz ungetestet.

Via LiteLLM (Pfad B) wird diese Komplexitaet versteckt.

---

### 10.8 Gateway-Zugriff: bereits lokal moeglich

**Aktueller Stand:**
- Gateway laeuft auf `hermes-gateway:8000` im Docker-Netz `struktur-net`
- MCP Server `/opt/struktur/hermes-carlo/gateway-mcp/server.py` laeuft im hermes-carlo Container
- Verbindung: Container `hermes-carlo` → `http://hermes-gateway:8000` (intern, kein Port nach aussen)
- Auth: GATEWAY_API_KEY wird aus `/opt/struktur/hermes-gateway/.env` geladen

**Was das fuer Codex bedeutet:**
Wenn GPT-5.5 als Modell in Hermes laeuft, nutzt es denselben internen Gateway-Pfad.
Kein neuer Zugriffspfad noetig. Gateway bleibt vollstaendig intern.

**Audit:**
`agent`-Feld im Log bleibt `hermes-carlo` — weil der MCP-Server den Hermes-Key verwendet.
Wenn Codex als eigenstaendiger Aufrufer (eigener Key) kommen soll, muss CODEX_GATEWAY_KEY
in den Gateway-Aufrufen des MCP-Servers gesetzt werden — das ist eine sppaetere optionale Anpassung.

---

### 10.9 Zusammenfassung: Was muss angepasst werden

**Pfad B (LiteLLM) — empfohlener erster Schritt:**

| Datei | Aenderung |
|---|---|
| `/opt/struktur/litellm/config.yaml` | GPT-5.5 Modell-Eintrag + OPENAI_API_KEY Referenz |
| `/opt/struktur/hermes-carlo/data/config.yaml` | model.default=gpt-5.5, base_url=http://litellm:4000 |
| `/opt/struktur/hermes-gateway/.env` (LiteLLM-Seite) | OPENAI_API_KEY setzen |
| `hermes-carlo` Container | OPENAI_API_KEY als Env-Var verfuegbar machen |

Kein Transport-Umbau. Kein Tool-Call-Format-Umbau. Kein neuer Container.

---

### 10.10 Groesstes technisches Risiko

**Responses API vs Chat Completions (bei Pfad A / C):**
GPT-5.5 direkt via api.openai.com spricht die Responses API.
Hermes' `codex_responses` Transport handhabt das technisch — aber:
- System-Prompts muessen `developer` Role verwenden statt `system`
- Tool-Call-Definitionen haben andere JSON-Struktur
- Streaming-Handler ist anders

**Via LiteLLM (Pfad B) entfaellt dieses Risiko vollstaendig.**

**Zweitgroesstes Risiko:**
GPT-5.5 Modell-Verfuegbarkeit und Kosten sind noch nicht vollstaendig dokumentiert.
Der Hermes-interne Models-Katalog hat fuer `openai/gpt-5.5` keine Kontextlaengen-Angabe.
Vor Produktivbetrieb: Kontextlimit pruefen und ggf. in config.yaml begrenzen.

---

### 10.11 Geschaetzter Umbauaufwand

| Pfad | Aufwand | Risiko | Empfehlung |
|---|---|---|---|
| B (LiteLLM Proxy) | 30-60 Minuten | Niedrig | Erster Schritt |
| A (OpenAI direkt) | 2-4 Stunden + Tests | Hoch | Erst nach Pfad B validiert |
| C (OAuth ChatGPT Pro) | 4+ Stunden | Sehr hoch | Nur fuer Pro-Modelle noetig |

---

### 10.12 Naechster einzelner Schritt (nach Entscheidung)

**Wenn Pfad B freigegeben:**
1. OPENAI_API_KEY besorgen und in `/opt/struktur/litellm/docker-compose.yml` Env setzen
2. GPT-5.5 Eintrag in `/opt/struktur/litellm/config.yaml` ergaenzen
3. LiteLLM Container neu starten
4. Test: `curl http://127.0.0.1:4000/v1/models` pruefen ob gpt-5.5 erscheint
5. Danach: Hermes config.yaml anpassen und Funktionstest

Kein Umbau bis zur expliziten Freigabe.