OpenClaw Skills konfigurieren: Anleitung & Pfade

Standorte und Priorität

OpenClaw lädt Skills aus diesen Quellen:

1. Extra skill folders: konfiguriert über skills.load.extraDirs
2. Bundled skills: werden mit der Installation ausgeliefert (npm-Paket oder OpenClaw.app)
3. Managed/local skills: ~/.openclaw/skills
4. Personal agent skills: ~/.agents/skills
5. Project agent skills: <workspace>/.agents/skills
6. Workspace skills: <workspace>/skills

Falls es Namenskonflikte bei Skills gibt, gilt diese Priorität:

<workspace>/skills (höchste) → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled skills → skills.load.extraDirs (niedrigste)

Agent-spezifische vs. geteilte Skills

In Setups mit mehreren Agents hat jeder Agent seinen eigenen Workspace. Das bedeutet für dich:

• Agent-spezifische Skills liegen in <workspace>/skills und sind nur für diesen einen Agent verfügbar.
• Project agent skills liegen in <workspace>/.agents/skills und greifen in diesem Workspace noch vor dem normalen skills/ Ordner.
• Personal agent skills liegen in ~/.agents/skills und funktionieren workspace-übergreifend auf deiner Maschine.
• Shared skills liegen in ~/.openclaw/skills (managed/local) und sind für alle Agents auf derselben Maschine sichtbar.
• Shared folders lassen sich auch über skills.load.extraDirs hinzufügen (niedrigste Priorität), falls du ein gemeinsames Skill-Paket für mehrere Agents nutzen willst.

Wenn derselbe Skill-Name an mehr als einem Ort existiert, greift die übliche Priorität: Workspace gewinnt, dann Project Agent Skills, dann Personal Agent Skills, dann managed/local, dann bundled und zuletzt extra Dirs.

Agent Skill Allowlists

Der Standort eines Skills und seine Sichtbarkeit sind zwei verschiedene Kontrollmechanismen.

• Der Standort und die Priorität entscheiden, welche Kopie eines gleichnamigen Skills gewinnt.
• Die Agent Allowlists entscheiden, welche der sichtbaren Skills ein Agent tatsächlich nutzen darf.

Verwende agents.defaults.skills für eine gemeinsame Basis und überschreibe diese bei Bedarf pro Agent mit agents.list[].skills:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

Hier sind die Regeln:

• Lass agents.defaults.skills weg, wenn Skills standardmäßig uneingeschränkt verfügbar sein sollen.
• Lass agents.list[].skills weg, um die agents.defaults.skills zu erben.
• Setze agents.list[].skills: [], wenn der Agent gar keine Skills erhalten soll.
• Eine Liste in agents.list[].skills, die nicht leer ist, bildet das finale Set für diesen Agent; sie wird nicht mit den Defaults gemischt.

OpenClaw wendet dieses effektive Skill-Set beim Prompt-Building, bei der Discovery von Skill-Slash-Commands, beim Sandbox-Sync und bei Skill-Snapshots an.

Plugins + Skills

Plugins können eigene Skills mitbringen, indem sie skills-Verzeichnisse in der openclaw.plugin.json auflisten (Pfade relativ zum Plugin-Root). Plugin-Skills werden geladen, sobald das Plugin aktiviert ist. Aktuell werden diese Verzeichnisse in denselben Pfad mit niedriger Priorität wie skills.load.extraDirs gemischt. Das bedeutet, dass ein gleichnamiger bundled, managed, agent oder workspace Skill diese überschreibt. Du kannst den Zugriff über metadata.openclaw.requires.config im Config-Eintrag des Plugins steuern. Schau dir Plugins für Discovery/Config und Tools für die Tool-Oberfläche an, die durch diese Skills gesteuert werden.

ClawHub (install + sync)

ClawHub ist das öffentliche Skills-Registry für OpenClaw. Schau dich auf https://clawhub.ai um. Nutze native openclaw skills Befehle, um Skills zu entdecken, zu installieren oder zu aktualisieren. Wenn du Publish- oder Sync-Workflows benötigst, nimmst du das separate clawhub CLI. Vollständiger Guide: ClawHub.

Typische Abläufe:

• Installiere einen Skill in deinen Workspace:
  • openclaw skills install <skill-slug>
• Aktualisiere alle installierten Skills:
  • openclaw skills update --all
• Sync (Scan + Updates veröffentlichen):
  • clawhub sync --all

