Workboard-CLI

openclaw workboard ist die Terminaloberfläche für das gebündelte Workboard-Plugin. Damit kann ein Operator Karten auflisten, eine Karte erstellen, eine einzelne Karte prüfen und das laufende Gateway anweisen, bereite Arbeit an Subagent-Worker-Läufe zu verteilen.

Aktivieren Sie das Plugin, bevor Sie den Befehl verwenden:

openclaw plugins enable workboardopenclaw gateway restart

Verwendung

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]openclaw workboard show <id> [--json]openclaw workboard move <id> --status <status> [--json]openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

Der Befehl liest und schreibt dieselbe Plugin-eigene SQLite-Datenbank, die vom Dashboard und den Workboard-Agent-Tools verwendet wird. Karten-IDs sind UUIDs; Befehle, die eine Karten-ID akzeptieren, akzeptieren auch ein eindeutiges ID-Präfix (die kompakte Textausgabe zeigt die ersten 8 Zeichen).

Gültige Werte für status: triage, backlog, todo, scheduled, ready, running, review, blocked, done. Gültige Werte für priority: low, normal, high, urgent.

list

openclaw workboard listopenclaw workboard list --board default --status readyopenclaw workboard list --json

Die Textausgabe ist kompakt:

7f4a2c10  ready     high    default agent-a  Veralteten Worker-Heartbeat beheben

Die Spalten enthalten ID-Präfix, Status, Priorität, Board-ID, optionale Agent-ID und Titel.

Die kompakte Textausgabe blendet archivierte Karten standardmäßig aus, damit die CLI mit /workboard list übereinstimmt. Übergeben Sie --include-archived, um sie anzuzeigen. Die JSON-Ausgabe enthält für bestehende Automatisierungen immer die vollständige Kartenliste einschließlich archivierter Karten.

create

openclaw workboard create "Veralteten Worker-Heartbeat beheben" --priority high --labels bug,workboardopenclaw workboard create "Workboard-Dokumentation verfassen" --status ready --agent docs-agent --board docs --notes "CLI, Slash-Befehl, Verteilung und SQLite-Zustand behandeln."

create schreibt direkt in den SQLite-Zustand von Workboard. Die Karte ist sofort im Workboard-Tab der Control UI und für Workboard-Tools sichtbar.

show

openclaw workboard show 7f4a2c10openclaw workboard show 7f4a2c10 --json

Die Textausgabe zeigt die kompakte Kartenzeile und die Notizen. Die JSON-Ausgabe gibt den vollständigen Kartendatensatz zurück, einschließlich Ausführungsmetadaten, Versuchen, Kommentaren, Links, Nachweisen, Artefakten, Worker-Protokollen, Protokollstatus, Diagnosen und Automatisierungsmetadaten.

Nachweisstatus in JSON sind vom Worker gemeldete Ergebnisse. passed erfasst die Selbsteinschätzung des Workers zum angehängten Befehl oder zur Prüfung; dies ist kein unabhängiges Verifizierungsergebnis.

move

openclaw workboard move 7f4a2c10 --status reviewopenclaw workboard move 7f4a2c10 --status done --json

move ändert den Status der Karte über denselben manuellen Operatorpfad wie beim Ziehen einer Karte im Dashboard. Es akzeptiert eine vollständige Karten-ID oder ein eindeutiges Präfix. Aktive Abhängigkeits- und Zeitplanblockierungen gelten weiterhin. Operatoren dürfen eine beanspruchte Karte ohne den Anspruchstoken ihres Agenten verschieben; Anspruchstoken bleiben auf Mutationen durch Agent-Tools beschränkt und werden in der JSON-Ausgabe unkenntlich gemacht.

dispatch

openclaw workboard dispatchopenclaw workboard dispatch --jsonopenclaw workboard dispatch --max-starts 10openclaw workboard dispatch --adminopenclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

