Merge pull request #33 from corylanou/issue-27-feat-add-picoclaw-migrate-command-for-openclaw-workspace-migration

feat(migrate): add picoclaw migrate command for OpenClaw workspace migration

Adds migrate command to migrate workspace and config from OpenClaw to PicoClaw.

- Migrates workspace files (SOUL.md, AGENTS.md, USER.md, TOOLS.md, HEARTBEAT.md, memory/, skills/)
- Converts config from camelCase (OpenClaw) to snake_case (PicoClaw) format
- Supports --dry-run, --refresh, --config-only, --workspace-only, --force flags
- Safety: backups (.bak), confirmation prompts, no silent overwrites

Closes #27

cmd/picoclaw/main.go

@@ -26,6 +26,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/cron"
 	"github.com/sipeed/picoclaw/pkg/heartbeat"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/migrate"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/skills"
 	"github.com/sipeed/picoclaw/pkg/tools"
@@ -86,6 +87,8 @@ func main() {
 		gatewayCmd()
 	case "status":
 		statusCmd()
+	case "migrate":
+		migrateCmd()
 	case "auth":
 		authCmd()
 	case "cron":
@@ -159,6 +162,7 @@ func printHelp() {
 	fmt.Println("  gateway     Start picoclaw gateway")
 	fmt.Println("  status      Show picoclaw status")
 	fmt.Println("  cron        Manage scheduled tasks")
+	fmt.Println("  migrate     Migrate from OpenClaw to PicoClaw")
 	fmt.Println("  skills      Manage skills (install, list, remove)")
 	fmt.Println("  version     Show version information")
 }
@@ -364,6 +368,76 @@ This file stores important information that should persist across sessions.
 	}
 }
 
