caoyachao/openclaw-create-agent

Verwendungsszenarien

Aktiviere dieses Skill, wenn der Benutzer Folgendes möchte:

• "Hilf mir, einen neuen Agenten zu erstellen"
• "Einen neuen Agent hinzufügen"
• "Einen Feishu-Bot konfigurieren"
• "Erstelle einen Agent für meinen Romancharakter / Assistenten / Avatar"
• "Wie füge ich einen Agenten in OpenClaw hinzu?"

Kernkonzepte

Aufgabenverteilung der beiden Verzeichnisse

Verzeichnis	Zweck	Manuelle Pflege
~/.openclaw/workspace/agents/<agent>/	Seelen-Workspace (Persönlichkeit, Erinnerungen, Tagebuch, Regeln)	✅ Manuell erstellt und gepflegt
~/.openclaw/agents/<agent>/	Laufzeitdaten (Session-Verlauf, models.json)	❌ Vom System automatisch generiert

Grundsatz: Lege niemals manuell Dateien in ~/.openclaw/agents/ an.

Standardverzeichnisstruktur für Agenten

Beim Erstellen eines Agenten werden unter ~/.openclaw/workspace/agents/<agent-name>/ folgende Dateien und Verzeichnisse angelegt:

~/.openclaw/workspace/agents/<agent-name>/
├── AGENTS.md              # Arbeitsregeln, Sicherheitsrichtlinien, Heartbeat-Verhalten
├── IDENTITY.md            # Identitätsprofil (Name, Spezies, Ausstrahlung, Signaturzeile, Emoji)
├── SOUL.md                # Seelendefinition (Kernpersönlichkeit, Sprechweise, Werteanker)
├── MEMORY.md              # Langzeitgedächtnis (Aufgaben, Konfiguration, destillierte Aufzeichnungen wichtiger Entscheidungen)
├── USER.md                # Benutzerprofil über den Menschen (existiert nur in der main session)
├── TOOLS.md               # Lokale Werkzeugnotizen (Gerätenamen, SSH, bevorzugte Stimmen usw.)
├── HEARTBEAT.md           # Heartbeat-Aufgabenliste (wird übersprungen, wenn leer)
├── BOOTSTRAP.md           # Erststart-Anleitung (optional, kann nach Abschluss gelöscht werden)
├── memory/                # Tägliche Gedächtnisdateien (`YYYY-MM-DD.md`)
├── diary/                 # Privates Tagebuch (Fragmente, Beobachtungen, unaufgeforderte Gedanken)
├── saves/                 # Spiel-/Projektspeicher (falls zutreffend)
├── output/                # Aufgaben-/Projektausgabedateien (siehe AGENTS.md für Regeln)
└── .openclaw/
    └── workspace-state.json   # Statusmarkierung

Output-Ordner-Regeln (wichtig)

Kernprinzip: Alle Ausgabedateien von Aufgaben/Projekten müssen strukturiert im output/-Verzeichnis abgelegt werden.

output/
├── task-001-beschreibung/     # Aufgabenunterverzeichnis
│   ├── README.md            # Aufgabenbeschreibung und Kontext
│   ├── dateien...           # Aufgabenbezogene Dateien
│   └── result/              # Endergebnis
├── projekt-name/            # Projektunterverzeichnis
│   ├── src/                 # Quellcode
│   ├── assets/              # Ressourcendateien
│   └── docs/                # Dokumentation
└── ...

Ausführungsregeln:

1. Jede neue Aufgabe/jedes neue Projekt → Erstelle ein Unterverzeichnis in output/
2. Unterverzeichnisbenennung → Verwende das Format task-Nummer-kurze-Beschreibung oder Projektname
3. Standardmäßig erstellen → Vor Dateioperationen das output/-Verzeichnis erstellen (falls nicht vorhanden)
4. Dateizugehörigkeit → Alle generierten Dateien, heruntergeladenen Inhalte und Skriptausgaben gehören in das entsprechende Unterverzeichnis

Warum ist das wichtig?

• Vermeidet Unordnung im Wurzelverzeichnis des Workspace
• Aufgaben sind nachvollziehbar und rückverfolgbar
• Erleichtert Bereinigung und Archivierung
• Unterstützt parallele Bearbeitung mehrerer Aufgaben

Erforderliche Dateien (minimale lauffähige Menge)

