FAQ

Häufige Fragen zu TaskMonkey und dem CLI-Workflow.

#Allgemein

#Ich habe die Plattform, aber keine CLI. Wo kriege ich die her?

npm install -g taskmonkey-cli

Siehe TaskMonkey CLI. Benötigt Node.js 18+.

#Wo liegt meine .tmrc?

Im Verzeichnis, in dem du tm login ausgeführt hast. Alle anderen tm-Commands suchen sie aufwärts im Pfad — du kannst also in Unterordnern arbeiten.

#Ich bekomme Not logged in. Run tm login first.

• .tmrc existiert nicht → tm login
• .tmrc existiert, aber Token abgelaufen → tm login neu
• Du bist im falschen Verzeichnis — prüfe, ob .tmrc oberhalb existiert

#Kann ich mehrere Workspaces parallel bearbeiten?

Ja. Jeder Workspace = eigener Ordner mit eigener .tmrc. Wechsle einfach ins passende Verzeichnis und arbeite.

#Tools

#Ein Tool wird nie aufgerufen, obwohl die Frage passt.

Checkliste:

1. Steht das Tool in der tools-Liste des aktiven Tasks?
2. Ist die description klar? Zu generisch → Modell erkennt den Anlass nicht.
3. Sagt der System-Prompt, wann das Tool aufzurufen ist? (Expliziter Hinweis hilft massiv.)
4. Probiere tm test-chat "die Frage" --task <slug> — siehst du im Output, welches Tool aufgerufen wurde (oder ob gar keins)?

#Ein Tool bekommt falsche Argumente.

• description in parameters.properties zu vage? Mach sie expliziter.
• Benutzer hat unklar formuliert? Das Tool mit einem preprocess normalisieren.
• Ein required Feld zu viel? Mach es optional und setze einen Default im Preprocess.

#tm test-tool gibt 401/403.

Bei OAuth-APIs: Verbindung unter /manage/o-auth-connections abgelaufen — neu verbinden. Bei API-Key-APIs: Env-Variable auf dem Server prüfen (Betreiber).

#Wie viele Tools kann ein Task haben?

Technisch kein hartes Limit. Praktisch:

• 5–15 pro Task ist der Sweet Spot
• Ab 20+ wird das Modell schlechter im Wählen
• Wenn du mehr brauchst: Tools zusammenfassen (ein generisches listX mit Filter statt zehn spezifische)

#Assistenten

#Mein neuer Task taucht nicht im Dashboard auf.

1. tm sync durchgelaufen? (Fehler im Output?)
2. tm tasks — ist er in der Liste?
3. Dateiname startet mit _? Dann ist er bewusst versteckt.
4. Beim Dashboard: Browser-Cache leeren oder Hard Reload.

#Ein Assistant-Prompt aktualisiert sich nicht.

System-Prompts werden bei jeder Anfrage frisch aus der Config geladen — kein Cache-Problem von deiner Seite. Wenn du glaubst, der alte Prompt wirkt noch: tm history --task <slug> zeigt dir, was das Modell in letzter Zeit gesehen hat.

#Mehrere Tasks mit ähnlichem Prompt — wie DRY halten?

prompts/-Ordner mit Snippets. Siehe prompts/.

#Scheduled Tasks

#Wie weiß ich, ob mein Scheduled Task läuft?

tm monitor

Scheduled Runs erscheinen mit Typ CRON. Falls du seit Tagen nichts siehst: enabled => true vergessen? tm sync nach Änderung durchgelaufen?

#Mein Scheduled Task läuft doppelt.

Passiert selten, aber: baue idempotente Handler. Idealerweise prüft das Tool am Anfang, ob der Job schon erledigt ist (z. B. „existiert Report für heute schon?"). Wenn ja → sofort zurückkehren.

#Zeitzone?

Die Plattform läuft in der Betreiber-Zeitzone. Bei 10:00 meint das die Serverzeit. Frage den Betreiber, welche Zone aktiv ist (typisch Europe/Berlin).

#Chat

#Der Chat ist abgeschnitten oder „vergisst".

Das Modell sieht maximal die letzten 50 Nachrichten. Bei sehr langen Sessions geht früher Verlauf verloren. Workaround: wichtige Informationen explizit in den System-Prompt oder als Reminder setzen.

#SSE-Stream bricht ab.

• nginx: proxy_buffering off; für die /chat/stream-Location
• CloudFlare: Rocket Loader deaktivieren
• Client-Code: richtiges EventSource-Event-Handling, auch error-Events behandeln

#Dateiuploads gehen nicht.

• Upload zu groß? PHP upload_max_filesize / post_max_size prüfen (Betreiber)
• Format nicht unterstützt? Siehe Datei-Uploads

#Knowledge Bases

#Die KB findet nichts, obwohl der Inhalt da ist.

• min_score zu hoch? In den Tool-options senken.
• Query war sehr spezifisch, die Entries aber anders formuliert → Entry-keywords ergänzen.
• Volltext-Index wurde nicht gebaut? Passiert sehr selten — Betreiber kontaktieren.

#Wie viele Entries sind ok?

Volltext-Suche performt bis in den niedrigen fünfstelligen Bereich. Darüber: eventuell KB aufteilen oder andere Such-Strategie überlegen.

#Integrationen

#Google gibt insufficient_scope zurück.

OAuth-Scope fehlt. /manage/o-auth-connections → Verbindung → Neu verbinden → weiteren Scope akzeptieren.

#Rate-Limit-Fehler (429).

• Scheduled Task zu häufig → interval erhöhen
• Viele parallele User → im Tool Backoff-Logik einbauen

#Custom API antwortet, wie sie nicht sollte.

TaskMonkey leitet nur durch. Reproduziere den Request mit curl oder Postman — wenn der Fehler dort auch da ist, liegt's an der API, nicht an TaskMonkey.

#Workflow

#Ich habe Angst, produktive Daten zu schrotten.

Gute Angst. Standard-Schutz:

• --dry-run bei tm test-tool für schreibende Tools
• Neue Tasks mit beabsichtigten Nebenwirkungen erst mit Testaccount anlegen
• Scheduled Tasks: erst mit enabled => false rein, manuell per tm test-tool mehrfach verifizieren, dann aktivieren
• Git: alles commiten vor tm sync --delete

#Was committe ich, was nicht?

• commiten: apis.php, assistants/, prompts/, tools/, scheduled.php, public.php
• NICHT commiten: .tmrc, logs/, tmp/, node_modules/, .DS_Store

Typische .gitignore:

.tmrc
logs/
tmp/
node_modules/
.DS_Store

#Kann ich Workspace-Konfig per CI deployen?

Grundsätzlich ja. Das CLI ist scriptbar (tm sync + Exit-Code). Für CI-Workflows brauchst du einen nicht-interaktiven Login-Mechanismus (z. B. Service-Token vom Betreiber). Mit ihm kommuniziert das CI statt tm login.

Sprich mit deinem Betreiber, ob Service-Tokens verfügbar sind.

#Sonstiges

#Wie melde ich einen Bug?

• An den Betreiber (Support-Mail, Ticket-System)
• Wenn möglich mit: Tool-Name, Args, Output, Zeitstempel
• tm logs --lines 200 > log.txt beifügen, wenn Logs beteiligt

#Kann ich Feedback zu diesem Handbuch geben?

Ja — sag dem Betreiber, was unklar oder fehlend ist. Das Handbuch ist Teil der Plattform und wird gepflegt.