# Claude Code erweitern: Fremde Modelle routen & Codex als zweiten Agenten nutzen

**Unterrichtsmaterial** · Modul „Konzeption KI" / Agentic AI
**Format:** Handoff für Claude AI Design · frei teilbar mit Kursteilnehmenden
**Umfang:** zwei aufeinander aufbauende Einheiten (je ca. 90 Min.)

---

## Über dieses Dokument

Dieses Material besteht aus zwei Teilen, die eigenständig unterrichtet oder kombiniert
werden können:

- **Teil 1 – Modell-Routing:** Wie man Claude Code auf einen anderen Anbieter (hier
  GLM-5.2 über Z.ai) umleitet, sodass die gewohnten Tiers wie *Opus* auf ein fremdes
  Modell zugreifen.
- **Teil 2 – Codex-Plugin:** Wie man mit `openai/codex-plugin-cc` einen zweiten,
  unabhängigen Coding-Agenten (Codex) in Claude Code einbindet.

Der rote Faden beider Teile: **Claude Code ist offen.** Man kann das *Modell dahinter*
austauschen (Teil 1) und *zusätzliche Agenten* daneben stellen (Teil 2). Beide Techniken
sind unabhängig voneinander und lassen sich sogar gleichzeitig nutzen.

> **Wichtiger Zusammenhang für die Teilnehmenden:** Biegt man Claude Code per Routing
> auf GLM um, läuft *nur Claude Code* über GLM. Das Codex-Plugin nutzt weiterhin die
> separate Codex-Anmeldung und OpenAI-Modelle. Die beiden Wege stören sich nicht — sind
> aber getrennt abzurechnen.

---

## Gemeinsame Lernziele

Nach beiden Einheiten können die Teilnehmenden:

1. erklären, wie Claude Code über Umgebungsvariablen konfiguriert wird;
2. Claude Code auf einen Anthropic-kompatiblen Fremd-Endpoint umleiten;
3. die Tier-Aliase (opus/sonnet/haiku) auf beliebige Modelle mappen;
4. ein Plugin über den Marketplace installieren und einrichten;
5. einen zweiten Agenten für Reviews und delegierte Aufgaben einsetzen;
6. Risiken beider Ansätze benennen (Kosten, Datenpfade, Agent-Loops, Vertrauensgrenzen).

---
---

# TEIL 1 — Fremde Modelle in Claude Code routen (Beispiel GLM-5.2)

## 1.1 Das Grundprinzip

Claude Code spricht standardmäßig `api.anthropic.com`. Über den `env`-Block in einer
Settings-Datei lässt sich dieser Ziel-Endpoint komplett umbiegen. Inzwischen bieten
mehrere Anbieter einen **Anthropic-kompatiblen Endpoint** an — neben Z.ai (Zhipu AI,
GLM-Familie) etwa auch Moonshot mit Kimi und MiniMax. Bei ihnen funktioniert das
Routing ohne Zusatz-Proxy als echter Drop-in-Ersatz. GLM-5.2 dient hier als Beispiel;
Kimi oder MiniMax bindet man über dieselben `env`-Variablen ein — man tauscht nur
Basis-URL und Modell-IDs (z. B. `https://api.z.ai/api/anthropic` für Z.ai).

**Der zentrale Trick:** Claude Code kennt intern nur die *Tier-Aliase* `opus`, `sonnet`
und `haiku`. Über die Variablen `ANTHROPIC_DEFAULT_*_MODEL` mappt man jedes Tier auf ein
konkretes GLM-Modell. Wählt man dann im CLI `/model opus`, geht der Request in Wahrheit
an `glm-5.2`.

```
   Du (im Terminal)
        │
        ▼
   Claude Code ──ANTHROPIC_BASE_URL──►  api.z.ai/api/anthropic
        │                                     │
   /model opus                          übersetzt Anfrage
        │                                     ▼
   mappt über                            GLM-5.2 antwortet
   ANTHROPIC_DEFAULT_OPUS_MODEL          im Anthropic-Format
```

## 1.2 Voraussetzungen

| Voraussetzung | Details |
|---|---|
| Z.ai-Account | Registrierung auf der Z.ai Open Platform |
| API-Key | im Bereich „API Keys" erzeugen |
| Coding-Plan | Abo für GLM-Coding-Zugang (Quota-basiert; GLM-5.2 inklusive) |
| Claude Code | aktuell installiert |

## 1.3 Schritt für Schritt

**Schritt 1 — API-Key besorgen.** Bei der Z.ai Open Platform registrieren, unter
„API Keys" einen Key erzeugen und kopieren.

**Schritt 2 — Settings-Datei öffnen.**
- *Projektbezogen* (empfohlen für Keys): `.claude/settings.local.json` im Repo-Root.
  Diese Datei wird per Default von Git ignoriert.
