OpenClaw Agent erstellen - Schritt für Schritt zum ersten KI-Agent

In dieser Lektion baust du deinen ersten echten OpenClaw-Agenten: einen kleinen Recherche-Assistenten, der eine Frage entgegennimmt, eine Web-Suche ausführt, die wichtigsten Treffer in eigenen Worten zusammenfasst und das Ergebnis als Notiz in einer lokalen Datei sichert. Der Agent läuft am Ende vollständig auf deiner Maschine, kommuniziert über die Konsole und nutzt zwei selbst geschriebene Tools sowie ein einfaches Summary-Memory. Du lernst dabei nicht nur die OpenClaw-API kennen, sondern auch die mentalen Modelle, die du für jeden weiteren Agenten brauchst: Provider, Tools, Memory, System-Prompt und die Loop, in der das alles zusammenläuft.

Was wir bauen

Stell dir vor, du sitzt vor einem leeren Terminal und tippst eine Frage ein, etwa: “Welche Open-Source-Frameworks gibt es aktuell für KI-Agenten in Python?”. Dein Agent erkennt, dass er die Antwort nicht aus dem Kopf weiß, ruft selbstständig ein Web-Such-Tool auf, bekommt strukturierte Treffer zurück, formuliert daraus eine kompakte Antwort und legt sie zusätzlich als Notiz in einer Datei notizen.txt ab. Beim zweiten und dritten Prompt erinnert er sich an die vorherigen Themen, weil das Memory die Konversation auf einen knappen Zusammenfassungs-String komprimiert. Genau dieser Ablauf ist das Mini-Modell jeder produktiven Agenten-Anwendung, vom Customer-Support-Bot bis zum internen DevOps-Helfer.

Architektonisch besteht unser System aus vier Bausteinen: einem Agent, der die zentrale Klammer bildet; einem Provider, der mit dem LLM spricht (in unserem Fall OpenAI mit GPT-4o Mini); einer Liste von Tool-Funktionen, die der Agent aufrufen kann, wenn er sie braucht; und einem Memory-Objekt, das den Konversationsverlauf in eine kurze Zusammenfassung kondensiert, damit das Kontextfenster nicht überläuft. OpenClaw ist bewusst so gebaut, dass diese vier Bausteine austauschbar sind: Du kannst den OpenAI-Provider gegen Anthropic, Ollama oder einen lokalen vLLM-Server tauschen, ohne den Rest deines Codes zu ändern.

Lernziele dieser Lektion: Du verstehst, wie du eine OpenClaw-Anwendung von Null aufsetzt; du kannst eigene Tools mit dem @agent.tool-Decorator registrieren und weißt, warum Type-Hints und Docstrings hier nicht optional sind; du kannst zwischen den verfügbaren Memory-Strategien wählen und einschätzen, wann welche passt; und du kannst dein Setup lokal mit Ollama betreiben, falls du keine Cloud-API verwenden willst oder darfst. Am Ende der Lektion hast du einen lauffähigen Agenten, den du in den nächsten Modulen schrittweise zu einem vollwertigen MCP-fähigen System ausbaust.

Wer schon Erfahrung mit Frameworks wie LangChain, LlamaIndex oder dem Anthropic-SDK hat, wird viele Patterns wiedererkennen, aber gleichzeitig merken, dass OpenClaw auf weniger Magie setzt. Es gibt keine versteckten Chains, keine Auto-Registrierung von Tools über globale Singletons und kein implizites Re-Prompting im Hintergrund. Alles, was passiert, ist explizit im Code sichtbar, was Debugging und produktive Wartung deutlich einfacher macht.

Voraussetzungen prüfen

Bevor wir loslegen, vergewissere dich kurz, dass dein System die nötigen Werkzeuge in einer modernen Version hat. OpenClaw 0.13 unterstützt offiziell Python 3.11 und 3.12. Auf 3.10 läuft vieles, aber bei den neueren strukturierten Tool-Aufrufen wird es früher oder später Reibung geben. Wenn du noch keine virtuelle Umgebung verwendest, ist jetzt der richtige Zeitpunkt, dir das anzugewöhnen, sonst kollidieren spätestens beim zweiten Projekt verschiedene Paketversionen.