dispatch ruft zuerst die RPC-Methode workboard.cards.dispatch des laufenden Gateways auf. Diese verwendet dieselbe Subagent-Laufzeit wie die Verteilungsaktion im Dashboard, sodass bereite Karten zu aufgabenverfolgten Worker-Läufen mit verknüpften Sitzungsschlüsseln werden. --max-starts verwendet die additive Methode workboard.cards.dispatchWithOptions, sodass ein älteres Gateway die Option ablehnt, bevor Worker gestartet werden; starten Sie das Gateway nach einem Upgrade neu, bevor Sie das Flag verwenden. Karten mit einem zugewiesenen Agenten verwenden Agent-bezogene Subagent-Sitzungsschlüssel; nicht zugewiesene Karten behalten einen nicht begrenzten Subagent-Schlüssel, sodass der konfigurierte Standard-Agent des Gateways erhalten bleibt.

Die Verteilungsschleife:

1. Stuft Kinder mit erfüllten Abhängigkeiten auf ready hoch.
2. Blockiert abgelaufene Ansprüche oder Worker-Läufe mit Zeitüberschreitung.
3. Erfasst Verteilungsmetadaten auf bereiten Karten.
4. Wählt eine kleine Gruppe nicht beanspruchter bereiter Karten aus.
5. Beansprucht jede ausgewählte Karte für den Verteiler oder den zugewiesenen Agenten.
6. Startet einen Subagent-Worker-Lauf mit begrenztem Kartenkontext und dem Anspruchstoken der Karte.
7. Speichert die Worker-Lauf-ID, den Sitzungsschlüssel, die Aufgabenverknüpfung, sofern sie vom Gateway-Aufgabenverzeichnis gemeldet wird, den Ausführungsstatus und das Worker-Protokoll auf der Karte.

Die Auswahl ist konservativ: Eine Verteilung startet standardmäßig höchstens drei Worker, überspringt archivierte oder bereits beanspruchte Karten und startet in einem Durchlauf nur eine Karte pro Besitzer oder Agent. Karten, deren Besitzer bereits aktive laufende oder zu prüfende Arbeit haben, werden für eine spätere Verteilung zurückgestellt. Übergeben Sie --max-starts <count> mit einer positiven Ganzzahl, um die Obergrenze pro Durchlauf zu ändern; die Regel „eine Karte pro Besitzer“ gilt weiterhin, sodass die tatsächliche Anzahl der Starts niedriger sein kann.

Wenn der Worker-Start fehlschlägt, nachdem eine Karte beansprucht wurde, blockiert Workboard diese Karte, hebt den Anspruch auf und erfasst den Fehler in den Ausführungs- und Worker-Protokollmetadaten der Karte. Dadurch bleiben fehlgeschlagene Starts sichtbar, statt die Karte unbemerkt in die Warteschlange zurückzustellen.

Wenn kein explizites Gateway-Ziel angegeben ist und das lokale Gateway nicht verfügbar ist oder die Workboard-Verteilungsmethode noch nicht bereitstellt, greift die CLI auf eine reine Datenverteilung anhand des lokalen Workboard-Zustands zurück. Die reine Datenverteilung kann weiterhin Abhängigkeiten hochstufen, veraltete Ansprüche bereinigen und Läufe mit Zeitüberschreitung blockieren, startet jedoch keine Worker. Authentifizierungs-, Berechtigungs- und Validierungsfehler sowie Fehler für ein explizites Ziel --url oder --token werden direkt gemeldet, statt den Rückgriff auszulösen.

Die Textausgabe meldet Worker-Starts:

Verteilung abgeschlossen: gestartet=2 Fehler=0

Die Rückgriffsausgabe ist eindeutig:

Gateway nicht verfügbar; nur Datenverteilung: hochgestuft=1 blockiert=0

Die JSON-Ausgabe enthält das Verteilungsergebnis. Eine Gateway-gestützte Verteilung kann started und startFailures enthalten; der Rückgriff auf reine Datenverteilung enthält gatewayUnavailable: true. Anspruchstoken werden in der Karten-JSON-Ausgabe unkenntlich gemacht.

Im Dashboard wird dasselbe Verteilungsergebnis als kurze Zusammenfassung angezeigt, sodass ein Operator sehen kann, wie viele Karten gestartet, hochgestuft, blockiert, erneut beansprucht oder als fehlgeschlagen markiert wurden, ohne die Kartendetails zu öffnen.

