raspi_openclaw/old/mailbox-cal-updated-docs/README.md

# openclaw-mailbox-cal

**OpenClaw Skill-Repository** — mailbox.org Kalender und Aufgaben auf dem Raspberry Pi  
Telegram-Bot-Befehle für Kalendertermine (khal), Tasks (todoman) und automatischen CalDAV-Sync (vdirsyncer).

---

## Schnellstart

```bash
# 1. .env befüllen
cp assets/.env.example .env && nano .env

# 2. Installation
chmod +x scripts/install.sh && bash scripts/install.sh

# 3. Selbsttest
bash scripts/test_setup.sh
```

---

## Projektstruktur

```
openclaw-mailbox-cal/
├── SKILL.md                     ← OpenClaw Skill-Definition
├── README.md                    ← Diese Datei
├── assets/
│   └── .env.example             ← Umgebungsvariablen-Vorlage
├── config/
│   ├── vdirsyncer.conf          ← vdirsyncer CalDAV-Konfiguration
│   ├── khal.conf                ← khal Kalender-Konfiguration
│   └── todoman.conf             ← todoman Aufgaben-Konfiguration
├── scripts/
│   ├── install.sh               ← Installations-Script (Raspi)
│   ├── test_setup.sh            ← Selbsttest aller Komponenten
│   └── openclaw_skill.py        ← OpenClaw/Telegram Bot Handler
└── systemd/
    ├── vdirsyncer-sync.service  ← systemd Service Unit
    ├── vdirsyncer-sync.timer    ← systemd Timer (alle 15 Min.)
    └── vdirsyncer-sync.env      ← Umgebungsvariablen für systemd
```

---

## Setup-Schritte (detailliert)

### Schritt 1 — Voraussetzungen

- Raspberry Pi mit Raspberry Pi OS Bookworm (64-bit empfohlen) oder Ubuntu 22.04+ ARM
- mailbox.org-Konto
- App-Passwort in mailbox.org anlegen:  
  `Einstellungen → Sicherheit → App-Passwörter → Neu erstellen`
