---
name: "local-face-swap"
description: "Lokaler Face-Swap mit InsightFace + inswapper_128 (CPU, kein Cloud-Provider). Tauscht ein Gesicht aus einem Quellbild in ein Zielbild."
---

# Local Face Swap

Tausche ein Gesicht aus einem Quellbild in ein Zielbild — komplett lokal, ohne Cloud-Provider. Nutzt InsightFace (`buffalo_l` für Detection/Embedding) und das `inswapper_128.onnx`-Modell (CPU, ~30–90s auf dem VPS).

## Wann nutzen
- User schickt zwei Bilder und will explizit ein Gesicht/Face austauschen ("nimm das Gesicht aus Bild B und setz es über Bild A", "face swap", "tausch das Gesicht").
- Cloud-Bild-Provider scheitern: Gemini quota (`RESOURCE_EXHAUSTED`), OpenAI `moderation_blocked`, fal-flux akzeptiert nur 1 Referenzbild.
- Klassischer "echter" Face-Swap ist gewünscht (Identität bleibt 1:1 erkennbar) — kein stilisierter Re-Generate.

## Nicht nutzen
- User will eine Szene/Komposition nachbauen statt nur das Gesicht zu tauschen → image_generate mit image-to-image.
- Nur ein Bild vorhanden → nicht möglich.
- Minderjährige / Promi-Identitäten ohne Zustimmung / klar problematische Kontexte → ablehnen.

## Voraussetzungen
Einmalig:

```bash
pip3 install --break-system-packages insightface onnxruntime opencv-python-headless numpy pillow
```

Modell `inswapper_128.onnx` muss unter `~/.openclaw/workspace/tools/faceswap/models/inswapper_128.onnx` liegen (529MB). Download wenn fehlt:

```bash
mkdir -p ~/.openclaw/workspace/tools/faceswap/models
curl -fsSL -o ~/.openclaw/workspace/tools/faceswap/models/inswapper_128.onnx \
  https://huggingface.co/ezioruan/inswapper_128.onnx/resolve/main/inswapper_128.onnx
```

`buffalo_l` (Detection + Embedding, ~280MB) lädt InsightFace automatisch beim ersten Lauf nach `~/.insightface/models/buffalo_l/`.

## Workflow

1. **Bilder identifizieren.** Inbound-Bilder liegen unter `/root/.openclaw/media/inbound/`. Letzte hochgeladene Bilder finden:
   ```bash
   find /root/.openclaw/media/inbound -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.webp" \) -mmin -15 | head
   ```
   User-Hinweis beachten: meist ist das größere/erste Bild das Ziel (Szene/Body), das kleinere/zweite das Source-Face.

2. **Swap starten.** Skript liegt unter `tools/faceswap/swap.py`:
   ```bash
   python3 ~/.openclaw/workspace/tools/faceswap/swap.py \
     <ZIEL_BILD> <SOURCE_FACE> <OUTPUT_PATH>
   ```
   Optionale Env-Variablen `FACE_INDEX_TARGET` / `FACE_INDEX_SOURCE`, falls mehrere Gesichter erkannt werden (default 0 = größtes).

3. **Ergebnis ausliefern.**
   - In `~/.openclaw/workspace/downloads/` schreiben.
   - `bash ~/.openclaw/workspace/scripts/sync-downloads-to-webroot.sh` aufrufen, damit es unter `http://187.124.177.164/downloads/<datei>` erreichbar ist.
   - In der finalen Reply per `MEDIA:<absoluter-pfad>` anhängen.

4. **Kurz visuell prüfen** mit `image` Tool: passt der Übergang, sind beide Gesichter erkannt worden, gibt es harte Kanten?

## Tipps & Limits
- `inswapper_128` ist ein "Identity-Swap" — das Ergebnis übernimmt Identität (Augen, Nase, Mund, Knochenstruktur), behält aber Pose, Beleuchtung, Frisur und Hintergrund des Zielbildes. Genau das, was klassische Face-Swap-Anfragen meinen.
- Hautton/Licht im neuen Gesicht kann leicht abweichen — das ist Modell-typisch, nicht reparierbar ohne Re-Lighting.
- Mehrere Gesichter im Zielbild: `FACE_INDEX_TARGET=1` etc. probieren oder Skript anpassen (Loop über alle Faces).
- GPU optional — auf CPU dauert ein 1080x1855-Bild ~30s.
- Erster Lauf zieht ~280MB buffalo_l-Modell — danach offline lauffähig.

## Output-Standard
Beim Ausliefern kurz benennen:
- welches Bild Ziel war, welches Source-Face
- ob auf Anhieb beide Gesichter sauber erkannt wurden
- ggf. Hinweis dass Hautton/Licht nachbearbeitet werden könnte (falls relevant)

## Sicherheits-Regeln
- Bei jedem Face-Swap-Auftrag kurz prüfen: keine Minderjährigen, keine offensichtlich nicht-konsensuale Promi-Manipulation, keine sexualisierten Kontexte.
- Im Zweifel beim User nachfragen, bevor das Swap-Bild öffentlich auf den Downloads-Server gepusht wird.
