feat: add mock_models config and improve remove_version_path with regex

- Add mock_models and mock_models_resp config options for mocking /models endpoint
- Improve remove_version_path to use regex for flexible version matching
- Regex pattern matches v1, v2, v3, v1beta, v1alpha, v2beta, v2alpha, etc.
- Add tests for isModelsRequest and mock models response
- Update README with new config options

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: systemime

Makefile

@@ -3,7 +3,7 @@
 # Variables
 APP_NAME := mask-ctl
 SERVICE_BINARY := coding-plan-mask
-VERSION := 0.8.1
+VERSION := 0.8.2
 BUILD_DIR := build
 BIN_DIR := $(BUILD_DIR)/bin
 CMD_DIR := cmd/coding-plan-mask

README.md

@@ -147,6 +147,12 @@ claude_code_user_agent = "claude-cli/2.1.76 (external, cli)"
 # Optional: Remove version prefix (e.g., /v1) from request path when forwarding
 # Example: Request to /v1/models will be forwarded as /models only
 remove_version_path = false
+# Mock /models endpoint response (default: false)
+# When enabled, returns mock data instead of forwarding to upstream
+# Matches: /models, /v1/models, /v2/models, /v3/models
+mock_models = false
+# Mock /models response content (JSON string)
+mock_models_resp = '{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}'
 ```
 
 #### 4. Start
@@ -262,6 +268,8 @@ You can also configure via environment variables:
 | `OPENCLAW_USER_AGENT` | Override the compatibility UA used by `openclaw` mode |
 | `CUSTOM_USER_AGENT` | Override User-Agent directly |
 | `REMOVE_VERSION_PATH` | Remove version prefix (e.g., `/v1`) from request path when forwarding (true/false) |
+| `MOCK_MODELS` | Enable mock /models endpoint response (true/false) |
+| `MOCK_MODELS_RESP` | Mock /models response content (JSON string) |
 
 ### ⚠️ Risk Warning
 
@@ -399,6 +407,12 @@ openclaw_user_agent = "OpenClaw-Gateway/1.0"
 # 可选：转发时移除请求路径中的版本前缀（如 /v1）
 # 例如：请求 /v1/models 时，转发时只拼接 /models 部分
 remove_version_path = false
+# 模拟 /models 端点响应 (默认: false)
+# 启用后返回模拟数据，不转发到上游
+# 匹配路径: /models, /v1/models, /v2/models, /v3/models
+mock_models = false
+# 模拟 /models 响应内容 (JSON 字符串)
+mock_models_resp = '{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}'
 ```
 
 #### 4. 启动
@@ -496,6 +510,8 @@ curl http://127.0.0.1:8787/stats
 | `OPENCLAW_USER_AGENT` | 覆盖 `openclaw` 模式兼容默认 User-Agent |
 | `CUSTOM_USER_AGENT` | 直接覆盖 User-Agent |
 | `REMOVE_VERSION_PATH` | 转发时移除请求路径中的版本前缀（如 `/v1`）(true/false) |
+| `MOCK_MODELS` | 启用模拟 /models 端点响应 (true/false) |
+| `MOCK_MODELS_RESP` | 模拟 /models 响应内容 (JSON 字符串) |
 
 ### ⚠️ 风险预警
 

internal/config/config.go

@@ -73,6 +73,10 @@ type APIConfig struct {
 	// 删除代理伪装请求的版本控制路径
 	// 例如：请求 /v1/models 时，转发时只拼接 /models 部分
 	RemoveVersionPath bool `toml:"remove_version_path"`
+	// 模拟 /models 响应
+	MockModels bool `toml:"mock_models"`
+	// 模拟 /models 响应内容 (JSON 字符串)
+	MockModelsResp string `toml:"mock_models_resp"`
 }
 
 // Config 应用配置（运行时使用）
