Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Support multi-file config loading (base + local overlay) for cross-machine setups [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#69776•Fetched 2026-04-22 07:48:26
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
EthanSKEthanSK
Participants
EthanSKEthanSK

I run OpenClaw on multiple machines (MacBook Pro + Mac-Mini) and share the ~/.openclaw/ directory via git so skills, hooks, agent definitions, and auth profiles stay in sync. It works, but the fact that everything lives in one openclaw.json means per-machine state (gateway port, which channels/accounts are actually active here, plugin install records) ends up mixed with genuinely shared state.

I just had an incident where a config sync between the two machines overwrote MacBook Pro's local openclaw.json with the Mac-Mini's version — restored from a timestamped backup, but it highlighted the design gap.

Root Cause

I run OpenClaw on multiple machines (MacBook Pro + Mac-Mini) and share the ~/.openclaw/ directory via git so skills, hooks, agent definitions, and auth profiles stay in sync. It works, but the fact that everything lives in one openclaw.json means per-machine state (gateway port, which channels/accounts are actually active here, plugin install records) ends up mixed with genuinely shared state.

I just had an incident where a config sync between the two machines overwrote MacBook Pro's local openclaw.json with the Mac-Mini's version — restored from a timestamped backup, but it highlighted the design gap.

Fix Action

Fix / Workaround

A single openclaw.json forces an all-or-nothing sync. Current workarounds:

Happy to open a PR if there's interest in the shape above. Could start with a simple deep-merge in the config loader and add openclaw.local.json as a convention without introducing new CLI surface.

Until then, my workaround is single-file + timestamped backups + sync discipline — works, but I've lost state once already today.

RAW_BUFFERClick to expand / collapse

Context

I run OpenClaw on multiple machines (MacBook Pro + Mac-Mini) and share the ~/.openclaw/ directory via git so skills, hooks, agent definitions, and auth profiles stay in sync. It works, but the fact that everything lives in one openclaw.json means per-machine state (gateway port, which channels/accounts are actually active here, plugin install records) ends up mixed with genuinely shared state.

I just had an incident where a config sync between the two machines overwrote MacBook Pro's local openclaw.json with the Mac-Mini's version — restored from a timestamped backup, but it highlighted the design gap.

Problem

A single openclaw.json forces an all-or-nothing sync. Current workarounds:

  • Discipline + manual backups before pulling (fragile — easy to forget).
  • Symlinks to abstract user paths (/Users/<host> variants) — works for paths but not semantics.
  • A .gitignore entry for openclaw.json entirely and per-machine maintenance — defeats the point of syncing.

None of these capture the actual intent: some sections are shared by design, some are per-machine by design.

Proposed solution

Base + overlay config loading. For example:

  • ~/.openclaw/openclaw.json — base (tracked, shared)
  • ~/.openclaw/openclaw.local.json — overlay (gitignored, machine-specific)

Gateway merges them at load time (deep merge; local wins on conflict). The base file would contain shared sections (skills, tools, hooks, agents, messages, commands, auth profile definitions). The local overlay would hold machine-specific sections (gateway port/binding, active channels/accounts, env overrides, plugin install state).

Optionally a third openclaw.secrets.json (also gitignored) for API keys, with reference-by-path support so the base file can point at them without exposing them.

Natural split boundaries (from current schema)

Shared (base)Machine-local (overlay)
metagateway (port, binding)
wizard (last-run metadata)channels.* active entries
skillsplugins install state
toolsenv overrides
commands(secrets)
agents
hooks
messages
auth.profiles.*.mode / non-secret fields

Prior art

  • VS Code: user settings (~/Library/.../settings.json) + workspace settings (.vscode/settings.json), last-wins merge.
  • Git: ~/.gitconfig + repo .git/config + include.path directive.
  • Helm: values.yaml + --values <override>.yaml, deep merge.
  • Kubernetes kustomize: base + overlays.

Willing to contribute

Happy to open a PR if there's interest in the shape above. Could start with a simple deep-merge in the config loader and add openclaw.local.json as a convention without introducing new CLI surface.

Until then, my workaround is single-file + timestamped backups + sync discipline — works, but I've lost state once already today.

Environment

  • OpenClaw 2026.4.15
  • macOS (dual-machine setup)
  • Config repo synced via git between machines

extent analysis

TL;DR

Implement a base and overlay configuration loading mechanism to separate shared and machine-specific settings in OpenClaw.

Guidance

  • Consider introducing a openclaw.local.json file to store machine-specific configurations, which can be gitignored to prevent overwriting between machines.
  • Use a deep merge approach to combine the base openclaw.json and openclaw.local.json files, with local settings taking precedence.
  • Identify and separate shared sections (e.g., skills, tools, hooks) from machine-specific sections (e.g., gateway port, active channels) to determine the natural split boundaries.
  • Review prior art from other projects (e.g., VS Code, Git, Helm, Kubernetes kustomize) for inspiration on implementing the base and overlay configuration loading mechanism.

Example

No code snippet is provided as the issue does not contain explicit code, but an example of the proposed configuration structure could be:

// openclaw.json (base)
{
  "skills": [...],
  "tools": [...],
  "hooks": [...]
}

// openclaw.local.json (overlay)
{
  "gateway": {
    "port": 8080,
    "binding": "localhost"
  },
  "channels": {
    "active": ["channel1", "channel2"]
  }
}

Notes

The proposed solution requires changes to the OpenClaw configuration loader to support the base and overlay mechanism. The issue author is willing to contribute to the project and open a PR to implement this feature.

Recommendation

Apply the proposed workaround by introducing a openclaw.local.json file and using a deep merge approach to combine the base and overlay configurations. This will allow for a separation of shared and machine-specific settings, reducing the risk of overwriting configurations between machines.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#model loading#dependency error#configuration error#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING