Configuration — runtime basics

Top-level runtime keys: worktreeRoot, worktreeAcceleration, worktreeMaxCount, repositoryBranchPrefix, models.*, discovery.*, update.*, acp.*, and wizard.*.

For the full key index and the other top-level config domains, see Configuration reference.

worktreeRoot

Optional global root directory for managed worktree checkouts. Defaults to <openclaw-state-dir>/worktrees.

{  worktreeRoot: "/mnt/workspaces/openclaw-worktrees",}

Use an absolute Gateway-host path, ~ for the Gateway user's home directory, or ~/ followed by a folder inside it; relative paths are rejected. OpenClaw creates checkouts at <worktreeRoot>/<repo-fingerprint>/<name>. This setting applies to all agents and all managed-worktree owners, with no per-agent override. The shared state database and allocation limits remain under the existing state directory.

Changes affect new allocations only. Registered worktrees retain their original paths for reuse, cleanup, and snapshot restore; existing checkouts are not moved automatically. Keep their original storage available while those records are still needed.

repositoryBranchPrefix

Sets the prefix for new remote repository session branches, including forks. The default is openclaw; branches use <prefix>/<workspace GUID>. For example, repositoryBranchPrefix: "clawson" creates clawson/<workspace GUID>.

The prefix must be one ASCII component of 1–64 characters: start with a letter or digit, then use letters, digits, underscores, or hyphens. Changing it leaves existing saved branches unchanged. This root setting does not change local worktree branch names.

worktreeAcceleration

Optional global boolean for managed worktree filesystem acceleration. Defaults to true, which selects an available filesystem backend automatically and otherwise uses normal Git checkout.

{  worktreeAcceleration: false,}

Set false to use normal Git checkout and file copying for new worktrees. This option applies across agents and managed-worktree owners; existing checkouts are unchanged. Supported backends are Btrfs snapshots on Linux, APFS directory clones on macOS, and ReFS block clones on Windows. Repository setup and dependencies remain per-worktree.

worktreeMaxCount

Optional positive integer limiting live managed worktrees across all agents, repositories, and owners in the same OpenClaw state directory. Defaults to 4096. Removed checkouts with retained recovery snapshots do not count toward this limit.

{  worktreeMaxCount: 4096,}

The cap is enforced: cleanup purges merged or squashed branches first, then idle worktrees by last-used age, including manual checkouts and unsaved data. Snapshot capture is best effort during cap eviction; a failed snapshot does not prevent purge. Lowering the cap can therefore remove existing checkouts. Live runs remain protected; if no other checkout can be evicted, creation fails with the cap and live owners in the error. Raise worktreeMaxCount or let those runs finish before retrying.

Background maintenance and creation use the same eviction owner. Concurrent creates cannot each claim the final slot. Disk-space admission remains a separate guard even when the configured count leaves room.

Models

Provider definitions, model allowlists, and custom provider setup live in Configuration - tools and custom providers. The models root also owns global model-catalog behavior.