Du brauchst außerdem einen API-Key. In dieser Lektion arbeiten wir mit OpenAI, weil die Tool-Calling-Implementierung dort am stabilsten ist und die Kosten für GPT-4o Mini im Cent-Bereich liegen. Wenn du den Key noch nicht hast, leg ihn auf platform.openai.com an und exportiere ihn als Umgebungsvariable, niemals direkt in den Code. Falls du strikt lokal arbeiten musst, springe zur Sektion “Variante mit Ollama” weiter unten, der Rest der Lektion bleibt bis auf den Provider-Aufruf identisch.

python3 --version    # ≥ 3.11
git --version
echo $OPENAI_API_KEY # nicht leer

Wenn die ersten beiden Befehle Versionen zurückliefern und der dritte Befehl deinen Key zeigt (oder zumindest eine nicht-leere Zeile, falls du set -o noglob aktiv hast), bist du startklar. Falls python3 --version etwas wie 3.10.x ausspuckt, installiere Python 3.11 oder 3.12 über deinen Paketmanager, pyenv oder uv. Auf Debian-basierten Systemen reicht meist sudo apt install python3.11 python3.11-venv. Auf macOS empfehlen wir brew install python@3.12. Unter Windows nutzt du am besten WSL2 mit Ubuntu, dort funktioniert die Toolchain genauso wie unter Linux und du sparst dir Pfad-Trennzeichen-Pannen in Tool-Code.

Schritt 1 - Projekt aufsetzen

Lege ein neues Verzeichnis an, wechsle hinein und richte eine virtuelle Umgebung ein. Wir installieren bewusst pinned Versionen, damit dieser Code in einem halben Jahr noch funktioniert. OpenClaw folgt SemVer, das heißt minor releases können neue Features bringen, aber keine Breaking Changes innerhalb von 0.13. Trotzdem ist es gute Praxis, Version-Pinning zu nutzen, gerade wenn du den Agent später in Produktion betreibst.

mkdir mein-erster-agent && cd mein-erster-agent
python3 -m venv .venv && source .venv/bin/activate
pip install openclaw==0.13.* python-dotenv requests

Drei Pakete, drei klare Aufgaben. openclaw ist das Framework selbst und bringt die Klassen Agent, Tool, Memory sowie die Provider-Module mit. python-dotenv lädt deine .env-Datei beim Start, damit du den API-Key nicht jedes Mal manuell exportieren musst. requests brauchen wir für unser Web-Such-Tool, das gegen die DuckDuckGo-Instant-Answer-API spricht, die ohne Key auskommt und für Lernzwecke völlig ausreicht. Falls du später Brave Search, Tavily oder eine eigene SearXNG-Instanz anbinden willst, ändert sich nur die URL und die Header.

Lege als Nächstes eine Datei .env im Projektordner an. Sie ist die einzige Stelle, an der dein Key explizit auftaucht, und sie ist von vornherein durch die .gitignore geschützt. Inhalt:

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx
OPENCLAW_LOG=info

Die zweite Zeile setzt das Standard-Log-Level. Während des Bauens kannst du es problemlos auf debug hochziehen und siehst dann jeden einzelnen Schritt, den der Agent intern unternimmt: jeden Prompt, jede Tool-Antwort, jede Memory-Operation. Im Produktionsbetrieb stellst du es zurück auf warning, weil sonst dein Log dichtmacht. Die Variable wird vom OpenClaw-Logger automatisch gelesen, du musst nichts weiter konfigurieren.

Lege außerdem eine .gitignore an mit den Einträgen .venv/, .env, notizen.txt und __pycache__/. So vermeidest du, dass dein Key oder lokale Notizen versehentlich in einem Repository landen. Dieser kleine Schritt rettet später Nerven, gerade wenn du das Projekt mit Kollegen oder über GitHub teilst.

Schritt 2 - Den Agent definieren

Jetzt kommt der spannende Teil: das eigentliche Agenten-Objekt. Erstelle eine Datei agent.py und lege darin einen Agent mit Provider, Memory und System-Prompt an. Beachte, wie wenig Boilerplate dafür nötig ist: Die gesamte Konfiguration passt in einen einzigen Konstruktor-Aufruf, weil OpenClaw vernünftige Defaults für die Loop, das Tool-Routing und das Error-Handling mitbringt.

