claude-launcher-profiles/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung – claude-launcher-profiles

> Claude Code mit günstigen Alternativ-Modellen statt der teuren Anthropic-API nutzen.
> Pro-Login bleibt erhalten; OpenRouter-Modelle werden über einfache Profile zugeschaltet.

---

## 1. Warum Modelle aus USA und China parallel?

Dieses Repo ist bewusst nicht an einen einzigen Anbieter oder ein einziges Land gebunden. Es verbindet Modelle aus **USA (Anthropic/Claude)** und **China (Z.ai GLM, Moonshot Kimi, Alibaba Qwen, DeepSeek)** über denselben Client. Dafür gibt es fünf handfeste Gründe:

1. **Resilienz gegen Störungen.** Wer nur eine Quelle hat, steht bei API-Ausfällen, Rate-Limits, Wartungsfenstern oder geopolitischen Maßnahmen (z. B. US-Exportkontrollen, regionalen Sperren) plötzlich ohne Coding-Tool da. Mit Profilen für mehrere Anbieter wechselst du den Endpunkt in einem Aufruf – `claude-pro` fällt aus? Weiter mit `claude-glm`.
2. **Preisdruck durch Wahl.** Allein die Existenz der chinesischen Modelle zwingt die Preisliste nach unten. Wer wählen kann, zahlt nicht den vollen Anthropic-Tarif, sondern nutzt für Alltags-Coding DeepSeek/GLM (ein Vielfaches günstiger, siehe Abschnitt 8) und hebt Claude für die kritischen Stellen auf.
3. **Kein Vendor-Lock-in.** Dein Workflow – Repository, Prompts, Tooling – bleibt anbieterunabhängig. Nur der API-Endpunkt wechselt. Niemand kann dir den Zugriff auf deine eigene Pipeline sperren.
4. **Modellvielfalt je Aufgabe.** Code-Stärke (GLM-5.2, Kimi-K2.7-code, Qwen3-Coder), maximale Wirtschaftlichkeit (DeepSeek V3.1), Top-Reasoning (Claude Opus/Sonnet), kostenloses Ausprobieren (Qwen3-Coder `:free`). Pro Task das passende Modell, pro Aufruf wechselbar.
5. **Perspektivenvielfalt.** Modelle aus unterschiedlichen Trainings- und Rechtsräumen liefern unterschiedliche Perspektiven – wertvoll bei Code-Reviews, Risk-Assessment oder kreativen Problemen, weil ein zweites, unabhängig trainiertes Modell denselben Code anders bewerten kann.