- *Maschinenweit:* `~/.claude/settings.json`.

**Schritt 3 — `env`-Block eintragen** (offizielle Z.ai-Konfiguration):

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "DEIN_ZAI_API_KEY",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "3000000"
  }
}
```

**Schritt 4 — Claude Code vollständig neu starten.** Umgebungsvariablen werden nur
*einmal beim Prozessstart* gelesen. Einen Tab neu öffnen genügt nicht — den Prozess
komplett beenden und `claude` frisch starten.

**Schritt 5 — Verifizieren.**
- `echo $ANTHROPIC_BASE_URL` → muss `https://api.z.ai/api/anthropic` ausgeben.
- Im CLI `/model` prüfen → sollte `glm-5.2` / `GLM-5.2` zeigen, keinen Claude-Fallback.
- Identity-Probe: „What model are you?" → GLM-5.2 identifiziert sich korrekt. Sagt es
  „Claude", ist das Routing falsch.

## 1.4 Was die Felder bedeuten

| Feld | Funktion |
|---|---|
| `ANTHROPIC_AUTH_TOKEN` | Bearer-Token für den Gateway. **Bei Z.ai zwingend hier**, nicht in `ANTHROPIC_API_KEY`. |
| `ANTHROPIC_BASE_URL` | Biegt sämtlichen Traffic auf den fremden Endpoint um. |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Tier *haiku* → günstiges `glm-4.7`. |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Tier *sonnet* → `glm-5.2[1m]` (1-Mio-Kontext). |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Tier *opus* → `glm-5.2[1m]`. |
| `API_TIMEOUT_MS` | Hochgesetzt, weil GLM langsamer antwortet und Agent-Loops sonst timeouten. |

## 1.5 Häufige Fehler (für den Unterricht)

- **Falsche Key-Variable:** Z.ai erwartet `ANTHROPIC_AUTH_TOKEN`, nicht
  `ANTHROPIC_API_KEY`. Häufigster Anfängerfehler.
- **Falscher Pfad in der URL:** Der Anthropic-kompatible Pfad ist `/api/anthropic` —
  nicht der generische OpenAI-Pfad.
- **Prozess nicht neu gestartet:** Änderung greift erst nach vollständigem Neustart.
- **Konkurrierende Anmeldung:** Ein aktives Claude-Max-Login oder eine
  `ANTHROPIC_API_KEY` in der Shell kann Vorrang bekommen. Mit `/status` prüfen, welche
  Route aktiv ist.
- **Key im Git:** `.claude/settings.local.json` unbedingt in `.gitignore` belassen.

## 1.6 Tipp: sauberes Umschalten

Wer zwischen GLM und dem normalen Claude wechseln will, legt statt globalem Umbiegen
besser eine separate Shell-Funktion an — dann ist immer klar, welcher Anbieter in
welchem Terminal aktiv ist (und bezahlt wird):

```bash
# in ~/.zshrc oder ~/.bashrc
claude-zai() {
  ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" \
  ANTHROPIC_AUTH_TOKEN="$Z_AI_API_KEY" \
  claude "$@"
}
```
Dann `claude-zai` für GLM und normales `claude` für Anthropic.

## 1.7 Diskussionsfragen (Teil 1)

1. Warum funktioniert das Routing bei Z.ai *ohne* Proxy, bei vielen anderen Anbietern
   aber nur über einen Gateway wie OpenRouter?
2. Was ist der Unterschied zwischen `ANTHROPIC_AUTH_TOKEN` und `ANTHROPIC_API_KEY`?
3. Welche Datenschutz-Frage stellt sich, wenn Code an einen Endpoint in einem anderen
   Rechtsraum geht?
4. Warum mappt man *haiku* bewusst auf ein günstigeres Modell als *opus*?

---
---

# TEIL 2 — Codex als zweiten Agenten einbinden (`openai/codex-plugin-cc`)

**Repository:** `openai/codex-plugin-cc` · Lizenz Apache-2.0 · Sprache JavaScript

## 2.1 Worum geht es?

Claude Code ist Anthropics agentisches Coding-Tool. Codex ist das Gegenstück von OpenAI.
Beide sind eigenständige Agenten mit eigenem CLI, eigener Anmeldung und eigenen Modellen.

Das Plugin `codex-plugin-cc` verbindet beide: Es lässt sich **Codex aus Claude Code
heraus** aufrufen — um den eigenen Code von einer zweiten, unabhängigen Instanz prüfen
zu lassen, oder um ganze Aufgaben an Codex abzugeben.

**Didaktische Kernidee — „Second Opinion" unter Agenten:** So wie man Code von einem
menschlichen Kollegen reviewen lässt, holt man hier das Urteil eines *anderen* Modells
ein. Ein zweiter Agent, der die Annahmen des ersten nicht teilt, findet oft Fehler, die
der ursprüngliche Autor (Mensch oder KI) übersieht.