Datei	Zweck	Pflichtfeld
AGENTS.md	Definiert das Verhalten jeder Session, Gedächtnisregeln, Sicherheitsgrenzen	✅
IDENTITY.md	Definiert "Wer bin ich"	✅
SOUL.md	Definiert "Wie ich denke und mich ausdrücke"	✅
MEMORY.md	Container für Langzeiterinnerungen	✅
USER.md	Benutzerprofil (für main agent dringend empfohlen, für andere optional)	Empfohlen
TOOLS.md	Umgebungsspezifische Notizen	Empfohlen
HEARTBEAT.md	Regelmäßige Überprüfungsaufgaben	Optional
.openclaw/workspace-state.json	Markiert Onboarding als abgeschlossen	Empfohlen
memory/	Speichert tägliche Erinnerungen	✅
diary/	Privater Tagebuchbereich	Empfohlen

Konfigurationsdatei ändern: ~/.openclaw/openclaw.json

Schritt 1: Agent registrieren

Füge zum agents.list-Array hinzu:

{
  "id": "<deine-agenten-id>",
  "name": "<dein-agenten-name>",
  "workspace": "/root/.openclaw/workspace/agents/<deine-agenten-id>",
  "agentDir": "/root/.openclaw/agents/<deine-agenten-id>",
  "memorySearch": {
    "enabled": true
  },
  "subagents": {
    "allowAgents": ["*"]
  }
}

Platzhaltererkläerung:

• <deine-agenten-id>: Eindeutige Kennung des Agenten, z. B. writer, assistant, novelist
• <dein-agenten-name>: Anzeigename (optional, standardmäßig gleich der ID)

Feldbeschreibung:

• id: Eindeutige Kennung des Agenten, systemweit eindeutig, darf nicht mit anderen Agenten-ID übereinstimmen
• name: Anzeigename (optional), wird in Logs und Antworten angezeigt
• workspace: Pfad zum Seelen-Workspace, das System liest von hier die Persönlichkeitsdateien (IDENTITY.md, SOUL.md usw.)
• agentDir: Laufzeitpfad, das System erstellt automatisch sessions/ und models.json
• memorySearch.enabled: Ob die vektorbasierte Gedächtnissuche aktiviert ist; wird empfohlen, sie zu aktivieren
• subagents.allowAgents: Liste der Agenten, die dieser Agent spawnen darf; ["*"] bedeutet, dass jeder Agent gespawnt werden darf

Zur Modellkonfiguration: Das Modell wird nicht auf Agentenebene einzeln konfiguriert, sondern global über agents.defaults.model einheitlich festgelegt. Alle Agenten erben das Standardmodell. Wenn für einen bestimmten Agenten ein anderes Modell gewünscht ist, kann in agents.defaults.models von openclaw.json ein Alias definiert werden.

Über subagents.allowAgents

subagents.allowAgents steuert, ob dieser Agent andere Agenten über sessions_spawn starten darf und welche Agenten in agents_list sichtbar sind.

Konfigurationswert	Bedeutung	agents_list-Effekt
["*"]	Darf jeden Agenten spawnen	allowAny: true, zeigt alle Agenten
["player", "writer"]	Whitelist-Modus	Zeigt nur die angegebenen Agenten
[] oder nicht konfiguriert	Darf nur sich selbst spawnen	Gibt nur sich selbst zurück

Empfehlung: Für Szenarien mit mehreren zusammenarbeitenden Agenten auf ["*"] setzen, um die vollständige Agentenerkennung zu aktivieren.

Schritt 2: Feishu-Channel-Konto konfigurieren

Füge unter channels.feishu.accounts ein Konto hinzu (unabhängig von der Agentenkonfiguration, kann für mehrere Agenten wiederverwendet werden):

