MagiClaw für den Einstieg: Das KI-Forschungs-Agententeam in Feishu – Zusammenarbeit entsteht ganz natürlich

In nur 15 Minuten konfiguriert｜Feishu-native Erfahrung｜Forschungs-Agent-Orchestrierung｜EvoMaster-Basis mit einem Klick erweitern

---

Projektüberblick

MagiClaw ist eine KI-Agenten-Plattform, die direkt in Feishu läuft. Der Kernansatz lautet: Kein weiteres eigenständiges Tool, das du extra öffnen musst. Stattdessen bindest du KI-Agenten direkt in Feishu ein – deinem Alltagstool. Du beschreibst Anforderungen im Gruppenchat oder im privaten Chat, und das Agententeam beginnt sofort zu arbeiten.

Hinter MagiClaw steht das EvoMaster-Framework: eine leichte Agent-Infrastruktur, die für Tool-Aufrufe, Skills, das Speichermanagement und das „Routing“ von Sitzungen zuständig ist. Das bedeutet: Du kannst dich darauf konzentrieren, „was“ die Agenten tun sollen – statt den Engineering-Overhead immer wieder neu aufzubauen. Das Projekt ist Open Source (Apache-2.0-Lizenz), die Codebasis ist klein und lässt sich gut weiterentwickeln.

---

Zielgruppe

Dieser Artikel richtet sich an folgende Entwickler:

• Du kennst dich mit Python aus, bist mit Feishu- oder Lark-Kollaborationstools vertraut und möchtest KI-Funktionen direkt in die alltägliche Teamkommunikation integrieren
• Du interessierst dich für „AI for Science“-Szenarien und suchst nach einem erweiterbaren Framework für Forschungs-Agenten
• Du nutzt bereits EvoMaster oder ein ähnliches Agent-Framework und möchtest Feishu als Frontend-Interaktionsschicht erweitern

Wenn du nach einem eigenständigen „Forschungs-Agenten-All-in-one“-Paket suchst, ist MagiClaw nicht genau das – es ist die Verbindung der EvoMaster-Ökologie mit Feishu, sodass wissenschaftliche Workflows in den Kommunikationstools deines Teams ganz natürlich „mitlaufen“.

---

Zentrale Abhängigkeiten und Umgebung

---

Vollständiger Projekt-Ordnerbaum

MagiClaw/
├── evomaster/                    # Kern-Framework-Bibliothek
│   ├── agent/                   # Agent-Grundklasse und Laufzeit
│   ├── core/                    # Kern-Tool-Aufrufe, Task-Planung
│   ├── interface/
│   │   └── feishu/             # Feishu-Schnittstelle (Long Connection, Webhook)
│   ├── memory/                  # Persistenter Speicher
│   ├── skills/                  # Wiederverwendbare Skill-Pakete
│   └── scheduler/               # Multi-Task-Dispatcher
├── playground/
│   ├── magiclaw/               # Standardmäßiger Feishu-Dialog-Agent
│   ├── agent_builder/           # Meta-Agent: Design / Erstellung neuer Agents
│   ├── coding_agent/            # Agent für Code-Erstellung
│   ├── report_writer_agent/     # Agent für das Verfassen von Berichten
│   └── web_search_agent/        # Agent für Websuche
├── configs/
│   ├── feishu/                  # Feishu-Bot-Verbindungs-Credentials
│   │   └── config.yaml
│   ├── magiclaw/               # LLM-, Tool-, MCP- und Memory-Konfiguration
│   │   └── config.yaml
│   └── agent_builder/           # Konfiguration für Planen + Bau zweier Agents
├── run.py                       # CLI-Schnellstart-Entrypoint
├── requirements.txt
└── pyproject.toml

---

Schritt-für-Schritt Installation

Schritt 1: Code klonen

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

Schritt 2: Abhängigkeiten installieren

pip install -r requirements.txt

Oder mit uv (schneller):

uv pip install -r requirements.txt

Schritt 3: Feishu-Anwendung erstellen

1. Öffne Feishu Open Platform und logge dich mit deinem Team-Konto ein
2. Klicke Unternehmensanwendung erstellen (selbst erstellt) und fülle Name sowie Beschreibung aus
3. Öffne die Anwendung, wähle im linken Menü Fähigkeiten hinzufügen und setze bei Bot ein Häkchen

Schritt 4: Anwendungs-Credentials konfigurieren

Kopiere die Umgebungsvariablen-Vorlage:

cp .env.template .env

Trage in .env die von der Feishu Open Platform bereitgestellten Credentials ein:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schritt 5: Berechtigungsbereiche importieren

