Re-implement Auto-Migration via OpenClaw Native Secrets System

[KHAEntertainment]

Context

Issue #34 tracks re-implementing the deprecated clawvault openclaw migrate --apply command. The original approach failed because OpenClaw doesn't expand ${ENV_VAR} placeholders in auth-profiles.json - it treats them as literal strings, causing auth failures.

OpenClaw now has a native secrets system with exec provider support and openclaw secrets apply command that accepts plan files. ClawVault's resolve command already implements the OpenClaw exec-provider protocol (JSON stdin/stdout). This opens a proper integration path.

Critical Findings

1. OAuth credentials do NOT support keyRef/tokenRef - OAuth tokens are "runtime-minted or rotating" and cannot use SecretRef. Only api_key and token credential types support refs.
2. Plan file supports providerUpserts - We can configure the clawvault exec provider entirely via the plan file - no separate setup command needed.
3. syncSiblingAgents feature - OAuth tokens can be synced to all sibling agents automatically during OAuth setup (via openclaw models auth login --sync-siblings).
4. Auth inheritance via mergeAuthProfileStores - Subagents automatically inherit from main agent if their own auth-profiles.json is empty.
5. Exec provider ID format - IDs like providers/openai/apiKey must match pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$.

Implementation Phases

Phase 1: Generate OpenClaw-Compatible Plan Files ✅

• New file: src/openclaw/plan.ts - SecretsApplyPlan types and utilities
• Modified: src/openclaw/migrate.ts - Added generateSecretsApplyPlan() and analyzeAuthStoreForPlan()
• OAuth credentials are correctly skipped with reason oauth_not_supported

Phase 2: Update Migration Command with --plan Option ✅

• Modified: src/cli/commands/openclaw-migrate.ts - Added --plan and --provider-name options
• Generates clawvault-migration-plan.json compatible with openclaw secrets apply

Phase 3: Config Cleanup/Deduplication Feature ✅

• New file: src/cli/commands/openclaw-cleanup.ts - Detects redundant auth configurations
• Identifies shared profiles, agents with no unique profiles, and global provider candidates

Phase 4: Update Documentation ✅

• Modified: docs/MIGRATION.md - Updated recommended workflow

What CAN and CANNOT Be Migrated

Credential Type	Can Migrate via Plan?	Notes
api_key with key	✅ Yes	Convert to keyRef with exec source
token with token	✅ Yes	Convert to tokenRef with exec source
oauth credentials	❌ No	OAuth doesn't support keyRef/tokenRef

For OAuth: Users must re-authenticate via openclaw models auth login --sync-siblings

Verification Steps

1. Unit tests - add tests for plan generation (TODO)
2. Integration test - Run migrate with --plan and verify plan.json is valid
3. Manual verification - Test clawvault resolve with exec provider IDs

Related

• Supersedes the deprecated --apply approach that rewrites with ${ENV_VAR} placeholders
• Build errors in web/index.ts are pre-existing and unrelated to this PR

[traycerai]

Warning

Insufficient credits. Please purchase more credits or upgrade your plan to continue using Traycer.