Der native Befehl openclaw skills install installiert direkt in das skills/ Verzeichnis deines aktiven Workspace. Das separate clawhub CLI installiert ebenfalls nach ./skills unter deinem aktuellen Arbeitsverzeichnis (oder nutzt den konfigurierten OpenClaw Workspace). OpenClaw erkennt das beim nächsten Start automatisch als <workspace>/skills.

Sicherheitshinweise

• Betrachte Skills von Drittanbietern immer als nicht vertrauenswürdigen Code. Lies den Code, bevor du ihn aktivierst.
• Nutze für unsicheren Input und riskante Tools am besten Sandboxed-Runs. Siehe Sandboxing.
• Die Skill-Discovery für Workspaces und Extra-Verzeichnisse akzeptiert nur Skill-Roots und SKILL.md Dateien, deren aufgelöster Pfad (realpath) innerhalb des konfigurierten Roots bleibt.
• Gateway-basierte Installationen von Skill-Abhängigkeiten (skills.install, Onboarding und die Skills-UI) lassen den eingebauten Scanner für gefährlichen Code laufen, bevor Installer-Metadaten ausgeführt werden. critical Funde blockieren standardmäßig, außer du setzt explizit einen Dangerous-Override; bei verdächtigen Funden wird lediglich gewarnt.
• openclaw skills install <slug> funktioniert anders: Es lädt einen ClawHub-Ordner direkt in den Workspace herunter und nutzt den oben genannten Pfad für Installer-Metadaten nicht.
• skills.entries.*.env und skills.entries.*.apiKey injizieren Secrets in den Host-Prozess des Agents (nicht in die Sandbox). Halte Secrets aus Prompts und Logs fern.
• Für ein umfassenderes Threat Model und Checklisten schau unter Security nach.

Format (AgentSkills + Pi-kompatibel)

Deine SKILL.md muss mindestens diesen Teil enthalten:

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

Hinweise:

• Wir folgen der AgentSkills-Spezifikation für Layout und Intent.
• Der Parser des eingebetteten Agents unterstützt nur einzeilige Frontmatter-Keys.
• metadata sollte ein einzeiliges JSON-Objekt sein.
• Nutze {baseDir} in den Instructions, um auf den Pfad des Skill-Ordners zu verweisen.
• Optionale Frontmatter-Keys:

  • homepage — URL, die in der macOS Skills-UI als „Website“ angezeigt wird (auch via metadata.openclaw.homepage unterstützt).

  • user-invocable — true|false (Standard: true). Wenn true, wird der Skill als Slash-Command für User verfügbar.

  • disable-model-invocation — true|false (Standard: false). Wenn true, wird der Skill aus dem Model-Prompt ausgeschlossen (bleibt aber via Slash-Command aufrufbar).

  • command-dispatch — tool (optional). Wenn auf tool gesetzt, umgeht der Slash-Command das Model und wird direkt an ein Tool gesendet.

  • command-tool — Name des Tools, das bei command-dispatch: tool aufgerufen wird.

  • command-arg-mode — raw (Standard). Leitet bei Tool-Dispatch den rohen Argument-String ohne Parsing an das Tool weiter.

    Das Tool wird mit diesen Parametern aufgerufen: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Gating (Filter beim Laden)

OpenClaw filtert Skills beim Laden mithilfe von metadata (einzeiliges JSON):

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Felder unter metadata.openclaw:

• always: true — Skill immer einbinden (überspringt andere Gates).
• emoji — Optionales Emoji für die macOS Skills-UI.
• homepage — Optionale URL für die macOS Skills-UI.
• os — Optionale Liste von Plattformen (darwin, linux, win32). Der Skill wird nur auf diesen Betriebssystemen geladen.
• requires.bins — Liste von Binaries, die im PATH existieren müssen.
• requires.anyBins — Liste; mindestens eines der Binaries muss im PATH existieren.
• requires.env — Liste; Umgebungsvariablen müssen existieren oder in der Config bereitgestellt werden.
• requires.config — Liste von Pfaden in der openclaw.json, die “truthy” sein müssen.
• primaryEnv — Name der Umgebungsvariable, die mit skills.entries.<name>.apiKey verknüpft ist.
• install — Optionales Array von Installer-Specs für die macOS Skills-UI (brew/node/go/uv/download).

Hinweis zum Sandboxing:

• requires.bins wird beim Laden des Skills auf dem Host geprüft.
• Wenn ein Agent in einer Sandbox läuft, muss das Binary auch innerhalb des Containers existieren. Installiere es über agents.defaults.sandbox.docker.setupCommand (oder ein eigenes Image). setupCommand läuft einmalig nach der Erstellung des Containers. Paket-Installationen benötigen zudem Netzwerkzugriff, ein beschreibbares Root-Dateisystem und einen Root-User in der Sandbox. Beispiel: Der summarize Skill (skills/summarize/SKILL.md) benötigt das summarize CLI im Sandbox-Container.

Beispiel für einen Installer:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Hinweise:

• Wenn mehrere Installer gelistet sind, wählt das Gateway eine einzelne bevorzugte Option (Brew falls verfügbar, sonst Node).
• Wenn alle Installer vom Typ download sind, listet OpenClaw jeden Eintrag einzeln auf.
• Installer-Specs können os: ["darwin"|"linux"|"win32"] enthalten, um Optionen nach Plattform zu filtern.
• Node-Installationen berücksichtigen skills.install.nodeManager in der openclaw.json (Standard: npm; Optionen: npm/pnpm/yarn/bun). Das betrifft nur Skill-Installationen; die Gateway-Runtime sollte weiterhin Node sein (Bun wird für WhatsApp/Telegram nicht empfohlen).
• Die Auswahl Gateway-basierter Installer folgt Prioritäten: Wenn Specs gemischt sind, bevorzugt OpenClaw Homebrew (wenn skills.install.preferBrew aktiv ist und brew existiert), dann uv, dann den konfigurierten Node-Manager und schließlich Fallbacks wie go oder download.
• Go-Installationen: Falls go fehlt und brew verfügbar ist, installiert das Gateway Go zuerst via Homebrew und setzt GOBIN nach Möglichkeit auf das Homebrew-Verzeichnis.
• Download-Installationen: url (erforderlich), archive (tar.gz | tar.bz2 | zip), extract (Standard: auto bei erkanntem Archiv), stripComponents, targetDir (Standard: ~/.openclaw/tools/<skillKey>).

Wenn kein metadata.openclaw vorhanden ist, ist der Skill immer verfügbar (außer er wurde in der Config deaktiviert oder durch skills.allowBundled für Bundled-Skills blockiert).

Konfigurations-Overrides (~/.openclaw/openclaw.json)

Du kannst gebündelte oder verwaltete Skills umschalten und ihnen spezifische Umgebungsvariablen mitgeben:

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Hinweis: Falls ein Skill-Name Bindestriche enthält, musst du den Key in Anführungszeichen setzen (JSON5 erlaubt das).

Wenn du Bilder direkt in OpenClaw generieren oder bearbeiten möchtest, solltest du das Core-Tool image_generate zusammen mit agents.defaults.imageGenerationModel nutzen, anstatt einen gebündelten Skill zu verwenden. Die Skill-Beispiele hier sind für eigene Workflows oder Drittanbieter gedacht.