# agent.py
from openclaw import Agent, Tool, Memory
from openclaw.providers.openai import OpenAIProvider

agent = Agent(
    name="recherche-assistent",
    provider=OpenAIProvider(model="gpt-4o-mini"),
    memory=Memory(strategy="summary", max_tokens=4000),
    system_prompt=(
        "Du bist ein präziser Recherche-Assistent. "
        "Nutze die verfügbaren Tools, statt zu raten."
    ),
)

Lass uns Zeile für Zeile durchgehen, weil jede Entscheidung hier später Konsequenzen hat. from openclaw import Agent, Tool, Memory zieht die drei Kernklassen herein. Agent ist die Klammer um alles. Tool brauchst du nicht zwingend explizit, weil wir gleich den Decorator nutzen, aber für komplexere Setups (Tools mit Lifecycle-Hooks oder asynchroner Initialisierung) ist die Klasse direkt nützlich. Memory ist die Konversations-Historie mit Auswahl der Komprimierungsstrategie.

from openclaw.providers.openai import OpenAIProvider lädt den OpenAI-Adapter. OpenClaw hat zusätzlich Module für Anthropic (openclaw.providers.anthropic), Google (openclaw.providers.google), Ollama (openclaw.providers.ollama) und einen generischen OpenAICompatProvider für lokale Server. Der Provider liest seinen Key automatisch aus der Umgebung, du brauchst ihn nicht im Code zu übergeben. Wenn du python-dotenv einbinden willst, importiere es ganz oben mit from dotenv import load_dotenv; load_dotenv(). Ab dann sind alle .env-Werte als Umgebungsvariablen verfügbar.

name="recherche-assistent" gibt deinem Agent einen Identifikator, den du später in Logs, Traces und Multi-Agent-Setups wiedererkennst. Halte ihn kurz und in kebab-case, das ist die OpenClaw-Konvention. Der Name taucht außerdem im Prompt auf, wenn du Multi-Agent-Choreographien baust, in denen Agents einander adressieren.

provider=OpenAIProvider(model="gpt-4o-mini") legt fest, welches Modell läuft. GPT-4o Mini ist die richtige Wahl für den Einstieg: schnell, günstig und stark genug für Tool-Calling. Wenn dein Use-Case komplexere Reasoning-Ketten verlangt, kannst du jederzeit auf gpt-4o oder gpt-4.1 umsteigen. Der Modellname wird beim Provider-Konstruktor 1:1 an die OpenAI-API durchgereicht, OpenClaw rät hier nichts.

memory=Memory(strategy="summary", max_tokens=4000) aktiviert das Summary-Memory mit einem 4000-Token-Budget. Sobald die Konversation diese Schwelle überschreitet, fasst OpenClaw die ältesten Nachrichten zu einem kompakten String zusammen und legt sie als System-Hint ab. Alternativen wären "buffer" (hält die letzten N Turns, alles davor wird verworfen) und "none" (kein Memory, jeder Turn ist stateless). Für die meisten Anwendungen ist summary der beste Default, weil es die Bilanz zwischen Kontext und Kosten am besten trifft.

system_prompt=... ist die Persönlichkeitsanweisung, die der Agent bei jedem Aufruf als erste Botschaft vom System sieht. Halte sie spezifisch, aber knapp: Wer ist der Agent, was ist sein Stil, wann nutzt er Tools, was sind harte Tabus. Drei bis fünf Sätze sind in der Praxis fast immer besser als ein halbseitiger Roman, weil das Modell bei kürzeren Anweisungen weniger Drift zeigt. Notiere dir gleich, dass du den Prompt später in eine eigene prompts/-Datei auslagerst, sobald er länger als zwei Zeilen wird.

Schritt 3 - Tools hinzufügen

