# my-free-code einrichten — Anleitung für deinen Coding-Agenten

> **So benutzt du diese Datei:** Leg sie in dein Projektverzeichnis und sag
> deinem Agenten: *„Halte dich an my-free-code-einrichten.md."* Das funktioniert mit Claude
> Code, Codex, Cursor, Cline und allem anderen, was Dateien lesen kann.
> Wenn dein Agent von selbst eine bestimmte Datei liest, kannst du sie auch
> in `AGENTS.md` umbenennen oder den Inhalt in deine `CLAUDE.md` kopieren.

**Projekt:** [github.com/hkqr/my-free-code](https://github.com/hkqr/my-free-code) · **Stand:** 2026-09-09 · Zusammengestellt von
[localdev.ai](https://localdev.ai/)

---

## Ziel

Der Agent hat einen lokalen AI-Gateway-Server auf Port 8082 laufen, der Claude Code und andere Coding-Agenten mit multi-provider Routing bedienen kann.

## Voraussetzungen

- Python 3.10 oder neuer
- pip mit Netzwerkzugriff
- Betriebssystem: Windows, macOS oder Linux
- Für Launcher: Ziel-Client (claude, codex, etc.) muss auf PATH sein
- Für externe Provider: API-Keys der gewünschten Provider

## Das fragst du mich, bevor du anfängst

- Welche Provider willst du nutzen? Brauchst du API-Keys dafür?
- Soll der Server auf dem Default-Port 8082 laufen oder anderer?
- Willst du lokale Modelle (Ollama, LM Studio, llama.cpp) einbinden? Wenn ja, laufen die bereits?
- Soll ich die .env.example kopieren und mit Beispielwerten füllen, oder hast du schon eigene Konfiguration?

## Einrichtung

### 1. Virtuelle Umgebung erstellen

```bash
python -m venv .venv
```

**Prüfen:** Verzeichnis .venv existiert mit Unterverzeichnissen bin/ (Linux/macOS) oder Scripts/ (Windows)

> ⚠️ Windows: .venv\Scripts\Activate.ps1 hat Execution-Policy-Beschränkungen

### 2. Virtuelle Umgebung aktivieren

```bash
source .venv/bin/activate
```

**Prüfen:** Prompt zeigt (.venv) oder `which python` zeigt auf .venv/bin/python

> ⚠️ Windows-Pfad ist .venv\Scripts\activate.bat oder .venv\Scripts\Activate.ps1

### 3. Abhängigkeiten installieren

```bash
python -m pip install -r requirements.txt
```

**Prüfen:** pip list zeigt installierte Pakete, keine ERROR-Meldungen

> ⚠️ Netzwerkzugriff nötig; bei Firmenproxy ggf. Umgebungsvariablen setzen

### 4. Konfigurationsdatei vorbereiten

```bash
cp .env.example .env
```

**Prüfen:** Datei .env existiert im Projektverzeichnis

> ⚠️ Windows: `copy` statt `cp`; .env niemals committen

### 5. Server starten

```bash
python -m my_free_code
```

**Prüfen:** Ausgabe zeigt Server läuft auf http://127.0.0.1:8082 oder konfiguriertem HOST:PORT

> ⚠️ Port 8082 muss frei sein; bei Belegung wird Fehler geworfen


## Erster Test

Prüfe, ob der Gateway-Server antwortet, bevor du Clients konfigurierst.

```python
curl http://127.0.0.1:8082/health
```

## Wenn es klemmt

| Symptom | Ursache | Lösung |
|---|---|---|
| ModuleNotFoundError beim Start | Venv nicht aktiviert oder requirements.txt nicht installiert | Prüfe `which python`, aktiviere venv neu, wiederhole pip install |
| Port 8082 bereits belegt | Anderer Prozess blockiert den Port | In .env PORT=8083 setzen oder laufenden Prozess beenden |
| curl /health liefert Connection refused | Server läuft nicht oder auf anderem Host/Port | Prüfe Server-Logs auf tatsächliche Bind-Adresse; HOST in .env prüfen |
| Provider liefert 401 Unauthorized | API-Key fehlt oder ist ungültig | In .env korrespondierenden Key setzen (z.B. OPENROUTER_API_KEY) |
| Claude Code ignoriert Gateway | ANTHROPIC_BASE_URL nicht gesetzt oder Client zu alt | Umgebungsvariablen prüfen; CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 setzen |

## Grenzen — das kann das Projekt nicht

- Kein offizieller Anthropic-Dienst; unabhängige Implementierung
- Provider mit ungewöhnlichen Protokollen brauchen dedizierten Adapter, nicht universell
- Launcher erfordern vorinstallierte Clients auf PATH
- Nach Beginn des Streamings kein stiller Provider-Wechsel mehr
- Nicht für direktes Internet-Exposure gedacht; Admin-Endpunkte ungeschützt ohne Reverse-Proxy

## Regeln für dich als Agent

- Niemals .env committen oder API-Keys im Log ausgeben
- Vor jedem Provider-Wechsel oder Key-Eintrag Nutzer um Bestätigung fragen
- Keine API-Keys erfinden oder aus dem Material extrapolieren; fehlende Keys = Frage an Nutzer
- Bei `python -m my_free_code.cli.mfc <client>` prüfen, ob Client auf PATH existiert
- Nach Serverstart immer /health testen, bevor Clients konfiguriert werden
- Windows/macOS/Linux-Unterschiede beachten: activate-Pfade, copy/cp, PowerShell vs bash

---

### Wichtig

Diese Datei wurde aus der Liesmich-Datei des Projekts vom 2026-09-09
zusammengestellt und ist keine offizielle Dokumentation. Sie ersetzt nicht den
Blick in das Repository — wenn ein Befehl hier nicht funktioniert, gilt
[die Quelle](https://github.com/hkqr/my-free-code), nicht diese Datei.

*Erklärvideos und Merkblätter zu Werkzeugen wie diesem:
[localdev.ai](https://localdev.ai/m/) — ohne Anmeldung.*