Für native Bildanalysen nutzt du das image Tool mit agents.defaults.imageModel. Für native Bildgenerierung oder Bearbeitung nimmst du image_generate mit agents.defaults.imageGenerationModel. Wenn du dich für openai/*, google/*, fal/* oder ein anderes providerspezifisches Modell entscheidest, musst du auch den entsprechenden Auth/API Key des Providers hinterlegen.

Standardmäßig entsprechen die Config-Keys dem Skill-Namen. Wenn ein Skill metadata.openclaw.skillKey definiert, verwende diesen Key unter skills.entries.

Regeln:

• enabled: false deaktiviert den Skill, selbst wenn er gebündelt oder installiert ist.
• env: Wird nur dann injiziert, wenn die Variable im Prozess noch nicht gesetzt ist.
• apiKey: Eine Abkürzung für Skills, die metadata.openclaw.primaryEnv deklarieren. Unterstützt Plaintext-Strings oder ein SecretRef-Objekt ({ source, provider, id }).
• config: Optionales Feld für benutzerdefinierte Skill-Einstellungen; eigene Keys müssen hier liegen.
• allowBundled: Optionale Allowlist, die nur für gebündelte Skills gilt. Falls gesetzt, sind nur die gelisteten gebündelten Skills verfügbar (verwaltete oder Workspace-Skills bleiben davon unberührt).

Environment-Injection (pro Agent-Run)

Sobald ein Agent-Run startet, führt OpenClaw folgende Schritte aus:

1. Die Skill-Metadaten werden gelesen.
2. Alle Werte aus skills.entries.<key>.env oder skills.entries.<key>.apiKey werden auf process.env angewendet.
3. Der System-Prompt wird mit den berechtigten Skills erstellt.
4. Nach Abschluss des Runs wird das ursprüngliche Environment wiederhergestellt.

Dieser Vorgang ist auf den Agent-Run begrenzt und betrifft nicht deine globale Shell-Umgebung.

Für das gebündelte claude-cli Backend erstellt OpenClaw zudem einen Snapshot der berechtigten Skills als temporäres Claude Code Plugin und übergibt diesen via --plugin-dir. So kann Claude Code seine native Skill-Auflösung nutzen, während OpenClaw weiterhin die Kontrolle über Prioritäten, Agent-Allowlists und die Injection von Env/API Keys behält. Andere CLI-Backends nutzen stattdessen nur den Prompt-Katalog.

Session-Snapshot (Performance)

OpenClaw erstellt einen Snapshot der verfügbaren Skills, wenn eine Session startet, und nutzt diese Liste für alle weiteren Turns innerhalb derselben Session. Änderungen an Skills oder der Konfiguration greifen erst bei der nächsten neuen Session.

Skills können jedoch auch während einer Session aktualisiert werden, wenn der Skills-Watcher aktiv ist oder ein neuer berechtigter Remote-Node auftaucht (siehe unten). Das funktioniert wie ein Hot Reload: Die aktualisierte Liste wird beim nächsten Turn des Agenten übernommen.

Falls sich die effektive Skill-Allowlist des Agenten für diese Session ändert, aktualisiert OpenClaw den Snapshot, damit die sichtbaren Skills immer zum aktuellen Agenten passen.

Remote macOS-Nodes (Linux Gateway)

Wenn das Gateway auf Linux läuft, aber ein macOS-Node verbunden ist, bei dem system.run erlaubt ist (Security-Einstellung für Exec-Freigaben steht nicht auf deny), kann OpenClaw reine macOS-Skills als verfügbar einstufen, sofern die benötigten Binaries auf diesem Node vorhanden sind. Der Agent führt diese Skills dann über das exec Tool mit host=node aus.

Das System verlässt sich darauf, dass der Node seinen Support für Befehle meldet und ein Bin-Probe via system.run erfolgreich ist. Falls der macOS-Node später offline geht, bleiben die Skills sichtbar, aber Aufrufe schlagen eventuell fehl, bis der Node wieder verbunden ist.

Skills-Watcher (Auto-Refresh)

Standardmäßig überwacht OpenClaw deine Skill-Ordner und aktualisiert den Snapshot der Skills, sobald sich SKILL.md-Dateien ändern. Das kannst du unter skills.load konfigurieren:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token-Auswirkung (Skills-Liste)

Wenn Skills infrage kommen, fügt OpenClaw eine kompakte XML-Liste der verfügbaren Skills in den System Prompt ein (über formatSkillsForPrompt in pi-coding-agent). Die Kosten dafür sind fest definiert:

• Basis-Overhead (nur bei ≥1 Skill): 195 Zeichen.
• Pro Skill: 97 Zeichen + die Länge der XML-escaped Werte für <name>, <description> und <location>.

Formel (Zeichen):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

Hinweise:

• XML-Escaping wandelt & < > " ' in Entities um (&, < usw.), was die Länge erhöht.
• Die Token-Anzahl variiert je nach Tokenizer des Models. Eine grobe Schätzung im OpenAI-Stil liegt bei ca. 4 Zeichen pro Token. Damit entsprechen 97 Zeichen ≈ 24 Token pro Skill, plus die Länge deiner tatsächlichen Feldinhalte.

Lebenszyklus verwalteter Skills

OpenClaw liefert eine Basis-Auswahl an Skills als bundled skills direkt mit der Installation aus (npm package oder OpenClaw.app). Das Verzeichnis ~/.openclaw/skills ist für deine lokalen Overrides reserviert. Das ist der beste Weg, wenn du einen Skill per pinning oder patching anpassen willst, ohne die bundled Version zu ändern. Workspace-Skills sind dein Bereich; sie überschreiben bei Namenskonflikten sowohl bundled als auch lokale Skills.

Konfigurationsreferenz

In der Skills-Konfiguration findest du alle Details zum vollständigen Schema.

Suchst du nach weiteren Skills?

Schau dich auf https://clawhub.ai um.

Verwandte Themen

• Skills erstellen — Eigene Skills bauen
• Skills Config — Referenz für die Skill-Konfiguration
• Slash Commands — Alle verfügbaren Slash Commands
• Plugins — Übersicht über das Plugin-System