Commit 546dd5
2026-04-08 20:55:40 Wiki: Add CT 118 PaperclipAI article| /dev/null .. ct-118-paperclipai.md | |
| @@ 0,0 1,277 @@ | |
| + | # CT 118 – PaperclipAI |
| + | |
| + | > [!NOTE] |
| + | > CT 118 hostet **PaperclipAI** – eine Open-Source Multi-Agent-Orchestrierungsplattform, die KI-Agenten (Claude Code) als autonome "Mitarbeiter" in virtuellen Unternehmen koordiniert. Zugriff über `https://agent.ls-cloud.biz` (Login erforderlich). |
| + | |
| + | ## Basisdaten |
| + | |
| + | | Eigenschaft | Wert | |
| + | |---|---| |
| + | | **CT-ID** | `118` | |
| + | | **Name** | `paperclipai` | |
| + | | **IP** | `192.168.178.88` | |
| + | | **OS** | Debian 12 (Bookworm) | |
| + | | **RAM** | 2048 MB | |
| + | | **Disk** | 20 GB | |
| + | | **Web-UI (intern)** | `http://192.168.178.88:3101` | |
| + | | **Web-UI (extern)** | `https://agent.ls-cloud.biz` | |
| + | | **Service** | `paperclipai.service` (User: `paperclip`) | |
| + | | **Node.js** | v20.20.2 | |
| + | | **PaperclipAI** | v2026.403.0 | |
| + | | **Claude Code** | v2.1.96 | |
| + | | **Auth** | Caddy basic_auth + PaperclipAI-eigene Accounts | |
| + | |
| + | --- |
| + | |
| + | ## Was ist PaperclipAI? |
| + | |
| + | PaperclipAI ist eine **Agentenorchestrierung** – du erstellst virtuelle Unternehmen mit KI-Agenten (hier: Claude Code), die eigenständig Code schreiben, Bugs fixen, Tasks ausführen und dabei ein Monatsbudget einhalten. |
| + | |
| + | **Kernkonzepte:** |
| + | |
| + | | Begriff | Bedeutung | |
| + | |---|---| |
| + | | **Company** | Virtuelles Unternehmen – Container für Agenten und Projekte | |
| + | | **Agent** | KI-Worker (hier Claude Code) – führt Tasks autonom aus | |
| + | | **Job** | Einzelner Auftrag / Prompt, den ein Agent bearbeitet | |
| + | | **Budget** | Monatliches Kostenlimit pro Agent (verhindert Kontrollverlust) | |
| + | | **Plugin** | Erweiterung für Agenten (z.B. GitHub, Jira-Integration) | |
| + | |
| + | --- |
| + | |
| + | ## Einrichtung – Schritt für Schritt |
| + | |
| + | ### 1. Dashboard öffnen |
| + | |
| + | Öffne `https://agent.ls-cloud.biz` im Browser. |
| + | |
| + | Login mit Caddy-Credentials → danach erscheint das PaperclipAI-Dashboard. |
| + | |
| + | > [!NOTE] |
| + | > Beim ersten Aufruf nach Installation erscheint ein **Bootstrap-Wizard** um den ersten Admin-Account anzulegen. E-Mail + Passwort eingeben → Account wird erstellt. |
| + | |
| + | --- |
| + | |
| + | ### 2. Ersten Account anlegen (Bootstrap) |
| + | |
| + | Falls noch kein Account existiert: |
| + | |
| + | 1. `https://agent.ls-cloud.biz` aufrufen |
| + | 2. **"Create Account"** oder Bootstrap-Formular ausfüllen |
| + | 3. E-Mail + Passwort festlegen |
| + | 4. Du bist jetzt Admin |
| + | |
| + | > [!TIP] |
| + | > Nach dem ersten Account empfiehlt es sich, in den Einstellungen die freie Registrierung zu deaktivieren – sonst kann sich jeder mit dem Caddy-Passwort auch einen PaperclipAI-Account anlegen. |
| + | |
| + | --- |
| + | |
| + | ### 3. Company erstellen |
| + | |
| + | Eine **Company** ist der Arbeitsraum. Jedes Projekt / jeder Themenkomplex kann eine eigene Company sein. |
| + | |
| + | 1. Im Dashboard auf **"New Company"** klicken |
| + | 2. Name vergeben (z.B. `Homelab Automation`) |
| + | 3. Optional: Beschreibung |
| + | 4. **"Create"** → Company ist angelegt |
| + | |
| + | Du landest automatisch im Company-Dashboard. |
| + | |
| + | --- |
| + | |
| + | ### 4. Agent hinzufügen |
| + | |
| + | Ein Agent ist die Verbindung zu Claude Code (dem eigentlichen KI-Worker). |
| + | |
| + | 1. In der Company auf **"Agents"** → **"Add Agent"** |
| + | 2. **Name** vergeben (z.B. `claude-engineer`) |
| + | 3. **Adapter** wählen: `claude_local` |
| + | 4. **Monatliches Budget** setzen (z.B. `$10.00`) – schützt vor unkontrollierten Kosten |
| + | 5. Optional: **Working Directory** – Verzeichnis in dem Claude Code arbeitet |
| + | 6. **"Save"** → Agent ist registriert |
| + | |
| + | > [!WARNING] |
| + | > Ohne Budget-Limit läuft der Agent unbegrenzt. Für Homelab-Nutzung reichen $5–$20/Monat je nach Nutzungsintensität. |
| + | |
| + | --- |
| + | |
| + | ### 5. Ersten Job erstellen (Agent beauftragen) |
| + | |
| + | Jobs sind die eigentlichen Aufgaben, die du dem Agenten gibst. |
| + | |
| + | 1. Im Company-Dashboard auf **"New Job"** klicken |
| + | 2. **Agent auswählen** (den gerade angelegten) |
| + | 3. **Prompt eingeben** – so präzise wie möglich, z.B.: |
| + | |
| + | ``` |
| + | Analysiere das Verzeichnis /opt/myapp und finde alle Stellen wo |
| + | SQL-Queries direkt aus User-Input gebaut werden. Liste die Dateien |
| + | und Zeilennummern auf und erkläre das Risiko. |
| + | ``` |
| + | |
| + | 4. Optional: **Kontext-Dateien** anhängen |
| + | 5. **"Start Job"** → Agent beginnt die Arbeit |
| + | |
| + | Der Job erscheint in der Job-Liste mit Status `running`. Du siehst in Echtzeit die Ausgabe des Agenten. |
| + | |
| + | --- |
| + | |
| + | ### 6. Job-Ausgabe lesen |
| + | |
| + | Während und nach dem Job: |
| + | |
| + | - **Live-Output**: Claude Codes Nachrichten erscheinen in Echtzeit im Job-Detail |
| + | - **Tool-Calls**: Jede Datei die gelesen/geschrieben wird, jeder Bash-Befehl – alles sichtbar |
| + | - **Status**: `running` → `completed` / `failed` |
| + | - **Kosten**: Werden nach Abschluss gegen das Budget gebucht |
| + | |
| + | --- |
| + | |
| + | ### 7. Mehrere Agenten & Arbeitsteilung |
| + | |
| + | Du kannst mehrere Agenten in einer Company anlegen und ihnen verschiedene Rollen geben: |
| + | |
| + | | Agent-Name | Working Dir | Aufgabe | |
| + | |---|---|---| |
| + | | `frontend-dev` | `/opt/webapp/frontend` | React/CSS Änderungen | |
| + | | `backend-dev` | `/opt/webapp/api` | API-Entwicklung | |
| + | | `devops` | `/opt/infra` | Server/Config-Verwaltung | |
| + | |
| + | Jeder Agent hat sein eigenes Budget. So lässt sich Kosten pro Bereich tracken. |
| + | |
| + | --- |
| + | |
| + | ### 8. Plugins & Integrationen |
| + | |
| + | Unter **Settings → Plugins** kannst du Erweiterungen aktivieren: |
| + | |
| + | - **GitHub**: Agent öffnet automatisch PRs für seine Änderungen |
| + | - **Jira / Linear**: Tasks aus Ticketsystem als Job-Quelle |
| + | - **Webhook**: Externe Trigger für Jobs (z.B. aus CI/CD Pipeline) |
| + | |
| + | Plugins werden pro Agent oder global aktiviert. |
| + | |
| + | --- |
| + | |
| + | ## Tägliche Nutzung |
| + | |
| + | ### Neuen Job starten |
| + | **Company** → **"New Job"** → Agent wählen → Prompt schreiben → **"Start"** |
| + | |
| + | ### Job-Status prüfen |
| + | **Company** → **"Jobs"** → Job anklicken → Live-Output + Kostenübersicht |
| + | |
| + | ### Budget-Verbrauch prüfen |
| + | **Company** → **"Agents"** → Agent anklicken → Budget-Chart (verbraucht / verbleibend) |
| + | |
| + | ### Agent temporär pausieren |
| + | **Agents** → Agent → **"Disable"** → Agent nimmt keine neuen Jobs an |
| + | |
| + | --- |
| + | |
| + | ## Überwachung & Wartung |
| + | |
| + | ### Service-Status |
| + | |
| + | ```bash |
| + | ssh root@192.168.178.88 |
| + | systemctl status paperclipai |
| + | ``` |
| + | |
| + | ### Logs |
| + | |
| + | ```bash |
| + | # Systemd-Journal |
| + | journalctl -u paperclipai -f |
| + | |
| + | # PaperclipAI eigene Logs |
| + | tail -f /home/paperclip/.paperclip/instances/default/logs/*.log |
| + | ``` |
| + | |
| + | ### Neustart |
| + | |
| + | ```bash |
| + | systemctl restart paperclipai |
| + | ``` |
| + | |
| + | ### Claude OAuth-Token erneuern (falls abgelaufen) |
| + | |
| + | ```bash |
| + | ssh root@192.168.178.88 |
| + | su - paperclip |
| + | claude logout |
| + | claude login |
| + | # URL kopieren → im Browser öffnen → Pro-Account einloggen |
| + | ``` |
| + | |
| + | Danach Credentials wieder für den paperclip User verfügbar machen: |
| + | ```bash |
| + | cp /root/.claude/.credentials.json /home/paperclip/.claude/.credentials.json |
| + | chown paperclip:paperclip /home/paperclip/.claude/.credentials.json |
| + | systemctl restart paperclipai |
| + | ``` |
| + | |
| + | ### PaperclipAI updaten |
| + | |
| + | ```bash |
| + | ssh root@192.168.178.88 |
| + | su - paperclip |
| + | npm install -g paperclipai@latest |
| + | systemctl restart paperclipai |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## Architektur im Überblick |
| + | |
| + | ``` |
| + | Browser |
| + | └── https://agent.ls-cloud.biz |
| + | └── Caddy (Proxmox Host, basic_auth) |
| + | └── nginx CT 118 :3101 |
| + | └── PaperclipAI :3100 (127.0.0.1, User: paperclip) |
| + | └── embedded PostgreSQL :54329 |
| + | └── claude_local Adapter |
| + | └── Claude Code (/usr/bin/claude) |
| + | └── OAuth → Claude Pro Plan |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## Wichtige Pfade |
| + | |
| + | | Pfad | Inhalt | |
| + | |---|---| |
| + | | `/home/paperclip/.paperclip/instances/default/config.json` | Hauptkonfiguration | |
| + | | `/home/paperclip/.paperclip/instances/default/db/` | PostgreSQL Daten | |
| + | | `/home/paperclip/.paperclip/instances/default/logs/` | Logs | |
| + | | `/home/paperclip/.paperclip/instances/default/data/backups/` | Automatische DB-Backups | |
| + | | `/home/paperclip/.claude/.credentials.json` | Claude OAuth-Token | |
| + | | `/etc/systemd/system/paperclipai.service` | Systemd Service | |
| + | | `/etc/nginx/sites-enabled/paperclipai` | nginx Proxy-Config | |
| + | |
| + | --- |
| + | |
| + | ## Schnellcheck |
| + | |
| + | ```bash |
| + | # Container läuft? |
| + | ssh root@192.168.178.46 "pct status 118" |
| + | |
| + | # Service läuft? |
| + | ssh root@192.168.178.88 "systemctl status paperclipai --no-pager | head -5" |
| + | |
| + | # API erreichbar? |
| + | curl -s http://192.168.178.88:3101/api/health | python3 -m json.tool |
| + | |
| + | # HTTPS mit Auth? |
| + | curl -sk -u 'xclusive:PASSWORT' https://agent.ls-cloud.biz/api/health |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | > [!TIP] |
| + | > Claude Code arbeitet im **Home-Verzeichnis des paperclip-Users** (`/home/paperclip`), sofern kein Working Directory im Agent gesetzt ist. Für produktive Nutzung immer ein konkretes Projektverzeichnis als Working Directory angeben. |
| + | |
| + | > [!WARNING] |
| + | > PaperclipAI läuft im Modus `local_trusted` – das bedeutet die App vertraut allen Requests die über localhost kommen **ohne zusätzliche Token-Prüfung**. Deshalb ist der Caddy `basic_auth` davor zwingend notwendig und darf nicht entfernt werden. |