#7596: docs(gateway): add multi-machine config sync guide
docs
gateway
size: XS
## Summary
Adds documentation for syncing OpenClaw config between multiple machines (e.g., home server + laptop) using git while keeping machine-specific gateway settings separate.
## Problem
Users with multiple machines often want to:
- Keep a server running the gateway 24/7
- Use a laptop that connects remotely when home, but runs locally when traveling
- Sync workspaces, sessions, and config via git
The challenge: \`gateway.mode\` needs to be \`local\` on the server but \`remote\` on the laptop. A simple git sync overwrites these settings.
## Solution
Uses the existing \`\$include\` directive to split machine-specific gateway config into a gitignored file (\`gateway-local.json5\`), while keeping shared settings in the tracked \`openclaw.json\`.
## Documentation Includes
- Step-by-step setup for server and laptop
- Git configuration with proper ignores
- Optional mode-switching scripts for laptops
- Troubleshooting common issues (timestamp conflicts, session continuity)
- Table of what should/shouldn't be synced
## Related Docs
Links to existing docs:
- [Configuration](/gateway/configuration)
- [Config Includes](/gateway/configuration#config-includes-include)
- [Remote Access](/gateway/remote)
- [Multiple Gateways](/gateway/multiple-gateways)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
Adds a new Gateway documentation page (`docs/gateway/multi-machine-sync.md`) describing how to sync `~/.openclaw` across multiple machines via git while keeping machine-specific gateway settings separate using `$include`.
The doc covers: creating per-machine `gateway-local.json5`, updating `openclaw.json`, suggested `.gitignore` entries, optional mode-switching scripts, an auto-sync cron example, and troubleshooting guidance. This fits into the existing Gateway docs alongside the configuration and remote access guides by providing a practical workflow for multi-host setups.
<h3>Confidence Score: 3/5</h3>
- Mostly safe to merge, but there’s a likely docs-inaccuracy around `$include` semantics that could misconfigure users.
- Only a new documentation file is added, so code risk is low; however, the recommended config structure appears to contradict the documented `$include` replacement behavior, which could lead to broken configs for readers following the guide.
- docs/gateway/multi-machine-sync.md (especially the `$include` example/merge explanation and internal anchor link)
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#14579: docs: add guide for openclaw-bridge-remote (MCP)
by lucas-jo · 2026-02-12
74.2%
#12834: docs(gateway): clarify there is no standalone clawrouter binary
by JBrady · 2026-02-09
73.3%
#20700: docs: add real-world setups and use cases guide
by aiagentswiz · 2026-02-19
71.7%
#12123: docs: add dedicated hardware guide (Jetson, Pi, mini PCs)
by yalexx · 2026-02-08
71.5%
#10894: Docs: fix legacy branding, add config reference, expand cron troubl...
by biv0711 · 2026-02-07
71.3%
#11915: Docs: Docker + reverse proxy deployment notes and pairing pitfalls
by walshd1 · 2026-02-08
71.3%
#11455: fix(gateway): default gateway.mode to local when unset
by AnonO6 · 2026-02-07
70.8%
#5036: docs: improve Slack setup and troubleshooting guide
by DanBatten · 2026-01-31
70.0%
#9081: docs(discord): add proxy configuration guide
by xxl115 · 2026-02-04
69.8%
#12234: gateway: incident tracking, recover command, and ciao ERR_SERVER_CL...
by levineam · 2026-02-09
69.4%