Konfiguration

Nicht interaktive Hilfsbefehle für openclaw.json: einen Wert anhand des Pfads abrufen/festlegen/patchen/entfernen, das Schema ausgeben, validieren oder den aktiven Dateipfad ausgeben. Führen Sie openclaw config ohne Unterbefehl aus, um denselben geführten Assistenten wie mit openclaw configure zu öffnen.

Stammoptionen

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Wiederholbarer Abschnittsfilter für die geführte Einrichtung, wenn Sie openclaw config ohne Unterbefehl ausführen.

Geführte Abschnitte: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Beispiele

openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"openclaw config set agents.defaults.heartbeat.every "2h"openclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

Pfade

Punkt- oder Klammernotation. Setzen Sie Klammerpfade in Shell-Beispielen in Anführungszeichen, damit zsh [0] nicht durch Glob-Expansion erweitert:

openclaw config get agents.defaults.workspaceopenclaw config get agents.entries.mainopenclaw config get agents.entriesopenclaw config set 'agents.entries.work.tools.exec.node' "node-id-or-name"

config get

Liest einen Wert aus dem geschwärzten Konfigurations-Snapshot (Geheimnisse werden niemals ausgegeben). --json gibt den Rohwert als JSON aus; andernfalls werden Zeichenfolgen/Zahlen/boolesche Werte ohne Formatierung und Objekte/Arrays als formatiertes JSON ausgegeben.

Wenn der Pfad fehlt, schreibt --json { "error": "Config path not found: <path>" } nach stdout und wird mit Status 1 beendet. Ohne --json verbleibt die Diagnose auf stderr.

openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

config file

Gibt den aktiven Konfigurationsdateipfad aus, der aus OPENCLAW_CONFIG_PATH oder dem Standardspeicherort aufgelöst wird. Der Pfad bezeichnet eine reguläre Datei und keinen symbolischen Link; siehe Schreibsicherheit.

config schema

Gibt das generierte JSON-Schema für openclaw.json nach stdout aus.

openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

Validiert die aktuelle Konfiguration anhand des aktiven Schemas, ohne das Gateway zu starten.

openclaw config validateopenclaw config validate --json

Werte

Werte werden nach Möglichkeit als JSON5 geparst; andernfalls werden sie als unformatierte Zeichenfolgen behandelt. Verwenden Sie --strict-json, um Standard-JSON ohne Rückfall auf Zeichenfolgen zu verlangen (reine JSON5-Syntax wie Kommentare, nachgestellte Kommas oder Schlüssel ohne Anführungszeichen wird dann abgelehnt). --json ist ein veralteter Alias für --strict-json bei config set.

openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json gibt den Rohwert als JSON statt als terminalformatierten Text aus.

Wenn ein Schreibvorgang agents.defaults.model oder ein agentenspezifisches agents.entries.*.model ändert, löst OpenClaw vor dem Schreiben jede geänderte primäre oder Fallback-Referenz über die konfigurierten Provider-Kataloge auf. Unbekannte Modellreferenzen werden abgelehnt, ohne die aktive Konfiguration zu ändern; führen Sie openclaw models list aus, um die verfügbaren Modelle anzuzeigen.

Verwenden Sie --merge, wenn Sie diesen Zuordnungen Einträge hinzufügen:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Verwenden Sie --replace nur, wenn der angegebene Wert absichtlich zum vollständigen Zielwert werden soll.

config set-Modi

openclaw config set <path> <value>

openclaw config set channels.discord.token \  --ref-provider default \  --ref-source env \  --ref-id DISCORD_BOT_TOKEN

openclaw config set secrets.providers.vault \  --provider-source exec \  --provider-command /usr/local/bin/openclaw-vault \  --provider-arg read \  --provider-arg openai/api-key \  --provider-timeout-ms 5000

openclaw config set --batch-json '[  {    "path": "secrets.providers.default",    "provider": { "source": "env" }  },  {    "path": "channels.discord.token",    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }  }]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

Beim Parsen von Stapeln dient stets die Stapelnutzlast (--batch-json/--batch-file) als maßgebliche Quelle; --strict-json / --json ändern das Parseverhalten für Stapel nicht.

Der JSON-Pfad-/Wertmodus funktioniert auch direkt für SecretRefs und Provider:

openclaw config set channels.discord.token \  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \  --strict-json openclaw config set secrets.providers.vaultfile \  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \  --strict-json

Flags für die Provider-Erstellung

Ziele der Provider-Erstellung müssen secrets.providers.<alias> als Pfad verwenden.

Beispiel für einen gehärteten Exec-Provider:

openclaw config set secrets.providers.vault \  --provider-source exec \  --provider-command /usr/local/bin/openclaw-vault \  --provider-arg read \  --provider-arg openai/api-key \  --provider-json-only \  --provider-pass-env VAULT_TOKEN \  --provider-trusted-dir /usr/local/bin \  --provider-timeout-ms 5000

config patch

Fügen Sie einen konfigurationsförmigen JSON5-Patch ein oder leiten Sie ihn weiter, anstatt viele pfadbasierte config set-Befehle auszuführen. Objekte werden rekursiv zusammengeführt; Arrays und skalare Werte ersetzen das Ziel; null löscht den Zielpfad.

openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

Patchdateien sind auf 8 MiB begrenzt. Über eine Pipe übergebene --stdin-Patches sind auf 1 MiB begrenzt.