@@ -101,6 +105,8 @@ type Config struct {
 	CustomAuthHeader  string
 	CustomAuthPrefix  string
 	RemoveVersionPath bool
+	MockModels        bool
+	MockModelsResp    string
 
 	configPath string
 }
@@ -119,6 +125,9 @@ const (
 	ClaudeCodeAppHeaderValue   = "cli"
 )
 
+// DefaultMockModelsResp 默认的 /models 模拟响应
+const DefaultMockModelsResp = `{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}`
+
 // PredefinedDisguiseTools 预定义的伪装工具
 // User-Agent 来源说明:
 // - claudecode: 当前 Claude Code CLI 请求格式，默认值可通过配置覆盖
@@ -174,6 +183,7 @@ func DefaultConfig() *Config {
 		RateLimitRequests:  100,
 		Timeout:            120,
 		MaxRequestBodySize: 10 * 1024 * 1024,
+		MockModelsResp:     DefaultMockModelsResp,
 	}
 }
 
@@ -294,6 +304,10 @@ func LoadConfig(path string) (*Config, error) {
 	cfg.CustomAuthHeader = cfgFile.API.AuthHeader
 	cfg.CustomAuthPrefix = cfgFile.API.AuthPrefix
 	cfg.RemoveVersionPath = cfgFile.API.RemoveVersionPath
+	cfg.MockModels = cfgFile.API.MockModels
+	if cfgFile.API.MockModelsResp != "" {
+		cfg.MockModelsResp = cfgFile.API.MockModelsResp
+	}
 
 	cfg.loadFromEnv()
 	return cfg, nil
@@ -342,6 +356,12 @@ func (c *Config) loadFromEnv() {
 	if v := os.Getenv("REMOVE_VERSION_PATH"); strings.ToLower(v) == "true" {
 		c.RemoveVersionPath = true
 	}
+	if v := os.Getenv("MOCK_MODELS"); strings.ToLower(v) == "true" {
+		c.MockModels = true
+	}
+	if v := os.Getenv("MOCK_MODELS_RESP"); v != "" {
+		c.MockModelsResp = v
+	}
 }
 
 // Set 设置配置项
@@ -388,6 +408,10 @@ func (c *Config) Set(key string, value string) error {
 		c.CustomAuthPrefix = value
 	case "remove_version_path":
 		c.RemoveVersionPath = strings.ToLower(value) == "true"
+	case "mock_models":
+		c.MockModels = strings.ToLower(value) == "true"
+	case "mock_models_resp":
+		c.MockModelsResp = value
 	default:
 		return fmt.Errorf("未知配置项: %s", key)
 	}
@@ -504,6 +528,8 @@ func (c *Config) GetSafe() map[string]interface{} {
 		"api_base_url":           c.CustomBaseURL,
 		"api_coding_url":         c.CustomCodingURL,
 		"remove_version_path":    c.RemoveVersionPath,
+		"mock_models":            c.MockModels,
+		"mock_models_resp":       c.MockModelsResp,
 	}
 }
 
@@ -608,6 +634,11 @@ auth_prefix = ""
 # 删除代理伪装请求的版本控制路径 (默认 false)
 # 例如：请求 /v1/models 时，转发时只拼接 /models 部分
 remove_version_path = false
