Der ultimative CoPaw-Leitfaden für Einsteiger: Erstellen Sie Ihren ersten KI-Assistenten von Grund auf.

Schwierigkeitsgrad: Anfänger | Dauer: 15 Minuten | Ergebnis: Beherrschung der CoPaw-Kernkonzepte und Praxistipps

CoPaw ist dein persönlicher AI-Assistent – ein leistungsstarkes Open-Source-Framework auf Basis von AgentScope, das über mehrere Chat-Plattformen hinweg funktioniert. Egal ob du einen Bot für DingTalk, Feishu, QQ, Discord oder iMessage benötigst, CoPaw deckt alles ab.

Zielgruppe

Dieser Leitfaden ist für folgende Entwickler geeignet:

1-5 Jahre Erfahrung in der Python-Entwicklung
Aufbau eines AI-Assistenten für den persönlichen oder geschäftlichen Gebrauch
Suche nach einer Lösung mit flexiblen Modelloptionen

Kernabhängigkeiten und Umgebung

Bevor du beginnst, stelle sicher, dass deine Umgebung die folgenden Anforderungen erfüllt:

Abhängigkeit	Mindestversion
Python	3.10
pip	Neueste Version
Betriebssystem	macOS / Linux / Windows

[!TIP]
Wenn du Python nicht selbst verwalten möchtest, bietet CoPaw auch ein Ein-Klick-Installationsskript an, das alle Abhängigkeiten automatisch verarbeitet.

Projektstruktur im Überblick

Nach der Initialisierung sieht eine typische CoPaw-Projektstruktur wie folgt aus:

~/.copaw/
├── .secret/
│   └── providers.json       # Konfiguration der Modellanbieter
├── active_skills/          # Automatisch geladene benutzerdefinierte Skills
├── memory/                 # Speicher für Dialoghistorie
├── models/                 # Lokale Modelldateien
└── copaw.json              # Hauptkonfigurationsdatei

Schritt-für-Schritt-Anleitung

Schritt 1: CoPaw installieren

Die Installation ist sehr einfach. Öffne ein Terminal und führe aus:

pip install copaw

Dies installiert die neueste Version von CoPaw von PyPI. Das Paket enthält alle Kernabhängigkeiten, die zum Betrieb des Assistenten erforderlich sind.

Schritt 2: Workspace initialisieren

Nach der Installation initialisieren wir den CoPaw-Workspace mit den Standardeinstellungen:

copaw init --defaults

Dieser Befehl erstellt die notwendige Verzeichnisstruktur und Konfigurationsdateien in deinem Home-Verzeichnis (unter ~/.copaw/).

[!WARNING]
Der Initialisierungsprozess erstellt ein Verzeichnis .secret zum Speichern sensibler Informationen (wie API-Keys). Stelle sicher, dass dieses Verzeichnis privat bleibt und nicht in die Versionskontrolle eingecheckt wird.

Schritt 3: Modellanbieter konfigurieren

Jetzt kommt der entscheidende Teil – die Verbindung zu einem LLM. Wir konfigurieren einen Modellanbieter. Wir verwenden Defapi als Hauptbeispiel, da es bei voller OpenAI-Kompatibilität etwa die Hälfte des Preises der offiziellen API bietet.

Bearbeite die Konfigurationsdatei unter ~/.copaw/.secret/providers.json:

