Erstellen benutzerdefinierter KI-Agenten mit OpenClaw: Entwicklerhandbuch

Der Aufbau eines produktionsreifen KI-Agenten ist nicht dasselbe wie das Schreiben eines Chatbots. Agenten müssen den Kontext erkennen, unvollständige Informationen begründen, mehrstufige Pläne ausführen und Fehler beheben – und das alles ohne menschliche Aufsicht. OpenClaw ist eine KI-Agentenplattform für Unternehmen, die speziell für dieses Maß an betrieblicher Autonomie entwickelt wurde und Entwicklern vom ersten Tag an eine strukturierte Laufzeit, ein Kompetenzzusammensetzungsmodell und erstklassige Beobachtbarkeit bietet.

Dieser Leitfaden richtet sich an Ingenieure, die von Null auf einen bereitgestellten, überwachten OpenClaw-Agenten umsteigen möchten. Wir behandeln Architekturinterna, Skill-Authoring, Speicherverwaltung, Orchestrierungs-Hooks und die Bereitstellungsmuster, die dafür sorgen, dass Agenten unter Produktionslast zuverlässig bleiben.

Wichtige Erkenntnisse

– OpenClaw-Agenten bestehen aus Skills (atomaren Fähigkeiten), Speicherschichten und einem Orchestrator, der Ausführungssequenzen plant. – Die Agent-Manifestdatei deklariert alle Abhängigkeiten, Berechtigungen und Toolbindungen vor der Laufzeit. – Fertigkeiten sind zustandslose Funktionen, die typisierte Eingaben akzeptieren und typisierte Ausgaben ausgeben – Testbarkeit ist integriert.

Die Ebenen Arbeitsspeicher, Episodenspeicher und Langzeitspeicher erfüllen unterschiedliche Aufbewahrungs- und Abrufanforderungen. – Mit Hooks (Pre-Run, Post-Run, On-Error) können Sie Überwachung, Ratenbegrenzung und Fallback-Logik einbinden, ohne den Kernkompetenzcode zu ändern. – Mit dem Sandbox-Modus von OpenClaw können Sie Produktions-Traces zum Debuggen lokal wiedergeben, ohne Live-API-Aufrufe. – Multi-Agent-Übergaben verwenden einen typisierten Nachrichtenbus – keine Weitergabe von Rohzeichenfolgen zwischen Agenten.

ECOSIRE bietet verwaltete OpenClaw-Implementierungen, benutzerdefinierte Skill-Bibliotheken und fortlaufende Optimierung für Unternehmensteams.

Das OpenClaw-Agentenmodell verstehen

Jeder OpenClaw-Agent besteht aus vier Grundelementen: Skills, Memory, Tools und einem Orchestrator.

Fähigkeiten sind die atomaren Einheiten der Agentenfähigkeit. Ein Skill ist eine Funktion, die ein typisiertes Eingabeschema akzeptiert und ein typisiertes Ausgabeschema zurückgibt. Fertigkeiten können synchron oder asynchron sein und deklarieren ihre externen Abhängigkeiten explizit. Beispiele: ParseInvoice, SendSlackMessage, QueryCRMContact, GenerateReport.

Tools sind externe Systembindungen. OpenClaw wird mit integrierten Tools für REST-APIs, Datenbanken, Dateisysteme, Browser und Nachrichtenwarteschlangen geliefert. Sie registrieren Tools im Agent-Manifest und injizieren sie zur Laufzeit über die Abhängigkeitsinjektion in Skills.

Speicher ist in drei Ebenen organisiert. Der Arbeitsspeicher speichert den aktuellen Aufgabenstatus – den Notizblock des Agenten. Der Episodenspeicher speichert abgeschlossene Aufgabenverläufe, die durch semantische Ähnlichkeit innerhalb der aktuellen Sitzung abgerufen werden können. Das Langzeitgedächtnis bleibt über Sitzungen hinweg bestehen und speichert gelernte Fakten, Benutzerpräferenzen und Domänenwissen.

Der Orchestrator ist der Kern der Argumentation. Es empfängt eine Zielaussage, fragt das verfügbare Kompetenzregister ab, erstellt einen Ausführungsplan und überwacht jeden Schritt. Wenn ein Skill fehlschlägt, entscheidet der Orchestrator, ob er es erneut versucht, durch einen alternativen Skill ersetzt oder an einen Menschen eskaliert.

