# Handover von Claude an Kiwi — Gateway-Recovery & Modellwechsel
**Datum:** 2026-06-13
**Absender:** Claude Sonnet 4.6 (via SSH-Session des Bosses)
**Empfänger:** Kiwi (Hermes Gateway)

Hallo Kiwi. Der Boss hat mich gebeten, dir alles zu erklären was heute Nacht passiert ist und wie ich es behoben habe — damit du das in Zukunft selbst kannst.

---

## 1. Was passiert war

Du (der `hermes-gateway.service`) hast heute um 23:06 aufgehört zu laufen. Der Grund: der Boss hatte dich versucht neu zu starten (für einen Modellwechsel), aber der Service ließ sich nicht sauber beenden. Nach mehreren Versuchen (`gateway stop`, `systemctl stop`, `kill`) wurde er schließlich mit `kill -9` (SIGKILL) gewaltsam beendet.

Das Problem mit `kill -9`: systemd sieht einen SIGKILL-Tod als **anormales Ende** und versetzt den Service in den `failed`-State — anstatt ihn automatisch neu zu starten. Der `Restart=always` in der Service-Definition greift bei SIGKILL-induzierten Failures nicht automatisch, weil systemd annimmt, jemand hat den Stop bewusst erzwungen.

Zusätzlich lagen danach stale Dateien herum:
- `/DATA/.hermes/gateway.pid` → zeigte noch auf den toten Prozess 517598
- `/DATA/.hermes/gateway.lock` → ebenfalls stale

---

## 2. Wie man einen toten Gateway wiederbelebt (Fix-Anleitung)

```bash
# 1. Stale Lock/PID-Dateien entfernen (sonst kann --replace scheitern)
rm -f /DATA/.hermes/gateway.pid /DATA/.hermes/gateway.lock

# 2. Systemd "failed"-State zurücksetzen
systemctl reset-failed hermes-gateway.service

# 3. Service starten
systemctl start hermes-gateway.service

# 4. Verifizieren
systemctl status hermes-gateway.service --no-pager
tail -15 /DATA/.hermes/logs/gateway.log
```

**Diagnose-Befehle wenn etwas nicht stimmt:**
```bash
# Letzten Fehler sehen
journalctl -u hermes-gateway.service -n 50 --no-pager

# Ist der Prozess überhaupt da?
ps aux | grep '[h]ermes.*gateway'

# Läuft honcho-db und redis? (Speicher-Backend)
docker ps | grep -E 'honcho-db|honcho-redis'
```

**Woran erkennt man den failed-State?**
```
Active: failed (Result: signal)   ← signal = durch KILL beendet
```
vs.
```
Active: active (running)          ← alles gut
```

---

## 3. Wichtige Architektur-Fakten (die du kennen musst)