Gehe in der Feishu Open Platform zu Berechtigungsverwaltung → Berechtigungen für Bulk Import/Export, und füge das folgende JSON ein:

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

Schritt 6: Event-Abonnement konfigurieren

In Events und Callbacks → Event-Konfiguration wähle Long Connection zum Empfangen von Events verwenden und füge die folgenden Events hinzu:

Wähle in Callback-Konfiguration ebenfalls Long Connection und abonniere:

Schritt 7: LLM konfigurieren

Bearbeite configs/magiclaw/config.yaml und trage deine LLM-Credentials ein:

llm:
  provider: openai              # oder anthropic / custom
  model: gpt-4o
  api_key: sk-...               # aus .env oder direkt in die Konfigurationsdatei schreiben
  base_url: https://api.openai.com/v1  # optional, eigener Endpunkt

Schritt 8: Anwendung veröffentlichen und starten

Erstelle in der Feishu Open Platform unter Versionsverwaltung und Veröffentlichung eine Version und veröffentliche sie, damit der Bot aktiv wird.

Starte dann den Bot:

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

Nach erfolgreichem Start schickst du dem Bot in Feishu eine Nachricht – er antwortet. Im Ausgangszustand ist er ein generischer Session-Agent mit Multi-Round-Kontext und Gedächtnisfähigkeiten.

---

Duale Kern-Agent-Architektur

Die echten Fähigkeiten von MagiClaw entstehen durch das Zusammenspiel zweier eingebauter Playground-Komponenten: magiclaw für den Alltagssitzungsdialog und agent_builder, um dir neue spezialisierte Agents zu erstellen.

magiclaw: Feishu-Sitzungs-Orchestrator

magiclaw ist der standardmäßig aktivierte Feishu-Dialog-Agent. Seine Kernfähigkeit ist das Orchestrieren und Delegieren.

Wenn du eine komplexe Anfrage sendest, versucht magiclaw nicht, alles allein zu lösen. Es erkennt vielmehr, welche spezialisierten Fähigkeiten für diese Aufgabe benötigt werden, und delegiert die Arbeit dann per Tool-Aufruf an andere bereits registrierte Playground-Agenten:

Du schreibst in Feishu: „Hilf mir, die neuesten Fortschritte der RAG-Architektur im Finanzbereich zu recherchieren und verfasse einen Bericht“

→ magiclaw nimmt die Anfrage an
→ erkennt: Literaturrecherche (web_search_agent) + Berichtserstellung (report_writer_agent)
→ ruft beide Agenten separat auf
→ fasst die Ergebnisse zusammen und gibt eine Feishu-Nachricht zurück

Dieses Delegationsmodell hält magiclaw schlank: Es muss nicht alles können, sondern nur wissen, wann es wen aufrufen soll. Die Fähigkeiten aller spezialisierten Agents werden über Skills und Tool-Schnittstellen erweitert.

agent_builder: Meta-Agent

agent_builder ist der spannendste Teil in MagiClaw: Er ist selbst ebenfalls ein Agent, aber seine Aufgabe ist es, neue Agents zu entwerfen und zu erzeugen.

Du sagst ihm, welche Art von Aufgabe du machen möchtest, und er:

1. analysiert die Anforderungen und extrahiert die Kernfähigkeiten, die der Agent braucht
2. erzeugt die Skill-Datei des Agents (YAML-Frontmatter + Markdown-Beschreibung)
3. schreibt sie in das playground/-Verzeichnis und registriert sie in MagiClaw
4. der neue Agent ist sofort verfügbar, und magiclaw kann ihn dann delegieren

Du schreibst in Feishu: „Ich brauche einen Agent, der sich auf Code-Reviews spezialisiert“

→ agent_builder analysiert die Anfrage
→ erzeugt `code_reviewer_agent.py` + die entsprechende Konfigurationsdatei
→ registriert es im System
→ antwortet: „code_reviewer erstellt. magiclaw kann jetzt Code-Review-Aufgaben an ihn delegieren“

Diese Bootstrap-Fähigkeit ermöglicht es Teams, ihre Agent-Bibliothek anhand ihrer Forschungsrichtung kontinuierlich zu erweitern – statt alle Szenarien einmalig komplett zu definieren.

---

Tool-Konfiguration und Skills-/Memory-Mechanismus

Tool-Ebene konfigurieren

In configs/magiclaw/config.yaml kannst du verschiedene Tool-Typen konfigurieren:

tools:
  mcp:
    # MCP-Protokoll-Tools (z. B. Dateisystem, Git, Datenbanken)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # optional: bing / google / serpapi

  feishu:
    read_document: true           # Feishu-Dokumente lesen
    send_file: true               # Dateien senden