+# 模拟 /models 响应 (默认 false)
+# 启用后，对 /models 或 /v1/models (取决于 remove_version_path) 返回模拟数据
+mock_models = false
+# 模拟 /models 响应内容 (JSON 字符串)
+mock_models_resp = '{"object":"list","data":[{"id":"gpt-4","object":"model","owned_by":"organization"}]}'
 `
 
 	return os.WriteFile(path, []byte(defaultContent), 0644)

internal/proxy/proxy.go

@@ -10,6 +10,7 @@ import (
 	"net/http"
 	"net/textproto"
 	"os"
+	"regexp"
 	"strings"
 	"time"
 	"unicode/utf8"
@@ -79,6 +80,12 @@ func (p *Proxy) Forward(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// 检查是否需要模拟 /models 响应
+	if p.cfg.MockModels && p.isModelsRequest(r.URL.Path) {
+		p.handleMockModels(w, r, startTime, clientIP)
+		return
+	}
+
 	// 读取请求体
 	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, p.cfg.MaxRequestBodySize))
 	if err != nil {
@@ -160,6 +167,46 @@ func (p *Proxy) Embeddings(w http.ResponseWriter, r *http.Request) {
 	p.Forward(w, r)
 }
 
+// isModelsRequest 检查是否是 /models 请求
+// 匹配规则:
+// - 始终匹配 /models
+// - 始终匹配 /v1/models, /v2/models, /v3/models (版本前缀格式)
+func (p *Proxy) isModelsRequest(path string) bool {
+	path = strings.TrimSuffix(path, "/")
+
+	// 匹配 /models
+	if path == "/models" {
+		return true
+	}
+
+	// 匹配 /v1/models, /v2/models, /v3/models 等
+	if strings.HasSuffix(path, "/models") {
+		prefix := strings.TrimSuffix(path, "/models")
+		return prefix == "/v1" || prefix == "/v2" || prefix == "/v3"
+	}
+
+	return false
+}
+
+// handleMockModels 处理模拟 /models 响应
+func (p *Proxy) handleMockModels(w http.ResponseWriter, r *http.Request, startTime time.Time, clientIP string) {
+	duration := time.Since(startTime).Milliseconds()
+
+	// 验证本地 API Key
+	if !p.validateLocalAPIKey(r) {
+		p.writeError(w, http.StatusUnauthorized, "API Key 无效")
+		return
+	}
+
+	// 返回模拟响应
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte(p.cfg.MockModelsResp))
+
+	// 打印日志
+	p.logResponse(r.Method, r.URL.Path, "mock://models", http.StatusOK, duration, clientIP, p.cfg.MockModelsResp)
+}
+
 // validateLocalAPIKey 验证本地 API Key
 func (p *Proxy) validateLocalAPIKey(r *http.Request) bool {
 	localAPIKey := p.cfg.LocalAPIKey
@@ -437,27 +484,20 @@ func buildTargetURL(baseURL string, r *http.Request, removeVersionPath bool) str
 	return targetURL
 }
 
+// versionPrefixRegex 匹配版本前缀的正则表达式
+// 匹配: /v1, /v2, /v1beta, /v2alpha, /v3rc 等（可选带尾部斜杠）
+var versionPrefixRegex = regexp.MustCompile(`^/?v\d+[a-z]*(?:/|$)`)
+
 // removeVersionPrefix 移除路径中的版本前缀（如 /v1, /v2 等）
 func removeVersionPrefix(path string) string {
-	// 匹配 /v1, /v2, /v1beta, /v2alpha 等版本前缀
-	// 正则匹配：/v 后面跟数字，可选跟 alpha/beta/rc 等
-	path = strings.TrimLeft(path, "/")
-
-	// 常见版本前缀模式
-	versionPatterns := []string{"v1/", "v2/", "v3/", "v1beta/", "v1alpha/", "v2beta/", "v2alpha/"}
-
-	for _, pattern := range versionPatterns {
-		if strings.HasPrefix(path, pattern) {
-			return strings.TrimPrefix(path, pattern)
-		}
-	}
-
-	// 如果是单纯的版本路径如 /v1 或 /v2（没有后续路径），返回空
-	if path == "v1" || path == "v2" || path == "v3" {
-		return ""
-	}
-
-	return path
+	// 使用正则匹配：/v 后面跟数字，可选跟 alpha/beta/rc 等后缀
+	// 如果匹配到，移除版本前缀部分
+	if versionPrefixRegex.MatchString(path) {
+		// 移除开头的 / 和版本号部分
+		path = versionPrefixRegex.ReplaceAllString(path, "")
+		return strings.Trim(path, "/")
+	}
+	return strings.Trim(path, "/")
 }
 
 func isHopByHopHeader(key string) bool {