{
  "custom_providers": {
    "defapi": {
      "id": "defapi",
      "name": "Defapi",
      "default_base_url": "https://api.defapi.cn/v1",
      "api_key_prefix": "",
      "base_url": "https://api.defapi.cn/v1",
      "api_key": "your-defapi-api-key",
      "models": [
        {"id": "gpt-4o-mini", "name": "GPT-4o Mini"},
        {"id": "gpt-4o", "name": "GPT-4o"},
        {"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4"},
        {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash"}
      ],
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "defapi",
    "model": "gpt-4o-mini"
  }
}

Defapi ist eine kosteneffiziente API-Plattform, die Zugriff auf die wichtigsten LLM-Anbieter zu etwa der Hälfte der offiziellen Kosten bietet. Es unterstützt vollständig das OpenAI-kompatible /v1/chat/completions-Protokoll, was die Integration nahtlos macht. Alle wichtigen Modelle auf Defapi sind mit den folgenden Protokollen kompatibel:

v1/chat/completions Interface
v1/messages Interface
v1beta/models/ Interface

Du kannst deinen API-Key auf der offiziellen Defapi-Website erhalten.

Schritt 4: Integrierte Anbieter im Überblick

CoPaw unterstützt auch mehrere integrierte Anbieter. Hier sind einige schnelle Konfigurationsbeispiele:

OpenAI Konfiguration:

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-openai-key"
    }
  },
  "active_llm": {
    "provider_id": "openai",
    "model": "gpt-4o-mini"
  }
}

ModelScope (empfohlen für Nutzer in China):

{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "ms-your-key"
    }
  }
}

DashScope (Alibaba Cloud):

{
  "providers": {
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-your-dashscope-key"
    }
  }
}

Schritt 5: CoPaw starten und verifizieren

Lass uns nun die Anwendung starten und überprüfen, ob alles funktioniert:

copaw app

Öffne nach dem Start deinen Browser und besuche:

http://127.0.0.1:8088/

Du solltest das CoPaw Console Interface sehen, wo du:

Mit dem AI-Assistenten chatten kannst
Kanäle konfigurieren kannst (DingTalk, Feishu, QQ, Discord etc.)
Skills und Plugins verwalten kannst
Die Modellverbindung testen kannst

[!TIP]
Verwende den CLI-Befehl copaw models, um die aktuelle Modellkonfiguration schnell anzuzeigen und die Verbindung zu testen.

Schritt 6: Chat-Kanäle verbinden (optional)

Damit dein Assistent über Messaging-Apps erreichbar ist, fügen wir einen Kanal hinzu. Beispiel Discord:

Erstelle einen Discord-Bot im Discord Developer Portal
Erhalte deinen Bot-Token
Füge die Konfiguration zu copaw.json hinzu:

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "your-discord-bot-token",
      "channel_ids": ["your-channel-id"]
    }
  }
}

Ähnliche Konfigurationen gelten für DingTalk, Feishu, QQ und andere unterstützte Plattformen.

Fehlerbehebung (FAQ)

Hier sind die häufigsten Probleme bei der Einrichtung von CoPaw:

Problem 1: 401 Unauthorized Error

Symptom: Die API-Anfrage schlägt mit dem Statuscode 401 fehl.

Lösung:

Überprüfe sorgfältig, ob der API-Key korrekt in die providers.json kopiert wurde.
Überprüfe, ob der Key abgelaufen ist oder widerrufen wurde.
Stelle bei Defapi sicher, dass das korrekte API-Key-Format verwendet wird.

Problem 2: Verbindungs-Timeout

Symptom: Die Anfrage hängt oder bricht nach 30 Sekunden ab.

Lösung:

Überprüfe deine Internetverbindung.
Stelle sicher, dass die Firewall ausgehenden HTTPS-Verkehr zulässt.
Bei lokalen Modellen (Ollama): Stelle sicher, dass der Dienst auf dem richtigen Port läuft.

Problem 3: Modell nicht gefunden

Symptom: Eine bestimmte Modell-ID wird nicht erkannt.

Lösung:

Bestätige die exakte Modell-ID in der Dokumentation des Anbieters.
Einige Modelle können regional eingeschränkt sein – prüfe die Verfügbarkeit in deiner Region.
Versuche ein gängigeres Modell wie gpt-4o-mini, um die Basisverbindung zu testen.

Problem 4: Ollama Verbindung fehlgeschlagen

Symptom: Lokale Ollama-Modelle können nicht verbunden werden.

