Schnellstart: WPAgently in unter 30 Minuten

Diese Anleitung verbindet deinen eigenen KI-Assistenten mit deiner WordPress-Seite. Der vollständig geführte Kernablauf gilt für Claude Code, Claude Desktop, Codex und ChatGPT. Das WordPress-Backend erzeugt außerdem Konfigurationen für Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity. Danach kann der Assistent Blogartikel und Landing-Pages erstellen, und WPAgently prüft nach jeder Änderung nach, ob sie wirklich funktioniert hat. Rechne mit etwa 25 Minuten.

Zwei Dinge vorweg, damit du entspannt bleibst:

Erstens bleiben deine Inhalte und WordPress-Logins ausschließlich bei dir. WPAgently läuft auf deinem Rechner und deiner Seite. Nur die Lizenzaktivierung und die tägliche Lizenzprüfung gehen direkt an Polars Lizenz-API, native Plugin-Updates lesen ein statisches Release-Manifest von wpagently.com. Dabei werden weder Inhalte noch WordPress-Zugangsdaten übertragen.

Zweitens ist die Anleitung in sechs kurze Schritte geteilt. Nach jedem Schritt steht, woran du erkennst, dass er geklappt hat. Wenn dir ein Schritt zu technisch vorkommt: Er ist es nicht. Kopiere die Befehle einfach so, wie sie hier stehen, in dein Terminal (das schwarze Eingabefenster, in dem du Befehle tippst). Du musst nichts davon verstehen, um es korrekt auszuführen.

Was du vorher brauchst

Diese Dinge sollten vorhanden sein, bevor du loslegst. Die meisten davon hast du wahrscheinlich schon.