> **Merksatz:** Das Plugin startet *keine* zweite KI-Runtime. Es ruft die lokal
> installierte Codex-CLI auf derselben Maschine auf — gleiche Installation, gleiche
> Anmeldung, gleicher Repo-Checkout. Claude Code ist nur die Fernbedienung.

## 2.2 Architektur

```
   Du (im Terminal)
        │
        ▼
   Claude Code  ──ruft──►  codex-plugin-cc  ──wrappt──►  Codex App Server
                             (Slash-Commands)                │
                                                             ▼
                                                    lokale Codex-CLI
                                                    (gleiche Anmeldung,
                                                     gleiche config.toml)
```

Konsequenzen:
- **Eine Anmeldung genügt:** Wer schon bei Codex eingeloggt ist, kann sofort loslegen.
- **Geteilte Konfiguration:** Das Plugin liest dieselbe `config.toml` wie Codex direkt.
- **Nutzung zählt auf Codex-Kontingent**, nicht auf das von Claude.

## 2.3 Voraussetzungen

| Voraussetzung | Details |
|---|---|
| Codex-Zugang | ChatGPT-Abo (auch Free) **oder** OpenAI-API-Key |
| Node.js | Version 18.18 oder neuer |
| Claude Code | mit Plugin-/Marketplace-Unterstützung |

## 2.4 Installation — Schritt für Schritt

**Schritt 1 — Marketplace hinzufügen**
```
/plugin marketplace add openai/codex-plugin-cc
```

**Schritt 2 — Plugin installieren**
```
/plugin install codex@openai-codex
```

**Schritt 3 — Plugins neu laden**
```
/reload-plugins
```

**Schritt 4 — Setup-Check**
```
/codex:setup
```
Prüft, ob Codex installiert und angemeldet ist. Fehlt Codex und ist npm verfügbar,
bietet das Setup an, Codex zu installieren.

**Manuelle Codex-Installation (optional):**
```
npm install -g @openai/codex
```

**Anmeldung (falls nötig):**
```
!codex login
```
> Das vorangestellte `!` führt einen Shell-Befehl direkt aus Claude Code heraus aus.

**Erfolgskontrolle:** Danach sind die Slash-Commands sichtbar und der Subagent
`codex:codex-rescue` taucht unter `/agents` auf.

## 2.5 Befehlsreferenz — die sieben Commands (Handout)

| Command | Zweck | Verändert Code? | Steuerbar? |
|---|---|---|---|
| `/codex:review` | Normales Read-only-Review der aktuellen Arbeit | Nein | Nein |
| `/codex:adversarial-review` | Kritische Prüfung von Design & Annahmen | Nein | Ja (Fokustext) |
| `/codex:rescue` | Aufgabe an Codex delegieren (Bug, Fix, Fortsetzung) | Ja | Ja |
| `/codex:transfer` | Claude-Session als Codex-Thread fortführen | — | — |
| `/codex:status` | Laufende & letzte Codex-Jobs anzeigen | Nein | — |
| `/codex:result` | Endergebnis eines fertigen Jobs abrufen | Nein | — |
| `/codex:cancel` | Aktiven Hintergrund-Job abbrechen | Nein | — |

### `/codex:review` — die zweite Meinung
Review der aktuellen, uncommitteten Änderungen. Branch-Vergleich mit `--base <ref>`.
```
/codex:review
/codex:review --base main
/codex:review --background
```
*Lehrpunkt:* Multi-Datei-Reviews dauern → im Hintergrund laufen lassen und mit
`/codex:status` / `/codex:result` einsammeln.

### `/codex:adversarial-review` — der Advocatus Diaboli
**Steuerbare** Prüfung, die die gewählte Umsetzung hinterfragt: Annahmen, Trade-offs,
Fehlermodi, Alternativen. Nach den Flags folgt freier Fokustext.
```
/codex:adversarial-review --base main challenge whether this was the right caching and retry design
/codex:adversarial-review --background look for race conditions and question the chosen approach
```
*Didaktischer Kontrast:* `review` = „Ist der Code korrekt?" · `adversarial-review` =
„War das überhaupt der richtige Weg?"

### `/codex:rescue` — Arbeit abgeben
Übergibt eine Aufgabe über den Subagenten `codex:codex-rescue`. Flags: `--background`,
`--wait`, `--resume`, `--fresh`, `--model`, `--effort`.
```
/codex:rescue investigate why the tests started failing
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
/codex:rescue --resume apply the top fix from the last run
```
Auch in natürlicher Sprache delegierbar:
```
Ask Codex to redesign the database connection to be more resilient.
```
*Hinweise:* Ohne `--model`/`--effort` wählt Codex Defaults. `spark` mappt auf
`gpt-5.3-codex-spark`. Folge-Anfragen setzen den letzten Task im Repo fort.