{  models: {    // Optional. Hosted catalog updates default on.    catalogRefresh: {      enabled: true,      // url: "https://catalog.example.com/openclaw/catalog.json",    },  },}

• models.mode: provider catalog behavior (merge or replace).
• models.providers: custom provider map keyed by provider id.
• models.providers.*.localService: optional on-demand process manager for local model servers. OpenClaw checks the configured health endpoint, starts the absolute command when needed, waits for readiness, then sends the model request. See Local model services.
• models.catalogRefresh.enabled: controls the hosted model catalog refresh (default: true). Set it to false to prevent all remote catalog requests; model metadata and pricing then stay at the values shipped in the installed release or declared under models.providers.*.models[].cost.
• models.catalogRefresh.url: optional HTTPS mirror override (plain HTTP is accepted only for explicit localhost testing). The default is https://catalog.openclaw.ai/models/v2/catalog.json. Mirrors can serve v1 or v2. The Gateway checks in the background at startup and every six hours. A compatible download is prepared and published as one model-and-pricing generation without a Gateway restart. Readers retain the current generation until preparation succeeds; a release whose bundled catalog is newer always wins.

Unknown input modalities are dropped from individual remote model rows with a warning naming the row. Malformed model rows are skipped without rejecting the other models; required bundle and provider fields remain strictly validated. If no valid model rows remain, the download is rejected and the previous catalog stays active. Pricing-only v1 catalogs without model providers remain supported. The v1 and v2 publisher outputs keep the text, image, and document input modalities accepted by released clients. They omit native-only decision models and inference capabilities. Chat defaults and recommendations exclude native-only models. Rows with only unsupported input modalities are omitted rather than exposed as text models; defaults and recommendations do not reference omitted hosted rows.

Downloads use a separate SQLite cache key; existing v1 and v2 cache entries remain intact for older clients. Catalog publishers write both wires with --out <v1-file> --out-v2 <v2-file> when running scripts/publish-model-catalog.mts.

Add --out-v3 <v3-file> to publish an opt-in task-capable catalog. V3 retains canonical inference facts for native Decision models and models that support both chat and Decisions. Native-only rows never become chat defaults or recommendations. Select a v3 mirror with the existing models.catalogRefresh.url; the default hosted URL and v1/v2 outputs stay unchanged. The v3 wire version is independent of the Decision provider SDK version. Installed plugins still own route eligibility, authentication, and execution; catalog metadata grants none of those capabilities.

V3 changes only by adding fields. Readers ignore fields they do not know, at any level, so a newer publisher never needs a v4 for an additive change. The publisher still rejects unknown row, provider, and pricing fields, so typos there fail before publication. Never rename, retype, remove, or reuse a v3 field. Mark every non-chat row with inference.chat: false so older readers keep it out of chat.

V2 includes pricing in each model row. Unknown or unavailable pricing does not mean a model is free. Models outside the catalog, such as older model IDs or models routed through a gateway, use standalone rates in the same file: a gateway that charges the vendor's price reads that vendor's rate once, without a per-gateway copy. Explicit model costs still take precedence.

Native decision usage keeps the provider's reported USD cost, including zero. Without a reported cost, estimation uses token rates captured from the prepared provider route. Missing rates or billable counters, request-based billing, and native non-token units leave the cost unknown.

Pricing updates ship in the same hosted catalog file as model metadata. The retired models.pricing toggle is removed automatically by openclaw doctor --fix; use models.catalogRefresh.enabled: false when OpenClaw must avoid all hosted catalog traffic.

Discovery

mDNS (Bonjour)

{  discovery: {    mdns: {      mode: "minimal", // minimal | full | off    },  },}

• minimal (default): omit cliPath + sshPort from TXT records.
• full: include cliPath + sshPort; LAN multicast advertising still requires the bundled bonjour plugin to be enabled.
• off: suppress LAN multicast advertising without changing plugin enablement.
• The bundled bonjour plugin auto-starts on macOS hosts and is opt-in on Linux, Windows, and containerized Gateway deployments.
• Hostname defaults to the system hostname when it is a valid DNS label, falling back to openclaw. Override with OPENCLAW_MDNS_HOSTNAME.
• OPENCLAW_DISABLE_BONJOUR=1 disables mDNS advertising outright, overriding discovery.mdns.mode.

Wide-area (DNS-SD)

{  discovery: {    wideArea: { domain: "openclaw.internal" },  },}

Setting discovery.wideArea.domain enables wide-area discovery and writes a unicast DNS-SD zone under ~/.openclaw/dns/. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS.

Setup: openclaw dns setup --apply.

Update

{  update: {    channel: "stable", // stable | extended-stable | beta | dev    checkOnStart: true,     auto: {      enabled: false,    },  },}

• channel: release channel - "stable", "extended-stable", "beta", or "dev". Extended-stable is package-only: foreground commands own installation, while the Gateway may emit read-only update hints.
• checkOnStart: check for updates through https://telemetry.openclaw.ai/api/latest-version when the Gateway starts and at most once every 24 hours afterward (default: true). The default request shares only the OpenClaw version and platform information in its User-Agent; anonymous feature statistics are included only when telemetry.enabled is true. Setting this to false, or setting OPENCLAW_NO_AUTO_UPDATE=1, prevents all automatic update requests, feature statistics, and update notices, even when auto.enabled is true. Stored extended-stable selections use the same read-only hint and 24-hour hint schedule.
• auto.enabled: enable background auto-update campaigns for stable and beta package installs and dev git installs when checkOnStart is also enabled (default: false). Extended-stable never applies automatically.

Headless nodes have a separate default-on nodeHost.autoUpdate.enabled policy with hourly checks and idle-only activation. update.checkOnStart: false and OPENCLAW_NO_AUTO_UPDATE=1 disable that policy too. See Headless node updates.

ACP

{  acp: {    enabled: true,    dispatch: { enabled: true },    backend: "acpx",    fallbacks: ["acpx-secondary"],    defaultAgent: "main",    allowedAgents: ["main", "ops"],    stream: {      repeatSuppression: true,      deliveryMode: "live", // live | final_only    },  },}

• enabled: global ACP feature gate (default: true; set false to hide ACP dispatch and spawn affordances).
• dispatch.enabled: independent gate for ACP session turn dispatch (default: true). Set false to keep ACP commands available while blocking execution.
• backend: default ACP runtime backend id (must match a registered ACP runtime plugin). Install the backend plugin first, and if plugins.allow is set, include the backend plugin id (for example acpx) or the ACP backend will not load.
• fallbacks: ordered list of fallback ACP backend ids tried when the primary backend fails early with a transient-looking error (unavailable, rate-limited, quota exhausted, or overloaded) before it produced any output. Each entry must match a registered ACP runtime plugin backend.
• defaultAgent: fallback ACP target agent id when spawns do not specify an explicit target.
• allowedAgents: allowlist of agent ids permitted for ACP runtime sessions; empty means no additional restriction.
• stream.repeatSuppression: suppress repeated status/tool lines per turn (default: true).
• stream.deliveryMode: "live" streams incrementally; "final_only" buffers until turn terminal events.
• stream.tagVisibility: record of tag names to boolean visibility overrides for streamed events.
• runtime.installCommand: optional install command to run when bootstrapping an ACP runtime environment.

Wizard

Behavior and metadata for CLI guided setup flows (onboard, configure, doctor):

{  wizard: {    accessMode: "full",    appRecommendations: true,    lastRunAt: "2026-01-01T00:00:00.000Z",    lastRunVersion: "2026.1.4",    lastRunCommit: "abc1234",    lastRunCommand: "configure",    lastRunMode: "local",    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",  },}

• wizard.accessMode: discovery consent chosen at the start of guided onboarding. "full" (recommended) lets setup look for AI apps, keys, and local runtimes automatically; "guarded" makes setup ask once before looking around and offers manual configuration instead.

• wizard.appRecommendations defaults to true. Set it to false to disable installed-application recommendations during guided or classic onboarding and block Gateway device.apps access. Node hosts still require their separate, default-off installed-app sharing flag before they advertise the command.

Bridge (legacy, removed)

Current builds no longer include the TCP bridge. Nodes connect over the Gateway WebSocket. bridge.* keys are no longer part of the config schema (validation fails until removed; openclaw doctor --fix can strip unknown keys).

{  "bridge": {    "enabled": true,    "port": 18790,    "bind": "tailnet",    "tls": {      "enabled": true,      "autoGenerate": true    }  }}