+func migrateCmd() {
+	if len(os.Args) > 2 && (os.Args[2] == "--help" || os.Args[2] == "-h") {
+		migrateHelp()
+		return
+	}
+
+	opts := migrate.Options{}
+
+	args := os.Args[2:]
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--dry-run":
+			opts.DryRun = true
+		case "--config-only":
+			opts.ConfigOnly = true
+		case "--workspace-only":
+			opts.WorkspaceOnly = true
+		case "--force":
+			opts.Force = true
+		case "--refresh":
+			opts.Refresh = true
+		case "--openclaw-home":
+			if i+1 < len(args) {
+				opts.OpenClawHome = args[i+1]
+				i++
+			}
+		case "--picoclaw-home":
+			if i+1 < len(args) {
+				opts.PicoClawHome = args[i+1]
+				i++
+			}
+		default:
+			fmt.Printf("Unknown flag: %s\n", args[i])
+			migrateHelp()
+			os.Exit(1)
+		}
+	}
+
+	result, err := migrate.Run(opts)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	if !opts.DryRun {
+		migrate.PrintSummary(result)
+	}
+}
+
+func migrateHelp() {
+	fmt.Println("\nMigrate from OpenClaw to PicoClaw")
+	fmt.Println()
+	fmt.Println("Usage: picoclaw migrate [options]")
+	fmt.Println()
+	fmt.Println("Options:")
+	fmt.Println("  --dry-run          Show what would be migrated without making changes")
+	fmt.Println("  --refresh          Re-sync workspace files from OpenClaw (repeatable)")
+	fmt.Println("  --config-only      Only migrate config, skip workspace files")
+	fmt.Println("  --workspace-only   Only migrate workspace files, skip config")
+	fmt.Println("  --force            Skip confirmation prompts")
+	fmt.Println("  --openclaw-home    Override OpenClaw home directory (default: ~/.openclaw)")
+	fmt.Println("  --picoclaw-home    Override PicoClaw home directory (default: ~/.picoclaw)")
+	fmt.Println()
+	fmt.Println("Examples:")
+	fmt.Println("  picoclaw migrate              Detect and migrate from OpenClaw")
+	fmt.Println("  picoclaw migrate --dry-run    Show what would be migrated")
+	fmt.Println("  picoclaw migrate --refresh    Re-sync workspace files")
+	fmt.Println("  picoclaw migrate --force      Migrate without confirmation")
+}
+
 func agentCmd() {
 	message := ""
 	sessionKey := "cli:default"

pkg/migrate/config.go

@@ -0,0 +1,377 @@
+package migrate
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"unicode"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+var supportedProviders = map[string]bool{
+	"anthropic":  true,
+	"openai":     true,
+	"openrouter": true,
+	"groq":       true,
+	"zhipu":      true,
+	"vllm":       true,
+	"gemini":     true,
+}
+
+var supportedChannels = map[string]bool{
+	"telegram": true,
+	"discord":  true,
+	"whatsapp": true,
+	"feishu":   true,
+	"qq":       true,
+	"dingtalk":  true,
+	"maixcam":  true,
+}
+
+func findOpenClawConfig(openclawHome string) (string, error) {
+	candidates := []string{
+		filepath.Join(openclawHome, "openclaw.json"),
+		filepath.Join(openclawHome, "config.json"),
+	}
+	for _, p := range candidates {
+		if _, err := os.Stat(p); err == nil {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("no config file found in %s (tried openclaw.json, config.json)", openclawHome)
+}
+
+func LoadOpenClawConfig(configPath string) (map[string]interface{}, error) {
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		return nil, fmt.Errorf("reading OpenClaw config: %w", err)
+	}
+
+	var raw map[string]interface{}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return nil, fmt.Errorf("parsing OpenClaw config: %w", err)
+	}
+
+	converted := convertKeysToSnake(raw)
+	result, ok := converted.(map[string]interface{})
+	if !ok {
+		return nil, fmt.Errorf("unexpected config format")
+	}
+	return result, nil
+}
+
+func ConvertConfig(data map[string]interface{}) (*config.Config, []string, error) {
+	cfg := config.DefaultConfig()
+	var warnings []string
+
+	if agents, ok := getMap(data, "agents"); ok {
+		if defaults, ok := getMap(agents, "defaults"); ok {
+			if v, ok := getString(defaults, "model"); ok {
+				cfg.Agents.Defaults.Model = v
+			}
+			if v, ok := getFloat(defaults, "max_tokens"); ok {
+				cfg.Agents.Defaults.MaxTokens = int(v)
+			}
+			if v, ok := getFloat(defaults, "temperature"); ok {
+				cfg.Agents.Defaults.Temperature = v
+			}
+			if v, ok := getFloat(defaults, "max_tool_iterations"); ok {
+				cfg.Agents.Defaults.MaxToolIterations = int(v)
+			}
+			if v, ok := getString(defaults, "workspace"); ok {
+				cfg.Agents.Defaults.Workspace = rewriteWorkspacePath(v)
+			}
+		}
+	}
+
+	if providers, ok := getMap(data, "providers"); ok {
+		for name, val := range providers {
+			pMap, ok := val.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			apiKey, _ := getString(pMap, "api_key")
+			apiBase, _ := getString(pMap, "api_base")
+
+			if !supportedProviders[name] {
+				if apiKey != "" || apiBase != "" {
+					warnings = append(warnings, fmt.Sprintf("Provider '%s' not supported in PicoClaw, skipping", name))
+				}
+				continue
+			}
+
+			pc := config.ProviderConfig{APIKey: apiKey, APIBase: apiBase}
+			switch name {
+			case "anthropic":
+				cfg.Providers.Anthropic = pc
+			case "openai":
+				cfg.Providers.OpenAI = pc
+			case "openrouter":
+				cfg.Providers.OpenRouter = pc
+			case "groq":
+				cfg.Providers.Groq = pc
+			case "zhipu":
+				cfg.Providers.Zhipu = pc
+			case "vllm":
+				cfg.Providers.VLLM = pc
+			case "gemini":
+				cfg.Providers.Gemini = pc
+			}
+		}
+	}
+
+	if channels, ok := getMap(data, "channels"); ok {
+		for name, val := range channels {
+			cMap, ok := val.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if !supportedChannels[name] {
+				warnings = append(warnings, fmt.Sprintf("Channel '%s' not supported in PicoClaw, skipping", name))
+				continue
+			}
+			enabled, _ := getBool(cMap, "enabled")
+			allowFrom := getStringSlice(cMap, "allow_from")
+
+			switch name {
+			case "telegram":
+				cfg.Channels.Telegram.Enabled = enabled
+				cfg.Channels.Telegram.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "token"); ok {
+					cfg.Channels.Telegram.Token = v
+				}
+			case "discord":
+				cfg.Channels.Discord.Enabled = enabled
+				cfg.Channels.Discord.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "token"); ok {
+					cfg.Channels.Discord.Token = v
+				}
+			case "whatsapp":
+				cfg.Channels.WhatsApp.Enabled = enabled
+				cfg.Channels.WhatsApp.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "bridge_url"); ok {
+					cfg.Channels.WhatsApp.BridgeURL = v
+				}
+			case "feishu":
+				cfg.Channels.Feishu.Enabled = enabled
+				cfg.Channels.Feishu.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "app_id"); ok {
+					cfg.Channels.Feishu.AppID = v
+				}
+				if v, ok := getString(cMap, "app_secret"); ok {
+					cfg.Channels.Feishu.AppSecret = v
+				}
+				if v, ok := getString(cMap, "encrypt_key"); ok {
+					cfg.Channels.Feishu.EncryptKey = v
+				}
+				if v, ok := getString(cMap, "verification_token"); ok {
+					cfg.Channels.Feishu.VerificationToken = v
+				}
+			case "qq":
+				cfg.Channels.QQ.Enabled = enabled
+				cfg.Channels.QQ.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "app_id"); ok {
+					cfg.Channels.QQ.AppID = v
+				}
+				if v, ok := getString(cMap, "app_secret"); ok {
+					cfg.Channels.QQ.AppSecret = v
+				}
+			case "dingtalk":
+				cfg.Channels.DingTalk.Enabled = enabled
+				cfg.Channels.DingTalk.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "client_id"); ok {
+					cfg.Channels.DingTalk.ClientID = v
+				}
+				if v, ok := getString(cMap, "client_secret"); ok {
+					cfg.Channels.DingTalk.ClientSecret = v
+				}
+			case "maixcam":
+				cfg.Channels.MaixCam.Enabled = enabled
+				cfg.Channels.MaixCam.AllowFrom = allowFrom
+				if v, ok := getString(cMap, "host"); ok {
+					cfg.Channels.MaixCam.Host = v
+				}
+				if v, ok := getFloat(cMap, "port"); ok {
+					cfg.Channels.MaixCam.Port = int(v)
+				}
+			}
+		}
+	}
+
+	if gateway, ok := getMap(data, "gateway"); ok {
+		if v, ok := getString(gateway, "host"); ok {
+			cfg.Gateway.Host = v
+		}
+		if v, ok := getFloat(gateway, "port"); ok {
+			cfg.Gateway.Port = int(v)
+		}
+	}
+
+	if tools, ok := getMap(data, "tools"); ok {
+		if web, ok := getMap(tools, "web"); ok {
+			if search, ok := getMap(web, "search"); ok {
+				if v, ok := getString(search, "api_key"); ok {
+					cfg.Tools.Web.Search.APIKey = v
+				}
+				if v, ok := getFloat(search, "max_results"); ok {
+					cfg.Tools.Web.Search.MaxResults = int(v)
+				}
+			}
+		}
+	}
+
+	return cfg, warnings, nil
+}
+
+func MergeConfig(existing, incoming *config.Config) *config.Config {
+	if existing.Providers.Anthropic.APIKey == "" {
+		existing.Providers.Anthropic = incoming.Providers.Anthropic
+	}
+	if existing.Providers.OpenAI.APIKey == "" {
+		existing.Providers.OpenAI = incoming.Providers.OpenAI
+	}
+	if existing.Providers.OpenRouter.APIKey == "" {
+		existing.Providers.OpenRouter = incoming.Providers.OpenRouter
+	}
+	if existing.Providers.Groq.APIKey == "" {
+		existing.Providers.Groq = incoming.Providers.Groq
+	}
+	if existing.Providers.Zhipu.APIKey == "" {
+		existing.Providers.Zhipu = incoming.Providers.Zhipu
+	}
+	if existing.Providers.VLLM.APIKey == "" && existing.Providers.VLLM.APIBase == "" {
+		existing.Providers.VLLM = incoming.Providers.VLLM
+	}
+	if existing.Providers.Gemini.APIKey == "" {
+		existing.Providers.Gemini = incoming.Providers.Gemini
+	}
+
+	if !existing.Channels.Telegram.Enabled && incoming.Channels.Telegram.Enabled {
+		existing.Channels.Telegram = incoming.Channels.Telegram
+	}
+	if !existing.Channels.Discord.Enabled && incoming.Channels.Discord.Enabled {
+		existing.Channels.Discord = incoming.Channels.Discord
+	}
+	if !existing.Channels.WhatsApp.Enabled && incoming.Channels.WhatsApp.Enabled {
+		existing.Channels.WhatsApp = incoming.Channels.WhatsApp
+	}
+	if !existing.Channels.Feishu.Enabled && incoming.Channels.Feishu.Enabled {
+		existing.Channels.Feishu = incoming.Channels.Feishu
+	}
+	if !existing.Channels.QQ.Enabled && incoming.Channels.QQ.Enabled {
+		existing.Channels.QQ = incoming.Channels.QQ
+	}
+	if !existing.Channels.DingTalk.Enabled && incoming.Channels.DingTalk.Enabled {
+		existing.Channels.DingTalk = incoming.Channels.DingTalk
+	}
+	if !existing.Channels.MaixCam.Enabled && incoming.Channels.MaixCam.Enabled {
+		existing.Channels.MaixCam = incoming.Channels.MaixCam
+	}
+
+	if existing.Tools.Web.Search.APIKey == "" {
+		existing.Tools.Web.Search = incoming.Tools.Web.Search
+	}
+
+	return existing
+}
+
+func camelToSnake(s string) string {
+	var result strings.Builder
+	for i, r := range s {
+		if unicode.IsUpper(r) {
+			if i > 0 {
+				prev := rune(s[i-1])
+				if unicode.IsLower(prev) || unicode.IsDigit(prev) {
+					result.WriteRune('_')
+				} else if unicode.IsUpper(prev) && i+1 < len(s) && unicode.IsLower(rune(s[i+1])) {
+					result.WriteRune('_')
+				}
+			}
+			result.WriteRune(unicode.ToLower(r))
+		} else {
+			result.WriteRune(r)
+		}
+	}
+	return result.String()
+}
+
+func convertKeysToSnake(data interface{}) interface{} {
+	switch v := data.(type) {
+	case map[string]interface{}:
+		result := make(map[string]interface{}, len(v))
+		for key, val := range v {
+			result[camelToSnake(key)] = convertKeysToSnake(val)
+		}
+		return result
+	case []interface{}:
+		result := make([]interface{}, len(v))
+		for i, val := range v {
+			result[i] = convertKeysToSnake(val)
+		}
+		return result
+	default:
+		return data
+	}
+}
+
+func rewriteWorkspacePath(path string) string {
+	path = strings.Replace(path, ".openclaw", ".picoclaw", 1)
+	return path
+}
+
+func getMap(data map[string]interface{}, key string) (map[string]interface{}, bool) {
+	v, ok := data[key]
+	if !ok {
+		return nil, false
+	}
+	m, ok := v.(map[string]interface{})
+	return m, ok
+}
+
+func getString(data map[string]interface{}, key string) (string, bool) {
+	v, ok := data[key]
+	if !ok {
+		return "", false
+	}
+	s, ok := v.(string)
+	return s, ok
+}
+
+func getFloat(data map[string]interface{}, key string) (float64, bool) {
+	v, ok := data[key]
+	if !ok {
+		return 0, false
+	}
+	f, ok := v.(float64)
+	return f, ok
+}
+
+func getBool(data map[string]interface{}, key string) (bool, bool) {
+	v, ok := data[key]
+	if !ok {
+		return false, false
+	}
+	b, ok := v.(bool)
+	return b, ok
+}
+
+func getStringSlice(data map[string]interface{}, key string) []string {
+	v, ok := data[key]
+	if !ok {
+		return []string{}
+	}
+	arr, ok := v.([]interface{})
+	if !ok {
+		return []string{}
+	}
+	result := make([]string, 0, len(arr))
+	for _, item := range arr {
+		if s, ok := item.(string); ok {
+			result = append(result, s)
+		}
+	}
+	return result
+}