Tools sind der Hebel, mit dem dein Agent von “spuckt Text aus” zu “tut etwas in der Welt” wird. In OpenClaw registrierst du eine Tool-Funktion einfach mit dem @agent.tool-Decorator. Der Decorator liest die Type-Hints und den Docstring deiner Funktion, generiert daraus automatisch ein JSON-Schema im Format der OpenAI-Tool-API und schreibt es in den Tool-Katalog des Agents. Dieser Mechanismus bedeutet: Wenn du Type-Hints vergisst oder den Docstring leer lässt, weiß das Modell nicht, wann es das Tool aufrufen soll. Es ist die häufigste Anfänger-Fehlerquelle, deshalb fett unterstrichen.

@agent.tool
def web_search(query: str) -> list[dict]:
    """Sucht im Web und gibt Top-5-Ergebnisse zurück."""
    import requests
    r = requests.get("https://api.duckduckgo.com/", params={"q": query, "format": "json"})
    return r.json().get("RelatedTopics", [])[:5]

@agent.tool
def save_note(text: str) -> str:
    """Speichert eine Notiz in einer lokalen Datei."""
    with open("notizen.txt", "a") as f:
        f.write(text + "\n---\n")
    return "Notiz gespeichert."

Schauen wir uns web_search genauer an. Die Funktion nimmt einen query: str und gibt eine list[dict] zurück, beides exakt mit Type-Hints versehen. OpenClaw übersetzt das in ein JSON-Schema mit einem Pflichtparameter vom Typ String. Der Docstring “Sucht im Web und gibt Top-5-Ergebnisse zurück.” landet als description-Feld in genau dem Format, das das Modell beim Tool-Routing liest. Das heißt: Wenn ein User “Was ist OpenClaw?” fragt, sieht das Modell die Description, erkennt die Eignung und löst einen Tool-Call mit einem passenden query-Argument aus. Die Implementierung selbst ist trivial: requests.get gegen die DuckDuckGo-Instant-Answer-API, JSON parsen, die ersten fünf Treffer zurückgeben. In der Praxis tauschst du das später durch Tavily, Brave oder eine interne Suchmaschine.

save_note zeigt das Pattern für Side-Effect-Tools, also Funktionen, die etwas an der Welt verändern. Sie nimmt einen text: str und schreibt ihn ans Ende einer Datei notizen.txt. Wichtig ist der return-Wert: ein String, der dem Modell bestätigt, dass alles geklappt hat. Wenn du hier None zurückgibst, weiß das Modell nicht, ob der Aufruf erfolgreich war, und produziert in der nächsten Antwort oft eine nervöse Wiederholung. Gewöhne dir an, dass jedes Tool entweder strukturierte Daten oder eine kurze Erfolgsmeldung zurückgibt, niemals nichts.

Beide Tools sind synchron, was für den Einstieg völlig ausreicht. OpenClaw erkennt aber automatisch, ob du eine async def-Funktion mit dem Decorator versiehst, und ruft sie dann im Eventloop auf. Sobald deine Tools Datenbankzugriffe, HTTP-Calls in Schleifen oder ähnlich I/O-lastige Logik enthalten, lohnt sich der Wechsel auf async sofort, weil dein Agent dann mehrere Calls parallel ausführen kann, statt zu blockieren.

Ein Hinweis zum Tool-Design, der dir später viel Debugging spart: Halte Tool-Signaturen so flach wie möglich. Statt eines komplexen params: dict lieber drei explizit getypte Parameter. Statt eines optionalen Booleans, der das Verhalten umkippt, lieber zwei separate Tools mit eindeutigen Namen. Modelle entscheiden sich konsistenter für das richtige Tool, wenn der Tool-Katalog scharfe Konturen hat. Diese Faustregel wirst du in Modul 3 noch ausführlicher kennenlernen, wenn wir Tool-Verträge formal modellieren.

Schritt 4 - Den Agent starten

Jetzt brauchen wir nur noch eine Schleife, die User-Eingaben einliest, an den Agent weitergibt und die Antwort zurückschreibt. OpenClaw bringt mit der agent.run(...)-Methode bereits einen vollständigen Turn mit: ein Aufruf, das Modell bekommt deinen Input plus den System-Prompt plus den Memory-Kontext plus den Tool-Katalog, entscheidet selbst, ob und welche Tools es aufruft, und gibt am Ende einen Text zurück. Du musst dich um nichts dazwischen kümmern.

