refactor(config): rename oauth-model-mappings to oauth-model-alias

internal/api/handlers/management/config_lists.go

@@ -703,21 +703,21 @@ func (h *Handler) DeleteOAuthExcludedModels(c *gin.Context) {
 	h.persist(c)
 }
 
-// oauth-model-mappings: map[string][]ModelNameMapping
-func (h *Handler) GetOAuthModelMappings(c *gin.Context) {
-	c.JSON(200, gin.H{"oauth-model-mappings": sanitizedOAuthModelMappings(h.cfg.OAuthModelMappings)})
+// oauth-model-alias: map[string][]OAuthModelAlias
+func (h *Handler) GetOAuthModelAlias(c *gin.Context) {
+	c.JSON(200, gin.H{"oauth-model-alias": sanitizedOAuthModelAlias(h.cfg.OAuthModelAlias)})
 }
 
-func (h *Handler) PutOAuthModelMappings(c *gin.Context) {
+func (h *Handler) PutOAuthModelAlias(c *gin.Context) {
 	data, err := c.GetRawData()
 	if err != nil {
 		c.JSON(400, gin.H{"error": "failed to read body"})
 		return
 	}
-	var entries map[string][]config.ModelNameMapping
+	var entries map[string][]config.OAuthModelAlias
 	if err = json.Unmarshal(data, &entries); err != nil {
 		var wrapper struct {
-			Items map[string][]config.ModelNameMapping `json:"items"`
+			Items map[string][]config.OAuthModelAlias `json:"items"`
 		}
 		if err2 := json.Unmarshal(data, &wrapper); err2 != nil {
 			c.JSON(400, gin.H{"error": "invalid body"})
@@ -725,15 +725,15 @@ func (h *Handler) PutOAuthModelMappings(c *gin.Context) {
 		}
 		entries = wrapper.Items
 	}
-	h.cfg.OAuthModelMappings = sanitizedOAuthModelMappings(entries)
+	h.cfg.OAuthModelAlias = sanitizedOAuthModelAlias(entries)
 	h.persist(c)
 }
 
-func (h *Handler) PatchOAuthModelMappings(c *gin.Context) {
+func (h *Handler) PatchOAuthModelAlias(c *gin.Context) {
 	var body struct {
-		Provider *string                   `json:"provider"`
-		Channel  *string                   `json:"channel"`
-		Mappings []config.ModelNameMapping `json:"mappings"`
+		Provider *string                  `json:"provider"`
+		Channel  *string                  `json:"channel"`
+		Aliases  []config.OAuthModelAlias `json:"aliases"`
 	}
 	if errBindJSON := c.ShouldBindJSON(&body); errBindJSON != nil {
 		c.JSON(400, gin.H{"error": "invalid body"})
@@ -751,32 +751,32 @@ func (h *Handler) PatchOAuthModelMappings(c *gin.Context) {
 		return
 	}
 
-	normalizedMap := sanitizedOAuthModelMappings(map[string][]config.ModelNameMapping{channel: body.Mappings})
+	normalizedMap := sanitizedOAuthModelAlias(map[string][]config.OAuthModelAlias{channel: body.Aliases})
 	normalized := normalizedMap[channel]
 	if len(normalized) == 0 {
-		if h.cfg.OAuthModelMappings == nil {
+		if h.cfg.OAuthModelAlias == nil {
 			c.JSON(404, gin.H{"error": "channel not found"})
 			return
 		}
-		if _, ok := h.cfg.OAuthModelMappings[channel]; !ok {
+		if _, ok := h.cfg.OAuthModelAlias[channel]; !ok {
 			c.JSON(404, gin.H{"error": "channel not found"})
 			return
 		}
-		delete(h.cfg.OAuthModelMappings, channel)
-		if len(h.cfg.OAuthModelMappings) == 0 {
-			h.cfg.OAuthModelMappings = nil
+		delete(h.cfg.OAuthModelAlias, channel)
+		if len(h.cfg.OAuthModelAlias) == 0 {
+			h.cfg.OAuthModelAlias = nil
 		}
 		h.persist(c)
 		return
 	}
-	if h.cfg.OAuthModelMappings == nil {
-		h.cfg.OAuthModelMappings = make(map[string][]config.ModelNameMapping)
+	if h.cfg.OAuthModelAlias == nil {
+		h.cfg.OAuthModelAlias = make(map[string][]config.OAuthModelAlias)
 	}
-	h.cfg.OAuthModelMappings[channel] = normalized
+	h.cfg.OAuthModelAlias[channel] = normalized
 	h.persist(c)
 }
 
-func (h *Handler) DeleteOAuthModelMappings(c *gin.Context) {
+func (h *Handler) DeleteOAuthModelAlias(c *gin.Context) {
 	channel := strings.ToLower(strings.TrimSpace(c.Query("channel")))
 	if channel == "" {
 		channel = strings.ToLower(strings.TrimSpace(c.Query("provider")))
@@ -785,17 +785,17 @@ func (h *Handler) DeleteOAuthModelMappings(c *gin.Context) {
 		c.JSON(400, gin.H{"error": "missing channel"})
 		return
 	}
-	if h.cfg.OAuthModelMappings == nil {
+	if h.cfg.OAuthModelAlias == nil {
 		c.JSON(404, gin.H{"error": "channel not found"})
 		return
 	}
-	if _, ok := h.cfg.OAuthModelMappings[channel]; !ok {
+	if _, ok := h.cfg.OAuthModelAlias[channel]; !ok {
 		c.JSON(404, gin.H{"error": "channel not found"})
 		return
 	}
-	delete(h.cfg.OAuthModelMappings, channel)
-	if len(h.cfg.OAuthModelMappings) == 0 {
-		h.cfg.OAuthModelMappings = nil
+	delete(h.cfg.OAuthModelAlias, channel)
+	if len(h.cfg.OAuthModelAlias) == 0 {
+		h.cfg.OAuthModelAlias = nil
 	}
 	h.persist(c)
 }
@@ -1042,26 +1042,26 @@ func normalizeVertexCompatKey(entry *config.VertexCompatKey) {
 	entry.Models = normalized
 }
 
-func sanitizedOAuthModelMappings(entries map[string][]config.ModelNameMapping) map[string][]config.ModelNameMapping {
+func sanitizedOAuthModelAlias(entries map[string][]config.OAuthModelAlias) map[string][]config.OAuthModelAlias {
 	if len(entries) == 0 {
 		return nil
 	}
-	copied := make(map[string][]config.ModelNameMapping, len(entries))
-	for channel, mappings := range entries {
-		if len(mappings) == 0 {
+	copied := make(map[string][]config.OAuthModelAlias, len(entries))
+	for channel, aliases := range entries {
+		if len(aliases) == 0 {
 			continue
 		}
-		copied[channel] = append([]config.ModelNameMapping(nil), mappings...)
+		copied[channel] = append([]config.OAuthModelAlias(nil), aliases...)
 	}
 	if len(copied) == 0 {
 		return nil
 	}
-	cfg := config.Config{OAuthModelMappings: copied}
-	cfg.SanitizeOAuthModelMappings()
-	if len(cfg.OAuthModelMappings) == 0 {
+	cfg := config.Config{OAuthModelAlias: copied}
+	cfg.SanitizeOAuthModelAlias()
+	if len(cfg.OAuthModelAlias) == 0 {
 		return nil
 	}
-	return cfg.OAuthModelMappings
+	return cfg.OAuthModelAlias
 }
 
 // GetAmpCode returns the complete ampcode configuration.

internal/api/server.go

@@ -601,10 +601,10 @@ func (s *Server) registerManagementRoutes() {
 		mgmt.PATCH("/oauth-excluded-models", s.mgmt.PatchOAuthExcludedModels)
 		mgmt.DELETE("/oauth-excluded-models", s.mgmt.DeleteOAuthExcludedModels)
 
-		mgmt.GET("/oauth-model-mappings", s.mgmt.GetOAuthModelMappings)
-		mgmt.PUT("/oauth-model-mappings", s.mgmt.PutOAuthModelMappings)
-		mgmt.PATCH("/oauth-model-mappings", s.mgmt.PatchOAuthModelMappings)
-		mgmt.DELETE("/oauth-model-mappings", s.mgmt.DeleteOAuthModelMappings)
+		mgmt.GET("/oauth-model-alias", s.mgmt.GetOAuthModelAlias)
+		mgmt.PUT("/oauth-model-alias", s.mgmt.PutOAuthModelAlias)
+		mgmt.PATCH("/oauth-model-alias", s.mgmt.PatchOAuthModelAlias)
+		mgmt.DELETE("/oauth-model-alias", s.mgmt.DeleteOAuthModelAlias)
 
 		mgmt.GET("/auth-files", s.mgmt.ListAuthFiles)
 		mgmt.GET("/auth-files/models", s.mgmt.GetAuthFileModels)

internal/config/config.go

@@ -91,13 +91,13 @@ type Config struct {
 	// OAuthExcludedModels defines per-provider global model exclusions applied to OAuth/file-backed auth entries.
 	OAuthExcludedModels map[string][]string `yaml:"oauth-excluded-models,omitempty" json:"oauth-excluded-models,omitempty"`
 
-	// OAuthModelMappings defines global model name mappings for OAuth/file-backed auth channels.
-	// These mappings affect both model listing and model routing for supported channels:
+	// OAuthModelAlias defines global model name aliases for OAuth/file-backed auth channels.
+	// These aliases affect both model listing and model routing for supported channels:
 	// gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow.
 	//
 	// NOTE: This does not apply to existing per-credential model alias features under:
 	// gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key, and ampcode.
-	OAuthModelMappings map[string][]ModelNameMapping `yaml:"oauth-model-mappings,omitempty" json:"oauth-model-mappings,omitempty"`
+	OAuthModelAlias map[string][]OAuthModelAlias `yaml:"oauth-model-alias,omitempty" json:"oauth-model-alias,omitempty"`
 
 	// Payload defines default and override rules for provider payload parameters.
 	Payload PayloadConfig `yaml:"payload" json:"payload"`
@@ -145,11 +145,11 @@ type RoutingConfig struct {
 	Strategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`
 }
 
-// ModelNameMapping defines a model ID mapping for a specific channel.
+// OAuthModelAlias defines a model ID alias for a specific channel.
 // It maps the upstream model name (Name) to the client-visible alias (Alias).
 // When Fork is true, the alias is added as an additional model in listings while
 // keeping the original model ID available.
-type ModelNameMapping struct {
+type OAuthModelAlias struct {
 	Name  string `yaml:"name" json:"name"`
 	Alias string `yaml:"alias" json:"alias"`
 	Fork  bool   `yaml:"fork,omitempty" json:"fork,omitempty"`
@@ -436,6 +436,15 @@ func LoadConfig(configFile string) (*Config, error) {
 // If optional is true and the file is missing, it returns an empty Config.
 // If optional is true and the file is empty or invalid, it returns an empty Config.
 func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
+	// Perform oauth-model-alias migration before loading config.
+	// This migrates oauth-model-mappings to oauth-model-alias if needed.
+	if migrated, err := MigrateOAuthModelAlias(configFile); err != nil {
+		// Log warning but don't fail - config loading should still work
+		fmt.Printf("Warning: oauth-model-alias migration failed: %v\n", err)
+	} else if migrated {
+		fmt.Println("Migrated oauth-model-mappings to oauth-model-alias")
+	}
+
 	// Read the entire configuration file into memory.
 	data, err := os.ReadFile(configFile)
 	if err != nil {
@@ -528,8 +537,8 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	// Normalize OAuth provider model exclusion map.
 	cfg.OAuthExcludedModels = NormalizeOAuthExcludedModels(cfg.OAuthExcludedModels)
 
-	// Normalize global OAuth model name mappings.
-	cfg.SanitizeOAuthModelMappings()
+	// Normalize global OAuth model name aliases.
+	cfg.SanitizeOAuthModelAlias()
 
 	if cfg.legacyMigrationPending {
 		fmt.Println("Detected legacy configuration keys, attempting to persist the normalized config...")
@@ -547,24 +556,24 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	return &cfg, nil
 }
 
-// SanitizeOAuthModelMappings normalizes and deduplicates global OAuth model name mappings.
+// 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) SanitizeOAuthModelMappings() {
-	if cfg == nil || len(cfg.OAuthModelMappings) == 0 {
+func (cfg *Config) SanitizeOAuthModelAlias() {
+	if cfg == nil || len(cfg.OAuthModelAlias) == 0 {
 		return
 	}
-	out := make(map[string][]ModelNameMapping, len(cfg.OAuthModelMappings))
-	for rawChannel, mappings := range cfg.OAuthModelMappings {
+	out := make(map[string][]OAuthModelAlias, len(cfg.OAuthModelAlias))
+	for rawChannel, aliases := range cfg.OAuthModelAlias {
 		channel := strings.ToLower(strings.TrimSpace(rawChannel))
-		if channel == "" || len(mappings) == 0 {
+		if channel == "" || len(aliases) == 0 {
 			continue
 		}
-		seenAlias := make(map[string]struct{}, len(mappings))
-		clean := make([]ModelNameMapping, 0, len(mappings))
-		for _, mapping := range mappings {
-			name := strings.TrimSpace(mapping.Name)
-			alias := strings.TrimSpace(mapping.Alias)
+		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
 			}
@@ -576,13 +585,13 @@ func (cfg *Config) SanitizeOAuthModelMappings() {
 				continue
 			}
 			seenAlias[aliasKey] = struct{}{}
-			clean = append(clean, ModelNameMapping{Name: name, Alias: alias, Fork: mapping.Fork})
+			clean = append(clean, OAuthModelAlias{Name: name, Alias: alias, Fork: entry.Fork})
 		}
 		if len(clean) > 0 {
 			out[channel] = clean
 		}
 	}
-	cfg.OAuthModelMappings = out
+	cfg.OAuthModelAlias = out
 }
 
 // SanitizeOpenAICompatibility removes OpenAI-compatibility provider entries that are

internal/config/oauth_model_alias_migration.go

@@ -0,0 +1,258 @@
+package config
+
+import (
+	"os"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// antigravityModelConversionTable maps old built-in aliases to actual model names
+// for the antigravity channel during migration.
+var antigravityModelConversionTable = map[string]string{
+	"gemini-2.5-computer-use-preview-10-2025": "rev19-uic3-1p",
+	"gemini-3-pro-image-preview":              "gemini-3-pro-image",
+	"gemini-3-pro-preview":                    "gemini-3-pro-high",
+	"gemini-3-flash-preview":                  "gemini-3-flash",
+	"gemini-claude-sonnet-4-5":                "claude-sonnet-4-5",
+	"gemini-claude-sonnet-4-5-thinking":       "claude-sonnet-4-5-thinking",
+	"gemini-claude-opus-4-5-thinking":         "claude-opus-4-5-thinking",
+}
+
+// defaultAntigravityAliases returns the default oauth-model-alias configuration
+// for the antigravity channel when neither field exists.
+func defaultAntigravityAliases() []OAuthModelAlias {
+	return []OAuthModelAlias{
+		{Name: "rev19-uic3-1p", Alias: "gemini-2.5-computer-use-preview-10-2025"},
+		{Name: "gemini-3-pro-image", Alias: "gemini-3-pro-image-preview"},
+		{Name: "gemini-3-pro-high", Alias: "gemini-3-pro-preview"},
+		{Name: "gemini-3-flash", Alias: "gemini-3-flash-preview"},
+		{Name: "claude-sonnet-4-5", Alias: "gemini-claude-sonnet-4-5"},
+		{Name: "claude-sonnet-4-5-thinking", Alias: "gemini-claude-sonnet-4-5-thinking"},
+		{Name: "claude-opus-4-5-thinking", Alias: "gemini-claude-opus-4-5-thinking"},
+	}
+}
+
+// MigrateOAuthModelAlias checks for and performs migration from oauth-model-mappings
+// to oauth-model-alias at startup. Returns true if migration was performed.
+//
+// Migration flow:
+// 1. Check if oauth-model-alias exists -> skip migration
+// 2. Check if oauth-model-mappings exists -> convert and migrate
+//   - For antigravity channel, convert old built-in aliases to actual model names
+//
+// 3. Neither exists -> add default antigravity config
+func MigrateOAuthModelAlias(configFile string) (bool, error) {
+	data, err := os.ReadFile(configFile)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, err
+	}
+	if len(data) == 0 {
+		return false, nil
+	}
+
+	// Parse YAML into node tree to preserve structure
+	var root yaml.Node
+	if err := yaml.Unmarshal(data, &root); err != nil {
+		return false, nil
+	}
+	if root.Kind != yaml.DocumentNode || len(root.Content) == 0 {
+		return false, nil
+	}
+	rootMap := root.Content[0]
+	if rootMap == nil || rootMap.Kind != yaml.MappingNode {
+		return false, nil
+	}
+
+	// Check if oauth-model-alias already exists
+	if findMapKeyIndex(rootMap, "oauth-model-alias") >= 0 {
+		return false, nil
+	}
+
+	// Check if oauth-model-mappings exists
+	oldIdx := findMapKeyIndex(rootMap, "oauth-model-mappings")
+	if oldIdx >= 0 {
+		// Migrate from old field
+		return migrateFromOldField(configFile, &root, rootMap, oldIdx)
+	}
+
+	// Neither field exists - add default antigravity config
+	return addDefaultAntigravityConfig(configFile, &root, rootMap)
+}
+
+// migrateFromOldField converts oauth-model-mappings to oauth-model-alias
+func migrateFromOldField(configFile string, root *yaml.Node, rootMap *yaml.Node, oldIdx int) (bool, error) {
+	if oldIdx+1 >= len(rootMap.Content) {
+		return false, nil
+	}
+	oldValue := rootMap.Content[oldIdx+1]
+	if oldValue == nil || oldValue.Kind != yaml.MappingNode {
+		return false, nil
+	}
+
+	// Parse the old aliases
+	oldAliases := parseOldAliasNode(oldValue)
+	if len(oldAliases) == 0 {
+		// Remove the old field and write
+		removeMapKeyByIndex(rootMap, oldIdx)
+		return writeYAMLNode(configFile, root)
+	}
+
+	// Convert model names for antigravity channel
+	newAliases := make(map[string][]OAuthModelAlias, len(oldAliases))
+	for channel, entries := range oldAliases {
+		converted := make([]OAuthModelAlias, 0, len(entries))
+		for _, entry := range entries {
+			newEntry := OAuthModelAlias{
+				Name:  entry.Name,
+				Alias: entry.Alias,
+				Fork:  entry.Fork,
+			}
+			// Convert model names for antigravity channel
+			if strings.EqualFold(channel, "antigravity") {
+				if actual, ok := antigravityModelConversionTable[entry.Name]; ok {
+					newEntry.Name = actual
+				}
+			}
+			converted = append(converted, newEntry)
+		}
+		newAliases[channel] = converted
+	}
+
+	// Build new node
+	newNode := buildOAuthModelAliasNode(newAliases)
+
+	// Replace old key with new key and value
+	rootMap.Content[oldIdx].Value = "oauth-model-alias"
+	rootMap.Content[oldIdx+1] = newNode
+
+	return writeYAMLNode(configFile, root)
+}
+
+// addDefaultAntigravityConfig adds the default antigravity configuration
+func addDefaultAntigravityConfig(configFile string, root *yaml.Node, rootMap *yaml.Node) (bool, error) {
+	defaults := map[string][]OAuthModelAlias{
+		"antigravity": defaultAntigravityAliases(),
+	}
+	newNode := buildOAuthModelAliasNode(defaults)
+
+	// Add new key-value pair
+	keyNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "oauth-model-alias"}
+	rootMap.Content = append(rootMap.Content, keyNode, newNode)
+
+	return writeYAMLNode(configFile, root)
+}
+
+// parseOldAliasNode parses the old oauth-model-mappings node structure
+func parseOldAliasNode(node *yaml.Node) map[string][]OAuthModelAlias {
+	if node == nil || node.Kind != yaml.MappingNode {
+		return nil
+	}
+	result := make(map[string][]OAuthModelAlias)
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		channelNode := node.Content[i]
+		entriesNode := node.Content[i+1]
+		if channelNode == nil || entriesNode == nil {
+			continue
+		}
+		channel := strings.ToLower(strings.TrimSpace(channelNode.Value))
+		if channel == "" || entriesNode.Kind != yaml.SequenceNode {
+			continue
+		}
+		entries := make([]OAuthModelAlias, 0, len(entriesNode.Content))
+		for _, entryNode := range entriesNode.Content {
+			if entryNode == nil || entryNode.Kind != yaml.MappingNode {
+				continue
+			}
+			entry := parseAliasEntry(entryNode)
+			if entry.Name != "" && entry.Alias != "" {
+				entries = append(entries, entry)
+			}
+		}
+		if len(entries) > 0 {
+			result[channel] = entries
+		}
+	}
+	return result
+}
+
+// parseAliasEntry parses a single alias entry node
+func parseAliasEntry(node *yaml.Node) OAuthModelAlias {
+	var entry OAuthModelAlias
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		valNode := node.Content[i+1]
+		if keyNode == nil || valNode == nil {
+			continue
+		}
+		switch strings.ToLower(strings.TrimSpace(keyNode.Value)) {
+		case "name":
+			entry.Name = strings.TrimSpace(valNode.Value)
+		case "alias":
+			entry.Alias = strings.TrimSpace(valNode.Value)
+		case "fork":
+			entry.Fork = strings.ToLower(strings.TrimSpace(valNode.Value)) == "true"
+		}
+	}
+	return entry
+}
+
+// buildOAuthModelAliasNode creates a YAML node for oauth-model-alias
+func buildOAuthModelAliasNode(aliases map[string][]OAuthModelAlias) *yaml.Node {
+	node := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+	for channel, entries := range aliases {
+		channelNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: channel}
+		entriesNode := &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
+		for _, entry := range entries {
+			entryNode := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+			entryNode.Content = append(entryNode.Content,
+				&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "name"},
+				&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: entry.Name},
+				&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "alias"},
+				&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: entry.Alias},
+			)
+			if entry.Fork {
+				entryNode.Content = append(entryNode.Content,
+					&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "fork"},
+					&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!bool", Value: "true"},
+				)
+			}
+			entriesNode.Content = append(entriesNode.Content, entryNode)
+		}
+		node.Content = append(node.Content, channelNode, entriesNode)
+	}
+	return node
+}
+
+// removeMapKeyByIndex removes a key-value pair from a mapping node by index
+func removeMapKeyByIndex(mapNode *yaml.Node, keyIdx int) {
+	if mapNode == nil || mapNode.Kind != yaml.MappingNode {
+		return
+	}
+	if keyIdx < 0 || keyIdx+1 >= len(mapNode.Content) {
+		return
+	}
+	mapNode.Content = append(mapNode.Content[:keyIdx], mapNode.Content[keyIdx+2:]...)
+}
+
+// writeYAMLNode writes the YAML node tree back to file
+func writeYAMLNode(configFile string, root *yaml.Node) (bool, error) {
+	f, err := os.Create(configFile)
+	if err != nil {
+		return false, err
+	}
+	defer f.Close()
+
+	enc := yaml.NewEncoder(f)
+	enc.SetIndent(2)
+	if err := enc.Encode(root); err != nil {
+		return false, err
+	}
+	if err := enc.Close(); err != nil {
+		return false, err
+	}
+	return true, nil
+}

internal/config/oauth_model_alias_migration_test.go

@@ -0,0 +1,225 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+func TestMigrateOAuthModelAlias_SkipsIfNewFieldExists(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	content := `oauth-model-alias:
+  gemini-cli:
+    - name: "gemini-2.5-pro"
+      alias: "g2.5p"
+`
+	if err := os.WriteFile(configFile, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if migrated {
+		t.Fatal("expected no migration when oauth-model-alias already exists")
+	}
+
+	// Verify file unchanged
+	data, _ := os.ReadFile(configFile)
+	if !strings.Contains(string(data), "oauth-model-alias:") {
+		t.Fatal("file should still contain oauth-model-alias")
+	}
+}
+
+func TestMigrateOAuthModelAlias_MigratesOldField(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	content := `oauth-model-mappings:
+  gemini-cli:
+    - name: "gemini-2.5-pro"
+      alias: "g2.5p"
+      fork: true
+`
+	if err := os.WriteFile(configFile, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !migrated {
+		t.Fatal("expected migration to occur")
+	}
+
+	// Verify new field exists and old field removed
+	data, _ := os.ReadFile(configFile)
+	if strings.Contains(string(data), "oauth-model-mappings:") {
+		t.Fatal("old field should be removed")
+	}
+	if !strings.Contains(string(data), "oauth-model-alias:") {
+		t.Fatal("new field should exist")
+	}
+
+	// Parse and verify structure
+	var root yaml.Node
+	if err := yaml.Unmarshal(data, &root); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestMigrateOAuthModelAlias_ConvertsAntigravityModels(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	// Use old model names that should be converted
+	content := `oauth-model-mappings:
+  antigravity:
+    - name: "gemini-2.5-computer-use-preview-10-2025"
+      alias: "computer-use"
+    - name: "gemini-3-pro-preview"
+      alias: "g3p"
+`
+	if err := os.WriteFile(configFile, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !migrated {
+		t.Fatal("expected migration to occur")
+	}
+
+	// Verify model names were converted
+	data, _ := os.ReadFile(configFile)
+	content = string(data)
+	if !strings.Contains(content, "rev19-uic3-1p") {
+		t.Fatal("expected gemini-2.5-computer-use-preview-10-2025 to be converted to rev19-uic3-1p")
+	}
+	if !strings.Contains(content, "gemini-3-pro-high") {
+		t.Fatal("expected gemini-3-pro-preview to be converted to gemini-3-pro-high")
+	}
+}
+
+func TestMigrateOAuthModelAlias_AddsDefaultIfNeitherExists(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	content := `debug: true
+port: 8080
+`
+	if err := os.WriteFile(configFile, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !migrated {
+		t.Fatal("expected migration to add default config")
+	}
+
+	// Verify default antigravity config was added
+	data, _ := os.ReadFile(configFile)
+	content = string(data)
+	if !strings.Contains(content, "oauth-model-alias:") {
+		t.Fatal("expected oauth-model-alias to be added")
+	}
+	if !strings.Contains(content, "antigravity:") {
+		t.Fatal("expected antigravity channel to be added")
+	}
+	if !strings.Contains(content, "rev19-uic3-1p") {
+		t.Fatal("expected default antigravity aliases to include rev19-uic3-1p")
+	}
+}
+
+func TestMigrateOAuthModelAlias_PreservesOtherConfig(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	content := `debug: true
+port: 8080
+oauth-model-mappings:
+  gemini-cli:
+    - name: "test"
+      alias: "t"
+api-keys:
+  - "key1"
+  - "key2"
+`
+	if err := os.WriteFile(configFile, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !migrated {
+		t.Fatal("expected migration to occur")
+	}
+
+	// Verify other config preserved
+	data, _ := os.ReadFile(configFile)
+	content = string(data)
+	if !strings.Contains(content, "debug: true") {
+		t.Fatal("expected debug field to be preserved")
+	}
+	if !strings.Contains(content, "port: 8080") {
+		t.Fatal("expected port field to be preserved")
+	}
+	if !strings.Contains(content, "api-keys:") {
+		t.Fatal("expected api-keys field to be preserved")
+	}
+}
+
+func TestMigrateOAuthModelAlias_NonexistentFile(t *testing.T) {
+	t.Parallel()
+
+	migrated, err := MigrateOAuthModelAlias("/nonexistent/path/config.yaml")
+	if err != nil {
+		t.Fatalf("unexpected error for nonexistent file: %v", err)
+	}
+	if migrated {
+		t.Fatal("expected no migration for nonexistent file")
+	}
+}
+
+func TestMigrateOAuthModelAlias_EmptyFile(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	configFile := filepath.Join(dir, "config.yaml")
+
+	if err := os.WriteFile(configFile, []byte(""), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	migrated, err := MigrateOAuthModelAlias(configFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if migrated {
+		t.Fatal("expected no migration for empty file")
+	}
+}

internal/config/oauth_model_alias_test.go

@@ -0,0 +1,56 @@
+package config
+
+import "testing"
+
+func TestSanitizeOAuthModelAlias_PreservesForkFlag(t *testing.T) {
+	cfg := &Config{
+		OAuthModelAlias: map[string][]OAuthModelAlias{
+			" CoDeX ": {
+				{Name: " gpt-5 ", Alias: " g5 ", Fork: true},
+				{Name: "gpt-6", Alias: "g6"},
+			},
+		},
+	}
+
+	cfg.SanitizeOAuthModelAlias()
+
+	aliases := cfg.OAuthModelAlias["codex"]
+	if len(aliases) != 2 {
+		t.Fatalf("expected 2 sanitized aliases, got %d", len(aliases))
+	}
+	if aliases[0].Name != "gpt-5" || aliases[0].Alias != "g5" || !aliases[0].Fork {
+		t.Fatalf("expected first alias to be gpt-5->g5 fork=true, got name=%q alias=%q fork=%v", aliases[0].Name, aliases[0].Alias, aliases[0].Fork)
+	}
+	if aliases[1].Name != "gpt-6" || aliases[1].Alias != "g6" || aliases[1].Fork {
+		t.Fatalf("expected second alias to be gpt-6->g6 fork=false, got name=%q alias=%q fork=%v", aliases[1].Name, aliases[1].Alias, aliases[1].Fork)
+	}
+}
+
+func TestSanitizeOAuthModelAlias_AllowsMultipleAliasesForSameName(t *testing.T) {
+	cfg := &Config{
+		OAuthModelAlias: map[string][]OAuthModelAlias{
+			"antigravity": {
+				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101", Fork: true},
+				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101-thinking", Fork: true},
+				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5", Fork: true},
+			},
+		},
+	}
+
+	cfg.SanitizeOAuthModelAlias()
+
+	aliases := cfg.OAuthModelAlias["antigravity"]
+	expected := []OAuthModelAlias{
+		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101", Fork: true},
+		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101-thinking", Fork: true},
+		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5", Fork: true},
+	}
+	if len(aliases) != len(expected) {
+		t.Fatalf("expected %d sanitized aliases, got %d", len(expected), len(aliases))
+	}
+	for i, exp := range expected {
+		if aliases[i].Name != exp.Name || aliases[i].Alias != exp.Alias || aliases[i].Fork != exp.Fork {
+			t.Fatalf("expected alias %d to be name=%q alias=%q fork=%v, got name=%q alias=%q fork=%v", i, exp.Name, exp.Alias, exp.Fork, aliases[i].Name, aliases[i].Alias, aliases[i].Fork)
+		}
+	}
+}

internal/config/oauth_model_mappings_test.go

@@ -1,56 +0,0 @@
-package config
-
-import "testing"
-
-func TestSanitizeOAuthModelMappings_PreservesForkFlag(t *testing.T) {
-	cfg := &Config{
-		OAuthModelMappings: map[string][]ModelNameMapping{
-			" CoDeX ": {
-				{Name: " gpt-5 ", Alias: " g5 ", Fork: true},
-				{Name: "gpt-6", Alias: "g6"},
-			},
-		},
-	}
-
-	cfg.SanitizeOAuthModelMappings()
-
-	mappings := cfg.OAuthModelMappings["codex"]
-	if len(mappings) != 2 {
-		t.Fatalf("expected 2 sanitized mappings, got %d", len(mappings))
-	}
-	if mappings[0].Name != "gpt-5" || mappings[0].Alias != "g5" || !mappings[0].Fork {
-		t.Fatalf("expected first mapping to be gpt-5->g5 fork=true, got name=%q alias=%q fork=%v", mappings[0].Name, mappings[0].Alias, mappings[0].Fork)
-	}
-	if mappings[1].Name != "gpt-6" || mappings[1].Alias != "g6" || mappings[1].Fork {
-		t.Fatalf("expected second mapping to be gpt-6->g6 fork=false, got name=%q alias=%q fork=%v", mappings[1].Name, mappings[1].Alias, mappings[1].Fork)
-	}
-}
-
-func TestSanitizeOAuthModelMappings_AllowsMultipleAliasesForSameName(t *testing.T) {
-	cfg := &Config{
-		OAuthModelMappings: map[string][]ModelNameMapping{
-			"antigravity": {
-				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101", Fork: true},
-				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101-thinking", Fork: true},
-				{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5", Fork: true},
-			},
-		},
-	}
-
-	cfg.SanitizeOAuthModelMappings()
-
-	mappings := cfg.OAuthModelMappings["antigravity"]
-	expected := []ModelNameMapping{
-		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101", Fork: true},
-		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5-20251101-thinking", Fork: true},
-		{Name: "gemini-claude-opus-4-5-thinking", Alias: "claude-opus-4-5", Fork: true},
-	}
-	if len(mappings) != len(expected) {
-		t.Fatalf("expected %d sanitized mappings, got %d", len(expected), len(mappings))
-	}
-	for i, exp := range expected {
-		if mappings[i].Name != exp.Name || mappings[i].Alias != exp.Alias || mappings[i].Fork != exp.Fork {
-			t.Fatalf("expected mapping %d to be name=%q alias=%q fork=%v, got name=%q alias=%q fork=%v", i, exp.Name, exp.Alias, exp.Fork, mappings[i].Name, mappings[i].Alias, mappings[i].Fork)
-		}
-	}
-}

internal/watcher/config_reload.go

@@ -127,7 +127,7 @@ func (w *Watcher) reloadConfig() bool {
 	}
 
 	authDirChanged := oldConfig == nil || oldConfig.AuthDir != newConfig.AuthDir
-	forceAuthRefresh := oldConfig != nil && (oldConfig.ForceModelPrefix != newConfig.ForceModelPrefix || !reflect.DeepEqual(oldConfig.OAuthModelMappings, newConfig.OAuthModelMappings))
+	forceAuthRefresh := oldConfig != nil && (oldConfig.ForceModelPrefix != newConfig.ForceModelPrefix || !reflect.DeepEqual(oldConfig.OAuthModelAlias, newConfig.OAuthModelAlias))
 
 	log.Infof("config successfully reloaded, triggering client reload")
 	w.reloadClients(authDirChanged, affectedOAuthProviders, forceAuthRefresh)

internal/watcher/diff/config_diff.go

@@ -212,7 +212,7 @@ func BuildConfigChangeDetails(oldCfg, newCfg *config.Config) []string {
 	if entries, _ := DiffOAuthExcludedModelChanges(oldCfg.OAuthExcludedModels, newCfg.OAuthExcludedModels); len(entries) > 0 {
 		changes = append(changes, entries...)
 	}
-	if entries, _ := DiffOAuthModelMappingChanges(oldCfg.OAuthModelMappings, newCfg.OAuthModelMappings); len(entries) > 0 {
+	if entries, _ := DiffOAuthModelAliasChanges(oldCfg.OAuthModelAlias, newCfg.OAuthModelAlias); len(entries) > 0 {
 		changes = append(changes, entries...)
 	}
 

internal/watcher/diff/oauth_model_alias.go

@@ -10,23 +10,23 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 )
 
-type OAuthModelMappingsSummary struct {
+type OAuthModelAliasSummary struct {
 	hash  string
 	count int
 }
 
-// SummarizeOAuthModelMappings summarizes OAuth model mappings per channel.
-func SummarizeOAuthModelMappings(entries map[string][]config.ModelNameMapping) map[string]OAuthModelMappingsSummary {
+// SummarizeOAuthModelAlias summarizes OAuth model alias per channel.
+func SummarizeOAuthModelAlias(entries map[string][]config.OAuthModelAlias) map[string]OAuthModelAliasSummary {
 	if len(entries) == 0 {
 		return nil
 	}
-	out := make(map[string]OAuthModelMappingsSummary, len(entries))
+	out := make(map[string]OAuthModelAliasSummary, len(entries))
 	for k, v := range entries {
 		key := strings.ToLower(strings.TrimSpace(k))
 		if key == "" {
 			continue
 		}
-		out[key] = summarizeOAuthModelMappingList(v)
+		out[key] = summarizeOAuthModelAliasList(v)
 	}
 	if len(out) == 0 {
 		return nil
@@ -34,10 +34,10 @@ func SummarizeOAuthModelMappings(entries map[string][]config.ModelNameMapping) m
 	return out
 }
 
-// DiffOAuthModelMappingChanges compares OAuth model mappings maps.
-func DiffOAuthModelMappingChanges(oldMap, newMap map[string][]config.ModelNameMapping) ([]string, []string) {
-	oldSummary := SummarizeOAuthModelMappings(oldMap)
-	newSummary := SummarizeOAuthModelMappings(newMap)
+// DiffOAuthModelAliasChanges compares OAuth model alias maps.
+func DiffOAuthModelAliasChanges(oldMap, newMap map[string][]config.OAuthModelAlias) ([]string, []string) {
+	oldSummary := SummarizeOAuthModelAlias(oldMap)
+	newSummary := SummarizeOAuthModelAlias(newMap)
 	keys := make(map[string]struct{}, len(oldSummary)+len(newSummary))
 	for k := range oldSummary {
 		keys[k] = struct{}{}
@@ -52,13 +52,13 @@ func DiffOAuthModelMappingChanges(oldMap, newMap map[string][]config.ModelNameMa
 		newInfo, okNew := newSummary[key]
 		switch {
 		case okOld && !okNew:
-			changes = append(changes, fmt.Sprintf("oauth-model-mappings[%s]: removed", key))
+			changes = append(changes, fmt.Sprintf("oauth-model-alias[%s]: removed", key))
 			affected = append(affected, key)
 		case !okOld && okNew:
-			changes = append(changes, fmt.Sprintf("oauth-model-mappings[%s]: added (%d entries)", key, newInfo.count))
+			changes = append(changes, fmt.Sprintf("oauth-model-alias[%s]: added (%d entries)", key, newInfo.count))
 			affected = append(affected, key)
 		case okOld && okNew && oldInfo.hash != newInfo.hash:
-			changes = append(changes, fmt.Sprintf("oauth-model-mappings[%s]: updated (%d -> %d entries)", key, oldInfo.count, newInfo.count))
+			changes = append(changes, fmt.Sprintf("oauth-model-alias[%s]: updated (%d -> %d entries)", key, oldInfo.count, newInfo.count))
 			affected = append(affected, key)
 		}
 	}
@@ -67,20 +67,20 @@ func DiffOAuthModelMappingChanges(oldMap, newMap map[string][]config.ModelNameMa
 	return changes, affected
 }
 
-func summarizeOAuthModelMappingList(list []config.ModelNameMapping) OAuthModelMappingsSummary {
+func summarizeOAuthModelAliasList(list []config.OAuthModelAlias) OAuthModelAliasSummary {
 	if len(list) == 0 {
-		return OAuthModelMappingsSummary{}
+		return OAuthModelAliasSummary{}
 	}
 	seen := make(map[string]struct{}, len(list))
 	normalized := make([]string, 0, len(list))
-	for _, mapping := range list {
-		name := strings.ToLower(strings.TrimSpace(mapping.Name))
-		alias := strings.ToLower(strings.TrimSpace(mapping.Alias))
-		if name == "" || alias == "" {
+	for _, alias := range list {
+		name := strings.ToLower(strings.TrimSpace(alias.Name))
+		aliasVal := strings.ToLower(strings.TrimSpace(alias.Alias))
+		if name == "" || aliasVal == "" {
 			continue
 		}
-		key := name + "->" + alias
-		if mapping.Fork {
+		key := name + "->" + aliasVal
+		if alias.Fork {
 			key += "|fork"
 		}
 		if _, exists := seen[key]; exists {
@@ -90,11 +90,11 @@ func summarizeOAuthModelMappingList(list []config.ModelNameMapping) OAuthModelMa
 		normalized = append(normalized, key)
 	}
 	if len(normalized) == 0 {
-		return OAuthModelMappingsSummary{}
+		return OAuthModelAliasSummary{}
 	}
 	sort.Strings(normalized)
 	sum := sha256.Sum256([]byte(strings.Join(normalized, "|")))
-	return OAuthModelMappingsSummary{
+	return OAuthModelAliasSummary{
 		hash:  hex.EncodeToString(sum[:]),
 		count: len(normalized),
 	}