pkg/migrate/migrate.go

@@ -0,0 +1,394 @@
+package migrate
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type ActionType int
+
+const (
+	ActionCopy ActionType = iota
+	ActionSkip
+	ActionBackup
+	ActionConvertConfig
+	ActionCreateDir
+	ActionMergeConfig
+)
+
+type Options struct {
+	DryRun        bool
+	ConfigOnly    bool
+	WorkspaceOnly bool
+	Force         bool
+	Refresh       bool
+	OpenClawHome  string
+	PicoClawHome  string
+}
+
+type Action struct {
+	Type        ActionType
+	Source      string
+	Destination string
+	Description string
+}
+
+type Result struct {
+	FilesCopied    int
+	FilesSkipped   int
+	BackupsCreated int
+	ConfigMigrated bool
+	DirsCreated    int
+	Warnings       []string
+	Errors         []error
+}
+
+func Run(opts Options) (*Result, error) {
+	if opts.ConfigOnly && opts.WorkspaceOnly {
+		return nil, fmt.Errorf("--config-only and --workspace-only are mutually exclusive")
+	}
+
+	if opts.Refresh {
+		opts.WorkspaceOnly = true
+	}
+
+	openclawHome, err := resolveOpenClawHome(opts.OpenClawHome)
+	if err != nil {
+		return nil, err
+	}
+
+	picoClawHome, err := resolvePicoClawHome(opts.PicoClawHome)
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err := os.Stat(openclawHome); os.IsNotExist(err) {
+		return nil, fmt.Errorf("OpenClaw installation not found at %s", openclawHome)
+	}
+
+	actions, warnings, err := Plan(opts, openclawHome, picoClawHome)
+	if err != nil {
+		return nil, err
+	}
+
+	fmt.Println("Migrating from OpenClaw to PicoClaw")
+	fmt.Printf("  Source:      %s\n", openclawHome)
+	fmt.Printf("  Destination: %s\n", picoClawHome)
+	fmt.Println()
+
+	if opts.DryRun {
+		PrintPlan(actions, warnings)
+		return &Result{Warnings: warnings}, nil
+	}
+
+	if !opts.Force {
+		PrintPlan(actions, warnings)
+		if !Confirm() {
+			fmt.Println("Aborted.")
+			return &Result{Warnings: warnings}, nil
+		}
+		fmt.Println()
+	}
+
+	result := Execute(actions, openclawHome, picoClawHome)
+	result.Warnings = warnings
+	return result, nil
+}
+
+func Plan(opts Options, openclawHome, picoClawHome string) ([]Action, []string, error) {
+	var actions []Action
+	var warnings []string
+
+	force := opts.Force || opts.Refresh
+
+	if !opts.WorkspaceOnly {
+		configPath, err := findOpenClawConfig(openclawHome)
+		if err != nil {
+			if opts.ConfigOnly {
+				return nil, nil, err
+			}
+			warnings = append(warnings, fmt.Sprintf("Config migration skipped: %v", err))
+		} else {
+			actions = append(actions, Action{
+				Type:        ActionConvertConfig,
+				Source:      configPath,
+				Destination: filepath.Join(picoClawHome, "config.json"),
+				Description: "convert OpenClaw config to PicoClaw format",
+			})
+
+			data, err := LoadOpenClawConfig(configPath)
+			if err == nil {
+				_, configWarnings, _ := ConvertConfig(data)
+				warnings = append(warnings, configWarnings...)
+			}
+		}
+	}
+
+	if !opts.ConfigOnly {
+		srcWorkspace := resolveWorkspace(openclawHome)
+		dstWorkspace := resolveWorkspace(picoClawHome)
+
+		if _, err := os.Stat(srcWorkspace); err == nil {
+			wsActions, err := PlanWorkspaceMigration(srcWorkspace, dstWorkspace, force)
+			if err != nil {
+				return nil, nil, fmt.Errorf("planning workspace migration: %w", err)
+			}
+			actions = append(actions, wsActions...)
+		} else {
+			warnings = append(warnings, "OpenClaw workspace directory not found, skipping workspace migration")
+		}
+	}
+
+	return actions, warnings, nil
+}
+
+func Execute(actions []Action, openclawHome, picoClawHome string) *Result {
+	result := &Result{}
+
+	for _, action := range actions {
+		switch action.Type {
+		case ActionConvertConfig:
+			if err := executeConfigMigration(action.Source, action.Destination, picoClawHome); err != nil {
+				result.Errors = append(result.Errors, fmt.Errorf("config migration: %w", err))
+				fmt.Printf("  ✗ Config migration failed: %v\n", err)
+			} else {
+				result.ConfigMigrated = true
+				fmt.Printf("  ✓ Converted config: %s\n", action.Destination)
+			}
+		case ActionCreateDir:
+			if err := os.MkdirAll(action.Destination, 0755); err != nil {
+				result.Errors = append(result.Errors, err)
+			} else {
+				result.DirsCreated++
+			}
+		case ActionBackup:
+			bakPath := action.Destination + ".bak"
+			if err := copyFile(action.Destination, bakPath); err != nil {
+				result.Errors = append(result.Errors, fmt.Errorf("backup %s: %w", action.Destination, err))
+				fmt.Printf("  ✗ Backup failed: %s\n", action.Destination)
+				continue
+			}
+			result.BackupsCreated++
+			fmt.Printf("  ✓ Backed up %s -> %s.bak\n", filepath.Base(action.Destination), filepath.Base(action.Destination))
+
+			if err := os.MkdirAll(filepath.Dir(action.Destination), 0755); err != nil {
+				result.Errors = append(result.Errors, err)
+				continue
+			}
+			if err := copyFile(action.Source, action.Destination); err != nil {
+				result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
+				fmt.Printf("  ✗ Copy failed: %s\n", action.Source)
+			} else {
+				result.FilesCopied++
+				fmt.Printf("  ✓ Copied %s\n", relPath(action.Source, openclawHome))
+			}
+		case ActionCopy:
+			if err := os.MkdirAll(filepath.Dir(action.Destination), 0755); err != nil {
+				result.Errors = append(result.Errors, err)
+				continue
+			}
+			if err := copyFile(action.Source, action.Destination); err != nil {
+				result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
+				fmt.Printf("  ✗ Copy failed: %s\n", action.Source)
+			} else {
+				result.FilesCopied++
+				fmt.Printf("  ✓ Copied %s\n", relPath(action.Source, openclawHome))
+			}
+		case ActionSkip:
+			result.FilesSkipped++
+		}
+	}
+
+	return result
+}
+
+func executeConfigMigration(srcConfigPath, dstConfigPath, picoClawHome string) error {
+	data, err := LoadOpenClawConfig(srcConfigPath)
+	if err != nil {
+		return err
+	}
+
+	incoming, _, err := ConvertConfig(data)
+	if err != nil {
+		return err
+	}
+
+	if _, err := os.Stat(dstConfigPath); err == nil {
+		existing, err := config.LoadConfig(dstConfigPath)
+		if err != nil {
+			return fmt.Errorf("loading existing PicoClaw config: %w", err)
+		}
+		incoming = MergeConfig(existing, incoming)
+	}
+
+	if err := os.MkdirAll(filepath.Dir(dstConfigPath), 0755); err != nil {
+		return err
+	}
+	return config.SaveConfig(dstConfigPath, incoming)
+}
+
+func Confirm() bool {
+	fmt.Print("Proceed with migration? (y/n): ")
+	var response string
+	fmt.Scanln(&response)
+	return strings.ToLower(strings.TrimSpace(response)) == "y"
+}
+
+func PrintPlan(actions []Action, warnings []string) {
+	fmt.Println("Planned actions:")
+	copies := 0
+	skips := 0
+	backups := 0
+	configCount := 0
+
+	for _, action := range actions {
+		switch action.Type {
+		case ActionConvertConfig:
+			fmt.Printf("  [config]  %s -> %s\n", action.Source, action.Destination)
+			configCount++
+		case ActionCopy:
+			fmt.Printf("  [copy]    %s\n", filepath.Base(action.Source))
+			copies++
+		case ActionBackup:
+			fmt.Printf("  [backup]  %s (exists, will backup and overwrite)\n", filepath.Base(action.Destination))
+			backups++
+			copies++
+		case ActionSkip:
+			if action.Description != "" {
+				fmt.Printf("  [skip]    %s (%s)\n", filepath.Base(action.Source), action.Description)
+			}
+			skips++
+		case ActionCreateDir:
+			fmt.Printf("  [mkdir]   %s\n", action.Destination)
+		}
+	}
+
+	if len(warnings) > 0 {
+		fmt.Println()
+		fmt.Println("Warnings:")
+		for _, w := range warnings {
+			fmt.Printf("  - %s\n", w)
+		}
+	}
+
+	fmt.Println()
+	fmt.Printf("%d files to copy, %d configs to convert, %d backups needed, %d skipped\n",
+		copies, configCount, backups, skips)
+}
+
+func PrintSummary(result *Result) {
+	fmt.Println()
+	parts := []string{}
+	if result.FilesCopied > 0 {
+		parts = append(parts, fmt.Sprintf("%d files copied", result.FilesCopied))
+	}
+	if result.ConfigMigrated {
+		parts = append(parts, "1 config converted")
+	}
+	if result.BackupsCreated > 0 {
+		parts = append(parts, fmt.Sprintf("%d backups created", result.BackupsCreated))
+	}
+	if result.FilesSkipped > 0 {
+		parts = append(parts, fmt.Sprintf("%d files skipped", result.FilesSkipped))
+	}
+
+	if len(parts) > 0 {
+		fmt.Printf("Migration complete! %s.\n", strings.Join(parts, ", "))
+	} else {
+		fmt.Println("Migration complete! No actions taken.")
+	}
+
+	if len(result.Errors) > 0 {
+		fmt.Println()
+		fmt.Printf("%d errors occurred:\n", len(result.Errors))
+		for _, e := range result.Errors {
+			fmt.Printf("  - %v\n", e)
+		}
+	}
+}
+
+func resolveOpenClawHome(override string) (string, error) {
+	if override != "" {
+		return expandHome(override), nil
+	}
+	if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
+		return expandHome(envHome), nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolving home directory: %w", err)
+	}
+	return filepath.Join(home, ".openclaw"), nil
+}
+
+func resolvePicoClawHome(override string) (string, error) {
+	if override != "" {
+		return expandHome(override), nil
+	}
+	if envHome := os.Getenv("PICOCLAW_HOME"); envHome != "" {
+		return expandHome(envHome), nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolving home directory: %w", err)
+	}
+	return filepath.Join(home, ".picoclaw"), nil
+}
+
+func resolveWorkspace(homeDir string) string {
+	return filepath.Join(homeDir, "workspace")
+}
+
+func expandHome(path string) string {
+	if path == "" {
+		return path
+	}
+	if path[0] == '~' {
+		home, _ := os.UserHomeDir()
+		if len(path) > 1 && path[1] == '/' {
+			return home + path[1:]
+		}
+		return home
+	}
+	return path
+}
+
+func backupFile(path string) error {
+	bakPath := path + ".bak"
+	return copyFile(path, bakPath)
+}
+
+func copyFile(src, dst string) error {
+	srcFile, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer srcFile.Close()
+
+	info, err := srcFile.Stat()
+	if err != nil {
+		return err
+	}
+
+	dstFile, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+	if err != nil {
+		return err
+	}
+	defer dstFile.Close()
+
+	_, err = io.Copy(dstFile, srcFile)
+	return err
+}
+
+func relPath(path, base string) string {
+	rel, err := filepath.Rel(base, path)
+	if err != nil {
+		return filepath.Base(path)
+	}
+	return rel
+}