Die Tool-Konfiguration entscheidet, „was“ der Agent tun kann. Skills entscheiden, „wie gut“ er es kann.

Skills-System

Skills sind gekapselte, strukturierte Prompts, die dem Agent bei bestimmten Aufgaben eine bessere Leistung ermöglichen. Das Skills-Verzeichnis von EvoMaster liegt in evomaster/skills/; jeder Skill ist eine Markdown-Datei:

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Research Paper Summary Skill

Wenn der Nutzer eine Zusammenfassung oder Analyse eines Papers fordert, führe die folgenden Schritte aus:

1. extrahiere Paper-Titel, Autoren, Venue
2. extrahiere die Kernbeiträge (contribution)
3. extrahiere die wichtigsten Punkte zur Methodik
4. extrahiere die Limitationen (limitations)
5. gib eine strukturierte Zusammenfassung aus (nicht mehr als 300 Wörter)

Wenn der Nutzer einen ArXiv-Link bereitstellt, hole zuerst den Seiteninhalt und analysiere ihn dann.

Skills werden nach Bedarf geladen. Wenn der Agent mit einem bestimmten Aufgabentyp arbeitet, matched er automatisch den passenden Skill – du musst ihn nicht manuell triggern.

Persistentes Gedächtnis

Das Gedächtnis von MagiClaw wird über das evomaster/memory/-Modul verwaltet und unterstützt verschiedene Storage-Backends:

memory:
  backend: sqlite               # optional: sqlite / redis / file
  session_ttl: 86400            # Aufbewahrungsdauer für Session-Gedächtnis (Sekunden)
  long_term:
    enabled: true
    store: file                 # persistiert auf der Festplatte
    path: ./memory_store/

Nach jeder Konversation schreibt der Agent automatisch wichtige Kontextinformationen ins Gedächtnis. Wenn die nächste Sitzung beginnt, liest der Agent die historischen Gedächtnisdaten und bleibt über Sitzungen hinweg konsistent.

---

Vollständige Workflow-Demo

Szenario: Ein „Paper-Schnelllese“-Agent für das Team aufbauen

Ziel: In Feishu wirfst du dem Bot einen ArXiv-Link hin – er liefert automatisch eine strukturierte Paper-Zusammenfassung.

Step 1: Mit agent_builder den Agent erstellen

Sende in Feishu eine Nachricht an MagiClaw:

Hilf mir, einen Paper-Schnelllese-Agent zu erstellen. Name: paper_reader

agent_builder erzeugt das Verzeichnis playground/paper_reader/, das enthält:

playground/paper_reader/
├── __init__.py
├── agent.py                   # Agent-Hauptlogik
└── config.yaml                 # Agent-weite Konfiguration

Step 2: In magiclaw registrieren

Nach dem Erstellen des neuen Agents bearbeitest du configs/magiclaw/config.yaml und registrierst ihn unter playgrounds:

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

Nach dem Neustart des Bots erkennt magiclaw den Agent und kann ihn delegieren.

Step 3: Testen

In Feishu:

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader führt automatisch aus:

1. ArXiv-Seite abrufen
2. Titel, Autoren und Abstract extrahieren
3. strukturierte Zusammenfassung generieren (Beitrag + Methode + Limitationen)
4. Feishu-Nachricht zurückgeben

---

Häufige Probleme beheben

Q1: Nach dem Start des Bots reagiert Feishu nicht

Ursache: Event-Abonnement oder Long-Connection-Konfiguration ist nicht korrekt.

Troubleshooting-Schritte:

# 1. Prüfen, ob der Bot veröffentlicht wurde (Feishu Open Platform → Versionsverwaltung und Veröffentlichung)
# Ein nicht veröffentlichter Bot kann in der Produktionsumgebung keine Nachrichten senden/empfangen

# 2. Prüfen, ob die Long Connection korrekt konfiguriert ist
# Feishu Open Platform → Events und Callbacks → Event-Konfiguration → „Long Connection“ auswählen

# 3. Start-Logs auf Fehlermeldungen prüfen
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2: Der Bot erhält Nachrichten, antwortet aber „Aktion wird nicht unterstützt“

Ursache: Der Berechtigungsumfang reicht nicht aus oder die Anwendung wurde nicht für den entsprechenden Bereich veröffentlicht.

Troubleshooting-Schritte:

In Feishu Open Platform → Berechtigungsverwaltung: Stelle sicher, dass das folgende minimale Berechtigungset aktiviert ist:

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

Wenn der Bot einer Gruppe beitreten muss, wird zusätzlich im:message.group_at_msg:readonly benötigt.

