Exec in OpenClaw: Shell-Befehle kontrolliert ausführen und Prozesse steuern

Wenn dein Agent in OpenClaw Shell-Befehle ausführt, läuft das über das exec-Tool. Kaum ein anderes Werkzeug in OpenClaw greift so direkt ins System ein wie exec. Deshalb solltest du wissen, wo ein Befehl läuft, wie lange er läuft und wie du ihn wieder stoppst. Diese Anleitung geht die wichtigsten Stellschrauben Schritt für Schritt durch. Grundlage ist die offizielle Exec-Dokumentation von OpenClaw, die auch als Quelltext im GitHub-Repository des Projekts liegt.

Was exec ist und warum es nicht „nur lesend“ ist

Laut OpenClaw-Dokumentation führt exec Shell-Befehle im Workspace aus und ist ausdrücklich eine verändernde Oberfläche. Befehle können Dateien überall dort anlegen, ändern oder löschen, wo das Dateisystem des gewählten Hosts oder der Sandbox es zulässt.

Ein Punkt wird leicht übersehen: Wenn du die Dateitools write, edit oder apply_patch deaktivierst, wird exec dadurch nicht read-only. Ein Agent, der nur lesen soll, braucht also auch für exec eine klare Regel.

Einordnung für KI-Agenten: Ein Agent mit Shell-Zugriff kann grundsätzlich alles, was seine Umgebung erlaubt. Eine Liste deaktivierter Tools grenzt ihn deshalb kaum ein. Wirksam sind der Ausführungsort, die Dateirechte dieser Umgebung, der Freigabemodus und die Tool-Policy, und zwar im Zusammenspiel. Wie sich diese Vertrauensgrenze im Team-Betrieb verhält, beschreibt unser Beitrag OpenClaw-Teamserver: Ein Gateway ist eine gemeinsame Vertrauensgrenze.

Schritt 1: Den Ausführungsort mit host festlegen

Der Parameter host bestimmt, wo ein Befehl läuft. Die Dokumentation erlaubt genau vier Werte:

auto
sandbox
gateway
node

host ist kein Hostname-Selektor. Werte, die wie ein Hostname aussehen, werden abgelehnt, bevor der Befehl startet.

Standardmäßig steht tools.exec.host laut Dokumentation auf auto, und dessen Verhalten hängt an einer einzigen Frage: Ist eine Sandbox-Runtime aktiv? Wenn nicht, wird auto zu gateway aufgelöst, also zur Ausführung direkt auf dem Rechner, auf dem OpenClaw läuft. Wenn ja, hält auto nach Angaben der Exec-Dokumentation auf GitHub exec in der Sandbox und lehnt Overrides pro Aufruf auf gateway oder node ab. Verlangt eine Sitzung eine Sandbox, bleibt sie laut Dokumentation unabhängig vom konfigurierten Host in der Sandbox.

Willst du auf einem Node ausführen, also auf einem gekoppelten Gerät, setzt du das laut Dokumentation explizit in der Konfiguration:

tools.exec.host=node

Nach Angaben der Exec-Dokumentation auf GitHub muss der Node gekoppelt und verbunden sein und system.run unterstützen. Ist nur ein passender Node verbunden, wählt exec ihn automatisch. Bei mehreren legst du das Ziel über einen dieser Wege fest:

exec.node
tools.exec.node
/exec node=...

Das aktive Canvas-Ziel zieht OpenClaw dabei nie heran.

Schritt 2: Lang laufende Befehle mit yieldMs und process steuern

Manche Befehle brauchen länger. Laut Exec-Dokumentation gibt exec mit yieldMs nach der angegebenen Verzögerung in Millisekunden einen laufenden Prozess-Handle zurück. Abgeschlossene Aufrufe liefern ihre Ausgabe dagegen direkt.

Das process-Tool brauchst du nach Angaben der Dokumentation nur, wenn exec meldet, dass ein Befehl noch läuft, und dabei eine sessionId liefert. Gibt der Befehl selbst eine ID aus, ist das gewöhnliche Ausgabe. Hintergrund-Sessions gelten pro Agent: process sieht nur Sessions desselben Agenten.

Auf dem Gateway und in seiner Sandbox gehört ein per yieldMs abgegebener Befehl weiterhin zur Anfrage. Der Stop-Button im Browser und ein getipptes

/stop

brechen ihn ab. Beendet das Modell seine Antwort dagegen ganz normal, läuft der Befehl weiter.

Achtung bei Nodes: Remote-Aufrufe mit host=node nutzen synchrones system.run. Dort werden background und yieldMs ignoriert, und es gibt keine sessionId. Für Hintergrundarbeit auf einem gekoppelten Gerät verweist OpenClaw auf eine Worker-Session mit worker-lokalem exec und process. Ist process ganz deaktiviert, läuft auch lokales exec synchron.

Schritt 3: Dienste bewusst mit background starten und wieder beenden

yieldMs ist für normale Arbeit gedacht. background startet dagegen sofort einen bewusst unabhängigen Dienst, und der folgt anderen Regeln: Ein Stop der Anfrage lässt ihn weiterlaufen. Beenden musst du ihn separat über seinen Prozess-Handle.

Für einen dauerhaft laufenden Dienst auf dem Gateway oder in der Sandbox nennt die Dokumentation diese Kombination:

background: true
timeoutSeconds: 0

Brauchst du ihn nicht mehr, beendest du ihn mit der process-Aktion kill.