if __name__ == "__main__":
    while True:
        user = input("Du > ")
        if user.lower() in {"exit", "quit"}:
            break
        print("Agent >", agent.run(user))

Die Schleife ist absichtlich minimalistisch, weil wir den Fokus auf das Agent-Verhalten legen wollen. input("Du > ") blockiert, bis der User eine Zeile eingibt und Enter drückt. Mit exit oder quit brichst du sauber ab, was wichtig ist, damit das Memory beim nächsten Start nicht in einem halben Zustand hängt (Spoiler: tut es ohnehin nicht, weil unser Memory rein im RAM lebt, aber gewöhne dir das Pattern an). Der Aufruf agent.run(user) ist die Schnittstelle zur eigentlichen Loop, die OpenClaw intern führt: Prompt zusammenbauen, Modell aufrufen, Tool-Calls auflösen, Ergebnisse zurückreichen, finalen Text rendern.

Beachte, was du an dieser Stelle nicht selbst implementieren musst: Du baust kein Tool-Routing, du parst keine JSON-Tool-Calls, du verwaltest keine Konversations-Historie, du kümmerst dich nicht um Token-Limits. All das übernimmt der Agent. Diese Trennung ist absichtlich: Der Aufrufer liefert User-Input und bekommt User-Output. Was zwischen Provider, Tools und Memory passiert, ist Implementierungsdetail des Frameworks und für deinen Anwendungs-Code unsichtbar.

Wenn du den Agent gerade auf einen Server deployen willst, ersetzt du diese CLI-Schleife einfach durch einen FastAPI-Endpoint, eine Slack-Bot-Anbindung oder ein Streamlit-Frontend. Die agent.run(...)-Schnittstelle bleibt dieselbe, was den Sprung von “läuft auf meinem Laptop” zu “läuft als Service” sehr viel kürzer macht, als du es vielleicht von anderen Frameworks gewohnt bist. Wir bauen genau diesen Sprung in Modul 4 nach, in dem wir den Agent hinter eine HTTP-API stellen.

Schritt 5 - Live-Test

Starte den Agent mit python agent.py und probiere ein paar Eingaben aus. Tippe als Erstes etwas wie “Was sind aktuelle Open-Source-Frameworks für KI-Agenten in Python? Bitte recherchier kurz.” und beobachte, was passiert. Mit OPENCLAW_LOG=debug siehst du jeden Schritt; mit info bekommst du nur die finale Antwort. Beim ersten Lauf empfehlen wir debug, damit du das Tool-Calling-Verhalten direkt nachvollziehen kannst.

Der Agent schickt deinen Prompt zusammen mit dem System-Prompt und dem Tool-Katalog an GPT-4o Mini. Das Modell sieht im Katalog die Description “Sucht im Web und gibt Top-5-Ergebnisse zurück.” und entscheidet, dass web_search zur Aufgabe passt. Es generiert einen Tool-Call mit query="Open-Source Frameworks KI-Agenten Python" (oder einer ähnlichen Formulierung). OpenClaw fängt diesen Call ab, ruft deine Python-Funktion mit genau diesem Argument auf, packt das Ergebnis in eine tool-Nachricht und reicht alles zurück ans Modell. Das Modell sieht jetzt die Treffer und formuliert daraus einen kompakten Antworttext.

In einem zweiten Schritt kannst du testen, ob der Agent das save_note-Tool sinnvoll einsetzt. Frage zum Beispiel “Bitte speichere die wichtigsten zwei Frameworks aus dem letzten Treffer als Notiz.” Der Agent erkennt, dass dieser Wunsch direkt zum Save-Note-Tool passt, formuliert einen kompakten Notizen-Text und ruft save_note(text=...) auf. Im Ordner liegt jetzt eine Datei notizen.txt mit deiner ersten persistenten Erinnerung. Öffne sie mit einem Editor und prüfe, ob das Format passt.

Frage in einem dritten Turn etwas, das auf den vorherigen Kontext aufbaut, etwa “Welches dieser Frameworks würdest du für asynchrone Agents empfehlen?” Der Agent darf dafür keine erneute Web-Suche brauchen, weil die Information aus den vorigen Treffern bereits im Memory steht. Genau hier zeigt sich der Wert der summary-Strategie: Der Agent erinnert sich an die Frameworks, ohne dass die komplette Treffer-JSON erneut im Kontext liegt. Das spart Tokens und beschleunigt die Antwort.

