dschlueter f623c424d0 docs: Setup auf jungfräulichem Host + Warum USA+China parallel (#4 )

2026-06-28 04:25:40 +02:00

17 KiB

Raw Blame History

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:

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.
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.
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.
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.
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:

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

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):

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):

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

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).

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

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

3.6 Repo klonen + installieren

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):

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:

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

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:

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):

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

Dauerhaft in ~/.bashrc:

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

5.3 Skripte ausführbar machen und installieren

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

source ~/.bashrc
alias | grep claude-

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

6. Nutzung

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):

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:

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

Dazu passend einen Alias in shell/aliases.sh:

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:
```
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

17 KiB Raw Blame History Unescape Escape