Merge pull request #634 from router-for-me/amp

fix(amp): add /docs routes to proxy

cmd/server/main.go

@@ -405,7 +405,7 @@ func main() {
 	usage.SetStatisticsEnabled(cfg.UsageStatisticsEnabled)
 	coreauth.SetQuotaCooldownDisabled(cfg.DisableCooling)
 
-	if err = logging.ConfigureLogOutput(cfg.LoggingToFile); err != nil {
+	if err = logging.ConfigureLogOutput(cfg.LoggingToFile, cfg.LogsMaxTotalSizeMB); err != nil {
 		log.Errorf("failed to configure log output: %v", err)
 		return
 	}

config.example.yaml

@@ -42,6 +42,10 @@ debug: false
 # When true, write application logs to rotating files instead of stdout
 logging-to-file: false
 
+# Maximum total size (MB) of log files under the logs directory. When exceeded, the oldest log
+# files are deleted until within the limit. Set to 0 to disable.
+logs-max-total-size-mb: 0
+
 # When false, disable in-memory usage statistics aggregation
 usage-statistics-enabled: false
 

examples/custom-provider/main.go

@@ -23,13 +23,13 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/api"
-	"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/sdk/api"
 	sdkAuth "github.com/router-for-me/CLIProxyAPI/v6/sdk/auth"
 	"github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
 	clipexec "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/executor"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/logging"
 	sdktr "github.com/router-for-me/CLIProxyAPI/v6/sdk/translator"
 )
 

internal/api/modules/amp/routes.go

@@ -126,7 +126,7 @@ func (m *AmpModule) registerManagementRoutes(engine *gin.Engine, baseHandler *ha
 	var authWithBypass gin.HandlerFunc
 	if auth != nil {
 		ampAPI.Use(auth)
-		authWithBypass = wrapManagementAuth(auth, "/threads", "/auth")
+		authWithBypass = wrapManagementAuth(auth, "/threads", "/auth", "/docs")
 	}
 
 	// Dynamic proxy handler that uses m.getProxy() for hot-reload support
@@ -175,7 +175,11 @@ func (m *AmpModule) registerManagementRoutes(engine *gin.Engine, baseHandler *ha
 	if authWithBypass != nil {
 		rootMiddleware = append(rootMiddleware, authWithBypass)
 	}
+	engine.GET("/threads", append(rootMiddleware, proxyHandler)...)
 	engine.GET("/threads/*path", append(rootMiddleware, proxyHandler)...)
+	engine.GET("/docs", append(rootMiddleware, proxyHandler)...)
+	engine.GET("/docs/*path", append(rootMiddleware, proxyHandler)...)
+
 	engine.GET("/threads.rss", append(rootMiddleware, proxyHandler)...)
 	engine.GET("/news.rss", append(rootMiddleware, proxyHandler)...)
 

internal/api/server.go

@@ -844,11 +844,20 @@ func (s *Server) UpdateClients(cfg *config.Config) {
 		}
 	}
 
-	if oldCfg != nil && oldCfg.LoggingToFile != cfg.LoggingToFile {
-		if err := logging.ConfigureLogOutput(cfg.LoggingToFile); err != nil {
+	if oldCfg == nil || oldCfg.LoggingToFile != cfg.LoggingToFile || oldCfg.LogsMaxTotalSizeMB != cfg.LogsMaxTotalSizeMB {
+		if err := logging.ConfigureLogOutput(cfg.LoggingToFile, cfg.LogsMaxTotalSizeMB); err != nil {
 			log.Errorf("failed to reconfigure log output: %v", err)
 		} else {
-			log.Debugf("logging_to_file updated from %t to %t", oldCfg.LoggingToFile, cfg.LoggingToFile)
+			if oldCfg == nil {
+				log.Debug("log output configuration refreshed")
+			} else {
+				if oldCfg.LoggingToFile != cfg.LoggingToFile {
+					log.Debugf("logging_to_file updated from %t to %t", oldCfg.LoggingToFile, cfg.LoggingToFile)
+				}
+				if oldCfg.LogsMaxTotalSizeMB != cfg.LogsMaxTotalSizeMB {
+					log.Debugf("logs_max_total_size_mb updated from %d to %d", oldCfg.LogsMaxTotalSizeMB, cfg.LogsMaxTotalSizeMB)
+				}
+			}
 		}
 	}
 

internal/config/config.go

@@ -12,7 +12,6 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 	"golang.org/x/crypto/bcrypt"
 	"gopkg.in/yaml.v3"
 )
@@ -21,7 +20,7 @@ const DefaultPanelGitHubRepository = "https://github.com/router-for-me/Cli-Proxy
 
 // Config represents the application's configuration, loaded from a YAML file.
 type Config struct {
-	config.SDKConfig `yaml:",inline"`
+	SDKConfig `yaml:",inline"`
 	// Host is the network host/interface on which the API server will bind.
 	// Default is empty ("") to bind all interfaces (IPv4 + IPv6). Use "127.0.0.1" or "localhost" for local-only access.
 	Host string `yaml:"host" json:"-"`
@@ -43,6 +42,10 @@ type Config struct {
 	// LoggingToFile controls whether application logs are written to rotating files or stdout.
 	LoggingToFile bool `yaml:"logging-to-file" json:"logging-to-file"`
 
+	// LogsMaxTotalSizeMB limits the total size (in MB) of log files under the logs directory.
+	// When exceeded, the oldest log files are deleted until within the limit. Set to 0 to disable.
+	LogsMaxTotalSizeMB int `yaml:"logs-max-total-size-mb" json:"logs-max-total-size-mb"`
+
 	// UsageStatisticsEnabled toggles in-memory usage aggregation; when false, usage data is discarded.
 	UsageStatisticsEnabled bool `yaml:"usage-statistics-enabled" json:"usage-statistics-enabled"`
 
@@ -342,6 +345,7 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	// Set defaults before unmarshal so that absent keys keep defaults.
 	cfg.Host = "" // Default empty: binds to all interfaces (IPv4 + IPv6)
 	cfg.LoggingToFile = false
+	cfg.LogsMaxTotalSizeMB = 0
 	cfg.UsageStatisticsEnabled = false
 	cfg.DisableCooling = false
 	cfg.AmpCode.RestrictManagementToLocalhost = false // Default to false: API key auth is sufficient
@@ -386,6 +390,10 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 		cfg.RemoteManagement.PanelGitHubRepository = DefaultPanelGitHubRepository
 	}
 
+	if cfg.LogsMaxTotalSizeMB < 0 {
+		cfg.LogsMaxTotalSizeMB = 0
+	}
+
 	// Sync request authentication providers with inline API keys for backwards compatibility.
 	syncInlineAccessProvider(&cfg)
 
@@ -692,7 +700,7 @@ func sanitizeConfigForPersist(cfg *Config) *Config {
 	}
 	clone := *cfg
 	clone.SDKConfig = cfg.SDKConfig
-	clone.SDKConfig.Access = config.AccessConfig{}
+	clone.SDKConfig.Access = AccessConfig{}
 	return &clone
 }
 

internal/config/sdk_config.go

@@ -0,0 +1,87 @@
+// Package config provides configuration management for the CLI Proxy API server.
+// It handles loading and parsing YAML configuration files, and provides structured
+// access to application settings including server port, authentication directory,
+// debug settings, proxy configuration, and API keys.
+package config
+
+// SDKConfig represents the application's configuration, loaded from a YAML file.
+type SDKConfig struct {
+	// ProxyURL is the URL of an optional proxy server to use for outbound requests.
+	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`
+
+	// ForceModelPrefix requires explicit model prefixes (e.g., "teamA/gemini-3-pro-preview")
+	// to target prefixed credentials. When false, unprefixed model requests may use prefixed
+	// credentials as well.
+	ForceModelPrefix bool `yaml:"force-model-prefix" json:"force-model-prefix"`
+
+	// RequestLog enables or disables detailed request logging functionality.
+	RequestLog bool `yaml:"request-log" json:"request-log"`
+
+	// APIKeys is a list of keys for authenticating clients to this proxy server.
+	APIKeys []string `yaml:"api-keys" json:"api-keys"`
+
+	// Access holds request authentication provider configuration.
+	Access AccessConfig `yaml:"auth,omitempty" json:"auth,omitempty"`
+}
+
+// AccessConfig groups request authentication providers.
+type AccessConfig struct {
+	// Providers lists configured authentication providers.
+	Providers []AccessProvider `yaml:"providers,omitempty" json:"providers,omitempty"`
+}
+
+// AccessProvider describes a request authentication provider entry.
+type AccessProvider struct {
+	// Name is the instance identifier for the provider.
+	Name string `yaml:"name" json:"name"`
+
+	// Type selects the provider implementation registered via the SDK.
+	Type string `yaml:"type" json:"type"`
+
+	// SDK optionally names a third-party SDK module providing this provider.
+	SDK string `yaml:"sdk,omitempty" json:"sdk,omitempty"`
+
+	// APIKeys lists inline keys for providers that require them.
+	APIKeys []string `yaml:"api-keys,omitempty" json:"api-keys,omitempty"`
+
+	// Config passes provider-specific options to the implementation.
+	Config map[string]any `yaml:"config,omitempty" json:"config,omitempty"`
+}
+
+const (
+	// AccessProviderTypeConfigAPIKey is the built-in provider validating inline API keys.
+	AccessProviderTypeConfigAPIKey = "config-api-key"
+
+	// DefaultAccessProviderName is applied when no provider name is supplied.
+	DefaultAccessProviderName = "config-inline"
+)
+
+// ConfigAPIKeyProvider returns the first inline API key provider if present.
+func (c *SDKConfig) ConfigAPIKeyProvider() *AccessProvider {
+	if c == nil {
+		return nil
+	}
+	for i := range c.Access.Providers {
+		if c.Access.Providers[i].Type == AccessProviderTypeConfigAPIKey {
+			if c.Access.Providers[i].Name == "" {
+				c.Access.Providers[i].Name = DefaultAccessProviderName
+			}
+			return &c.Access.Providers[i]
+		}
+	}
+	return nil
+}
+
+// MakeInlineAPIKeyProvider constructs an inline API key provider configuration.
+// It returns nil when no keys are supplied.
+func MakeInlineAPIKeyProvider(keys []string) *AccessProvider {
+	if len(keys) == 0 {
+		return nil
+	}
+	provider := &AccessProvider{
+		Name:    DefaultAccessProviderName,
+		Type:    AccessProviderTypeConfigAPIKey,
+		APIKeys: append([]string(nil), keys...),
+	}
+	return provider
+}

internal/logging/global_logger.go

@@ -72,39 +72,45 @@ func SetupBaseLogger() {
 }
 
 // ConfigureLogOutput switches the global log destination between rotating files and stdout.
-func ConfigureLogOutput(loggingToFile bool) error {
+// When logsMaxTotalSizeMB > 0, a background cleaner removes the oldest log files in the logs directory
+// until the total size is within the limit.
+func ConfigureLogOutput(loggingToFile bool, logsMaxTotalSizeMB int) error {
 	SetupBaseLogger()
 
 	writerMu.Lock()
 	defer writerMu.Unlock()
 
+	logDir := "logs"
+	if base := util.WritablePath(); base != "" {
+		logDir = filepath.Join(base, "logs")
+	}
+
+	protectedPath := ""
 	if loggingToFile {
-		logDir := "logs"
-		if base := util.WritablePath(); base != "" {
-			logDir = filepath.Join(base, "logs")
-		}
 		if err := os.MkdirAll(logDir, 0o755); err != nil {
 			return fmt.Errorf("logging: failed to create log directory: %w", err)
 		}
 		if logWriter != nil {
 			_ = logWriter.Close()
 		}
+		protectedPath = filepath.Join(logDir, "main.log")
 		logWriter = &lumberjack.Logger{
-			Filename:   filepath.Join(logDir, "main.log"),
+			Filename:   protectedPath,
 			MaxSize:    10,
 			MaxBackups: 0,
 			MaxAge:     0,
 			Compress:   false,
 		}
 		log.SetOutput(logWriter)
-		return nil
+	} else {
+		if logWriter != nil {
+			_ = logWriter.Close()
+			logWriter = nil
+		}
+		log.SetOutput(os.Stdout)
 	}
 
-	if logWriter != nil {
-		_ = logWriter.Close()
-		logWriter = nil
-	}
-	log.SetOutput(os.Stdout)
+	configureLogDirCleanerLocked(logDir, logsMaxTotalSizeMB, protectedPath)
 	return nil
 }
 
@@ -112,6 +118,8 @@ func closeLogOutputs() {
 	writerMu.Lock()
 	defer writerMu.Unlock()
 
+	stopLogDirCleanerLocked()
+
 	if logWriter != nil {
 		_ = logWriter.Close()
 		logWriter = nil

internal/logging/log_dir_cleaner.go

@@ -0,0 +1,166 @@
+package logging
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const logDirCleanerInterval = time.Minute
+
+var logDirCleanerCancel context.CancelFunc
+
+func configureLogDirCleanerLocked(logDir string, maxTotalSizeMB int, protectedPath string) {
+	stopLogDirCleanerLocked()
+
+	if maxTotalSizeMB <= 0 {
+		return
+	}
+
+	maxBytes := int64(maxTotalSizeMB) * 1024 * 1024
+	if maxBytes <= 0 {
+		return
+	}
+
+	dir := strings.TrimSpace(logDir)
+	if dir == "" {
+		return
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	logDirCleanerCancel = cancel
+	go runLogDirCleaner(ctx, filepath.Clean(dir), maxBytes, strings.TrimSpace(protectedPath))
+}
+
+func stopLogDirCleanerLocked() {
+	if logDirCleanerCancel == nil {
+		return
+	}
+	logDirCleanerCancel()
+	logDirCleanerCancel = nil
+}
+
+func runLogDirCleaner(ctx context.Context, logDir string, maxBytes int64, protectedPath string) {
+	ticker := time.NewTicker(logDirCleanerInterval)
+	defer ticker.Stop()
+
+	cleanOnce := func() {
+		deleted, errClean := enforceLogDirSizeLimit(logDir, maxBytes, protectedPath)
+		if errClean != nil {
+			log.WithError(errClean).Warn("logging: failed to enforce log directory size limit")
+			return
+		}
+		if deleted > 0 {
+			log.Debugf("logging: removed %d old log file(s) to enforce log directory size limit", deleted)
+		}
+	}
+
+	cleanOnce()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			cleanOnce()
+		}
+	}
+}
+
+func enforceLogDirSizeLimit(logDir string, maxBytes int64, protectedPath string) (int, error) {
+	if maxBytes <= 0 {
+		return 0, nil
+	}
+
+	dir := strings.TrimSpace(logDir)
+	if dir == "" {
+		return 0, nil
+	}
+	dir = filepath.Clean(dir)
+
+	entries, errRead := os.ReadDir(dir)
+	if errRead != nil {
+		if os.IsNotExist(errRead) {
+			return 0, nil
+		}
+		return 0, errRead
+	}
+
+	protected := strings.TrimSpace(protectedPath)
+	if protected != "" {
+		protected = filepath.Clean(protected)
+	}
+
+	type logFile struct {
+		path    string
+		size    int64
+		modTime time.Time
+	}
+
+	var (
+		files []logFile
+		total int64
+	)
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		name := entry.Name()
+		if !isLogFileName(name) {
+			continue
+		}
+		info, errInfo := entry.Info()
+		if errInfo != nil {
+			continue
+		}
+		if !info.Mode().IsRegular() {
+			continue
+		}
+		path := filepath.Join(dir, name)
+		files = append(files, logFile{
+			path:    path,
+			size:    info.Size(),
+			modTime: info.ModTime(),
+		})
+		total += info.Size()
+	}
+
+	if total <= maxBytes {
+		return 0, nil
+	}
+
+	sort.Slice(files, func(i, j int) bool {
+		return files[i].modTime.Before(files[j].modTime)
+	})
+
+	deleted := 0
+	for _, file := range files {
+		if total <= maxBytes {
+			break
+		}
+		if protected != "" && filepath.Clean(file.path) == protected {
+			continue
+		}
+		if errRemove := os.Remove(file.path); errRemove != nil {
+			log.WithError(errRemove).Warnf("logging: failed to remove old log file: %s", filepath.Base(file.path))
+			continue
+		}
+		total -= file.size
+		deleted++
+	}
+
+	return deleted, nil
+}
+
+func isLogFileName(name string) bool {
+	trimmed := strings.TrimSpace(name)
+	if trimmed == "" {
+		return false
+	}
+	lower := strings.ToLower(trimmed)
+	return strings.HasSuffix(lower, ".log") || strings.HasSuffix(lower, ".log.gz")
+}

internal/logging/log_dir_cleaner_test.go

@@ -0,0 +1,70 @@
+package logging
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestEnforceLogDirSizeLimitDeletesOldest(t *testing.T) {
+	dir := t.TempDir()
+
+	writeLogFile(t, filepath.Join(dir, "old.log"), 60, time.Unix(1, 0))
+	writeLogFile(t, filepath.Join(dir, "mid.log"), 60, time.Unix(2, 0))
+	protected := filepath.Join(dir, "main.log")
+	writeLogFile(t, protected, 60, time.Unix(3, 0))
+
+	deleted, err := enforceLogDirSizeLimit(dir, 120, protected)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if deleted != 1 {
+		t.Fatalf("expected 1 deleted file, got %d", deleted)
+	}
+
+	if _, err := os.Stat(filepath.Join(dir, "old.log")); !os.IsNotExist(err) {
+		t.Fatalf("expected old.log to be removed, stat error: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "mid.log")); err != nil {
+		t.Fatalf("expected mid.log to remain, stat error: %v", err)
+	}
+	if _, err := os.Stat(protected); err != nil {
+		t.Fatalf("expected protected main.log to remain, stat error: %v", err)
+	}
+}
+
+func TestEnforceLogDirSizeLimitSkipsProtected(t *testing.T) {
+	dir := t.TempDir()
+
+	protected := filepath.Join(dir, "main.log")
+	writeLogFile(t, protected, 200, time.Unix(1, 0))
+	writeLogFile(t, filepath.Join(dir, "other.log"), 50, time.Unix(2, 0))
+
+	deleted, err := enforceLogDirSizeLimit(dir, 100, protected)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if deleted != 1 {
+		t.Fatalf("expected 1 deleted file, got %d", deleted)
+	}
+
+	if _, err := os.Stat(protected); err != nil {
+		t.Fatalf("expected protected main.log to remain, stat error: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "other.log")); !os.IsNotExist(err) {
+		t.Fatalf("expected other.log to be removed, stat error: %v", err)
+	}
+}
+
+func writeLogFile(t *testing.T, path string, size int, modTime time.Time) {
+	t.Helper()
+
+	data := make([]byte, size)
+	if err := os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+	if err := os.Chtimes(path, modTime, modTime); err != nil {
+		t.Fatalf("set times: %v", err)
+	}
+}

internal/translator/antigravity/openai/chat-completions/antigravity_openai_request.go

@@ -39,8 +39,23 @@ func ConvertOpenAIRequestToAntigravity(modelName string, inputRawJSON []byte, _
 	// Note: OpenAI official fields take precedence over extra_body.google.thinking_config
 	re := gjson.GetBytes(rawJSON, "reasoning_effort")
 	hasOfficialThinking := re.Exists()
-	if hasOfficialThinking && util.ModelSupportsThinking(modelName) && !util.ModelUsesThinkingLevels(modelName) {
-		out = util.ApplyReasoningEffortToGeminiCLI(out, re.String())
+	if hasOfficialThinking && util.ModelSupportsThinking(modelName) {
+		effort := strings.ToLower(strings.TrimSpace(re.String()))
+		if util.IsGemini3Model(modelName) {
+			switch effort {
+			case "none":
+				out, _ = sjson.DeleteBytes(out, "request.generationConfig.thinkingConfig")
+			case "auto":
+				includeThoughts := true
+				out = util.ApplyGeminiCLIThinkingLevel(out, "", &includeThoughts)
+			default:
+				if level, ok := util.ValidateGemini3ThinkingLevel(modelName, effort); ok {
+					out = util.ApplyGeminiCLIThinkingLevel(out, level, nil)
+				}
+			}
+		} else if !util.ModelUsesThinkingLevels(modelName) {
+			out = util.ApplyReasoningEffortToGeminiCLI(out, effort)
+		}
 	}
 
 	// Cherry Studio extension extra_body.google.thinking_config (effective only when official fields are absent)

internal/translator/gemini/openai/chat-completions/gemini_openai_request.go

@@ -37,12 +37,28 @@ func ConvertOpenAIRequestToGemini(modelName string, inputRawJSON []byte, _ bool)
 
 	// Reasoning effort -> thinkingBudget/include_thoughts
 	// Note: OpenAI official fields take precedence over extra_body.google.thinking_config
-	// Only convert for models that use numeric budgets (not discrete levels) to avoid
-	// incorrectly applying thinkingBudget for level-based models like gpt-5.
+	// Only apply numeric budgets for models that use budgets (not discrete levels) to avoid
+	// incorrectly applying thinkingBudget for level-based models like gpt-5. Gemini 3 models
+	// use thinkingLevel/includeThoughts instead.
 	re := gjson.GetBytes(rawJSON, "reasoning_effort")
 	hasOfficialThinking := re.Exists()
-	if hasOfficialThinking && util.ModelSupportsThinking(modelName) && !util.ModelUsesThinkingLevels(modelName) {
-		out = util.ApplyReasoningEffortToGemini(out, re.String())
+	if hasOfficialThinking && util.ModelSupportsThinking(modelName) {
+		effort := strings.ToLower(strings.TrimSpace(re.String()))
+		if util.IsGemini3Model(modelName) {
+			switch effort {
+			case "none":
+				out, _ = sjson.DeleteBytes(out, "generationConfig.thinkingConfig")
+			case "auto":
+				includeThoughts := true
+				out = util.ApplyGeminiThinkingLevel(out, "", &includeThoughts)
+			default:
+				if level, ok := util.ValidateGemini3ThinkingLevel(modelName, effort); ok {
+					out = util.ApplyGeminiThinkingLevel(out, level, nil)
+				}
+			}
+		} else if !util.ModelUsesThinkingLevels(modelName) {
+			out = util.ApplyReasoningEffortToGemini(out, effort)
+		}
 	}
 
 	// Cherry Studio extension extra_body.google.thinking_config (effective only when official fields are absent)

sdk/api/options.go

@@ -0,0 +1,46 @@
+// Package api exposes server option helpers for embedding CLIProxyAPI.
+//
+// It wraps internal server option types so external projects can configure the embedded
+// HTTP server without importing internal packages.
+package api
+
+import (
+	"time"
+
+	"github.com/gin-gonic/gin"
+	internalapi "github.com/router-for-me/CLIProxyAPI/v6/internal/api"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/api/handlers"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/logging"
+)
+
+// ServerOption customises HTTP server construction.
+type ServerOption = internalapi.ServerOption
+
+// WithMiddleware appends additional Gin middleware during server construction.
+func WithMiddleware(mw ...gin.HandlerFunc) ServerOption { return internalapi.WithMiddleware(mw...) }
+
+// WithEngineConfigurator allows callers to mutate the Gin engine prior to middleware setup.
+func WithEngineConfigurator(fn func(*gin.Engine)) ServerOption {
+	return internalapi.WithEngineConfigurator(fn)
+}
+
+// WithRouterConfigurator appends a callback after default routes are registered.
+func WithRouterConfigurator(fn func(*gin.Engine, *handlers.BaseAPIHandler, *config.Config)) ServerOption {
+	return internalapi.WithRouterConfigurator(fn)
+}
+
+// WithLocalManagementPassword stores a runtime-only management password accepted for localhost requests.
+func WithLocalManagementPassword(password string) ServerOption {
+	return internalapi.WithLocalManagementPassword(password)
+}
+
+// WithKeepAliveEndpoint enables a keep-alive endpoint with the provided timeout and callback.
+func WithKeepAliveEndpoint(timeout time.Duration, onTimeout func()) ServerOption {
+	return internalapi.WithKeepAliveEndpoint(timeout, onTimeout)
+}
+
+// WithRequestLoggerFactory customises request logger creation.
+func WithRequestLoggerFactory(factory func(*config.Config, string) logging.RequestLogger) ServerOption {
+	return internalapi.WithRequestLoggerFactory(factory)
+}

sdk/auth/filestore.go

@@ -267,7 +267,7 @@ func (s *FileTokenStore) baseDirSnapshot() string {
 }
 
 // DEPRECATED: Use metadataEqualIgnoringTimestamps for comparing auth metadata.
-// This function is kept for backward compatibility but can cause refresh loops. 
+// This function is kept for backward compatibility but can cause refresh loops.
 func jsonEqual(a, b []byte) bool {
 	var objA any
 	var objB any

sdk/cliproxy/builder.go

@@ -7,10 +7,10 @@ import (
 	"fmt"
 
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/api"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
 	sdkAuth "github.com/router-for-me/CLIProxyAPI/v6/sdk/auth"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 )
 
 // Builder constructs a Service instance with customizable providers.

sdk/cliproxy/providers.go

@@ -3,8 +3,8 @@ package cliproxy
 import (
 	"context"
 
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/watcher"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 )
 
 // NewFileTokenClientProvider returns the default token-backed client loader.

sdk/cliproxy/service.go

@@ -13,7 +13,6 @@ import (
 	"time"
 
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/api"
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/registry"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/runtime/executor"
 	_ "github.com/router-for-me/CLIProxyAPI/v6/internal/usage"
@@ -23,6 +22,7 @@ import (
 	sdkAuth "github.com/router-for-me/CLIProxyAPI/v6/sdk/auth"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
 	"github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/usage"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 	log "github.com/sirupsen/logrus"
 )
 

sdk/cliproxy/types.go

@@ -6,9 +6,9 @@ package cliproxy
 import (
 	"context"
 
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/watcher"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 )
 
 // TokenClientProvider loads clients backed by stored authentication tokens.

sdk/cliproxy/watcher.go

@@ -3,9 +3,9 @@ package cliproxy
 import (
 	"context"
 
-	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/watcher"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 )
 
 func defaultWatcherFactory(configPath, authDir string, reload func(*config.Config)) (*WatcherWrapper, error) {

sdk/config/config.go

@@ -1,87 +1,59 @@
-// Package config provides configuration management for the CLI Proxy API server.
-// It handles loading and parsing YAML configuration files, and provides structured
-// access to application settings including server port, authentication directory,
-// debug settings, proxy configuration, and API keys.
+// Package config provides the public SDK configuration API.
+//
+// It re-exports the server configuration types and helpers so external projects can
+// embed CLIProxyAPI without importing internal packages.
 package config
 
-// SDKConfig represents the application's configuration, loaded from a YAML file.
-type SDKConfig struct {
-	// ProxyURL is the URL of an optional proxy server to use for outbound requests.
-	ProxyURL string `yaml:"proxy-url" json:"proxy-url"`
+import internalconfig "github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 
-	// ForceModelPrefix requires explicit model prefixes (e.g., "teamA/gemini-3-pro-preview")
-	// to target prefixed credentials. When false, unprefixed model requests may use prefixed
-	// credentials as well.
-	ForceModelPrefix bool `yaml:"force-model-prefix" json:"force-model-prefix"`
+type SDKConfig = internalconfig.SDKConfig
+type AccessConfig = internalconfig.AccessConfig
+type AccessProvider = internalconfig.AccessProvider
 
-	// RequestLog enables or disables detailed request logging functionality.
-	RequestLog bool `yaml:"request-log" json:"request-log"`
+type Config = internalconfig.Config
 
-	// APIKeys is a list of keys for authenticating clients to this proxy server.
-	APIKeys []string `yaml:"api-keys" json:"api-keys"`
+type TLSConfig = internalconfig.TLSConfig
+type RemoteManagement = internalconfig.RemoteManagement
+type AmpCode = internalconfig.AmpCode
+type PayloadConfig = internalconfig.PayloadConfig
+type PayloadRule = internalconfig.PayloadRule
+type PayloadModelRule = internalconfig.PayloadModelRule
 
-	// Access holds request authentication provider configuration.
-	Access AccessConfig `yaml:"auth,omitempty" json:"auth,omitempty"`
-}
+type GeminiKey = internalconfig.GeminiKey
+type CodexKey = internalconfig.CodexKey
+type ClaudeKey = internalconfig.ClaudeKey
+type VertexCompatKey = internalconfig.VertexCompatKey
+type VertexCompatModel = internalconfig.VertexCompatModel
+type OpenAICompatibility = internalconfig.OpenAICompatibility
+type OpenAICompatibilityAPIKey = internalconfig.OpenAICompatibilityAPIKey
+type OpenAICompatibilityModel = internalconfig.OpenAICompatibilityModel
 
-// AccessConfig groups request authentication providers.
-type AccessConfig struct {
-	// Providers lists configured authentication providers.
-	Providers []AccessProvider `yaml:"providers,omitempty" json:"providers,omitempty"`
-}
-
-// AccessProvider describes a request authentication provider entry.
-type AccessProvider struct {
-	// Name is the instance identifier for the provider.
-	Name string `yaml:"name" json:"name"`
-
-	// Type selects the provider implementation registered via the SDK.
-	Type string `yaml:"type" json:"type"`
-
-	// SDK optionally names a third-party SDK module providing this provider.
-	SDK string `yaml:"sdk,omitempty" json:"sdk,omitempty"`
-
-	// APIKeys lists inline keys for providers that require them.
-	APIKeys []string `yaml:"api-keys,omitempty" json:"api-keys,omitempty"`
-
-	// Config passes provider-specific options to the implementation.
-	Config map[string]any `yaml:"config,omitempty" json:"config,omitempty"`
-}
+type TLS = internalconfig.TLSConfig
 
 const (
-	// AccessProviderTypeConfigAPIKey is the built-in provider validating inline API keys.
-	AccessProviderTypeConfigAPIKey = "config-api-key"
-
-	// DefaultAccessProviderName is applied when no provider name is supplied.
-	DefaultAccessProviderName = "config-inline"
+	AccessProviderTypeConfigAPIKey = internalconfig.AccessProviderTypeConfigAPIKey
+	DefaultAccessProviderName      = internalconfig.DefaultAccessProviderName
+	DefaultPanelGitHubRepository   = internalconfig.DefaultPanelGitHubRepository
 )
 
-// ConfigAPIKeyProvider returns the first inline API key provider if present.
-func (c *SDKConfig) ConfigAPIKeyProvider() *AccessProvider {
-	if c == nil {
-		return nil
-	}
-	for i := range c.Access.Providers {
-		if c.Access.Providers[i].Type == AccessProviderTypeConfigAPIKey {
-			if c.Access.Providers[i].Name == "" {
-				c.Access.Providers[i].Name = DefaultAccessProviderName
-			}
-			return &c.Access.Providers[i]
-		}
-	}
-	return nil
+func MakeInlineAPIKeyProvider(keys []string) *AccessProvider {
+	return internalconfig.MakeInlineAPIKeyProvider(keys)
 }
 
-// MakeInlineAPIKeyProvider constructs an inline API key provider configuration.
-// It returns nil when no keys are supplied.
-func MakeInlineAPIKeyProvider(keys []string) *AccessProvider {
-	if len(keys) == 0 {
-		return nil
-	}
-	provider := &AccessProvider{
-		Name:    DefaultAccessProviderName,
-		Type:    AccessProviderTypeConfigAPIKey,
-		APIKeys: append([]string(nil), keys...),
-	}
-	return provider
+func LoadConfig(configFile string) (*Config, error) { return internalconfig.LoadConfig(configFile) }
+
+func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
+	return internalconfig.LoadConfigOptional(configFile, optional)
+}
+
+func SaveConfigPreserveComments(configFile string, cfg *Config) error {
+	return internalconfig.SaveConfigPreserveComments(configFile, cfg)
+}
+
+func SaveConfigPreserveCommentsUpdateNestedScalar(configFile string, path []string, value string) error {
+	return internalconfig.SaveConfigPreserveCommentsUpdateNestedScalar(configFile, path, value)
+}
+
+func NormalizeCommentIndentation(data []byte) []byte {
+	return internalconfig.NormalizeCommentIndentation(data)
 }

sdk/logging/request_logger.go

@@ -0,0 +1,18 @@
+// Package logging re-exports request logging primitives for SDK consumers.
+package logging
+
+import internallogging "github.com/router-for-me/CLIProxyAPI/v6/internal/logging"
+
+// RequestLogger defines the interface for logging HTTP requests and responses.
+type RequestLogger = internallogging.RequestLogger
+
+// StreamingLogWriter handles real-time logging of streaming response chunks.
+type StreamingLogWriter = internallogging.StreamingLogWriter
+
+// FileRequestLogger implements RequestLogger using file-based storage.
+type FileRequestLogger = internallogging.FileRequestLogger
+
+// NewFileRequestLogger creates a new file-based request logger.
+func NewFileRequestLogger(enabled bool, logsDir string, configDir string) *FileRequestLogger {
+	return internallogging.NewFileRequestLogger(enabled, logsDir, configDir)
+}