Parität mit Slash-Befehlen

Befehlsfähige Kanäle können den entsprechenden Slash-Befehl verwenden:

/workboard list/workboard show 7f4a2c10/workboard create Veralteten Worker-Heartbeat beheben/workboard move 7f4a2c10 --status review/workboard dispatch

Die Verteilung per Slash-Befehl verwendet ebenfalls die Subagent-Laufzeit des Gateways und folgt daher demselben Verhalten für Beanspruchung, Worker-Start und Fehler wie das Dashboard und der CLI-Gateway-Pfad.

/workboard list und /workboard show sind Lesebefehle für autorisierte Befehlsabsender. /workboard create, /workboard move und /workboard dispatch verändern den Board-Zustand und erfordern auf Chat-Oberflächen den Besitzerstatus oder einen Gateway-Client mit operator.write oder operator.admin.

Berechtigungen

Der CLI-Verteilungspfad fordert normalerweise die Gateway-Bereiche operator.write und operator.read an. An einen Arbeitsbereich gebundene Karten werden direkt in einem exakt konfigurierten Agent-Arbeitsbereich ausgeführt; eine Worktree-Anforderung wird auf dieses Verzeichnis beschränkt, statt dem Host zu erlauben, Repository-gesteuerten Code bereitzustellen. Der ausgewählte Worker muss über schreibbaren, nicht gemeinsam genutzten Docker-Sandbox-Zugriff auf genau diesen Arbeitsbereich, einen aktiven Container-Hash, der den angeforderten Einbindungen und Richtlinien entspricht, und keinerlei Möglichkeit zum Ausbruch auf den Host verfügen. Übergeben Sie --admin, um ausdrücklich operator.admin anzufordern, einen anderen Host-Checkout zuzulassen und die normale Einrichtung verwalteter Worktrees zu verwenden; die Verbindung schlägt fehl, wenn dieser Bereich für den Client nicht genehmigt ist. Ein schreibgeschützter Gateway-Token kann Workboard-Daten über Lesemethoden prüfen, aber keine Karten erstellen oder Worker verteilen. Arbeitsbereichsbeschränkungen ändern ansonsten nicht das manuelle Verschieben von Karten für Aufrufer mit Berechtigung zur Workboard-Mutation.

Lokale Befehle list, create, show und move arbeiten mit dem lokalen OpenClaw-Zustandsverzeichnis, das vom aktuellen Profil verwendet wird. Verwenden Sie --dev oder --profile <name> beim übergeordneten Befehl openclaw, wenn Sie ein anderes Zustandsstammverzeichnis benötigen.

Fehlerbehebung

Es werden keine Karten angezeigt

Vergewissern Sie sich, dass das Plugin für dasselbe Profil und Zustandsstammverzeichnis aktiviert ist:

openclaw plugins inspect workboard --runtime --json

Wenn das Dashboard Karten anzeigt, die CLI jedoch nicht, prüfen Sie, ob beide Befehle dieselbe Einstellung --dev oder --profile verwenden.

Die Verteilung meldet „nur Daten“

Starten Sie das Gateway oder starten Sie es neu:

openclaw gateway restartopenclaw gateway status --deep

Versuchen Sie anschließend openclaw workboard dispatch erneut. Der Rückgriff auf reine Datenverteilung ist für die lokale Zustandsbereinigung nützlich, Worker-Läufe benötigen jedoch ein aktives Gateway.

Die Verteilung startet nichts

Prüfen Sie, ob mindestens eine Karte mit dem Status ready ohne aktiven Anspruch vorhanden ist:

openclaw workboard list --status ready

Karten können auch übersprungen werden, wenn derselbe Besitzer bereits laufende oder zu prüfende Arbeit hat. Verschieben Sie abgeschlossene Arbeit nach done, geben Sie veraltete Ansprüche über die Workboard-Tools frei oder führen Sie die Verteilung erneut aus, nachdem der aktive Worker fertig ist.

Verwandte Themen

• Workboard-Plugin
• CLI-Referenz
• Slash-Befehle
• Control UI