Das Architekturdiagramm für einen einzelnen Agenten sieht folgendermaßen aus:

User Request
     ↓
[ Orchestrator ]
     ↓ plan
[ Skill Selector ] → [ Skill Registry ]
     ↓ execute
[ Skill Instance ]
     ↓ tool calls
[ Tool Layer ] → [ External Systems ]
     ↓ result
[ Memory Writer ]
     ↓ store
[ Working / Episode / Long-Term Memory ]
     ↓ next step or done
[ Orchestrator ] → response

Diese Schleife wird fortgesetzt, bis der Orchestrator feststellt, dass das Ziel erfüllt ist oder eine Stoppbedingung erreicht ist.

Einrichten Ihrer Entwicklungsumgebung

Bevor Sie Ihren ersten Skill schreiben, benötigen Sie das OpenClaw SDK und eine lokale Agentenlaufzeit.

npm install @openclaw/sdk @openclaw/runtime @openclaw/cli
npx openclaw init my-agent --template=typescript

Der Befehl init generiert ein Projekt mit dieser Struktur:

my-agent/
  agent.manifest.json   # Agent declaration
  skills/               # Skill implementations
  tools/                # Tool registrations
  memory/               # Memory adapter config
  tests/                # Skill and integration tests
  .openclaw/            # Local runtime state

Der agent.manifest.json ist die wichtigste Datei. Es deklariert alles, was OpenClaw zum Bootstrap Ihres Agenten benötigt:

{
  "name": "invoice-processor",
  "version": "1.0.0",
  "runtime": "node-20",
  "skills": [
    "skills/extract-line-items.ts",
    "skills/validate-vendor.ts",
    "skills/post-to-erp.ts"
  ],
  "tools": {
    "erp": { "type": "rest", "baseUrl": "${ERP_BASE_URL}", "auth": "bearer" },
    "storage": { "type": "s3", "bucket": "${DOCS_BUCKET}" }
  },
  "memory": {
    "working": { "ttl": 3600 },
    "episode": { "backend": "redis", "maxItems": 500 },
    "longTerm": { "backend": "postgres", "table": "agent_facts" }
  },
  "permissions": ["read:invoices", "write:erp", "read:vendors"]
}

Umgebungsvariablen werden zur Laufzeit eingefügt und nie im Manifest gespeichert.

Schreiben Sie Ihre erste Fähigkeit

Die Fähigkeiten unterliegen einem strengen Vertrag. Sie akzeptieren ein input-Objekt, das einem deklarierten Schema entspricht, empfangen injizierte tools- und memory-Objekte und geben ein output-Objekt zurück oder werfen ein typisiertes SkillError-Objekt aus.

import { defineSkill, SkillError } from "@openclaw/sdk";
import { z } from "zod";

const ExtractLineItemsInput = z.object({
  documentUrl: z.string().url(),
  documentType: z.enum(["invoice", "receipt", "purchase-order"]),
});

const ExtractLineItemsOutput = z.object({
  lineItems: z.array(
    z.object({
      description: z.string(),
      quantity: z.number(),
      unitPrice: z.number(),
      total: z.number(),
    })
  ),
  confidence: z.number().min(0).max(1),
});

export const ExtractLineItems = defineSkill({
  name: "extract-line-items",
  description: "Extracts line items from a document using OCR and LLM parsing",
  input: ExtractLineItemsInput,
  output: ExtractLineItemsOutput,
  tools: ["storage"],
  async run({ input, tools, memory }) {
    const fileBuffer = await tools.storage.get(input.documentUrl);
    if (!fileBuffer) {
      throw new SkillError("DOCUMENT_NOT_FOUND", `No document at ${input.documentUrl}`);
    }

    // OCR + LLM extraction logic here
    const extracted = await runOcrPipeline(fileBuffer);

    await memory.working.set("lastExtraction", extracted);

    return {
      lineItems: extracted.items,
      confidence: extracted.confidence,
    };
  },
});

Wichtige Gestaltungsregeln für Fertigkeiten:

Keine Nebenwirkungen auf die Eingabe: Fertigkeiten sollten ihre Eingabeobjekte nicht ändern.
Eingegebene Fehler: Geben Sie SkillError immer mit einem maschinenlesbaren Code aus, nicht mit generischem Error.
Tool-Abhängigkeiten deklarieren: Es werden nur Tools eingefügt, die im Array tools deklariert sind. Nicht deklarierte Tools verursachen einen Startvalidierungsfehler.
Explizit in den Speicher schreiben: Fertigkeiten bleiben nicht automatisch im Status erhalten. Rufen Sie memory.working.set() bewusst auf.