> **Hinweis zu Datenschutz & Datenabfluss:** Sowohl US- als auch CN-Endpunkte übertragen deine Prompts und Codes in fremde Rechtsräume (USA bzw. VR China). Konfiguriere OpenRouter-Datenverarbeitung bewusst (https://openrouter.ai/settings), setze für sensible Projekte `ANTHROPIC_AUTH_TOKEN` nur in vertrauenswürdigen Sessions und vermeide das Einreichen von Secrets über das CLI. Siehe auch Abschnitt 9.

---

## 2. Wozu dieses Repository?

Claude Code ist der CLI-Client von Anthropic. Er spricht standardmäßig die Anthropic-API an – und die ist teuer:

| Anthropic-Modell | Input / 1M Tok | Output / 1M Tok |
|---|---|---|
| Claude Opus 4.5 | $5.00 | $25.00 |
| Claude Sonnet 4.5 | $3.00 | $15.00 |

Dieses Repo schaltet Claude Code stattdessen auf **OpenRouter** um. Dort laufen u. a. starke Open-Source- und Drittanbieter-Modelle, die für viele Coding-Aufgaben qualitativ nah an Claude heranreichen – aber **ein Vielfaches günstiger** sind:

| OpenRouter-Modell | Input / 1M Tok | Output / 1M Tok | Kontext |
|---|---|---|---|
| `z-ai/glm-5.2` | $0.95 | $3.00 | 1 M |
| `moonshotai/kimi-k2.7-code` | $0.74 | $3.50 | 262 K |
| `deepseek/deepseek-chat-v3.1` | $0.21 | $0.79 | 164 K |
| `qwen/qwen3-coder` | $0.22 | $1.80 | 1 M |
| `qwen/qwen3-coder:free` | **gratis** | **gratis** | 1 M |

Konkret: GLM-5.2 ist im Output rund **5× günstiger als Sonnet 4.5** und rund **8× günstiger als Opus 4.5**; DeepSeek V3.1 im Output sogar rund **19× günstiger als Sonnet**. Wer es nur ausprobieren will, nutzt `qwen3-coder:free` ganz ohne Kreditkarte.

> **Live-Beweis:** Dieses Dokument wurde in einer Claude-Code-Session verfasst, die selbst über `z-ai/glm-5.2` via OpenRouter lief – das Setup funktioniert also genau wie beschrieben.

Mit diesem Repo wählst du das Modell über ein Profil:

```bash
claude-pro     # Anthropic Pro-Login (wie gehabt, kein API-Kosten)
claude-glm     # GLM-5.2 über OpenRouter
claude-kimi    # Kimi K2 über OpenRouter
claude-free    # kostenloses Modell über OpenRouter
claude-profile <name>   # generischer Aufruf
```

---

## 3. Setup auf einem jungfräulichen Linux-Host

Dieser Abschnitt führt von einem nackten Debian/Ubuntu-System (vHost im Rechenzentrum oder heimischer Laptop) bis zur lauffähigen `claude-*`-Umgebung. Falls `claude` und `node` bei dir bereits vorhanden sind, überspringe ihn und gehe direkt zu Abschnitt 4.

> **Zielplattform:** Debian/Ubuntu (apt). Für Fedora/RHEL ersetze `apt-get` durch `dnf`, für Arch durch `pacman`. Ein containerisiertes Setup (reproduzierbar, ohne Host-Veränderung) steht ganz unten in diesem Abschnitt.

### 3.1 Basissystem: git, bash, yq

```bash
sudo apt-get update
sudo apt-get install -y git bash yq curl ca-certificates
```

> Hinweis: Unter Debian/Ubuntu ist `yq` der *jq-Wrapper* („Command-line YAML processor – jq wrapper"). Das funktioniert. Der *MikeFarah-yq* geht ebenfalls.

### 3.2 Node.js 18+ (Voraussetzung für Claude Code)

Claude Code benötigt **Node.js 18 oder neuer**. Die sauberste, sudo-freie Methode auf einem vHost ist **NodeSource** (systemweit) oder **nvm** (pro User):

**Variante A – NodeSource (empfohlen für vHost):**

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version    # muss >= 18 sein
```

**Variante B – nvm (pro User, mehrere Node-Versionen):**

```bash
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source "$HOME/.bashrc"
nvm install --lts
nvm use --lts
node --version
```

### 3.3 Claude Code CLI installieren

```bash
npm install -g @anthropic-ai/claude-code
claude --version
```

- Paketname: `@anthropic-ai/claude-code` (offiziell, global).
- ⚠️ **Nicht `sudo npm install -g` verwenden** – das verursacht Berechtigungsprobleme. Nutze NodeSource (systemweit) oder nvm (pro User), damit `npm -g` ohne `sudo` in ein Verzeichnis deines Users installiert.
- Upgrade später mit `npm install -g @anthropic-ai/claude-code@latest` (nicht `npm update -g`).

### 3.4 Claude-Pro-Login

```bash
claude
```

Erstmaliger Start öffnet den Login-Flow. Melde dich mit dem Anthropic-Pro-Account an. Damit ist das `pro`-Profil einsatzbereit (keine API-Kosten, nur das Pro-Abo).

### 3.5 OpenRouter-Account + Key

1. Auf https://openrouter.ai ein Konto anlegen (funktioniert auch ohne Kreditkarte für die `:free`-Modelle).
2. Unter https://openrouter.ai/keys einen API-Key erzeugen (Format `sk-or-v1-…`).
3. Key als Umgebungsvariable setzen (siehe Abschnitt 5.4).

### 3.6 Repo klonen + installieren

```bash
git clone https://kitux.de/forgejo/dschlueter/claude-launcher-profiles.git
cd claude-launcher-profiles
cp config/profiles.example.yml config/profiles.yml
chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh
./bin/install-claude-profiles
source ~/.bashrc
```

Ab hier weiter mit **Abschnitt 5 (OpenRouter-Key setzen)** und **Abschnitt 6 (Nutzung)**.

### 3.7 Alternative: containerisiertes Setup

Für reproduzierbare vHost-Umgebungen ohne Veränderung des Host-Systems. Beispiel-`Dockerfile` (Debian-basiert, enthält Node, Claude Code, yq und das Repo):

```dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      git bash yq curl ca-certificates gnupg \
 && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
 && apt-get install -y nodejs \
 && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /root/src
RUN git clone https://kitux.de/forgejo/dschlueter/claude-launcher-profiles.git \
 && cd claude-launcher-profiles \
 && cp config/profiles.example.yml config/profiles.yml \
 && chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh \
 && ./bin/install-claude-profiles
WORKDIR /root/src/claude-launcher-profiles
ENV OPENROUTER_API_KEY=""
ENTRYPOINT ["/bin/bash"]
```

Bauen und starten:

```bash
docker build -t vibe-code .
# Key zur Laufzeit reinreichen, nie ins Image backen:
docker run -it -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  -v "$HOME/.claude:/root/.claude" \
  vibe-code
```

> ⚠️ **OpenRouter-Key nie ins Image backen.** Im `Dockerfile` ist er absichtlich leer (`ENV OPENROUTER_API_KEY=""`); er wird erst beim `docker run` als `-e`-Flag hereingereicht. Das Claude-Pro-Login liegt im Volume `~/.claude` auf dem Host und bleibt so containerübergreifend erhalten. Podman funktioniert analog (ersetze `docker` durch `podman`).

---

## 4. Voraussetzungen (Kurzfassung)

Vollständige Einrichtung ab nacktem System → **Abschnitt 3**. Kurzform, falls du schon `claude`, `node` und `yq` hast:

- `claude` (Claude Code CLI) installiert → Abschnitt 3.3
- funktionierendes **Claude-Pro-Login** (nur für das `pro`-Profil nötig) → Abschnitt 3.4
- `bash` + `yq` (YAML-Parser) → Abschnitt 3.1
- ein **OpenRouter-Account + API-Key** (nur für die OpenRouter-Profile) → Abschnitt 3.5

---

## 5. Konfiguration & Keys

### 5.1 `profiles.yml` anlegen

```bash
cp config/profiles.example.yml config/profiles.yml
$EDITOR config/profiles.yml
```

`config/profiles.yml` enthält **keine** API-Keys – nur Modellnamen, Base-URL und den Claude-Startbefehl. Der OpenRouter-Key kommt ausschließlich aus der Umgebung (siehe 5.2). Beispiel:

```yaml
defaults:
  claude_cmd: "claude"
  openrouter_base_url: "https://openrouter.ai/api"

profiles:
  pro:
    mode: "pro"

  glm:
    mode: "openrouter"
    model: "z-ai/glm-5.2"

  kimi:
    mode: "openrouter"
    model: "moonshotai/kimi-k2.7-code"

  free:
    mode: "openrouter"
    model: "openrouter/free"
```

> **Modell-Slugs:** Die obigen Slugs (`z-ai/glm-5.2`, `moonshotai/kimi-k2.7-code`, `openrouter/free`) sind gegen die OpenRouter-API getestet (Stand Juni 2026) und entsprechen der mitgelieferten `profiles.example.yml`. OpenRouter ändert gelegentlich Bezeichner – bei eigenen Ergänzungen gegen https://openrouter.ai/models prüfen.
>
> ⚠️ **`openrouter/free` ist ein Meta-Slug**, kein festes Modell: OpenRouter routet den Aufruf an ein gerade verfügbares Gratis-Modell weiter. Aktuell landet das z. B. bei `nvidia/nemotron-3.5-content-safety` – einem **Content-Safety-Klassifikator, nicht einem Coding-Modell**. Zum Coden stattdessen `qwen/qwen3-coder:free` eintragen (gültig, aber rate-limitiert – bei 429 kurz warten oder eigenes Guthaben nutzen).

### 5.2 OpenRouter-Key setzen

Der Key wird **nicht** in `profiles.yml` gespeichert, sondern als Umgebungsvariable.

Temporär (nur aktuelle Session):

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Dauerhaft in `~/.bashrc`:

```bash
echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.bashrc
source ~/.bashrc
```

### 5.3 Skripte ausführbar machen und installieren

```bash
chmod +x bin/claude-profile bin/install-claude-profiles lib/profiles.sh
./bin/install-claude-profiles
```

Der Installer legt (falls nötig) einen Symlink unter `~/src/claude-launcher-profiles` an und fügt eine `source`-Zeile in deine `~/.bashrc` ein, die die Aliase lädt.

### 5.4 Shell neu laden und prüfen

```bash
source ~/.bashrc
alias | grep claude-
```

Du solltest `claude-pro`, `claude-glm`, `claude-kimi`, `claude-free` sehen.

---

## 6. Nutzung

```bash
claude-pro      # Claude Pro (Anthropic-Login, keine API-Kosten)
claude-glm      # GLM-5.2 via OpenRouter
claude-kimi     # Kimi K2 via OpenRouter
claude-free     # kostenloses Modell via OpenRouter
```

Generisch (z. B. für selbst angelegte Profile):

```bash
claude-profile glm
claude-profile mein-eigenes-profil
```

Jeder Aufruf setzt die nötigen `ANTHROPIC_*`-Variablen für die jeweilige Sitzung und startet `claude`. Vorher gesetzte Claude-Umgebungsvariablen werden pro Aufruf bereinigt, damit Profile sich nicht vermischen.

---

## 7. Eigene Profile anlegen

Trage ein neues Profil in `config/profiles.yml` ein:

```yaml
  deepseek:
    mode: "openrouter"
    model: "deepseek/deepseek-chat-v3.1"
```

Dazu passend einen Alias in `shell/aliases.sh`:

```bash
alias claude-deep="$HOME/src/claude-launcher-profiles/bin/claude-profile deepseek"
```

Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für alle OpenRouter-Profile gemeinsam.

---

## 8. Kosten vs. Qualität – ehrlicher Vergleich

### 8.1 Beispielsitzung (500 K Input + 50 K Output, ungespeichert)

| Modell | Kosten | relativ zu Sonnet 4.5 |
|---|---|---|
| Claude Opus 4.5 | 0,5·$5 + 0,05·$25 = **$3,75** | 1,7× |
| Claude Sonnet 4.5 | 0,5·$3 + 0,05·$15 = **$2,25** | 1× (Referenz) |
| GLM-5.2 | 0,5·$0,95 + 0,05·$3 = **$0,63** | ≈ 0,28× |
| Kimi K2.7-code | 0,5·$0,74 + 0,05·$3,50 = **$0,55** | ≈ 0,24× |
| DeepSeek V3.1 | 0,5·$0,21 + 0,05·$0,79 = **$0,15** | ≈ 0,07× |
| Qwen3 Coder (free) | **$0,00** | gratis |

> Wer Claude Code intensiv nutzt, gibt an einem Tag schnell mehrere Millionen Token aus. Bei 10 M Output/Tag macht der Unterschied zwischen Sonnet ($150) und GLM-5.2 ($30) schnell **über $120 pro Tag** aus. Prompt-Caching (Cache-Read bei GLM ~$0,18/M) senkt die Kosten für wiederholte System-Prompts zusätzlich.

### 8.2 Qualität – realistische Einordnung

- **GLM-5.2** (`z-ai/glm-5.2`): großes Reasoning-Modell, 1-M-Kontext, stark in langen Coding-/Agenten-Workflows und Werkzeugnutzung. Für die meisten Software-Engineering-Aufgaben ein brauchbarer Sonnet-Ersatz; bei den allerschwersten Schlussfolgerungen liegt Opus weiter vorn.
- **Kimi K2.7-code** (`moonshotai/kimi-k2.7-code`): fokussiert auf langfristiges Coding und UI-Generierung, Multi-Agenten-Orchestrierung. Gut für komplexere End-to-End-Coding-Tasks; 262K-Kontext (schmaler als GLM). Reasoning-Modell – braucht genug Output-Token, sonst verbraucht das „Denken" das Limit bevor die Antwort kommt.
- **DeepSeek V3.1** (`deepseek/deepseek-chat-v3.1`): extrem günstig, hybrides Reasoning, solide Tool-Nutzung – Top-Wirtschaftlichkeit für Alltags-Coding.
- **Qwen3 Coder** (`qwen/qwen3-coder` / `:free`): MoE-Code-Modell, 1-M-Kontext, auf agentenhaftes Coding (Function Calling, Repo-Weit-Kontext) optimiert. Die `:free`-Variante ist rate-limitiert, aber ideal zum Ausprobieren.
- **Kostenlos-Modelle** allgemein: gut zum Testen und für einfache Aufgaben; Rate-Limits und gelegentliche Auslastung machen sie für produktiven Dauereinsatz weniger verlässlich. Achtung bei `openrouter/free`: das ist ein Meta-Slug, der an ein gerade verfügbares Gratis-Modell routet – das kann auch ein Nicht-Coding-Modell wie ein Content-Safety-Klassifikator sein (siehe Hinweis in 3.2).

**Faustregel:** Für tägliche Coding-Arbeit sind GLM-5.2 oder DeepSeek V3.1 das beste Preis-Leistungs-Verhältnis; für die härtesten Reasoning-Aufgaben oder maximale Zuverlässigkeit bleibt Claude (Pro oder API) die Referenz. Das Schöne: Du kannst **pro Aufruf wechseln** – `claude-glm` zum Bauen, `claude-pro` für die kritische Stelle.

---

## 9. Sicherheit

- `config/profiles.yml` enthält nur lokale Einstellungen und steht in `.gitignore` – sie wird nicht committet.
- Der OpenRouter-Key liegt **nur** in der Shell-Umgebung (`~/.bashrc`), nie im Repo.
- Vor jedem Profilwechsel werden `ANTHROPIC_*`-Variablen bereinigt, damit kein altes Token in eine andere Sitzung durchsickert.
- Prüfe vor jedem Commit auf versehentliche Secrets:
  ```bash
  grep -R "sk-or-v1-" .
  ```
  Hier darf es keinen Treffer geben.

---

## 10. Troubleshooting

| Symptom | Ursache / Lösung |
|---|---|
| `Error: yq is required` | `yq` fehlt → siehe Abschnitt 3.1. |
| `Error: missing config file` | `config/profiles.yml` fehlt → `cp config/profiles.example.yml config/profiles.yml`. |
| `Error: OPENROUTER_API_KEY is not set` | Key nicht exportiert → `export OPENROUTER_API_KEY=...` und `source ~/.bashrc`. |
| `Error: profile 'x' not found` | Tippfehler oder Profil fehlt in `profiles.yml`. |
| `Error: unsupported mode` | `mode` muss `pro` oder `openrouter` sein. |
| Model-Antworten fehlerhaft / 404 | Slug veraltet → auf https://openrouter.ai/models prüfen und in `profiles.yml` anpassen. |
| Antwort leer / „finish_reason: length" | Reasoning-Modell hat das Token-Limit im „Denkschritt" verbraucht → höheres `max_tokens`-Setting im Client bzw. längere Antworten erlauben. |
| `claude-free` liefert unbrauchbare Antworten | `openrouter/free` ist ein Meta-Slug und kann an ein Nicht-Coding-Modell routen → stattdessen `qwen/qwen3-coder:free` eintragen. |
| 429 / „rate-limited upstream" | Gratis-Modell ist ausgelastet → kurz warten, ein kostenpflichtiges Slug nutzen oder Guthaben aufladen. |
| Aliase fehlen nach `source ~/.bashrc` | Installer-Zeile fehlt → `./bin/install-claude-profiles` erneut ausführen. |
| `claude-pro` startet nicht richtig | Pro-Login abgelaufen → `claude` einmal direkt starten und anmelden. |

---

## 11. Wo was liegt

```
bin/claude-profile           # Einstieg: ruft launch_profile <name> auf
bin/install-claude-profiles  # richtet Symlink + .bashrc-Alias-Zeile ein
lib/profiles.sh              # Kernlogik: YAML-Parser, Profile, Env-Setup
shell/aliases.sh             # die claude-* Aliase
config/profiles.example.yml  # Vorlage (im Repo)
config/profiles.yml          # deine lokale Konfig (gitignored)
tests/test_profiles.sh       # Test-Suite (siehe Abschnitt 10)
Makefile                     # `make test` Runner
```

Fragen oder Erweiterungen → Forgejo: https://kitux.de/forgejo/dschlueter/claude-launcher-profiles