feat(core): agent ingress tokens and Claude Desktop route mapping

Use clovapi--{agent} bearer tokens to identify callers, map Desktop gateway
model aliases to wire models, tag call logs with agentKind, and isolate proxy
tests from the shared call-log database.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: joo

core/cmd/switch_cmd.go

@@ -13,6 +13,7 @@ import (
 	"github.com/clovapi/switcher/internal/apply"
 	"github.com/clovapi/switcher/internal/cliswitch"
 	"github.com/clovapi/switcher/internal/desktop"
+	"github.com/clovapi/switcher/internal/ingresstoken"
 	"github.com/clovapi/switcher/internal/profile"
 	"github.com/clovapi/switcher/internal/syslog"
 )
@@ -314,7 +315,7 @@ func applyDirectToCLI(kind agentkind.Kind, baseURL, apiKey, model, styleStr stri
 	}
 	key := strings.TrimSpace(apiKey)
 	if key == "" {
-		key = "clovapi-local"
+		key = ingresstoken.ForAgent(kind)
 	}
 	p := profile.Profile{
 		Name:     "__direct__",

core/internal/apply/target_claude_desktop.go

@@ -62,7 +62,7 @@ func (claudeDesktopTarget) Apply(p profile.Profile) error {
 		return err
 	}
 	return withClaudeDesktopRollback(paths, func() error {
-		profileJSON := claudeDesktopGatewayProfile(ensureAnthropicWireBaseURL(p.BaseURL), p.APIKey, p.Model)
+		profileJSON := claudeDesktopGatewayProfile(ensureAnthropicWireBaseURL(p.BaseURL), p.APIKey, profile.ClaudeDesktopRouteName(p.Model, 0))
 		if err := writeClaudeDesktopDeploymentMode(paths.normalConfigPath, "3p"); err != nil {
 			return err
 		}

core/internal/apply/target_claude_desktop_test.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/clovapi/switcher/internal/agentkind"
 	"github.com/clovapi/switcher/internal/apistyle"
+	"github.com/clovapi/switcher/internal/ingresstoken"
 	"github.com/clovapi/switcher/internal/profile"
 )
 
@@ -29,7 +30,7 @@ func TestClaudeDesktopApplyWritesThreePProfile(t *testing.T) {
 		CLI:      agentkind.ClaudeDesktop,
 		APIStyle: apistyle.Claude,
 		BaseURL:  "http://127.0.0.1:27483/custom-api/v1",
-		APIKey:   "clovapi-local",
+		APIKey:   ingresstoken.ForAgent(agentkind.ClaudeDesktop),
 		Model:    "gpt-5.5/pro",
 	}
 	if err := (claudeDesktopTarget{}).Apply(p); err != nil {
@@ -51,16 +52,16 @@ func TestClaudeDesktopApplyWritesThreePProfile(t *testing.T) {
 	if prof["inferenceGatewayBaseUrl"] != wantBase {
 		t.Fatalf("base url = %q want %q", prof["inferenceGatewayBaseUrl"], wantBase)
 	}
-	if prof["inferenceGatewayApiKey"] != "clovapi-local" || prof["inferenceGatewayAuthScheme"] != "bearer" || prof["inferenceProvider"] != "gateway" {
+	if prof["inferenceGatewayApiKey"] != "clovapi--claude-desktop" || prof["inferenceGatewayAuthScheme"] != "bearer" || prof["inferenceProvider"] != "gateway" {
 		t.Fatalf("profile auth/provider fields = %#v", prof)
 	}
 	models, ok := prof["inferenceModels"].([]any)
 	if !ok || len(models) != 1 {
 		t.Fatalf("inferenceModels = %#v", prof["inferenceModels"])
 	}
 	model, _ := models[0].(map[string]any)
-	if model["name"] != "gpt-5.5/pro" {
-		t.Fatalf("model route = %#v", model)
+	if model["name"] != "claude-sonnet-4-6" {
+		t.Fatalf("model route = %#v want claude-sonnet-4-6 alias for gpt-5.5/pro", model)
 	}
 	if meta["appliedId"] != claudeDesktopProfileID {
 		t.Fatalf("meta = %#v", meta)
@@ -74,7 +75,7 @@ func TestClaudeDesktopResetRestoresOfficialMode(t *testing.T) {
 		CLI:      agentkind.ClaudeDesktop,
 		APIStyle: apistyle.Claude,
 		BaseURL:  "http://127.0.0.1:27483/custom-api/v1",
-		APIKey:   "clovapi-local",
+		APIKey:   ingresstoken.ForAgent(agentkind.ClaudeDesktop),
 		Model:    "gpt-5.5",
 	}
 	if err := (claudeDesktopTarget{}).Apply(p); err != nil {

core/internal/buildinfo/buildinfo.go

@@ -4,7 +4,7 @@ import "strings"
 
 // Set at link time via -ldflags (see .goreleaser.yaml).
 var (
-	Version = "dev0.1.109"
+	Version = "dev0.1.113"
 	Commit  = "none"
 	Date    = "unknown"
 )

core/internal/desktop/switch.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/clovapi/switcher/internal/agentkind"
 	"github.com/clovapi/switcher/internal/apply"
+	"github.com/clovapi/switcher/internal/ingresstoken"
 	"github.com/clovapi/switcher/internal/profile"
 	"github.com/clovapi/switcher/internal/provider"
 )
@@ -45,7 +46,7 @@ func ApplyProviderModel(kind agentkind.Kind, providerID, modelID string) error {
 		Kind:                   hit.Vendor.Kind,
 		SubscriptionProviderID: hit.Vendor.SubscriptionProviderID,
 		BaseURL:                baseURL,
-		APIKey:                 "clovapi-local",
+		APIKey:                 ingresstoken.ForAgent(kind),
 		Model:                  modelWire,
 		Models:                 hit.Vendor.Models,
 		APIStyle:               ingressStyle,

core/internal/ingresstoken/token.go

@@ -0,0 +1,99 @@
+package ingresstoken
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/clovapi/switcher/internal/agentkind"
+)
+
+const (
+	Prefix = "clovapi--"
+	Legacy = "clovapi-local"
+)
+
+// Auth carries a parsed local proxy ingress bearer token.
+type Auth struct {
+	Token string
+	Agent agentkind.Kind
+}
+
+// ForAgent returns the bearer token written into agent configs for local proxy ingress.
+func ForAgent(kind agentkind.Kind) string {
+	if slug := agentSlug(kind); slug != "" {
+		return Prefix + slug
+	}
+	return Legacy
+}
+
+func agentSlug(kind agentkind.Kind) string {
+	switch kind {
+	case agentkind.ClaudeCode:
+		return "claude-code"
+	case agentkind.ClaudeDesktop:
+		return "claude-desktop"
+	case agentkind.Codex:
+		return "codex"
+	case agentkind.OpenCode:
+		return "opencode"
+	case agentkind.OpenClaw:
+		return "openclaw"
+	case agentkind.Hermes:
+		return "hermes"
+	case agentkind.KimiCode:
+		return "kimi-code"
+	default:
+		return ""
+	}
+}
+
+// FromHTTPRequest parses Authorization: Bearer … from an inbound proxy request.
+func FromHTTPRequest(r *http.Request) Auth {
+	if r == nil {
+		return Auth{}
+	}
+	return ParseBearer(r.Header.Get("Authorization"))
+}
+
+// ParseBearer extracts a clovapi ingress token from an Authorization header value.
+func ParseBearer(authHeader string) Auth {
+	auth := strings.TrimSpace(authHeader)
+	if auth == "" {
+		return Auth{}
+	}
+	const prefix = "Bearer "
+	if !strings.HasPrefix(auth, prefix) && !strings.HasPrefix(auth, "bearer ") {
+		return Auth{}
+	}
+	token := strings.TrimSpace(strings.TrimPrefix(strings.TrimPrefix(auth, "Bearer "), "bearer "))
+	return ParseToken(token)
+}
+
+// ParseToken maps clovapi ingress tokens to agent kinds.
+func ParseToken(token string) Auth {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return Auth{}
+	}
+	if token == Legacy {
+		return Auth{Token: token}
+	}
+	if !strings.HasPrefix(token, Prefix) {
+		return Auth{}
+	}
+	slug := strings.TrimSpace(strings.TrimPrefix(token, Prefix))
+	if slug == "" {
+		return Auth{Token: token}
+	}
+	kind, err := agentkind.Parse(slug)
+	if err != nil {
+		return Auth{Token: token}
+	}
+	return Auth{Token: token, Agent: kind}
+}
+
+// IsClovapiToken reports whether token is a recognized local proxy ingress bearer value.
+func IsClovapiToken(token string) bool {
+	token = strings.TrimSpace(token)
+	return token == Legacy || strings.HasPrefix(token, Prefix)
+}

core/internal/ingresstoken/token_test.go

@@ -0,0 +1,37 @@
+package ingresstoken
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/clovapi/switcher/internal/agentkind"
+)
+
+func TestForAgentUsesAgentSlug(t *testing.T) {
+	if got := ForAgent(agentkind.ClaudeDesktop); got != "clovapi--claude-desktop" {
+		t.Fatalf("token = %q", got)
+	}
+	if got := ForAgent(agentkind.Codex); got != "clovapi--codex" {
+		t.Fatalf("token = %q", got)
+	}
+}
+
+func TestParseTokenRecognizesAgentAndLegacy(t *testing.T) {
+	auth := ParseBearer("Bearer clovapi--claude-desktop")
+	if auth.Token != "clovapi--claude-desktop" || auth.Agent != agentkind.ClaudeDesktop {
+		t.Fatalf("auth = %+v", auth)
+	}
+	auth = ParseToken(Legacy)
+	if auth.Token != Legacy || auth.Agent != "" {
+		t.Fatalf("legacy = %+v", auth)
+	}
+}
+
+func TestFromHTTPRequest(t *testing.T) {
+	req, _ := http.NewRequest(http.MethodGet, "http://127.0.0.1:27483/codex/v1/models", nil)
+	req.Header.Set("Authorization", "Bearer clovapi--hermes")
+	auth := FromHTTPRequest(req)
+	if auth.Agent != agentkind.Hermes {
+		t.Fatalf("auth = %+v", auth)
+	}
+}

core/internal/profile/claude_desktop_route.go

@@ -0,0 +1,130 @@
+package profile
+
+import (
+	"strings"
+
+	"github.com/clovapi/switcher/internal/agentkind"
+)
+
+var claudeDesktopFallbackRoutes = []string{
+	"claude-sonnet-4-6",
+	"claude-sonnet-4-5",
+	"claude-opus-4-6",
+	"claude-haiku-4-5",
+}
+
+var claudeDesktopRouteKeywords = []string{"claude", "sonnet", "opus", "haiku", "anthropic"}
+
+// IsAnthropicGatewayRouteName reports whether name satisfies Claude Desktop gateway validation.
+func IsAnthropicGatewayRouteName(name string) bool {
+	lower := strings.ToLower(strings.TrimSpace(name))
+	if lower == "" {
+		return false
+	}
+	for _, kw := range claudeDesktopRouteKeywords {
+		if strings.Contains(lower, kw) {
+			return true
+		}
+	}
+	return false
+}
+
+// ClaudeDesktopRouteName returns the model route Claude Desktop accepts for inferenceModels.
+// Non-Anthropic wire names are mapped to stable Claude-style aliases; the proxy resolves them back.
+func ClaudeDesktopRouteName(wireModel string, index int) string {
+	wireModel = strings.TrimSpace(wireModel)
+	if IsAnthropicGatewayRouteName(wireModel) {
+		return wireModel
+	}
+	if index < 0 {
+		index = 0
+	}
+	return claudeDesktopFallbackRoutes[index%len(claudeDesktopFallbackRoutes)]
+}
+
+// ResolveModelIDFromClaudeDesktopRoute maps a Desktop gateway route back to a persisted model id.
+func ResolveModelIDFromClaudeDesktopRoute(store *Store, providerID, routeName string) (string, bool) {
+	routeName = strings.TrimSpace(routeName)
+	if store == nil || routeName == "" {
+		return "", false
+	}
+	providerID = strings.TrimSpace(providerID)
+	for _, prof := range store.List {
+		if ProviderIDFromStoreProfile(prof) != providerID {
+			continue
+		}
+		for i, raw := range prof.Models {
+			m := NormalizeModelEntry(raw, i)
+			wire := strings.TrimSpace(firstNonEmpty(m.Model, m.ID))
+			route := ClaudeDesktopRouteName(wire, i)
+			if routeName == route || routeName == m.ID || routeName == wire {
+				id := strings.TrimSpace(m.ID)
+				if id == "" {
+					id = wire
+				}
+				return id, id != ""
+			}
+		}
+		break
+	}
+	return "", false
+}
+
+// ClaudeDesktopRouteIDs lists gateway route ids for models under providerID.
+func ClaudeDesktopRouteIDs(store *Store, providerID string) []string {
+	if store == nil {
+		return nil
+	}
+	providerID = strings.TrimSpace(providerID)
+	seen := map[string]bool{}
+	var routes []string
+	add := func(route string) {
+		route = strings.TrimSpace(route)
+		if route == "" || seen[route] {
+			return
+		}
+		seen[route] = true
+		routes = append(routes, route)
+	}
+	for _, prof := range store.List {
+		if ProviderIDFromStoreProfile(prof) != providerID {
+			continue
+		}
+		if len(prof.Models) == 0 {
+			add(ClaudeDesktopRouteName(prof.Model, 0))
+			break
+		}
+		for i, raw := range prof.Models {
+			m := NormalizeModelEntry(raw, i)
+			wire := strings.TrimSpace(firstNonEmpty(m.Model, m.ID))
+			add(ClaudeDesktopRouteName(wire, i))
+		}
+		break
+	}
+	return routes
+}
+
+// ResolveIngressModelID maps Claude Desktop gateway routes back to persisted model ids.
+func ResolveIngressModelID(store *Store, providerID, modelID string) string {
+	modelID = strings.TrimSpace(modelID)
+	if modelID == "" || store == nil {
+		return modelID
+	}
+	if wire, ok := ResolveModelIDFromClaudeDesktopRoute(store, providerID, modelID); ok {
+		return wire
+	}
+	if !IsAnthropicGatewayRouteName(modelID) {
+		return modelID
+	}
+	sel, ok := store.Active[string(agentkind.ClaudeDesktop)]
+	if !ok {
+		return modelID
+	}
+	if strings.TrimSpace(sel.ProviderID) != strings.TrimSpace(providerID) {
+		return modelID
+	}
+	if wire := strings.TrimSpace(sel.ModelID); wire != "" {
+		return wire
+	}
+	return modelID
+}