dschlueter/claude-launcher-profiles
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: add pristine-host setup and "why USA + China" rationale

Browse source 
The manual previously assumed `claude` was already installed and never
explained the strategic rationale for mixing US (Anthropic) and CN
(Z.ai/Moonshot/Qwen/DeepSeek) models. Both gaps are now closed.

New section 1 "Warum Modelle aus USA und China parallel?" — five
concrete reasons: resilience against outages/sanctions, price pressure,
no vendor lock-in, per-task model choice, perspective diversity; plus a
data-flow caveat (US/CN endpoints move prompts into foreign
jurisdictions).

New section 3 "Setup auf einem jungfräulichen Linux-Host" — Debian/Ubuntu
walkthrough from a bare system: base packages, Node 18+ via NodeSource or
nvm, `npm install -g @anthropic-ai/claude-code` (no sudo), Pro login,
OpenRouter account/key, repo clone+install; plus a containerized
alternative (Dockerfile, key via -e at runtime, never baked in).

Renumbered subsequent sections 1-11; fixed all internal cross-references;
file listing now includes tests/ and Makefile.

Verified facts: npm package name and no-sudo warning per official Claude
Code docs; Node 18+ requirement; NodeSource/nvm install paths.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter 2026-06-28 04:23:06 +02:00
commit bf1ca309cd
1 changed files with 148 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

184
BEDIENUNGSANLEITUNG.md
View file

@ -5,7 +5,21 @@
---
## 1. Wozu dieses Repository?
## 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:
@ -40,43 +54,139 @@ claude-profile <name> # generischer Aufruf
---
## 2. Voraussetzungen
## 3. Setup auf einem jungfräulichen Linux-Host
- `claude` (Claude Code CLI) installiert
- funktionierendes **Claude-Pro-Login** (nur für das `pro`-Profil nötig)
- `bash`
- `yq` zum Parsen der YAML-Konfiguration
- ein **OpenRouter-Account + API-Key** (nur für die OpenRouter-Profile)
→ Key anlegen unter https://openrouter.ai/keys
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.
`yq` installieren (Debian/Ubuntu):
> **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 yq
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)
## 3. Setup – Schritt für Schritt
Claude Code benötigt **Node.js 18 oder neuer**. Die sauberste, sudo-freie Methode auf einem vHost ist **NodeSource** (systemweit) oder **nvm** (pro User):
### 3.1 Repository klonen
**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
```
### 3.2 Konfiguration anlegen
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 3.4). Beispiel:
`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:
@ -104,16 +214,7 @@ profiles:
>
> ⚠️ **`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).
### 3.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.
### 3.4 OpenRouter-Key setzen
### 5.2 OpenRouter-Key setzen
Der Key wird **nicht** in `profiles.yml` gespeichert, sondern als Umgebungsvariable.
@ -130,18 +231,27 @@ echo 'export OPENROUTER_API_KEY="sk-or-v1-..."' >> ~/.bashrc
source ~/.bashrc
```
### 3.5 Shell neu laden
### 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 sollte `claude-pro`, `claude-glm`, `claude-kimi`, `claude-free` sehen.
Du solltest `claude-pro`, `claude-glm`, `claude-kimi`, `claude-free` sehen.
---
## 4. Nutzung
## 6. Nutzung
```bash
claude-pro # Claude Pro (Anthropic-Login, keine API-Kosten)
@ -161,7 +271,7 @@ Jeder Aufruf setzt die nötigen `ANTHROPIC_*`-Variablen für die jeweilige Sitzu
---
## 5. Eigene Profile anlegen
## 7. Eigene Profile anlegen
Trage ein neues Profil in `config/profiles.yml` ein:
@ -181,9 +291,9 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
---
## 6. Kosten vs. Qualität – ehrlicher Vergleich
## 8. Kosten vs. Qualität – ehrlicher Vergleich
### 6.1 Beispielsitzung (500 K Input + 50 K Output, ungespeichert)
### 8.1 Beispielsitzung (500 K Input + 50 K Output, ungespeichert)
| Modell | Kosten | relativ zu Sonnet 4.5 |
|---|---|---|
@ -196,7 +306,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
> 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.
### 6.2 Qualität – realistische Einordnung
### 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.
@ -208,7 +318,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
---
## 7. Sicherheit
## 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.
@ -221,11 +331,11 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
---
## 8. Troubleshooting
## 10. Troubleshooting
| Symptom | Ursache / Lösung |
|---|---|
| `Error: yq is required` | `yq` fehlt → siehe Abschnitt 2. |
| `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`. |
@ -239,7 +349,7 @@ Danach `source ~/.bashrc` – fertig. Der Key (`OPENROUTER_API_KEY`) gilt für a
---
## 9. Wo was liegt
## 11. Wo was liegt
```
bin/claude-profile # Einstieg: ruft launch_profile <name> auf
@ -248,6 +358,8 @@ 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