"<deine-feishu-konto-id>": {
  "appId": "<deine-app-id>",
  "appSecret": "<dein-app-secret>",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

Platzhaltererkläerung:

• <deine-feishu-konto-id>: Kennung des Feishu-Kontos, beliebige Zeichenkette, z. B. mybot, writer-feishu
• <deine-app-id>: AppID von der Feishu Open Platform (Format: cli_xxxxxxxx)
• <dein-app-secret>: AppSecret von der Feishu Open Platform

Detaillierte Channel-Strategiebeschreibung:

Feld	Typ	Pflichtfeld	Beschreibung
appId	string	✅	AppID der Feishu-App, abrufbar von der Feishu Open Platform
appSecret	string	✅	AppSecret der Feishu-App, gepaart mit der AppID
dmPolicy	string	✅	Direktnachrichten-Strategie, siehe Tabelle unten
groupPolicy	string	✅	Gruppenchat-Strategie, siehe Tabelle unten
allowFrom	string[]	Optional	Whitelist für Direktnachrichten, nur diese open_id können privat chatten
groupAllowFrom	string[]	Optional	Whitelist für Gruppenchat, nur diese open_id können den Bot in Gruppen erwähnen
requireMention	boolean	Optional	Ob der Bot in Gruppen erwähnt werden muss, um zu antworten

Policy-Strategietypen im Detail:

Strategiewert	Bedeutung	Anwendungsfall
"pairing"	Paarung erforderlich	Privater Agent, der Zugriffskontrolle benötigt
"open"	Jeder kann interagieren	Öffentlicher Agent, z. B. Kundenservice, Informationsabfrage
"allowlist"	Nur Whitelist-Benutzer können interagieren	Für bestimmte Benutzergruppen, in Kombination mit allowFrom

Hinweise:

• Bei erstmaliger Verwendung der pairing-Strategie erhält man in der Direktnachricht einen Paarungscode; diesen auf der Kimi Claw Web-Einstellungsseite anzeigen und eingeben
• In allowFrom und groupAllowFrom werden die open_id der Benutzer eingetragen (Format ou_xxxxxxxx)

Schritt 3: Agent an Feishu-Konto binden (Bindings)

Füge zum bindings-Array hinzu, um den Agenten mit dem Feishu-Channel-Konto zu verknüpfen:

{
  "agentId": "<deine-agenten-id>",
  "match": {
    "channel": "feishu",
    "accountId": "<deine-feishu-konto-id>"
  }
}

Logik der Bindung:

• agentId: Verweist auf die in agents.list definierte Agenten-ID
• match.channel: Kanaltyp, hier feishu
• match.accountId: Verweist auf den in channels.feishu.accounts definierten Kontoschlüssel

Bindungs-Matching-Regeln:

Wenn der Feishu-Channel eine Nachricht erhält, geht OpenClaw wie folgt vor:

1. Ermittle das Feishu-Konto der Nachrichtenquelle (accountId)
2. Suche in bindings nach Einträgen mit übereinstimmendem match.accountId
3. Finde anhand der agentId die entsprechende Agentenkonfiguration
4. Leite die Nachricht an den Workspace dieses Agenten zur Verarbeitung weiter

Eins-zu-eins vs. Eins-zu-viele:

• Eins-zu-eins-Bindung (empfohlen): Ein Feishu-Konto ist an einen Agenten gebunden

  { "agentId": "writer", "match": { "channel": "feishu", "accountId": "writer-feishu" } }
  

• Eins-zu-viele-Bindung: Mehrere Feishu-Konten können an denselben Agenten gebunden werden

  { "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-1" } }
  { "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-2" } }
  

• Viele-zu-eins-Bindung: Ein Feishu-Konto wird basierend auf Bedingungen an verschiedene Agenten weitergeleitet (erfordert erweiterte Matching-Regeln)

Vollständiger Erstellungsablauf (am Beispiel des Agenten "writer")

Das folgende Beispiel zeigt, wie du einen Agenten namens writer erstellst, der an das Feishu-Konto writer-feishu gebunden wird:

Schritt 1: Verzeichnisse erstellen

mkdir -p /root/.openclaw/workspace/agents/writer/{memory,diary,output,.openclaw}

Hinweis: Das Verzeichnis output/ dient der Ablage aller Aufgaben-/Projektausgabedateien und folgt den Output-Ordner-Regeln in AGENTS.md.

Schritt 2: Persönlichkeitsdateien schreiben

Erstelle folgende Dateien (Inhalt je nach Persönlichkeit anpassen):

• IDENTITY.md — Name, Ausstrahlung, Signaturzeile, Emoji
• SOUL.md — Kernpersönlichkeit, Sprechweise, Geschmack und Abneigungen
• AGENTS.md — Arbeitsregeln, Gedächtnisregeln, Heartbeat-Verhalten, Output-Ordner-Regeln
• MEMORY.md — Startseite des Langzeitgedächtnisses (Aufgaben, Änderungsprotokoll)
• USER.md — Vorlage für Benutzerprofil
• TOOLS.md — Vorlage für Umgebungsnotizen
• HEARTBEAT.md — Kann zunächst leer bleiben oder mit Kommentaren versehen werden

Schritt 3: Statusdatei schreiben

cat > /root/.openclaw/workspace/agents/writer/.openclaw/workspace-state.json << 'EOF'
{
  "version": 1,
  "onboardingCompletedAt": "2026-04-14T02:46:05.000Z"
}
EOF

Schritt 4: ~/.openclaw/openclaw.json ändern

① Agent registrieren (zu agents.list hinzufügen):

{
  "id": "writer",
  "name": "writer",
  "workspace": "/root/.openclaw/workspace/agents/writer",
  "agentDir": "/root/.openclaw/agents/writer",
  "memorySearch": {
    "enabled": true
  }
}

