v6.5.32

.gitignore

@@ -15,6 +15,7 @@ pgstore/*
 gitstore/*
 objectstore/*
 static/*
+refs/*
 
 # Authentication data
 auths/*
@@ -30,3 +31,7 @@ GEMINI.md
 .vscode/*
 .claude/*
 .serena/*
+
+# macOS
+.DS_Store
+._*

config.example.yaml

@@ -55,6 +55,28 @@ quota-exceeded:
 # When true, enable authentication for the WebSocket API (/v1/ws).
 ws-auth: false
 
+# Amp CLI Integration
+# Configure upstream URL for Amp CLI OAuth and management features
+#amp-upstream-url: "https://ampcode.com"
+
+# Optional: Override API key for Amp upstream (otherwise uses env or file)
+#amp-upstream-api-key: ""
+
+# Restrict Amp management routes (/api/auth, /api/user, etc.) to localhost only (recommended)
+#amp-restrict-management-to-localhost: true
+
+# Amp Model Mappings
+# Route unavailable Amp models to alternative models available in your local proxy.
+# Useful when Amp CLI requests models you don't have access to (e.g., Claude Opus 4.5)
+# but you have a similar model available (e.g., Claude Sonnet 4).
+#amp-model-mappings:
+#  - from: "claude-opus-4.5"       # Model requested by Amp CLI
+#    to: "claude-sonnet-4"         # Route to this available model instead
+#  - from: "gpt-5"
+#    to: "gemini-2.5-pro"
+#  - from: "claude-3-opus-20240229"
+#    to: "claude-3-5-sonnet-20241022"
+
 # Gemini API keys (preferred)
 #gemini-api-key:
 #  - api-key: "AIzaSy...01"
@@ -123,6 +145,19 @@ ws-auth: false
 #      - name: "moonshotai/kimi-k2:free" # The actual model name.
 #        alias: "kimi-k2" # The alias used in the API.
 
+# Vertex API keys (Vertex-compatible endpoints, use API key + base URL)
+#vertex-api-key:
+#  - api-key: "vk-123..."                        # x-goog-api-key header
+#    base-url: "https://example.com/api"         # e.g. https://zenmux.ai/api
+#    proxy-url: "socks5://proxy.example.com:1080" # optional per-key proxy override
+#    headers:
+#      X-Custom-Header: "custom-value"
+#    models:                                     # optional: map aliases to upstream model names
+#      - name: "gemini-2.0-flash"                # upstream model name
+#        alias: "vertex-flash"                   # client-visible alias
+#      - name: "gemini-1.5-pro"
+#        alias: "vertex-pro"
+
 #payload: # Optional payload configuration
 #  default: # Default rules only set parameters when they are missing in the payload.
 #    - models:

docs/amp-cli-integration.md

@@ -8,6 +8,7 @@ This guide explains how to use CLIProxyAPI with Amp CLI and Amp IDE extensions,
   - [Which Providers Should You Authenticate?](#which-providers-should-you-authenticate)
 - [Architecture](#architecture)
 - [Configuration](#configuration)
+  - [Model Mapping Configuration](#model-mapping-configuration)
 - [Setup](#setup)
 - [Usage](#usage)
 - [Troubleshooting](#troubleshooting)
@@ -21,6 +22,7 @@ The Amp CLI integration adds specialized routing to support Amp's API patterns w
 - **Provider route aliases**: Maps Amp's `/api/provider/{provider}/v1...` patterns to CLIProxyAPI handlers
 - **Management proxy**: Forwards OAuth and account management requests to Amp's control plane
 - **Smart fallback**: Automatically routes unconfigured models to ampcode.com
+- **Model mapping**: Route unavailable models to alternatives you have access to (e.g., `claude-opus-4.5` → `claude-sonnet-4`)
 - **Secret management**: Configurable precedence (config > env > file) with 5-minute caching
 - **Security-first**: Management routes restricted to localhost by default
 - **Automatic gzip handling**: Decompresses responses from Amp upstream
@@ -75,7 +77,10 @@ Amp CLI/IDE
   │   ↓
   │   ├─ Model configured locally?
   │   │   YES → Use local OAuth tokens (OpenAI/Claude/Gemini handlers)
-  │   │   NO  → Forward to ampcode.com (reverse proxy)
+  │   │   NO  ↓
+  │   │       ├─ Model mapping configured?
+  │   │       │   YES → Rewrite model → Use local handler (free)
+  │   │       │   NO  → Forward to ampcode.com (uses Amp credits)
   │   ↓
   │   Response
   │
@@ -115,6 +120,49 @@ amp-upstream-url: "https://ampcode.com"
 amp-restrict-management-to-localhost: true
 ```
 
+### Model Mapping Configuration
+
+When Amp CLI requests a model that you don't have access to, you can configure mappings to route those requests to alternative models that you DO have available. This avoids consuming Amp credits for models you could handle locally.
+
+```yaml
+# Route unavailable models to alternatives
+amp-model-mappings:
+  # Example: Route Claude Opus 4.5 requests to Claude Sonnet 4
+  - from: "claude-opus-4.5"
+    to: "claude-sonnet-4"
+
+  # Example: Route GPT-5 requests to Gemini 2.5 Pro
+  - from: "gpt-5"
+    to: "gemini-2.5-pro"
+
+  # Example: Map older model names to newer versions
+  - from: "claude-3-opus-20240229"
+    to: "claude-3-5-sonnet-20241022"
+```
+
+**How it works:**
+
+1. Amp CLI requests a model (e.g., `claude-opus-4.5`)
+2. CLIProxyAPI checks if a local provider is available for that model
+3. If not available, it checks the model mappings
+4. If a mapping exists, the request is rewritten to use the target model
+5. The request is then handled locally (free, using your OAuth subscription)
+
+**Benefits:**
+- **Save Amp credits**: Use your local subscriptions instead of forwarding to ampcode.com
+- **Hot-reload**: Mappings can be updated without restarting the proxy
+- **Structured logging**: Clear logs show when mappings are applied
+
+**Routing Decision Logs:**
+
+The proxy logs each routing decision with structured fields:
+
+```
+[AMP] Using local provider for model: gemini-2.5-pro          # Local provider (free)
+[AMP] Model mapped: claude-opus-4.5 -> claude-sonnet-4        # Mapping applied (free)
+[AMP] Forwarding to ampcode.com (uses Amp credits) - model_id: gpt-5  # Fallback (costs credits)
+```
+
 ### Secret Resolution Precedence
 
 The Amp module resolves API keys using this precedence order:
@@ -301,11 +349,14 @@ When Amp requests a model:
 
 1. **Check local configuration**: Does CLIProxyAPI have OAuth tokens for this model's provider?
 2. **If YES**: Route to local handler (use your OAuth subscription)
-3. **If NO**: Forward to ampcode.com (use Amp's default routing)
+3. **If NO**: Check if a model mapping exists
+4. **If mapping exists**: Rewrite request to mapped model → Route to local handler (free)
+5. **If no mapping**: Forward to ampcode.com (uses Amp credits)
 
 This enables seamless mixed usage:
 - Models you've configured (Gemini, ChatGPT, Claude) → Your OAuth subscriptions
-- Models you haven't configured → Amp's default providers
+- Models with mappings configured → Routed to alternative local models (free)
+- Models you haven't configured and have no mapping → Amp's default providers (uses credits)
 
 ### Example API Calls
 

internal/api/modules/amp/amp.go

@@ -23,11 +23,13 @@ type Option func(*AmpModule)
 //   - Reverse proxy to Amp control plane for OAuth/management
 //   - Provider-specific route aliases (/api/provider/{provider}/...)
 //   - Automatic gzip decompression for misconfigured upstreams
+//   - Model mapping for routing unavailable models to alternatives
 type AmpModule struct {
 	secretSource    SecretSource
 	proxy           *httputil.ReverseProxy
 	accessManager   *sdkaccess.Manager
 	authMiddleware_ gin.HandlerFunc
+	modelMapper     *DefaultModelMapper
 	enabled         bool
 	registerOnce    sync.Once
 }
@@ -101,6 +103,9 @@ func (m *AmpModule) Register(ctx modules.Context) error {
 	// Use registerOnce to ensure routes are only registered once
 	var regErr error
 	m.registerOnce.Do(func() {
+		// Initialize model mapper from config (for routing unavailable models to alternatives)
+		m.modelMapper = NewModelMapper(ctx.Config.AmpModelMappings)
+
 		// Always register provider aliases - these work without an upstream
 		m.registerProviderAliases(ctx.Engine, ctx.BaseHandler, auth)
 
@@ -159,8 +164,16 @@ func (m *AmpModule) getAuthMiddleware(ctx modules.Context) gin.HandlerFunc {
 // OnConfigUpdated handles configuration updates.
 // Currently requires restart for URL changes (could be enhanced for dynamic updates).
 func (m *AmpModule) OnConfigUpdated(cfg *config.Config) error {
+	// Update model mappings (hot-reload supported)
+	if m.modelMapper != nil {
+		log.Infof("amp config updated: reloading %d model mapping(s)", len(cfg.AmpModelMappings))
+		m.modelMapper.UpdateMappings(cfg.AmpModelMappings)
+	} else {
+		log.Warnf("amp model mapper not initialized, skipping model mapping update")
+	}
+
 	if !m.enabled {
-		log.Debug("Amp routing not enabled, skipping config update")
+		log.Debug("Amp routing not enabled, skipping other config updates")
 		return nil
 	}
 
@@ -181,3 +194,8 @@ func (m *AmpModule) OnConfigUpdated(cfg *config.Config) error {
 	log.Debug("Amp config updated (restart required for URL changes)")
 	return nil
 }
+
+// GetModelMapper returns the model mapper instance (for testing/debugging).
+func (m *AmpModule) GetModelMapper() *DefaultModelMapper {
+	return m.modelMapper
+}