Leiten Sie für Remote-Einrichtungsskripte einen Patch über stdin weiter:

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Beispiel-Patch:

{  channels: {    slack: {      enabled: true,      mode: "socket",      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },      groupPolicy: "open",      requireMention: false,    },    discord: {      enabled: true,      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },      dmPolicy: "disabled",      dm: { enabled: false },      groupPolicy: "allowlist",    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },      models: {        "openai/gpt-5.6-sol": { params: { fastMode: true } },      },    },  },}

Verwenden Sie --replace-path <path>, wenn ein Objekt oder Array exakt zum angegebenen Wert werden muss, anstatt rekursiv gepatcht zu werden:

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run führt Schema- und Auflösbarkeitsprüfungen für SecretRefs durch, ohne zu schreiben. Auf Ausführungsbefehlen basierende SecretRefs werden bei einem Probelauf standardmäßig übersprungen; fügen Sie --allow-exec hinzu, wenn der Probelauf bewusst Provider-Befehle ausführen soll.

Probelauf

--dry-run validiert Änderungen, ohne openclaw.json zu schreiben. Verfügbar für config set, config patch und config unset.

openclaw config set channels.discord.token \  --ref-provider default \  --ref-source env \  --ref-id DISCORD_BOT_TOKEN \  --dry-run \  --json openclaw config set channels.discord.token \  --ref-provider vault \  --ref-source exec \  --ref-id discord/token \  --dry-run \  --allow-exec

Struktur der JSON-Ausgabe

{  ok: boolean,  operations: number,  configPath: string,  inputModes: ["value" | "json" | "builder" | "unset", ...],  checks: {    schema: boolean,    resolvability: boolean,    resolvabilityComplete: boolean,  },  refsChecked: number,  skippedExecRefs: number,  errors?: [    {      kind: "missing-path" | "schema" | "resolvability" | "model",      message: string,      ref?: string, // bei Auflösbarkeitsfehlern vorhanden    },  ],}

{  "ok": true,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0}

{  "ok": false,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0,  "errors": [    {      "kind": "resolvability",      "message": "Fehler: Die Umgebungsvariable \"MISSING_TEST_SECRET\" ist nicht gesetzt.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}

Änderungen anwenden

Nach jedem erfolgreichen config set / config patch / config unset gibt die CLI einen von drei Hinweisen aus, damit Sie wissen, ob der Gateway neu gestartet werden muss:

Schreibvorgänge für plugins.entries (oder einen beliebigen Unterpfad) erfordern immer einen Neustart, da die CLI nicht nachweisen kann, dass die Metadaten zum Neuladen jedes Plugins geladen sind.

Schreibsicherheit

openclaw config set und andere OpenClaw-eigene Konfigurationsschreiber validieren die vollständige Konfiguration nach der Änderung, bevor sie auf dem Datenträger gespeichert wird. Wenn die neue Nutzlast die Schemavalidierung nicht besteht oder wie ein destruktives Überschreiben wirkt, bleibt die aktive Konfiguration unverändert und die abgelehnte Nutzlast wird daneben als openclaw.json.rejected.* gespeichert.

OpenClaw-eigene Schreibvorgänge serialisieren JSON5 erneut als Standard-JSON. Wenn die Quelle Kommentare enthält, warnt der Schreiber unmittelbar vor deren Entfernung; verwenden Sie einen direkten Editor, wenn Kommentare erhalten bleiben müssen.

Bevorzugen Sie für kleine Änderungen Schreibvorgänge über die CLI:

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

Wenn ein Schreibvorgang abgelehnt wird, prüfen Sie die gespeicherte Nutzlast und korrigieren Sie die vollständige Konfigurationsstruktur:

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw config validate

Direkte Schreibvorgänge mit einem Editor sind weiterhin zulässig, der laufende Gateway behandelt sie jedoch als nicht vertrauenswürdig, bis sie validiert wurden. Ungültige direkte Änderungen verhindern den Start oder werden beim Hot Reload übersprungen; der Gateway schreibt openclaw.json nicht neu. Führen Sie openclaw doctor --fix aus, um Konfigurationen mit vorangestellten oder überschriebenen Inhalten zu reparieren oder die letzte bekanntermaßen funktionierende Kopie wiederherzustellen. Siehe Gateway-Fehlerbehebung.

Die Wiederherstellung der gesamten Datei ist der Reparatur durch Doctor vorbehalten. Änderungen am Plugin-Schema oder Abweichungen bei minHostVersion bleiben deutlich sichtbar, statt nicht zusammenhängende Benutzereinstellungen wie Modelle, Provider, Authentifizierungsprofile, Kanäle, Gateway-Erreichbarkeit, Tools, Speicher, Browser oder Cron-Konfiguration zurückzusetzen.

Reparaturschleife

Nachdem openclaw config validate erfolgreich war, können Sie über die lokale TUI einen eingebetteten Agenten die aktive Konfiguration mit der Dokumentation vergleichen lassen, während Sie jede Änderung im selben Terminal validieren:

openclaw chat

Innerhalb der TUI führt ein vorangestelltes ! einen wörtlichen lokalen Shell-Befehl aus (nach einer einmaligen Bestätigungsaufforderung pro Sitzung):

!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

Verwandte Themen

• CLI-Referenz
• Konfiguration