Wenn der Agent unerwartete Antworten gibt, lies das Debug-Log von oben nach unten. Dort siehst du den exakt zusammengesetzten Prompt, den Tool-Call inklusive Argumenten, die Tool-Antwort und den finalen Modell-Output. In 90 Prozent aller Fälle ist die Ursache einer schlechten Antwort entweder ein zu vager Tool-Docstring oder ein zu allgemeiner System-Prompt. Beides kannst du in Sekunden ändern und hast direkt eine messbare Wirkung. Probiere bewusst ein paar Varianten aus, das ist die Lernschleife, mit der du in Modul 6 (Evals) systematisch besser wirst.

Lass den Agent zum Schluss bewusst scheitern, indem du eine Frage stellst, für die kein passendes Tool existiert, etwa “Sag mir den aktuellen Wechselkurs von Euro zu Yen.” Dein Agent hat nur web_search und save_note, also wird er entweder via Web-Search auf eine externe Quelle ausweichen oder ehrlich sagen, dass er es nicht weiß. Beobachte, welche Strategie das Modell wählt: Das ist gleichzeitig ein Indikator dafür, wie eng dein System-Prompt das Verhalten lenkt. Wenn er zu oft halluziniert, schärfe den Prompt mit einer Klausel wie “Wenn kein passendes Tool verfügbar ist, sag das offen, statt zu raten.”

Variante - Lokal mit Ollama

Nicht jedes Projekt darf oder will Cloud-LLMs nutzen, sei es aus Datenschutz-, Compliance- oder Kostengründen. OpenClaw macht den Wechsel auf ein lokales Modell denkbar einfach, weil der Provider die einzige Stelle ist, die etwas weiß über das konkrete LLM. Du tauschst genau diesen Baustein und der Rest deines Codes (Tools, Memory, Loop) bleibt unverändert. Voraussetzung ist, dass auf deiner Maschine Ollama läuft (Download von ollama.com, anschließend ollama serve) und ein Modell wie llama3.1:8b oder hermes3:8b gepullt ist.

Statt OpenAIProvider importierst du OpenAICompatProvider und richtest ihn auf deine lokale Ollama-Instanz aus, die per Default auf Port 11434 lauscht und eine OpenAI-kompatible Schnittstelle anbietet. Das Schöne: Tool-Calling funktioniert in den neueren Llama-Versionen ähnlich gut wie bei OpenAI, vorausgesetzt, du wählst ein Modell, das explizit mit Tool-Use trainiert wurde. Hermes 3 von Nous Research ist hier sehr stark, weil es konsequent JSON-formatierte Tool-Calls produziert.

from openclaw.providers.openai import OpenAICompatProvider

agent = Agent(
    name="recherche-assistent",
    provider=OpenAICompatProvider(
        base_url="http://localhost:11434/v1",
        model="hermes3:8b",
        api_key="ollama",  # Ollama akzeptiert beliebige Strings
    ),
    memory=Memory(strategy="summary", max_tokens=4000),
    system_prompt=(
        "Du bist ein präziser Recherche-Assistent. "
        "Nutze die verfügbaren Tools, statt zu raten."
    ),
)

Achtung: Lokale Modelle sind langsamer als Cloud-APIs, gerade auf Maschinen ohne dedizierte GPU. Rechne bei einem 8B-Modell auf CPU mit zehn bis dreißig Sekunden pro Turn, auf einer aktuellen GPU (RTX 4070 oder besser) sind es eher zwei bis vier Sekunden. Die Tool-Call-Qualität schwankt zwischen den Modellen, deshalb starte beim ersten lokalen Test mit Hermes 3 oder Mistral Small Instruct. Wenn dein Modell die Tools systematisch ignoriert, ist das Problem fast immer fehlendes Tool-Use-Training, nicht dein Code. In Modul 7 zeigen wir, wie du eigene Modelle für robustes Tool-Use feintunest.

Häufige Anfänger-Fehler