Speichermanagement in der Praxis

Die drei Speicherebenen dienen unterschiedlichen Zwecken und die Wahl der richtigen Ebene ist für die Agentenkorrektheit von entscheidender Bedeutung.

Arbeitsspeicher ist ein prozessinterner Schlüsselwertspeicher, der für die Dauer einer einzelnen Aufgabenausführung bestehen bleibt. Verwenden Sie es, um Zwischenergebnisse zwischen Fertigkeiten weiterzugeben, ohne die Ausgabekette zu durchlaufen. Es wird automatisch gelöscht, wenn der Orchestrator den Vorgang abschließt oder eine Zeitüberschreitung auftritt.

// Skill A writes
await memory.working.set("vendorId", "VND-4521");

// Skill B reads
const vendorId = await memory.working.get("vendorId");

Episode Memory ist ein semantischer Suchspeicher. Wenn eine Aufgabe abgeschlossen ist, schreibt der Orchestrator optional eine Zusammenfassung, die in den Episodenspeicher eingebettet wird. Zukünftige Aufgaben können ähnliche vergangene Episoden abrufen, um ihre Argumentation zu unterstützen.

// Query past episodes
const relatedEpisodes = await memory.episode.search(
  "invoice from Acme Corp with disputed line items",
  { topK: 3, minScore: 0.75 }
);

Langzeitgedächtnis ist die dauerhafte Wissensdatenbank Ihres Agenten. Verwenden Sie es für Fakten, die sitzungsübergreifend bestehen bleiben sollten: Regeln zur Anbieterkategorisierung, Benutzerpräferenzen, erlernte Domänenbeschränkungen.

// Store a learned fact
await memory.longTerm.upsert({
  key: `vendor:${vendorId}:paymentTerms`,
  value: "NET-30",
  source: "invoice-2024-0312",
  confidence: 0.9,
});

Ein häufiger Fehler ist das Überschreiben ins Langzeitgedächtnis. Bewahren Sie es auf, um stabile, vertrauenswürdige Fakten zu erhalten. Ephemeres Denken gehört ins Arbeitsgedächtnis.

Lebenszyklus-Hooks für Beobachtbarkeit und Kontrolle

OpenClaw stellt vier Lebenszyklus-Hooks pro Skill-Ausführung bereit: preRun, postRun, onError und onTimeout. Registrieren Sie Hooks im Agent-Manifest oder programmgesteuert in Ihrer Bootstrap-Datei.

import { AgentRuntime } from "@openclaw/runtime";

const agent = new AgentRuntime({ manifest: "./agent.manifest.json" });

agent.useHook("preRun", async (ctx) => {
  ctx.metadata.startTime = Date.now();
  console.log(`[${ctx.skill}] starting with input keys: ${Object.keys(ctx.input)}`);
});

agent.useHook("postRun", async (ctx) => {
  const elapsed = Date.now() - ctx.metadata.startTime;
  metrics.record("skill.duration", elapsed, { skill: ctx.skill });
});

agent.useHook("onError", async (ctx) => {
  if (ctx.error.code === "RATE_LIMIT_EXCEEDED") {
    await sleep(ctx.error.retryAfterMs);
    return "retry";
  }
  alerting.send(`Skill ${ctx.skill} failed: ${ctx.error.message}`);
  return "escalate";
});

Der Hook-Rückgabewert onError steuert das Verhalten des Orchestrators: "retry" löst einen Wiederholungsversuch aus (bis zum konfigurierten Maximum), "escalate" leitet die Aufgabe an eine menschliche Warteschlange weiter, "fail" beendet die Aufgabe sofort.

Fähigkeiten isoliert testen

Da Fertigkeiten über typisierte Eingaben und Ausgaben verfügen, sind Unit-Tests unkompliziert. Die Testdienstprogramme von OpenClaw bieten Scheinimplementierungen aller Tool-Schnittstellen.

import { testSkill } from "@openclaw/testing";
import { ExtractLineItems } from "../skills/extract-line-items";

