Support multiple Claude API keys with round-robin

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

internal/config/config.go

@@ -270,12 +270,26 @@ type CloakConfig struct {
 	SensitiveWords []string `yaml:"sensitive-words,omitempty" json:"sensitive-words,omitempty"`
 }
 
+// ClaudeAPIKeyEntry represents an API key configuration with optional proxy setting for Claude.
+type ClaudeAPIKeyEntry struct {
+	// APIKey is the authentication key for accessing Claude API services.
+	APIKey string `yaml:"api-key" json:"api-key"`
+
+	// ProxyURL overrides the global proxy setting for this API key if provided.
+	ProxyURL string `yaml:"proxy-url,omitempty" json:"proxy-url,omitempty"`
+}
+
 // ClaudeKey represents the configuration for a Claude API key,
 // including the API key itself and an optional base URL for the API endpoint.
 type ClaudeKey struct {
 	// APIKey is the authentication key for accessing Claude API services.
+	// Deprecated: Use APIKeyEntries for multiple API keys with round-robin support.
 	APIKey string `yaml:"api-key" json:"api-key"`
 
+	// APIKeyEntries defines API keys with optional per-key proxy configuration.
+	// When provided, each entry creates a separate Auth for round-robin load balancing.
+	APIKeyEntries []ClaudeAPIKeyEntry `yaml:"api-key-entries,omitempty" json:"api-key-entries,omitempty"`
+
 	// Priority controls selection preference when multiple credentials match.
 	// Higher values are preferred; defaults to 0.
 	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
@@ -288,6 +302,7 @@ type ClaudeKey struct {
 	BaseURL string `yaml:"base-url" json:"base-url"`
 
 	// ProxyURL overrides the global proxy setting for this API key if provided.
+	// Used as fallback when APIKeyEntries is empty or when entries don't specify ProxyURL.
 	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`
 
 	// Models defines upstream model names and aliases for request routing.
@@ -787,7 +802,7 @@ func (cfg *Config) SanitizeCodexKeys() {
 	cfg.CodexKey = out
 }
 
-// SanitizeClaudeKeys normalizes headers for Claude credentials.
+// SanitizeClaudeKeys normalizes headers and API key entries for Claude credentials.
 func (cfg *Config) SanitizeClaudeKeys() {
 	if cfg == nil || len(cfg.ClaudeKey) == 0 {
 		return
@@ -797,6 +812,15 @@ func (cfg *Config) SanitizeClaudeKeys() {
 		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)
+		}
 	}
 }
 

internal/watcher/diff/config_diff.go

@@ -125,6 +125,11 @@ func BuildConfigChangeDetails(oldCfg, newCfg *config.Config) []string {
 			if strings.TrimSpace(o.APIKey) != strings.TrimSpace(n.APIKey) {
 				changes = append(changes, fmt.Sprintf("claude[%d].api-key: updated", i))
 			}
+			if len(o.APIKeyEntries) != len(n.APIKeyEntries) {
+				changes = append(changes, fmt.Sprintf("claude[%d].api-key-entries count: %d -> %d", i, len(o.APIKeyEntries), len(n.APIKeyEntries)))
+			} else if !equalClaudeAPIKeyEntries(o.APIKeyEntries, n.APIKeyEntries) {
+				changes = append(changes, fmt.Sprintf("claude[%d].api-key-entries: updated", i))
+			}
 			if !equalStringMap(o.Headers, n.Headers) {
 				changes = append(changes, fmt.Sprintf("claude[%d].headers: updated", i))
 			}
@@ -367,3 +372,19 @@ func equalUpstreamAPIKeys(a, b []config.AmpUpstreamAPIKeyEntry) bool {
 	}
 	return true
 }
+
+// equalClaudeAPIKeyEntries compares two slices of ClaudeAPIKeyEntry for equality.
+func equalClaudeAPIKeyEntries(a, b []config.ClaudeAPIKeyEntry) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if strings.TrimSpace(a[i].APIKey) != strings.TrimSpace(b[i].APIKey) {
+			return false
+		}
+		if strings.TrimSpace(a[i].ProxyURL) != strings.TrimSpace(b[i].ProxyURL) {
+			return false
+		}
+	}
+	return true
+}

internal/watcher/synthesizer/config.go

@@ -77,7 +77,7 @@ func (s *ConfigSynthesizer) synthesizeKiroKeys(ctx *SynthesisContext) []*coreaut
 		}
 
 		attrs := map[string]string{
-			"source":  fmt.Sprintf("config:kiro[%s]", suffix),
+			"source": fmt.Sprintf("config:kiro[%s]", suffix),
 		}
 		if entry.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(entry.Priority)
@@ -156,44 +156,93 @@ func (s *ConfigSynthesizer) synthesizeClaudeKeys(ctx *SynthesisContext) []*corea
 	now := ctx.Now
 	idGen := ctx.IDGenerator
 
-	out := make([]*coreauth.Auth, 0, len(cfg.ClaudeKey))
+	out := make([]*coreauth.Auth, 0)
 	for i := range cfg.ClaudeKey {
 		ck := cfg.ClaudeKey[i]
-		key := strings.TrimSpace(ck.APIKey)
-		if key == "" {
-			continue
-		}
 		prefix := strings.TrimSpace(ck.Prefix)
 		base := strings.TrimSpace(ck.BaseURL)
-		id, token := idGen.Next("claude:apikey", key, base)
-		attrs := map[string]string{
-			"source":  fmt.Sprintf("config:claude[%s]", token),
-			"api_key": key,
-		}
-		if ck.Priority != 0 {
-			attrs["priority"] = strconv.Itoa(ck.Priority)
-		}
-		if base != "" {
-			attrs["base_url"] = base
-		}
-		if hash := diff.ComputeClaudeModelsHash(ck.Models); hash != "" {
-			attrs["models_hash"] = hash
+
+		// Handle new APIKeyEntries format (preferred) for round-robin support
+		createdEntries := 0
+		for j := range ck.APIKeyEntries {
+			entry := &ck.APIKeyEntries[j]
+			key := strings.TrimSpace(entry.APIKey)
+			if key == "" {
+				continue
+			}
+			// Use entry proxy if set, otherwise fall back to key-level proxy
+			proxyURL := strings.TrimSpace(entry.ProxyURL)
+			if proxyURL == "" {
+				proxyURL = strings.TrimSpace(ck.ProxyURL)
+			}
+
+			id, token := idGen.Next("claude:apikey", key, base, proxyURL)
+			attrs := map[string]string{
+				"source":  fmt.Sprintf("config:claude[%s]", token),
+				"api_key": key,
+			}
+			if ck.Priority != 0 {
+				attrs["priority"] = strconv.Itoa(ck.Priority)
+			}
+			if base != "" {
+				attrs["base_url"] = base
+			}
+			if hash := diff.ComputeClaudeModelsHash(ck.Models); hash != "" {
+				attrs["models_hash"] = hash
+			}
+			addConfigHeadersToAttrs(ck.Headers, attrs)
+			a := &coreauth.Auth{
+				ID:         id,
+				Provider:   "claude",
+				Label:      "claude-apikey",
+				Prefix:     prefix,
+				Status:     coreauth.StatusActive,
+				ProxyURL:   proxyURL,
+				Attributes: attrs,
+				CreatedAt:  now,
+				UpdatedAt:  now,
+			}
+			ApplyAuthExcludedModelsMeta(a, cfg, ck.ExcludedModels, "apikey")
+			out = append(out, a)
+			createdEntries++
 		}
-		addConfigHeadersToAttrs(ck.Headers, attrs)
-		proxyURL := strings.TrimSpace(ck.ProxyURL)
-		a := &coreauth.Auth{
-			ID:         id,
-			Provider:   "claude",
-			Label:      "claude-apikey",
-			Prefix:     prefix,
-			Status:     coreauth.StatusActive,
-			ProxyURL:   proxyURL,
-			Attributes: attrs,
-			CreatedAt:  now,
-			UpdatedAt:  now,
+
+		// Fallback: use single APIKey if no APIKeyEntries (backward compatibility)
+		if createdEntries == 0 {
+			key := strings.TrimSpace(ck.APIKey)
+			if key == "" {
+				continue
+			}
+			proxyURL := strings.TrimSpace(ck.ProxyURL)
+			id, token := idGen.Next("claude:apikey", key, base, proxyURL)
+			attrs := map[string]string{
+				"source":  fmt.Sprintf("config:claude[%s]", token),
+				"api_key": key,
+			}
+			if ck.Priority != 0 {
+				attrs["priority"] = strconv.Itoa(ck.Priority)
+			}
+			if base != "" {
+				attrs["base_url"] = base
+			}
+			if hash := diff.ComputeClaudeModelsHash(ck.Models); hash != "" {
+				attrs["models_hash"] = hash
+			}
+			addConfigHeadersToAttrs(ck.Headers, attrs)
+			a := &coreauth.Auth{
+				ID:         id,
+				Provider:   "claude",
+				Label:      "claude-apikey",
+				Prefix:     prefix,
+				Status:     coreauth.StatusActive,
+				ProxyURL:   proxyURL,
+				Attributes: attrs,
+				CreatedAt:  now,
+				UpdatedAt:  now,
+			}
+			ApplyAuthExcludedModelsMeta(a, cfg, ck.ExcludedModels, "apikey")
+			out = append(out, a)
 		}
-		ApplyAuthExcludedModelsMeta(a, cfg, ck.ExcludedModels, "apikey")
-		out = append(out, a)
 	}
 	return out
 }