- OpenClaw installiert: [openclaw.dev](https://openclaw.dev)
- Telegram Bot-Token via [@BotFather](https://t.me/BotFather)

### Schritt 2 — .env konfigurieren

```bash
cp assets/.env.example .env
nano .env
```

Mindestens diese Werte setzen:

```dotenv
MAILBOX_USER=vorname.nachname@mailbox.org
MAILBOX_PASS=app-passwort-xyz
```

### Schritt 3 — install.sh ausführen

```bash
chmod +x scripts/install.sh
bash scripts/install.sh
```

Das Script installiert automatisch:
- `vdirsyncer` — CalDAV-Sync-Tool
- `khal` — CLI-Kalender
- `todoman` — CLI-Aufgabenverwaltung
- `pass` — GNU Password Store
- `python3-keyring` — Python-Keyring-Integration
- `gettext-base` — envsubst für Konfigurationen

Anschließend:
- Alle Konfigurationsdateien werden deployed
- systemd User-Timer wird aktiviert
- Initialer Sync wird durchgeführt

### Schritt 4 — OpenClaw Skill registrieren

OpenClaw erkennt Skills **automatisch** wenn sie in einem der Skill-Verzeichnisse liegen.
Kein manueller Eintrag in `openclaw.json` nötig — das `install.sh` legt bereits einen Symlink an.

```bash
# Manuell (falls install.sh den Symlink nicht angelegt hat):
mkdir -p ~/.openclaw/skills
ln -s ~/mailbox-cal ~/.openclaw/skills/mailbox-cal
```

Optional — Zugangsdaten direkt in `~/.openclaw/openclaw.json` hinterlegen
(Alternative zur `.env`-Datei). **Immer zuerst Backup anlegen:**

```bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
```

Den bestehenden `"skills"`-Block in `openclaw.json` um `"entries"` ergänzen
(der Block sieht danach so aus):

```json
{
  "skills": {
    "install": {
      "nodeManager": "npm"
    },
    "entries": {
      "mailbox-cal": {
        "enabled": true,
        "env": {
          "MAILBOX_USER": "dein.name@mailbox.org",
          "MAILBOX_PASS": "app-passwort-xyz"
        }
      }
    }
  }
}
```

Nach jeder Änderung an `openclaw.json` validieren und Gateway neu starten:

```bash
openclaw doctor --fix
openclaw gateway restart
```

### Schritt 5 — Telegram testen

Sende an deinen Bot:
```
/termine
/aufgaben
/sync
/status
```

---

## Test-Befehle

### Vollständiger Selbsttest
```bash
bash scripts/test_setup.sh
```

### vdirsyncer
```bash
# Verbindung testen und Sammlungen entdecken
vdirsyncer discover calendars
vdirsyncer discover tasks

# Synchronisation manuell starten
vdirsyncer sync

# Nur Kalender synchronisieren
vdirsyncer sync calendars

# Verbose-Ausgabe
vdirsyncer -v DEBUG sync
```

### khal
```bash
# Termine heute
khal list

# Termine nächste 7 Tage
khal list today 7d

# Agenda-Ansicht
khal agenda

# Interaktiver Kalender
ikhal

# Ereignis hinzufügen (interaktiv)
khal new

# Ereignis direkt anlegen
khal new 2025-06-15 14:00 15:00 "Arzttermin" --calendar mailbox_kalender

# Cache neu aufbauen
khal rebuild-cache

# Konfiguration anzeigen
khal printformats
```

### todoman
```bash
# Alle offenen Aufgaben
todo list

# Alle Aufgaben inkl. erledigt
todo list --all

# Neue Aufgabe
todo new "Bericht schreiben"

# Aufgabe mit Fälligkeitsdatum
todo new --due 2025-06-30 "Bericht abgeben"

# Aufgabe mit Priorität (1=hoch, 9=niedrig)
todo new --priority 1 "Dringend: Server patchen"

# Aufgabe als erledigt markieren (ID aus 'todo list')
todo done 1

# Aufgabe löschen
todo delete 2

# Aufgaben-Listen anzeigen
todo lists
```

### systemd
```bash
# Timer-Status
systemctl --user status vdirsyncer-sync.timer

# Service manuell starten (einmaliger Sync)
systemctl --user start vdirsyncer-sync.service

# Alle User-Timer anzeigen
systemctl --user list-timers

# Live-Log verfolgen
journalctl --user -u vdirsyncer-sync.service -f

# Log der letzten 50 Zeilen
journalctl --user -u vdirsyncer-sync.service -n 50

# Timer deaktivieren
systemctl --user disable --now vdirsyncer-sync.timer
```

### Python-Skill direkt testen
```bash
python3 scripts/openclaw_skill.py
```

---

## mailbox.org CalDAV-Endpunkte

| Zweck | URL |
|---|---|
| CalDAV-Basis | `https://dav.mailbox.org/caldav/<USER>/` |
| Kalender-Sammlung | `https://dav.mailbox.org/caldav/<USER>/Kalender/` |
| Aufgaben-Sammlung | `https://dav.mailbox.org/caldav/<USER>/Aufgaben/` |
| CardDAV (Kontakte) | `https://dav.mailbox.org/carddav/<USER>/` |

Entdeckung aller Sammlungen:
```bash
curl -u "USER:PASS" -X PROPFIND https://dav.mailbox.org/caldav/ \
  -H "Depth: 1" -H "Content-Type: application/xml"
```

---

## Sicherheit

| Maßnahme | Status |
|---|---|
| App-Passwort statt Hauptpasswort | ✅ Empfohlen |
| vdirsyncer-Config: chmod 600 | ✅ Automatisch via install.sh |
| .env nicht in Git | ✅ In .gitignore eingetragen |
| HTTPS für CalDAV | ✅ dav.mailbox.org erzwingt TLS |
| pass(1)-Integration | Optional via `pass` + `python3-keyring` |

---

## Fehlerbehebung

**vdirsyncer: `[Errno 111] Connection refused`**  
→ Netzwerkverbindung prüfen: `ping dav.mailbox.org`

**vdirsyncer: `Conflict!`**  
→ Beide Seiten wurden geändert. Konflikt manuell lösen oder `conflict_resolution = "b wins"` in vdirsyncer.conf setzen.

**khal: `No calendars configured`**  
→ `khal rebuild-cache` ausführen; Pfad in `~/.config/khal/config` prüfen.

**todoman: `Error: No lists found`**  
→ `path`-Eintrag in `~/.config/todoman/config.cfg` prüfen; Verzeichnis `~/.local/share/vdirsyncer/tasks/` muss existieren und `.ics`-Dateien enthalten.

**systemd-Timer läuft nach Reboot nicht**  
→ `sudo loginctl enable-linger $USER` ausführen (User-Session ohne Login).

---

## Lizenz

MIT — Freie Nutzung, Veränderung und Weitergabe.