Clockodo Skill

Steuere Clockodo-Zeiterfassung direkt aus Clawdbot: Stoppuhr starten/stoppen, Zeiteinträge verwalten, Auswertungen abrufen.

Setup

1. API-Zugangsdaten holen

1. In Clockodo einloggen → Persönliche Daten → API-Schlüssel
2. E-Mail-Adresse und API-Key notieren

2. Environment Variables setzen

export CLOCKODO_EMAIL="deine@email.de"
export CLOCKODO_API_KEY="dein-api-key"
export CLOCKODO_APP_NAME="Clawdbot"  # optional

Am besten in ~/.zshrc oder ~/.bashrc eintragen, oder in Clawdbot config als environment.

Verwendung

Stoppuhr

Status prüfen (läuft gerade was?):

<skill>/scripts/clockodo.sh clock-status

Starten (benötigt Kunden-ID und Leistungs-ID):

<skill>/scripts/clockodo.sh clock-start <customers_id> <services_id> [projects_id] [text] [billable]

Stoppen:

<skill>/scripts/clockodo.sh clock-stop <entry_id>

Zeiteinträge

Auflisten (Zeitraum im ISO8601-Format):

<skill>/scripts/clockodo.sh entries-list "2026-01-01T00:00:00Z" "2026-01-31T23:59:59Z"

Einzelnen Eintrag abrufen:

<skill>/scripts/clockodo.sh entries-get <id>

Neuen Eintrag anlegen (JSON):

<skill>/scripts/clockodo.sh entries-add '{"customers_id":123,"services_id":456,"billable":1,"time_since":"2026-01-15T09:00:00Z","time_until":"2026-01-15T12:00:00Z","text":"Beschreibung"}'

Stammdaten

Kunden auflisten:

<skill>/scripts/clockodo.sh customers

Projekte auflisten (optional gefiltert nach Kunde):

<skill>/scripts/clockodo.sh projects [customers_id]

Leistungsarten auflisten:

<skill>/scripts/clockodo.sh services

Benutzer auflisten:

<skill>/scripts/clockodo.sh users

Eigene Daten:

<skill>/scripts/clockodo.sh me

Urlaubsanträge & Abwesenheiten

Alle Abwesenheiten auflisten:

<skill>/scripts/clockodo.sh absences [year]

Offene Urlaubsanträge (Status = 0/enquired):

<skill>/scripts/clockodo.sh absences-pending [year]

Einzelne Abwesenheit abrufen:

<skill>/scripts/clockodo.sh absence-get <id>

Urlaubsantrag freigeben:

<skill>/scripts/clockodo.sh absence-approve <id>

Urlaubsantrag ablehnen (optional mit Begründung):

<skill>/scripts/clockodo.sh absence-reject <id> [note]

Zeitkontrolle

Arbeitszeiten eines Users (Datum im Format YYYY-MM-DD):

<skill>/scripts/clockodo.sh worktimes <user_id> <since> <until>

Arbeitsziel:

<skill>/scripts/clockodo.sh worktime-target <user_id> [year]

Einträge eines Users:

<skill>/scripts/clockodo.sh entries-by-user <user_id> <since> <until>

Agent-Anweisungen

Typische Anfragen

"Starte Timer für [Projekt/Kunde]"

1. Hole Stammdaten wenn IDs unbekannt: customers, projects, services
2. Finde passende IDs
3. Starte mit clock-start

"Was läuft gerade?" / "Timer Status"

1. clock-status aufrufen
2. Wenn running null → nichts läuft
3. Sonst: Zeige Kunde, Projekt, Startzeit, Dauer

"Stoppe Timer"

1. clock-status für aktuelle Entry-ID
2. clock-stop <entry_id>

"Zeiteinträge heute/diese Woche/diesen Monat"

1. Berechne Zeitraum (ISO8601 UTC)
2. entries-list mit Zeitraum
3. Formatiere Ergebnis übersichtlich (Summen, nach Projekt gruppiert)

"Buche X Stunden auf Projekt Y"

1. Finde Kunden-/Projekt-/Leistungs-IDs
2. Berechne Start- und Endzeit
3. entries-add mit JSON

"Offene Urlaubsanträge" / "Wer will Urlaub?"