---

Q3: Nach dem Erstellen eines Agents durch agent_builder erkennt magiclaw ihn nicht

Ursache: Der neue Agent ist nicht in configs/magiclaw/config.yaml registriert.

Lösung:

Stelle sicher, dass du in der playgrounds-Liste in configs/magiclaw/config.yaml den neuen Agent hinzugefügt und enabled: true gesetzt hast. Nach der Konfigurationsänderung muss der Bot neu gestartet werden.

---

Q4: Das Gedächtnis wird nicht über Sitzungen hinweg beibehalten – der Agent wirkt bei jedem Gespräch, als hätte er vergessen

Ursache: Das Speicher-Backend ist nicht korrekt konfiguriert oder der Speicherpfad ist nicht beschreibbar.

Troubleshooting-Schritte:

# 1. Memory-Konfiguration in config.yaml prüfen
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. Sicherstellen, dass der Ordner memory_store existiert und beschreibbar ist
mkdir -p memory_store
chmod 755 memory_store

# 3. Bot neu starten und eine Nachricht senden, um das Schreiben des Gedächtnisses zu triggern

---

Q5: Die Web-Search-Tools liefern leere Ergebnisse oder brechen mit Timeout ab

Ursache: Das Netzwerk kann den Suchdienst nicht erreichen oder die Search-API-Credentials sind nicht konfiguriert.

Lösung:

Wenn du DuckDuckGo nutzt (kostenlos, ohne API Key), prüfe, ob deine Python-Umgebung Zugriff auf das Internet hat:

# Netzwerk testen
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

Wenn 200 zurückkommt, der Bot in Feishu aber dennoch timeouts hat, prüfe, ob die Konfiguration tools.web_search.provider in configs/magiclaw/config.yaml korrekt ist.

---

Q6: MCP-Tool kann nicht gestartet werden, Meldung „command not found“

Ursache: Der MCP Server findet npx oder den Node.js-Pfad nicht, weil er nicht in der System-Umgebungsvariable PATH enthalten ist.

Lösung:

# Prüfen, ob npx verfügbar ist
npx --version

# Wenn npx nicht gefunden wird, Pfad manuell angeben
# configs/magiclaw/config.yaml anpassen:
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Weiterführende Lektüre und nächste Schritte

1. SciMaster-Ökosystem anbinden

MagiClaw ist der Feishu-Einstieg in das EvoMaster-Ökosystem. Die vollständige SciMaster-Reihe (ML-Master, X-Master, Browse-Master usw.) befindet sich im Upstream-EvoMaster-Repository. Wenn deine Forschungsrichtung Multi-Modal-Materialwissenschaftsanalysen oder die Koordination mehrerer Experimente erfordert, kannst du diese spezialisierten Agents von EvoMaster synchronisieren und in die Orchestrierungsschicht von MagiClaw integrieren.

2. Eigene MCP-Tools entwickeln

Die MCP-Tool-Schnittstelle von MagiClaw unterstützt das Andocken an beliebige MCP Server. Du kannst einen MCP Server mit Python schreiben, um interne APIs, Tools zur Abfrage wissenschaftlicher Datenbanken oder HPC-Cluster-Submit-Skripte zu kapseln – und ihn dann in MagiClaw registrieren. So können Agents in Feishu direkt darauf zugreifen.

3. Multi-Bot-Kooperationsarchitektur

Wenn dein Team mehrere Bots mit unterschiedlichen Aufgaben hat (z. B. ein Bot für Kalender, einer für Code, einer für Literatur), kannst du sie über Feishu-Group-Chats zusammenarbeiten lassen: In einem Gruppenchat integrierst du mehrere Bots, jeder übernimmt seine Funktion, und du wechselst per @.

4. Deployment privater Modelle im Team

EvoMaster unterstützt den custom Provider, um LLMs einzubinden, die intern im Unternehmen deployt sind (Llama, Mistral, Qwen usw.). Wenn Forschungsdaten nicht nach außen übertragen werden dürfen, kannst du die Modelle lokal oder in einer privaten Cloud bereitstellen. Dann bedienst du alles über die Feishu-Oberfläche von MagiClaw – die Daten verlassen das interne Netz nicht.

5. Optimierung des Agent-Verhaltens

Das Verhalten der Agents in jedem Playground wird hauptsächlich durch config.yaml (Feld prompt) und die skills gesteuert. Wenn du feststellst, dass ein Agent in bestimmten Szenarien schwach ist, kannst du die entsprechende Skill-Datei anpassen, die Denk-Schritte und Ausgabeformate verändern – ohne Code anfassen zu müssen.