2026 OpenClaw Migration and Cold-Start Runbook: From Copying Directories to First Gateway Link (systemd vs launchd)

1. Pain points: copied trees are not runnable by themselves

Teams migrating from laptops or old VPS hosts routinely assume that if the directory listing matches, behavior will match. OpenClaw actually depends on four coupled layers: which openclaw binary wins on PATH, the on-disk configuration tree under ~/.openclaw, workspace-relative assets, and the supervisor context that systemd or launchd provides. Drop any layer and you get intermittent symptoms such as a gateway that runs fine inside an SSH session but disappears after disconnect or reboot.

1. CLI drift across machines: The old host may have used global npm while the new Mac cloud image only ships Homebrew paths or a static install script layout. Copying JSON does not install binaries. Mixed pnpm workspaces plus global packages can even produce matching version strings with different dynamic loader paths.
2. Broken daemon context: On Linux, systemd --user units often declare Environment=HOME=... explicitly. On macOS, LaunchAgents do not inherit login shell rc files, so nvm-style prefixes vanish unless you embed absolute paths or a thin wrapper script. A wrong WorkingDirectory silently points logs and credential lookups at the wrong place.
3. Wrong triage order: Jumping to channel pairing before validating openclaw.json syntax and port 18789 wastes hours. Local probes must go green before you touch upstream messaging surfaces.
4. Ownership after rsync: Trees copied as root and later handed to an application user may be readable yet not writable for stderr logs, yielding mute failures that look like mysterious hangs.

2. systemd versus launchd environment matrix

Use the table as an appendix to your change ticket. The first-stop column highlights what operators should verify on the host before blaming chat providers or firewalls.

If the destination is a long-lived Mac cloud instance, prefer locking absolute paths and log files in launchd first, then decide whether Docker partitioning is worth the extra volume and uid complexity. On Linux, if you already run other user-level daemons under systemd --user, align OpenClaw with the same slice limits so a heavy xcodebuild neighbor cannot starve Gateway responses.

3. Seven-step cold start to first successful link

These steps deliberately front-load human-readable signals and defer anything that needs an external account. For overnight cutovers, annotate expected minutes per step in the maintenance window so the incident lead can choose continue versus rollback without debating scope ad hoc.

1. Freeze version and medium: Record openclaw --version, npm versus pnpm versus install script versus image digest on the old host. Pick a single entry point on the new host using the install-path article before copying trees so you never run two binaries accidentally.
2. Sync directories: Use rsync -aH or equivalent for ~/.openclaw and the workspace, honoring team exclusions for large caches. Immediately compare mtimes and sizes for critical files so partial transfers are caught early.
3. Permissions and secrets reachability: Run ls -la ~/.openclaw. For Docker flows, revalidate bind mounts and uid mapping using the Docker section of the install guide.
4. Author the service unit: Linux gets a systemd --user unit with explicit environment lines. macOS gets a LaunchAgent whose ProgramArguments use absolute paths to openclaw. Encode listen address and port explicitly when defaults move between releases.
5. Load and cold start: systemctl --user daemon-reload && restart or launchctl bootstrap followed by kickstart. Confirm the parent process is systemd or launchd, not an SSH session.
6. Local probes: lsof -i :18789, minimal JSON validation, then openclaw doctor following the ladder article. Do not rotate channel tokens while probes are red.
7. Channel smoke test: Only after Gateway logs look healthy should you repair pairing. Capture command transcripts in the change record for auditors.

4. Reference bullets: paths, port 18789, audit fields

This section is the wiki appendix; the numbered steps above are the narrative. Together they give both sequence and checklist depth for postmortems.

• Single source of truth for JSON: Document which machine owns the canonical openclaw.json and how backups are taken. After migration, diff old versus new files before starting services to avoid half-written merges.
• Port contention: Multiple lab gateways on one Mac cloud host must use distinct ports or stopped labels. Contention often masquerades as flaky connectivity.
• Audit minimum: Medium, semver, unit or plist label, image digest if containerized, first green doctor summary, channel account id, pairing timestamp, operator ids for regulated environments.
• Rollback: Keep the last known-good unit file and package or image tag on the old host. Quarterly drills ensure keys rotated since that snapshot can still be restored within RTO.
• Upstream risks: After install and supervisor layers pass, handle ClawHub Skill supply chain topics using the April 2026 audit checklist article.
• Time zones: When correlating file logs across regions, align NTP and displayed time zones before inferring causality.

5. FAQ

Q: I only copied the workspace, not ~/.openclaw. Can Gateway still start?
You will miss keys and local state. Either migrate both volumes or rebuild secrets deliberately with a read-only export checklist from the old host.

Q: launchctl shows loaded but nothing listens on 18789?
Inspect StandardErrorPath, WorkingDirectory, and plist PATH. Empty error files may mean logs are directed to an unwritable path.

Q: Can I reuse my Linux systemd unit on macOS?
No. Rewrite as a LaunchAgent and re-validate environment variables and log paths line by line.

Q: Channel is silent but 18789 responds locally?
Read Gateway logs first, then upstream network and allow lists. Avoid nuking entire configs before ruling out bind address mismatches after recent edits.

Q: I want a side-by-side old instance for comparison?
Use distinct ports and labels and forbid writing production JSON from the lab unit to prevent double-writer corruption.

6. From pilot to production on native Mac cloud

Runbook complexity tracks how closely SSH access matches production. Nested virtualization magnifies PATH, volume, and permission surprises. A dedicated Mac cloud host with launchd aligned to the install guide is the shortest path to auditable cold starts. Add Docker sandboxes only after the native path is boringly reliable, not during the first migration window.

Treat long-lived OpenClaw gateways as infrastructure peers to CI runners: reserve disk, rotate logs, tag nodes, and wire login auditing. When every teammate follows the same plist and directory contract, future migrations repeat a known playbook instead of improvising per laptop.