• WordPress 6.9+. Ab Version 6.9 ist die sogenannte Abilities API im WordPress-Kern enthalten. Das ist die Schnittstelle, über die das Zusatz-Plugin von WPAgently später mit deiner Seite spricht. Deine WordPress-Version findest du im Backend unten rechts oder unter „Werkzeuge > Website-Zustand“.
• Pretty-Permalinks aktiv (Einstellungen > Permalinks, irgendeine Option außer „Einfach“ bzw. „Plain“). Permalinks sind die Struktur deiner URLs. Eine ganz frische WordPress-Installation nutzt „Einfach“ als Standard, und in diesem Zustand ist die technische Schnittstelle, über die der Assistent sich verbindet, nicht erreichbar. Das ist der mit Abstand häufigste Fehler beim ersten Versuch, und er ist mit zwei Klicks behoben: Einstellungen > Permalinks öffnen, eine andere Option wählen, speichern.
• HTTPS auf deiner Seite (also eine Adresse, die mit https:// beginnt). Das ist für Browser-OAuth, Application Passwords und externe Clients wie Claude Code oder Codex erforderlich. Nur eine wirklich lokale Installation unter localhost oder 127.0.0.1 darf für Tests HTTP verwenden. Falls du dort ein Application Password brauchst, setzt du zusätzlich WP_ENVIRONMENT_TYPE auf local (siehe Schritt 2).
• PHP 8.1+. PHP ist die Programmiersprache, in der WordPress läuft, deine Version steht ebenfalls unter „Werkzeuge > Website-Zustand“. Prüfe dein Hosting auf ein PHP-Upgrade, bevor du das ZIP hochlädst. WordPress blockiert den Plugin-Upload auf älteren PHP-Versionen korrekt, damit kein inkompatibles Plugin installiert wird. Für eine lokale Testinstanz brauchst du zusätzlich die PHP-Erweiterung pdo_sqlite.
• Node.js 20 oder neuer auf deinem Rechner. Node.js ist die Umgebung, in der das kleine WPAgently-Programm (die CLI aus Schritt 3) läuft. Ob du es hast, prüfst du im Terminal mit node --version.
• Einen eigenen Zugang bei einem kompatiblen KI-Anbieter und einen von zwei Arbeitswegen. Der vollständig dokumentierte externe Weg nutzt Claude Code, Claude Desktop, Codex oder ChatGPT als MCP-Client. Geführte Verbindungsdateien gibt es zusätzlich für Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity. Für ChatGPT brauchst du eine Version mit benutzerdefinierten Apps im Entwicklermodus. Vollständige Schreibwerkzeuge stehen dort derzeit nur in Business-, Enterprise- und Edu-Arbeitsbereichen zur Verfügung. Alternativ kannst du ab WordPress 7.0 den integrierten Chat mit einem unter Einstellungen > Connectors eingerichteten KI-Anbieter verwenden. WPAgently ist in beiden Fällen die Sicherheitsschicht, nicht der KI-Anbieter selbst.

Zum MCP Adapter (wordpress/mcp-adapter) musst du übrigens nichts installieren. MCP ist die gemeinsame Sprache, über die KI-Assistenten mit externen Werkzeugen wie deiner WordPress-Seite reden. Das Zusatz-Plugin aus Schritt 1 bringt diesen Adapter schon mit, ein separates Fremd-Plugin dafür entfällt.

Schritt 1: Companion-Plugin installieren (etwa 5 Minuten)

Installiere und aktiviere das Plugin wp-agent-companion auf deiner Seite, genauso wie du jedes andere WordPress-Plugin installierst. „Aktivieren“ heißt: das Plugin im WordPress-Backend einschalten, sodass es zu arbeiten beginnt.

Dieses Companion-Plugin (Companion = Begleiter) ist das Herzstück auf der WordPress-Seite. Es meldet WordPress eine Reihe von „Abilities“ an. Eine Ability ist eine klar abgegrenzte, geprüfte Aktion, die der Assistent ausführen darf, zum Beispiel „einen Beitrag aus Markdown anlegen“. Nach der Aktivierung sind unter anderem diese Abilities angemeldet:

• wp-agent/create-post-from-markdown (der einzige Writer für neue Artikelinhalte in der verifizierten ARTIKEL-Pipeline; Updates sind derzeit manual_only)
• wp-agent/upsert-pattern (Landing-Pages aus einzelnen Abschnitten)
• wp-agent/get-seo-meta (SEO-Angaben provider-neutral lesen; set-seo-meta prüft den Zustand derzeit nur und endet vor jeder Provider-Mutation mit HTTP 409 und manual_only)
• wp-agent/render-verify (nur lesend: prüft die wirksame Darstellung, Blockstruktur und dokumentierte Providerfallen)
• wp-agent/refresh-hooks (holt Nacharbeiten nach, die WordPress sonst nur beim Speichern im Editor macht: Permalink-Regeln, Beitrags-Cache, Sitemap)
• wp-agent/write-theme-file (schreibt eine Datei ins aktive Theme, nur .html, .json und .css)
• wp-agent/disable-power (Not-Aus-Schalter für das separate Power-Plugin)

Die mit Skills 0.4.86 gebündelte Dokumentation beschreibt den Release-Satz aus Companion 0.4.117, Power 0.6.35 sowie CLI und Skills 0.4.86. Die bestätigte Zählung umfasst 414 Companion-Abilities, 317 im empfohlenen Inhaltsprofil, 440 kombinierte Companion- und Power-Schemas, 414 Companion-Tools und 34 geprüfte öffentliche Pfade. Free stellt exakt 34 eng begrenzte Kern-Abilities ohne Lizenzschlüssel, Site-Limit oder Aufrufslimit bereit. Das Operation Ledger ist eine administrative Funktion ohne Ability und ohne MCP-Vorabgenehmigung. Die übrigen Grenzen stehen in der Roadmap.

Katalogzahlen und reine Quellstandsignaturen belegen nicht von selbst, dass jede Ability in jedem Profil oder Providerzustand verfügbar ist.

Die Capability-Grenzen dieses Release-Satzes gelten unabhängig vom Auslieferungsweg. Das Operation Ledger ist kein MCP-Tool und keine Vorabgenehmigung.

Die vollständige aktuelle Liste steht in der Abilities-Referenz.

Nach der Plugin-Aktivierung ist WPAgently Free sofort nutzbar. Es ist kein Konto und kein Lizenzschlüssel nötig. Wenn du eine Jahreslizenz gekauft hast, öffne Werkzeuge > WPAgently-Lizenz, füge den von Polar erhaltenen Lizenzschlüssel ein und klicke „Lizenz aktivieren“. Die Aktivierung zählt genau diese Website gegen das Site-Limit deines Tarifs und erweitert dieselbe Installation auf die vollständige Companion-Oberfläche. Das Power-Plugin muss zusätzlich separat installiert und aktiviert werden. Seine eigenen serverseitigen Gates bleiben danach weiterhin geschlossen, bis du sie bewusst freischaltest. Ein vorübergehender Ausfall von Polar sperrt eine zuletzt erfolgreich geprüfte bezahlte Lizenz nicht sofort. Die lokale Bestätigung gilt höchstens sieben Tage. Free bleibt davon unabhängig verfügbar.

Das Plugin richtet nach der Aktivierung automatisch einen eigenen MCP-Server unter der Adresse <site>/wp-json/wp-agent/mcp ein. Öffne danach im Backend WPAgently > Übersicht. Dort zeigt die Einrichtungs-Karte zunächst PHP-, WordPress-, HTTPS- und Staging-Voraussetzungen und führt anschließend zum passenden Verbindungsschritt für deinen Client. Sie überträgt dabei keine Zugangsdaten. Mit dem Profil Nur lesen kannst du einen Agenten verbinden, ohne ihm schreibende Werkzeuge anzubieten. Der zusätzliche Domain Lock gehört zur bezahlten Lizenz.

Für den aktuellen Builder-Katalog gilt ausschließlich die Referenz. Sie beschreibt den Release-Satz 0.4.117/0.6.35/0.4.86 und seine Grenzen. Das Inhaltsprofil bleibt ohne das breitere Design- oder Vollzugriffsprofil nutzbar.

Bei dynamischen Builderdaten folgt dein Client immer dem Schema aus tools/list. Native Blockattribute und Supports verwenden den geschlossenen, integritätsgebundenen Umschlag {format,json,sha256,bytes}. Elementor- und Beaver-Builder-Dokumente verwenden bewusst den getrennten Umschlag {json,sha256,bytes}. Sende keine rohen JSON-Objekte an diese Felder. Werte, die die Grenze des jeweiligen Providerpfads überschreiten oder nicht in seinen öffentlichen Vertrag passen, werden abgelehnt, nicht still abgeschnitten.

Ab WordPress 7.0 kannst du zusätzlich den integrierten Chat unter WPAgently > Chat und Vorschau verwenden. Richte dafür zuerst unter Einstellungen > Connectors deinen eigenen KI-Anbieter ein. Der Chat recherchiert ausschließlich über die freigegebenen lesenden Abilities. Schreibende Vorschläge werden als Plan angezeigt und erst nach deiner einzelnen Freigabe unter dem gewählten Redakteur ausgeführt. Nachrichten und gelesene Website-Daten gehen direkt von WordPress an deinen KI-Anbieter, nicht über einen WPAgently-KI-Proxy. Die Vorschau erlaubt nur Pfade derselben Website und deaktiviert Seitenskripte sowie Formulare. Mit Element auswählen kannst du einen sichtbaren Seitenbereich anklicken und als begrenzten Kontext für deine nächste Nachricht übernehmen. Die Auswahl führt keinen CSS-Selektor aus und wird vom Modell ausdrücklich als nicht vertrauenswürdiger Website-Inhalt behandelt.

Für sichtbare Arbeiten im Gutenberg- oder Elementor-Editor öffnest du WPAgently > Live-Editor, wählst den dedizierten Redakteur und startest den Arbeitsbereich. Der Assistent kann danach über die bestehende MCP-Verbindung Seiten öffnen und ihre bestätigte Editor-Arbeitsfläche verwenden. Gutenberg-Änderungen erscheinen zunächst nur im Browser und werden erst durch den getrennt bestätigten Speicherbefehl dauerhaft. Elementor-Änderungen werden nach deiner Einzelbestätigung über den geprüften serverseitigen Elementor-Pfad mit Konfliktschutz, Revision und Rückleseprüfung ausgeführt. Beende die Sitzung nach der Arbeit. Bricks, Breakdance und Oxygen besitzen weiterhin keine bestätigte visuelle Laufzeit-Arbeitsfläche.

Geschafft, wenn: das Plugin als „Aktiv“ angezeigt wird und Werkzeuge > WPAgently-Lizenz den Status „Free aktiv“ oder „Bezahlt“ meldet. Alles Weitere prüfen wir in Schritt 5 automatisch nach.

Schritt 2: Dedizierten Editor-Bot anlegen (etwa 3 Minuten)

Öffne WPAgently > Agent verbinden und klicke auf „Dedizierten Agent-Nutzer anlegen“. Das Plugin erstellt einen eigenen Redakteur mit zufälligem internem Login-Passwort. Diesen eigenen Benutzer nennen wir „Bot-User“. Der Assistent arbeitet über dieses separate Konto, nie über dein eigenes. So bleibt dein Login unberührt, und du kannst dem Bot jederzeit die Rechte entziehen, ohne dich selbst auszusperren.

Der Bot bekommt die Rolle Editor, niemals Administrator. Läuft dein WordPress-Backend auf Deutsch, heißt diese Rolle in der Oberfläche „Redakteur“ (der technische Name bleibt editor, genau den prüft WPAgently). Ein Admin-Konto in falschen Händen wäre der größtmögliche Schaden, deshalb verweigert WPAgently jede Arbeit, sobald der Bot Admin-Rechte trägt. Das ist Absicht und schützt dich.

Application Passwords setzen HTTPS voraus. Ein Application Password ist ein spezielles WordPress-Passwort nur für Programme und Werkzeuge, getrennt von deinem normalen Login, das du jederzeit wieder zurückziehen kannst. Läuft deine Instanz lokal ohne SSL-Zertifikat (also ohne https://), ergänze stattdessen in der Datei wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' );

Ohne eine der beiden Bedingungen (HTTPS oder diese Zeile) erscheint der Menüpunkt „Anwendungspasswörter“ im Profil gar nicht erst.

Für OAuth-fähige Clients kopierst du unter WPAgently > Agent verbinden nur die angezeigte MCP-URL. Der Client öffnet bei der ersten Verbindung die WordPress-Anmeldung. Dort wählst du den neuen Redakteur aus und bestätigst den Zugriff. Ein Passwort wird dabei nicht in eine Konfigurationsdatei geschrieben.

Nur wenn dein Client OAuth nicht unterstützt, wählst du den Redakteur im Abschnitt „Fallback mit Application Password“ aus und lädst die passende Konfiguration einmalig herunter. Das Plugin erstellt dafür ein separates Application Password. Es speichert dessen Klartext nicht. Die heruntergeladene Datei enthält das Geheimnis und darf deshalb nie in Git landen. Du kannst die Verbindung später im Profil des Agent-Nutzers widerrufen.

Für die CLI brauchst du kein zusätzliches Application Password. Sie verbindet sich im empfohlenen Ablauf in Schritt 4 per Browser-OAuth. Dort wählst du genau diesen Redakteur aus und bestätigst den Zugriff. Ein weiteres Application Password ist nur der ausdrücklich dokumentierte Fallback, falls Browser-OAuth in deiner Umgebung nicht möglich ist.

Falls WPForms aktiv ist, findest du weiter unten drei getrennte Rechte für Formulare, Einträge und Schreibzugriffe. Formular-Lesen wird beim neu angelegten Agent-Nutzer automatisch vorbereitet, exponiert aber noch keine Werkzeuge. Eintragsrechte bleiben wegen möglicher personenbezogener Daten immer aus. Für Schreibzugriffe musst du zusätzlich unter WPForms > Werkzeuge > AI MCP den WPForms-eigenen Schalter aktivieren und die gewünschte Gruppe unter WPAgently > Übersicht freigeben. Der Agent bleibt dabei Redakteur. Administratorrechte werden nicht ergänzt. Die drei Rechte gelten nur am WPAgently-MCP-Endpunkt. Normale WPForms-Admin-, AJAX- und fremde REST-Pfade bleiben geschlossen.

Falls Ninja Forms aktiv ist, erscheinen vier getrennte Rechte für Formularlesen, sensible Einreichungen, Formularbearbeitung und E-Mail-Auslösung. Nur das Formularlesen wird für einen neu angelegten Agent-Nutzer vorbereitet. Die eigentlichen Werkzeuge bleiben zusätzlich durch das aktive WPAgently-Profil begrenzt. Einreichungen, Writes und E-Mail-Auslösung musst du ausdrücklich getrennt freigeben. Das breite Ninja-Forms-Recht nf_edit_forms wird dabei ausschließlich während eines passenden Aufrufs am WPAgently-MCP-Endpunkt vermittelt und nie dauerhaft am Nutzer gespeichert. Acht riskante Lösch-, Einstellungs-, Geheimnis- und Einreichungspfade bleiben vollständig gesperrt.

Geschafft, wenn: der neue Agent-Nutzer die Rolle Editor/Redakteur trägt und du entweder die OAuth-MCP-URL kopiert oder die Fallback-Konfiguration einmalig heruntergeladen hast.

Schritt 3: CLI installieren (etwa 2 Minuten)

Jetzt kommt das kleine WPAgently-Programm auf deinen eigenen Rechner. Es heißt CLI (Command-Line-Tool), also ein Programm, das du nicht anklickst, sondern durch Tippen eines Befehls im Terminal startest. Diese CLI ist die Fernbedienung, mit der du gleich alles einrichtest und prüfst.

Die wp-agent-CLI kommt als Node-Paket im gelieferten Archiv wp-agent-<version>.tgz (<version> steht für die Versionsnummer, die im Dateinamen deines Downloads steht). Installiere sie global direkt aus diesem Archiv:

npm install -g wp-agent-<version>.tgz

Prüfe danach die Installation:

wp-agent --help

Die Ausgabe muss die verfügbaren Befehle auflisten, unter anderem login, logout, preflight, abilities, doctor, article und landing. Wenn du diese Liste siehst, ist die CLI installiert.

Unter Windows erkennt die CLI ein natives wp.exe sowie die üblichen wp.bat- und wp.cmd-Launcher von WP-CLI und Local automatisch. Batchdateien werden aus Sicherheitsgründen nicht über cmd.exe ausgeführt. Liegt wie bei der offiziellen Installation wp-cli.phar daneben, startet WPAgently stattdessen PHP und das PHAR direkt. Falls WP-CLI oder PHP nicht im Suchpfad liegt, setze in PowerShell die absoluten Pfade:

$env:WP_AGENT_WP_CLI_BIN = "C:\Pfad\zu\wp.bat"
$env:WP_AGENT_PHP_BIN = "C:\Pfad\zu\php.exe"

WP_AGENT_WP_CLI_BIN akzeptiert alternativ wp.exe oder wp-cli.phar. Diese Variablen betreffen nur lokale Backup- und Restore-Läufe mit WP_AGENT_WP_PATH. Remote-Backups und normale REST- oder MCP-Verbindungen benötigen kein lokales WP-CLI.

Geschafft, wenn: wp-agent --help die Befehlsliste zeigt, statt einer Fehlermeldung wie „command not found“.

Schritt 4: CLI per Browser verbinden (etwa 3 Minuten)

Speichere zuerst nur die Basisadresse deiner Website in der Shell. Die Adresse enthält weder /wp-json noch einen abschließenden Slash:

export WP_AGENT_SITE="https://deine-domain.tld"

Starte danach die Anmeldung:

wp-agent login --site "$WP_AGENT_SITE"

Die CLI registriert einen eigenen öffentlichen OAuth-Client, öffnet deinen Browser und wartet lokal auf die Antwort. Melde dich im WordPress-Backend an, wähle den Redakteur aus Schritt 2 und bestätige den Zugriff. Danach speichert die CLI kurzlebige Zugriffstokens und ein rotierendes Refresh-Token in deinem privaten lokalen Konfigurationsordner. Unter macOS und Linux sind Ordner und Datei nur für deinen Benutzer lesbar. Dein WordPress-Passwort und das Passwort des Redakteurs werden weder an die CLI übergeben noch gespeichert.

Standardmäßig speichert eine Site höchstens 200 OAuth-Clients, offene Anmeldungen und aktive Verbindungen. Große Installationen können diese Grenze serverseitig über wpagent_companion_oauth_max_clients anpassen. Erlaubt sind Ganzzahlen von 1 bis 10.000. Ungültige Werte fallen auf 200 zurück. Eine Erhöhung vergrößert den Optionsspeicher und sollte nur mit einem konkreten Kapazitätsbedarf erfolgen.

Falls kein Browser geöffnet werden kann, zeigt wp-agent login --site "$WP_AGENT_SITE" --no-open die Freigabeadresse zum manuellen Öffnen an. Mit wp-agent logout --site "$WP_AGENT_SITE" widerrufst du den Serverzugang und entfernst den lokalen Eintrag. --force ist nur für den Sonderfall gedacht, dass der Server dauerhaft nicht mehr erreichbar ist. Dann wird ausschließlich der lokale Eintrag entfernt.

Application Passwords bleiben als Fallback erhalten. Setze dafür WP_AGENT_USER und WP_AGENT_APP_PASSWORD oder übergib --user und --app-password. Ein ausdrücklich gesetzter Passwortzugang hat Vorrang vor dem gespeicherten OAuth-Zugang. Flags mit Zugangsdaten können in Prozesslisten und im Shell-Verlauf sichtbar sein. Die CLI lädt keine .env-Datei automatisch.

wp-agent init ist für die normale CLI-Anmeldung nicht erforderlich. Standardmäßig erzeugt der Befehl statische MCP-Verbindungsdateien für Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity und benötigt dafür einen getrennten Benutzernamen und ein Application Password. Für Claude Code und Codex gibt es zusätzlich die benutzerweite OAuth-Registrierung aus Schritt 6. Sie benötigt kein WordPress-Passwort. Im geführten Ablauf hast du die passende Clientdatei bereits in Schritt 2 direkt aus WordPress heruntergeladen.

Geschafft, wenn: wp-agent login die erfolgreiche Verbindung meldet. Ab dann erneuert die CLI ablaufende Tokens automatisch.

Schritt 5: Smoke-Test (etwa 6 Minuten)

Jetzt der große Moment: Wir prüfen einmal komplett durch, ob alles zusammenspielt. „Smoke-Test“ ist nur ein gängiger Begriff für „kurz einschalten und schauen, ob es raucht“, also ein schneller Grundcheck.

Führe zuerst den Rundum-Check aus:

wp-agent doctor

Der Befehl erledigt in einem Durchlauf sieben Verbindungs- und Konfigurationsprüfungen. Er prüft Erreichbarkeit, Authentifizierung, Bot-Rolle, Lizenz, zentrale Companion-Steuerung, Kern-Abilities und MCP. Nur wenn alle sieben Checks OK melden, ist die Verbindung startklar. Schlägt eine Voraussetzung fehl, markiert wp-agent doctor abhängige Prüfungen als nicht ausgeführt. So kann eine nicht erreichbare Steuerung niemals als leere, aber angeblich vollständige Ability- oder MCP-Liste grün erscheinen.

Zusätzlich kannst du unter WPAgently > Agent verbinden eine externe Verbindungsdiagnose starten. WordPress ruft dabei ohne Zugangsdaten seine öffentliche REST-API, den MCP-Endpunkt und die OAuth-Metadaten über die normale Website-Adresse auf. Dadurch werden viele Sperren durch CDN, Firewall oder Security-Plugin sichtbar, die eine rein interne Prüfung nicht erkennt. Erkannte vorgeschaltete Dienste und bekannte aktive Security-Plugins erscheinen als Hinweise, nicht als pauschale Fehlerursache. Wenn eine bereits erfolgreich verwendete Verbindung später ihre Anmeldung verliert, zeigt WPAgently Administratoren außerdem eine Warnung mit direktem Link zu dieser Diagnose.

Für eine gezielte Einzelprüfung stehen zusätzlich wp-agent preflight (nur die Bot-Rolle) und wp-agent abilities (nur die Ability-Liste, jeweils markiert als readonly [R] = nur lesend oder schreibend [W]) zur Verfügung.

Zum Abschluss legst du einen ersten Test-Entwurf aus einer winzigen Textdatei an. Erzeuge sie zum Beispiel mit printf (ein Befehl, der schlicht Text in eine Datei schreibt):

printf '## Smoke-Test\n\nEin Absatz mit **Fett** und einer Liste:\n\n- eins\n- zwei\n' > test.md

Erzeuge daraus den Testartikel:

wp-agent article --markdown-file test.md --title "Smoke-Test" --slug smoke-test

Das Ergebnis muss Freiform: 0 melden. In der Render-Zeile steht zusätzlich Freiform=0. Das bedeutet, dass die Formatierung sauber in echte WordPress-Blöcke umgewandelt wurde und nichts in der alten, kaputten Editor-Ansicht gelandet ist. Der Beitrag bleibt automatisch ein Entwurf (Draft), du veröffentlichst also aus Versehen nichts.

Dieser Smoke-Test erzeugt bewusst einen minimalen Artikel. Ein vollständiger erster Beitrag mit Beitragsbild und anschließendem SEO-Read entsteht über den wp-article-Skill (Claude Code) beziehungsweise über die passenden Flags (--image, --alt, --seo-title, --seo-description, siehe wp-agent article --help). Mit Companion 0.4.30 oder neuer streamt die Artikel-Pipeline lokale Beitragsbilder automatisch über den kurzlebigen Direkt-Upload. Bei älteren Companion-Versionen nutzt sie kompatibel den bisherigen Core-REST-Upload. Öffentliche Bild-URLs werden heruntergeladen, wobei jedes Weiterleitungsziel erneut gegen den SSRF-Schutz geprüft wird. Für SEO-Angaben muss Rank Math, Yoast, AIOSEO oder SEOPress aktiv sein. set-seo-meta validiert die Eingabe, liest den Zustand frisch und bricht derzeit providerübergreifend mit HTTP 409 und manual_only vor jeder Mutation ab. Gewünschte Änderungen nimmst du im SEO-Plugin manuell vor und liest sie danach über get-seo-meta erneut.

Die Artikel- und Landing-Pipelines verlangen zusätzlich die flachen Schreibsemantiken remote_create und manual_only_update aus tools/list sowie das allgemeine manual_only. Companion-Stände, die diese Metadaten nicht liefern, werden für kombinierte Pipelines nicht als kompatibel angenommen: Die CLI bricht vor der ersten Remote-Mutation ab, weil sie einen späteren manuellen 409-Schreibpfad sonst nicht sicher erkennen kann. Das betrifft bestehende Markdown-Updates sowie SEO- und Status-Schritte. Einzelne Abilities bleiben nach ihrem jeweils installierten Schema nutzbar. Für Pipelines müssen CLI und Companion deshalb aus einem zusammengehörigen, semantisch kompatiblen Stand stammen.

Geschafft ist der Schritt, wenn wp-agent doctor siebenmal OK meldet und der Testartikel mit Freiform: 0 beziehungsweise Freiform=0 als Entwurf in deinem WordPress landet. Ein --publish-Aufruf ändert den Status derzeit nicht automatisch, weil set-post-status mit manual_only abbricht. Veröffentlichung und weitere Statuswechsel erfolgen nach der Prüfung manuell in WordPress. Ab hier steht die Verbindung.

Schritt 6: Agent verbinden (etwa 4 Minuten)

Die in Schritt 2 heruntergeladene Verbindungsdatei trägst du jetzt in deinen Assistenten ein. Sie ist von der OAuth-Anmeldung der CLI getrennt.

Für Claude Code ist .mcp.json direkt nutzbar: Lege die Datei in dein Projektverzeichnis. Claude Code erkennt den MCP-Server darüber beim nächsten Start automatisch. Alternativ registrierst du dieselbe Website einmal benutzerweit und ohne statisches WordPress-Passwort:

wp-agent init --agent claude --scope user --site "$WP_AGENT_SITE" --i-approve

Der Befehl ruft die installierte Claude-CLI ohne Authorization-Header auf. Ein vorhandener gleichnamiger User-Eintrag wird nicht überschrieben. Öffne danach in Claude Code /mcp und schließe die OAuth-Freigabe im Browser ab. Falls du stattdessen bewusst eine projektlokale Datei brauchst, erzeugt wp-agent init --agent claude weiterhin .mcp.json mit einem eigenen Application Password.

Codex lässt sich ebenfalls ohne statisches WordPress-Passwort benutzerweit registrieren:

wp-agent init --agent codex --scope user --site "$WP_AGENT_SITE" --i-approve

Der Befehl prüft einen vorhandenen gleichnamigen Eintrag vorab und überschreibt keine abweichende oder geheimnisgebundene Konfiguration. Nach einem neuen Eintrag bestätigt er den gespeicherten Endpunkt durch Rücklesen. Starte anschließend den in der Ausgabe genannten Befehl codex mcp login <name>. WPAgently öffnet dabei nicht ungefragt einen Browser.

Für Claude Desktop erzeugst du die Verbindung nicht mit wp-agent init. Öffne stattdessen im WordPress-Backend WPAgently > Agent verbinden, wähle Claude Desktop und lade die site-spezifische .mcpb-Datei herunter. Öffne diese Datei lokal mit Claude Desktop und bestätige die Erweiterung. Die .mcpb enthält ein eigenes widerrufbares WordPress Application Password. Behandle sie daher wie die anderen Verbindungsdateien als Geheimnis. Ein direkter Remote-Eintrag aus .mcp.json funktioniert in Claude Desktop nicht.

Für Codex öffnest du codex-mcp-wp-agent.toml und fügst den Inhalt in ~/.codex/config.toml oder in .codex/config.toml eines vertrauenswürdigen Projekts ein. Codex verbindet sich direkt per Streamable HTTP mit WordPress. Der Block setzt default_tools_approval_mode = "writes", sodass Codex bei schreibenden Werkzeugen nachfragt. Ein lokaler Übersetzungsprozess und eine zusätzliche npm-Abhängigkeit sind nicht nötig. Auch hier ist wp-agent init --agent codex nur eine alternative Dateierzeugung mit eigenem Application Password.

Die CLI erzeugt dieselben formatspezifischen Verbindungsdateien außerdem für Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity. Verwende dafür wp-agent init --agent cursor, windsurf, vscode, gemini-cli, opencode, cline, roo-code, kilo-code, zed, github-copilot, amazon-q oder antigravity. wp-agent init --agent alle schreibt alle vierzehn unterstützten MCP-Varianten in den gewählten Ausgabeordner. mcpServers aus der GitHub-Copilot-Datei wird mit ~/.copilot/mcp-config.json, .mcp.json oder .github/mcp.json zusammengeführt. Für Amazon Q verwendest du ~/.aws/amazonq/default.json oder .amazonq/default.json. Für Antigravity verwendest du je nach installierter Version ~/.gemini/config/mcp_config.json oder ~/.gemini/antigravity/mcp_config.json. Der Menüpunkt MCP-Server verwalten > Rohkonfiguration ansehen öffnet den tatsächlich verwendeten Pfad. Die Cline-Datei gehört in ~/.cline/mcp.json oder die MCP-Einstellungsdatei der Erweiterung, die Roo-Datei in die globale mcp_settings.json oder .roo/mcp.json, die Kilo-Datei in ~/.config/kilo/kilo.json oder .kilo/kilo.json und context_servers aus der Zed-Datei in die Zed-Einstellungen. Die Dateien enthalten das Application Password und erhalten deshalb den privaten Dateimodus 0600. Führe den jeweiligen Eintrag mit der bestehenden Client-Konfiguration zusammen, statt fremde Servereinträge zu überschreiben.

Für ChatGPT arbeitest du im Web und öffnest dort den Bereich Apps. Je nach Tarif liegt er in den persönlichen Einstellungen oder in den Arbeitsbereichseinstellungen. In Business kann nur ein Admin oder Owner den Entwicklermodus freischalten und eine benutzerdefinierte App bereitstellen. In Enterprise und Edu braucht der anlegende Nutzer die vom Administrator vergebene Berechtigung. Trage die MCP-URL aus WPAgently > Agent verbinden ein, wähle OAuth als Anmeldung, lasse die Werkzeuge prüfen und schließe die WordPress-Freigabe im Browser ab. ChatGPT verbindet sich direkt mit deiner WordPress-Seite. Lokale MCP-Server werden dabei nicht unterstützt. Vollständige Schreibwerkzeuge benötigen nach aktuellem ChatGPT-Stand einen Business-, Enterprise- oder Edu-Arbeitsbereich. ChatGPT Pro kann benutzerdefinierte MCP-Verbindungen derzeit nur für lesende Abrufe verwenden.

Bestätige danach im jeweiligen Assistenten, dass tools/list die wp-agent-*-Tools zeigt (tools/list ist die Liste der Werkzeuge, die der Assistent von deiner Seite kennt). Serverseitig hat wp-agent doctor in Schritt 5 das schon geprüft, hier stellst du nur sicher, dass auch der Assistent selbst sauber verbindet. Danach lädt wp-site-context gezielt Website-Kontext, Designprofil, passende Site-Skills und relevante Memories. Ist eine Designrichtung aktiv, lädt der Skill zusätzlich ihre Tonalität, Regeln, zu vermeidenden Muster und ihr validiertes Profil. Inaktive Richtungen bleiben unberücksichtigt. Die ausführenden Skills wp-article, wp-landing, wp-reference und wp-content führen anschließend durch die geprüften Abläufe. wp-feedback erstellt bei einem Fehler einen reproduzierbaren, datensparsamen Bericht zur Nutzerprüfung und sendet niemals automatisch Daten.

Die Skills selbst kommen aus dem mitgelieferten Skills-Bundle wp-agent-skills-<version>.zip. Ersetze <version> durch die Versionsnummer aus deinem Download. Das ZIP enthält einen dependency-freien Installer. Der erste Lauf zeigt nur den Plan. Der zweite wendet nach deiner Bestätigung den gesamten Skill-Satz als eine Transaktion für Claude und Codex an. Schlägt ein Skill fehl, werden bereits installierte oder ersetzte Skills dieses Laufs zurückgerollt:

unzip wp-agent-skills-<version>.zip -d wp-agent-skills-bundle
node wp-agent-skills-bundle/skills/install.mjs --agent both
node wp-agent-skills-bundle/skills/install.mjs --agent both --i-approve

Identische vorhandene Skills werden übersprungen. Abweichende lokale Fassungen bleiben unangetastet, bis du sie bewusst mit --replace ersetzen lässt. Der Power-Skill wird niemals stillschweigend installiert. Verwende dafür zusätzlich --include-power. Wenn du lieber manuell kopierst, entsprechen die sechs deutschen Standard-Skills diesen Pfaden:

mkdir -p ~/.claude/skills
cp -R wp-agent-skills-bundle/skills/wp-article ~/.claude/skills/
cp -R wp-agent-skills-bundle/skills/wp-landing ~/.claude/skills/
cp -R wp-agent-skills-bundle/skills/wp-reference ~/.claude/skills/
cp -R wp-agent-skills-bundle/skills/wp-content ~/.claude/skills/
cp -R wp-agent-skills-bundle/skills/wp-site-context ~/.claude/skills/
cp -R wp-agent-skills-bundle/skills/wp-feedback ~/.claude/skills/

Die Zielpfade müssen ~/.claude/skills/wp-article, ~/.claude/skills/wp-landing, ~/.claude/skills/wp-reference, ~/.claude/skills/wp-content, ~/.claude/skills/wp-site-context und ~/.claude/skills/wp-feedback sein. Der Installer verwendet für Codex entsprechend ~/.codex/skills. Die mitgelieferten Dateien docs/AGENTS.wp-agent.md und docs/agents/codex-content.md bleiben als Alternative für Clients ohne Skill-Unterstützung verfügbar. Ohne dieses Bundle kennt der Assistent diese Abläufe nicht, auch wenn die MCP-Verbindung selbst bereits steht.

Wenn du die englischen Skill-Varianten zusätzlich installieren willst, verwende --locale en. Der Installer legt sie konfliktfrei in Zielordnern mit -en-Endung ab. Manuell entsprechen sie diesen Pfaden:

mkdir -p ~/.claude/skills/wp-article-en ~/.claude/skills/wp-landing-en ~/.claude/skills/wp-reference-en ~/.claude/skills/wp-content-en ~/.claude/skills/wp-site-context-en ~/.claude/skills/wp-feedback-en
cp -R wp-agent-skills-bundle/skills/en/wp-article/. ~/.claude/skills/wp-article-en/
cp -R wp-agent-skills-bundle/skills/en/wp-landing/. ~/.claude/skills/wp-landing-en/
cp -R wp-agent-skills-bundle/skills/en/wp-reference/. ~/.claude/skills/wp-reference-en/
cp -R wp-agent-skills-bundle/skills/en/wp-content/. ~/.claude/skills/wp-content-en/
cp -R wp-agent-skills-bundle/skills/en/wp-site-context/. ~/.claude/skills/wp-site-context-en/
cp -R wp-agent-skills-bundle/skills/en/wp-feedback/. ~/.claude/skills/wp-feedback-en/

Geschafft, wenn: dein Assistent die wp-agent-*-Tools in tools/list zeigt und die kopierten Skills kennt. Ab jetzt kannst du ihn bitten, einen echten Artikel oder eine Landing-Page zu bauen. Die gehärteten Schreibpfade prüfen ihre geänderten Werte im Hintergrund nach.

Diagnose

Die sieben Checks von wp-agent doctor (siehe Schritt 5) im Detail. Der Befehl läuft sie der Reihe nach durch und meldet je Check OK oder FEHLER mit einem Klartext-Hinweis. Falls einer rot ist, findest du hier die Ursache:

1. Erreichbarkeit: Ist die Seite unter WP_AGENT_SITE erreichbar, und antwortet die technische Schnittstelle unter /wp-json mit den erwarteten Daten (JSON)? Häufigster Anfängerfehler: Bei „Einfach“-Permalinks liefert /wp-json/ die Startseite als HTML statt der erwarteten Daten. Dieser Check erkennt das und gibt dir einen Permalink-Hinweis, statt fälschlich grün zu sein. Abhilfe: Pretty-Permalinks aktivieren (Einstellungen > Permalinks).
2. Auth: Meldet der gespeicherte OAuth-Zugang den ausgewählten Redakteur korrekt an? Die CLI erneuert ein bald ablaufendes Token automatisch. Ein Fehler bedeutet meist, dass der Zugang serverseitig widerrufen wurde. Führe dann wp-agent logout --site "$WP_AGENT_SITE" --force und anschließend wp-agent login --site "$WP_AGENT_SITE" aus. Beim Passwort-Fallback prüfst du stattdessen Benutzername und Application Password.
3. Bot-Rolle: Trägt der Bot die Rolle Editor und nicht Administrator? Das ist dieselbe Prüfung wie wp-agent preflight; Admin-Rechte sind ein harter Stopp und Absicht.
4. Lizenz: Ist die lokale Lizenzbestätigung gültig und innerhalb der erlaubten Offline-Frist?
5. Steuerung: Sind der zentrale Schalter, der Domain Lock und das Ability-Profil gültig, und melden die serverseitigen Diagnosen keinen Fehler?
6. Abilities: Sind alle laut Kontrollzentrum aktivierten Abilities angemeldet? Fehlen welche, prüfe das Profil und den Companion-Schalter unter WPAgently > Übersicht.
7. MCP: Antwortet der Server unter <site>/wp-json/wp-agent/mcp sauber, und enthält tools/list die Werkzeuge für alle laut Kontrollzentrum aktivierten Abilities? Fehlt der Server trotz aktivem Plugin, ist das Plugin unvollständig ausgeliefert und muss neu gebaut werden.

Für eine gezielte Einzelprüfung wiederholen wp-agent preflight (Check 3) und wp-agent abilities (Check 6) denselben Aspekt isoliert. wp-agent login richtet den CLI-Zugang ein, gehört aber nicht zu den sieben Doctor-Checks. wp-agent init testet ebenfalls nichts. Der Befehl schreibt nur optionale statische Verbindungsdateien (siehe Schritt 4).

Die Gesamtarchitektur der installierbaren Bausteine beschreibt die Architektur-Dokumentation.

Troubleshooting: die fünf stillen Fehler

Es gibt fünf Stellen, an denen naive KI-Setups regelmäßig still scheitern. WPAgently fängt sie ab und macht den Fehler sichtbar, bevor ein unbemerkter Schaden entsteht:

1. Der Artikel steht plötzlich unformatiert da (der Classic-Editor-Fallback, core/freeform)
2. Die SEO-Änderung wird sichtbar mit HTTP 409 und manual_only gestoppt, bevor ein Providerfeld verändert wird
3. Google erfährt nichts vom neuen Beitrag (Sitemap oder Cache aktualisiert nicht)
4. Bilder öffnen ein Sicherheitsloch, oder Alt-Text und Beitragsbild fehlen
5. Derselbe Artikel landet bei einem zweiten Lauf doppelt auf deiner Seite

Symptom, Ursache und Abhilfe zu jedem dieser fünf Fehler (inklusive der genauen Meldungen, mit denen WPAgently abbricht) stehen ausführlich in der Fehlerbehebung, Teil 1. Dort findest du auch besondere Fälle einzelner Funktionen (WooCommerce, ACF, Contact Form 7, Fluent Forms, Gravity Forms, WPForms, Ninja Forms, Page-Builder-Erkennung, Teil 2) und die nur lesenden Werkzeuge, mit denen du selbst nachsehen kannst, was auf einem Beitrag gespeichert ist (Teil 3).

Optional: Power-/Developer-Modus

Diese Anleitung richtet ausschließlich den geprüften Kern (wp-agent-companion) ein, und das ist für Blogartikel und Landing-Pages auch der einzig nötige Weg. Für direkten Zugriff auf Dateien, Datenbank und PHP-Ausführung gibt es ein zweites, komplett separates und standardmäßig abgeschaltetes Plugin wp-agent-power. Das ist eine bewusste, eigene Entscheidung und nicht Teil des Standard-Setups. Wenn dir die Begriffe nichts sagen, brauchst du diesen Modus mit hoher Wahrscheinlichkeit nicht.

Wer den Power-Modus einsetzen will, installiert das eigene Paket dist/wp-agent-power-<version>.zip zusätzlich. Master und benötigte Stufen werden unter Werkzeuge > WPAgently Power aktiviert. Danach prüft wp-agent power init den Serverzustand und legt nach der bewussten Bestätigung die lokale Sitzung an. Die vollständigen Gates, Remote-Backups und Remote-Restores sowie die Grenzen stehen in der Power-Dokumentation, Abschnitt 16.

Der Skill wp-power liegt ebenfalls im Skills-Bundle, wird aber bewusst nie standardmäßig installiert. Führe den Installer nur dann erneut mit --include-power --i-approve aus, wenn du diesen Modus wirklich einsetzen willst. Für die englische Variante ergänzt du außerdem --locale en.