Ein paar Stolpersteine sehen wir in jeder OpenClaw-Schulung wieder, deshalb hier die Top-Liste mit jeweils einer kurzen Diagnose und Behebung. Wenn dein Agent sich seltsam verhält, geh diese Punkte in Reihenfolge durch, in 80 Prozent der Fälle ist die Lösung dabei.

Tool-Schema-Mismatch: Du hast eine Funktion mit dem Decorator versehen, aber das Modell ruft sie nie auf, obwohl der Use-Case offensichtlich passt. Fast immer liegt das daran, dass dein Docstring und deine Type-Hints nicht zueinander passen. Wenn der Docstring von “Speichert eine Datei” spricht, die Funktion aber save_note(text: str, tags: list[str]) heißt, generiert OpenClaw zwar ein Schema, das Modell sieht aber widersprüchliche Signale. Lösung: Funktion lesbar benennen, Docstring auf einen klaren Imperativ-Satz reduzieren, Parameter mit eigenen :param:-Hinweisen erläutern, falls sie nicht selbsterklärend sind.

Fehlende Type-Hints: Wenn du Type-Hints weglässt, hat OpenClaw keine Möglichkeit, ein präzises JSON-Schema zu generieren. Es fällt dann auf Any zurück, was vielen Modellen reicht, aber bei strengeren OpenAI-Tool-Modi zu Fehlermeldungen wie “tool input must be an object” führt. Lösung: Jede Tool-Funktion bekommt vollständige Type-Hints für alle Parameter und einen Return-Typ. Wenn du moderne Container-Typen wie list[dict] nutzt, verlangt das Python 3.10+, was bei unserer Voraussetzung 3.11 ohnehin erfüllt ist.

Memory-Strategie zu klein: Mit max_tokens=512 läuft das Memory nach drei Turns über und der Agent vergisst die Konversation, was er beim vierten Turn als wirre Antwort zeigt. Lösung: Für die meisten interaktiven Use-Cases ist max_tokens=4000 ein guter Start; für lange Recherche-Sessions kannst du auf 8000 hochgehen, ohne signifikant mehr zu zahlen, weil die Summary-Strategie nur die kondensierte Form behält, nicht die Roh-Historie.

API-Key in Code statt .env: Der Klassiker. Du schreibst den Key direkt in agent.py, das Repository wandert auf GitHub, und der Key ist binnen Stunden geleakt. OpenAI scannt aktive Keys auf öffentlichen Repos und revoked sie zwar oft proaktiv, aber verlassen kannst du dich darauf nicht. Lösung: .env plus python-dotenv plus .gitignore-Eintrag. Wenn du in einer Team-Umgebung arbeitest, nutze einen Secret-Manager wie 1Password CLI, AWS Secrets Manager oder Vault.

Verbose-Logging vergessen: Wenn ein Agent “nichts macht”, liegt es meistens nicht daran, dass er nichts tut, sondern daran, dass du nicht siehst, was er tut. Mit OPENCLAW_LOG=debug werden alle Prompts, Tool-Calls und Memory-Operationen geloggt. Lass das beim Bauen immer an. Im Produktionsbetrieb runter auf info oder warning, aber im Development sollte debug der Default sein, weil du sonst Debugging-Zeit verschenkst.

Bonus-Stolperstein: Das Tool wirft eine Exception, der Agent verschluckt sie und antwortet kryptisch. OpenClaw fängt Tool-Exceptions standardmäßig ab und reicht eine kompakte Fehlermeldung als Tool-Antwort ans Modell zurück. Das ist meist gewünscht, weil dein Agent nicht crasht, sobald ein externes API mal hängt. Wenn du aber selbst entwickeln willst, setze beim Decorator @agent.tool(reraise=True), dann fliegen Exceptions hoch und du siehst den vollen Stack-Trace direkt im Terminal.

Nächster Schritt

Du hast jetzt einen lauffähigen Agent mit zwei Tools, Memory und einem austauschbaren Provider. In Modul 3 - Tools und MCP bauen wir den Tool-Begriff systematisch aus, schauen uns das Model Context Protocol genauer an und integrieren externe MCP-Server, damit dein Agent Zugriff auf Datenbanken, Filesystem und Drittanbieter-APIs bekommt, ohne dass du jeden Adapter selbst schreibst.