pkg/migrate/migrate_test.go

@@ -0,0 +1,854 @@
+package migrate
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestCamelToSnake(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"simple", "apiKey", "api_key"},
+		{"two words", "apiBase", "api_base"},
+		{"three words", "maxToolIterations", "max_tool_iterations"},
+		{"already snake", "api_key", "api_key"},
+		{"single word", "enabled", "enabled"},
+		{"all lower", "model", "model"},
+		{"consecutive caps", "apiURL", "api_url"},
+		{"starts upper", "Model", "model"},
+		{"bridge url", "bridgeUrl", "bridge_url"},
+		{"client id", "clientId", "client_id"},
+		{"app secret", "appSecret", "app_secret"},
+		{"verification token", "verificationToken", "verification_token"},
+		{"allow from", "allowFrom", "allow_from"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := camelToSnake(tt.input)
+			if got != tt.want {
+				t.Errorf("camelToSnake(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestConvertKeysToSnake(t *testing.T) {
+	input := map[string]interface{}{
+		"apiKey":  "test-key",
+		"apiBase": "https://example.com",
+		"nested": map[string]interface{}{
+			"maxTokens":   float64(8192),
+			"allowFrom":   []interface{}{"user1", "user2"},
+			"deeperLevel": map[string]interface{}{
+				"clientId": "abc",
+			},
+		},
+	}
+
+	result := convertKeysToSnake(input)
+	m, ok := result.(map[string]interface{})
+	if !ok {
+		t.Fatal("expected map[string]interface{}")
+	}
+
+	if _, ok := m["api_key"]; !ok {
+		t.Error("expected key 'api_key' after conversion")
+	}
+	if _, ok := m["api_base"]; !ok {
+		t.Error("expected key 'api_base' after conversion")
+	}
+
+	nested, ok := m["nested"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected nested map")
+	}
+	if _, ok := nested["max_tokens"]; !ok {
+		t.Error("expected key 'max_tokens' in nested map")
+	}
+	if _, ok := nested["allow_from"]; !ok {
+		t.Error("expected key 'allow_from' in nested map")
+	}
+
+	deeper, ok := nested["deeper_level"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected deeper_level map")
+	}
+	if _, ok := deeper["client_id"]; !ok {
+		t.Error("expected key 'client_id' in deeper level")
+	}
+}
+
+func TestLoadOpenClawConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	openclawConfig := map[string]interface{}{
+		"providers": map[string]interface{}{
+			"anthropic": map[string]interface{}{
+				"apiKey":  "sk-ant-test123",
+				"apiBase": "https://api.anthropic.com",
+			},
+		},
+		"agents": map[string]interface{}{
+			"defaults": map[string]interface{}{
+				"maxTokens": float64(4096),
+				"model":     "claude-3-opus",
+			},
+		},
+	}
+
+	data, err := json.Marshal(openclawConfig)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(configPath, data, 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := LoadOpenClawConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadOpenClawConfig: %v", err)
+	}
+
+	providers, ok := result["providers"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected providers map")
+	}
+	anthropic, ok := providers["anthropic"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected anthropic map")
+	}
+	if anthropic["api_key"] != "sk-ant-test123" {
+		t.Errorf("api_key = %v, want sk-ant-test123", anthropic["api_key"])
+	}
+
+	agents, ok := result["agents"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected agents map")
+	}
+	defaults, ok := agents["defaults"].(map[string]interface{})
+	if !ok {
+		t.Fatal("expected defaults map")
+	}
+	if defaults["max_tokens"] != float64(4096) {
+		t.Errorf("max_tokens = %v, want 4096", defaults["max_tokens"])
+	}
+}
+
+func TestConvertConfig(t *testing.T) {
+	t.Run("providers mapping", func(t *testing.T) {
+		data := map[string]interface{}{
+			"providers": map[string]interface{}{
+				"anthropic": map[string]interface{}{
+					"api_key":  "sk-ant-test",
+					"api_base": "https://api.anthropic.com",
+				},
+				"openrouter": map[string]interface{}{
+					"api_key": "sk-or-test",
+				},
+				"groq": map[string]interface{}{
+					"api_key": "gsk-test",
+				},
+			},
+		}
+
+		cfg, warnings, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if len(warnings) != 0 {
+			t.Errorf("expected no warnings, got %v", warnings)
+		}
+		if cfg.Providers.Anthropic.APIKey != "sk-ant-test" {
+			t.Errorf("Anthropic.APIKey = %q, want %q", cfg.Providers.Anthropic.APIKey, "sk-ant-test")
+		}
+		if cfg.Providers.OpenRouter.APIKey != "sk-or-test" {
+			t.Errorf("OpenRouter.APIKey = %q, want %q", cfg.Providers.OpenRouter.APIKey, "sk-or-test")
+		}
+		if cfg.Providers.Groq.APIKey != "gsk-test" {
+			t.Errorf("Groq.APIKey = %q, want %q", cfg.Providers.Groq.APIKey, "gsk-test")
+		}
+	})
+
+	t.Run("unsupported provider warning", func(t *testing.T) {
+		data := map[string]interface{}{
+			"providers": map[string]interface{}{
+				"deepseek": map[string]interface{}{
+					"api_key": "sk-deep-test",
+				},
+			},
+		}
+
+		_, warnings, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if len(warnings) != 1 {
+			t.Fatalf("expected 1 warning, got %d", len(warnings))
+		}
+		if warnings[0] != "Provider 'deepseek' not supported in PicoClaw, skipping" {
+			t.Errorf("unexpected warning: %s", warnings[0])
+		}
+	})
+
+	t.Run("channels mapping", func(t *testing.T) {
+		data := map[string]interface{}{
+			"channels": map[string]interface{}{
+				"telegram": map[string]interface{}{
+					"enabled":    true,
+					"token":      "tg-token-123",
+					"allow_from": []interface{}{"user1"},
+				},
+				"discord": map[string]interface{}{
+					"enabled": true,
+					"token":   "disc-token-456",
+				},
+			},
+		}
+
+		cfg, _, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if !cfg.Channels.Telegram.Enabled {
+			t.Error("Telegram should be enabled")
+		}
+		if cfg.Channels.Telegram.Token != "tg-token-123" {
+			t.Errorf("Telegram.Token = %q, want %q", cfg.Channels.Telegram.Token, "tg-token-123")
+		}
+		if len(cfg.Channels.Telegram.AllowFrom) != 1 || cfg.Channels.Telegram.AllowFrom[0] != "user1" {
+			t.Errorf("Telegram.AllowFrom = %v, want [user1]", cfg.Channels.Telegram.AllowFrom)
+		}
+		if !cfg.Channels.Discord.Enabled {
+			t.Error("Discord should be enabled")
+		}
+	})
+
+	t.Run("unsupported channel warning", func(t *testing.T) {
+		data := map[string]interface{}{
+			"channels": map[string]interface{}{
+				"email": map[string]interface{}{
+					"enabled": true,
+				},
+			},
+		}
+
+		_, warnings, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if len(warnings) != 1 {
+			t.Fatalf("expected 1 warning, got %d", len(warnings))
+		}
+		if warnings[0] != "Channel 'email' not supported in PicoClaw, skipping" {
+			t.Errorf("unexpected warning: %s", warnings[0])
+		}
+	})
+
+	t.Run("agent defaults", func(t *testing.T) {
+		data := map[string]interface{}{
+			"agents": map[string]interface{}{
+				"defaults": map[string]interface{}{
+					"model":                "claude-3-opus",
+					"max_tokens":           float64(4096),
+					"temperature":          0.5,
+					"max_tool_iterations":  float64(10),
+					"workspace":            "~/.openclaw/workspace",
+				},
+			},
+		}
+
+		cfg, _, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if cfg.Agents.Defaults.Model != "claude-3-opus" {
+			t.Errorf("Model = %q, want %q", cfg.Agents.Defaults.Model, "claude-3-opus")
+		}
+		if cfg.Agents.Defaults.MaxTokens != 4096 {
+			t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 4096)
+		}
+		if cfg.Agents.Defaults.Temperature != 0.5 {
+			t.Errorf("Temperature = %f, want %f", cfg.Agents.Defaults.Temperature, 0.5)
+		}
+		if cfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
+			t.Errorf("Workspace = %q, want %q", cfg.Agents.Defaults.Workspace, "~/.picoclaw/workspace")
+		}
+	})
+
+	t.Run("empty config", func(t *testing.T) {
+		data := map[string]interface{}{}
+
+		cfg, warnings, err := ConvertConfig(data)
+		if err != nil {
+			t.Fatalf("ConvertConfig: %v", err)
+		}
+		if len(warnings) != 0 {
+			t.Errorf("expected no warnings, got %v", warnings)
+		}
+		if cfg.Agents.Defaults.Model != "glm-4.7" {
+			t.Errorf("default model should be glm-4.7, got %q", cfg.Agents.Defaults.Model)
+		}
+	})
+}
+
+func TestMergeConfig(t *testing.T) {
+	t.Run("fills empty fields", func(t *testing.T) {
+		existing := config.DefaultConfig()
+		incoming := config.DefaultConfig()
+		incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
+		incoming.Providers.OpenRouter.APIKey = "sk-or-incoming"
+
+		result := MergeConfig(existing, incoming)
+		if result.Providers.Anthropic.APIKey != "sk-ant-incoming" {
+			t.Errorf("Anthropic.APIKey = %q, want %q", result.Providers.Anthropic.APIKey, "sk-ant-incoming")
+		}
+		if result.Providers.OpenRouter.APIKey != "sk-or-incoming" {
+			t.Errorf("OpenRouter.APIKey = %q, want %q", result.Providers.OpenRouter.APIKey, "sk-or-incoming")
+		}
+	})
+
+	t.Run("preserves existing non-empty fields", func(t *testing.T) {
+		existing := config.DefaultConfig()
+		existing.Providers.Anthropic.APIKey = "sk-ant-existing"
+
+		incoming := config.DefaultConfig()
+		incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
+		incoming.Providers.OpenAI.APIKey = "sk-oai-incoming"
+
+		result := MergeConfig(existing, incoming)
+		if result.Providers.Anthropic.APIKey != "sk-ant-existing" {
+			t.Errorf("Anthropic.APIKey should be preserved, got %q", result.Providers.Anthropic.APIKey)
+		}
+		if result.Providers.OpenAI.APIKey != "sk-oai-incoming" {
+			t.Errorf("OpenAI.APIKey should be filled, got %q", result.Providers.OpenAI.APIKey)
+		}
+	})
+
+	t.Run("merges enabled channels", func(t *testing.T) {
+		existing := config.DefaultConfig()
+		incoming := config.DefaultConfig()
+		incoming.Channels.Telegram.Enabled = true
+		incoming.Channels.Telegram.Token = "tg-token"
+
+		result := MergeConfig(existing, incoming)
+		if !result.Channels.Telegram.Enabled {
+			t.Error("Telegram should be enabled after merge")
+		}
+		if result.Channels.Telegram.Token != "tg-token" {
+			t.Errorf("Telegram.Token = %q, want %q", result.Channels.Telegram.Token, "tg-token")
+		}
+	})
+
+	t.Run("preserves existing enabled channels", func(t *testing.T) {
+		existing := config.DefaultConfig()
+		existing.Channels.Telegram.Enabled = true
+		existing.Channels.Telegram.Token = "existing-token"
+
+		incoming := config.DefaultConfig()
+		incoming.Channels.Telegram.Enabled = true
+		incoming.Channels.Telegram.Token = "incoming-token"
+
+		result := MergeConfig(existing, incoming)
+		if result.Channels.Telegram.Token != "existing-token" {
+			t.Errorf("Telegram.Token should be preserved, got %q", result.Channels.Telegram.Token)
+		}
+	})
+}
+
+func TestPlanWorkspaceMigration(t *testing.T) {
+	t.Run("copies available files", func(t *testing.T) {
+		srcDir := t.TempDir()
+		dstDir := t.TempDir()
+
+		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0644)
+		os.WriteFile(filepath.Join(srcDir, "SOUL.md"), []byte("# Soul"), 0644)
+		os.WriteFile(filepath.Join(srcDir, "USER.md"), []byte("# User"), 0644)
+
+		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
+		if err != nil {
+			t.Fatalf("PlanWorkspaceMigration: %v", err)
+		}
+
+		copyCount := 0
+		skipCount := 0
+		for _, a := range actions {
+			if a.Type == ActionCopy {
+				copyCount++
+			}
+			if a.Type == ActionSkip {
+				skipCount++
+			}
+		}
+		if copyCount != 3 {
+			t.Errorf("expected 3 copies, got %d", copyCount)
+		}
+		if skipCount != 2 {
+			t.Errorf("expected 2 skips (TOOLS.md, HEARTBEAT.md), got %d", skipCount)
+		}
+	})
+
+	t.Run("plans backup for existing destination files", func(t *testing.T) {
+		srcDir := t.TempDir()
+		dstDir := t.TempDir()
+
+		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0644)
+		os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing Agents"), 0644)
+
+		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
+		if err != nil {
+			t.Fatalf("PlanWorkspaceMigration: %v", err)
+		}
+
+		backupCount := 0
+		for _, a := range actions {
+			if a.Type == ActionBackup && filepath.Base(a.Destination) == "AGENTS.md" {
+				backupCount++
+			}
+		}
+		if backupCount != 1 {
+			t.Errorf("expected 1 backup action for AGENTS.md, got %d", backupCount)
+		}
+	})
+
+	t.Run("force skips backup", func(t *testing.T) {
+		srcDir := t.TempDir()
+		dstDir := t.TempDir()
+
+		os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0644)
+		os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing"), 0644)
+
+		actions, err := PlanWorkspaceMigration(srcDir, dstDir, true)
+		if err != nil {
+			t.Fatalf("PlanWorkspaceMigration: %v", err)
+		}
+
+		for _, a := range actions {
+			if a.Type == ActionBackup {
+				t.Error("expected no backup actions with force=true")
+			}
+		}
+	})
+
+	t.Run("handles memory directory", func(t *testing.T) {
+		srcDir := t.TempDir()
+		dstDir := t.TempDir()
+
+		memDir := filepath.Join(srcDir, "memory")
+		os.MkdirAll(memDir, 0755)
+		os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory"), 0644)
+
+		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
+		if err != nil {
+			t.Fatalf("PlanWorkspaceMigration: %v", err)
+		}
+
+		hasCopy := false
+		hasDir := false
+		for _, a := range actions {
+			if a.Type == ActionCopy && filepath.Base(a.Source) == "MEMORY.md" {
+				hasCopy = true
+			}
+			if a.Type == ActionCreateDir {
+				hasDir = true
+			}
+		}
+		if !hasCopy {
+			t.Error("expected copy action for memory/MEMORY.md")
+		}
+		if !hasDir {
+			t.Error("expected create dir action for memory/")
+		}
+	})
+
+	t.Run("handles skills directory", func(t *testing.T) {
+		srcDir := t.TempDir()
+		dstDir := t.TempDir()
+
+		skillDir := filepath.Join(srcDir, "skills", "weather")
+		os.MkdirAll(skillDir, 0755)
+		os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("# Weather"), 0644)
+
+		actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
+		if err != nil {
+			t.Fatalf("PlanWorkspaceMigration: %v", err)
+		}
+
+		hasCopy := false
+		for _, a := range actions {
+			if a.Type == ActionCopy && filepath.Base(a.Source) == "SKILL.md" {
+				hasCopy = true
+			}
+		}
+		if !hasCopy {
+			t.Error("expected copy action for skills/weather/SKILL.md")
+		}
+	})
+}
+
+func TestFindOpenClawConfig(t *testing.T) {
+	t.Run("finds openclaw.json", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		configPath := filepath.Join(tmpDir, "openclaw.json")
+		os.WriteFile(configPath, []byte("{}"), 0644)
+
+		found, err := findOpenClawConfig(tmpDir)
+		if err != nil {
+			t.Fatalf("findOpenClawConfig: %v", err)
+		}
+		if found != configPath {
+			t.Errorf("found %q, want %q", found, configPath)
+		}
+	})
+
+	t.Run("falls back to config.json", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		configPath := filepath.Join(tmpDir, "config.json")
+		os.WriteFile(configPath, []byte("{}"), 0644)
+
+		found, err := findOpenClawConfig(tmpDir)
+		if err != nil {
+			t.Fatalf("findOpenClawConfig: %v", err)
+		}
+		if found != configPath {
+			t.Errorf("found %q, want %q", found, configPath)
+		}
+	})
+
+	t.Run("prefers openclaw.json over config.json", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		openclawPath := filepath.Join(tmpDir, "openclaw.json")
+		os.WriteFile(openclawPath, []byte("{}"), 0644)
+		os.WriteFile(filepath.Join(tmpDir, "config.json"), []byte("{}"), 0644)
+
+		found, err := findOpenClawConfig(tmpDir)
+		if err != nil {
+			t.Fatalf("findOpenClawConfig: %v", err)
+		}
+		if found != openclawPath {
+			t.Errorf("should prefer openclaw.json, got %q", found)
+		}
+	})
+
+	t.Run("error when no config found", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		_, err := findOpenClawConfig(tmpDir)
+		if err == nil {
+			t.Fatal("expected error when no config found")
+		}
+	})
+}
+
+func TestRewriteWorkspacePath(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"default path", "~/.openclaw/workspace", "~/.picoclaw/workspace"},
+		{"custom path", "/custom/path", "/custom/path"},
+		{"empty", "", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := rewriteWorkspacePath(tt.input)
+			if got != tt.want {
+				t.Errorf("rewriteWorkspacePath(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRunDryRun(t *testing.T) {
+	openclawHome := t.TempDir()
+	picoClawHome := t.TempDir()
+
+	wsDir := filepath.Join(openclawHome, "workspace")
+	os.MkdirAll(wsDir, 0755)
+	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0644)
+	os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents"), 0644)
+
+	configData := map[string]interface{}{
+		"providers": map[string]interface{}{
+			"anthropic": map[string]interface{}{
+				"apiKey": "test-key",
+			},
+		},
+	}
+	data, _ := json.Marshal(configData)
+	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0644)
+
+	opts := Options{
+		DryRun:       true,
+		OpenClawHome: openclawHome,
+		PicoClawHome: picoClawHome,
+	}
+
+	result, err := Run(opts)
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	picoWs := filepath.Join(picoClawHome, "workspace")
+	if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
+		t.Error("dry run should not create files")
+	}
+	if _, err := os.Stat(filepath.Join(picoClawHome, "config.json")); !os.IsNotExist(err) {
+		t.Error("dry run should not create config")
+	}
+
+	_ = result
+}
+
+func TestRunFullMigration(t *testing.T) {
+	openclawHome := t.TempDir()
+	picoClawHome := t.TempDir()
+
+	wsDir := filepath.Join(openclawHome, "workspace")
+	os.MkdirAll(wsDir, 0755)
+	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul from OpenClaw"), 0644)
+	os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0644)
+	os.WriteFile(filepath.Join(wsDir, "USER.md"), []byte("# User from OpenClaw"), 0644)
+
+	memDir := filepath.Join(wsDir, "memory")
+	os.MkdirAll(memDir, 0755)
+	os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory notes"), 0644)
+
+	configData := map[string]interface{}{
+		"providers": map[string]interface{}{
+			"anthropic": map[string]interface{}{
+				"apiKey": "sk-ant-migrate-test",
+			},
+			"openrouter": map[string]interface{}{
+				"apiKey": "sk-or-migrate-test",
+			},
+		},
+		"channels": map[string]interface{}{
+			"telegram": map[string]interface{}{
+				"enabled": true,
+				"token":   "tg-migrate-test",
+			},
+		},
+	}
+	data, _ := json.Marshal(configData)
+	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0644)
+
+	opts := Options{
+		Force:        true,
+		OpenClawHome: openclawHome,
+		PicoClawHome: picoClawHome,
+	}
+
+	result, err := Run(opts)
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	picoWs := filepath.Join(picoClawHome, "workspace")
+
+	soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
+	if err != nil {
+		t.Fatalf("reading SOUL.md: %v", err)
+	}
+	if string(soulData) != "# Soul from OpenClaw" {
+		t.Errorf("SOUL.md content = %q, want %q", string(soulData), "# Soul from OpenClaw")
+	}
+
+	agentsData, err := os.ReadFile(filepath.Join(picoWs, "AGENTS.md"))
+	if err != nil {
+		t.Fatalf("reading AGENTS.md: %v", err)
+	}
+	if string(agentsData) != "# Agents from OpenClaw" {
+		t.Errorf("AGENTS.md content = %q", string(agentsData))
+	}
+
+	memData, err := os.ReadFile(filepath.Join(picoWs, "memory", "MEMORY.md"))
+	if err != nil {
+		t.Fatalf("reading memory/MEMORY.md: %v", err)
+	}
+	if string(memData) != "# Memory notes" {
+		t.Errorf("MEMORY.md content = %q", string(memData))
+	}
+
+	picoConfig, err := config.LoadConfig(filepath.Join(picoClawHome, "config.json"))
+	if err != nil {
+		t.Fatalf("loading PicoClaw config: %v", err)
+	}
+	if picoConfig.Providers.Anthropic.APIKey != "sk-ant-migrate-test" {
+		t.Errorf("Anthropic.APIKey = %q, want %q", picoConfig.Providers.Anthropic.APIKey, "sk-ant-migrate-test")
+	}
+	if picoConfig.Providers.OpenRouter.APIKey != "sk-or-migrate-test" {
+		t.Errorf("OpenRouter.APIKey = %q, want %q", picoConfig.Providers.OpenRouter.APIKey, "sk-or-migrate-test")
+	}
+	if !picoConfig.Channels.Telegram.Enabled {
+		t.Error("Telegram should be enabled")
+	}
+	if picoConfig.Channels.Telegram.Token != "tg-migrate-test" {
+		t.Errorf("Telegram.Token = %q, want %q", picoConfig.Channels.Telegram.Token, "tg-migrate-test")
+	}
+
+	if result.FilesCopied < 3 {
+		t.Errorf("expected at least 3 files copied, got %d", result.FilesCopied)
+	}
+	if !result.ConfigMigrated {
+		t.Error("config should have been migrated")
+	}
+	if len(result.Errors) > 0 {
+		t.Errorf("expected no errors, got %v", result.Errors)
+	}
+}
+
+func TestRunOpenClawNotFound(t *testing.T) {
+	opts := Options{
+		OpenClawHome: "/nonexistent/path/to/openclaw",
+		PicoClawHome: t.TempDir(),
+	}
+
+	_, err := Run(opts)
+	if err == nil {
+		t.Fatal("expected error when OpenClaw not found")
+	}
+}
+
+func TestRunMutuallyExclusiveFlags(t *testing.T) {
+	opts := Options{
+		ConfigOnly:    true,
+		WorkspaceOnly: true,
+	}
+
+	_, err := Run(opts)
+	if err == nil {
+		t.Fatal("expected error for mutually exclusive flags")
+	}
+}
+
+func TestBackupFile(t *testing.T) {
+	tmpDir := t.TempDir()
+	filePath := filepath.Join(tmpDir, "test.md")
+	os.WriteFile(filePath, []byte("original content"), 0644)
+
+	if err := backupFile(filePath); err != nil {
+		t.Fatalf("backupFile: %v", err)
+	}
+
+	bakPath := filePath + ".bak"
+	bakData, err := os.ReadFile(bakPath)
+	if err != nil {
+		t.Fatalf("reading backup: %v", err)
+	}
+	if string(bakData) != "original content" {
+		t.Errorf("backup content = %q, want %q", string(bakData), "original content")
+	}
+}
+
+func TestCopyFile(t *testing.T) {
+	tmpDir := t.TempDir()
+	srcPath := filepath.Join(tmpDir, "src.md")
+	dstPath := filepath.Join(tmpDir, "dst.md")
+
+	os.WriteFile(srcPath, []byte("file content"), 0644)
+
+	if err := copyFile(srcPath, dstPath); err != nil {
+		t.Fatalf("copyFile: %v", err)
+	}
+
+	data, err := os.ReadFile(dstPath)
+	if err != nil {
+		t.Fatalf("reading copy: %v", err)
+	}
+	if string(data) != "file content" {
+		t.Errorf("copy content = %q, want %q", string(data), "file content")
+	}
+}
+
+func TestRunConfigOnly(t *testing.T) {
+	openclawHome := t.TempDir()
+	picoClawHome := t.TempDir()
+
+	wsDir := filepath.Join(openclawHome, "workspace")
+	os.MkdirAll(wsDir, 0755)
+	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0644)
+
+	configData := map[string]interface{}{
+		"providers": map[string]interface{}{
+			"anthropic": map[string]interface{}{
+				"apiKey": "sk-config-only",
+			},
+		},
+	}
+	data, _ := json.Marshal(configData)
+	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0644)
+
+	opts := Options{
+		Force:        true,
+		ConfigOnly:   true,
+		OpenClawHome: openclawHome,
+		PicoClawHome: picoClawHome,
+	}
+
+	result, err := Run(opts)
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	if !result.ConfigMigrated {
+		t.Error("config should have been migrated")
+	}
+
+	picoWs := filepath.Join(picoClawHome, "workspace")
+	if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
+		t.Error("config-only should not copy workspace files")
+	}
+}
+
+func TestRunWorkspaceOnly(t *testing.T) {
+	openclawHome := t.TempDir()
+	picoClawHome := t.TempDir()
+
+	wsDir := filepath.Join(openclawHome, "workspace")
+	os.MkdirAll(wsDir, 0755)
+	os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0644)
+
+	configData := map[string]interface{}{
+		"providers": map[string]interface{}{
+			"anthropic": map[string]interface{}{
+				"apiKey": "sk-ws-only",
+			},
+		},
+	}
+	data, _ := json.Marshal(configData)
+	os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0644)
+
+	opts := Options{
+		Force:         true,
+		WorkspaceOnly: true,
+		OpenClawHome:  openclawHome,
+		PicoClawHome:  picoClawHome,
+	}
+
+	result, err := Run(opts)
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+
+	if result.ConfigMigrated {
+		t.Error("workspace-only should not migrate config")
+	}
+
+	picoWs := filepath.Join(picoClawHome, "workspace")
+	soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
+	if err != nil {
+		t.Fatalf("reading SOUL.md: %v", err)
+	}
+	if string(soulData) != "# Soul" {
+		t.Errorf("SOUL.md content = %q", string(soulData))
+	}
+}