### `/codex:transfer` — Kontext mitnehmen
Erzeugt aus der aktuellen Claude-Session einen persistenten Codex-Thread und gibt
`codex resume <session-id>` aus. Sinnvoll, um eine begonnene Debug-Konversation mit
demselben Kontext in Codex fortzuführen. Quelle muss unter `~/.claude/projects` liegen.

### Job-Management: `status`, `result`, `cancel`
```
/codex:status              # läuft der Job noch?
/codex:result              # Endergebnis abrufen (inkl. Codex-Session-ID)
/codex:cancel task-abc123  # Abbruch eines konkreten Jobs
```

## 2.6 Typische Abläufe

**Review vor dem Ausliefern**
```
/codex:review
```
**Ein Problem an Codex abgeben**
```
/codex:rescue investigate why the build is failing in CI
```
**Langlaufendes starten und später abholen**
```
/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test
/codex:status
/codex:result
```

## 2.7 Das Review-Gate — fortgeschritten & mit Vorsicht

```
/codex:setup --enable-review-gate
/codex:setup --disable-review-gate
```
Ist das Gate aktiv, hängt sich das Plugin über einen `Stop`-Hook in Claudes Antwort ein
und lässt Codex ein gezieltes Review laufen. Findet Codex Probleme, wird der Stopp
**blockiert**, bis Claude sie behoben hat.

> **Warnung:** Das Gate kann eine langlaufende Claude-↔-Codex-Schleife erzeugen und das
> Usage-Limit schnell aufbrauchen. Nur aktivieren, wenn man die Session aktiv beobachtet.

Guter Anlass, **Agent-Loops und Kostenkontrolle** zu thematisieren.

## 2.8 Konfiguration

Reasoning-Effort und Standardmodell steuert man über Codex' `config.toml`:
```toml
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
```
Ladereihenfolge: User-Ebene `~/.codex/config.toml` → Projekt-Ebene
`.codex/config.toml` (nur wenn das Projekt *trusted* ist). Ein alternativer Endpoint
lässt sich über `openai_base_url` setzen.

## 2.9 Diskussionsfragen (Teil 2)

1. Warum liefert ein *anderes* Modell beim Review oft bessere Ergebnisse als das Modell,
   das den Code geschrieben hat?
2. Wann ist `adversarial-review` sinnvoller als `review`? Nenne zwei Fälle.
3. Was bedeutet es für Datenschutz und Kosten, dass das Plugin die *lokale* Codex-CLI
   und deren Anmeldung nutzt?
4. Erkläre den Unterschied zwischen `--wait` und `--background`.
5. Welche Gefahr birgt das Review-Gate und wie grenzt man sie ein?

---
---

# Abschluss-Praxisaufgabe (verbindet Teil 1 & 2)

**Ziel:** Beide Techniken in einem realistischen Ablauf erleben.

1. Ein kleines Repo klonen und auf einem Branch einen subtilen Bug einbauen
   (z. B. Off-by-one oder Race Condition).
2. **Teil 1:** Claude Code per `.claude/settings.local.json` auf GLM-5.2 routen und mit
   `/model` sowie einer Identity-Probe verifizieren.
3. Den Bug mit dem GLM-gerouteten Claude Code untersuchen lassen.
4. **Teil 2:** Das Codex-Plugin installieren (`/codex:setup`) und
   `/codex:adversarial-review --background` mit Fokus auf die Race Condition starten.
5. Ergebnisse einsammeln (`/codex:status`, `/codex:result`) und mit dem GLM-Befund
   vergleichen.
6. **Reflexion:** Wo lagen GLM-Analyse und Codex-Review inhaltlich auseinander? Was sagt
   das über den Wert unabhängiger Zweitmeinungen aus?

---

## Hinweise für die Weiterverwendung in Claude AI Design

- Dieses Dokument ist bewusst modular: Überschriften-Ebenen (`#`, `##`, `###`) und
  Tabellen lassen sich direkt in Folien, ein Dashboard oder ein Handout überführen.
- Die Befehlstabellen in 2.5 und die Feldtabelle in 1.4 eignen sich als eigenständige
  Spickzettel-Karten.
- Die Diskussionsfragen und die Praxisaufgaben können als separate Arbeitsblätter
  ausgekoppelt werden.

*Quellen: offizielle Z.ai-Doku zur Claude-Code-Integration sowie das README des
Repositorys `openai/codex-plugin-cc`. Befehle, Flags und Modellnamen können sich mit
neuen Releases ändern — für die aktuelle Referenz die jeweiligen Original-Quellen prüfen.*