describe("ExtractLineItems", () => {
  it("extracts items from a valid invoice", async () => {
    const result = await testSkill(ExtractLineItems, {
      input: {
        documentUrl: "s3://test-bucket/invoice-001.pdf",
        documentType: "invoice",
      },
      mocks: {
        storage: {
          get: jest.fn().mockResolvedValue(samplePdfBuffer),
        },
      },
    });

    expect(result.lineItems).toHaveLength(3);
    expect(result.confidence).toBeGreaterThan(0.8);
  });

  it("throws DOCUMENT_NOT_FOUND for missing file", async () => {
    await expect(
      testSkill(ExtractLineItems, {
        input: { documentUrl: "s3://test-bucket/missing.pdf", documentType: "invoice" },
        mocks: { storage: { get: jest.fn().mockResolvedValue(null) } },
      })
    ).rejects.toMatchObject({ code: "DOCUMENT_NOT_FOUND" });
  });
});

Verwenden Sie den Sandbox-Modus für Integrationstests. Sandbox spielt aufgezeichnete Produktionsspuren mit Ihrem aktuellen Skill-Code ab und erkennt Regressionen, bevor sie Live-Systeme erreichen.

npx openclaw sandbox replay --trace=traces/invoice-20240315.json

Bereitstellung in der Produktion

OpenClaw-Agenten können als Docker-Container, serverlose Funktionen oder lang laufende Prozesse bereitgestellt werden. Das empfohlene Muster für Unternehmensbereitstellungen ist ein containerisierter Agentenpool hinter einer Aufgabenwarteschlange.

FROM openclaw/runtime:node-20
WORKDIR /agent
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN npx openclaw build
CMD ["npx", "openclaw", "serve", "--workers=4"]

Konfigurieren Sie für Szenarien mit hohem Durchsatz den Agent-Pool mit Regeln für die automatische Skalierung. Die OpenClaw-Laufzeit stellt Prometheus-Metriken bei /metrics für Warteschlangentiefe, Skill-Latenzperzentile, Fehlerraten und Speichernutzung bereit – verbinden Sie diese mit Ihrem Alarmierungsstapel.

Checkliste für die Produktion vor dem Go-Live: – Alle Umgebungsvariablen befinden sich in einem Secrets-Manager (AWS Secrets Manager, HashiCorp Vault), nicht in .env-Dateien. – Für Speicher-Backends (Redis, PostgreSQL) ist Verbindungspooling konfiguriert.

Die Einstellung maxConcurrentTasks entspricht Ihrer Infrastrukturkapazität. – Ratenbeschränkungen für externe Toolaufrufe entsprechen den API-Grenzwerten des Anbieters. – Für Aufgaben, die Wiederholungsversuche erschöpfen, ist eine Warteschlange für unzustellbare Nachrichten konfiguriert. – Die verteilte Ablaufverfolgung (OpenTelemetry) ist aktiviert und Ablaufverfolgungen fließen an Ihre Observability-Plattform.

Häufig gestellte Fragen

Wie entscheidet der OpenClaw-Orchestrator, welcher Skill als nächstes ausgeführt wird?

Der Orchestrator verwendet eine Kombination aus Zielzerlegung und Fähigkeitsabgleich. Es unterteilt das Ziel der obersten Ebene in Unterziele und fragt dann das Fertigkeitsregister anhand semantischer Ähnlichkeit mit der Beschreibung jedes Unterziels ab. Fertigkeiten werden nach Relevanzbewertung, Abhängigkeitsverfügbarkeit und historischer Erfolgsquote geordnet. Der Orchestrator erstellt einen gerichteten azyklischen Graphen der Skill-Ausführungen und löst vor dem Start Abhängigkeiten auf.

Kann ein Skill einen anderen Skill direkt aufrufen?

Nein – Fertigkeiten sollten andere Fertigkeiten nicht direkt aufrufen. Die kompetenzübergreifende Koordination liegt in der Verantwortung des Orchestrators. Wenn Sie die Ausgabe von Skill A benötigen, bevor Skill B ausgeführt wird, deklarieren Sie die Abhängigkeit im Orchestratorplan. Dadurch bleiben Fähigkeiten zustandslos und individuell testbar. Die Ausnahme bilden zusammengesetzte Fertigkeiten, die explizit als Orchestrierungsgrundelemente gekennzeichnet sind.

Was passiert, wenn eine externe API während einer Skill-Ausführung ausfällt?

