#8195: feat(migration): env fallbacks + legacy launchd cleanup
app: web-ui
gateway
agents
stale
Cluster:
Cross-Platform Fixes
## Summary
This PR improves the migration experience from legacy Clawdbot/Moltbot installations to OpenClaw by:
1. **Centralizing environment variable resolution** - Adds `MigrationService.getEnv()` with consistent fallback (`OPENCLAW_*` -> `CLAWDBOT_*` -> `MOLTBOT_*`), strict-mode guard, and accurate legacy warnings.
2. **Improving macOS launchd cleanup** - Ensures legacy LaunchAgent services (`ai.clawdbot.gateway`, `ai.moltbot.gateway`) are booted out, and surfaces real failures while ignoring "not found".
3. **Preserving gateway auth precedence** - Remote mode still prefers `gateway.remote.*` tokens (local env only in local mode), while password behavior remains unchanged.
## Changes
### `src/services/MigrationService.ts` [NEW]
- Implements `MigrationService.getEnv(key, env?)` with:
- Primary lookup: `OPENCLAW_<KEY>`
- Fallback: `CLAWDBOT_<KEY>` -> `MOLTBOT_<KEY>`
- Accurate legacy warnings when legacy vars are used
- **Strict mode**: If `~/.openclaw` exists, legacy vars are ignored unless `OPENCLAW_ALLOW_LEGACY_ENV=1`
- Adds unit tests for strict mode, caching, and warning key accuracy
### `src/gateway/auth.ts`
- Uses `MigrationService` for token/password resolution
- Threads `env` param through to support testing mocks
### `src/gateway/call.ts`
- Uses `MigrationService` for gateway token/password env lookups
- Keeps remote-mode token precedence aligned with pre-PR behavior
### `src/daemon/constants.ts`
- `resolveLegacyGatewayLaunchAgentLabels()` returns actual legacy labels
### `src/daemon/launchd.ts`
- `stopLaunchAgent()` bootouts legacy services and reports non-"not found" failures
### Branding Updates
- `src/routing/resolve-route.test.ts`: `MoltbotConfig` -> `OpenClawConfig`
- `src/gateway/server-methods/*.ts`: Updated doc links to openclaw/openclaw
- `src/agents/system-prompt.test.ts`: Updated test fixtures
## Related Issues
- Partially addresses #2354 (legacy launchd not stopped on mode switch)
- Improves experience for users migrating from Clawdbot/Moltbot (#6085, #6720)
## Testing
- `pnpm exec vitest run src/services/MigrationService.test.ts`
Most Similar PRs
#11602: fix(config): skip stale legacy config files when openclaw.json exists
by akoscz · 2026-02-08
77.2%
#5638: fix: rewrite sessionFile paths during state dir migration
by lailoo · 2026-01-31
73.4%
#23444: Gateway: move auth token storage to state dotenv by default
by bmendonca3 · 2026-02-22
72.3%
#10744: fix: update stale MoltbotProtocol paths to OpenClawProtocol
by marezgui · 2026-02-06
71.4%
#21188: doctor: clean up legacy Linux gateway services
by Phineas1500 · 2026-02-19
71.4%
#8260: fix(macOS): gateway readiness detection + reversible Configure later
by xksteven · 2026-02-03
71.2%
#7611: fix: migrate channels.telegram.token to botToken on config load
by luiginotmario · 2026-02-03
71.0%
#3561: fix: fail fast when both state dirs exist
by adityarao3 · 2026-01-28
70.7%
#18236: macOS daemon: bootstrap LaunchAgent on gateway start after stop
by agisilaos · 2026-02-16
70.5%
#10182: fix: skip non-openclaw LaunchAgents in doctor gateway scan
by Yida-Dev · 2026-02-06
70.2%