diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 313967d..1de2274 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -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 # 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 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