1. absences-pending aufrufen
2. Filtern nach status: 0 (enquired)
3. Übersichtlich formatieren: Name, Zeitraum, Typ, Tage

"Urlaubsantrag von [Name] freigeben"

1. absences-pending für offene Anträge
2. Antrag des Mitarbeiters finden
3. absence-approve <id>

"Haben alle Mitarbeiter ihre Zeiten eingetragen?" / "Zeitkontrolle"

1. users für Liste aller aktiven Mitarbeiter
2. Für jeden User: entries-by-user <id> <wochenstart> <wochenende>
3. Summe der Stunden berechnen (duration / 3600)
4. Mit Soll vergleichen (z.B. 40h oder aus worktime-target)
5. Fehlende Stunden markieren

Wöchentlicher Timesheet-Check (für Cron)

1. Hole alle User
2. Berechne letzte Woche (Mo-Fr)
3. Für jeden User: Prüfe gebuchte Stunden
4. Liste Mitarbeiter mit < X Stunden gebuchter Zeit
5. Sende Slack-Nachricht an säumige Mitarbeiter

Formatierung der Ausgabe

Zeiteinträge als kompakte Liste:

📅 Heute (Mo 27.01.2026)
━━━━━━━━━━━━━━━━━━━━━━━
• 09:00-12:00 (3h) – Kunde A / Projekt X – "Meeting"
• 13:00-17:30 (4,5h) – Kunde B / Projekt Y – "Entwicklung"
━━━━━━━━━━━━━━━━━━━━━━━
Gesamt: 7,5h

Laufender Timer:

⏱️ Timer läuft seit 14:23 (2h 15m)
   Kunde: Rockstardevelopers
   Projekt: Website Relaunch
   Leistung: Entwicklung

ID-Caching

Speichere häufig genutzte IDs in <workspace>/TOOLS.md unter ### Clockodo:

### Clockodo

**Kunden:**
- 12345 → Rockstardevelopers GmbH
- 12346 → accessibleAI SmartCompliance GmbH

**Projekte:**
- 67890 → RSD Website Relaunch
- 67891 → accessibleAI MVP

**Leistungen:**
- 111 → Entwicklung
- 112 → Meeting
- 113 → Support

Beim ersten Aufruf die Stammdaten abrufen und in TOOLS.md cachen.

Automatisierung: Wöchentlicher Timesheet-Check

Beispiel-Workflow für wöchentliche Zeiterfassungs-Kontrolle:

Setup (einmalig)

1. User-Mapping anlegen in <workspace>/TOOLS.md:

### Clockodo User → Slack

| User ID | Name | Slack ID | Soll-Stunden/Woche |
|---------|------|----------|-------------------|
| 12345 | Max Mustermann | U0ABC123 | 40 |
| 12346 | Erika Musterfrau | U0DEF456 | 32 |

2. Cron-Job erstellen (z.B. jeden Montag 10:00):
   • Prüfe Vorwoche
   • Slack-Erinnerung an Mitarbeiter mit < 90% Soll

Check-Logik

1. Berechne Zeitraum: Letzte Woche Mo 00:00 bis Fr 23:59
2. Für jeden aktiven User:
   a. entries-by-user <id> <start> <end>
   b. Summe = Σ(entry.duration) / 3600 Stunden
   c. Wenn Summe < (Soll * 0.9):
      → Slack-Nachricht: "Bitte Zeiten für letzte Woche nachtragen"
3. Report an Admin: Übersicht aller User + gebuchte Stunden

Absence-Status Codes

Absence-Typen

API-Referenz

Volle Dokumentation: https://www.clockodo.com/en/api/

Wichtige Endpunkte:

• /v2/clock – Stoppuhr steuern
• /v2/entries – Zeiteinträge CRUD
• /v2/customers – Kundenliste
• /v2/projects – Projektliste
• /v2/services – Leistungsarten
• /v2/users – Benutzerliste
• /v2/absences – Abwesenheiten
• /v2/worktimes – Arbeitszeiten

Authentifizierung:

• Header: X-ClockodoApiUser + X-ClockodoApiKey
• Plus: X-Clockodo-External-Application: AppName;email

Datumsformat: ISO 8601 UTC (z.B. 2026-01-27T14:30:00Z)