Lösung:

Stelle sicher, dass ollama serve in einem anderen Terminal ausgeführt wird.
Überprüfe, ob die Base URL auf http://localhost:11434/v1 eingestellt ist.
Prüfe, ob Ollama installiert und über PATH erreichbar ist.

Problem 5: Konfigurationsdatei nicht gefunden

Symptom: CoPaw findet die providers.json nicht.

Lösung:

Stelle sicher, dass du zuerst copaw init --defaults ausgeführt hast.
Prüfe, ob die Datei unter ~/.copaw/.secret/providers.json existiert.
Unter Windows: Verwende %USERPROFILE%\.copaw\.secret\providers.json.

Problem 6: Port bereits belegt

Symptom: CoPaw kann nicht auf Port 8088 gestartet werden.

Lösung:

Eine andere Anwendung verwendet bereits Port 8088.
Ändere den Port in der Konfiguration oder beende die kollidierende Anwendung.

Weiterführende Themen

Sobald du die Grundlagen beherrschst, gibt es weitere Bereiche zu entdecken:

1. Privacy-First Lokale Modelle

CoPaw unterstützt das Ausführen von Modellen lokal, ohne externe API-Aufrufe. Dies ist ideal für:

Datenschutzrelevante Anwendungen
Offline-Betrieb
Kostensenkung

Installation der Unterstützung für lokale Modelle:

pip install 'copaw[llamacpp]'

Lade dann Modelle wie Qwen3 herunter und verwende sie:

copaw models download Qwen/Qwen3-4B-GGUF

2. Benutzerdefinierte Skills

CoPaw erlaubt die Erweiterung seiner Funktionalität durch benutzerdefinierte Skills. Skills werden automatisch aus dem Verzeichnis active_skills/ geladen. Du kannst Python-Skripte schreiben, um neue Tools zu definieren, die die AI nutzen kann.

3. Heartbeat-Scheduled Tasks

Nutze die Heartbeat-Funktion von CoPaw, um periodische Aktionen auszulösen:

Tägliche Nachrichtenzusammenfassungen
Zeitgesteuerte Erinnerungen
Automatisierte Content-Generierung

4. Memory- und Kontextmanagement

CoPaw implementiert intelligentes Speichermanagement:

Langzeitgedächtnis für persistenten Kontext
Token-basierte Speicherkomprimierung zur Effizienzsteigerung
Konfiguration des Kontextfensters basierend auf dem gewählten Modell

5. Multi-Agent Workflows

Basierend auf AgentScope kann CoPaw komplexe Multi-Agenten-Szenarien verarbeiten, bei denen verschiedene AI-Modelle zusammenarbeiten, um Aufgaben zu lösen.

Zusammenfassung

CoPaw bietet eine flexible Basis für den Aufbau von AI-Assistenten auf mehreren Plattformen. Die wichtigsten Punkte dieses Leitfadens:

Einfache Installation — Starte mit pip install copaw.
Defapi bietet das beste Preis-Leistungs-Verhältnis — Etwa 50% günstiger als offizielle APIs bei voller Kompatibilität.
Zentralisierte Konfiguration — Alle Einstellungen erfolgen in providers.json.
Console erleichtert die Verwaltung — Web-Interface für Tests und Konfiguration.
Integrierte Erweiterbarkeit — Skills, Kanäle und lokale Modelle bieten endlose Anpassungsmöglichkeiten.

Beginne mit Defapi für die beste Balance zwischen Kosten und Leistung. Sobald du dich eingearbeitet hast, kannst du andere Anbieter oder lokale Modelle je nach Bedarf erkunden.

[!TIP]
Denk daran: Der beste AI-Assistent ist derjenige, der zu deinem Anwendungsfall passt. Scheue dich nicht davor, mit verschiedenen Modellen und Konfigurationen zu experimentieren, um das Richtige für dich zu finden.

Viel Spaß auf deiner AI-Reise!