Konfiguration 🔧¶

OpenClaw liest eine optionale JSON5-Konfiguration aus ~/.openclaw/openclaw.json (Kommentare + nachgestellte Kommata erlaubt).

Fehlt die Datei, verwendet OpenClaw sichere Standardwerte (eingebetteter Pi‑Agent + Sitzungen pro Absender + Workspace ~/.openclaw/workspace). In der Regel benötigen Sie eine Konfiguration nur, um:

• Connect channels and control who can message the bot
• Set models, tools, sandboxing, or automation (cron, hooks)
• Tune sessions, media, networking, or UI

See the full reference for every available field.

„Alle Konfigurationsoptionen für ~/.openclaw/openclaw.json mit Beispielen“

Minimal config¶

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Editing config¶

bash openclaw onboard # full setup wizard openclaw configure # config wizard bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset tools.web.search.apiKey Das Gateway stellt eine JSON-Schema-Darstellung der Konfiguration über config.schema für UI-Editoren bereit. Die Control UI rendert aus diesem Schema ein Formular, mit einem Raw JSON-Editor als Notausgang. ~/.openclaw/openclaw.json (oder OPENCLAW_CONFIG_PATH) The Gateway watches the file and applies changes automatically (see hot reload).

Strikte Konfigurationsvalidierung¶

OpenClaw akzeptiert nur Konfigurationen, die vollständig dem Schema entsprechen. Unbekannte Schlüssel, fehlerhafte Typen oder ungültige Werte führen dazu, dass das Gateway aus Sicherheitsgründen nicht startet. The only root-level exception is $schema (string), so editors can attach JSON Schema metadata.

Wenn die Validierung fehlschlägt:

• Das Gateway startet nicht.
• Es sind nur Diagnosebefehle erlaubt (z. B.: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
• Führen Sie openclaw doctor aus, um die genauen Probleme zu sehen.
• Führen Sie openclaw doctor --fix (oder --yes) aus, um Migrationen/Reparaturen anzuwenden.

Common tasks¶

Each channel has its own config section under channels.<provider>. See the dedicated channel page for setup steps:

```
{
  Kanäle: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowVon: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"],
    },
    Signal: {
      groupPolicy: "allowlist",
      groupAllowVon: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowVrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@org. om"],
    },
    discord: {
      groupPolicy: "allowlist",
      Gilden: {
        GUILD_ID: {
          Kanäle: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      Kanäle: { "#general": { allow: true } },
    },
  },
}
```

Set the primary model and optional fallbacks:

```
Wenn `models.providers` vorhanden ist, schreibt OpenClaw eine `models.json` in
`~/.openclaw/agents/<agentId>/agent/` beim Start:
```

DM access is controlled per channel via dmPolicy:

```
Gruppen: `channels.mattermost.groupPolicy="allowlist"` standardmäßig (mention-gated). Benutze `channels.mattermost.groupAllowFrom` um Absender zu beschränken.
```

Gruppieren von Nachrichten standardmäßig Erwähnung benötigen (entweder Metadaten Erwähnung oder Regex Pattern). agents.defaults.subagents konfiguriert Subagent Standards:

```
{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist is DMs only; including your own number enables self-chat mode.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}
```

Sessions control conversation continuity and isolation:

````
```json5
{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`: `main` (shared) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- See [Session Management](/concepts/session) for scoping, identity links, and send policy.
- See [full reference](/gateway/configuration-reference#session) for all fields.
````

Run agent sessions in isolated Docker containers:

```
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Common agent defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Merge agent lists from all clients
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Merge broadcast configs
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}
```

json5 { agents: { defaults: { heartbeat: { every: "30m", target: "last", }, }, }, }

```
- `every`: duration string (`30m`, `2h`). Set `0m` to disable.
- `target`: `last` | `whatsapp` | `telegram` | `discord` | `none`
- See [Heartbeat](/gateway/heartbeat) for the full guide.
```

{ cron: { enabled: true, maxConcurrentRuns: 2, }, }

```
Siehe [Cron Jobs](/automation/cron-jobs) für die Funktionsübersicht und CLI Beispiele.
```

Aktivieren Sie einen einfachen HTTP-Webhook-Endpunkt auf dem Gateway HTTP-Server.

````
```json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
```

See [full reference](/gateway/configuration-reference#hooks) for all mapping options and Gmail integration.
````

Führen Sie mehrere isolierte Agenten (separater Arbeitsbereich, agentDir, Sitzungen) innerhalb eines Gateways aus.

```
// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}
```

Teilen Sie Ihre Konfiguration mithilfe der Direktive $include in mehrere Dateien auf. Dies ist nützlich für:

```
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Include a single file (replaces the key's value)
  agents: { $include: "./agents.json5" },

  // Include multiple files (deep-merged in order)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}
```

gateway.reload (Config hot reload)¶

The Gateway watches ~/.openclaw/openclaw.json and applies changes automatically — no manual restart needed for most settings.

Reload modes¶

Modus:	Behavior
hybrid (default)	Hot-applies safe changes instantly. Automatically restarts for critical ones.
hot	Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it.
Anwenden + Neustart (RPC)	restart: Starten Sie das Gateway bei jeder Konfigurationsänderung neu.
Regeln:	Disables file watching. Changes take effect on the next manual restart.

{
  Gateway: {
    reload: {
      Modus: "hybrid",
      debounceMs: 300,
    },
  },
}

What hot-applies vs what needs a restart¶

Most fields hot-apply without downtime. In hybrid mode, restart-required changes are handled automatically.

Category	Felder:	Restart needed?
`channels.	channels.*, web (WhatsApp) — all built-in and extension channels	No
Agent & models	model: Standardmodell, überschreibt agents.defaults.model für diesen Agent.	No
Automation	hooks, cron, agent.heartbeat	No
messages	messages.queue	No
Tools & media	tools, browser, skills, audio, talk	No
Schema- und UI-Hinweise	ui, logging, identity, bindings	No
Gateway server	gateway (port/bind/auth/control UI/tailscale)	Inline‑Substitution:
Infrastructure	discovery, canvasHost, plugins	Erwähnungstypen:

gateway.reload and gateway.remote are exceptions — changing them does not trigger a restart.

Partielle Updates (RPC)¶

Verwenden Sie config.apply, um die vollständige Konfiguration in einem Schritt zu validieren, zu schreiben und das Gateway neu zu starten.

```
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'
```

Verwenden Sie config.patch, um ein partielles Update in die bestehende Konfiguration zu mergen, ohne unverwandte Schlüssel zu überschreiben. Es gelten die Semantiken von JSON Merge Patch:

````
- Objects merge recursively
- `null` deletes a key
- Arrays replace

Params:

- `raw` (string) — JSON5 with just the keys to change
- `baseHash` (required) — config hash from `config.get`
- `sessionKey`, `note`, `restartDelayMs` — same as `config.apply`

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```
````

Variable¶

OpenClaw reads env vars from the parent process plus:

• .env aus dem aktuellen Arbeitsverzeichnis (falls vorhanden)
• eine globale Fallback‑Datei .env aus ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env)

Keine der .env‑Dateien überschreibt bestehende Umgebungsvariablen. Sie können Umgebungsvariablen auch inline in der Konfiguration angeben.

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Opt‑in‑Komfortfunktion: Wenn aktiviert und noch keiner der erwarteten Schlüssel gesetzt ist, führt OpenClaw Ihre Login‑Shell aus und importiert nur die fehlenden erwarteten Schlüssel (überschreibt nie).

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

OPENCLAW_LOAD_SHELL_ENV=1

Sie können Umgebungsvariablen direkt in jedem String‑Wert der Konfiguration mit der Syntax ${VAR_NAME} referenzieren.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

Standards:

• Es werden nur großgeschriebene Umgebungsvariablennamen gematcht: [A-Z_][A-Z0-9_]*
• Missing/empty vars throw an error at load time
• Mit $${VAR} escapen, um ein literales ${VAR} auszugeben
• Funktioniert mit $include (auch eingebundene Dateien erhalten Substitution)
• Inline substitution: "${BASE}/v1" → "https://api.example.com/v1"

Siehe /environment für vollständige Prioritäten und Quellen.

Full reference¶

Neu bei der Konfiguration? Sehen Sie sich den Leitfaden Configuration Examples mit vollständigen Beispielen und detaillierten Erläuterungen an!

---

Beispiel (Provider/modellspezifische Erlaubnisliste):