Hinweis: Das Modell wird nicht auf Agentenebene konfiguriert, sondern vom globalen Standardmodell geerbt oder über agents.defaults.model einheitlich festgelegt.

② Feishu-Channel konfigurieren (zu channels.feishu.accounts hinzufügen):

"writer-feishu": {
  "appId": "cli_xxxxxxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

⚠️ Ersetze cli_xxxxxxxxxxxxxxxx und xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx durch die tatsächlichen Anmeldedaten von der Feishu Open Platform.

③ Agent an Feishu binden (zu bindings hinzufügen):

{
  "agentId": "writer",
  "match": {
    "channel": "feishu",
    "accountId": "writer-feishu"
  }
}

Schritt 5: Gateway neustarten

openclaw gateway restart

Vor der Ausführung muss der Benutzer ausdrücklich informiert werden: "Ich werde jetzt das OpenClaw Gateway neustarten, um die neue Konfiguration anzuwenden."

Schritt 6: Verbindung überprüfen

Prüfe in den Logs, ob der WebSocket eingerichtet wurde:

cat /root/.openclaw/logs/openclaw.log | grep "feishu\[writer-feishu\]"

Erwartete Ausgabe:

feishu[writer-feishu]: starting WebSocket connection...
feishu[writer-feishu]: received message from ...

Häufige Fehler und Fehlerbehebung

1. "Channel is required when multiple channels are configured"

• Wenn für einen Agenten ein Cron-Job erstellt wurde, aber kein channel explizit angegeben ist, tritt dieser Fehler auf
• Lösung: Füge in der Cron-Konfiguration "channel": "feishu" und "accountId": "writer-feishu" hinzu

2. Feishu-Nachrichten werden nicht an den neuen Agenten weitergeleitet

• Überprüfe, ob accountId in bindings mit dem Schlüssel in channels.feishu.accounts übereinstimmt
• Überprüfe, ob agentId mit der id in agents.list übereinstimmt
• Überprüfe die Syntax von openclaw.json auf Korrektheit (Kommas, Klammern)
• Überprüfe, ob channels.feishu.enabled auf true gesetzt ist

3. Paarung fehlgeschlagen

• Wenn dmPolicy auf pairing gesetzt ist, wird bei der ersten Direktnachricht ein Paarungscode benötigt
• Der Paarungscode kann auf der Kimi Claw Web-Einstellungsseite eingesehen oder von einem bereits gepaarten Benutzer weitergeleitet werden

4. "appId or appSecret not configured"

• Überprüfe, ob die Anmeldedaten der Feishu-App korrekt eingetragen sind
• Überprüfe, ob die Feishu-App auf der Open Platform aktiviert und eine Version veröffentlicht wurde

Vollständiges minimales Konfigurationsbeispiel

Das Folgende ist ein vollständig lauffähiger Ausschnitt einer openclaw.json, der die Verknüpfung von Agent, Channel und Bindings zeigt:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "kimi-coding/k2p5"
      }
    },
    "list": [
      {
        "id": "writer",
        "name": "writer",
        "workspace": "/root/.openclaw/workspace/agents/writer",
        "agentDir": "/root/.openclaw/agents/writer",
        "memorySearch": { "enabled": true },
        "subagents": {
          "allowAgents": ["*"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "writer",
      "match": { "channel": "feishu", "accountId": "writer-feishu" }
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "requireMention": false,
      "defaultAccount": "main-bot",
      "accounts": {
        "writer-feishu": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dmPolicy": "pairing",
          "groupPolicy": "pairing",
          "allowFrom": [],
          "groupAllowFrom": []
        }
      }
    }
  }
}

Hinweise:

• Die Modellkonfiguration wird in agents.defaults.model zentral festgelegt; alle Agenten erben dieses Standardmodell
• subagents.allowAgents: ["*"] aktiviert die vollständige Agentenerkennung und die Zusammenarbeit mehrerer Agenten

Abbildung der Schlüsselbeziehungen:

┌─────────────────────────────────────────────────────────────┐
│  Nachricht trifft bei Feishu ein (appId: cli_xxxxxxxx)      │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Channel: channels.feishu.accounts["writer-feishu"]         │
│  → Identifizierte accountId: "writer-feishu"                │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Binding: bindings.find(b => b.match.accountId === "writer-feishu")
│  → Gefunden: { agentId: "writer", ... }                     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent: agents.list.find(a => a.id === "writer")            │
│  → Gefunden: { workspace: "/root/.openclaw/workspace/agents/writer" }
│  → Lade SOUL.md, IDENTITY.md, MEMORY.md aus diesem Pfad     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent "writer" verarbeitet die Nachricht und antwortet     │
└─────────────────────────────────────────────────────────────┘