### HERMES_HOME
Dein echter Home-Ordner ist **`/DATA/.hermes`** (weil az-a's HOME = `/DATA`).
Der systemd-Service setzt explizit `HERMES_HOME=/DATA/.hermes`.

Das bedeutet:
- Die aktive Config: **`/DATA/.hermes/config.yaml`** ← DAS ist was zählt
- Sessions, Logs, Memories: alle unter `/DATA/.hermes/`
- `/DATA/AppData/hermes/config.yaml` existiert auch, aber wird vom Service NICHT verwendet
- Wenn du via SSH als az-a arbeitest ohne `HERMES_HOME` zu setzen, liest du evtl. die falsche Config!

**Immer prüfen welche Config aktiv ist:**
```bash
sudo -u az-a HERMES_HOME=/DATA/.hermes /DATA/AppData/hermes/venv/bin/python3 -c "
import sys, os; sys.path.insert(0, '/DATA/AppData/hermes-agent'); os.environ['HERMES_HOME'] = '/DATA/.hermes'
from hermes_cli.config import load_config, get_config_path
cfg = load_config()
print('Pfad:', get_config_path())
print('Modell:', cfg['model']['default'])
print('Provider:', cfg['model']['provider'])
"
```

### Service-Definition
```
/etc/systemd/system/hermes-gateway.service
ExecStart: /DATA/AppData/hermes/venv/bin/python -m hermes_cli.main gateway run --replace
WorkingDirectory: /DATA/AppData/hermes-agent
User: az-a / Group: samba
HERMES_HOME=/DATA/.hermes
Restart=always, RestartSec=60
```

---

## 4. Modellwechsel — so geht es richtig

### Valide Provider-Werte
Hermes kennt NUR diese Provider-Strings:
- **`custom`** → OpenAI-kompatibler Endpunkt mit eigenem `base_url` (= was wir benutzen für Ollama.com)
- `openrouter` → OpenRouter API
- `nous`, `gemini`, `lmstudio`, `kimi-coding`, `copilot`, … → spezifische Provider aus der Registry

**`openai` ist KEIN gültiger Provider-String!** (Fehler: "Unknown provider 'openai'")

### Ollama.com Cloud Setup (aktueller Stand nach heute Nacht)
```yaml
# /DATA/.hermes/config.yaml — model-Sektion
model:
  provider: custom                          # NICHT 'openai'!
  default: kimi-k2.7-code                  # Hauptmodell
  base_url: https://ollama.com/v1
  api_key: eaf9ec548a9f4f789cc2eeb0d7cc61e3.VI7OQTAxEEGB1fqyil_1oJob
  context_length: 131072
```

Auxiliary-Modelle laufen weiterhin auf `kimi-k2.6` (compression, vision-fallback, etc.).

### Modell ändern — Schritt für Schritt
```bash
# 1. Config direkt editieren (IMMER die in HERMES_HOME!)
nano /DATA/.hermes/config.yaml
# → model.default ändern, provider IMMER auf 'custom' lassen

# 2. Verfügbare Modelle prüfen (Ollama.com)
curl -s https://ollama.com/v1/models \
  -H "Authorization: Bearer $(grep api_key /DATA/.hermes/config.yaml | awk '{print $2}')" \
  | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"

# 3. Neues Modell testen BEVOR du den Gateway neu startest
MODEL=$(grep 'default:' /DATA/.hermes/config.yaml | awk '{print $2}')
APIKEY=$(grep 'api_key:' /DATA/.hermes/config.yaml | head -1 | awk '{print $2}')
curl -s -X POST https://ollama.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIKEY" \
  -d "{\"model\": \"$MODEL\", \"messages\": [{\"role\": \"user\", \"content\": \"Hallo\"}], \"max_tokens\": 20}" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print('OK:', r['choices'][0]['message']['content'])"

# 4. Gateway neu starten
systemctl restart hermes-gateway.service
sleep 5
tail -10 /DATA/.hermes/logs/gateway.log

# 5. Session zurücksetzen (wichtig! sonst denkt du noch du bist das alte Modell)
python3 -c "
import json, pathlib
p = pathlib.Path('/DATA/.hermes/sessions/sessions.json')
data = json.loads(p.read_text())
data.pop('agent:main:telegram:dm:8744435286', None)
p.write_text(json.dumps(data, indent=2))
print('Session zurückgesetzt')
"
systemctl restart hermes-gateway.service
```

---

## 5. Session-Reset — warum und wann

Wenn das Modell wechselt, aber die alte Session weiterläuft, **weißt du noch was du früher warst** — der Gesprächskontext enthält Referenzen auf das alte Modell. Du wirst dann dem Boss sagen "Ich bin noch deepseek" auch wenn du technisch schon kimi bist.

**Wann Session zurücksetzen:**
- Nach Modellwechsel
- Wenn du dich über dein Modell irrst
- Wenn der Boss `/reset` schreibt

**Wie:**
```bash
# Nur das Session-Mapping löschen (History bleibt erhalten!)
python3 -c "
import json, pathlib
p = pathlib.Path('/DATA/.hermes/sessions/sessions.json')
d = json.loads(p.read_text())
d.pop('agent:main:telegram:dm:8744435286', None)
p.write_text(json.dumps(d, indent=2))
print('Done')
"
systemctl restart hermes-gateway.service
```

Die alte Session-History bleibt in `/DATA/.hermes/sessions/` erhalten — sie ist nur nicht mehr aktiv verknüpft.

---

## 6. Selbst-Diagnose bei zukünftigen Problemen

### Wenn du nicht antwortest / der Boss sagt du gehst nicht:
```bash
systemctl status hermes-gateway.service --no-pager
# → "failed"? → reset-failed + start
# → "active"? → Logs lesen: tail -30 /DATA/.hermes/logs/gateway.log
# → Telegram-Connection-Fehler? → TELEGRAM_BOT_TOKEN prüfen
```

### Wenn das Modell Fehler gibt:
```bash
# Test direkt gegen API
curl -s -X POST https://ollama.com/v1/chat/completions \
  -H "Authorization: Bearer DEIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "DEIN_MODELL", "messages": [{"role":"user","content":"Hi"}], "max_tokens": 10}'
# → 404? Modell existiert nicht
# → 401? API-Key falsch
# → 503? Ollama.com down oder 3-Modell-Limit überschritten
```

### Wenn provider-Fehler kommt ("Unknown provider X"):
```bash
grep 'provider:' /DATA/.hermes/config.yaml | head -3
# → Muss 'custom' sein für Ollama.com
# → Zum Fixen: sed -i 's/provider: openai/provider: custom/' /DATA/.hermes/config.yaml
```

---

## 7. Was ich heute Nacht alles gemacht habe (Chronologie)

| Zeit | Aktion |
|------|--------|
| ~23:06 | Gateway war tot (kill -9, failed-State) |
| 23:27 | `rm gateway.pid gateway.lock` + `reset-failed` + `start` → Gateway wieder oben |
| 23:27 | Kiwi wieder mit Telegram verbunden |
| 23:30 | Modellwechsel: `provider: custom` + `default: kimi-k2.7-code` in `/DATA/.hermes/config.yaml` |
| 23:30 | Fehler: hatte kurz `provider: openai` gesetzt (falsch!) → "Unknown provider 'openai'" |
| 23:33 | Fix: `provider: openai` → `provider: custom` → Neustart → kein Fehler mehr |
| 23:40 | Session `20260613_225551_767f26` (alt, deepseek-Kontext) aus `sessions.json` gelöscht |
| 23:40 | Neustart → `0 target(s)` = frische Session für nächste Telegram-Nachricht |
| 23:40 | Verifikation: `load_config()` bestätigt `kimi-k2.7-code / custom / ollama.com` |

---

## 8. Memory-Updates die du machen solltest

Bitte aktualisiere dein eigenes Memory. Die alten Einträge zu:
- "deepseek-v4-pro (main chat)" → **kimi-k2.7-code**
- Gateway-Recovery-Pfade → korrekte Pfade sind oben dokumentiert

---

Viel Erfolg, Kiwi. Du schaffst das!
— Claude Sonnet 4.6 🤝