Der onError-Hook fängt den Fehler ab. Wenn der Hook "retry" zurückgibt, wartet der Orchestrator auf das konfigurierte Backoff-Intervall und versucht den Skill erneut. Nach erschöpfenden Wiederholungsversuchen wird die Aufgabe in die Warteschlange für unzustellbare Nachrichten verschoben. Wenn Sie eine Fallback-Fähigkeit für dieselbe Funktion registriert haben, wird der Orchestrator diese ausprobieren, bevor er aufgibt. Ein Teilstatus der Aufgabe bleibt im Arbeitsspeicher erhalten, sodass die Aufgabe ab dem letzten erfolgreichen Skill fortgesetzt werden kann.

Wie gehen Sie mit Geheimnissen um, die Fähigkeiten zur Laufzeit benötigen?

Im Agentenmanifest deklarierte Tools werden beim Start mit Anmeldeinformationen initialisiert, nicht pro Skill. Ihr Secrets-Manager füllt die Umgebungsvariablen, auf die im Manifest verwiesen wird (${ERP_BASE_URL}, ${DOCS_BUCKET} usw.), beim Start des Containers. Skills sehen niemals rohe Anmeldeinformationen – sie interagieren mit vorab authentifizierten Tool-Instanzen, die von der Laufzeit eingefügt werden.

Gibt es eine Grenze dafür, wie viele Fähigkeiten ein Agent haben kann?

Für die Fertigkeitsregistrierung gibt es keine feste Grenze, aber die Qualität der praktischen Orchestrierung nimmt ab, wenn Sie Hunderte von Fertigkeiten mit überlappenden Beschreibungen registrieren. Gruppieren Sie verwandte Fertigkeiten in Fertigkeitspaketen und verwenden Sie klare, eindeutige Beschreibungen. Erwägen Sie bei sehr großen Kompetenzbibliotheken eine Aufteilung in spezialisierte Agenten und die Verwendung einer Multi-Agenten-Orchestrierung, um Aufgaben an den richtigen Agenten weiterzuleiten.

Können OpenClaw-Agenten vor Ort ohne Cloud-Abhängigkeiten ausgeführt werden?

Ja. OpenClaw ist Cloud-agnostisch. Die Laufzeit, die Speicher-Backends und die Tool-Ebene können alle für die Nutzung der Infrastruktur vor Ort konfiguriert werden. Redis kann lokal ausgeführt werden, das Langzeitspeicher-Backend kann auf eine lokale PostgreSQL-Instanz verweisen und Tool-Integrationen können auf interne APIs abzielen. Der einzige externe Anruf erfolgt an den LLM-Anbieter zur Begründung des Orchestrators. Sie können dies bei Bedarf so konfigurieren, dass ein lokales LLM verwendet wird.

Wie können Sie Agentenfähigkeiten versionieren, ohne laufende Aufgaben zu unterbrechen?

Fertigkeiten werden im Agentenmanifest mit semantischer Versionierung versioniert. Die Laufzeit unterstützt die gleichzeitige Ausführung mehrerer Skillversionen während einer fortlaufenden Bereitstellung. Für Aufgaben während des Flugs wird weiterhin die Fertigkeitsversion verwendet, mit der sie begonnen haben. Neue Aufgaben übernehmen die neueste Version. Breaking Changes an Skill-Eingabe-/Ausgabeschemata erfordern einen großen Versionssprung und einen Migrationsplan für jeden Agenten, der die Ausgabe dieses Skills nutzt.

Nächste Schritte

Der Aufbau von KI-Agenten in Produktionsqualität erfordert mehr als nur guten Code – er erfordert Betriebserfahrung mit Fehlermodi, Skalierungsmustern und domänenspezifischen Fähigkeitsbibliotheken, deren Entwicklung und Verfeinerung Monate in Anspruch nimmt.

Der OpenClaw Custom Skills-Service von ECOSIRE bietet eine End-to-End-Agentenentwicklung: Anforderungsanalyse, Skill-Architektur, Integration in Ihre vorhandenen Systeme, Tests, Bereitstellung und fortlaufende Optimierung. Unser Team hat OpenClaw-Agenten für Dokumentenverarbeitung, ERP-Automatisierung, Kundensupport, Finanzanalyse und mehr entwickelt.

Sprechen Sie mit einem OpenClaw-Spezialisten, um Ihre Automatisierungsanforderungen zu besprechen und eine individuelle Entwicklungs-Roadmap zu erhalten.

Building Custom AI Agents with OpenClaw: Developer Guide