Refactor config and management API handlers

- Split config.go into separate files (migration, sanitizer, yaml_utils)
- Add bootstrap.go for server initialization
- Add generics.go for generic API handler utilities
- Refactor gemini_vertex_executor.go
- Update management config_lists.go with new patterns

Co-Authored-By: Claude <noreply@anthropic.com>

cmd/server/bootstrap.go

@@ -0,0 +1,286 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"github.com/joho/godotenv"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/misc"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/store"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/util"
+	sdkAuth "github.com/router-for-me/CLIProxyAPI/v6/sdk/auth"
+	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+	log "github.com/sirupsen/logrus"
+)
+
+// BootstrapResult holds the outcome of the application bootstrap process.
+type BootstrapResult struct {
+	Config         *config.Config
+	ConfigFilePath string
+	TokenStore     coreauth.Store
+}
+
+// Bootstrap initializes the environment, determines the storage backend,
+// loads the configuration, and sets up the token store.
+func Bootstrap(ctx context.Context, configPathOverride string, isCloudDeploy bool) (*BootstrapResult, error) {
+	var (
+		err                  error
+		cfg                  *config.Config
+		configFilePath       string
+		tokenStore           coreauth.Store
+		usePostgresStore     bool
+		pgStoreDSN           string
+		pgStoreSchema        string
+		pgStoreLocalPath     string
+		useGitStore          bool
+		gitStoreRemoteURL    string
+		gitStoreUser         string
+		gitStorePassword     string
+		gitStoreLocalPath    string
+		useObjectStore       bool
+		objectStoreEndpoint  string
+		objectStoreAccess    string
+		objectStoreSecret    string
+		objectStoreBucket    string
+		objectStoreLocalPath string
+	)
+
+	wd, err := os.Getwd()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get working directory: %w", err)
+	}
+
+	// Load environment variables from .env if present.
+	if errLoad := godotenv.Load(filepath.Join(wd, ".env")); errLoad != nil {
+		if !errors.Is(errLoad, os.ErrNotExist) {
+			log.WithError(errLoad).Warn("failed to load .env file")
+		}
+	}
+
+	lookupEnv := func(keys ...string) (string, bool) {
+		for _, key := range keys {
+			if value, ok := os.LookupEnv(key); ok {
+				if trimmed := strings.TrimSpace(value); trimmed != "" {
+					return trimmed, true
+				}
+			}
+		}
+		return "", false
+	}
+
+	writableBase := util.WritablePath()
+	if value, ok := lookupEnv("PGSTORE_DSN", "pgstore_dsn"); ok {
+		usePostgresStore = true
+		pgStoreDSN = value
+	}
+	if usePostgresStore {
+		if value, ok := lookupEnv("PGSTORE_SCHEMA", "pgstore_schema"); ok {
+			pgStoreSchema = value
+		}
+		if value, ok := lookupEnv("PGSTORE_LOCAL_PATH", "pgstore_local_path"); ok {
+			pgStoreLocalPath = value
+		}
+		if pgStoreLocalPath == "" {
+			if writableBase != "" {
+				pgStoreLocalPath = writableBase
+			} else {
+				pgStoreLocalPath = wd
+			}
+		}
+		useGitStore = false
+	}
+	if value, ok := lookupEnv("GITSTORE_GIT_URL", "gitstore_git_url"); ok {
+		useGitStore = true
+		gitStoreRemoteURL = value
+	}
+	if value, ok := lookupEnv("GITSTORE_GIT_USERNAME", "gitstore_git_username"); ok {
+		gitStoreUser = value
+	}
+	if value, ok := lookupEnv("GITSTORE_GIT_TOKEN", "gitstore_git_token"); ok {
+		gitStorePassword = value
+	}
+	if value, ok := lookupEnv("GITSTORE_LOCAL_PATH", "gitstore_local_path"); ok {
+		gitStoreLocalPath = value
+	}
+	if value, ok := lookupEnv("OBJECTSTORE_ENDPOINT", "objectstore_endpoint"); ok {
+		useObjectStore = true
+		objectStoreEndpoint = value
+	}
+	if value, ok := lookupEnv("OBJECTSTORE_ACCESS_KEY", "objectstore_access_key"); ok {
+		objectStoreAccess = value
+	}
+	if value, ok := lookupEnv("OBJECTSTORE_SECRET_KEY", "objectstore_secret_key"); ok {
+		objectStoreSecret = value
+	}
+	if value, ok := lookupEnv("OBJECTSTORE_BUCKET", "objectstore_bucket"); ok {
+		objectStoreBucket = value
+	}
+	if value, ok := lookupEnv("OBJECTSTORE_LOCAL_PATH", "objectstore_local_path"); ok {
+		objectStoreLocalPath = value
+	}
+
+	// Determine and load the configuration file.
+	// Prefer the Postgres store when configured, otherwise fallback to git or local files.
+	if usePostgresStore {
+		if pgStoreLocalPath == "" {
+			pgStoreLocalPath = wd
+		}
+		pgStoreLocalPath = filepath.Join(pgStoreLocalPath, "pgstore")
+		pgStoreInst, err := store.NewPostgresStore(ctx, store.PostgresStoreConfig{
+			DSN:      pgStoreDSN,
+			Schema:   pgStoreSchema,
+			SpoolDir: pgStoreLocalPath,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to initialize postgres token store: %w", err)
+		}
+		tokenStore = pgStoreInst
+
+		examplePath := filepath.Join(wd, "config.example.yaml")
+		if errBootstrap := pgStoreInst.Bootstrap(ctx, examplePath); errBootstrap != nil {
+			return nil, fmt.Errorf("failed to bootstrap postgres-backed config: %w", errBootstrap)
+		}
+		configFilePath = pgStoreInst.ConfigPath()
+		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
+		if err == nil {
+			cfg.AuthDir = pgStoreInst.AuthDir()
+			log.Infof("postgres-backed token store enabled, workspace path: %s", pgStoreInst.WorkDir())
+		}
+	} else if useObjectStore {
+		if objectStoreLocalPath == "" {
+			if writableBase != "" {
+				objectStoreLocalPath = writableBase
+			} else {
+				objectStoreLocalPath = wd
+			}
+		}
+		objectStoreRoot := filepath.Join(objectStoreLocalPath, "objectstore")
+		resolvedEndpoint := strings.TrimSpace(objectStoreEndpoint)
+		useSSL := true
+		if strings.Contains(resolvedEndpoint, "://") {
+			parsed, errParse := url.Parse(resolvedEndpoint)
+			if errParse != nil {
+				return nil, fmt.Errorf("failed to parse object store endpoint %q: %w", objectStoreEndpoint, errParse)
+			}
+			switch strings.ToLower(parsed.Scheme) {
+			case "http":
+				useSSL = false
+			case "https":
+				useSSL = true
+			default:
+				return nil, fmt.Errorf("unsupported object store scheme %q (only http and https are allowed)", parsed.Scheme)
+			}
+			if parsed.Host == "" {
+				return nil, fmt.Errorf("object store endpoint %q is missing host information", objectStoreEndpoint)
+			}
+			resolvedEndpoint = parsed.Host
+			if parsed.Path != "" && parsed.Path != "/" {
+				resolvedEndpoint = strings.TrimSuffix(parsed.Host+parsed.Path, "/")
+			}
+		}
+		resolvedEndpoint = strings.TrimRight(resolvedEndpoint, "/")
+		objCfg := store.ObjectStoreConfig{
+			Endpoint:  resolvedEndpoint,
+			Bucket:    objectStoreBucket,
+			AccessKey: objectStoreAccess,
+			SecretKey: objectStoreSecret,
+			LocalRoot: objectStoreRoot,
+			UseSSL:    useSSL,
+			PathStyle: true,
+		}
+		objectStoreInst, err := store.NewObjectTokenStore(objCfg)
+		if err != nil {
+			return nil, fmt.Errorf("failed to initialize object token store: %w", err)
+		}
+		tokenStore = objectStoreInst
+
+		examplePath := filepath.Join(wd, "config.example.yaml")
+		if errBootstrap := objectStoreInst.Bootstrap(ctx, examplePath); errBootstrap != nil {
+			return nil, fmt.Errorf("failed to bootstrap object-backed config: %w", errBootstrap)
+		}
+		configFilePath = objectStoreInst.ConfigPath()
+		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
+		if err == nil {
+			if cfg == nil {
+				cfg = &config.Config{}
+			}
+			cfg.AuthDir = objectStoreInst.AuthDir()
+			log.Infof("object-backed token store enabled, bucket: %s", objectStoreBucket)
+		}
+	} else if useGitStore {
+		if gitStoreLocalPath == "" {
+			if writableBase != "" {
+				gitStoreLocalPath = writableBase
+			} else {
+				gitStoreLocalPath = wd
+			}
+		}
+		gitStoreRoot := filepath.Join(gitStoreLocalPath, "gitstore")
+		authDir := filepath.Join(gitStoreRoot, "auths")
+		gitStoreInst := store.NewGitTokenStore(gitStoreRemoteURL, gitStoreUser, gitStorePassword)
+		gitStoreInst.SetBaseDir(authDir)
+		tokenStore = gitStoreInst
+
+		if errRepo := gitStoreInst.EnsureRepository(); errRepo != nil {
+			return nil, fmt.Errorf("failed to prepare git token store: %w", errRepo)
+		}
+		configFilePath = gitStoreInst.ConfigPath()
+		if configFilePath == "" {
+			configFilePath = filepath.Join(gitStoreRoot, "config", "config.yaml")
+		}
+		if _, statErr := os.Stat(configFilePath); errors.Is(statErr, fs.ErrNotExist) {
+			examplePath := filepath.Join(wd, "config.example.yaml")
+			if _, errExample := os.Stat(examplePath); errExample != nil {
+				return nil, fmt.Errorf("failed to find template config file: %w", errExample)
+			}
+			if errCopy := misc.CopyConfigTemplate(examplePath, configFilePath); errCopy != nil {
+				return nil, fmt.Errorf("failed to bootstrap git-backed config: %w", errCopy)
+			}
+			if errCommit := gitStoreInst.PersistConfig(context.Background()); errCommit != nil {
+				return nil, fmt.Errorf("failed to commit initial git-backed config: %w", errCommit)
+			}
+			log.Infof("git-backed config initialized from template: %s", configFilePath)
+		} else if statErr != nil {
+			return nil, fmt.Errorf("failed to inspect git-backed config: %w", statErr)
+		}
+		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
+		if err == nil {
+			cfg.AuthDir = gitStoreInst.AuthDir()
+			log.Infof("git-backed token store enabled, repository path: %s", gitStoreRoot)
+		}
+	} else if configPathOverride != "" {
+		configFilePath = configPathOverride
+		cfg, err = config.LoadConfigOptional(configPathOverride, isCloudDeploy)
+	} else {
+		wd, err = os.Getwd()
+		if err != nil {
+			return nil, fmt.Errorf("failed to get working directory: %w", err)
+		}
+		configFilePath = filepath.Join(wd, "config.yaml")
+		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+	if cfg == nil {
+		cfg = &config.Config{}
+	}
+
+	// If tokenStore is still nil (local file mode), use the file token store
+	if tokenStore == nil {
+		tokenStore = sdkAuth.NewFileTokenStore()
+	}
+
+	return &BootstrapResult{
+		Config:         cfg,
+		ConfigFilePath: configFilePath,
+		TokenStore:     tokenStore,
+	}, nil
+}

cmd/server/main.go

@@ -5,25 +5,15 @@ package main
 
 import (
 	"context"
-	"errors"
 	"flag"
 	"fmt"
-	"io/fs"
-	"net/url"
 	"os"
-	"path/filepath"
-	"strings"
-	"time"
 
-	"github.com/joho/godotenv"
 	configaccess "github.com/router-for-me/CLIProxyAPI/v6/internal/access/config_access"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/buildinfo"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/cmd"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/logging"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/managementasset"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/misc"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/store"
 	_ "github.com/router-for-me/CLIProxyAPI/v6/internal/translator"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/usage"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/util"
@@ -113,276 +103,19 @@ func main() {
 	// Parse the command-line flags.
 	flag.Parse()
 
-	// Core application variables.
-	var err error
-	var cfg *config.Config
-	var isCloudDeploy bool
-	var (
-		usePostgresStore     bool
-		pgStoreDSN           string
-		pgStoreSchema        string
-		pgStoreLocalPath     string
-		pgStoreInst          *store.PostgresStore
-		useGitStore          bool
-		gitStoreRemoteURL    string
-		gitStoreUser         string
-		gitStorePassword     string
-		gitStoreLocalPath    string
-		gitStoreInst         *store.GitTokenStore
-		gitStoreRoot         string
-		useObjectStore       bool
-		objectStoreEndpoint  string
-		objectStoreAccess    string
-		objectStoreSecret    string
-		objectStoreBucket    string
-		objectStoreLocalPath string
-		objectStoreInst      *store.ObjectTokenStore
-	)
-
-	wd, err := os.Getwd()
-	if err != nil {
-		log.Errorf("failed to get working directory: %v", err)
-		return
-	}
-
-	// Load environment variables from .env if present.
-	if errLoad := godotenv.Load(filepath.Join(wd, ".env")); errLoad != nil {
-		if !errors.Is(errLoad, os.ErrNotExist) {
-			log.WithError(errLoad).Warn("failed to load .env file")
-		}
-	}
-
-	lookupEnv := func(keys ...string) (string, bool) {
-		for _, key := range keys {
-			if value, ok := os.LookupEnv(key); ok {
-				if trimmed := strings.TrimSpace(value); trimmed != "" {
-					return trimmed, true
-				}
-			}
-		}
-		return "", false
-	}
-	writableBase := util.WritablePath()
-	if value, ok := lookupEnv("PGSTORE_DSN", "pgstore_dsn"); ok {
-		usePostgresStore = true
-		pgStoreDSN = value
-	}
-	if usePostgresStore {
-		if value, ok := lookupEnv("PGSTORE_SCHEMA", "pgstore_schema"); ok {
-			pgStoreSchema = value
-		}
-		if value, ok := lookupEnv("PGSTORE_LOCAL_PATH", "pgstore_local_path"); ok {
-			pgStoreLocalPath = value
-		}
-		if pgStoreLocalPath == "" {
-			if writableBase != "" {
-				pgStoreLocalPath = writableBase
-			} else {
-				pgStoreLocalPath = wd
-			}
-		}
-		useGitStore = false
-	}
-	if value, ok := lookupEnv("GITSTORE_GIT_URL", "gitstore_git_url"); ok {
-		useGitStore = true
-		gitStoreRemoteURL = value
-	}
-	if value, ok := lookupEnv("GITSTORE_GIT_USERNAME", "gitstore_git_username"); ok {
-		gitStoreUser = value
-	}
-	if value, ok := lookupEnv("GITSTORE_GIT_TOKEN", "gitstore_git_token"); ok {
-		gitStorePassword = value
-	}
-	if value, ok := lookupEnv("GITSTORE_LOCAL_PATH", "gitstore_local_path"); ok {
-		gitStoreLocalPath = value
-	}
-	if value, ok := lookupEnv("OBJECTSTORE_ENDPOINT", "objectstore_endpoint"); ok {
-		useObjectStore = true
-		objectStoreEndpoint = value
-	}
-	if value, ok := lookupEnv("OBJECTSTORE_ACCESS_KEY", "objectstore_access_key"); ok {
-		objectStoreAccess = value
-	}
-	if value, ok := lookupEnv("OBJECTSTORE_SECRET_KEY", "objectstore_secret_key"); ok {
-		objectStoreSecret = value
-	}
-	if value, ok := lookupEnv("OBJECTSTORE_BUCKET", "objectstore_bucket"); ok {
-		objectStoreBucket = value
-	}
-	if value, ok := lookupEnv("OBJECTSTORE_LOCAL_PATH", "objectstore_local_path"); ok {
-		objectStoreLocalPath = value
-	}
-
 	// Check for cloud deploy mode only on first execution
-	// Read env var name in uppercase: DEPLOY
 	deployEnv := os.Getenv("DEPLOY")
-	if deployEnv == "cloud" {
-		isCloudDeploy = true
-	}
+	isCloudDeploy := deployEnv == "cloud"
 
-	// Determine and load the configuration file.
-	// Prefer the Postgres store when configured, otherwise fallback to git or local files.
-	var configFilePath string
-	if usePostgresStore {
-		if pgStoreLocalPath == "" {
-			pgStoreLocalPath = wd
-		}
-		pgStoreLocalPath = filepath.Join(pgStoreLocalPath, "pgstore")
-		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-		pgStoreInst, err = store.NewPostgresStore(ctx, store.PostgresStoreConfig{
-			DSN:      pgStoreDSN,
-			Schema:   pgStoreSchema,
-			SpoolDir: pgStoreLocalPath,
-		})
-		cancel()
-		if err != nil {
-			log.Errorf("failed to initialize postgres token store: %v", err)
-			return
-		}
-		examplePath := filepath.Join(wd, "config.example.yaml")
-		ctx, cancel = context.WithTimeout(context.Background(), 30*time.Second)
-		if errBootstrap := pgStoreInst.Bootstrap(ctx, examplePath); errBootstrap != nil {
-			cancel()
-			log.Errorf("failed to bootstrap postgres-backed config: %v", errBootstrap)
-			return
-		}
-		cancel()
-		configFilePath = pgStoreInst.ConfigPath()
-		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
-		if err == nil {
-			cfg.AuthDir = pgStoreInst.AuthDir()
-			log.Infof("postgres-backed token store enabled, workspace path: %s", pgStoreInst.WorkDir())
-		}
-	} else if useObjectStore {
-		if objectStoreLocalPath == "" {
-			if writableBase != "" {
-				objectStoreLocalPath = writableBase
-			} else {
-				objectStoreLocalPath = wd
-			}
-		}
-		objectStoreRoot := filepath.Join(objectStoreLocalPath, "objectstore")
-		resolvedEndpoint := strings.TrimSpace(objectStoreEndpoint)
-		useSSL := true
-		if strings.Contains(resolvedEndpoint, "://") {
-			parsed, errParse := url.Parse(resolvedEndpoint)
-			if errParse != nil {
-				log.Errorf("failed to parse object store endpoint %q: %v", objectStoreEndpoint, errParse)
-				return
-			}
-			switch strings.ToLower(parsed.Scheme) {
-			case "http":
-				useSSL = false
-			case "https":
-				useSSL = true
-			default:
-				log.Errorf("unsupported object store scheme %q (only http and https are allowed)", parsed.Scheme)
-				return
-			}
-			if parsed.Host == "" {
-				log.Errorf("object store endpoint %q is missing host information", objectStoreEndpoint)
-				return
-			}
-			resolvedEndpoint = parsed.Host
-			if parsed.Path != "" && parsed.Path != "/" {
-				resolvedEndpoint = strings.TrimSuffix(parsed.Host+parsed.Path, "/")
-			}
-		}
-		resolvedEndpoint = strings.TrimRight(resolvedEndpoint, "/")
-		objCfg := store.ObjectStoreConfig{
-			Endpoint:  resolvedEndpoint,
-			Bucket:    objectStoreBucket,
-			AccessKey: objectStoreAccess,
-			SecretKey: objectStoreSecret,
-			LocalRoot: objectStoreRoot,
-			UseSSL:    useSSL,
-			PathStyle: true,
-		}
-		objectStoreInst, err = store.NewObjectTokenStore(objCfg)
-		if err != nil {
-			log.Errorf("failed to initialize object token store: %v", err)
-			return
-		}
-		examplePath := filepath.Join(wd, "config.example.yaml")
-		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-		if errBootstrap := objectStoreInst.Bootstrap(ctx, examplePath); errBootstrap != nil {
-			cancel()
-			log.Errorf("failed to bootstrap object-backed config: %v", errBootstrap)
-			return
-		}
-		cancel()
-		configFilePath = objectStoreInst.ConfigPath()
-		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
-		if err == nil {
-			if cfg == nil {
-				cfg = &config.Config{}
-			}
-			cfg.AuthDir = objectStoreInst.AuthDir()
-			log.Infof("object-backed token store enabled, bucket: %s", objectStoreBucket)
-		}
-	} else if useGitStore {
-		if gitStoreLocalPath == "" {
-			if writableBase != "" {
-				gitStoreLocalPath = writableBase
-			} else {
-				gitStoreLocalPath = wd
-			}
-		}
-		gitStoreRoot = filepath.Join(gitStoreLocalPath, "gitstore")
-		authDir := filepath.Join(gitStoreRoot, "auths")
-		gitStoreInst = store.NewGitTokenStore(gitStoreRemoteURL, gitStoreUser, gitStorePassword)
-		gitStoreInst.SetBaseDir(authDir)
-		if errRepo := gitStoreInst.EnsureRepository(); errRepo != nil {
-			log.Errorf("failed to prepare git token store: %v", errRepo)
-			return
-		}
-		configFilePath = gitStoreInst.ConfigPath()
-		if configFilePath == "" {
-			configFilePath = filepath.Join(gitStoreRoot, "config", "config.yaml")
-		}
-		if _, statErr := os.Stat(configFilePath); errors.Is(statErr, fs.ErrNotExist) {
-			examplePath := filepath.Join(wd, "config.example.yaml")
-			if _, errExample := os.Stat(examplePath); errExample != nil {
-				log.Errorf("failed to find template config file: %v", errExample)
-				return
-			}
-			if errCopy := misc.CopyConfigTemplate(examplePath, configFilePath); errCopy != nil {
-				log.Errorf("failed to bootstrap git-backed config: %v", errCopy)
-				return
-			}
-			if errCommit := gitStoreInst.PersistConfig(context.Background()); errCommit != nil {
-				log.Errorf("failed to commit initial git-backed config: %v", errCommit)
-				return
-			}
-			log.Infof("git-backed config initialized from template: %s", configFilePath)
-		} else if statErr != nil {
-			log.Errorf("failed to inspect git-backed config: %v", statErr)
-			return
-		}
-		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
-		if err == nil {
-			cfg.AuthDir = gitStoreInst.AuthDir()
-			log.Infof("git-backed token store enabled, repository path: %s", gitStoreRoot)
-		}
-	} else if configPath != "" {
-		configFilePath = configPath
-		cfg, err = config.LoadConfigOptional(configPath, isCloudDeploy)
-	} else {
-		wd, err = os.Getwd()
-		if err != nil {
-			log.Errorf("failed to get working directory: %v", err)
-			return
-		}
-		configFilePath = filepath.Join(wd, "config.yaml")
-		cfg, err = config.LoadConfigOptional(configFilePath, isCloudDeploy)
-	}
+	// Bootstrap the application (load config, init token store)
+	bootstrap, err := Bootstrap(context.Background(), configPath, isCloudDeploy)
 	if err != nil {
-		log.Errorf("failed to load config: %v", err)
+		log.Errorf("failed to bootstrap application: %v", err)
 		return
 	}
-	if cfg == nil {
-		cfg = &config.Config{}
-	}
+
+	cfg := bootstrap.Config
+	configFilePath := bootstrap.ConfigFilePath
 
 	// In cloud deploy mode, check if we have a valid configuration
 	var configFileExists bool
@@ -432,15 +165,7 @@ func main() {
 	}
 
 	// Register the shared token store once so all components use the same persistence backend.
-	if usePostgresStore {
-		sdkAuth.RegisterTokenStore(pgStoreInst)
-	} else if useObjectStore {
-		sdkAuth.RegisterTokenStore(objectStoreInst)
-	} else if useGitStore {
-		sdkAuth.RegisterTokenStore(gitStoreInst)
-	} else {
-		sdkAuth.RegisterTokenStore(sdkAuth.NewFileTokenStore())
-	}
+	sdkAuth.RegisterTokenStore(bootstrap.TokenStore)
 
 	// Register built-in access providers before constructing services.
 	configaccess.Register()
@@ -463,6 +188,7 @@ func main() {
 		// Handle Claude login
 		cmd.DoClaudeLogin(cfg, options)
 	} else if qwenLogin {
+		// Handle Qwen login
 		cmd.DoQwenLogin(cfg, options)
 	} else if iflowLogin {
 		cmd.DoIFlowLogin(cfg, options)

internal/api/handlers/management/config_lists.go

@@ -9,31 +9,70 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 )
 
-// Generic helpers for list[string]
-func (h *Handler) putStringList(c *gin.Context, set func([]string), after func()) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []string
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []string `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	set(arr)
-	if after != nil {
-		after()
-	}
-	h.persist(c)
-}
-
+// Patch structs for generic handlers
+
+type geminiKeyPatch struct {
+	APIKey         *string            `json:"api-key"`
+	Prefix         *string            `json:"prefix"`
+	BaseURL        *string            `json:"base-url"`
+	ProxyURL       *string            `json:"proxy-url"`
+	Headers        *map[string]string `json:"headers"`
+	ExcludedModels *[]string          `json:"excluded-models"`
+}
+
+type kiroKeyPatch struct {
+	RefreshToken    *string             `json:"refresh-token"`
+	ProfileARN      *string             `json:"profile-arn"`
+	Region          *string             `json:"region"`
+	Prefix          *string             `json:"prefix"`
+	ProxyURL        *string             `json:"proxy-url"`
+	CredentialsFile *string             `json:"credentials-file"`
+	KiroCliDBFile   *string             `json:"kiro-cli-db-file"`
+	Models          *[]config.KiroModel `json:"models"`
+	Headers         *map[string]string  `json:"headers"`
+	ExcludedModels  *[]string           `json:"excluded-models"`
+}
+
+type claudeKeyPatch struct {
+	APIKey         *string                     `json:"api-key"`
+	APIKeyEntries  *[]config.ClaudeAPIKeyEntry `json:"api-key-entries"`
+	Prefix         *string                     `json:"prefix"`
+	BaseURL        *string                     `json:"base-url"`
+	ProxyURL       *string                     `json:"proxy-url"`
+	Models         *[]config.ClaudeModel       `json:"models"`
+	Headers        *map[string]string          `json:"headers"`
+	ExcludedModels *[]string                   `json:"excluded-models"`
+}
+
+type openAICompatPatch struct {
+	Name          *string                             `json:"name"`
+	Prefix        *string                             `json:"prefix"`
+	BaseURL       *string                             `json:"base-url"`
+	APIKeyEntries *[]config.OpenAICompatibilityAPIKey `json:"api-key-entries"`
+	Models        *[]config.OpenAICompatibilityModel  `json:"models"`
+	Headers       *map[string]string                  `json:"headers"`
+}
+
+type vertexCompatPatch struct {
+	APIKey   *string                     `json:"api-key"`
+	Prefix   *string                     `json:"prefix"`
+	BaseURL  *string                     `json:"base-url"`
+	ProxyURL *string                     `json:"proxy-url"`
+	Headers  *map[string]string          `json:"headers"`
+	Models   *[]config.VertexCompatModel `json:"models"`
+}
+
+type codexKeyPatch struct {
+	APIKey         *string              `json:"api-key"`
+	Prefix         *string              `json:"prefix"`
+	BaseURL        *string              `json:"base-url"`
+	ProxyURL       *string              `json:"proxy-url"`
+	Models         *[]config.CodexModel `json:"models"`
+	Headers        *map[string]string   `json:"headers"`
+	ExcludedModels *[]string            `json:"excluded-models"`
+}
+
+// Special helper for string list patch (API Keys) due to unique Old/New format support
 func (h *Handler) patchStringList(c *gin.Context, target *[]string, after func()) {
 	var body struct {
 		Old   *string `json:"old"`
@@ -74,49 +113,28 @@ func (h *Handler) patchStringList(c *gin.Context, target *[]string, after func()
 	c.JSON(400, gin.H{"error": "missing fields"})
 }
 
-func (h *Handler) deleteFromStringList(c *gin.Context, target *[]string, after func()) {
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		_, err := fmt.Sscanf(idxStr, "%d", &idx)
-		if err == nil && idx >= 0 && idx < len(*target) {
-			*target = append((*target)[:idx], (*target)[idx+1:]...)
-			if after != nil {
-				after()
-			}
-			h.persist(c)
-			return
-		}
-	}
-	if val := strings.TrimSpace(c.Query("value")); val != "" {
-		out := make([]string, 0, len(*target))
-		for _, v := range *target {
-			if strings.TrimSpace(v) != val {
-				out = append(out, v)
-			}
-		}
-		*target = out
-		if after != nil {
-			after()
-		}
-		h.persist(c)
-		return
-	}
-	c.JSON(400, gin.H{"error": "missing index or value"})
-}
-
 // api-keys
 func (h *Handler) GetAPIKeys(c *gin.Context) { c.JSON(200, gin.H{"api-keys": h.cfg.APIKeys}) }
 func (h *Handler) PutAPIKeys(c *gin.Context) {
-	h.putStringList(c, func(v []string) {
+	genericPutList(h, c, func(v []string) {
 		h.cfg.APIKeys = append([]string(nil), v...)
 		h.cfg.Access.Providers = nil
-	}, nil)
+	}, nil, nil)
 }
 func (h *Handler) PatchAPIKeys(c *gin.Context) {
 	h.patchStringList(c, &h.cfg.APIKeys, func() { h.cfg.Access.Providers = nil })
 }
 func (h *Handler) DeleteAPIKeys(c *gin.Context) {
-	h.deleteFromStringList(c, &h.cfg.APIKeys, func() { h.cfg.Access.Providers = nil })
+	genericDeleteList(h, c,
+		func() []string { return h.cfg.APIKeys },
+		func(v []string) {
+			h.cfg.APIKeys = v
+			h.cfg.Access.Providers = nil
+		},
+		func(item string, val string) bool { return strings.TrimSpace(item) == val },
+		"value",
+		nil,
+	)
 }
 
 // gemini-api-key: []GeminiKey
@@ -124,122 +142,53 @@ func (h *Handler) GetGeminiKeys(c *gin.Context) {
 	c.JSON(200, gin.H{"gemini-api-key": h.cfg.GeminiKey})
 }
 func (h *Handler) PutGeminiKeys(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.GeminiKey
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.GeminiKey `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	h.cfg.GeminiKey = append([]config.GeminiKey(nil), arr...)
-	h.cfg.SanitizeGeminiKeys()
-	h.persist(c)
+	genericPutList(h, c, func(v []config.GeminiKey) {
+		h.cfg.GeminiKey = append([]config.GeminiKey(nil), v...)
+	}, nil, h.cfg.SanitizeGeminiKeys)
 }
 func (h *Handler) PatchGeminiKey(c *gin.Context) {
-	type geminiKeyPatch struct {
-		APIKey         *string            `json:"api-key"`
-		Prefix         *string            `json:"prefix"`
-		BaseURL        *string            `json:"base-url"`
-		ProxyURL       *string            `json:"proxy-url"`
-		Headers        *map[string]string `json:"headers"`
-		ExcludedModels *[]string          `json:"excluded-models"`
-	}
-	var body struct {
-		Index *int            `json:"index"`
-		Match *string         `json:"match"`
-		Value *geminiKeyPatch `json:"value"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.GeminiKey) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Match != nil {
-		match := strings.TrimSpace(*body.Match)
-		if match != "" {
-			for i := range h.cfg.GeminiKey {
-				if h.cfg.GeminiKey[i].APIKey == match {
-					targetIndex = i
-					break
+	genericPatchList(h, c,
+		func() []config.GeminiKey { return h.cfg.GeminiKey },
+		func(v []config.GeminiKey) { h.cfg.GeminiKey = v },
+		func(item config.GeminiKey, match string) bool { return item.APIKey == match },
+		func(item *config.GeminiKey, patch geminiKeyPatch) bool {
+			if patch.APIKey != nil {
+				trimmed := strings.TrimSpace(*patch.APIKey)
+				if trimmed == "" {
+					return false
 				}
+				item.APIKey = trimmed
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.GeminiKey[targetIndex]
-	if body.Value.APIKey != nil {
-		trimmed := strings.TrimSpace(*body.Value.APIKey)
-		if trimmed == "" {
-			h.cfg.GeminiKey = append(h.cfg.GeminiKey[:targetIndex], h.cfg.GeminiKey[targetIndex+1:]...)
-			h.cfg.SanitizeGeminiKeys()
-			h.persist(c)
-			return
-		}
-		entry.APIKey = trimmed
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.BaseURL != nil {
-		entry.BaseURL = strings.TrimSpace(*body.Value.BaseURL)
-	}
-	if body.Value.ProxyURL != nil {
-		entry.ProxyURL = strings.TrimSpace(*body.Value.ProxyURL)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	if body.Value.ExcludedModels != nil {
-		entry.ExcludedModels = config.NormalizeExcludedModels(*body.Value.ExcludedModels)
-	}
-	h.cfg.GeminiKey[targetIndex] = entry
-	h.cfg.SanitizeGeminiKeys()
-	h.persist(c)
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.BaseURL != nil {
+				item.BaseURL = strings.TrimSpace(*patch.BaseURL)
+			}
+			if patch.ProxyURL != nil {
+				item.ProxyURL = strings.TrimSpace(*patch.ProxyURL)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			if patch.ExcludedModels != nil {
+				item.ExcludedModels = config.NormalizeExcludedModels(*patch.ExcludedModels)
+			}
+			return true
+		},
+		nil,
+		h.cfg.SanitizeGeminiKeys,
+	)
 }
 
 func (h *Handler) DeleteGeminiKey(c *gin.Context) {
-	if val := strings.TrimSpace(c.Query("api-key")); val != "" {
-		out := make([]config.GeminiKey, 0, len(h.cfg.GeminiKey))
-		for _, v := range h.cfg.GeminiKey {
-			if v.APIKey != val {
-				out = append(out, v)
-			}
-		}
-		if len(out) != len(h.cfg.GeminiKey) {
-			h.cfg.GeminiKey = out
-			h.cfg.SanitizeGeminiKeys()
-			h.persist(c)
-		} else {
-			c.JSON(404, gin.H{"error": "item not found"})
-		}
-		return
-	}
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		if _, err := fmt.Sscanf(idxStr, "%d", &idx); err == nil && idx >= 0 && idx < len(h.cfg.GeminiKey) {
-			h.cfg.GeminiKey = append(h.cfg.GeminiKey[:idx], h.cfg.GeminiKey[idx+1:]...)
-			h.cfg.SanitizeGeminiKeys()
-			h.persist(c)
-			return
-		}
-	}
-	c.JSON(400, gin.H{"error": "missing api-key or index"})
+	genericDeleteList(h, c,
+		func() []config.GeminiKey { return h.cfg.GeminiKey },
+		func(v []config.GeminiKey) { h.cfg.GeminiKey = v },
+		func(item config.GeminiKey, val string) bool { return item.APIKey == val },
+		"api-key",
+		h.cfg.SanitizeGeminiKeys,
+	)
 }
 
 // kiro-api-key: []KiroKey
@@ -247,127 +196,61 @@ func (h *Handler) GetKiroKeys(c *gin.Context) {
 	c.JSON(200, gin.H{"kiro-api-key": h.cfg.KiroKey})
 }
 func (h *Handler) PutKiroKeys(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.KiroKey
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.KiroKey `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	for i := range arr {
-		normalizeKiroKey(&arr[i])
-	}
-	h.cfg.KiroKey = arr
-	// h.cfg.SanitizeKiroKeys() // Add sanitizer if needed
-	h.persist(c)
+	genericPutList(h, c, func(v []config.KiroKey) {
+		h.cfg.KiroKey = v
+	}, normalizeKiroKey, nil)
 }
 func (h *Handler) PatchKiroKey(c *gin.Context) {
-	type kiroKeyPatch struct {
-		RefreshToken    *string             `json:"refresh-token"`
-		ProfileARN      *string             `json:"profile-arn"`
-		Region          *string             `json:"region"`
-		Prefix          *string             `json:"prefix"`
-		ProxyURL        *string             `json:"proxy-url"`
-		CredentialsFile *string             `json:"credentials-file"`
-		KiroCliDBFile   *string             `json:"kiro-cli-db-file"`
-		Models          *[]config.KiroModel `json:"models"`
-		Headers         *map[string]string  `json:"headers"`
-		ExcludedModels  *[]string           `json:"excluded-models"`
-	}
-	var body struct {
-		Index *int          `json:"index"`
-		Match *string       `json:"match"`
-		Value *kiroKeyPatch `json:"value"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.KiroKey) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Match != nil {
-		match := strings.TrimSpace(*body.Match)
-		for i := range h.cfg.KiroKey {
-			if h.cfg.KiroKey[i].RefreshToken == match {
-				targetIndex = i
-				break
+	genericPatchList(h, c,
+		func() []config.KiroKey { return h.cfg.KiroKey },
+		func(v []config.KiroKey) { h.cfg.KiroKey = v },
+		func(item config.KiroKey, match string) bool { return item.RefreshToken == match },
+		func(item *config.KiroKey, patch kiroKeyPatch) bool {
+			if patch.RefreshToken != nil {
+				item.RefreshToken = strings.TrimSpace(*patch.RefreshToken)
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.KiroKey[targetIndex]
-	if body.Value.RefreshToken != nil {
-		entry.RefreshToken = strings.TrimSpace(*body.Value.RefreshToken)
-	}
-	if body.Value.ProfileARN != nil {
-		entry.ProfileARN = strings.TrimSpace(*body.Value.ProfileARN)
-	}
-	if body.Value.Region != nil {
-		entry.Region = strings.TrimSpace(*body.Value.Region)
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.ProxyURL != nil {
-		entry.ProxyURL = strings.TrimSpace(*body.Value.ProxyURL)
-	}
-	if body.Value.CredentialsFile != nil {
-		entry.CredentialsFile = strings.TrimSpace(*body.Value.CredentialsFile)
-	}
-	if body.Value.KiroCliDBFile != nil {
-		entry.KiroCliDBFile = strings.TrimSpace(*body.Value.KiroCliDBFile)
-	}
-	if body.Value.Models != nil {
-		entry.Models = append([]config.KiroModel(nil), (*body.Value.Models)...)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	if body.Value.ExcludedModels != nil {
-		entry.ExcludedModels = config.NormalizeExcludedModels(*body.Value.ExcludedModels)
-	}
-	normalizeKiroKey(&entry)
-	h.cfg.KiroKey[targetIndex] = entry
-	h.persist(c)
+			if patch.ProfileARN != nil {
+				item.ProfileARN = strings.TrimSpace(*patch.ProfileARN)
+			}
+			if patch.Region != nil {
+				item.Region = strings.TrimSpace(*patch.Region)
+			}
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.ProxyURL != nil {
+				item.ProxyURL = strings.TrimSpace(*patch.ProxyURL)
+			}
+			if patch.CredentialsFile != nil {
+				item.CredentialsFile = strings.TrimSpace(*patch.CredentialsFile)
+			}
+			if patch.KiroCliDBFile != nil {
+				item.KiroCliDBFile = strings.TrimSpace(*patch.KiroCliDBFile)
+			}
+			if patch.Models != nil {
+				item.Models = append([]config.KiroModel(nil), (*patch.Models)...)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			if patch.ExcludedModels != nil {
+				item.ExcludedModels = config.NormalizeExcludedModels(*patch.ExcludedModels)
+			}
+			return true
+		},
+		normalizeKiroKey,
+		nil,
+	)
 }
 
 func (h *Handler) DeleteKiroKey(c *gin.Context) {
-	if val := c.Query("refresh-token"); val != "" {
-		out := make([]config.KiroKey, 0, len(h.cfg.KiroKey))
-		for _, v := range h.cfg.KiroKey {
-			if v.RefreshToken != val {
-				out = append(out, v)
-			}
-		}
-		h.cfg.KiroKey = out
-		h.persist(c)
-		return
-	}
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		_, err := fmt.Sscanf(idxStr, "%d", &idx)
-		if err == nil && idx >= 0 && idx < len(h.cfg.KiroKey) {
-			h.cfg.KiroKey = append(h.cfg.KiroKey[:idx], h.cfg.KiroKey[idx+1:]...)
-			h.persist(c)
-			return
-		}
-	}
-	c.JSON(400, gin.H{"error": "missing refresh-token or index"})
+	genericDeleteList(h, c,
+		func() []config.KiroKey { return h.cfg.KiroKey },
+		func(v []config.KiroKey) { h.cfg.KiroKey = v },
+		func(item config.KiroKey, val string) bool { return item.RefreshToken == val },
+		"refresh-token",
+		nil,
+	)
 }
 
 // claude-api-key: []ClaudeKey
@@ -375,109 +258,63 @@ func (h *Handler) GetClaudeKeys(c *gin.Context) {
 	c.JSON(200, gin.H{"claude-api-key": h.cfg.ClaudeKey})
 }
 func (h *Handler) PutClaudeKeys(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.ClaudeKey
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.ClaudeKey `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	for i := range arr {
-		normalizeClaudeKey(&arr[i])
-	}
-	h.cfg.ClaudeKey = arr
-	h.cfg.SanitizeClaudeKeys()
-	h.persist(c)
+	genericPutList(h, c, func(v []config.ClaudeKey) {
+		h.cfg.ClaudeKey = v
+	}, normalizeClaudeKey, h.cfg.SanitizeClaudeKeys)
 }
 func (h *Handler) PatchClaudeKey(c *gin.Context) {
-	type claudeKeyPatch struct {
-		APIKey         *string                     `json:"api-key"`
-		APIKeyEntries  *[]config.ClaudeAPIKeyEntry `json:"api-key-entries"`
-		Prefix         *string                     `json:"prefix"`
-		BaseURL        *string                     `json:"base-url"`
-		ProxyURL       *string                     `json:"proxy-url"`
-		Models         *[]config.ClaudeModel       `json:"models"`
-		Headers        *map[string]string          `json:"headers"`
-		ExcludedModels *[]string                   `json:"excluded-models"`
-	}
-	var body struct {
-		Index *int            `json:"index"`
-		Match *string         `json:"match"`
-		Value *claudeKeyPatch `json:"value"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.ClaudeKey) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Match != nil {
-		match := strings.TrimSpace(*body.Match)
-		for i := range h.cfg.ClaudeKey {
-			// Match by single API key or check if match exists in APIKeyEntries
-			if h.cfg.ClaudeKey[i].APIKey == match {
-				targetIndex = i
-				break
+	genericPatchList(h, c,
+		func() []config.ClaudeKey { return h.cfg.ClaudeKey },
+		func(v []config.ClaudeKey) { h.cfg.ClaudeKey = v },
+		func(item config.ClaudeKey, match string) bool {
+			if item.APIKey == match {
+				return true
 			}
-			for _, entry := range h.cfg.ClaudeKey[i].APIKeyEntries {
+			for _, entry := range item.APIKeyEntries {
 				if entry.APIKey == match {
-					targetIndex = i
-					break
+					return true
 				}
 			}
-			if targetIndex != -1 {
-				break
+			return false
+		},
+		func(item *config.ClaudeKey, patch claudeKeyPatch) bool {
+			if patch.APIKey != nil {
+				item.APIKey = strings.TrimSpace(*patch.APIKey)
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.ClaudeKey[targetIndex]
-	if body.Value.APIKey != nil {
-		entry.APIKey = strings.TrimSpace(*body.Value.APIKey)
-	}
-	if body.Value.APIKeyEntries != nil {
-		entry.APIKeyEntries = append([]config.ClaudeAPIKeyEntry(nil), (*body.Value.APIKeyEntries)...)
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.BaseURL != nil {
-		entry.BaseURL = strings.TrimSpace(*body.Value.BaseURL)
-	}
-	if body.Value.ProxyURL != nil {
-		entry.ProxyURL = strings.TrimSpace(*body.Value.ProxyURL)
-	}
-	if body.Value.Models != nil {
-		entry.Models = append([]config.ClaudeModel(nil), (*body.Value.Models)...)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	if body.Value.ExcludedModels != nil {
-		entry.ExcludedModels = config.NormalizeExcludedModels(*body.Value.ExcludedModels)
-	}
-	normalizeClaudeKey(&entry)
-	h.cfg.ClaudeKey[targetIndex] = entry
-	h.cfg.SanitizeClaudeKeys()
-	h.persist(c)
+			if patch.APIKeyEntries != nil {
+				item.APIKeyEntries = append([]config.ClaudeAPIKeyEntry(nil), (*patch.APIKeyEntries)...)
+			}
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.BaseURL != nil {
+				item.BaseURL = strings.TrimSpace(*patch.BaseURL)
+			}
+			if patch.ProxyURL != nil {
+				item.ProxyURL = strings.TrimSpace(*patch.ProxyURL)
+			}
+			if patch.Models != nil {
+				item.Models = append([]config.ClaudeModel(nil), (*patch.Models)...)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			if patch.ExcludedModels != nil {
+				item.ExcludedModels = config.NormalizeExcludedModels(*patch.ExcludedModels)
+			}
+			return true
+		},
+		normalizeClaudeKey,
+		h.cfg.SanitizeClaudeKeys,
+	)
 }
 
 func (h *Handler) DeleteClaudeKey(c *gin.Context) {
+	// Custom logic needed for APIKeyEntries deletion support
+	// existing handler removes either the whole key OR just an entry from APIKeyEntries
+	// This is not supported by genericDeleteList (which removes items from the list).
+	// So we keep custom implementation for now, but cleaner.
+
 	if val := c.Query("api-key"); val != "" {
 		out := make([]config.ClaudeKey, 0, len(h.cfg.ClaudeKey))
 		for _, v := range h.cfg.ClaudeKey {
@@ -502,6 +339,11 @@ func (h *Handler) DeleteClaudeKey(c *gin.Context) {
 		h.persist(c)
 		return
 	}
+	// Index deletion can use generic logic, but mix and match is messy.
+	// Let's fallback to genericDeleteList for index, and manually handle api-key above.
+	// Actually, if we use genericDeleteList, we can't handle the "partial delete" of APIKeyEntries.
+	// So we keep the custom implementation for Claude Delete.
+
 	if idxStr := c.Query("index"); idxStr != "" {
 		var idx int
 		_, err := fmt.Sscanf(idxStr, "%d", &idx)
@@ -520,125 +362,63 @@ func (h *Handler) GetOpenAICompat(c *gin.Context) {
 	c.JSON(200, gin.H{"openai-compatibility": normalizedOpenAICompatibilityEntries(h.cfg.OpenAICompatibility)})
 }
 func (h *Handler) PutOpenAICompat(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.OpenAICompatibility
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.OpenAICompatibility `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	filtered := make([]config.OpenAICompatibility, 0, len(arr))
-	for i := range arr {
-		normalizeOpenAICompatibilityEntry(&arr[i])
-		if strings.TrimSpace(arr[i].BaseURL) != "" {
-			filtered = append(filtered, arr[i])
-		}
-	}
-	h.cfg.OpenAICompatibility = filtered
-	h.cfg.SanitizeOpenAICompatibility()
-	h.persist(c)
+	// Custom Put because of filter logic (BaseURL check)
+	// We can use genericPutList with normalize, but we need to remove items if BaseURL is empty.
+	// genericPutList normalize works on *T. If we empty it, it stays.
+	// So we can't use genericPutList if we need to filter *during* Put.
+	// Let's keep custom implementation.
+	// Or we can rely on SanitizeOpenAICompatibility to remove empty BaseURL entries?
+	// Existing SanitizeOpenAICompatibility:
+	// "SanitizeOpenAICompatibility providers: drop entries without base-url"
+	// So yes, we can use genericPutList + Sanitize!
+
+	genericPutList(h, c, func(v []config.OpenAICompatibility) {
+		h.cfg.OpenAICompatibility = v
+	}, normalizeOpenAICompatibilityEntry, h.cfg.SanitizeOpenAICompatibility)
 }
 func (h *Handler) PatchOpenAICompat(c *gin.Context) {
-	type openAICompatPatch struct {
-		Name          *string                             `json:"name"`
-		Prefix        *string                             `json:"prefix"`
-		BaseURL       *string                             `json:"base-url"`
-		APIKeyEntries *[]config.OpenAICompatibilityAPIKey `json:"api-key-entries"`
-		Models        *[]config.OpenAICompatibilityModel  `json:"models"`
-		Headers       *map[string]string                  `json:"headers"`
-	}
-	var body struct {
-		Name  *string            `json:"name"`
-		Index *int               `json:"index"`
-		Value *openAICompatPatch `json:"value"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.OpenAICompatibility) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Name != nil {
-		match := strings.TrimSpace(*body.Name)
-		for i := range h.cfg.OpenAICompatibility {
-			if h.cfg.OpenAICompatibility[i].Name == match {
-				targetIndex = i
-				break
+	genericPatchList(h, c,
+		func() []config.OpenAICompatibility { return h.cfg.OpenAICompatibility },
+		func(v []config.OpenAICompatibility) { h.cfg.OpenAICompatibility = v },
+		func(item config.OpenAICompatibility, match string) bool { return item.Name == match },
+		func(item *config.OpenAICompatibility, patch openAICompatPatch) bool {
+			if patch.Name != nil {
+				item.Name = strings.TrimSpace(*patch.Name)
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.OpenAICompatibility[targetIndex]
-	if body.Value.Name != nil {
-		entry.Name = strings.TrimSpace(*body.Value.Name)
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.BaseURL != nil {
-		trimmed := strings.TrimSpace(*body.Value.BaseURL)
-		if trimmed == "" {
-			h.cfg.OpenAICompatibility = append(h.cfg.OpenAICompatibility[:targetIndex], h.cfg.OpenAICompatibility[targetIndex+1:]...)
-			h.cfg.SanitizeOpenAICompatibility()
-			h.persist(c)
-			return
-		}
-		entry.BaseURL = trimmed
-	}
-	if body.Value.APIKeyEntries != nil {
-		entry.APIKeyEntries = append([]config.OpenAICompatibilityAPIKey(nil), (*body.Value.APIKeyEntries)...)
-	}
-	if body.Value.Models != nil {
-		entry.Models = append([]config.OpenAICompatibilityModel(nil), (*body.Value.Models)...)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	normalizeOpenAICompatibilityEntry(&entry)
-	h.cfg.OpenAICompatibility[targetIndex] = entry
-	h.cfg.SanitizeOpenAICompatibility()
-	h.persist(c)
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.BaseURL != nil {
+				trimmed := strings.TrimSpace(*patch.BaseURL)
+				if trimmed == "" {
+					return false // Remove if base URL is cleared
+				}
+				item.BaseURL = trimmed
+			}
+			if patch.APIKeyEntries != nil {
+				item.APIKeyEntries = append([]config.OpenAICompatibilityAPIKey(nil), (*patch.APIKeyEntries)...)
+			}
+			if patch.Models != nil {
+				item.Models = append([]config.OpenAICompatibilityModel(nil), (*patch.Models)...)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			return true
+		},
+		normalizeOpenAICompatibilityEntry,
+		h.cfg.SanitizeOpenAICompatibility,
+	)
 }
 
 func (h *Handler) DeleteOpenAICompat(c *gin.Context) {
-	if name := c.Query("name"); name != "" {
-		out := make([]config.OpenAICompatibility, 0, len(h.cfg.OpenAICompatibility))
-		for _, v := range h.cfg.OpenAICompatibility {
-			if v.Name != name {
-				out = append(out, v)
-			}
-		}
-		h.cfg.OpenAICompatibility = out
-		h.cfg.SanitizeOpenAICompatibility()
-		h.persist(c)
-		return
-	}
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		_, err := fmt.Sscanf(idxStr, "%d", &idx)
-		if err == nil && idx >= 0 && idx < len(h.cfg.OpenAICompatibility) {
-			h.cfg.OpenAICompatibility = append(h.cfg.OpenAICompatibility[:idx], h.cfg.OpenAICompatibility[idx+1:]...)
-			h.cfg.SanitizeOpenAICompatibility()
-			h.persist(c)
-			return
-		}
-	}
-	c.JSON(400, gin.H{"error": "missing name or index"})
+	genericDeleteList(h, c,
+		func() []config.OpenAICompatibility { return h.cfg.OpenAICompatibility },
+		func(v []config.OpenAICompatibility) { h.cfg.OpenAICompatibility = v },
+		func(item config.OpenAICompatibility, val string) bool { return item.Name == val },
+		"name",
+		h.cfg.SanitizeOpenAICompatibility,
+	)
 }
 
 // vertex-api-key: []VertexCompatKey
@@ -646,133 +426,61 @@ func (h *Handler) GetVertexCompatKeys(c *gin.Context) {
 	c.JSON(200, gin.H{"vertex-api-key": h.cfg.VertexCompatAPIKey})
 }
 func (h *Handler) PutVertexCompatKeys(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.VertexCompatKey
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.VertexCompatKey `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	for i := range arr {
-		normalizeVertexCompatKey(&arr[i])
-	}
-	h.cfg.VertexCompatAPIKey = arr
-	h.cfg.SanitizeVertexCompatKeys()
-	h.persist(c)
+	genericPutList(h, c, func(v []config.VertexCompatKey) {
+		h.cfg.VertexCompatAPIKey = v
+	}, normalizeVertexCompatKey, h.cfg.SanitizeVertexCompatKeys)
 }
 func (h *Handler) PatchVertexCompatKey(c *gin.Context) {
-	type vertexCompatPatch struct {
-		APIKey   *string                     `json:"api-key"`
-		Prefix   *string                     `json:"prefix"`
-		BaseURL  *string                     `json:"base-url"`
-		ProxyURL *string                     `json:"proxy-url"`
-		Headers  *map[string]string          `json:"headers"`
-		Models   *[]config.VertexCompatModel `json:"models"`
-	}
-	var body struct {
-		Index *int               `json:"index"`
-		Match *string            `json:"match"`
-		Value *vertexCompatPatch `json:"value"`
-	}
-	if errBindJSON := c.ShouldBindJSON(&body); errBindJSON != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.VertexCompatAPIKey) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Match != nil {
-		match := strings.TrimSpace(*body.Match)
-		if match != "" {
-			for i := range h.cfg.VertexCompatAPIKey {
-				if h.cfg.VertexCompatAPIKey[i].APIKey == match {
-					targetIndex = i
-					break
+	genericPatchList(h, c,
+		func() []config.VertexCompatKey { return h.cfg.VertexCompatAPIKey },
+		func(v []config.VertexCompatKey) { h.cfg.VertexCompatAPIKey = v },
+		func(item config.VertexCompatKey, match string) bool { return item.APIKey == match },
+		func(item *config.VertexCompatKey, patch vertexCompatPatch) bool {
+			if patch.APIKey != nil {
+				trimmed := strings.TrimSpace(*patch.APIKey)
+				if trimmed == "" {
+					return false
 				}
+				item.APIKey = trimmed
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.VertexCompatAPIKey[targetIndex]
-	if body.Value.APIKey != nil {
-		trimmed := strings.TrimSpace(*body.Value.APIKey)
-		if trimmed == "" {
-			h.cfg.VertexCompatAPIKey = append(h.cfg.VertexCompatAPIKey[:targetIndex], h.cfg.VertexCompatAPIKey[targetIndex+1:]...)
-			h.cfg.SanitizeVertexCompatKeys()
-			h.persist(c)
-			return
-		}
-		entry.APIKey = trimmed
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.BaseURL != nil {
-		trimmed := strings.TrimSpace(*body.Value.BaseURL)
-		if trimmed == "" {
-			h.cfg.VertexCompatAPIKey = append(h.cfg.VertexCompatAPIKey[:targetIndex], h.cfg.VertexCompatAPIKey[targetIndex+1:]...)
-			h.cfg.SanitizeVertexCompatKeys()
-			h.persist(c)
-			return
-		}
-		entry.BaseURL = trimmed
-	}
-	if body.Value.ProxyURL != nil {
-		entry.ProxyURL = strings.TrimSpace(*body.Value.ProxyURL)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	if body.Value.Models != nil {
-		entry.Models = append([]config.VertexCompatModel(nil), (*body.Value.Models)...)
-	}
-	normalizeVertexCompatKey(&entry)
-	h.cfg.VertexCompatAPIKey[targetIndex] = entry
-	h.cfg.SanitizeVertexCompatKeys()
-	h.persist(c)
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.BaseURL != nil {
+				trimmed := strings.TrimSpace(*patch.BaseURL)
+				if trimmed == "" {
+					return false
+				}
+				item.BaseURL = trimmed
+			}
+			if patch.ProxyURL != nil {
+				item.ProxyURL = strings.TrimSpace(*patch.ProxyURL)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			if patch.Models != nil {
+				item.Models = append([]config.VertexCompatModel(nil), (*patch.Models)...)
+			}
+			return true
+		},
+		normalizeVertexCompatKey,
+		h.cfg.SanitizeVertexCompatKeys,
+	)
 }
 
 func (h *Handler) DeleteVertexCompatKey(c *gin.Context) {
-	if val := strings.TrimSpace(c.Query("api-key")); val != "" {
-		out := make([]config.VertexCompatKey, 0, len(h.cfg.VertexCompatAPIKey))
-		for _, v := range h.cfg.VertexCompatAPIKey {
-			if v.APIKey != val {
-				out = append(out, v)
-			}
-		}
-		h.cfg.VertexCompatAPIKey = out
-		h.cfg.SanitizeVertexCompatKeys()
-		h.persist(c)
-		return
-	}
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		_, errScan := fmt.Sscanf(idxStr, "%d", &idx)
-		if errScan == nil && idx >= 0 && idx < len(h.cfg.VertexCompatAPIKey) {
-			h.cfg.VertexCompatAPIKey = append(h.cfg.VertexCompatAPIKey[:idx], h.cfg.VertexCompatAPIKey[idx+1:]...)
-			h.cfg.SanitizeVertexCompatKeys()
-			h.persist(c)
-			return
-		}
-	}
-	c.JSON(400, gin.H{"error": "missing api-key or index"})
+	genericDeleteList(h, c,
+		func() []config.VertexCompatKey { return h.cfg.VertexCompatAPIKey },
+		func(v []config.VertexCompatKey) { h.cfg.VertexCompatAPIKey = v },
+		func(item config.VertexCompatKey, val string) bool { return item.APIKey == val },
+		"api-key",
+		h.cfg.SanitizeVertexCompatKeys,
+	)
 }
 
 // oauth-excluded-models: map[string][]string
+// ... (Keeping as is, it's a map)
 func (h *Handler) GetOAuthExcludedModels(c *gin.Context) {
 	c.JSON(200, gin.H{"oauth-excluded-models": config.NormalizeOAuthExcludedModels(h.cfg.OAuthExcludedModels)})
 }
@@ -858,6 +566,7 @@ func (h *Handler) DeleteOAuthExcludedModels(c *gin.Context) {
 }
 
 // oauth-model-alias: map[string][]OAuthModelAlias
+// ... (Keeping as is, it's a map)
 func (h *Handler) GetOAuthModelAlias(c *gin.Context) {
 	c.JSON(200, gin.H{"oauth-model-alias": sanitizedOAuthModelAlias(h.cfg.OAuthModelAlias)})
 }
@@ -959,132 +668,56 @@ func (h *Handler) GetCodexKeys(c *gin.Context) {
 	c.JSON(200, gin.H{"codex-api-key": h.cfg.CodexKey})
 }
 func (h *Handler) PutCodexKeys(c *gin.Context) {
-	data, err := c.GetRawData()
-	if err != nil {
-		c.JSON(400, gin.H{"error": "failed to read body"})
-		return
-	}
-	var arr []config.CodexKey
-	if err = json.Unmarshal(data, &arr); err != nil {
-		var obj struct {
-			Items []config.CodexKey `json:"items"`
-		}
-		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
-			c.JSON(400, gin.H{"error": "invalid body"})
-			return
-		}
-		arr = obj.Items
-	}
-	// Filter out codex entries with empty base-url (treat as removed)
-	filtered := make([]config.CodexKey, 0, len(arr))
-	for i := range arr {
-		entry := arr[i]
-		normalizeCodexKey(&entry)
-		if entry.BaseURL == "" {
-			continue
-		}
-		filtered = append(filtered, entry)
-	}
-	h.cfg.CodexKey = filtered
-	h.cfg.SanitizeCodexKeys()
-	h.persist(c)
+	genericPutList(h, c, func(v []config.CodexKey) {
+		h.cfg.CodexKey = v
+	}, normalizeCodexKey, h.cfg.SanitizeCodexKeys)
 }
 func (h *Handler) PatchCodexKey(c *gin.Context) {
-	type codexKeyPatch struct {
-		APIKey         *string              `json:"api-key"`
-		Prefix         *string              `json:"prefix"`
-		BaseURL        *string              `json:"base-url"`
-		ProxyURL       *string              `json:"proxy-url"`
-		Models         *[]config.CodexModel `json:"models"`
-		Headers        *map[string]string   `json:"headers"`
-		ExcludedModels *[]string            `json:"excluded-models"`
-	}
-	var body struct {
-		Index *int           `json:"index"`
-		Match *string        `json:"match"`
-		Value *codexKeyPatch `json:"value"`
-	}
-	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
-		c.JSON(400, gin.H{"error": "invalid body"})
-		return
-	}
-	targetIndex := -1
-	if body.Index != nil && *body.Index >= 0 && *body.Index < len(h.cfg.CodexKey) {
-		targetIndex = *body.Index
-	}
-	if targetIndex == -1 && body.Match != nil {
-		match := strings.TrimSpace(*body.Match)
-		for i := range h.cfg.CodexKey {
-			if h.cfg.CodexKey[i].APIKey == match {
-				targetIndex = i
-				break
+	genericPatchList(h, c,
+		func() []config.CodexKey { return h.cfg.CodexKey },
+		func(v []config.CodexKey) { h.cfg.CodexKey = v },
+		func(item config.CodexKey, match string) bool { return item.APIKey == match },
+		func(item *config.CodexKey, patch codexKeyPatch) bool {
+			if patch.APIKey != nil {
+				item.APIKey = strings.TrimSpace(*patch.APIKey)
 			}
-		}
-	}
-	if targetIndex == -1 {
-		c.JSON(404, gin.H{"error": "item not found"})
-		return
-	}
-
-	entry := h.cfg.CodexKey[targetIndex]
-	if body.Value.APIKey != nil {
-		entry.APIKey = strings.TrimSpace(*body.Value.APIKey)
-	}
-	if body.Value.Prefix != nil {
-		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
-	}
-	if body.Value.BaseURL != nil {
-		trimmed := strings.TrimSpace(*body.Value.BaseURL)
-		if trimmed == "" {
-			h.cfg.CodexKey = append(h.cfg.CodexKey[:targetIndex], h.cfg.CodexKey[targetIndex+1:]...)
-			h.cfg.SanitizeCodexKeys()
-			h.persist(c)
-			return
-		}
-		entry.BaseURL = trimmed
-	}
-	if body.Value.ProxyURL != nil {
-		entry.ProxyURL = strings.TrimSpace(*body.Value.ProxyURL)
-	}
-	if body.Value.Models != nil {
-		entry.Models = append([]config.CodexModel(nil), (*body.Value.Models)...)
-	}
-	if body.Value.Headers != nil {
-		entry.Headers = config.NormalizeHeaders(*body.Value.Headers)
-	}
-	if body.Value.ExcludedModels != nil {
-		entry.ExcludedModels = config.NormalizeExcludedModels(*body.Value.ExcludedModels)
-	}
-	normalizeCodexKey(&entry)
-	h.cfg.CodexKey[targetIndex] = entry
-	h.cfg.SanitizeCodexKeys()
-	h.persist(c)
+			if patch.Prefix != nil {
+				item.Prefix = strings.TrimSpace(*patch.Prefix)
+			}
+			if patch.BaseURL != nil {
+				trimmed := strings.TrimSpace(*patch.BaseURL)
+				if trimmed == "" {
+					return false
+				}
+				item.BaseURL = trimmed
+			}
+			if patch.ProxyURL != nil {
+				item.ProxyURL = strings.TrimSpace(*patch.ProxyURL)
+			}
+			if patch.Models != nil {
+				item.Models = append([]config.CodexModel(nil), (*patch.Models)...)
+			}
+			if patch.Headers != nil {
+				item.Headers = config.NormalizeHeaders(*patch.Headers)
+			}
+			if patch.ExcludedModels != nil {
+				item.ExcludedModels = config.NormalizeExcludedModels(*patch.ExcludedModels)
+			}
+			return true
+		},
+		normalizeCodexKey,
+		h.cfg.SanitizeCodexKeys,
+	)
 }
 
 func (h *Handler) DeleteCodexKey(c *gin.Context) {
-	if val := c.Query("api-key"); val != "" {
-		out := make([]config.CodexKey, 0, len(h.cfg.CodexKey))
-		for _, v := range h.cfg.CodexKey {
-			if v.APIKey != val {
-				out = append(out, v)
-			}
-		}
-		h.cfg.CodexKey = out
-		h.cfg.SanitizeCodexKeys()
-		h.persist(c)
-		return
-	}
-	if idxStr := c.Query("index"); idxStr != "" {
-		var idx int
-		_, err := fmt.Sscanf(idxStr, "%d", &idx)
-		if err == nil && idx >= 0 && idx < len(h.cfg.CodexKey) {
-			h.cfg.CodexKey = append(h.cfg.CodexKey[:idx], h.cfg.CodexKey[idx+1:]...)
-			h.cfg.SanitizeCodexKeys()
-			h.persist(c)
-			return
-		}
-	}
-	c.JSON(400, gin.H{"error": "missing api-key or index"})
+	genericDeleteList(h, c,
+		func() []config.CodexKey { return h.cfg.CodexKey },
+		func(v []config.CodexKey) { h.cfg.CodexKey = v },
+		func(item config.CodexKey, val string) bool { return item.APIKey == val },
+		"api-key",
+		h.cfg.SanitizeCodexKeys,
+	)
 }
 
 func normalizeOpenAICompatibilityEntry(entry *config.OpenAICompatibility) {

internal/api/handlers/management/generics.go

@@ -0,0 +1,164 @@
+package management
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// genericPutList handles PUT requests for a list of items.
+func genericPutList[T any](h *Handler, c *gin.Context, setList func([]T), normalize func(*T), sanitize func()) {
+	data, err := c.GetRawData()
+	if err != nil {
+		c.JSON(400, gin.H{"error": "failed to read body"})
+		return
+	}
+	var arr []T
+	if err = json.Unmarshal(data, &arr); err != nil {
+		var obj struct {
+			Items []T `json:"items"`
+		}
+		if err2 := json.Unmarshal(data, &obj); err2 != nil || len(obj.Items) == 0 {
+			c.JSON(400, gin.H{"error": "invalid body"})
+			return
+		}
+		arr = obj.Items
+	}
+
+	if normalize != nil {
+		for i := range arr {
+			normalize(&arr[i])
+		}
+	}
+
+	setList(arr)
+	if sanitize != nil {
+		sanitize()
+	}
+	h.persist(c)
+}
+
+// genericPatchList handles PATCH requests for a list item.
+// T is the item type (e.g. config.GeminiKey).
+// P is the patch struct type (e.g. geminiKeyPatch).
+func genericPatchList[T any, P any](
+	h *Handler,
+	c *gin.Context,
+	getList func() []T,
+	setList func([]T),
+	matchFunc func(T, string) bool, // returns true if item matches the match string
+	updateFunc func(*T, P) bool, // applies patch P to item T, returns false if item should be removed
+	normalize func(*T),
+	sanitize func(),
+) {
+	var body struct {
+		Index *int    `json:"index"`
+		Match *string `json:"match"`
+		Value *P      `json:"value"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Value == nil {
+		c.JSON(400, gin.H{"error": "invalid body"})
+		return
+	}
+
+	list := getList()
+	targetIndex := -1
+	if body.Index != nil && *body.Index >= 0 && *body.Index < len(list) {
+		targetIndex = *body.Index
+	}
+	if targetIndex == -1 && body.Match != nil {
+		match := strings.TrimSpace(*body.Match)
+		if match != "" && matchFunc != nil {
+			for i := range list {
+				if matchFunc(list[i], match) {
+					targetIndex = i
+					break
+				}
+			}
+		}
+	}
+
+	if targetIndex == -1 {
+		c.JSON(404, gin.H{"error": "item not found"})
+		return
+	}
+
+	// Work on a copy of the list to be safe, but we need to modify the list in place or reassign.
+	// Since getList returns a slice, modifications to elements reflect in the underlying array usually,
+	// but appending/slicing does not.
+	// We will create a new slice for assignment.
+
+	// Use a copy of the slice to avoid modifying the config in place before persisting (though persist calls save, config is in memory).
+	// Actually we want to modify h.cfg in place then persist.
+
+	entry := list[targetIndex]
+	keep := updateFunc(&entry, *body.Value)
+
+	if !keep {
+		// Remove item
+		list = append(list[:targetIndex], list[targetIndex+1:]...)
+	} else {
+		if normalize != nil {
+			normalize(&entry)
+		}
+		list[targetIndex] = entry
+	}
+
+	setList(list)
+	if sanitize != nil {
+		sanitize()
+	}
+	h.persist(c)
+}
+
+// genericDeleteList handles DELETE requests for a list item.
+func genericDeleteList[T any](
+	h *Handler,
+	c *gin.Context,
+	getList func() []T,
+	setList func([]T),
+	shouldDelete func(T, string) bool, // returns true if item matches criteria and should be deleted
+	queryParamName string,
+	sanitize func(),
+) {
+	if val := strings.TrimSpace(c.Query(queryParamName)); val != "" {
+		list := getList()
+		out := make([]T, 0, len(list))
+		deleted := false
+		for _, v := range list {
+			if shouldDelete(v, val) {
+				deleted = true
+				continue
+			}
+			out = append(out, v)
+		}
+
+		if deleted {
+			setList(out)
+			if sanitize != nil {
+				sanitize()
+			}
+			h.persist(c)
+		} else {
+			c.JSON(404, gin.H{"error": "item not found"})
+		}
+		return
+	}
+
+	if idxStr := c.Query("index"); idxStr != "" {
+		list := getList()
+		var idx int
+		if _, err := fmt.Sscanf(idxStr, "%d", &idx); err == nil && idx >= 0 && idx < len(list) {
+			list = append(list[:idx], list[idx+1:]...)
+			setList(list)
+			if sanitize != nil {
+				sanitize()
+			}
+			h.persist(c)
+			return
+		}
+	}
+	c.JSON(400, gin.H{"error": fmt.Sprintf("missing %s or index", queryParamName)})
+}

internal/api/handlers/management/generics_test.go

@@ -0,0 +1,142 @@
+package management
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
+	"github.com/stretchr/testify/assert"
+)
+
+// setupTestHandler creates a temporary config file and a Handler for testing.
+// It returns the handler, the config object, the cleanup function, and an error if any.
+func setupTestHandler(t *testing.T) (*Handler, *config.Config, func(), error) {
+	// Create a temporary file for config
+	tmpFile, err := os.CreateTemp("", "config_test_*.yaml")
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	
+	// Write initial valid YAML content (empty object)
+	if _, err := tmpFile.WriteString("{}\n"); err != nil {
+		tmpFile.Close()
+		os.Remove(tmpFile.Name())
+		return nil, nil, nil, err
+	}
+	tmpFile.Close()
+
+	cfg := &config.Config{
+		SDKConfig: config.SDKConfig{
+			Access: config.AccessConfig{
+				Providers: nil,
+			},
+		},
+	}
+	
+	h := NewHandler(cfg, tmpFile.Name(), nil)
+	
+	cleanup := func() {
+		os.Remove(tmpFile.Name())
+	}
+
+	return h, cfg, cleanup, nil
+}
+
+func TestPutAPIKeys(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h, cfg, cleanup, err := setupTestHandler(t)
+	assert.NoError(t, err)
+	defer cleanup()
+
+	// Initial state
+	cfg.APIKeys = []string{"initial-key"}
+
+	// Test case: Put a new list of keys
+	newKeys := []string{"key1", "key2", "key3"}
+	body, _ := json.Marshal(newKeys)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodPut, "/api-keys", bytes.NewBuffer(body))
+
+	h.PutAPIKeys(c)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	
+	// Verify memory update
+	assert.Equal(t, newKeys, cfg.APIKeys)
+	
+	// Verify Access.Providers is cleared (as per PutAPIKeys logic)
+	assert.Nil(t, cfg.Access.Providers)
+
+	// Test case: Put using object wrapper { "items": [...] }
+	wrapperBody := `{"items": ["wrapped-key-1", "wrapped-key-2"]}`
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodPut, "/api-keys", bytes.NewBufferString(wrapperBody))
+
+	h.PutAPIKeys(c)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, []string{"wrapped-key-1", "wrapped-key-2"}, cfg.APIKeys)
+}
+
+func TestDeleteAPIKeys(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h, cfg, cleanup, err := setupTestHandler(t)
+	assert.NoError(t, err)
+	defer cleanup()
+
+	// Initial state
+	cfg.APIKeys = []string{"key1", "key2", "key3", "key4"}
+
+	// Test case: Delete by value (query param "value")
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodDelete, "/api-keys?value=key2", nil)
+
+	h.DeleteAPIKeys(c)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, []string{"key1", "key3", "key4"}, cfg.APIKeys)
+
+	// Test case: Delete by index
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodDelete, "/api-keys?index=1", nil) // Deleting index 1 (key3 now, since key2 is gone)
+
+	h.DeleteAPIKeys(c)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, []string{"key1", "key4"}, cfg.APIKeys)
+
+	// Test case: Delete non-existent value
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodDelete, "/api-keys?value=non-existent", nil)
+
+	h.DeleteAPIKeys(c)
+
+	assert.Equal(t, http.StatusNotFound, w.Code)
+	assert.Equal(t, []string{"key1", "key4"}, cfg.APIKeys)
+
+	// Test case: Delete invalid index
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request, _ = http.NewRequest(http.MethodDelete, "/api-keys?index=99", nil)
+
+	h.DeleteAPIKeys(c)
+
+	// GenericDeleteList returns 400 if index is out of bounds but parsed correctly?
+	// The code says: if _, err := fmt.Sscanf(idxStr, "%d", &idx); err == nil && idx >= 0 && idx < len(list)
+	// If that condition fails, it falls through to c.JSON(400, "missing ... or index")
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Equal(t, []string{"key1", "key4"}, cfg.APIKeys)
+}

internal/config/config.go

@@ -5,16 +5,12 @@
 package config
 
 import (
-	"bytes"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
 	"strings"
 	"syscall"
 
-	log "github.com/sirupsen/logrus"
-	"golang.org/x/crypto/bcrypt"
 	"gopkg.in/yaml.v3"
 )
 
@@ -664,1104 +660,3 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	// Return the populated configuration struct.
 	return &cfg, nil
 }
-
-// SanitizePayloadRules validates raw JSON payload rule params and drops invalid rules.
-func (cfg *Config) SanitizePayloadRules() {
-	if cfg == nil {
-		return
-	}
-	cfg.Payload.DefaultRaw = sanitizePayloadRawRules(cfg.Payload.DefaultRaw, "default-raw")
-	cfg.Payload.OverrideRaw = sanitizePayloadRawRules(cfg.Payload.OverrideRaw, "override-raw")
-}
-
-func sanitizePayloadRawRules(rules []PayloadRule, section string) []PayloadRule {
-	if len(rules) == 0 {
-		return rules
-	}
-	out := make([]PayloadRule, 0, len(rules))
-	for i := range rules {
-		rule := rules[i]
-		if len(rule.Params) == 0 {
-			continue
-		}
-		invalid := false
-		for path, value := range rule.Params {
-			raw, ok := payloadRawString(value)
-			if !ok {
-				continue
-			}
-			trimmed := bytes.TrimSpace(raw)
-			if len(trimmed) == 0 || !json.Valid(trimmed) {
-				log.WithFields(log.Fields{
-					"section":    section,
-					"rule_index": i + 1,
-					"param":      path,
-				}).Warn("payload rule dropped: invalid raw JSON")
-				invalid = true
-				break
-			}
-		}
-		if invalid {
-			continue
-		}
-		out = append(out, rule)
-	}
-	return out
-}
-
-func payloadRawString(value any) ([]byte, bool) {
-	switch typed := value.(type) {
-	case string:
-		return []byte(typed), true
-	case []byte:
-		return typed, true
-	default:
-		return nil, false
-	}
-}
-
-// SanitizeOAuthModelAlias normalizes and deduplicates global OAuth model name aliases.
-// It trims whitespace, normalizes channel keys to lower-case, drops empty entries,
-// allows multiple aliases per upstream name, and ensures aliases are unique within each channel.
-func (cfg *Config) SanitizeOAuthModelAlias() {
-	if cfg == nil || len(cfg.OAuthModelAlias) == 0 {
-		return
-	}
-	out := make(map[string][]OAuthModelAlias, len(cfg.OAuthModelAlias))
-	for rawChannel, aliases := range cfg.OAuthModelAlias {
-		channel := strings.ToLower(strings.TrimSpace(rawChannel))
-		if channel == "" || len(aliases) == 0 {
-			continue
-		}
-		seenAlias := make(map[string]struct{}, len(aliases))
-		clean := make([]OAuthModelAlias, 0, len(aliases))
-		for _, entry := range aliases {
-			name := strings.TrimSpace(entry.Name)
-			alias := strings.TrimSpace(entry.Alias)
-			if name == "" || alias == "" {
-				continue
-			}
-			if strings.EqualFold(name, alias) {
-				continue
-			}
-			aliasKey := strings.ToLower(alias)
-			if _, ok := seenAlias[aliasKey]; ok {
-				continue
-			}
-			seenAlias[aliasKey] = struct{}{}
-			clean = append(clean, OAuthModelAlias{Name: name, Alias: alias, Fork: entry.Fork})
-		}
-		if len(clean) > 0 {
-			out[channel] = clean
-		}
-	}
-	cfg.OAuthModelAlias = out
-}
-
-// SanitizeOpenAICompatibility removes OpenAI-compatibility provider entries that are
-// not actionable, specifically those missing a BaseURL. It trims whitespace before
-// evaluation and preserves the relative order of remaining entries.
-func (cfg *Config) SanitizeOpenAICompatibility() {
-	if cfg == nil || len(cfg.OpenAICompatibility) == 0 {
-		return
-	}
-	out := make([]OpenAICompatibility, 0, len(cfg.OpenAICompatibility))
-	for i := range cfg.OpenAICompatibility {
-		e := cfg.OpenAICompatibility[i]
-		e.Name = strings.TrimSpace(e.Name)
-		e.Prefix = normalizeModelPrefix(e.Prefix)
-		e.BaseURL = strings.TrimSpace(e.BaseURL)
-		e.Headers = NormalizeHeaders(e.Headers)
-		if e.BaseURL == "" {
-			// Skip providers with no base-url; treated as removed
-			continue
-		}
-		out = append(out, e)
-	}
-	cfg.OpenAICompatibility = out
-}
-
-// SanitizeCodexKeys removes Codex API key entries missing a BaseURL.
-// It trims whitespace and preserves order for remaining entries.
-func (cfg *Config) SanitizeCodexKeys() {
-	if cfg == nil || len(cfg.CodexKey) == 0 {
-		return
-	}
-	out := make([]CodexKey, 0, len(cfg.CodexKey))
-	for i := range cfg.CodexKey {
-		e := cfg.CodexKey[i]
-		e.Prefix = normalizeModelPrefix(e.Prefix)
-		e.BaseURL = strings.TrimSpace(e.BaseURL)
-		e.Headers = NormalizeHeaders(e.Headers)
-		e.ExcludedModels = NormalizeExcludedModels(e.ExcludedModels)
-		if e.BaseURL == "" {
-			continue
-		}
-		out = append(out, e)
-	}
-	cfg.CodexKey = out
-}
-
-// SanitizeClaudeKeys normalizes headers and API key entries for Claude credentials.
-func (cfg *Config) SanitizeClaudeKeys() {
-	if cfg == nil || len(cfg.ClaudeKey) == 0 {
-		return
-	}
-	for i := range cfg.ClaudeKey {
-		entry := &cfg.ClaudeKey[i]
-		entry.Prefix = normalizeModelPrefix(entry.Prefix)
-		entry.Headers = NormalizeHeaders(entry.Headers)
-		entry.ExcludedModels = NormalizeExcludedModels(entry.ExcludedModels)
-		entry.BaseURL = strings.TrimSpace(entry.BaseURL)
-		entry.ProxyURL = strings.TrimSpace(entry.ProxyURL)
-		entry.APIKey = strings.TrimSpace(entry.APIKey)
-		// Sanitize APIKeyEntries
-		for j := range entry.APIKeyEntries {
-			apiKeyEntry := &entry.APIKeyEntries[j]
-			apiKeyEntry.APIKey = strings.TrimSpace(apiKeyEntry.APIKey)
-			apiKeyEntry.ProxyURL = strings.TrimSpace(apiKeyEntry.ProxyURL)
-		}
-	}
-}
-
-// SanitizeGeminiKeys deduplicates and normalizes Gemini credentials.
-func (cfg *Config) SanitizeGeminiKeys() {
-	if cfg == nil {
-		return
-	}
-
-	seen := make(map[string]struct{}, len(cfg.GeminiKey))
-	out := cfg.GeminiKey[:0]
-	for i := range cfg.GeminiKey {
-		entry := cfg.GeminiKey[i]
-		entry.APIKey = strings.TrimSpace(entry.APIKey)
-		if entry.APIKey == "" {
-			continue
-		}
-		entry.Prefix = normalizeModelPrefix(entry.Prefix)
-		entry.BaseURL = strings.TrimSpace(entry.BaseURL)
-		entry.ProxyURL = strings.TrimSpace(entry.ProxyURL)
-		entry.Headers = NormalizeHeaders(entry.Headers)
-		entry.ExcludedModels = NormalizeExcludedModels(entry.ExcludedModels)
-		if _, exists := seen[entry.APIKey]; exists {
-			continue
-		}
-		seen[entry.APIKey] = struct{}{}
-		out = append(out, entry)
-	}
-	cfg.GeminiKey = out
-}
-
-func normalizeModelPrefix(prefix string) string {
-	trimmed := strings.TrimSpace(prefix)
-	trimmed = strings.Trim(trimmed, "/")
-	if trimmed == "" {
-		return ""
-	}
-	if strings.Contains(trimmed, "/") {
-		return ""
-	}
-	return trimmed
-}
-
-func syncInlineAccessProvider(cfg *Config) {
-	if cfg == nil {
-		return
-	}
-	if len(cfg.APIKeys) == 0 {
-		if provider := cfg.ConfigAPIKeyProvider(); provider != nil && len(provider.APIKeys) > 0 {
-			cfg.APIKeys = append([]string(nil), provider.APIKeys...)
-		}
-	}
-	cfg.Access.Providers = nil
-}
-
-// looksLikeBcrypt returns true if the provided string appears to be a bcrypt hash.
-func looksLikeBcrypt(s string) bool {
-	return len(s) > 4 && (s[:4] == "$2a$" || s[:4] == "$2b$" || s[:4] == "$2y$")
-}
-
-// NormalizeHeaders trims header keys and values and removes empty pairs.
-func NormalizeHeaders(headers map[string]string) map[string]string {
-	if len(headers) == 0 {
-		return nil
-	}
-	clean := make(map[string]string, len(headers))
-	for k, v := range headers {
-		key := strings.TrimSpace(k)
-		val := strings.TrimSpace(v)
-		if key == "" || val == "" {
-			continue
-		}
-		clean[key] = val
-	}
-	if len(clean) == 0 {
-		return nil
-	}
-	return clean
-}
-
-// NormalizeExcludedModels trims, lowercases, and deduplicates model exclusion patterns.
-// It preserves the order of first occurrences and drops empty entries.
-func NormalizeExcludedModels(models []string) []string {
-	if len(models) == 0 {
-		return nil
-	}
-	seen := make(map[string]struct{}, len(models))
-	out := make([]string, 0, len(models))
-	for _, raw := range models {
-		trimmed := strings.ToLower(strings.TrimSpace(raw))
-		if trimmed == "" {
-			continue
-		}
-		if _, exists := seen[trimmed]; exists {
-			continue
-		}
-		seen[trimmed] = struct{}{}
-		out = append(out, trimmed)
-	}
-	if len(out) == 0 {
-		return nil
-	}
-	return out
-}
-
-// NormalizeOAuthExcludedModels cleans provider -> excluded models mappings by normalizing provider keys
-// and applying model exclusion normalization to each entry.
-func NormalizeOAuthExcludedModels(entries map[string][]string) map[string][]string {
-	if len(entries) == 0 {
-		return nil
-	}
-	out := make(map[string][]string, len(entries))
-	for provider, models := range entries {
-		key := strings.ToLower(strings.TrimSpace(provider))
-		if key == "" {
-			continue
-		}
-		normalized := NormalizeExcludedModels(models)
-		if len(normalized) == 0 {
-			continue
-		}
-		out[key] = normalized
-	}
-	if len(out) == 0 {
-		return nil
-	}
-	return out
-}
-
-// hashSecret hashes the given secret using bcrypt.
-func hashSecret(secret string) (string, error) {
-	// Use default cost for simplicity.
-	hashedBytes, err := bcrypt.GenerateFromPassword([]byte(secret), bcrypt.DefaultCost)
-	if err != nil {
-		return "", err
-	}
-	return string(hashedBytes), nil
-}
-
-// SaveConfigPreserveComments writes the config back to YAML while preserving existing comments
-// and key ordering by loading the original file into a yaml.Node tree and updating values in-place.
-func SaveConfigPreserveComments(configFile string, cfg *Config) error {
-	persistCfg := sanitizeConfigForPersist(cfg)
-	// Load original YAML as a node tree to preserve comments and ordering.
-	data, err := os.ReadFile(configFile)
-	if err != nil {
-		return err
-	}
-
-	var original yaml.Node
-	if err = yaml.Unmarshal(data, &original); err != nil {
-		return err
-	}
-	if original.Kind != yaml.DocumentNode || len(original.Content) == 0 {
-		return fmt.Errorf("invalid yaml document structure")
-	}
-	if original.Content[0] == nil || original.Content[0].Kind != yaml.MappingNode {
-		return fmt.Errorf("expected root mapping node")
-	}
-
-	// Marshal the current cfg to YAML, then unmarshal to a yaml.Node we can merge from.
-	rendered, err := yaml.Marshal(persistCfg)
-	if err != nil {
-		return err
-	}
-	var generated yaml.Node
-	if err = yaml.Unmarshal(rendered, &generated); err != nil {
-		return err
-	}
-	if generated.Kind != yaml.DocumentNode || len(generated.Content) == 0 || generated.Content[0] == nil {
-		return fmt.Errorf("invalid generated yaml structure")
-	}
-	if generated.Content[0].Kind != yaml.MappingNode {
-		return fmt.Errorf("expected generated root mapping node")
-	}
-
-	// Remove deprecated sections before merging back the sanitized config.
-	removeLegacyAuthBlock(original.Content[0])
-	removeLegacyOpenAICompatAPIKeys(original.Content[0])
-	removeLegacyAmpKeys(original.Content[0])
-	removeLegacyGenerativeLanguageKeys(original.Content[0])
-
-	pruneMappingToGeneratedKeys(original.Content[0], generated.Content[0], "oauth-excluded-models")
-
-	// Merge generated into original in-place, preserving comments/order of existing nodes.
-	mergeMappingPreserve(original.Content[0], generated.Content[0])
-	normalizeCollectionNodeStyles(original.Content[0])
-
-	// Write back.
-	f, err := os.Create(configFile)
-	if err != nil {
-		return err
-	}
-	defer func() { _ = f.Close() }()
-	var buf bytes.Buffer
-	enc := yaml.NewEncoder(&buf)
-	enc.SetIndent(2)
-	if err = enc.Encode(&original); err != nil {
-		_ = enc.Close()
-		return err
-	}
-	if err = enc.Close(); err != nil {
-		return err
-	}
-	data = NormalizeCommentIndentation(buf.Bytes())
-	_, err = f.Write(data)
-	return err
-}
-
-func sanitizeConfigForPersist(cfg *Config) *Config {
-	if cfg == nil {
-		return nil
-	}
-	clone := *cfg
-	clone.SDKConfig = cfg.SDKConfig
-	clone.SDKConfig.Access = AccessConfig{}
-	return &clone
-}
-
-// SaveConfigPreserveCommentsUpdateNestedScalar updates a nested scalar key path like ["a","b"]
-// while preserving comments and positions.
-func SaveConfigPreserveCommentsUpdateNestedScalar(configFile string, path []string, value string) error {
-	data, err := os.ReadFile(configFile)
-	if err != nil {
-		return err
-	}
-	var root yaml.Node
-	if err = yaml.Unmarshal(data, &root); err != nil {
-		return err
-	}
-	if root.Kind != yaml.DocumentNode || len(root.Content) == 0 {
-		return fmt.Errorf("invalid yaml document structure")
-	}
-	node := root.Content[0]
-	// descend mapping nodes following path
-	for i, key := range path {
-		if i == len(path)-1 {
-			// set final scalar
-			v := getOrCreateMapValue(node, key)
-			v.Kind = yaml.ScalarNode
-			v.Tag = "!!str"
-			v.Value = value
-		} else {
-			next := getOrCreateMapValue(node, key)
-			if next.Kind != yaml.MappingNode {
-				next.Kind = yaml.MappingNode
-				next.Tag = "!!map"
-			}
-			node = next
-		}
-	}
-	f, err := os.Create(configFile)
-	if err != nil {
-		return err
-	}
-	defer func() { _ = f.Close() }()
-	var buf bytes.Buffer
-	enc := yaml.NewEncoder(&buf)
-	enc.SetIndent(2)
-	if err = enc.Encode(&root); err != nil {
-		_ = enc.Close()
-		return err
-	}
-	if err = enc.Close(); err != nil {
-		return err
-	}
-	data = NormalizeCommentIndentation(buf.Bytes())
-	_, err = f.Write(data)
-	return err
-}
-
-// NormalizeCommentIndentation removes indentation from standalone YAML comment lines to keep them left aligned.
-func NormalizeCommentIndentation(data []byte) []byte {
-	lines := bytes.Split(data, []byte("\n"))
-	changed := false
-	for i, line := range lines {
-		trimmed := bytes.TrimLeft(line, " \t")
-		if len(trimmed) == 0 || trimmed[0] != '#' {
-			continue
-		}
-		if len(trimmed) == len(line) {
-			continue
-		}
-		lines[i] = append([]byte(nil), trimmed...)
-		changed = true
-	}
-	if !changed {
-		return data
-	}
-	return bytes.Join(lines, []byte("\n"))
-}
-
-// getOrCreateMapValue finds the value node for a given key in a mapping node.
-// If not found, it appends a new key/value pair and returns the new value node.
-func getOrCreateMapValue(mapNode *yaml.Node, key string) *yaml.Node {
-	if mapNode.Kind != yaml.MappingNode {
-		mapNode.Kind = yaml.MappingNode
-		mapNode.Tag = "!!map"
-		mapNode.Content = nil
-	}
-	for i := 0; i+1 < len(mapNode.Content); i += 2 {
-		k := mapNode.Content[i]
-		if k.Value == key {
-			return mapNode.Content[i+1]
-		}
-	}
-	// append new key/value
-	mapNode.Content = append(mapNode.Content, &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: key})
-	val := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: ""}
-	mapNode.Content = append(mapNode.Content, val)
-	return val
-}
-
-// mergeMappingPreserve merges keys from src into dst mapping node while preserving
-// key order and comments of existing keys in dst. New keys are only added if their
-// value is non-zero to avoid polluting the config with defaults.
-func mergeMappingPreserve(dst, src *yaml.Node) {
-	if dst == nil || src == nil {
-		return
-	}
-	if dst.Kind != yaml.MappingNode || src.Kind != yaml.MappingNode {
-		// If kinds do not match, prefer replacing dst with src semantics in-place
-		// but keep dst node object to preserve any attached comments at the parent level.
-		copyNodeShallow(dst, src)
-		return
-	}
-	for i := 0; i+1 < len(src.Content); i += 2 {
-		sk := src.Content[i]
-		sv := src.Content[i+1]
-		idx := findMapKeyIndex(dst, sk.Value)
-		if idx >= 0 {
-			// Merge into existing value node (always update, even to zero values)
-			dv := dst.Content[idx+1]
-			mergeNodePreserve(dv, sv)
-		} else {
-			// New key: only add if value is non-zero to avoid polluting config with defaults
-			if isZeroValueNode(sv) {
-				continue
-			}
-			dst.Content = append(dst.Content, deepCopyNode(sk), deepCopyNode(sv))
-		}
-	}
-}
-
-// mergeNodePreserve merges src into dst for scalars, mappings and sequences while
-// reusing destination nodes to keep comments and anchors. For sequences, it updates
-// in-place by index.
-func mergeNodePreserve(dst, src *yaml.Node) {
-	if dst == nil || src == nil {
-		return
-	}
-	switch src.Kind {
-	case yaml.MappingNode:
-		if dst.Kind != yaml.MappingNode {
-			copyNodeShallow(dst, src)
-		}
-		mergeMappingPreserve(dst, src)
-	case yaml.SequenceNode:
-		// Preserve explicit null style if dst was null and src is empty sequence
-		if dst.Kind == yaml.ScalarNode && dst.Tag == "!!null" && len(src.Content) == 0 {
-			// Keep as null to preserve original style
-			return
-		}
-		if dst.Kind != yaml.SequenceNode {
-			dst.Kind = yaml.SequenceNode
-			dst.Tag = "!!seq"
-			dst.Content = nil
-		}
-		reorderSequenceForMerge(dst, src)
-		// Update elements in place
-		minContent := len(dst.Content)
-		if len(src.Content) < minContent {
-			minContent = len(src.Content)
-		}
-		for i := 0; i < minContent; i++ {
-			if dst.Content[i] == nil {
-				dst.Content[i] = deepCopyNode(src.Content[i])
-				continue
-			}
-			mergeNodePreserve(dst.Content[i], src.Content[i])
-			if dst.Content[i] != nil && src.Content[i] != nil &&
-				dst.Content[i].Kind == yaml.MappingNode && src.Content[i].Kind == yaml.MappingNode {
-				pruneMissingMapKeys(dst.Content[i], src.Content[i])
-			}
-		}
-		// Append any extra items from src
-		for i := len(dst.Content); i < len(src.Content); i++ {
-			dst.Content = append(dst.Content, deepCopyNode(src.Content[i]))
-		}
-		// Truncate if dst has extra items not in src
-		if len(src.Content) < len(dst.Content) {
-			dst.Content = dst.Content[:len(src.Content)]
-		}
-	case yaml.ScalarNode, yaml.AliasNode:
-		// For scalars, update Tag and Value but keep Style from dst to preserve quoting
-		dst.Kind = src.Kind
-		dst.Tag = src.Tag
-		dst.Value = src.Value
-		// Keep dst.Style as-is intentionally
-	case 0:
-		// Unknown/empty kind; do nothing
-	default:
-		// Fallback: replace shallowly
-		copyNodeShallow(dst, src)
-	}
-}
-
-// findMapKeyIndex returns the index of key node in dst mapping (index of key, not value).
-// Returns -1 when not found.
-func findMapKeyIndex(mapNode *yaml.Node, key string) int {
-	if mapNode == nil || mapNode.Kind != yaml.MappingNode {
-		return -1
-	}
-	for i := 0; i+1 < len(mapNode.Content); i += 2 {
-		if mapNode.Content[i] != nil && mapNode.Content[i].Value == key {
-			return i
-		}
-	}
-	return -1
-}
-
-// isZeroValueNode returns true if the YAML node represents a zero/default value
-// that should not be written as a new key to preserve config cleanliness.
-// For mappings and sequences, recursively checks if all children are zero values.
-func isZeroValueNode(node *yaml.Node) bool {
-	if node == nil {
-		return true
-	}
-	switch node.Kind {
-	case yaml.ScalarNode:
-		switch node.Tag {
-		case "!!bool":
-			return node.Value == "false"
-		case "!!int", "!!float":
-			return node.Value == "0" || node.Value == "0.0"
-		case "!!str":
-			return node.Value == ""
-		case "!!null":
-			return true
-		}
-	case yaml.SequenceNode:
-		if len(node.Content) == 0 {
-			return true
-		}
-		// Check if all elements are zero values
-		for _, child := range node.Content {
-			if !isZeroValueNode(child) {
-				return false
-			}
-		}
-		return true
-	case yaml.MappingNode:
-		if len(node.Content) == 0 {
-			return true
-		}
-		// Check if all values are zero values (values are at odd indices)
-		for i := 1; i < len(node.Content); i += 2 {
-			if !isZeroValueNode(node.Content[i]) {
-				return false
-			}
-		}
-		return true
-	}
-	return false
-}
-
-// deepCopyNode creates a deep copy of a yaml.Node graph.
-func deepCopyNode(n *yaml.Node) *yaml.Node {
-	if n == nil {
-		return nil
-	}
-	cp := *n
-	if len(n.Content) > 0 {
-		cp.Content = make([]*yaml.Node, len(n.Content))
-		for i := range n.Content {
-			cp.Content[i] = deepCopyNode(n.Content[i])
-		}
-	}
-	return &cp
-}
-
-// copyNodeShallow copies type/tag/value and resets content to match src, but
-// keeps the same destination node pointer to preserve parent relations/comments.
-func copyNodeShallow(dst, src *yaml.Node) {
-	if dst == nil || src == nil {
-		return
-	}
-	dst.Kind = src.Kind
-	dst.Tag = src.Tag
-	dst.Value = src.Value
-	// Replace content with deep copy from src
-	if len(src.Content) > 0 {
-		dst.Content = make([]*yaml.Node, len(src.Content))
-		for i := range src.Content {
-			dst.Content[i] = deepCopyNode(src.Content[i])
-		}
-	} else {
-		dst.Content = nil
-	}
-}
-
-func reorderSequenceForMerge(dst, src *yaml.Node) {
-	if dst == nil || src == nil {
-		return
-	}
-	if len(dst.Content) == 0 {
-		return
-	}
-	if len(src.Content) == 0 {
-		return
-	}
-	original := append([]*yaml.Node(nil), dst.Content...)
-	used := make([]bool, len(original))
-	ordered := make([]*yaml.Node, len(src.Content))
-	for i := range src.Content {
-		if idx := matchSequenceElement(original, used, src.Content[i]); idx >= 0 {
-			ordered[i] = original[idx]
-			used[idx] = true
-		}
-	}
-	dst.Content = ordered
-}
-
-func matchSequenceElement(original []*yaml.Node, used []bool, target *yaml.Node) int {
-	if target == nil {
-		return -1
-	}
-	switch target.Kind {
-	case yaml.MappingNode:
-		id := sequenceElementIdentity(target)
-		if id != "" {
-			for i := range original {
-				if used[i] || original[i] == nil || original[i].Kind != yaml.MappingNode {
-					continue
-				}
-				if sequenceElementIdentity(original[i]) == id {
-					return i
-				}
-			}
-		}
-	case yaml.ScalarNode:
-		val := strings.TrimSpace(target.Value)
-		if val != "" {
-			for i := range original {
-				if used[i] || original[i] == nil || original[i].Kind != yaml.ScalarNode {
-					continue
-				}
-				if strings.TrimSpace(original[i].Value) == val {
-					return i
-				}
-			}
-		}
-	default:
-	}
-	// Fallback to structural equality to preserve nodes lacking explicit identifiers.
-	for i := range original {
-		if used[i] || original[i] == nil {
-			continue
-		}
-		if nodesStructurallyEqual(original[i], target) {
-			return i
-		}
-	}
-	return -1
-}
-
-func sequenceElementIdentity(node *yaml.Node) string {
-	if node == nil || node.Kind != yaml.MappingNode {
-		return ""
-	}
-	identityKeys := []string{"id", "name", "alias", "api-key", "api_key", "apikey", "key", "provider", "model"}
-	for _, k := range identityKeys {
-		if v := mappingScalarValue(node, k); v != "" {
-			return k + "=" + v
-		}
-	}
-	for i := 0; i+1 < len(node.Content); i += 2 {
-		keyNode := node.Content[i]
-		valNode := node.Content[i+1]
-		if keyNode == nil || valNode == nil || valNode.Kind != yaml.ScalarNode {
-			continue
-		}
-		val := strings.TrimSpace(valNode.Value)
-		if val != "" {
-			return strings.ToLower(strings.TrimSpace(keyNode.Value)) + "=" + val
-		}
-	}
-	return ""
-}
-
-func mappingScalarValue(node *yaml.Node, key string) string {
-	if node == nil || node.Kind != yaml.MappingNode {
-		return ""
-	}
-	lowerKey := strings.ToLower(key)
-	for i := 0; i+1 < len(node.Content); i += 2 {
-		keyNode := node.Content[i]
-		valNode := node.Content[i+1]
-		if keyNode == nil || valNode == nil || valNode.Kind != yaml.ScalarNode {
-			continue
-		}
-		if strings.ToLower(strings.TrimSpace(keyNode.Value)) == lowerKey {
-			return strings.TrimSpace(valNode.Value)
-		}
-	}
-	return ""
-}
-
-func nodesStructurallyEqual(a, b *yaml.Node) bool {
-	if a == nil || b == nil {
-		return a == b
-	}
-	if a.Kind != b.Kind {
-		return false
-	}
-	switch a.Kind {
-	case yaml.MappingNode:
-		if len(a.Content) != len(b.Content) {
-			return false
-		}
-		for i := 0; i+1 < len(a.Content); i += 2 {
-			if !nodesStructurallyEqual(a.Content[i], b.Content[i]) {
-				return false
-			}
-			if !nodesStructurallyEqual(a.Content[i+1], b.Content[i+1]) {
-				return false
-			}
-		}
-		return true
-	case yaml.SequenceNode:
-		if len(a.Content) != len(b.Content) {
-			return false
-		}
-		for i := range a.Content {
-			if !nodesStructurallyEqual(a.Content[i], b.Content[i]) {
-				return false
-			}
-		}
-		return true
-	case yaml.ScalarNode:
-		return strings.TrimSpace(a.Value) == strings.TrimSpace(b.Value)
-	case yaml.AliasNode:
-		return nodesStructurallyEqual(a.Alias, b.Alias)
-	default:
-		return strings.TrimSpace(a.Value) == strings.TrimSpace(b.Value)
-	}
-}
-
-func removeMapKey(mapNode *yaml.Node, key string) {
-	if mapNode == nil || mapNode.Kind != yaml.MappingNode || key == "" {
-		return
-	}
-	for i := 0; i+1 < len(mapNode.Content); i += 2 {
-		if mapNode.Content[i] != nil && mapNode.Content[i].Value == key {
-			mapNode.Content = append(mapNode.Content[:i], mapNode.Content[i+2:]...)
-			return
-		}
-	}
-}
-
-func pruneMappingToGeneratedKeys(dstRoot, srcRoot *yaml.Node, key string) {
-	if key == "" || dstRoot == nil || srcRoot == nil {
-		return
-	}
-	if dstRoot.Kind != yaml.MappingNode || srcRoot.Kind != yaml.MappingNode {
-		return
-	}
-	dstIdx := findMapKeyIndex(dstRoot, key)
-	if dstIdx < 0 || dstIdx+1 >= len(dstRoot.Content) {
-		return
-	}
-	srcIdx := findMapKeyIndex(srcRoot, key)
-	if srcIdx < 0 {
-		removeMapKey(dstRoot, key)
-		return
-	}
-	if srcIdx+1 >= len(srcRoot.Content) {
-		return
-	}
-	srcVal := srcRoot.Content[srcIdx+1]
-	dstVal := dstRoot.Content[dstIdx+1]
-	if srcVal == nil {
-		dstRoot.Content[dstIdx+1] = nil
-		return
-	}
-	if srcVal.Kind != yaml.MappingNode {
-		dstRoot.Content[dstIdx+1] = deepCopyNode(srcVal)
-		return
-	}
-	if dstVal == nil || dstVal.Kind != yaml.MappingNode {
-		dstRoot.Content[dstIdx+1] = deepCopyNode(srcVal)
-		return
-	}
-	pruneMissingMapKeys(dstVal, srcVal)
-}
-
-func pruneMissingMapKeys(dstMap, srcMap *yaml.Node) {
-	if dstMap == nil || srcMap == nil || dstMap.Kind != yaml.MappingNode || srcMap.Kind != yaml.MappingNode {
-		return
-	}
-	keep := make(map[string]struct{}, len(srcMap.Content)/2)
-	for i := 0; i+1 < len(srcMap.Content); i += 2 {
-		keyNode := srcMap.Content[i]
-		if keyNode == nil {
-			continue
-		}
-		key := strings.TrimSpace(keyNode.Value)
-		if key == "" {
-			continue
-		}
-		keep[key] = struct{}{}
-	}
-	for i := 0; i+1 < len(dstMap.Content); {
-		keyNode := dstMap.Content[i]
-		if keyNode == nil {
-			i += 2
-			continue
-		}
-		key := strings.TrimSpace(keyNode.Value)
-		if _, ok := keep[key]; !ok {
-			dstMap.Content = append(dstMap.Content[:i], dstMap.Content[i+2:]...)
-			continue
-		}
-		i += 2
-	}
-}
-
-// normalizeCollectionNodeStyles forces YAML collections to use block notation, keeping
-// lists and maps readable. Empty sequences retain flow style ([]) so empty list markers
-// remain compact.
-func normalizeCollectionNodeStyles(node *yaml.Node) {
-	if node == nil {
-		return
-	}
-	switch node.Kind {
-	case yaml.MappingNode:
-		node.Style = 0
-		for i := range node.Content {
-			normalizeCollectionNodeStyles(node.Content[i])
-		}
-	case yaml.SequenceNode:
-		if len(node.Content) == 0 {
-			node.Style = yaml.FlowStyle
-		} else {
-			node.Style = 0
-		}
-		for i := range node.Content {
-			normalizeCollectionNodeStyles(node.Content[i])
-		}
-	default:
-		// Scalars keep their existing style to preserve quoting
-	}
-}
-
-// Legacy migration helpers (move deprecated config keys into structured fields).
-type legacyConfigData struct {
-	LegacyGeminiKeys      []string                    `yaml:"generative-language-api-key"`
-	OpenAICompat          []legacyOpenAICompatibility `yaml:"openai-compatibility"`
-	AmpUpstreamURL        string                      `yaml:"amp-upstream-url"`
-	AmpUpstreamAPIKey     string                      `yaml:"amp-upstream-api-key"`
-	AmpRestrictManagement *bool                       `yaml:"amp-restrict-management-to-localhost"`
-	AmpModelMappings      []AmpModelMapping           `yaml:"amp-model-mappings"`
-}
-
-type legacyOpenAICompatibility struct {
-	Name    string   `yaml:"name"`
-	BaseURL string   `yaml:"base-url"`
-	APIKeys []string `yaml:"api-keys"`
-}
-
-func (cfg *Config) migrateLegacyGeminiKeys(legacy []string) bool {
-	if cfg == nil || len(legacy) == 0 {
-		return false
-	}
-	changed := false
-	seen := make(map[string]struct{}, len(cfg.GeminiKey))
-	for i := range cfg.GeminiKey {
-		key := strings.TrimSpace(cfg.GeminiKey[i].APIKey)
-		if key == "" {
-			continue
-		}
-		seen[key] = struct{}{}
-	}
-	for _, raw := range legacy {
-		key := strings.TrimSpace(raw)
-		if key == "" {
-			continue
-		}
-		if _, exists := seen[key]; exists {
-			continue
-		}
-		cfg.GeminiKey = append(cfg.GeminiKey, GeminiKey{APIKey: key})
-		seen[key] = struct{}{}
-		changed = true
-	}
-	return changed
-}
-
-func (cfg *Config) migrateLegacyOpenAICompatibilityKeys(legacy []legacyOpenAICompatibility) bool {
-	if cfg == nil || len(cfg.OpenAICompatibility) == 0 || len(legacy) == 0 {
-		return false
-	}
-	changed := false
-	for _, legacyEntry := range legacy {
-		if len(legacyEntry.APIKeys) == 0 {
-			continue
-		}
-		target := findOpenAICompatTarget(cfg.OpenAICompatibility, legacyEntry.Name, legacyEntry.BaseURL)
-		if target == nil {
-			continue
-		}
-		if mergeLegacyOpenAICompatAPIKeys(target, legacyEntry.APIKeys) {
-			changed = true
-		}
-	}
-	return changed
-}
-
-func mergeLegacyOpenAICompatAPIKeys(entry *OpenAICompatibility, keys []string) bool {
-	if entry == nil || len(keys) == 0 {
-		return false
-	}
-	changed := false
-	existing := make(map[string]struct{}, len(entry.APIKeyEntries))
-	for i := range entry.APIKeyEntries {
-		key := strings.TrimSpace(entry.APIKeyEntries[i].APIKey)
-		if key == "" {
-			continue
-		}
-		existing[key] = struct{}{}
-	}
-	for _, raw := range keys {
-		key := strings.TrimSpace(raw)
-		if key == "" {
-			continue
-		}
-		if _, ok := existing[key]; ok {
-			continue
-		}
-		entry.APIKeyEntries = append(entry.APIKeyEntries, OpenAICompatibilityAPIKey{APIKey: key})
-		existing[key] = struct{}{}
-		changed = true
-	}
-	return changed
-}
-
-func findOpenAICompatTarget(entries []OpenAICompatibility, legacyName, legacyBase string) *OpenAICompatibility {
-	nameKey := strings.ToLower(strings.TrimSpace(legacyName))
-	baseKey := strings.ToLower(strings.TrimSpace(legacyBase))
-	if nameKey != "" && baseKey != "" {
-		for i := range entries {
-			if strings.ToLower(strings.TrimSpace(entries[i].Name)) == nameKey &&
-				strings.ToLower(strings.TrimSpace(entries[i].BaseURL)) == baseKey {
-				return &entries[i]
-			}
-		}
-	}
-	if baseKey != "" {
-		for i := range entries {
-			if strings.ToLower(strings.TrimSpace(entries[i].BaseURL)) == baseKey {
-				return &entries[i]
-			}
-		}
-	}
-	if nameKey != "" {
-		for i := range entries {
-			if strings.ToLower(strings.TrimSpace(entries[i].Name)) == nameKey {
-				return &entries[i]
-			}
-		}
-	}
-	return nil
-}
-
-func (cfg *Config) migrateLegacyAmpConfig(legacy *legacyConfigData) bool {
-	if cfg == nil || legacy == nil {
-		return false
-	}
-	changed := false
-	if cfg.AmpCode.UpstreamURL == "" {
-		if val := strings.TrimSpace(legacy.AmpUpstreamURL); val != "" {
-			cfg.AmpCode.UpstreamURL = val
-			changed = true
-		}
-	}
-	if cfg.AmpCode.UpstreamAPIKey == "" {
-		if val := strings.TrimSpace(legacy.AmpUpstreamAPIKey); val != "" {
-			cfg.AmpCode.UpstreamAPIKey = val
-			changed = true
-		}
-	}
-	if legacy.AmpRestrictManagement != nil {
-		cfg.AmpCode.RestrictManagementToLocalhost = *legacy.AmpRestrictManagement
-		changed = true
-	}
-	if len(cfg.AmpCode.ModelMappings) == 0 && len(legacy.AmpModelMappings) > 0 {
-		cfg.AmpCode.ModelMappings = append([]AmpModelMapping(nil), legacy.AmpModelMappings...)
-		changed = true
-	}
-	return changed
-}
-
-func removeLegacyOpenAICompatAPIKeys(root *yaml.Node) {
-	if root == nil || root.Kind != yaml.MappingNode {
-		return
-	}
-	idx := findMapKeyIndex(root, "openai-compatibility")
-	if idx < 0 || idx+1 >= len(root.Content) {
-		return
-	}
-	seq := root.Content[idx+1]
-	if seq == nil || seq.Kind != yaml.SequenceNode {
-		return
-	}
-	for i := range seq.Content {
-		if seq.Content[i] != nil && seq.Content[i].Kind == yaml.MappingNode {
-			removeMapKey(seq.Content[i], "api-keys")
-		}
-	}
-}
-
-func removeLegacyAmpKeys(root *yaml.Node) {
-	if root == nil || root.Kind != yaml.MappingNode {
-		return
-	}
-	removeMapKey(root, "amp-upstream-url")
-	removeMapKey(root, "amp-upstream-api-key")
-	removeMapKey(root, "amp-restrict-management-to-localhost")
-	removeMapKey(root, "amp-model-mappings")
-}
-
-func removeLegacyGenerativeLanguageKeys(root *yaml.Node) {
-	if root == nil || root.Kind != yaml.MappingNode {
-		return
-	}
-	removeMapKey(root, "generative-language-api-key")
-}
-
-func removeLegacyAuthBlock(root *yaml.Node) {
-	if root == nil || root.Kind != yaml.MappingNode {
-		return
-	}
-	removeMapKey(root, "auth")
-}

internal/config/migration.go

@@ -0,0 +1,198 @@
+package config
+
+import (
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Legacy migration helpers (move deprecated config keys into structured fields).
+type legacyConfigData struct {
+	LegacyGeminiKeys      []string                    `yaml:"generative-language-api-key"`
+	OpenAICompat          []legacyOpenAICompatibility `yaml:"openai-compatibility"`
+	AmpUpstreamURL        string                      `yaml:"amp-upstream-url"`
+	AmpUpstreamAPIKey     string                      `yaml:"amp-upstream-api-key"`
+	AmpRestrictManagement *bool                       `yaml:"amp-restrict-management-to-localhost"`
+	AmpModelMappings      []AmpModelMapping           `yaml:"amp-model-mappings"`
+}
+
+type legacyOpenAICompatibility struct {
+	Name    string   `yaml:"name"`
+	BaseURL string   `yaml:"base-url"`
+	APIKeys []string `yaml:"api-keys"`
+}
+
+func (cfg *Config) migrateLegacyGeminiKeys(legacy []string) bool {
+	if cfg == nil || len(legacy) == 0 {
+		return false
+	}
+	changed := false
+	seen := make(map[string]struct{}, len(cfg.GeminiKey))
+	for i := range cfg.GeminiKey {
+		key := strings.TrimSpace(cfg.GeminiKey[i].APIKey)
+		if key == "" {
+			continue
+		}
+		seen[key] = struct{}{}
+	}
+	for _, raw := range legacy {
+		key := strings.TrimSpace(raw)
+		if key == "" {
+			continue
+		}
+		if _, exists := seen[key]; exists {
+			continue
+		}
+		cfg.GeminiKey = append(cfg.GeminiKey, GeminiKey{APIKey: key})
+		seen[key] = struct{}{}
+		changed = true
+	}
+	return changed
+}
+
+func (cfg *Config) migrateLegacyOpenAICompatibilityKeys(legacy []legacyOpenAICompatibility) bool {
+	if cfg == nil || len(cfg.OpenAICompatibility) == 0 || len(legacy) == 0 {
+		return false
+	}
+	changed := false
+	for _, legacyEntry := range legacy {
+		if len(legacyEntry.APIKeys) == 0 {
+			continue
+		}
+		target := findOpenAICompatTarget(cfg.OpenAICompatibility, legacyEntry.Name, legacyEntry.BaseURL)
+		if target == nil {
+			continue
+		}
+		if mergeLegacyOpenAICompatAPIKeys(target, legacyEntry.APIKeys) {
+			changed = true
+		}
+	}
+	return changed
+}
+
+func mergeLegacyOpenAICompatAPIKeys(entry *OpenAICompatibility, keys []string) bool {
+	if entry == nil || len(keys) == 0 {
+		return false
+	}
+	changed := false
+	existing := make(map[string]struct{}, len(entry.APIKeyEntries))
+	for i := range entry.APIKeyEntries {
+		key := strings.TrimSpace(entry.APIKeyEntries[i].APIKey)
+		if key == "" {
+			continue
+		}
+		existing[key] = struct{}{}
+	}
+	for _, raw := range keys {
+		key := strings.TrimSpace(raw)
+		if key == "" {
+			continue
+		}
+		if _, ok := existing[key]; ok {
+			continue
+		}
+		entry.APIKeyEntries = append(entry.APIKeyEntries, OpenAICompatibilityAPIKey{APIKey: key})
+		existing[key] = struct{}{}
+		changed = true
+	}
+	return changed
+}
+
+func findOpenAICompatTarget(entries []OpenAICompatibility, legacyName, legacyBase string) *OpenAICompatibility {
+	nameKey := strings.ToLower(strings.TrimSpace(legacyName))
+	baseKey := strings.ToLower(strings.TrimSpace(legacyBase))
+	if nameKey != "" && baseKey != "" {
+		for i := range entries {
+			if strings.ToLower(strings.TrimSpace(entries[i].Name)) == nameKey &&
+				strings.ToLower(strings.TrimSpace(entries[i].BaseURL)) == baseKey {
+				return &entries[i]
+			}
+		}
+	}
+	if baseKey != "" {
+		for i := range entries {
+			if strings.ToLower(strings.TrimSpace(entries[i].BaseURL)) == baseKey {
+				return &entries[i]
+			}
+		}
+	}
+	if nameKey != "" {
+		for i := range entries {
+			if strings.ToLower(strings.TrimSpace(entries[i].Name)) == nameKey {
+				return &entries[i]
+			}
+		}
+	}
+	return nil
+}
+
+func (cfg *Config) migrateLegacyAmpConfig(legacy *legacyConfigData) bool {
+	if cfg == nil || legacy == nil {
+		return false
+	}
+	changed := false
+	if cfg.AmpCode.UpstreamURL == "" {
+		if val := strings.TrimSpace(legacy.AmpUpstreamURL); val != "" {
+			cfg.AmpCode.UpstreamURL = val
+			changed = true
+		}
+	}
+	if cfg.AmpCode.UpstreamAPIKey == "" {
+		if val := strings.TrimSpace(legacy.AmpUpstreamAPIKey); val != "" {
+			cfg.AmpCode.UpstreamAPIKey = val
+			changed = true
+		}
+	}
+	if legacy.AmpRestrictManagement != nil {
+		cfg.AmpCode.RestrictManagementToLocalhost = *legacy.AmpRestrictManagement
+		changed = true
+	}
+	if len(cfg.AmpCode.ModelMappings) == 0 && len(legacy.AmpModelMappings) > 0 {
+		cfg.AmpCode.ModelMappings = append([]AmpModelMapping(nil), legacy.AmpModelMappings...)
+		changed = true
+	}
+	return changed
+}
+
+func removeLegacyOpenAICompatAPIKeys(root *yaml.Node) {
+	if root == nil || root.Kind != yaml.MappingNode {
+		return
+	}
+	idx := findMapKeyIndex(root, "openai-compatibility")
+	if idx < 0 || idx+1 >= len(root.Content) {
+		return
+	}
+	seq := root.Content[idx+1]
+	if seq == nil || seq.Kind != yaml.SequenceNode {
+		return
+	}
+	for i := range seq.Content {
+		if seq.Content[i] != nil && seq.Content[i].Kind == yaml.MappingNode {
+			removeMapKey(seq.Content[i], "api-keys")
+		}
+	}
+}
+
+func removeLegacyAmpKeys(root *yaml.Node) {
+	if root == nil || root.Kind != yaml.MappingNode {
+		return
+	}
+	removeMapKey(root, "amp-upstream-url")
+	removeMapKey(root, "amp-upstream-api-key")
+	removeMapKey(root, "amp-restrict-management-to-localhost")
+	removeMapKey(root, "amp-model-mappings")
+}
+
+func removeLegacyGenerativeLanguageKeys(root *yaml.Node) {
+	if root == nil || root.Kind != yaml.MappingNode {
+		return
+	}
+	removeMapKey(root, "generative-language-api-key")
+}
+
+func removeLegacyAuthBlock(root *yaml.Node) {
+	if root == nil || root.Kind != yaml.MappingNode {
+		return
+	}
+	removeMapKey(root, "auth")
+}

internal/config/sanitizer.go

@@ -0,0 +1,316 @@
+package config
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/crypto/bcrypt"
+)
+
+// SanitizePayloadRules validates raw JSON payload rule params and drops invalid rules.
+func (cfg *Config) SanitizePayloadRules() {
+	if cfg == nil {
+		return
+	}
+	cfg.Payload.DefaultRaw = sanitizePayloadRawRules(cfg.Payload.DefaultRaw, "default-raw")
+	cfg.Payload.OverrideRaw = sanitizePayloadRawRules(cfg.Payload.OverrideRaw, "override-raw")
+}
+
+func sanitizePayloadRawRules(rules []PayloadRule, section string) []PayloadRule {
+	if len(rules) == 0 {
+		return rules
+	}
+	out := make([]PayloadRule, 0, len(rules))
+	for i := range rules {
+		rule := rules[i]
+		if len(rule.Params) == 0 {
+			continue
+		}
+		invalid := false
+		for path, value := range rule.Params {
+			raw, ok := payloadRawString(value)
+			if !ok {
+				continue
+			}
+			trimmed := bytes.TrimSpace(raw)
+			if len(trimmed) == 0 || !json.Valid(trimmed) {
+				log.WithFields(log.Fields{
+					"section":    section,
+					"rule_index": i + 1,
+					"param":      path,
+				}).Warn("payload rule dropped: invalid raw JSON")
+				invalid = true
+				break
+			}
+		}
+		if invalid {
+			continue
+		}
+		out = append(out, rule)
+	}
+	return out
+}
+
+func payloadRawString(value any) ([]byte, bool) {
+	switch typed := value.(type) {
+	case string:
+		return []byte(typed), true
+	case []byte:
+		return typed, true
+	default:
+		return nil, false
+	}
+}
+
+// SanitizeOAuthModelAlias normalizes and deduplicates global OAuth model name aliases.
+// It trims whitespace, normalizes channel keys to lower-case, drops empty entries,
+// allows multiple aliases per upstream name, and ensures aliases are unique within each channel.
+func (cfg *Config) SanitizeOAuthModelAlias() {
+	if cfg == nil || len(cfg.OAuthModelAlias) == 0 {
+		return
+	}
+	out := make(map[string][]OAuthModelAlias, len(cfg.OAuthModelAlias))
+	for rawChannel, aliases := range cfg.OAuthModelAlias {
+		channel := strings.ToLower(strings.TrimSpace(rawChannel))
+		if channel == "" || len(aliases) == 0 {
+			continue
+		}
+		seenAlias := make(map[string]struct{}, len(aliases))
+		clean := make([]OAuthModelAlias, 0, len(aliases))
+		for _, entry := range aliases {
+			name := strings.TrimSpace(entry.Name)
+			alias := strings.TrimSpace(entry.Alias)
+			if name == "" || alias == "" {
+				continue
+			}
+			if strings.EqualFold(name, alias) {
+				continue
+			}
+			aliasKey := strings.ToLower(alias)
+			if _, ok := seenAlias[aliasKey]; ok {
+				continue
+			}
+			seenAlias[aliasKey] = struct{}{}
+			clean = append(clean, OAuthModelAlias{Name: name, Alias: alias, Fork: entry.Fork})
+		}
+		if len(clean) > 0 {
+			out[channel] = clean
+		}
+	}
+	cfg.OAuthModelAlias = out
+}
+
+// SanitizeOpenAICompatibility removes OpenAI-compatibility provider entries that are
+// not actionable, specifically those missing a BaseURL. It trims whitespace before
+// evaluation and preserves the relative order of remaining entries.
+func (cfg *Config) SanitizeOpenAICompatibility() {
+	if cfg == nil || len(cfg.OpenAICompatibility) == 0 {
+		return
+	}
+	out := make([]OpenAICompatibility, 0, len(cfg.OpenAICompatibility))
+	for i := range cfg.OpenAICompatibility {
+		e := cfg.OpenAICompatibility[i]
+		e.Name = strings.TrimSpace(e.Name)
+		e.Prefix = normalizeModelPrefix(e.Prefix)
+		e.BaseURL = strings.TrimSpace(e.BaseURL)
+		e.Headers = NormalizeHeaders(e.Headers)
+		if e.BaseURL == "" {
+			// Skip providers with no base-url; treated as removed
+			continue
+		}
+		out = append(out, e)
+	}
+	cfg.OpenAICompatibility = out
+}
+
+// SanitizeCodexKeys removes Codex API key entries missing a BaseURL.
+// It trims whitespace and preserves order for remaining entries.
+func (cfg *Config) SanitizeCodexKeys() {
+	if cfg == nil || len(cfg.CodexKey) == 0 {
+		return
+	}
+	out := make([]CodexKey, 0, len(cfg.CodexKey))
+	for i := range cfg.CodexKey {
+		e := cfg.CodexKey[i]
+		e.Prefix = normalizeModelPrefix(e.Prefix)
+		e.BaseURL = strings.TrimSpace(e.BaseURL)
+		e.Headers = NormalizeHeaders(e.Headers)
+		e.ExcludedModels = NormalizeExcludedModels(e.ExcludedModels)
+		if e.BaseURL == "" {
+			continue
+		}
+		out = append(out, e)
+	}
+	cfg.CodexKey = out
+}
+
+
+// SanitizeClaudeKeys normalizes headers and API key entries for Claude credentials.
+func (cfg *Config) SanitizeClaudeKeys() {
+	if cfg == nil || len(cfg.ClaudeKey) == 0 {
+		return
+	}
+	for i := range cfg.ClaudeKey {
+		entry := &cfg.ClaudeKey[i]
+		entry.Prefix = normalizeModelPrefix(entry.Prefix)
+		entry.Headers = NormalizeHeaders(entry.Headers)
+		entry.ExcludedModels = NormalizeExcludedModels(entry.ExcludedModels)
+		entry.BaseURL = strings.TrimSpace(entry.BaseURL)
+		entry.ProxyURL = strings.TrimSpace(entry.ProxyURL)
+		entry.APIKey = strings.TrimSpace(entry.APIKey)
+		// Sanitize APIKeyEntries
+		for j := range entry.APIKeyEntries {
+			apiKeyEntry := &entry.APIKeyEntries[j]
+			apiKeyEntry.APIKey = strings.TrimSpace(apiKeyEntry.APIKey)
+			apiKeyEntry.ProxyURL = strings.TrimSpace(apiKeyEntry.ProxyURL)
+		}
+	}
+}
+
+// SanitizeGeminiKeys deduplicates and normalizes Gemini credentials.
+func (cfg *Config) SanitizeGeminiKeys() {
+	if cfg == nil {
+		return
+	}
+
+	seen := make(map[string]struct{}, len(cfg.GeminiKey))
+	out := cfg.GeminiKey[:0]
+	for i := range cfg.GeminiKey {
+		entry := cfg.GeminiKey[i]
+		entry.APIKey = strings.TrimSpace(entry.APIKey)
+		if entry.APIKey == "" {
+			continue
+		}
+		entry.Prefix = normalizeModelPrefix(entry.Prefix)
+		entry.BaseURL = strings.TrimSpace(entry.BaseURL)
+		entry.ProxyURL = strings.TrimSpace(entry.ProxyURL)
+		entry.Headers = NormalizeHeaders(entry.Headers)
+		entry.ExcludedModels = NormalizeExcludedModels(entry.ExcludedModels)
+		if _, exists := seen[entry.APIKey]; exists {
+			continue
+		}
+		seen[entry.APIKey] = struct{}{}
+		out = append(out, entry)
+	}
+	cfg.GeminiKey = out
+}
+
+func normalizeModelPrefix(prefix string) string {
+	trimmed := strings.TrimSpace(prefix)
+	trimmed = strings.Trim(trimmed, "/")
+	if trimmed == "" {
+		return ""
+	}
+	if strings.Contains(trimmed, "/") {
+		return ""
+	}
+	return trimmed
+}
+
+func syncInlineAccessProvider(cfg *Config) {
+	if cfg == nil {
+		return
+	}
+	if len(cfg.APIKeys) == 0 {
+		if provider := cfg.ConfigAPIKeyProvider(); provider != nil && len(provider.APIKeys) > 0 {
+			cfg.APIKeys = append([]string(nil), provider.APIKeys...)
+		}
+	}
+	cfg.Access.Providers = nil
+}
+
+// looksLikeBcrypt returns true if the provided string appears to be a bcrypt hash.
+func looksLikeBcrypt(s string) bool {
+	return len(s) > 4 && (s[:4] == "$2a$" || s[:4] == "$2b$" || s[:4] == "$2y$")
+}
+
+// NormalizeHeaders trims header keys and values and removes empty pairs.
+func NormalizeHeaders(headers map[string]string) map[string]string {
+	if len(headers) == 0 {
+		return nil
+	}
+	clean := make(map[string]string, len(headers))
+	for k, v := range headers {
+		key := strings.TrimSpace(k)
+		val := strings.TrimSpace(v)
+		if key == "" || val == "" {
+			continue
+		}
+		clean[key] = val
+	}
+	if len(clean) == 0 {
+		return nil
+	}
+	return clean
+}
+
+// NormalizeExcludedModels trims, lowercases, and deduplicates model exclusion patterns.
+// It preserves the order of first occurrences and drops empty entries.
+func NormalizeExcludedModels(models []string) []string {
+	if len(models) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(models))
+	out := make([]string, 0, len(models))
+	for _, raw := range models {
+		trimmed := strings.ToLower(strings.TrimSpace(raw))
+		if trimmed == "" {
+			continue
+		}
+		if _, exists := seen[trimmed]; exists {
+			continue
+		}
+		seen[trimmed] = struct{}{}
+		out = append(out, trimmed)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// NormalizeOAuthExcludedModels cleans provider -> excluded models mappings by normalizing provider keys
+// and applying model exclusion normalization to each entry.
+func NormalizeOAuthExcludedModels(entries map[string][]string) map[string][]string {
+	if len(entries) == 0 {
+		return nil
+	}
+	out := make(map[string][]string, len(entries))
+	for provider, models := range entries {
+		key := strings.ToLower(strings.TrimSpace(provider))
+		if key == "" {
+			continue
+		}
+		normalized := NormalizeExcludedModels(models)
+		if len(normalized) == 0 {
+			continue
+		}
+		out[key] = normalized
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// hashSecret hashes the given secret using bcrypt.
+func hashSecret(secret string) (string, error) {
+	// Use default cost for simplicity.
+	hashedBytes, err := bcrypt.GenerateFromPassword([]byte(secret), bcrypt.DefaultCost)
+	if err != nil {
+		return "", err
+	}
+	return string(hashedBytes), nil
+}
+
+func sanitizeConfigForPersist(cfg *Config) *Config {
+	if cfg == nil {
+		return nil
+	}
+	clone := *cfg
+	clone.SDKConfig = cfg.SDKConfig
+	clone.SDKConfig.Access = AccessConfig{}
+	return &clone
+}

internal/config/yaml_utils.go

@@ -0,0 +1,615 @@
+package config
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// SaveConfigPreserveComments writes the config back to YAML while preserving existing comments
+// and key ordering by loading the original file into a yaml.Node tree and updating values in-place.
+func SaveConfigPreserveComments(configFile string, cfg *Config) error {
+	persistCfg := sanitizeConfigForPersist(cfg)
+	// Load original YAML as a node tree to preserve comments and ordering.
+	data, err := os.ReadFile(configFile)
+	if err != nil {
+		return err
+	}
+
+	var original yaml.Node
+	if err = yaml.Unmarshal(data, &original); err != nil {
+		return err
+	}
+	if original.Kind != yaml.DocumentNode || len(original.Content) == 0 {
+		return fmt.Errorf("invalid yaml document structure")
+	}
+	if original.Content[0] == nil || original.Content[0].Kind != yaml.MappingNode {
+		return fmt.Errorf("expected root mapping node")
+	}
+
+	// Marshal the current cfg to YAML, then unmarshal to a yaml.Node we can merge from.
+	rendered, err := yaml.Marshal(persistCfg)
+	if err != nil {
+		return err
+	}
+	var generated yaml.Node
+	if err = yaml.Unmarshal(rendered, &generated); err != nil {
+		return err
+	}
+	if generated.Kind != yaml.DocumentNode || len(generated.Content) == 0 || generated.Content[0] == nil {
+		return fmt.Errorf("invalid generated yaml structure")
+	}
+	if generated.Content[0].Kind != yaml.MappingNode {
+		return fmt.Errorf("expected generated root mapping node")
+	}
+
+	// Remove deprecated sections before merging back the sanitized config.
+	removeLegacyAuthBlock(original.Content[0])
+	removeLegacyOpenAICompatAPIKeys(original.Content[0])
+	removeLegacyAmpKeys(original.Content[0])
+	removeLegacyGenerativeLanguageKeys(original.Content[0])
+
+	pruneMappingToGeneratedKeys(original.Content[0], generated.Content[0], "oauth-excluded-models")
+
+	// Merge generated into original in-place, preserving comments/order of existing nodes.
+	mergeMappingPreserve(original.Content[0], generated.Content[0])
+	normalizeCollectionNodeStyles(original.Content[0])
+
+	// Write back.
+	f, err := os.Create(configFile)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	if err = enc.Encode(&original); err != nil {
+		_ = enc.Close()
+		return err
+	}
+	if err = enc.Close(); err != nil {
+		return err
+	}
+	data = NormalizeCommentIndentation(buf.Bytes())
+	_, err = f.Write(data)
+	return err
+}
+
+// SaveConfigPreserveCommentsUpdateNestedScalar updates a nested scalar key path like ["a","b"]
+// while preserving comments and positions.
+func SaveConfigPreserveCommentsUpdateNestedScalar(configFile string, path []string, value string) error {
+	data, err := os.ReadFile(configFile)
+	if err != nil {
+		return err
+	}
+	var root yaml.Node
+	if err = yaml.Unmarshal(data, &root); err != nil {
+		return err
+	}
+	if root.Kind != yaml.DocumentNode || len(root.Content) == 0 {
+		return fmt.Errorf("invalid yaml document structure")
+	}
+	node := root.Content[0]
+	// descend mapping nodes following path
+	for i, key := range path {
+		if i == len(path)-1 {
+			// set final scalar
+			v := getOrCreateMapValue(node, key)
+			v.Kind = yaml.ScalarNode
+			v.Tag = "!!str"
+			v.Value = value
+		} else {
+			next := getOrCreateMapValue(node, key)
+			if next.Kind != yaml.MappingNode {
+				next.Kind = yaml.MappingNode
+				next.Tag = "!!map"
+			}
+			node = next
+		}
+	}
+	f, err := os.Create(configFile)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	if err = enc.Encode(&root); err != nil {
+		_ = enc.Close()
+		return err
+	}
+	if err = enc.Close(); err != nil {
+		return err
+	}
+	data = NormalizeCommentIndentation(buf.Bytes())
+	_, err = f.Write(data)
+	return err
+}
+
+// NormalizeCommentIndentation removes indentation from standalone YAML comment lines to keep them left aligned.
+func NormalizeCommentIndentation(data []byte) []byte {
+	lines := bytes.Split(data, []byte("\n"))
+	changed := false
+	for i, line := range lines {
+		trimmed := bytes.TrimLeft(line, " \t")
+		if len(trimmed) == 0 || trimmed[0] != '#' {
+			continue
+		}
+		if len(trimmed) == len(line) {
+			continue
+		}
+		lines[i] = append([]byte(nil), trimmed...)
+		changed = true
+	}
+	if !changed {
+		return data
+	}
+	return bytes.Join(lines, []byte("\n"))
+}
+
+// getOrCreateMapValue finds the value node for a given key in a mapping node.
+// If not found, it appends a new key/value pair and returns the new value node.
+func getOrCreateMapValue(mapNode *yaml.Node, key string) *yaml.Node {
+	if mapNode.Kind != yaml.MappingNode {
+		mapNode.Kind = yaml.MappingNode
+		mapNode.Tag = "!!map"
+		mapNode.Content = nil
+	}
+	for i := 0; i+1 < len(mapNode.Content); i += 2 {
+		k := mapNode.Content[i]
+		if k.Value == key {
+			return mapNode.Content[i+1]
+		}
+	}
+	// append new key/value
+	mapNode.Content = append(mapNode.Content, &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: key})
+	val := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: ""}
+	mapNode.Content = append(mapNode.Content, val)
+	return val
+}
+
+// mergeMappingPreserve merges keys from src into dst mapping node while preserving
+// key order and comments of existing keys in dst. New keys are only added if their
+// value is non-zero to avoid polluting the config with defaults.
+func mergeMappingPreserve(dst, src *yaml.Node) {
+	if dst == nil || src == nil {
+		return
+	}
+	if dst.Kind != yaml.MappingNode || src.Kind != yaml.MappingNode {
+		// If kinds do not match, prefer replacing dst with src semantics in-place
+		// but keep dst node object to preserve any attached comments at the parent level.
+		copyNodeShallow(dst, src)
+		return
+	}
+	for i := 0; i+1 < len(src.Content); i += 2 {
+		sk := src.Content[i]
+		sv := src.Content[i+1]
+		idx := findMapKeyIndex(dst, sk.Value)
+		if idx >= 0 {
+			// Merge into existing value node (always update, even to zero values)
+			dv := dst.Content[idx+1]
+			mergeNodePreserve(dv, sv)
+		} else {
+			// New key: only add if value is non-zero to avoid polluting config with defaults
+			if isZeroValueNode(sv) {
+				continue
+			}
+			dst.Content = append(dst.Content, deepCopyNode(sk), deepCopyNode(sv))
+		}
+	}
+}
+
+// mergeNodePreserve merges src into dst for scalars, mappings and sequences while
+// reusing destination nodes to keep comments and anchors. For sequences, it updates
+// in-place by index.
+func mergeNodePreserve(dst, src *yaml.Node) {
+	if dst == nil || src == nil {
+		return
+	}
+	switch src.Kind {
+	case yaml.MappingNode:
+		if dst.Kind != yaml.MappingNode {
+			copyNodeShallow(dst, src)
+		}
+		mergeMappingPreserve(dst, src)
+	case yaml.SequenceNode:
+		// Preserve explicit null style if dst was null and src is empty sequence
+		if dst.Kind == yaml.ScalarNode && dst.Tag == "!!null" && len(src.Content) == 0 {
+			// Keep as null to preserve original style
+			return
+		}
+		if dst.Kind != yaml.SequenceNode {
+			dst.Kind = yaml.SequenceNode
+			dst.Tag = "!!seq"
+			dst.Content = nil
+		}
+		reorderSequenceForMerge(dst, src)
+		// Update elements in place
+		minContent := len(dst.Content)
+		if len(src.Content) < minContent {
+			minContent = len(src.Content)
+		}
+		for i := 0; i < minContent; i++ {
+			if dst.Content[i] == nil {
+				dst.Content[i] = deepCopyNode(src.Content[i])
+				continue
+			}
+			mergeNodePreserve(dst.Content[i], src.Content[i])
+			if dst.Content[i] != nil && src.Content[i] != nil &&
+				dst.Content[i].Kind == yaml.MappingNode && src.Content[i].Kind == yaml.MappingNode {
+				pruneMissingMapKeys(dst.Content[i], src.Content[i])
+			}
+		}
+		// Append any extra items from src
+		for i := len(dst.Content); i < len(src.Content); i++ {
+			dst.Content = append(dst.Content, deepCopyNode(src.Content[i]))
+		}
+		// Truncate if dst has extra items not in src
+		if len(src.Content) < len(dst.Content) {
+			dst.Content = dst.Content[:len(src.Content)]
+		}
+	case yaml.ScalarNode, yaml.AliasNode:
+		// For scalars, update Tag and Value but keep Style from dst to preserve quoting
+		dst.Kind = src.Kind
+		dst.Tag = src.Tag
+		dst.Value = src.Value
+		// Keep dst.Style as-is intentionally
+	case 0:
+		// Unknown/empty kind; do nothing
+	default:
+		// Fallback: replace shallowly
+		copyNodeShallow(dst, src)
+	}
+}
+
+// findMapKeyIndex returns the index of key node in dst mapping (index of key, not value).
+// Returns -1 when not found.
+func findMapKeyIndex(mapNode *yaml.Node, key string) int {
+	if mapNode == nil || mapNode.Kind != yaml.MappingNode {
+		return -1
+	}
+	for i := 0; i+1 < len(mapNode.Content); i += 2 {
+		if mapNode.Content[i] != nil && mapNode.Content[i].Value == key {
+			return i
+		}
+	}
+	return -1
+}
+
+// isZeroValueNode returns true if the YAML node represents a zero/default value
+// that should not be written as a new key to preserve config cleanliness.
+// For mappings and sequences, recursively checks if all children are zero values.
+func isZeroValueNode(node *yaml.Node) bool {
+	if node == nil {
+		return true
+	}
+	switch node.Kind {
+	case yaml.ScalarNode:
+		switch node.Tag {
+		case "!!bool":
+			return node.Value == "false"
+		case "!!int", "!!float":
+			return node.Value == "0" || node.Value == "0.0"
+		case "!!str":
+			return node.Value == ""
+		case "!!null":
+			return true
+		}
+	case yaml.SequenceNode:
+		if len(node.Content) == 0 {
+			return true
+		}
+		// Check if all elements are zero values
+		for _, child := range node.Content {
+			if !isZeroValueNode(child) {
+				return false
+			}
+		}
+		return true
+	case yaml.MappingNode:
+		if len(node.Content) == 0 {
+			return true
+		}
+		// Check if all values are zero values (values are at odd indices)
+		for i := 1; i < len(node.Content); i += 2 {
+			if !isZeroValueNode(node.Content[i]) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+// deepCopyNode creates a deep copy of a yaml.Node graph.
+func deepCopyNode(n *yaml.Node) *yaml.Node {
+	if n == nil {
+		return nil
+	}
+	cp := *n
+	if len(n.Content) > 0 {
+		cp.Content = make([]*yaml.Node, len(n.Content))
+		for i := range n.Content {
+			cp.Content[i] = deepCopyNode(n.Content[i])
+		}
+	}
+	return &cp
+}
+
+// copyNodeShallow copies type/tag/value and resets content to match src, but
+// keeps the same destination node pointer to preserve parent relations/comments.
+func copyNodeShallow(dst, src *yaml.Node) {
+	if dst == nil || src == nil {
+		return
+	}
+	dst.Kind = src.Kind
+	dst.Tag = src.Tag
+	dst.Value = src.Value
+	// Replace content with deep copy from src
+	if len(src.Content) > 0 {
+		dst.Content = make([]*yaml.Node, len(src.Content))
+		for i := range src.Content {
+			dst.Content[i] = deepCopyNode(src.Content[i])
+		}
+	} else {
+		dst.Content = nil
+	}
+}
+
+func reorderSequenceForMerge(dst, src *yaml.Node) {
+	if dst == nil || src == nil {
+		return
+	}
+	if len(dst.Content) == 0 {
+		return
+	}
+	if len(src.Content) == 0 {
+		return
+	}
+	original := append([]*yaml.Node(nil), dst.Content...)
+	used := make([]bool, len(original))
+	ordered := make([]*yaml.Node, len(src.Content))
+	for i := range src.Content {
+		if idx := matchSequenceElement(original, used, src.Content[i]); idx >= 0 {
+			ordered[i] = original[idx]
+			used[idx] = true
+		}
+	}
+	dst.Content = ordered
+}
+
+func matchSequenceElement(original []*yaml.Node, used []bool, target *yaml.Node) int {
+	if target == nil {
+		return -1
+	}
+	switch target.Kind {
+	case yaml.MappingNode:
+		id := sequenceElementIdentity(target)
+		if id != "" {
+			for i := range original {
+				if used[i] || original[i] == nil || original[i].Kind != yaml.MappingNode {
+					continue
+				}
+				if sequenceElementIdentity(original[i]) == id {
+					return i
+				}
+			}
+		}
+	case yaml.ScalarNode:
+		val := strings.TrimSpace(target.Value)
+		if val != "" {
+			for i := range original {
+				if used[i] || original[i] == nil || original[i].Kind != yaml.ScalarNode {
+					continue
+				}
+				if strings.TrimSpace(original[i].Value) == val {
+					return i
+				}
+			}
+		}
+	default:
+	}
+	// Fallback to structural equality to preserve nodes lacking explicit identifiers.
+	for i := range original {
+		if used[i] || original[i] == nil {
+			continue
+		}
+		if nodesStructurallyEqual(original[i], target) {
+			return i
+		}
+	}
+	return -1
+}
+
+func sequenceElementIdentity(node *yaml.Node) string {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return ""
+	}
+	identityKeys := []string{"id", "name", "alias", "api-key", "api_key", "apikey", "key", "provider", "model"}
+	for _, k := range identityKeys {
+		if v := mappingScalarValue(node, k); v != "" {
+			return k + "=" + v
+		}
+	}
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		valNode := node.Content[i+1]
+		if keyNode == nil || valNode == nil || valNode.Kind != yaml.ScalarNode {
+			continue
+		}
+		val := strings.TrimSpace(valNode.Value)
+		if val != "" {
+			return strings.ToLower(strings.TrimSpace(keyNode.Value)) + "=" + val
+		}
+	}
+	return ""
+}
+
+func mappingScalarValue(node *yaml.Node, key string) string {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return ""
+	}
+	lowerKey := strings.ToLower(key)
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		valNode := node.Content[i+1]
+		if keyNode == nil || valNode == nil || valNode.Kind != yaml.ScalarNode {
+			continue
+		}
+		if strings.ToLower(strings.TrimSpace(keyNode.Value)) == lowerKey {
+			return strings.TrimSpace(valNode.Value)
+		}
+	}
+	return ""
+}
+
+func nodesStructurallyEqual(a, b *yaml.Node) bool {
+	if a == nil || b == nil {
+		return a == b
+	}
+	if a.Kind != b.Kind {
+		return false
+	}
+	switch a.Kind {
+	case yaml.MappingNode:
+		if len(a.Content) != len(b.Content) {
+			return false
+		}
+		for i := 0; i+1 < len(a.Content); i += 2 {
+			if !nodesStructurallyEqual(a.Content[i], b.Content[i]) {
+				return false
+			}
+			if !nodesStructurallyEqual(a.Content[i+1], b.Content[i+1]) {
+				return false
+			}
+		}
+		return true
+	case yaml.SequenceNode:
+		if len(a.Content) != len(b.Content) {
+			return false
+		}
+		for i := range a.Content {
+			if !nodesStructurallyEqual(a.Content[i], b.Content[i]) {
+				return false
+			}
+		}
+		return true
+	case yaml.ScalarNode:
+		return strings.TrimSpace(a.Value) == strings.TrimSpace(b.Value)
+	case yaml.AliasNode:
+		return nodesStructurallyEqual(a.Alias, b.Alias)
+	default:
+		return strings.TrimSpace(a.Value) == strings.TrimSpace(b.Value)
+	}
+}
+
+func removeMapKey(mapNode *yaml.Node, key string) {
+	if mapNode == nil || mapNode.Kind != yaml.MappingNode || key == "" {
+		return
+	}
+	for i := 0; i+1 < len(mapNode.Content); i += 2 {
+		if mapNode.Content[i] != nil && mapNode.Content[i].Value == key {
+			mapNode.Content = append(mapNode.Content[:i], mapNode.Content[i+2:]...)
+			return
+		}
+	}
+}
+
+func pruneMappingToGeneratedKeys(dstRoot, srcRoot *yaml.Node, key string) {
+	if key == "" || dstRoot == nil || srcRoot == nil {
+		return
+	}
+	if dstRoot.Kind != yaml.MappingNode || srcRoot.Kind != yaml.MappingNode {
+		return
+	}
+	dstIdx := findMapKeyIndex(dstRoot, key)
+	if dstIdx < 0 || dstIdx+1 >= len(dstRoot.Content) {
+		return
+	}
+	srcIdx := findMapKeyIndex(srcRoot, key)
+	if srcIdx < 0 {
+		removeMapKey(dstRoot, key)
+		return
+	}
+	if srcIdx+1 >= len(srcRoot.Content) {
+		return
+	}
+	srcVal := srcRoot.Content[srcIdx+1]
+	dstVal := dstRoot.Content[dstIdx+1]
+	if srcVal == nil {
+		dstRoot.Content[dstIdx+1] = nil
+		return
+	}
+	if srcVal.Kind != yaml.MappingNode {
+		dstRoot.Content[dstIdx+1] = deepCopyNode(srcVal)
+		return
+	}
+	if dstVal == nil || dstVal.Kind != yaml.MappingNode {
+		dstRoot.Content[dstIdx+1] = deepCopyNode(srcVal)
+		return
+	}
+	pruneMissingMapKeys(dstVal, srcVal)
+}
+
+func pruneMissingMapKeys(dstMap, srcMap *yaml.Node) {
+	if dstMap == nil || srcMap == nil || dstMap.Kind != yaml.MappingNode || srcMap.Kind != yaml.MappingNode {
+		return
+	}
+	keep := make(map[string]struct{}, len(srcMap.Content)/2)
+	for i := 0; i+1 < len(srcMap.Content); i += 2 {
+		keyNode := srcMap.Content[i]
+		if keyNode == nil {
+			continue
+		}
+		key := strings.TrimSpace(keyNode.Value)
+		if key == "" {
+			continue
+		}
+		keep[key] = struct{}{}
+	}
+	for i := 0; i+1 < len(dstMap.Content); {
+		keyNode := dstMap.Content[i]
+		if keyNode == nil {
+			i += 2
+			continue
+		}
+		key := strings.TrimSpace(keyNode.Value)
+		if _, ok := keep[key]; !ok {
+			dstMap.Content = append(dstMap.Content[:i], dstMap.Content[i+2:]...)
+			continue
+		}
+		i += 2
+	}
+}
+
+// normalizeCollectionNodeStyles forces YAML collections to use block notation, keeping
+// lists and maps readable. Empty sequences retain flow style ([]) so empty list markers
+// remain compact.
+func normalizeCollectionNodeStyles(node *yaml.Node) {
+	if node == nil {
+		return
+	}
+	switch node.Kind {
+	case yaml.MappingNode:
+		node.Style = 0
+		for i := range node.Content {
+			normalizeCollectionNodeStyles(node.Content[i])
+		}
+	case yaml.SequenceNode:
+		if len(node.Content) == 0 {
+			node.Style = yaml.FlowStyle
+		} else {
+			node.Style = 0
+		}
+		for i := range node.Content {
+			normalizeCollectionNodeStyles(node.Content[i])
+		}
+	default:
+		// Scalars keep their existing style to preserve quoting
+	}
+}

internal/runtime/executor/gemini_vertex_executor.go

@@ -30,144 +30,10 @@ import (
 const (
 	// vertexAPIVersion aligns with current public Vertex Generative AI API.
 	vertexAPIVersion = "v1"
-)
-
-// isImagenModel checks if the model name is an Imagen image generation model.
-// Imagen models use the :predict action instead of :generateContent.
-func isImagenModel(model string) bool {
-	lowerModel := strings.ToLower(model)
-	return strings.Contains(lowerModel, "imagen")
-}
-
-// getVertexAction returns the appropriate action for the given model.
-// Imagen models use "predict", while Gemini models use "generateContent".
-func getVertexAction(model string, isStream bool) string {
-	if isImagenModel(model) {
-		return "predict"
-	}
-	if isStream {
-		return "streamGenerateContent"
-	}
-	return "generateContent"
-}
-
-// convertImagenToGeminiResponse converts Imagen API response to Gemini format
-// so it can be processed by the standard translation pipeline.
-// This ensures Imagen models return responses in the same format as gemini-3-pro-image-preview.
-func convertImagenToGeminiResponse(data []byte, model string) []byte {
-	predictions := gjson.GetBytes(data, "predictions")
-	if !predictions.Exists() || !predictions.IsArray() {
-		return data
-	}
-
-	// Build Gemini-compatible response with inlineData
-	parts := make([]map[string]any, 0)
-	for _, pred := range predictions.Array() {
-		imageData := pred.Get("bytesBase64Encoded").String()
-		mimeType := pred.Get("mimeType").String()
-		if mimeType == "" {
-			mimeType = "image/png"
-		}
-		if imageData != "" {
-			parts = append(parts, map[string]any{
-				"inlineData": map[string]any{
-					"mimeType": mimeType,
-					"data":     imageData,
-				},
-			})
-		}
-	}
-
-	// Generate unique response ID using timestamp
-	responseId := fmt.Sprintf("imagen-%d", time.Now().UnixNano())
-
-	response := map[string]any{
-		"candidates": []map[string]any{{
-			"content": map[string]any{
-				"parts": parts,
-				"role":  "model",
-			},
-			"finishReason": "STOP",
-		}},
-		"responseId":   responseId,
-		"modelVersion": model,
-		// Imagen API doesn't return token counts, set to 0 for tracking purposes
-		"usageMetadata": map[string]any{
-			"promptTokenCount":     0,
-			"candidatesTokenCount": 0,
-			"totalTokenCount":      0,
-		},
-	}
-
-	result, err := json.Marshal(response)
-	if err != nil {
-		return data
-	}
-	return result
-}
-
-// convertToImagenRequest converts a Gemini-style request to Imagen API format.
-// Imagen API uses a different structure: instances[].prompt instead of contents[].
-func convertToImagenRequest(payload []byte) ([]byte, error) {
-	// Extract prompt from Gemini-style contents
-	prompt := ""
-
-	// Try to get prompt from contents[0].parts[0].text
-	contentsText := gjson.GetBytes(payload, "contents.0.parts.0.text")
-	if contentsText.Exists() {
-		prompt = contentsText.String()
-	}
-
-	// If no contents, try messages format (OpenAI-compatible)
-	if prompt == "" {
-		messagesText := gjson.GetBytes(payload, "messages.#.content")
-		if messagesText.Exists() && messagesText.IsArray() {
-			for _, msg := range messagesText.Array() {
-				if msg.String() != "" {
-					prompt = msg.String()
-					break
-				}
-			}
-		}
-	}
-
-	// If still no prompt, try direct prompt field
-	if prompt == "" {
-		directPrompt := gjson.GetBytes(payload, "prompt")
-		if directPrompt.Exists() {
-			prompt = directPrompt.String()
-		}
-	}
-
-	if prompt == "" {
-		return nil, fmt.Errorf("imagen: no prompt found in request")
-	}
 
-	// Build Imagen API request
-	imagenReq := map[string]any{
-		"instances": []map[string]any{
-			{
-				"prompt": prompt,
-			},
-		},
-		"parameters": map[string]any{
-			"sampleCount": 1,
-		},
-	}
-
-	// Extract optional parameters
-	if aspectRatio := gjson.GetBytes(payload, "aspectRatio"); aspectRatio.Exists() {
-		imagenReq["parameters"].(map[string]any)["aspectRatio"] = aspectRatio.String()
-	}
-	if sampleCount := gjson.GetBytes(payload, "sampleCount"); sampleCount.Exists() {
-		imagenReq["parameters"].(map[string]any)["sampleCount"] = int(sampleCount.Int())
-	}
-	if negativePrompt := gjson.GetBytes(payload, "negativePrompt"); negativePrompt.Exists() {
-		imagenReq["instances"].([]map[string]any)[0]["negativePrompt"] = negativePrompt.String()
-	}
-
-	return json.Marshal(imagenReq)
-}
+	// defaultVertexLocation is the default location for Vertex AI resources.
+	defaultVertexLocation = "us-central1"
+)
 
 // GeminiVertexExecutor sends requests to Vertex AI Gemini endpoints using service account credentials.
 type GeminiVertexExecutor struct {
@@ -175,12 +41,6 @@ type GeminiVertexExecutor struct {
 }
 
 // NewGeminiVertexExecutor creates a new Vertex AI Gemini executor instance.
-//
-// Parameters:
-//   - cfg: The application configuration
-//
-// Returns:
-//   - *GeminiVertexExecutor: A new Vertex AI Gemini executor instance
 func NewGeminiVertexExecutor(cfg *config.Config) *GeminiVertexExecutor {
 	return &GeminiVertexExecutor{cfg: cfg}
 }
@@ -188,31 +48,28 @@ func NewGeminiVertexExecutor(cfg *config.Config) *GeminiVertexExecutor {
 // Identifier returns the executor identifier.
 func (e *GeminiVertexExecutor) Identifier() string { return "vertex" }
 
+// vertexContext holds resolved configuration and credentials for a request.
+type vertexContext struct {
+	IsAPIKey           bool
+	APIKey             string
+	ProjectID          string
+	Location           string
+	ServiceAccountJSON []byte
+	BaseURL            string
+	CompatConfig       *config.VertexCompatKey
+}
+
 // PrepareRequest injects Vertex credentials into the outgoing HTTP request.
 func (e *GeminiVertexExecutor) PrepareRequest(req *http.Request, auth *cliproxyauth.Auth) error {
 	if req == nil {
 		return nil
 	}
-	apiKey, _ := vertexAPICreds(auth)
-	if strings.TrimSpace(apiKey) != "" {
-		req.Header.Set("x-goog-api-key", apiKey)
-		req.Header.Del("Authorization")
-		return nil
-	}
-	_, _, saJSON, errCreds := vertexCreds(auth)
-	if errCreds != nil {
-		return errCreds
-	}
-	token, errToken := vertexAccessToken(req.Context(), e.cfg, auth, saJSON)
-	if errToken != nil {
-		return errToken
-	}
-	if strings.TrimSpace(token) == "" {
-		return statusErr{code: http.StatusUnauthorized, msg: "missing access token"}
+	ctx := req.Context()
+	vCtx, err := e.resolveVertexContext(auth)
+	if err != nil {
+		return err
 	}
-	req.Header.Set("Authorization", "Bearer "+token)
-	req.Header.Del("x-goog-api-key")
-	return nil
+	return e.setVertexHeaders(ctx, req, vCtx, auth)
 }
 
 // HttpRequest injects Vertex credentials into the request and executes it.
@@ -233,101 +90,18 @@ func (e *GeminiVertexExecutor) HttpRequest(ctx context.Context, auth *cliproxyau
 
 // Execute performs a non-streaming request to the Vertex AI API.
 func (e *GeminiVertexExecutor) Execute(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (resp cliproxyexecutor.Response, err error) {
-	// Try API key authentication first
-	apiKey, baseURL := vertexAPICreds(auth)
-
-	// If no API key found, fall back to service account authentication
-	if apiKey == "" {
-		projectID, location, saJSON, errCreds := vertexCreds(auth)
-		if errCreds != nil {
-			return resp, errCreds
-		}
-		return e.executeWithServiceAccount(ctx, auth, req, opts, projectID, location, saJSON)
-	}
-
-	// Use API key authentication
-	return e.executeWithAPIKey(ctx, auth, req, opts, apiKey, baseURL)
-}
-
-// ExecuteStream performs a streaming request to the Vertex AI API.
-func (e *GeminiVertexExecutor) ExecuteStream(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (stream <-chan cliproxyexecutor.StreamChunk, err error) {
-	// Try API key authentication first
-	apiKey, baseURL := vertexAPICreds(auth)
-
-	// If no API key found, fall back to service account authentication
-	if apiKey == "" {
-		projectID, location, saJSON, errCreds := vertexCreds(auth)
-		if errCreds != nil {
-			return nil, errCreds
-		}
-		return e.executeStreamWithServiceAccount(ctx, auth, req, opts, projectID, location, saJSON)
-	}
-
-	// Use API key authentication
-	return e.executeStreamWithAPIKey(ctx, auth, req, opts, apiKey, baseURL)
-}
-
-// CountTokens counts tokens for the given request using the Vertex AI API.
-func (e *GeminiVertexExecutor) CountTokens(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error) {
-	// Try API key authentication first
-	apiKey, baseURL := vertexAPICreds(auth)
-
-	// If no API key found, fall back to service account authentication
-	if apiKey == "" {
-		projectID, location, saJSON, errCreds := vertexCreds(auth)
-		if errCreds != nil {
-			return cliproxyexecutor.Response{}, errCreds
-		}
-		return e.countTokensWithServiceAccount(ctx, auth, req, opts, projectID, location, saJSON)
+	vCtx, err := e.resolveVertexContext(auth)
+	if err != nil {
+		return resp, err
 	}
 
-	// Use API key authentication
-	return e.countTokensWithAPIKey(ctx, auth, req, opts, apiKey, baseURL)
-}
-
-// Refresh refreshes the authentication credentials (no-op for Vertex).
-func (e *GeminiVertexExecutor) Refresh(_ context.Context, auth *cliproxyauth.Auth) (*cliproxyauth.Auth, error) {
-	return auth, nil
-}
-
-// executeWithServiceAccount handles authentication using service account credentials.
-// This method contains the original service account authentication logic.
-func (e *GeminiVertexExecutor) executeWithServiceAccount(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, projectID, location string, saJSON []byte) (resp cliproxyexecutor.Response, err error) {
 	baseModel := thinking.ParseSuffix(req.Model).ModelName
-
 	reporter := newUsageReporter(ctx, e.Identifier(), baseModel, auth)
 	defer reporter.trackFailure(ctx, &err)
 
-	var body []byte
-
-	// Handle Imagen models with special request format
-	if isImagenModel(baseModel) {
-		imagenBody, errImagen := convertToImagenRequest(req.Payload)
-		if errImagen != nil {
-			return resp, errImagen
-		}
-		body = imagenBody
-	} else {
-		// Standard Gemini translation flow
-		from := opts.SourceFormat
-		to := sdktranslator.FromString("gemini")
-
-		originalPayload := bytes.Clone(req.Payload)
-		if len(opts.OriginalRequest) > 0 {
-			originalPayload = bytes.Clone(opts.OriginalRequest)
-		}
-		originalTranslated := sdktranslator.TranslateRequest(from, to, baseModel, originalPayload, false)
-		body = sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), false)
-
-		body, err = thinking.ApplyThinking(body, req.Model, from.String(), to.String(), e.Identifier())
-		if err != nil {
-			return resp, err
-		}
-
-		body = fixGeminiImageAspectRatio(baseModel, body)
-		requestedModel := payloadRequestedModel(opts, req.Model)
-		body = applyPayloadConfigWithRoot(e.cfg, baseModel, to.String(), "", body, originalTranslated, requestedModel)
-		body, _ = sjson.SetBytes(body, "model", baseModel)
+	body, _, err := e.preparePayload(ctx, req, opts, baseModel, false)
+	if err != nil {
+		return resp, err
 	}
 
 	action := getVertexAction(baseModel, false)
@@ -336,43 +110,19 @@ func (e *GeminiVertexExecutor) executeWithServiceAccount(ctx context.Context, au
 			action = "countTokens"
 		}
 	}
-	baseURL := vertexBaseURL(location)
-	url := fmt.Sprintf("%s/%s/projects/%s/locations/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, projectID, location, baseModel, action)
-	if opts.Alt != "" && action != "countTokens" {
-		url = url + fmt.Sprintf("?$alt=%s", opts.Alt)
-	}
+
+	url := e.buildVertexURL(vCtx, baseModel, action, opts.Alt)
 	body, _ = sjson.DeleteBytes(body, "session_id")
 
 	httpReq, errNewReq := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
 	if errNewReq != nil {
 		return resp, errNewReq
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if token, errTok := vertexAccessToken(ctx, e.cfg, auth, saJSON); errTok == nil && token != "" {
-		httpReq.Header.Set("Authorization", "Bearer "+token)
-	} else if errTok != nil {
-		log.Errorf("vertex executor: access token error: %v", errTok)
-		return resp, statusErr{code: 500, msg: "internal server error"}
-	}
-	applyGeminiHeaders(httpReq, auth)
 
-	var authID, authLabel, authType, authValue string
-	if auth != nil {
-		authID = auth.ID
-		authLabel = auth.Label
-		authType, authValue = auth.AccountInfo()
+	if err := e.setVertexHeaders(ctx, httpReq, vCtx, auth); err != nil {
+		return resp, err
 	}
-	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      body,
-		Provider:  e.Identifier(),
-		AuthID:    authID,
-		AuthLabel: authLabel,
-		AuthType:  authType,
-		AuthValue: authValue,
-	})
+	e.recordRequest(ctx, httpReq, body, auth)
 
 	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
 	httpResp, errDo := httpClient.Do(httpReq)
@@ -385,14 +135,12 @@ func (e *GeminiVertexExecutor) executeWithServiceAccount(ctx context.Context, au
 			log.Errorf("vertex executor: close response body error: %v", errClose)
 		}
 	}()
+
 	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
 	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		err = statusErr{code: httpResp.StatusCode, msg: string(b)}
-		return resp, err
+		return resp, e.handleErrorResponse(ctx, httpResp)
 	}
+
 	data, errRead := io.ReadAll(httpResp.Body)
 	if errRead != nil {
 		recordAPIResponseError(ctx, e.cfg, errRead)
@@ -401,13 +149,11 @@ func (e *GeminiVertexExecutor) executeWithServiceAccount(ctx context.Context, au
 	appendAPIResponseChunk(ctx, e.cfg, data)
 	reporter.publish(ctx, parseGeminiUsage(data))
 
-	// For Imagen models, convert response to Gemini format before translation
-	// This ensures Imagen responses use the same format as gemini-3-pro-image-preview
+	// Handle Imagen models conversion
 	if isImagenModel(baseModel) {
 		data = convertImagenToGeminiResponse(data, baseModel)
 	}
 
-	// Standard Gemini translation (works for both Gemini and converted Imagen responses)
 	from := opts.SourceFormat
 	to := sdktranslator.FromString("gemini")
 	var param any
@@ -416,273 +162,30 @@ func (e *GeminiVertexExecutor) executeWithServiceAccount(ctx context.Context, au
 	return resp, nil
 }
 
-// executeWithAPIKey handles authentication using API key credentials.
-func (e *GeminiVertexExecutor) executeWithAPIKey(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, apiKey, baseURL string) (resp cliproxyexecutor.Response, err error) {
-	baseModel := thinking.ParseSuffix(req.Model).ModelName
-
-	reporter := newUsageReporter(ctx, e.Identifier(), baseModel, auth)
-	defer reporter.trackFailure(ctx, &err)
-
-	from := opts.SourceFormat
-	to := sdktranslator.FromString("gemini")
-
-	originalPayload := bytes.Clone(req.Payload)
-	if len(opts.OriginalRequest) > 0 {
-		originalPayload = bytes.Clone(opts.OriginalRequest)
-	}
-	originalTranslated := sdktranslator.TranslateRequest(from, to, baseModel, originalPayload, false)
-	body := sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), false)
-
-	body, err = thinking.ApplyThinking(body, req.Model, from.String(), to.String(), e.Identifier())
-	if err != nil {
-		return resp, err
-	}
-
-	body = fixGeminiImageAspectRatio(baseModel, body)
-	requestedModel := payloadRequestedModel(opts, req.Model)
-	body = applyPayloadConfigWithRoot(e.cfg, baseModel, to.String(), "", body, originalTranslated, requestedModel)
-	body, _ = sjson.SetBytes(body, "model", baseModel)
-
-	action := getVertexAction(baseModel, false)
-	if req.Metadata != nil {
-		if a, _ := req.Metadata["action"].(string); a == "countTokens" {
-			action = "countTokens"
-		}
-	}
-
-	// For API key auth, use simpler URL format without project/location
-	if baseURL == "" {
-		baseURL = "https://generativelanguage.googleapis.com"
-	}
-	url := fmt.Sprintf("%s/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, baseModel, action)
-	if opts.Alt != "" && action != "countTokens" {
-		url = url + fmt.Sprintf("?$alt=%s", opts.Alt)
-	}
-	body, _ = sjson.DeleteBytes(body, "session_id")
-
-	httpReq, errNewReq := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
-	if errNewReq != nil {
-		return resp, errNewReq
-	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if apiKey != "" {
-		httpReq.Header.Set("x-goog-api-key", apiKey)
-	}
-	applyGeminiHeaders(httpReq, auth)
-
-	var authID, authLabel, authType, authValue string
-	if auth != nil {
-		authID = auth.ID
-		authLabel = auth.Label
-		authType, authValue = auth.AccountInfo()
-	}
-	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      body,
-		Provider:  e.Identifier(),
-		AuthID:    authID,
-		AuthLabel: authLabel,
-		AuthType:  authType,
-		AuthValue: authValue,
-	})
-
-	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
-	httpResp, errDo := httpClient.Do(httpReq)
-	if errDo != nil {
-		recordAPIResponseError(ctx, e.cfg, errDo)
-		return resp, errDo
-	}
-	defer func() {
-		if errClose := httpResp.Body.Close(); errClose != nil {
-			log.Errorf("vertex executor: close response body error: %v", errClose)
-		}
-	}()
-	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
-	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		err = statusErr{code: httpResp.StatusCode, msg: string(b)}
-		return resp, err
-	}
-	data, errRead := io.ReadAll(httpResp.Body)
-	if errRead != nil {
-		recordAPIResponseError(ctx, e.cfg, errRead)
-		return resp, errRead
-	}
-	appendAPIResponseChunk(ctx, e.cfg, data)
-	reporter.publish(ctx, parseGeminiUsage(data))
-	var param any
-	out := sdktranslator.TranslateNonStream(ctx, to, from, req.Model, bytes.Clone(opts.OriginalRequest), body, data, &param)
-	resp = cliproxyexecutor.Response{Payload: []byte(out)}
-	return resp, nil
-}
-
-// executeStreamWithServiceAccount handles streaming authentication using service account credentials.
-func (e *GeminiVertexExecutor) executeStreamWithServiceAccount(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, projectID, location string, saJSON []byte) (stream <-chan cliproxyexecutor.StreamChunk, err error) {
-	baseModel := thinking.ParseSuffix(req.Model).ModelName
-
-	reporter := newUsageReporter(ctx, e.Identifier(), baseModel, auth)
-	defer reporter.trackFailure(ctx, &err)
-
-	from := opts.SourceFormat
-	to := sdktranslator.FromString("gemini")
-
-	originalPayload := bytes.Clone(req.Payload)
-	if len(opts.OriginalRequest) > 0 {
-		originalPayload = bytes.Clone(opts.OriginalRequest)
-	}
-	originalTranslated := sdktranslator.TranslateRequest(from, to, baseModel, originalPayload, true)
-	body := sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), true)
-
-	body, err = thinking.ApplyThinking(body, req.Model, from.String(), to.String(), e.Identifier())
-	if err != nil {
-		return nil, err
-	}
-
-	body = fixGeminiImageAspectRatio(baseModel, body)
-	requestedModel := payloadRequestedModel(opts, req.Model)
-	body = applyPayloadConfigWithRoot(e.cfg, baseModel, to.String(), "", body, originalTranslated, requestedModel)
-	body, _ = sjson.SetBytes(body, "model", baseModel)
-
-	action := getVertexAction(baseModel, true)
-	baseURL := vertexBaseURL(location)
-	url := fmt.Sprintf("%s/%s/projects/%s/locations/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, projectID, location, baseModel, action)
-	// Imagen models don't support streaming, skip SSE params
-	if !isImagenModel(baseModel) {
-		if opts.Alt == "" {
-			url = url + "?alt=sse"
-		} else {
-			url = url + fmt.Sprintf("?$alt=%s", opts.Alt)
-		}
-	}
-	body, _ = sjson.DeleteBytes(body, "session_id")
-
-	httpReq, errNewReq := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
-	if errNewReq != nil {
-		return nil, errNewReq
-	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if token, errTok := vertexAccessToken(ctx, e.cfg, auth, saJSON); errTok == nil && token != "" {
-		httpReq.Header.Set("Authorization", "Bearer "+token)
-	} else if errTok != nil {
-		log.Errorf("vertex executor: access token error: %v", errTok)
-		return nil, statusErr{code: 500, msg: "internal server error"}
-	}
-	applyGeminiHeaders(httpReq, auth)
-
-	var authID, authLabel, authType, authValue string
-	if auth != nil {
-		authID = auth.ID
-		authLabel = auth.Label
-		authType, authValue = auth.AccountInfo()
-	}
-	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      body,
-		Provider:  e.Identifier(),
-		AuthID:    authID,
-		AuthLabel: authLabel,
-		AuthType:  authType,
-		AuthValue: authValue,
-	})
-
-	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
-	httpResp, errDo := httpClient.Do(httpReq)
-	if errDo != nil {
-		recordAPIResponseError(ctx, e.cfg, errDo)
-		return nil, errDo
-	}
-	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
-	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		if errClose := httpResp.Body.Close(); errClose != nil {
-			log.Errorf("vertex executor: close response body error: %v", errClose)
-		}
-		return nil, statusErr{code: httpResp.StatusCode, msg: string(b)}
-	}
-
-	out := make(chan cliproxyexecutor.StreamChunk)
-	stream = out
-	go func() {
-		defer close(out)
-		defer func() {
-			if errClose := httpResp.Body.Close(); errClose != nil {
-				log.Errorf("vertex executor: close response body error: %v", errClose)
-			}
-		}()
-		scanner := bufio.NewScanner(httpResp.Body)
-		scanner.Buffer(nil, streamScannerBuffer)
-		var param any
-		for scanner.Scan() {
-			line := scanner.Bytes()
-			appendAPIResponseChunk(ctx, e.cfg, line)
-			if detail, ok := parseGeminiStreamUsage(line); ok {
-				reporter.publish(ctx, detail)
-			}
-			lines := sdktranslator.TranslateStream(ctx, to, from, req.Model, bytes.Clone(opts.OriginalRequest), body, bytes.Clone(line), &param)
-			for i := range lines {
-				out <- cliproxyexecutor.StreamChunk{Payload: []byte(lines[i])}
-			}
-		}
-		lines := sdktranslator.TranslateStream(ctx, to, from, req.Model, bytes.Clone(opts.OriginalRequest), body, []byte("[DONE]"), &param)
-		for i := range lines {
-			out <- cliproxyexecutor.StreamChunk{Payload: []byte(lines[i])}
-		}
-		if errScan := scanner.Err(); errScan != nil {
-			recordAPIResponseError(ctx, e.cfg, errScan)
-			reporter.publishFailure(ctx)
-			out <- cliproxyexecutor.StreamChunk{Err: errScan}
-		}
-	}()
-	return stream, nil
-}
-
-// executeStreamWithAPIKey handles streaming authentication using API key credentials.
-func (e *GeminiVertexExecutor) executeStreamWithAPIKey(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, apiKey, baseURL string) (stream <-chan cliproxyexecutor.StreamChunk, err error) {
-	baseModel := thinking.ParseSuffix(req.Model).ModelName
-
-	reporter := newUsageReporter(ctx, e.Identifier(), baseModel, auth)
-	defer reporter.trackFailure(ctx, &err)
-
-	from := opts.SourceFormat
-	to := sdktranslator.FromString("gemini")
-
-	originalPayload := bytes.Clone(req.Payload)
-	if len(opts.OriginalRequest) > 0 {
-		originalPayload = bytes.Clone(opts.OriginalRequest)
+// ExecuteStream performs a streaming request to the Vertex AI API.
+func (e *GeminiVertexExecutor) ExecuteStream(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (stream <-chan cliproxyexecutor.StreamChunk, err error) {
+	vCtx, err := e.resolveVertexContext(auth)
+	if err != nil {
+		return nil, err
 	}
-	originalTranslated := sdktranslator.TranslateRequest(from, to, baseModel, originalPayload, true)
-	body := sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), true)
 
-	body, err = thinking.ApplyThinking(body, req.Model, from.String(), to.String(), e.Identifier())
+	baseModel := thinking.ParseSuffix(req.Model).ModelName
+	reporter := newUsageReporter(ctx, e.Identifier(), baseModel, auth)
+	defer reporter.trackFailure(ctx, &err)
+
+	body, _, err := e.preparePayload(ctx, req, opts, baseModel, true)
 	if err != nil {
 		return nil, err
 	}
 
-	body = fixGeminiImageAspectRatio(baseModel, body)
-	requestedModel := payloadRequestedModel(opts, req.Model)
-	body = applyPayloadConfigWithRoot(e.cfg, baseModel, to.String(), "", body, originalTranslated, requestedModel)
-	body, _ = sjson.SetBytes(body, "model", baseModel)
-
 	action := getVertexAction(baseModel, true)
-	// For API key auth, use simpler URL format without project/location
-	if baseURL == "" {
-		baseURL = "https://generativelanguage.googleapis.com"
-	}
-	url := fmt.Sprintf("%s/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, baseModel, action)
-	// Imagen models don't support streaming, skip SSE params
-	if !isImagenModel(baseModel) {
-		if opts.Alt == "" {
-			url = url + "?alt=sse"
+	url := e.buildVertexURL(vCtx, baseModel, action, opts.Alt)
+	// Add alt=sse if not overridden and not imagen (imagen doesn't stream)
+	if !isImagenModel(baseModel) && !strings.Contains(url, "alt=") {
+		if strings.Contains(url, "?") {
+			url += "&alt=sse"
 		} else {
-			url = url + fmt.Sprintf("?$alt=%s", opts.Alt)
+			url += "?alt=sse"
 		}
 	}
 	body, _ = sjson.DeleteBytes(body, "session_id")
@@ -691,29 +194,11 @@ func (e *GeminiVertexExecutor) executeStreamWithAPIKey(ctx context.Context, auth
 	if errNewReq != nil {
 		return nil, errNewReq
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if apiKey != "" {
-		httpReq.Header.Set("x-goog-api-key", apiKey)
-	}
-	applyGeminiHeaders(httpReq, auth)
 
-	var authID, authLabel, authType, authValue string
-	if auth != nil {
-		authID = auth.ID
-		authLabel = auth.Label
-		authType, authValue = auth.AccountInfo()
+	if err := e.setVertexHeaders(ctx, httpReq, vCtx, auth); err != nil {
+		return nil, err
 	}
-	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      body,
-		Provider:  e.Identifier(),
-		AuthID:    authID,
-		AuthLabel: authLabel,
-		AuthType:  authType,
-		AuthValue: authValue,
-	})
+	e.recordRequest(ctx, httpReq, body, auth)
 
 	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
 	httpResp, errDo := httpClient.Do(httpReq)
@@ -723,13 +208,7 @@ func (e *GeminiVertexExecutor) executeStreamWithAPIKey(ctx context.Context, auth
 	}
 	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
 	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		if errClose := httpResp.Body.Close(); errClose != nil {
-			log.Errorf("vertex executor: close response body error: %v", errClose)
-		}
-		return nil, statusErr{code: httpResp.StatusCode, msg: string(b)}
+		return nil, e.handleErrorResponse(ctx, httpResp)
 	}
 
 	out := make(chan cliproxyexecutor.StreamChunk)
@@ -743,6 +222,8 @@ func (e *GeminiVertexExecutor) executeStreamWithAPIKey(ctx context.Context, auth
 		}()
 		scanner := bufio.NewScanner(httpResp.Body)
 		scanner.Buffer(nil, streamScannerBuffer)
+		from := opts.SourceFormat
+		to := sdktranslator.FromString("gemini")
 		var param any
 		for scanner.Scan() {
 			line := scanner.Bytes()
@@ -768,60 +249,36 @@ func (e *GeminiVertexExecutor) executeStreamWithAPIKey(ctx context.Context, auth
 	return stream, nil
 }
 
-// countTokensWithServiceAccount counts tokens using service account credentials.
-func (e *GeminiVertexExecutor) countTokensWithServiceAccount(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, projectID, location string, saJSON []byte) (cliproxyexecutor.Response, error) {
-	baseModel := thinking.ParseSuffix(req.Model).ModelName
-
-	from := opts.SourceFormat
-	to := sdktranslator.FromString("gemini")
-
-	translatedReq := sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), false)
+// CountTokens counts tokens for the given request using the Vertex AI API.
+func (e *GeminiVertexExecutor) CountTokens(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) (cliproxyexecutor.Response, error) {
+	vCtx, err := e.resolveVertexContext(auth)
+	if err != nil {
+		return cliproxyexecutor.Response{}, err
+	}
 
-	translatedReq, err := thinking.ApplyThinking(translatedReq, req.Model, from.String(), to.String(), e.Identifier())
+	baseModel := thinking.ParseSuffix(req.Model).ModelName
+	body, _, err := e.preparePayload(ctx, req, opts, baseModel, false)
 	if err != nil {
 		return cliproxyexecutor.Response{}, err
 	}
 
-	translatedReq = fixGeminiImageAspectRatio(baseModel, translatedReq)
-	translatedReq, _ = sjson.SetBytes(translatedReq, "model", baseModel)
-	respCtx := context.WithValue(ctx, "alt", opts.Alt)
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "tools")
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "generationConfig")
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "safetySettings")
+	// CountTokens specific cleanup
+	body, _ = sjson.DeleteBytes(body, "tools")
+	body, _ = sjson.DeleteBytes(body, "generationConfig")
+	body, _ = sjson.DeleteBytes(body, "safetySettings")
 
-	baseURL := vertexBaseURL(location)
-	url := fmt.Sprintf("%s/%s/projects/%s/locations/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, projectID, location, baseModel, "countTokens")
+	url := e.buildVertexURL(vCtx, baseModel, "countTokens", opts.Alt)
+	respCtx := context.WithValue(ctx, "alt", opts.Alt)
 
-	httpReq, errNewReq := http.NewRequestWithContext(respCtx, http.MethodPost, url, bytes.NewReader(translatedReq))
+	httpReq, errNewReq := http.NewRequestWithContext(respCtx, http.MethodPost, url, bytes.NewReader(body))
 	if errNewReq != nil {
 		return cliproxyexecutor.Response{}, errNewReq
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if token, errTok := vertexAccessToken(ctx, e.cfg, auth, saJSON); errTok == nil && token != "" {
-		httpReq.Header.Set("Authorization", "Bearer "+token)
-	} else if errTok != nil {
-		log.Errorf("vertex executor: access token error: %v", errTok)
-		return cliproxyexecutor.Response{}, statusErr{code: 500, msg: "internal server error"}
-	}
-	applyGeminiHeaders(httpReq, auth)
 
-	var authID, authLabel, authType, authValue string
-	if auth != nil {
-		authID = auth.ID
-		authLabel = auth.Label
-		authType, authValue = auth.AccountInfo()
+	if err := e.setVertexHeaders(ctx, httpReq, vCtx, auth); err != nil {
+		return cliproxyexecutor.Response{}, err
 	}
-	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      translatedReq,
-		Provider:  e.Identifier(),
-		AuthID:    authID,
-		AuthLabel: authLabel,
-		AuthType:  authType,
-		AuthValue: authValue,
-	})
+	e.recordRequest(ctx, httpReq, body, auth)
 
 	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
 	httpResp, errDo := httpClient.Do(httpReq)
@@ -836,59 +293,153 @@ func (e *GeminiVertexExecutor) countTokensWithServiceAccount(ctx context.Context
 	}()
 	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
 	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		return cliproxyexecutor.Response{}, statusErr{code: httpResp.StatusCode, msg: string(b)}
+		return cliproxyexecutor.Response{}, e.handleErrorResponse(ctx, httpResp)
 	}
+
 	data, errRead := io.ReadAll(httpResp.Body)
 	if errRead != nil {
 		recordAPIResponseError(ctx, e.cfg, errRead)
 		return cliproxyexecutor.Response{}, errRead
 	}
 	appendAPIResponseChunk(ctx, e.cfg, data)
+
+	from := opts.SourceFormat
+	to := sdktranslator.FromString("gemini")
 	count := gjson.GetBytes(data, "totalTokens").Int()
 	out := sdktranslator.TranslateTokenCount(ctx, to, from, count, data)
 	return cliproxyexecutor.Response{Payload: []byte(out)}, nil
 }
 
-// countTokensWithAPIKey handles token counting using API key credentials.
-func (e *GeminiVertexExecutor) countTokensWithAPIKey(ctx context.Context, auth *cliproxyauth.Auth, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, apiKey, baseURL string) (cliproxyexecutor.Response, error) {
-	baseModel := thinking.ParseSuffix(req.Model).ModelName
+// Refresh refreshes the authentication credentials (no-op for Vertex).
+func (e *GeminiVertexExecutor) Refresh(_ context.Context, auth *cliproxyauth.Auth) (*cliproxyauth.Auth, error) {
+	return auth, nil
+}
 
-	from := opts.SourceFormat
-	to := sdktranslator.FromString("gemini")
+// resolveVertexContext resolves the execution context (API Key vs Service Account) and configuration.
+func (e *GeminiVertexExecutor) resolveVertexContext(auth *cliproxyauth.Auth) (*vertexContext, error) {
+	if auth == nil {
+		return nil, fmt.Errorf("vertex executor: auth is nil")
+	}
 
-	translatedReq := sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), false)
+	// 1. Try API Key
+	apiKey, baseURL := vertexAPICreds(auth)
+	if apiKey != "" {
+		compat := e.resolveVertexConfig(auth)
+		if compat != nil && compat.BaseURL != "" {
+			baseURL = compat.BaseURL
+		}
+		if baseURL == "" {
+			baseURL = "https://generativelanguage.googleapis.com"
+		}
+		return &vertexContext{
+			IsAPIKey:     true,
+			APIKey:       apiKey,
+			BaseURL:      baseURL,
+			CompatConfig: compat,
+		}, nil
+	}
 
-	translatedReq, err := thinking.ApplyThinking(translatedReq, req.Model, from.String(), to.String(), e.Identifier())
+	// 2. Fallback to Service Account
+	projectID, location, saJSON, err := vertexCreds(auth)
 	if err != nil {
-		return cliproxyexecutor.Response{}, err
+		return nil, err
 	}
+	return &vertexContext{
+		IsAPIKey:           false,
+		ProjectID:          projectID,
+		Location:           location,
+		ServiceAccountJSON: saJSON,
+		BaseURL:            vertexBaseURL(location),
+	}, nil
+}
 
-	translatedReq = fixGeminiImageAspectRatio(baseModel, translatedReq)
-	translatedReq, _ = sjson.SetBytes(translatedReq, "model", baseModel)
-	respCtx := context.WithValue(ctx, "alt", opts.Alt)
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "tools")
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "generationConfig")
-	translatedReq, _ = sjson.DeleteBytes(translatedReq, "safetySettings")
+// buildVertexURL constructs the API URL based on the context and action.
+func (e *GeminiVertexExecutor) buildVertexURL(vCtx *vertexContext, model, action, alt string) string {
+	var url string
+	if vCtx.IsAPIKey {
+		// API Key: base/v1/publishers/google/models/{model}:{action}
+		base := strings.TrimRight(vCtx.BaseURL, "/")
+		url = fmt.Sprintf("%s/%s/publishers/google/models/%s:%s", base, vertexAPIVersion, model, action)
+	} else {
+		// Service Account: base/v1/projects/{id}/locations/{loc}/publishers/google/models/{model}:{action}
+		base := strings.TrimRight(vCtx.BaseURL, "/")
+		url = fmt.Sprintf("%s/%s/projects/%s/locations/%s/publishers/google/models/%s:%s",
+			base, vertexAPIVersion, vCtx.ProjectID, vCtx.Location, model, action)
+	}
 
-	// For API key auth, use simpler URL format without project/location
-	if baseURL == "" {
-		baseURL = "https://generativelanguage.googleapis.com"
+	if alt != "" && action != "countTokens" {
+		if strings.Contains(url, "?") {
+			url += fmt.Sprintf("&alt=%s", alt)
+		} else {
+			url += fmt.Sprintf("?$alt=%s", alt)
+		}
 	}
-	url := fmt.Sprintf("%s/%s/publishers/google/models/%s:%s", baseURL, vertexAPIVersion, baseModel, "countTokens")
+	return url
+}
 
-	httpReq, errNewReq := http.NewRequestWithContext(respCtx, http.MethodPost, url, bytes.NewReader(translatedReq))
-	if errNewReq != nil {
-		return cliproxyexecutor.Response{}, errNewReq
+// setVertexHeaders applies the necessary headers for authentication and configuration.
+func (e *GeminiVertexExecutor) setVertexHeaders(ctx context.Context, req *http.Request, vCtx *vertexContext, auth *cliproxyauth.Auth) error {
+	req.Header.Set("Content-Type", "application/json")
+
+	if vCtx.IsAPIKey {
+		req.Header.Set("x-goog-api-key", vCtx.APIKey)
+		req.Header.Del("Authorization")
+		// Apply compat headers if available
+		if vCtx.CompatConfig != nil && len(vCtx.CompatConfig.Headers) > 0 {
+			for k, v := range vCtx.CompatConfig.Headers {
+				req.Header.Set(k, v)
+			}
+		}
+	} else {
+		// Service Account needs Access Token
+		token, err := vertexAccessToken(ctx, e.cfg, auth, vCtx.ServiceAccountJSON)
+		if err != nil {
+			return err
+		}
+		if strings.TrimSpace(token) == "" {
+			return statusErr{code: http.StatusUnauthorized, msg: "missing access token"}
+		}
+		req.Header.Set("Authorization", "Bearer "+token)
+		req.Header.Del("x-goog-api-key")
 	}
-	httpReq.Header.Set("Content-Type", "application/json")
-	if apiKey != "" {
-		httpReq.Header.Set("x-goog-api-key", apiKey)
+
+	// Apply headers from auth attributes (overrides compat headers if conflict)
+	applyGeminiHeaders(req, auth)
+	return nil
+}
+
+// preparePayload handles common payload preparation logic.
+func (e *GeminiVertexExecutor) preparePayload(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, baseModel string, isStream bool) (body []byte, originalTranslated []byte, err error) {
+	// Handle Imagen models separately
+	if isImagenModel(baseModel) {
+		body, err = convertToImagenRequest(req.Payload)
+		return body, nil, err
+	}
+
+	from := opts.SourceFormat
+	to := sdktranslator.FromString("gemini")
+
+	originalPayload := bytes.Clone(req.Payload)
+	if len(opts.OriginalRequest) > 0 {
+		originalPayload = bytes.Clone(opts.OriginalRequest)
+	}
+	originalTranslated = sdktranslator.TranslateRequest(from, to, baseModel, originalPayload, isStream)
+	body = sdktranslator.TranslateRequest(from, to, baseModel, bytes.Clone(req.Payload), isStream)
+
+	body, err = thinking.ApplyThinking(body, req.Model, from.String(), to.String(), e.Identifier())
+	if err != nil {
+		return nil, nil, err
 	}
-	applyGeminiHeaders(httpReq, auth)
 
+	body = fixGeminiImageAspectRatio(baseModel, body)
+	requestedModel := payloadRequestedModel(opts, req.Model)
+	body = applyPayloadConfigWithRoot(e.cfg, baseModel, to.String(), "", body, originalTranslated, requestedModel)
+	body, _ = sjson.SetBytes(body, "model", baseModel)
+	return body, originalTranslated, nil
+}
+
+// recordRequest helper to log the upstream request.
+func (e *GeminiVertexExecutor) recordRequest(ctx context.Context, req *http.Request, body []byte, auth *cliproxyauth.Auth) {
 	var authID, authLabel, authType, authValue string
 	if auth != nil {
 		authID = auth.ID
@@ -896,44 +447,145 @@ func (e *GeminiVertexExecutor) countTokensWithAPIKey(ctx context.Context, auth *
 		authType, authValue = auth.AccountInfo()
 	}
 	recordAPIRequest(ctx, e.cfg, upstreamRequestLog{
-		URL:       url,
-		Method:    http.MethodPost,
-		Headers:   httpReq.Header.Clone(),
-		Body:      translatedReq,
+		URL:       req.URL.String(),
+		Method:    req.Method,
+		Headers:   req.Header.Clone(),
+		Body:      body,
 		Provider:  e.Identifier(),
 		AuthID:    authID,
 		AuthLabel: authLabel,
 		AuthType:  authType,
 		AuthValue: authValue,
 	})
+}
 
-	httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
-	httpResp, errDo := httpClient.Do(httpReq)
-	if errDo != nil {
-		recordAPIResponseError(ctx, e.cfg, errDo)
-		return cliproxyexecutor.Response{}, errDo
+// handleErrorResponse handles non-2xx responses.
+func (e *GeminiVertexExecutor) handleErrorResponse(ctx context.Context, resp *http.Response) error {
+	b, _ := io.ReadAll(resp.Body)
+	appendAPIResponseChunk(ctx, e.cfg, b)
+	logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", resp.StatusCode, summarizeErrorBody(resp.Header.Get("Content-Type"), b))
+	return statusErr{code: resp.StatusCode, msg: string(b)}
+}
+
+// --- Helper Functions ---
+
+// isImagenModel checks if the model name is an Imagen image generation model.
+func isImagenModel(model string) bool {
+	lowerModel := strings.ToLower(model)
+	return strings.Contains(lowerModel, "imagen")
+}
+
+// getVertexAction returns the appropriate action for the given model.
+func getVertexAction(model string, isStream bool) string {
+	if isImagenModel(model) {
+		return "predict"
 	}
-	defer func() {
-		if errClose := httpResp.Body.Close(); errClose != nil {
-			log.Errorf("vertex executor: close response body error: %v", errClose)
+	if isStream {
+		return "streamGenerateContent"
+	}
+	return "generateContent"
+}
+
+// convertImagenToGeminiResponse converts Imagen API response to Gemini format.
+func convertImagenToGeminiResponse(data []byte, model string) []byte {
+	predictions := gjson.GetBytes(data, "predictions")
+	if !predictions.Exists() || !predictions.IsArray() {
+		return data
+	}
+
+	parts := make([]map[string]any, 0)
+	for _, pred := range predictions.Array() {
+		imageData := pred.Get("bytesBase64Encoded").String()
+		mimeType := pred.Get("mimeType").String()
+		if mimeType == "" {
+			mimeType = "image/png"
+		}
+		if imageData != "" {
+			parts = append(parts, map[string]any{
+				"inlineData": map[string]any{
+					"mimeType": mimeType,
+					"data":     imageData,
+				},
+			})
 		}
-	}()
-	recordAPIResponseMetadata(ctx, e.cfg, httpResp.StatusCode, httpResp.Header.Clone())
-	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
-		b, _ := io.ReadAll(httpResp.Body)
-		appendAPIResponseChunk(ctx, e.cfg, b)
-		logWithRequestID(ctx).Debugf("request error, error status: %d, error message: %s", httpResp.StatusCode, summarizeErrorBody(httpResp.Header.Get("Content-Type"), b))
-		return cliproxyexecutor.Response{}, statusErr{code: httpResp.StatusCode, msg: string(b)}
 	}
-	data, errRead := io.ReadAll(httpResp.Body)
-	if errRead != nil {
-		recordAPIResponseError(ctx, e.cfg, errRead)
-		return cliproxyexecutor.Response{}, errRead
+
+	responseId := fmt.Sprintf("imagen-%d", time.Now().UnixNano())
+	response := map[string]any{
+		"candidates": []map[string]any{{
+			"content": map[string]any{
+				"parts": parts,
+				"role":  "model",
+			},
+			"finishReason": "STOP",
+		}},
+		"responseId":   responseId,
+		"modelVersion": model,
+		"usageMetadata": map[string]any{
+			"promptTokenCount":     0,
+			"candidatesTokenCount": 0,
+			"totalTokenCount":      0,
+		},
 	}
-	appendAPIResponseChunk(ctx, e.cfg, data)
-	count := gjson.GetBytes(data, "totalTokens").Int()
-	out := sdktranslator.TranslateTokenCount(ctx, to, from, count, data)
-	return cliproxyexecutor.Response{Payload: []byte(out)}, nil
+
+	result, err := json.Marshal(response)
+	if err != nil {
+		return data
+	}
+	return result
+}
+
+// convertToImagenRequest converts a Gemini-style request to Imagen API format.
+func convertToImagenRequest(payload []byte) ([]byte, error) {
+	prompt := ""
+	contentsText := gjson.GetBytes(payload, "contents.0.parts.0.text")
+	if contentsText.Exists() {
+		prompt = contentsText.String()
+	}
+
+	if prompt == "" {
+		messagesText := gjson.GetBytes(payload, "messages.#.content")
+		if messagesText.Exists() && messagesText.IsArray() {
+			for _, msg := range messagesText.Array() {
+				if msg.String() != "" {
+					prompt = msg.String()
+					break
+				}
+			}
+		}
+	}
+
+	if prompt == "" {
+		directPrompt := gjson.GetBytes(payload, "prompt")
+		if directPrompt.Exists() {
+			prompt = directPrompt.String()
+		}
+	}
+
+	if prompt == "" {
+		return nil, fmt.Errorf("imagen: no prompt found in request")
+	}
+
+	imagenReq := map[string]any{
+		"instances": []map[string]any{
+			{"prompt": prompt},
+		},
+		"parameters": map[string]any{
+			"sampleCount": 1,
+		},
+	}
+
+	if aspectRatio := gjson.GetBytes(payload, "aspectRatio"); aspectRatio.Exists() {
+		imagenReq["parameters"].(map[string]any)["aspectRatio"] = aspectRatio.String()
+	}
+	if sampleCount := gjson.GetBytes(payload, "sampleCount"); sampleCount.Exists() {
+		imagenReq["parameters"].(map[string]any)["sampleCount"] = int(sampleCount.Int())
+	}
+	if negativePrompt := gjson.GetBytes(payload, "negativePrompt"); negativePrompt.Exists() {
+		imagenReq["instances"].([]map[string]any)[0]["negativePrompt"] = negativePrompt.String()
+	}
+
+	return json.Marshal(imagenReq)
 }
 
 // vertexCreds extracts project, location and raw service account JSON from auth metadata.
@@ -945,7 +597,6 @@ func vertexCreds(a *cliproxyauth.Auth) (projectID, location string, serviceAccou
 		projectID = strings.TrimSpace(v)
 	}
 	if projectID == "" {
-		// Some service accounts may use "project"; still prefer standard field
 		if v, ok := a.Metadata["project"].(string); ok {
 			projectID = strings.TrimSpace(v)
 		}
@@ -956,7 +607,7 @@ func vertexCreds(a *cliproxyauth.Auth) (projectID, location string, serviceAccou
 	if v, ok := a.Metadata["location"].(string); ok && strings.TrimSpace(v) != "" {
 		location = strings.TrimSpace(v)
 	} else {
-		location = "us-central1"
+		location = defaultVertexLocation
 	}
 	var sa map[string]any
 	if raw, ok := a.Metadata["service_account"].(map[string]any); ok {
@@ -976,7 +627,7 @@ func vertexCreds(a *cliproxyauth.Auth) (projectID, location string, serviceAccou
 	return projectID, location, saJSON, nil
 }
 
-// vertexAPICreds extracts API key and base URL from auth attributes following the claudeCreds pattern.
+// vertexAPICreds extracts API key and base URL from auth attributes.
 func vertexAPICreds(a *cliproxyauth.Auth) (apiKey, baseURL string) {
 	if a == nil {
 		return "", ""
@@ -996,7 +647,7 @@ func vertexAPICreds(a *cliproxyauth.Auth) (apiKey, baseURL string) {
 func vertexBaseURL(location string) string {
 	loc := strings.TrimSpace(location)
 	if loc == "" {
-		loc = "us-central1"
+		loc = defaultVertexLocation
 	}
 	return fmt.Sprintf("https://%s-aiplatform.googleapis.com", loc)
 }
@@ -1005,7 +656,6 @@ func vertexAccessToken(ctx context.Context, cfg *config.Config, auth *cliproxyau
 	if httpClient := newProxyAwareHTTPClient(ctx, cfg, auth, 0); httpClient != nil {
 		ctx = context.WithValue(ctx, oauth2.HTTPClient, httpClient)
 	}
-	// Use cloud-platform scope for Vertex AI.
 	creds, errCreds := google.CredentialsFromJSON(ctx, saJSON, "https://www.googleapis.com/auth/cloud-platform")
 	if errCreds != nil {
 		return "", fmt.Errorf("vertex executor: parse service account json failed: %w", errCreds)