---
name: mailbox-cal
description: "OpenClaw Telegram-Bot-Skill für mailbox.org Kalender und Aufgaben auf dem Raspberry Pi. Synchronisiert CalDAV-Kalender und VTODO-Aufgaben via vdirsyncer, zeigt Termine mit khal und verwaltet Tasks mit todoman. Befehle: /termine, /aufgaben, /neu_aufgabe, /sync, /status. Lade diesen Skill wenn: der Nutzer Kalender-Einträge oder Aufgaben aus mailbox.org per Telegram abfragen, anlegen oder synchronisieren möchte."
license: MIT
compatibility: "Raspberry Pi OS Bookworm / Ubuntu 22.04+ ARM. Benötigt: vdirsyncer >= 0.19, khal >= 0.11, todoman >= 4.3, python3 >= 3.10. mailbox.org CalDAV-Zugang erforderlich."
metadata:
  author: lonely.wolf.64
  version: '1.0'
  platform: Raspberry Pi
  caldav_server: mailbox.org
---

# mailbox.org Kalender + Aufgaben Skill

## Übersicht

Dieser OpenClaw-Skill synchronisiert deinen mailbox.org-Kalender und deine Aufgaben über CalDAV auf einen Raspberry Pi und stellt sie über Telegram-Bot-Befehle bereit. Die Synchronisation läuft automatisch alle 15 Minuten via systemd-Timer.

**Architektur:**
```
mailbox.org (CalDAV)
      │
  vdirsyncer (Sync)
      │
  ┌───┴───────────┐
  │               │
 khal          todoman
(Kalender)    (Aufgaben)
  │               │
  └───────┬───────┘
          │
    openclaw_skill.py
          │
     Telegram Bot
```

## Unterstützte Befehle

| Telegram-Befehl | Beschreibung | Beispiel |
|---|---|---|
| `/termine` | Heutige Termine | `/termine heute` |
| `/termine morgen` | Morgige Termine | `/termine morgen` |
| `/termine woche` | Termine nächste 7 Tage | `/termine woche` |
| `/aufgaben` | Offene Aufgaben | `/aufgaben` |
| `/aufgaben alle` | Alle Aufgaben inkl. erledigt | `/aufgaben alle` |
| `/neu_aufgabe` | Neue Aufgabe anlegen | `/neu_aufgabe Arzt anrufen` |
| `/sync` | Manuellen Sync auslösen | `/sync` |
| `/status` | Sync-Timer-Status | `/status` |

## Voraussetzungen

- Raspberry Pi mit Raspberry Pi OS Bookworm oder Ubuntu 22.04+ ARM
- mailbox.org-Konto mit CalDAV-Zugang
- OpenClaw installiert und konfiguriert
- Telegram Bot-Token (via @BotFather)
- Internetverbindung vom Raspberry Pi

## Installation

### 1. Repository klonen

```bash
git clone https://github.com/DEIN_USER/openclaw-mailbox-cal.git
cd openclaw-mailbox-cal
```

### 2. .env befüllen

```bash
cp assets/.env.example .env
nano .env
# MAILBOX_USER und MAILBOX_PASS setzen
```

**Empfehlung:** Lege in mailbox.org ein App-Passwort an:
Einstellungen → Sicherheit → App-Passwörter → Neu erstellen

### 3. Installation ausführen

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

Das Script führt folgende Schritte aus:
1. Pakete installieren: `vdirsyncer khal todoman pass python3-keyring gettext-base`
2. Konfigurationsdateien deployen (mit envsubst)
3. systemd User-Timer aktivieren
4. Initialen Sync durchführen
5. khal-Datenbank aufbauen
6. OpenClaw Skill verknüpfen

### 4. Skill in OpenClaw registrieren

OpenClaw erkennt Skills automatisch aus diesen Verzeichnissen (höchste Priorität zuerst):
- `<workspace>/skills/`
- `~/.openclaw/skills/`
- bundled skills

Skill-Verzeichnis ins OpenClaw-Skills-Verzeichnis kopieren oder verlinken:

```bash
# Option A: Symlink (empfohlen — Updates wirken sofort)
mkdir -p ~/.openclaw/skills
ln -s ~/mailbox-cal ~/.openclaw/skills/mailbox-cal

# Option B: Kopieren
cp -r ~/mailbox-cal ~/.openclaw/skills/mailbox-cal
```

Optional: Zugangsdaten direkt in `~/.openclaw/openclaw.json` hinterlegen
(nur nötig für env-Variablen oder explizites enable/disable).
Den bestehenden `"skills"`-Block um `"entries"` ergänzen:

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

**Wichtig:** Unbekannte Keys lassen den OpenClaw-Gateway nicht starten.
Vor dem Bearbeiten immer ein Backup anlegen:
```bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# Nach der Bearbeitung validieren:
openclaw doctor --fix
```

Danach Gateway neu starten:
```bash
openclaw gateway restart
```

## Test-Befehle

Nach der Installation Setup validieren:

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

# Einzeltests
vdirsyncer sync                                  # Sync testen
khal list today tomorrow                         # Termine heute + morgen
khal list --format "{start} {title}" 2025-01-01 2025-12-31  # Jahresübersicht
todo list                                        # Aufgaben anzeigen
todo list --all                                  # Alle inkl. erledigt
todo new "Test-Aufgabe"                         # Aufgabe anlegen

# systemd Timer
systemctl --user status vdirsyncer-sync.timer   # Timer-Status
systemctl --user list-timers                    # Alle Timer
journalctl --user -u vdirsyncer-sync.service -f  # Live-Log

# Python-Skill direkt testen (ohne OpenClaw/Telegram)
python3 scripts/openclaw_skill.py
```

## Konfigurationsdateien

| Datei | Ziel-Pfad | Beschreibung |
|---|---|---|
| `config/vdirsyncer.conf` | `~/.config/vdirsyncer/config` | CalDAV-Sync-Konfiguration |
| `config/khal.conf` | `~/.config/khal/config` | Kalender-Anzeige-Konfiguration |
| `config/todoman.conf` | `~/.config/todoman/config.cfg` | Aufgaben-Konfiguration |
| `systemd/vdirsyncer-sync.service` | `~/.config/systemd/user/` | Sync-Service Unit |
| `systemd/vdirsyncer-sync.timer` | `~/.config/systemd/user/` | 15-Minuten-Timer |
| `scripts/openclaw_skill.py` | (in-place) | OpenClaw/Telegram-Integration |

## Sicherheitshinweise

- Die vdirsyncer-Config (`~/.config/vdirsyncer/config`) enthält das Passwort — Berechtigungen sind `chmod 600`
- Verwende ein mailbox.org App-Passwort statt des Hauptpassworts
- Für produktive Umgebungen: `pass`-Integration (GNU Password Store) via `pass` + `python3-keyring`
- `.env`-Datei niemals in Git committen (ist in `.gitignore` eingetragen)

## Fehlerbehebung

### vdirsyncer discover schlägt fehl
```bash
# Verbindung testen
curl -u "USER:PASS" https://dav.mailbox.org/caldav/
# SSL-Zertifikate prüfen
openssl s_client -connect dav.mailbox.org:443
```

### khal zeigt keine Termine
```bash
# Cache neu aufbauen
khal rebuild-cache
# Config validieren
khal printformats
```

### systemd-Timer läuft nicht
```bash
# Lingering aktivieren (damit User-Units ohne Login laufen)
sudo loginctl enable-linger pi
# Timer manuell starten
systemctl --user start vdirsyncer-sync.service
```

### Todoman findet keine Aufgaben
```bash
# Pfad in config prüfen
cat ~/.config/todoman/config.cfg
# Verzeichnis prüfen
ls ~/.local/share/vdirsyncer/tasks/
```

## Erweiterungen

- **Mehrere Kalender:** Weitere `[[kalender_name]]`-Sektionen in `khal.conf` hinzufügen
- **Push-Sync:** mailbox.org unterstützt CalDAV-Push — XMPP-Trigger via `vdirsyncer`
- **Erinnerungen:** Integration mit `khal-remind` oder `at`-Daemon
- **Verschlüsselung:** `.env` via `gpg-agent` verschlüsseln