pkg/migrate/workspace.go

@@ -0,0 +1,106 @@
+package migrate
+
+import (
+	"os"
+	"path/filepath"
+)
+
+var migrateableFiles = []string{
+	"AGENTS.md",
+	"SOUL.md",
+	"USER.md",
+	"TOOLS.md",
+	"HEARTBEAT.md",
+}
+
+var migrateableDirs = []string{
+	"memory",
+	"skills",
+}
+
+func PlanWorkspaceMigration(srcWorkspace, dstWorkspace string, force bool) ([]Action, error) {
+	var actions []Action
+
+	for _, filename := range migrateableFiles {
+		src := filepath.Join(srcWorkspace, filename)
+		dst := filepath.Join(dstWorkspace, filename)
+		action := planFileCopy(src, dst, force)
+		if action.Type != ActionSkip || action.Description != "" {
+			actions = append(actions, action)
+		}
+	}
+
+	for _, dirname := range migrateableDirs {
+		srcDir := filepath.Join(srcWorkspace, dirname)
+		if _, err := os.Stat(srcDir); os.IsNotExist(err) {
+			continue
+		}
+		dirActions, err := planDirCopy(srcDir, filepath.Join(dstWorkspace, dirname), force)
+		if err != nil {
+			return nil, err
+		}
+		actions = append(actions, dirActions...)
+	}
+
+	return actions, nil
+}
+
+func planFileCopy(src, dst string, force bool) Action {
+	if _, err := os.Stat(src); os.IsNotExist(err) {
+		return Action{
+			Type:        ActionSkip,
+			Source:      src,
+			Destination: dst,
+			Description: "source file not found",
+		}
+	}
+
+	_, dstExists := os.Stat(dst)
+	if dstExists == nil && !force {
+		return Action{
+			Type:        ActionBackup,
+			Source:      src,
+			Destination: dst,
+			Description: "destination exists, will backup and overwrite",
+		}
+	}
+
+	return Action{
+		Type:        ActionCopy,
+		Source:      src,
+		Destination: dst,
+		Description: "copy file",
+	}
+}
+
+func planDirCopy(srcDir, dstDir string, force bool) ([]Action, error) {
+	var actions []Action
+
+	err := filepath.Walk(srcDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		relPath, err := filepath.Rel(srcDir, path)
+		if err != nil {
+			return err
+		}
+
+		dst := filepath.Join(dstDir, relPath)
+
+		if info.IsDir() {
+			actions = append(actions, Action{
+				Type:        ActionCreateDir,
+				Destination: dst,
+				Description: "create directory",
+			})
+			return nil
+		}
+
+		action := planFileCopy(path, dst, force)
+		actions = append(actions, action)
+		return nil
+	})
+
+	return actions, err
+}