Hypothetisches Beispiel: Dein Agent startet zum Testen einen lokalen Entwicklungsserver. Mit der Kombination oben läuft er weiter, auch wenn du die Anfrage stoppst. Aufräumen musst du selbst.

Eine Grenze bleibt: Auch ohne Timeout überlebt der Prozess nicht, wenn sein Host oder Worker herunterfährt.

Schritt 4: Timeouts richtig einsetzen

Zwei Timeouts werden leicht verwechselt. Der Grund sind die Einheiten.

timeoutSeconds begrenzt die gesamte Lebensdauer eines Befehls in Sekunden und überschreibt für diesen Aufruf den konfigurierten Exec-Timeout, der laut Dokumentation standardmäßig bei 1800 Sekunden liegt. Läuft er ab, wird der Prozess beendet, auch wenn background oder yieldMs schon eine Session-ID zurückgegeben haben. Der timeout des process-Tools regelt dagegen nur, wie lange eine einzelne Abfrage wartet, und zwar in Millisekunden. timeoutSeconds: 0 schaltet den Prozess-Timeout für den jeweiligen Aufruf ab, und das auf Gateway, in der Sandbox und auf Nodes gleichermaßen.

Wird ein Prozess per Signal beendet, nennt ein headless Node-Host den Signalnamen im Ergebnis. Ausgabe vor dem Abbruch heißt ausdrücklich nicht, dass der Befehl erfolgreich war.

Einordnung für KI-Agenten: Ein Abbruch durch Timeout verrät nicht, wie weit ein Befehl gekommen ist. Ein blindes Wiederholen kann eine Aktion deshalb doppelt auslösen. Mehr dazu steht in unserem Artikel über Agenten-Retries und Idempotenz.

Schritt 5: Shell, Umgebung und Arbeitsverzeichnis verstehen

Ob ein Befehl so läuft wie erwartet, hängt oft an wenigen Details. Die Exec-Dokumentation beschreibt vier davon:

1. Arbeitsverzeichnis: Relative Pfade werden bei lokaler Ausführung gegen das Standard-Arbeitsverzeichnis der Session aufgelöst. ~ wird nicht expandiert.
2. Umgebungsvariablen: Overrides werden auf die geerbte Umgebung gelegt. Bei Ausführung auf gateway oder node werden env.PATH sowie Loader-Overrides wie LD_* und DYLD_* abgelehnt, damit niemand fremde Programme oder eingeschleusten Code unterschiebt. Die einzige Pager-Ausnahme: GIT_PAGER oder PAGER exakt auf „cat“ oder leer wird auf einen leeren Wert normalisiert.
3. Shell-Wahl: Außerhalb von Windows nutzt exec die Variable SHELL, bei fish aber bevorzugt bash oder sh. Unter Windows sucht es zuerst PowerShell 7 (pwsh) und fällt auf Windows PowerShell 5.1 zurück.
4. Erkennung: OpenClaw setzt OPENCLAW_SHELL=exec. Deine Shell-Profile können so erkennen, dass sie im Exec-Kontext laufen.

Für bash und zsh auf Gateway-Hosts außerhalb von Windows legt OpenClaw zusätzlich einen Startup-Snapshot an. Er übernimmt Aliase, Funktionen und eine kleine Auswahl an Umgebungsvariablen aus deinen Startdateien; nach Geheimnissen aussehende Variablen bleiben draußen. Sandbox und Node nutzen ihn nicht. Abschalten lässt er sich in der Umgebung des Gateway-Prozesses:

OPENCLAW_EXEC_SHELL_SNAPSHOT=0

Für TTY-only-CLIs, Coding-Agenten und Terminal-UIs kann exec außerdem in einem Pseudo-Terminal laufen, sofern verfügbar.

Freigaben und erhöhte Rechte: wo die Grenzen liegen

Ob OpenClaw vor einem Befehl nachfragt, ergibt sich laut Dokumentation aus tools.exec.mode und den Host-Freigaben. Die Modi reichen von deny über allowlist, ask und auto bis full. Im Modus ask laufen Befehle von der Allowlist direkt, alles andere landet bei einem Menschen. Ein einzelner Aufruf kann die Rückfrage-Einstellung nur verschärfen, nie lockern. Kommt er aus einem Channel und steht die effektive Host-Einstellung auf off, wird ein ask pro Aufruf ignoriert. Freigaben für gateway und node steuert die Approvals-Datei des Hosts.

elevated lässt einen Befehl aus der Sandbox auf den konfigurierten Host-Pfad ausbrechen, standardmäßig aufs Gateway, mit tools.exec.host=node auf den Node. Das geht nur, wenn der Betreiber es erlaubt und erhöhter Zugriff für die Session oder den Provider aktiviert ist. Elevated full überspringt Freigaben nur, wenn die effektiven Einstellungen ohnehin full und off erlauben.

Die Grenze

Mit exec verändert dein Agent tatsächlich etwas am System. Die Stellschrauben dafür sind überschaubar: host für den Ort, yieldMs und background für die Prozesskontrolle, timeoutSeconds für die Lebensdauer und der Freigabemodus für die Rechte.

Aus unserer Sicht schützen sie allein nicht vor Fehlbedienung. Daraus folgt eine einfache Mindestregel: Unbekannte Befehle laufen zuerst in einer Sandbox, mit einem knapp gesetzten timeoutSeconds und in einem Modus wie ask, in dem alles außerhalb der Allowlist eine menschliche Freigabe braucht. Erst wenn ein Befehl dort tut, was er soll, verdient er mehr Spielraum.