codexmate 0.0.12 → 0.0.13

package/{src/cli.js → cli.js}

@@ -6,9 +6,10 @@ const crypto = require('crypto');
 const toml = require('@iarna/toml');
 const JSON5 = require('json5');
 const zipLib = require('zip-lib');
-const { exec, execSync, spawn } = require('child_process');
+const { exec, execSync, spawn, spawnSync } = require('child_process');
 const http = require('http');
 const https = require('https');
+const net = require('net');
 const readline = require('readline');
 const {
     expandHomePath,
@@ -52,6 +53,7 @@ const {
     parseMaxMessagesValue,
     resolveMaxMessagesValue
 } = require('./lib/cli-session-utils');
+const { createMcpStdioServer } = require('./lib/mcp-stdio');
 
 const DEFAULT_WEB_PORT = 3737;
 const DEFAULT_WEB_HOST = '127.0.0.1';
@@ -62,9 +64,12 @@ const DEFAULT_WEB_HOST = '127.0.0.1';
 const CONFIG_DIR = path.join(os.homedir(), '.codex');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.toml');
 const AUTH_FILE = path.join(CONFIG_DIR, 'auth.json');
+const AUTH_PROFILES_DIR = path.join(CONFIG_DIR, 'auth-profiles');
+const AUTH_REGISTRY_FILE = path.join(AUTH_PROFILES_DIR, 'registry.json');
 const MODELS_FILE = path.join(CONFIG_DIR, 'models.json');
 const CURRENT_MODELS_FILE = path.join(CONFIG_DIR, 'provider-current-models.json');
 const INIT_MARK_FILE = path.join(CONFIG_DIR, 'codexmate-init.json');
+const BUILTIN_PROXY_SETTINGS_FILE = path.join(CONFIG_DIR, 'codexmate-proxy.json');
 const CODEX_SESSIONS_DIR = path.join(CONFIG_DIR, 'sessions');
 const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw');
 const OPENCLAW_CONFIG_FILE = path.join(OPENCLAW_DIR, 'openclaw.json');
@@ -74,6 +79,7 @@ const CLAUDE_SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 const RECENT_CONFIGS_FILE = path.join(CONFIG_DIR, 'recent-configs.json');
 const DEFAULT_CLAUDE_MODEL = 'glm-4.7';
+const CODEX_BACKUP_NAME = 'codex-config';
 
 const DEFAULT_MODELS = ['gpt-5.3-codex', 'gpt-5.1-codex-max', 'gpt-4-turbo', 'gpt-4'];
 const SPEED_TEST_TIMEOUT_MS = 8000;
@@ -97,6 +103,16 @@ const MODELS_NEGATIVE_CACHE_TTL_MS = 5 * 1000;
 const MODELS_CACHE_MAX_ENTRIES = 50;
 const MODELS_RESPONSE_MAX_BYTES = 1024 * 1024;
 const MAX_RECENT_CONFIGS = 3;
+const MAX_UPLOAD_SIZE = 200 * 1024 * 1024;
+const BUILTIN_PROXY_PROVIDER_NAME = 'codexmate-proxy';
+const DEFAULT_BUILTIN_PROXY_SETTINGS = Object.freeze({
+    enabled: false,
+    host: '127.0.0.1',
+    port: 8318,
+    provider: '',
+    authSource: 'provider',
+    timeoutMs: 30000
+});
 const BOOTSTRAP_TEXT_MARKERS = [
     'agents.md instructions',
     '<instructions>',
@@ -104,6 +120,20 @@ const BOOTSTRAP_TEXT_MARKERS = [
     'you are a coding agent',
     'codex cli'
 ];
+const CLI_INSTALL_TARGETS = Object.freeze([
+    {
+        id: 'claude',
+        name: 'Claude Code CLI',
+        packageName: '@anthropic-ai/claude-code',
+        bins: ['claude']
+    },
+    {
+        id: 'codex',
+        name: 'Codex CLI',
+        packageName: '@openai/codex',
+        bins: ['codex']
+    }
+]);
 
 const HTTP_KEEP_ALIVE_AGENT = new http.Agent({ keepAlive: true });
 const HTTPS_KEEP_ALIVE_AGENT = new https.Agent({ keepAlive: true });
@@ -152,6 +182,29 @@ let g_initNotice = '';
 let g_sessionListCache = new Map();
 let g_modelsCache = new Map();
 let g_modelsInFlight = new Map();
+let g_builtinProxyRuntime = null;
+const DEFAULT_LOCAL_PROVIDER_NAME = 'local';
+
+function isBuiltinProxyProvider(providerName) {
+    return typeof providerName === 'string' && providerName.trim() === BUILTIN_PROXY_PROVIDER_NAME;
+}
+
+function isReservedProviderNameForCreation(providerName) {
+    return typeof providerName === 'string'
+        && providerName.trim().toLowerCase() === DEFAULT_LOCAL_PROVIDER_NAME;
+}
+
+function isDefaultLocalProvider(providerName) {
+    return typeof providerName === 'string' && providerName.trim() === DEFAULT_LOCAL_PROVIDER_NAME;
+}
+
+function isNonDeletableProvider(providerName) {
+    return isBuiltinProxyProvider(providerName) || isDefaultLocalProvider(providerName);
+}
+
+function isNonEditableProvider(providerName) {
+    return isBuiltinProxyProvider(providerName) || isDefaultLocalProvider(providerName);
+}
 
 // ============================================================================
 // 工具函数
@@ -220,6 +273,310 @@ function updateAuthJson(apiKey) {
     fs.writeFileSync(AUTH_FILE, JSON.stringify(authData, null, 2), 'utf-8');
 }
 
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeAuthProfileName(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (!raw) return '';
+    const sanitized = raw
+        .replace(/[\\\/:*?"<>|]/g, '-')
+        .replace(/\s+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 120);
+    return sanitized;
+}
+
+function normalizeAuthRegistry(raw) {
+    const fallback = { version: 1, current: '', items: [] };
+    if (!isPlainObject(raw)) return fallback;
+    const items = Array.isArray(raw.items)
+        ? raw.items.filter(item => isPlainObject(item) && typeof item.name === 'string' && item.name.trim())
+        : [];
+    return {
+        version: 1,
+        current: typeof raw.current === 'string' ? raw.current.trim() : '',
+        items: items.map((item) => ({
+            name: normalizeAuthProfileName(item.name) || item.name.trim(),
+            fileName: typeof item.fileName === 'string' ? path.basename(item.fileName) : '',
+            type: typeof item.type === 'string' ? item.type : '',
+            email: typeof item.email === 'string' ? item.email : '',
+            accountId: typeof item.accountId === 'string' ? item.accountId : '',
+            expired: typeof item.expired === 'string' ? item.expired : '',
+            lastRefresh: typeof item.lastRefresh === 'string' ? item.lastRefresh : '',
+            updatedAt: typeof item.updatedAt === 'string' ? item.updatedAt : '',
+            importedAt: typeof item.importedAt === 'string' ? item.importedAt : '',
+            sourceFile: typeof item.sourceFile === 'string' ? item.sourceFile : ''
+        }))
+    };
+}
+
+function readAuthRegistry() {
+    const parsed = readJsonFile(AUTH_REGISTRY_FILE, null);
+    return normalizeAuthRegistry(parsed);
+}
+
+function writeAuthRegistry(registry) {
+    writeJsonAtomic(AUTH_REGISTRY_FILE, normalizeAuthRegistry(registry));
+}
+
+function parseAuthProfileJson(rawContent, label = '') {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripUtf8Bom(String(rawContent || '')));
+    } catch (e) {
+        throw new Error(`认证文件不是有效 JSON${label ? `: ${label}` : ''}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error('认证文件根节点必须是对象');
+    }
+    const hasCredential = ['access_token', 'refresh_token', 'id_token', 'OPENAI_API_KEY']
+        .some((key) => typeof parsed[key] === 'string' && parsed[key].trim());
+    if (!hasCredential) {
+        throw new Error('认证文件缺少可用凭据（access_token / refresh_token / id_token / OPENAI_API_KEY）');
+    }
+    return parsed;
+}
+
+function buildAuthProfileSummary(name, payload, fileName = '') {
+    const safePayload = isPlainObject(payload) ? payload : {};
+    return {
+        name,
+        fileName: fileName || `${name}.json`,
+        type: typeof safePayload.type === 'string' ? safePayload.type : '',
+        email: typeof safePayload.email === 'string' ? safePayload.email : '',
+        accountId: typeof safePayload.account_id === 'string'
+            ? safePayload.account_id
+            : (typeof safePayload.accountId === 'string' ? safePayload.accountId : ''),
+        expired: typeof safePayload.expired === 'string' ? safePayload.expired : '',
+        lastRefresh: typeof safePayload.last_refresh === 'string'
+            ? safePayload.last_refresh
+            : (typeof safePayload.lastRefresh === 'string' ? safePayload.lastRefresh : ''),
+        updatedAt: toIsoTime(Date.now())
+    };
+}
+
+function getAuthProfileNameFallback(payload, fallbackName = '') {
+    const fromPayload = isPlainObject(payload)
+        ? (payload.email || payload.account_id || payload.accountId || '')
+        : '';
+    const fromFallback = typeof fallbackName === 'string' ? fallbackName : '';
+    const resolved = normalizeAuthProfileName(fromPayload) || normalizeAuthProfileName(fromFallback);
+    if (resolved) return resolved;
+    return `auth-${Date.now()}`;
+}
+
+function listAuthProfilesInfo() {
+    const registry = readAuthRegistry();
+    return registry.items.map((item) => ({
+        ...item,
+        current: item.name === registry.current
+    }));
+}
+
+function upsertAuthProfile(payload, options = {}) {
+    const safePayload = parseAuthProfileJson(JSON.stringify(payload || {}));
+    const sourceFile = typeof options.sourceFile === 'string' ? options.sourceFile : '';
+    const preferredName = normalizeAuthProfileName(options.name || '');
+    const profileName = preferredName || getAuthProfileNameFallback(safePayload, sourceFile);
+    const fileName = `${profileName}.json`;
+    const profilePath = path.join(AUTH_PROFILES_DIR, fileName);
+
+    ensureDir(AUTH_PROFILES_DIR);
+    writeJsonAtomic(profilePath, safePayload);
+
+    const registry = readAuthRegistry();
+    const meta = buildAuthProfileSummary(profileName, safePayload, fileName);
+    meta.importedAt = toIsoTime(Date.now());
+    meta.sourceFile = sourceFile || '';
+
+    const idx = registry.items.findIndex((item) => item.name === profileName);
+    if (idx >= 0) {
+        registry.items[idx] = {
+            ...registry.items[idx],
+            ...meta
+        };
+    } else {
+        registry.items.push(meta);
+    }
+    registry.items.sort((a, b) => a.name.localeCompare(b.name));
+
+    const shouldActivate = options.activate !== false;
+    if (shouldActivate) {
+        writeJsonAtomic(AUTH_FILE, safePayload);
+        registry.current = profileName;
+    }
+    writeAuthRegistry(registry);
+
+    return {
+        success: true,
+        profile: {
+            ...meta,
+            current: shouldActivate ? true : registry.current === profileName
+        }
+    };
+}
+
+function importAuthProfileFromFile(filePath, options = {}) {
+    const absPath = path.resolve(String(filePath || ''));
+    if (!absPath || !fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+        throw new Error('认证文件不存在');
+    }
+    const raw = fs.readFileSync(absPath, 'utf-8');
+    const payload = parseAuthProfileJson(raw, path.basename(absPath));
+    const fallbackName = path.basename(absPath, path.extname(absPath));
+    return upsertAuthProfile(payload, {
+        ...options,
+        sourceFile: absPath,
+        name: options.name || fallbackName
+    });
+}
+
+function importAuthProfileFromUpload(payload = {}) {
+    const fileBase64 = typeof payload.fileBase64 === 'string' ? payload.fileBase64.trim() : '';
+    if (!fileBase64) {
+        return { error: '缺少认证文件内容' };
+    }
+    let buffer;
+    try {
+        buffer = Buffer.from(fileBase64, 'base64');
+    } catch (e) {
+        return { error: '认证文件不是有效的 base64 编码' };
+    }
+    if (!buffer || buffer.length === 0) {
+        return { error: '认证文件为空' };
+    }
+    if (buffer.length > 10 * 1024 * 1024) {
+        return { error: '认证文件过大（>10MB）' };
+    }
+
+    try {
+        const raw = buffer.toString('utf-8');
+        const profileData = parseAuthProfileJson(raw, payload.fileName || 'upload.json');
+        return upsertAuthProfile(profileData, {
+            name: payload.name || path.basename(payload.fileName || '', path.extname(payload.fileName || '')),
+            sourceFile: payload.fileName || '',
+            activate: payload.activate !== false
+        });
+    } catch (e) {
+        return { error: e.message || '导入认证文件失败' };
+    }
+}
+
+function switchAuthProfile(name, options = {}) {
+    const profileName = normalizeAuthProfileName(name);
+    if (!profileName) {
+        throw new Error('认证名称不能为空');
+    }
+    const registry = readAuthRegistry();
+    const profile = registry.items.find((item) => item.name === profileName);
+    if (!profile) {
+        throw new Error(`认证不存在: ${profileName}`);
+    }
+    const fileName = profile.fileName || `${profileName}.json`;
+    const profilePath = path.join(AUTH_PROFILES_DIR, fileName);
+    if (!fs.existsSync(profilePath)) {
+        throw new Error(`认证文件不存在: ${fileName}`);
+    }
+    const raw = fs.readFileSync(profilePath, 'utf-8');
+    const profileData = parseAuthProfileJson(raw, fileName);
+    writeJsonAtomic(AUTH_FILE, profileData);
+
+    registry.current = profileName;
+    const idx = registry.items.findIndex((item) => item.name === profileName);
+    if (idx >= 0) {
+        registry.items[idx] = {
+            ...registry.items[idx],
+            updatedAt: toIsoTime(Date.now())
+        };
+    }
+    writeAuthRegistry(registry);
+
+    if (!options.silent) {
+        console.log(`✓ 已切换认证: ${profileName}`);
+        if (profile.email) {
+            console.log(`  账号: ${profile.email}`);
+        }
+        console.log();
+    }
+    return {
+        success: true,
+        profile: {
+            ...profile,
+            current: true
+        }
+    };
+}
+
+function deleteAuthProfile(name) {
+    const profileName = normalizeAuthProfileName(name);
+    if (!profileName) {
+        return { error: '认证名称不能为空' };
+    }
+    const registry = readAuthRegistry();
+    const idx = registry.items.findIndex((item) => item.name === profileName);
+    if (idx < 0) {
+        return { error: '认证不存在' };
+    }
+    const profile = registry.items[idx];
+    const fileName = profile.fileName || `${profileName}.json`;
+    const profilePath = path.join(AUTH_PROFILES_DIR, fileName);
+
+    if (fs.existsSync(profilePath)) {
+        try {
+            fs.unlinkSync(profilePath);
+        } catch (e) {
+            return { error: `删除认证文件失败: ${e.message}` };
+        }
+    }
+
+    registry.items.splice(idx, 1);
+    let switchedTo = '';
+    if (registry.current === profileName) {
+        if (registry.items.length > 0) {
+            const next = registry.items[0];
+            try {
+                const nextPath = path.join(AUTH_PROFILES_DIR, next.fileName || `${next.name}.json`);
+                const raw = fs.readFileSync(nextPath, 'utf-8');
+                const nextData = parseAuthProfileJson(raw, next.fileName || `${next.name}.json`);
+                writeJsonAtomic(AUTH_FILE, nextData);
+                registry.current = next.name;
+                switchedTo = next.name;
+            } catch (e) {
+                registry.current = '';
+            }
+        } else {
+            registry.current = '';
+        }
+    }
+    writeAuthRegistry(registry);
+    return {
+        success: true,
+        switchedTo
+    };
+}
+
+function resolveAuthTokenFromCurrentProfile() {
+    const registry = readAuthRegistry();
+    if (!registry.current) return '';
+    const profile = registry.items.find((item) => item.name === registry.current);
+    if (!profile) return '';
+    const filePath = path.join(AUTH_PROFILES_DIR, profile.fileName || `${profile.name}.json`);
+    if (!fs.existsSync(filePath)) return '';
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const payload = parseAuthProfileJson(raw, profile.fileName || `${profile.name}.json`);
+        if (typeof payload.access_token === 'string' && payload.access_token.trim()) {
+            return payload.access_token.trim();
+        }
+        if (typeof payload.OPENAI_API_KEY === 'string' && payload.OPENAI_API_KEY.trim()) {
+            return payload.OPENAI_API_KEY.trim();
+        }
+    } catch (e) {}
+    return '';
+}
+
 function getCodexSessionsDir() {
     const candidates = [];
     const envCodexHome = process.env.CODEX_HOME;
@@ -1295,9 +1652,16 @@ function addProviderToConfig(params = {}) {
     const name = typeof params.name === 'string' ? params.name.trim() : '';
     const url = typeof params.url === 'string' ? params.url.trim() : '';
     const key = typeof params.key === 'string' ? params.key.trim() : '';
+    const allowManaged = !!params.allowManaged;
 
     if (!name) return { error: '名称不能为空' };
     if (!url) return { error: 'URL 不能为空' };
+    if (isReservedProviderNameForCreation(name)) {
+        return { error: 'local provider 为系统保留名称，不可新增' };
+    }
+    if (isBuiltinProxyProvider(name) && !allowManaged) {
+        return { error: '本地代理配置为系统内建项，不可手动添加' };
+    }
 
     ensureConfigDir();
 
@@ -1368,14 +1732,21 @@ function updateProviderInConfig(params = {}) {
     const key = params.key !== undefined && params.key !== null
         ? String(params.key).trim()
         : undefined;
+    const allowManaged = !!params.allowManaged;
 
     if (!name) return { error: '名称不能为空' };
     if (!url && key === undefined) {
         return { error: 'URL 或密钥至少填写一项' };
     }
+    if (isNonEditableProvider(name) && !allowManaged) {
+        if (isDefaultLocalProvider(name)) {
+            return { error: 'local provider 为系统保留项，不可编辑' };
+        }
+        return { error: '本地代理配置为系统内建项，不可编辑' };
+    }
 
     try {
-        cmdUpdate(name, url || undefined, key, true);
+        cmdUpdate(name, url || undefined, key, true, { allowManaged });
         return { success: true };
     } catch (e) {
         return { error: e.message || '更新失败' };
@@ -1385,6 +1756,12 @@ function updateProviderInConfig(params = {}) {
 function deleteProviderFromConfig(params = {}) {
     const name = typeof params.name === 'string' ? params.name.trim() : '';
     if (!name) return { error: '名称不能为空' };
+    if (isNonDeletableProvider(name)) {
+        if (isDefaultLocalProvider(name)) {
+            return { error: 'local provider 为系统保留项，不可删除' };
+        }
+        return { error: '本地代理配置为系统内建项，不可删除' };
+    }
     if (!fs.existsSync(CONFIG_FILE)) {
         return { error: 'config.toml 不存在' };
     }
@@ -1410,6 +1787,13 @@ function deleteProviderFromConfig(params = {}) {
 
 function performProviderDeletion(name, options = {}) {
     const silent = !!options.silent;
+    if (isNonDeletableProvider(name)) {
+        const msg = isDefaultLocalProvider(name)
+            ? 'local provider 为系统保留项，不可删除'
+            : '本地代理配置为系统内建项，不可删除';
+        if (!silent) console.error('错误:', msg);
+        return { error: msg };
+    }
     const config = options.config || readConfig();
     if (!config.model_providers || !config.model_providers[name]) {
         const msg = '提供商不存在';
@@ -2789,143 +3173,661 @@ function findClaudeSessionIndexPath(sessionFilePath) {
     return '';
 }
 
-function updateClaudeSessionIndex(indexPath, sessionFilePath, sessionId) {
-    if (!indexPath || !fs.existsSync(indexPath)) {
-        return;
-    }
-    const index = readJsonFile(indexPath, null);
-    if (!index || !Array.isArray(index.entries)) {
-        return;
+function canListenPort(host, port) {
+    return new Promise((resolve) => {
+        const tester = net.createServer();
+        tester.unref();
+        tester.once('error', () => {
+            resolve(false);
+        });
+        tester.once('listening', () => {
+            tester.close(() => resolve(true));
+        });
+        tester.listen(port, host);
+    });
+}
+
+async function findAvailablePort(host, startPort, maxAttempts = 20) {
+    const start = parseInt(String(startPort), 10);
+    if (!Number.isFinite(start) || start <= 0) {
+        return 0;
     }
-    const resolvedFile = sessionFilePath ? path.resolve(sessionFilePath) : '';
-    const resolvedLower = resolvedFile ? resolvedFile.toLowerCase() : '';
-    const filtered = index.entries.filter((entry) => {
-        if (!entry || typeof entry !== 'object') {
-            return false;
-        }
-        const entrySessionId = typeof entry.sessionId === 'string' ? entry.sessionId : '';
-        if (sessionId && entrySessionId === sessionId) {
-            return false;
+    const attempts = Number.isFinite(maxAttempts) && maxAttempts > 0 ? maxAttempts : 20;
+    for (let offset = 0; offset < attempts; offset += 1) {
+        const candidate = start + offset;
+        if (candidate > 65535) {
+            break;
         }
-        if (entry.fullPath) {
-            const expanded = expandHomePath(entry.fullPath);
-            const entryPath = expanded ? path.resolve(expanded) : '';
-            if (entryPath && resolvedLower && entryPath.toLowerCase() === resolvedLower) {
-                return false;
-            }
+        // eslint-disable-next-line no-await-in-loop
+        const ok = await canListenPort(host, candidate);
+        if (ok) {
+            return candidate;
         }
-        return true;
-    });
-    if (filtered.length === index.entries.length) {
-        return;
     }
-    index.entries = filtered;
-    try {
-        fs.writeFileSync(indexPath, JSON.stringify(index, null, 2), 'utf-8');
-    } catch (e) {}
+    return 0;
 }
 
-async function deleteSessionData(params = {}) {
-    const source = params.source === 'claude' ? 'claude' : (params.source === 'codex' ? 'codex' : '');
-    if (!source) {
-        return { error: 'Invalid source' };
-    }
+function normalizeBuiltinProxySettings(raw) {
+    const merged = {
+        ...DEFAULT_BUILTIN_PROXY_SETTINGS,
+        ...(isPlainObject(raw) ? raw : {})
+    };
+    const host = typeof merged.host === 'string' ? merged.host.trim() : '';
+    const port = parseInt(String(merged.port), 10);
+    const provider = typeof merged.provider === 'string' ? merged.provider.trim() : '';
+    const authSourceRaw = typeof merged.authSource === 'string' ? merged.authSource.trim().toLowerCase() : '';
+    const timeoutMs = parseInt(String(merged.timeoutMs), 10);
+    const authSource = authSourceRaw === 'profile' || authSourceRaw === 'none' ? authSourceRaw : 'provider';
 
-    const filePath = resolveSessionFilePath(source, params.filePath, params.sessionId);
-    if (!filePath) {
-        return { error: 'Session file not found' };
-    }
+    return {
+        enabled: merged.enabled !== false,
+        host: host || DEFAULT_BUILTIN_PROXY_SETTINGS.host,
+        port: Number.isFinite(port) && port > 0 && port <= 65535 ? port : DEFAULT_BUILTIN_PROXY_SETTINGS.port,
+        provider,
+        authSource,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs >= 1000 ? timeoutMs : DEFAULT_BUILTIN_PROXY_SETTINGS.timeoutMs
+    };
+}
 
-    const sessionId = params.sessionId || path.basename(filePath, '.jsonl');
-    try {
-        fs.unlinkSync(filePath);
-    } catch (e) {
-        return { error: `删除会话失败: ${e.message}` };
+function readBuiltinProxySettings() {
+    const parsed = readJsonFile(BUILTIN_PROXY_SETTINGS_FILE, null);
+    return normalizeBuiltinProxySettings(parsed);
+}
+
+function resolveBuiltinProxyProviderName(rawProviderName, providers = {}, preferredProvider = '') {
+    const providerMap = providers && isPlainObject(providers) ? providers : {};
+    const providerNames = Object.keys(providerMap)
+        .filter((name) => name && name !== BUILTIN_PROXY_PROVIDER_NAME);
+    const requested = typeof rawProviderName === 'string' ? rawProviderName.trim() : '';
+    if (requested && requested !== BUILTIN_PROXY_PROVIDER_NAME && providerMap[requested]) {
+        return requested;
     }
+    const preferred = typeof preferredProvider === 'string' ? preferredProvider.trim() : '';
+    if (preferred && preferred !== BUILTIN_PROXY_PROVIDER_NAME && providerMap[preferred]) {
+        return preferred;
+    }
+    return providerNames[0] || '';
+}
 
-    if (source === 'claude') {
-        const indexPath = findClaudeSessionIndexPath(filePath);
-        if (indexPath) {
-            updateClaudeSessionIndex(indexPath, filePath, sessionId);
-        }
+function saveBuiltinProxySettings(payload = {}, options = {}) {
+    const current = readBuiltinProxySettings();
+    const merged = normalizeBuiltinProxySettings({
+        ...current,
+        ...(isPlainObject(payload) ? payload : {})
+    });
+
+    if (!merged.host) {
+        return { error: '代理 host 不能为空' };
+    }
+    if (!Number.isFinite(merged.port) || merged.port <= 0 || merged.port > 65535) {
+        return { error: '代理端口无效（1-65535）' };
     }
 
-    invalidateSessionListCache();
+    const { config } = readConfigOrVirtualDefault();
+    const providers = config && isPlainObject(config.model_providers) ? config.model_providers : {};
+    const preferredProvider = typeof config.model_provider === 'string' ? config.model_provider.trim() : '';
+    const finalProvider = resolveBuiltinProxyProviderName(merged.provider, providers, preferredProvider);
+
+    const normalized = {
+        ...merged,
+        provider: finalProvider
+    };
+
+    if (!options.skipWrite) {
+        writeJsonAtomic(BUILTIN_PROXY_SETTINGS_FILE, normalized);
+    }
 
     return {
         success: true,
-        source,
-        sessionId,
-        filePath
+        settings: normalized
     };
 }
 
-function generateCloneSessionId() {
-    if (crypto.randomUUID) {
-        return `clone-${crypto.randomUUID()}`;
-    }
-    const timePart = Date.now().toString(36);
-    const randomPart = crypto.randomBytes(8).toString('hex');
-    return `clone-${timePart}-${randomPart}`;
+function buildProxyListenUrl(settings) {
+    const host = formatHostForUrl(settings.host || DEFAULT_BUILTIN_PROXY_SETTINGS.host);
+    return `http://${host}:${settings.port}`;
 }
 
-function allocateCloneSessionTarget(dirPath) {
-    for (let attempt = 0; attempt < 6; attempt += 1) {
-        const sessionId = generateCloneSessionId();
-        const filePath = path.join(dirPath, `${sessionId}.jsonl`);
-        if (!fs.existsSync(filePath)) {
-            return { sessionId, filePath };
-        }
+function hasCodexConfigReadyForProxy() {
+    const result = readConfigOrVirtualDefault();
+    if (!result || result.isVirtual) {
+        return false;
     }
-    const fallbackId = `clone-${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
-    return { sessionId: fallbackId, filePath: path.join(dirPath, `${fallbackId}.jsonl`) };
+    const config = result.config || {};
+    if (!isPlainObject(config.model_providers)) {
+        return false;
+    }
+    const providerNames = Object.keys(config.model_providers)
+        .filter((name) => name && name !== BUILTIN_PROXY_PROVIDER_NAME);
+    return providerNames.length > 0;
 }
 
-function parseTimestampMs(value) {
-    if (value === undefined || value === null || value === '') {
-        return null;
+function resolveBuiltinProxyUpstream(settings) {
+    const { config } = readConfigOrVirtualDefault();
+    const providers = config && isPlainObject(config.model_providers) ? config.model_providers : {};
+    const currentProvider = typeof config.model_provider === 'string' ? config.model_provider.trim() : '';
+    const providerName = resolveBuiltinProxyProviderName(settings.provider, providers, currentProvider);
+    if (!providerName) {
+        return { error: '未找到可用的上游 provider，请先添加 provider' };
     }
-    if (typeof value === 'number' && Number.isFinite(value)) {
-        if (value > 1e12) return value;
-        if (value > 1e9) return value * 1000;
-        return value;
+    if (providerName === BUILTIN_PROXY_PROVIDER_NAME) {
+        return { error: `上游 provider 不能是 ${BUILTIN_PROXY_PROVIDER_NAME}` };
     }
-    if (typeof value === 'string') {
-        const parsed = Date.parse(value);
-        if (Number.isFinite(parsed)) {
-            return parsed;
-        }
-        const numeric = Number(value);
-        if (Number.isFinite(numeric)) {
-            if (numeric > 1e12) return numeric;
-            if (numeric > 1e9) return numeric * 1000;
-            return numeric;
-        }
+    const provider = providers[providerName];
+    if (!provider || !isPlainObject(provider)) {
+        return { error: `上游 provider 不存在: ${providerName}` };
     }
-    return null;
-}
 
-async function cloneCodexSession(params = {}) {
-    const source = params.source === 'codex' ? 'codex' : '';
-    if (!source) {
-        return { error: '仅支持 Codex 会话克隆' };
+    const baseUrl = typeof provider.base_url === 'string' ? provider.base_url.trim() : '';
+    if (!baseUrl || !isValidHttpUrl(baseUrl)) {
+        return { error: `上游 provider base_url 无效: ${providerName}` };
     }
 
-    const filePath = resolveSessionFilePath(source, params.filePath, params.sessionId);
-    if (!filePath) {
-        return { error: 'Session file not found' };
+    let token = '';
+    if (settings.authSource === 'profile') {
+        token = resolveAuthTokenFromCurrentProfile();
+    } else if (settings.authSource === 'provider') {
+        token = typeof provider.preferred_auth_method === 'string' ? provider.preferred_auth_method.trim() : '';
+        if (!token) {
+            token = resolveAuthTokenFromCurrentProfile();
+        }
     }
 
-    let content = '';
-    try {
-        content = fs.readFileSync(filePath, 'utf-8');
-    } catch (e) {
-        return { error: `读取会话失败: ${e.message}` };
+    let authHeader = '';
+    if (token) {
+        authHeader = /^bearer\s+/i.test(token) ? token : `Bearer ${token}`;
     }
 
-    if (!content.trim()) {
-        return { error: 'Session file is empty' };
-    }
+    return {
+        providerName,
+        baseUrl: normalizeBaseUrl(baseUrl),
+        authHeader
+    };
+}
+
+function createBuiltinProxyServer(settings, upstream) {
+    const connections = new Set();
+    const timeoutMs = settings.timeoutMs;
+
+    const server = http.createServer((req, res) => {
+        let parsedIncoming;
+        try {
+            parsedIncoming = new URL(req.url || '/', 'http://localhost');
+        } catch (e) {
+            res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ error: 'invalid request path' }));
+            return;
+        }
+
+        const incomingPath = parsedIncoming.pathname || '/';
+        if (incomingPath === '/health' || incomingPath === '/status') {
+            const body = JSON.stringify({
+                ok: true,
+                upstreamProvider: upstream.providerName,
+                upstreamBaseUrl: upstream.baseUrl
+            });
+            res.writeHead(200, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': Buffer.byteLength(body, 'utf-8')
+            });
+            res.end(body, 'utf-8');
+            return;
+        }
+
+        if (!(incomingPath === '/v1' || incomingPath.startsWith('/v1/'))) {
+            const body = JSON.stringify({ error: 'proxy only supports /v1/* paths' });
+            res.writeHead(404, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': Buffer.byteLength(body, 'utf-8')
+            });
+            res.end(body, 'utf-8');
+            return;
+        }
+
+        const suffix = incomingPath === '/v1'
+            ? ''
+            : incomingPath.replace(/^\/v1\/?/, '');
+        const targetBase = joinApiUrl(upstream.baseUrl, suffix);
+        if (!targetBase) {
+            const body = JSON.stringify({ error: 'failed to build upstream URL' });
+            res.writeHead(500, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': Buffer.byteLength(body, 'utf-8')
+            });
+            res.end(body, 'utf-8');
+            return;
+        }
+
+        let targetUrl;
+        try {
+            targetUrl = new URL(targetBase);
+            targetUrl.search = parsedIncoming.search || '';
+        } catch (e) {
+            const body = JSON.stringify({ error: `invalid upstream URL: ${e.message}` });
+            res.writeHead(500, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': Buffer.byteLength(body, 'utf-8')
+            });
+            res.end(body, 'utf-8');
+            return;
+        }
+
+        const requestHeaders = { ...req.headers };
+        delete requestHeaders.host;
+        delete requestHeaders.connection;
+        delete requestHeaders['content-length'];
+        if (upstream.authHeader) {
+            requestHeaders.authorization = upstream.authHeader;
+        }
+        requestHeaders['x-codexmate-proxy'] = '1';
+        if (!requestHeaders['x-forwarded-for'] && req.socket && req.socket.remoteAddress) {
+            requestHeaders['x-forwarded-for'] = req.socket.remoteAddress;
+        }
+
+        const transport = targetUrl.protocol === 'https:' ? https : http;
+        const upstreamReq = transport.request({
+            protocol: targetUrl.protocol,
+            hostname: targetUrl.hostname,
+            port: targetUrl.port || (targetUrl.protocol === 'https:' ? 443 : 80),
+            method: req.method || 'GET',
+            path: `${targetUrl.pathname}${targetUrl.search}`,
+            headers: requestHeaders,
+            agent: targetUrl.protocol === 'https:' ? HTTPS_KEEP_ALIVE_AGENT : HTTP_KEEP_ALIVE_AGENT
+        }, (upstreamRes) => {
+            const responseHeaders = { ...upstreamRes.headers };
+            delete responseHeaders.connection;
+            res.writeHead(upstreamRes.statusCode || 502, responseHeaders);
+            upstreamRes.pipe(res);
+        });
+
+        upstreamReq.setTimeout(timeoutMs, () => {
+            upstreamReq.destroy(new Error(`upstream timeout (${timeoutMs}ms)`));
+        });
+
+        upstreamReq.on('error', (err) => {
+            if (res.headersSent) {
+                try { res.destroy(err); } catch (_) {}
+                return;
+            }
+            const body = JSON.stringify({ error: `proxy request failed: ${err.message}` });
+            res.writeHead(502, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': Buffer.byteLength(body, 'utf-8')
+            });
+            res.end(body, 'utf-8');
+        });
+
+        req.pipe(upstreamReq);
+    });
+
+    server.on('connection', (socket) => {
+        connections.add(socket);
+        socket.on('close', () => connections.delete(socket));
+    });
+
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(settings.port, settings.host, () => {
+            server.removeListener('error', reject);
+            resolve({
+                server,
+                connections,
+                settings,
+                upstream,
+                startedAt: toIsoTime(Date.now()),
+                listenUrl: buildProxyListenUrl(settings)
+            });
+        });
+    });
+}
+
+async function startBuiltinProxyRuntime(payload = {}) {
+    if (g_builtinProxyRuntime) {
+        return {
+            error: '内建代理已在运行',
+            runtime: {
+                listenUrl: g_builtinProxyRuntime.listenUrl,
+                upstreamProvider: g_builtinProxyRuntime.upstream.providerName
+            }
+        };
+    }
+
+    const saveResult = saveBuiltinProxySettings(payload);
+    if (saveResult.error) {
+        return { error: saveResult.error };
+    }
+    const settings = saveResult.settings;
+    const upstream = resolveBuiltinProxyUpstream(settings);
+    if (upstream.error) {
+        return { error: upstream.error };
+    }
+
+    try {
+        g_builtinProxyRuntime = await createBuiltinProxyServer(settings, upstream);
+        return {
+            success: true,
+            running: true,
+            listenUrl: g_builtinProxyRuntime.listenUrl,
+            upstreamProvider: upstream.providerName,
+            settings
+        };
+    } catch (e) {
+        return { error: `启动内建代理失败: ${e.message}` };
+    }
+}
+
+async function stopBuiltinProxyRuntime() {
+    if (!g_builtinProxyRuntime) {
+        return { success: true, running: false };
+    }
+    const runtime = g_builtinProxyRuntime;
+    g_builtinProxyRuntime = null;
+
+    await new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled) return;
+            settled = true;
+            resolve();
+        };
+
+        runtime.server.close(() => finish());
+        setTimeout(() => finish(), 1000);
+    });
+
+    for (const socket of runtime.connections) {
+        try { socket.destroy(); } catch (_) {}
+    }
+    runtime.connections.clear();
+
+    return {
+        success: true,
+        running: false
+    };
+}
+
+function getBuiltinProxyStatus() {
+    const settings = readBuiltinProxySettings();
+    return {
+        running: !!g_builtinProxyRuntime,
+        settings,
+        runtime: g_builtinProxyRuntime
+            ? {
+                provider: DEFAULT_LOCAL_PROVIDER_NAME,
+                startedAt: g_builtinProxyRuntime.startedAt,
+                listenUrl: g_builtinProxyRuntime.listenUrl,
+                upstreamProvider: g_builtinProxyRuntime.upstream.providerName,
+                upstreamBaseUrl: g_builtinProxyRuntime.upstream.baseUrl
+            }
+            : null
+    };
+}
+
+function applyBuiltinProxyProvider(params = {}) {
+    const settings = readBuiltinProxySettings();
+    const hostForUrl = formatHostForUrl(settings.host);
+    const baseUrl = `http://${hostForUrl}:${settings.port}`;
+
+    const { config } = readConfigOrVirtualDefault();
+    const providers = config && isPlainObject(config.model_providers) ? config.model_providers : {};
+    const exists = !!providers[BUILTIN_PROXY_PROVIDER_NAME];
+    const saveResult = exists
+        ? updateProviderInConfig({
+            name: BUILTIN_PROXY_PROVIDER_NAME,
+            url: baseUrl,
+            key: '',
+            allowManaged: true
+        })
+        : addProviderToConfig({
+            name: BUILTIN_PROXY_PROVIDER_NAME,
+            url: baseUrl,
+            key: '',
+            allowManaged: true
+        });
+
+    if (saveResult && saveResult.error) {
+        return saveResult;
+    }
+
+    const switchToProxy = params.switchToProxy !== false;
+    let targetModel = '';
+    if (switchToProxy) {
+        try {
+            targetModel = cmdSwitch(BUILTIN_PROXY_PROVIDER_NAME, true) || '';
+        } catch (e) {
+            return { error: `写入代理 provider 成功，但切换失败: ${e.message}` };
+        }
+    }
+
+    return {
+        success: true,
+        provider: BUILTIN_PROXY_PROVIDER_NAME,
+        baseUrl,
+        switched: switchToProxy,
+        model: targetModel
+    };
+}
+
+async function ensureBuiltinProxyForCodexDefault(params = {}) {
+    const payload = isPlainObject(params) ? { ...params } : {};
+    const switchToProxy = payload.switchToProxy !== false;
+    delete payload.switchToProxy;
+    payload.enabled = true;
+
+    const saveResult = saveBuiltinProxySettings(payload);
+    if (saveResult.error) {
+        return { error: saveResult.error };
+    }
+    let nextSettings = saveResult.settings;
+
+    let upstreamResult = resolveBuiltinProxyUpstream(nextSettings);
+    if (upstreamResult.error) {
+        return { error: upstreamResult.error };
+    }
+
+    const runtime = g_builtinProxyRuntime;
+    const shouldRestart = !!runtime && (
+        runtime.settings.host !== nextSettings.host
+        || runtime.settings.port !== nextSettings.port
+        || runtime.settings.authSource !== nextSettings.authSource
+        || runtime.settings.timeoutMs !== nextSettings.timeoutMs
+        || runtime.upstream.providerName !== upstreamResult.providerName
+        || runtime.upstream.baseUrl !== upstreamResult.baseUrl
+        || runtime.upstream.authHeader !== upstreamResult.authHeader
+    );
+
+    if (shouldRestart) {
+        await stopBuiltinProxyRuntime();
+    }
+
+    if (!g_builtinProxyRuntime) {
+        let startRes = await startBuiltinProxyRuntime(nextSettings);
+        if (!startRes.success && /EADDRINUSE/i.test(String(startRes.error || ''))) {
+            const fallbackPort = await findAvailablePort(nextSettings.host, nextSettings.port + 1, 30);
+            if (fallbackPort > 0) {
+                const retrySave = saveBuiltinProxySettings({
+                    ...nextSettings,
+                    port: fallbackPort,
+                    enabled: true
+                });
+                if (retrySave.success) {
+                    nextSettings = retrySave.settings;
+                    upstreamResult = resolveBuiltinProxyUpstream(nextSettings);
+                    if (upstreamResult.error) {
+                        return { error: upstreamResult.error };
+                    }
+                    startRes = await startBuiltinProxyRuntime(nextSettings);
+                }
+            }
+        }
+        if (!startRes.success) {
+            return { error: startRes.error || '启动内建代理失败' };
+        }
+    }
+
+    let applyRes = {
+        success: true,
+        provider: BUILTIN_PROXY_PROVIDER_NAME,
+        baseUrl: buildProxyListenUrl(nextSettings),
+        switched: false,
+        model: ''
+    };
+    if (switchToProxy) {
+        applyRes = applyBuiltinProxyProvider({ switchToProxy: true });
+        if (applyRes.error) {
+            return applyRes;
+        }
+    }
+
+    const status = getBuiltinProxyStatus();
+    return {
+        success: true,
+        provider: applyRes.provider,
+        baseUrl: applyRes.baseUrl,
+        switched: applyRes.switched,
+        model: applyRes.model || '',
+        settings: status.settings,
+        runtime: status.runtime
+    };
+}
+
+function updateClaudeSessionIndex(indexPath, sessionFilePath, sessionId) {
+    if (!indexPath || !fs.existsSync(indexPath)) {
+        return;
+    }
+    const index = readJsonFile(indexPath, null);
+    if (!index || !Array.isArray(index.entries)) {
+        return;
+    }
+    const resolvedFile = sessionFilePath ? path.resolve(sessionFilePath) : '';
+    const resolvedLower = resolvedFile ? resolvedFile.toLowerCase() : '';
+    const filtered = index.entries.filter((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return false;
+        }
+        const entrySessionId = typeof entry.sessionId === 'string' ? entry.sessionId : '';
+        if (sessionId && entrySessionId === sessionId) {
+            return false;
+        }
+        if (entry.fullPath) {
+            const expanded = expandHomePath(entry.fullPath);
+            const entryPath = expanded ? path.resolve(expanded) : '';
+            if (entryPath && resolvedLower && entryPath.toLowerCase() === resolvedLower) {
+                return false;
+            }
+        }
+        return true;
+    });
+    if (filtered.length === index.entries.length) {
+        return;
+    }
+    index.entries = filtered;
+    try {
+        fs.writeFileSync(indexPath, JSON.stringify(index, null, 2), 'utf-8');
+    } catch (e) {}
+}
+
+async function deleteSessionData(params = {}) {
+    const source = params.source === 'claude' ? 'claude' : (params.source === 'codex' ? 'codex' : '');
+    if (!source) {
+        return { error: 'Invalid source' };
+    }
+
+    const filePath = resolveSessionFilePath(source, params.filePath, params.sessionId);
+    if (!filePath) {
+        return { error: 'Session file not found' };
+    }
+
+    const sessionId = params.sessionId || path.basename(filePath, '.jsonl');
+    try {
+        fs.unlinkSync(filePath);
+    } catch (e) {
+        return { error: `删除会话失败: ${e.message}` };
+    }
+
+    if (source === 'claude') {
+        const indexPath = findClaudeSessionIndexPath(filePath);
+        if (indexPath) {
+            updateClaudeSessionIndex(indexPath, filePath, sessionId);
+        }
+    }
+
+    invalidateSessionListCache();
+
+    return {
+        success: true,
+        source,
+        sessionId,
+        filePath
+    };
+}
+
+function generateCloneSessionId() {
+    if (crypto.randomUUID) {
+        return `clone-${crypto.randomUUID()}`;
+    }
+    const timePart = Date.now().toString(36);
+    const randomPart = crypto.randomBytes(8).toString('hex');
+    return `clone-${timePart}-${randomPart}`;
+}
+
+function allocateCloneSessionTarget(dirPath) {
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        const sessionId = generateCloneSessionId();
+        const filePath = path.join(dirPath, `${sessionId}.jsonl`);
+        if (!fs.existsSync(filePath)) {
+            return { sessionId, filePath };
+        }
+    }
+    const fallbackId = `clone-${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
+    return { sessionId: fallbackId, filePath: path.join(dirPath, `${fallbackId}.jsonl`) };
+}
+
+function parseTimestampMs(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        if (value > 1e12) return value;
+        if (value > 1e9) return value * 1000;
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+        const numeric = Number(value);
+        if (Number.isFinite(numeric)) {
+            if (numeric > 1e12) return numeric;
+            if (numeric > 1e9) return numeric * 1000;
+            return numeric;
+        }
+    }
+    return null;
+}
+
+async function cloneCodexSession(params = {}) {
+    const source = params.source === 'codex' ? 'codex' : '';
+    if (!source) {
+        return { error: '仅支持 Codex 会话克隆' };
+    }
+
+    const filePath = resolveSessionFilePath(source, params.filePath, params.sessionId);
+    if (!filePath) {
+        return { error: 'Session file not found' };
+    }
+
+    let content = '';
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+        return { error: `读取会话失败: ${e.message}` };
+    }
+
+    if (!content.trim()) {
+        return { error: 'Session file is empty' };
+    }
 
     const lineEnding = detectLineEnding(content);
     const rawLines = content.split(/\r?\n/);
@@ -3440,6 +4342,9 @@ function buildExportPayload(includeKeys) {
     const providers = config.model_providers || {};
     const providerData = {};
     for (const [name, provider] of Object.entries(providers)) {
+        if (isBuiltinProxyProvider(name)) {
+            continue;
+        }
         providerData[name] = {
             baseUrl: provider.base_url || '',
             apiKey: includeKeys ? (provider.preferred_auth_method || '') : null
@@ -3561,6 +4466,9 @@ function importConfigData(payload, options = {}) {
     let updatedProviders = 0;
 
     for (const [name, provider] of Object.entries(normalized.providers)) {
+        if (isBuiltinProxyProvider(name)) {
+            continue;
+        }
         if (existingProviders[name]) {
             if (overwriteProviders) {
                 const apiKey = typeof provider.apiKey === 'string' && provider.apiKey
@@ -3592,6 +4500,7 @@ function importConfigData(payload, options = {}) {
     if (applyCurrentModels && normalized.currentModels) {
         const currentModels = readCurrentModels();
         for (const [name, model] of Object.entries(normalized.currentModels)) {
+            if (isBuiltinProxyProvider(name)) continue;
             if (typeof model !== 'string' || !model) continue;
             currentModels[name] = model;
         }
@@ -4108,7 +5017,10 @@ function cmdUseModel(modelName, silent = false) {
 
 // 添加提供商
 function cmdAdd(name, baseUrl, apiKey, silent = false) {
-    if (!name || !baseUrl) {
+    const providerName = typeof name === 'string' ? name.trim() : '';
+    const providerBaseUrl = typeof baseUrl === 'string' ? baseUrl.trim() : '';
+
+    if (!providerName || !providerBaseUrl) {
         if (!silent) {
             console.error('用法: codexmate add <名称> <URL> [密钥]');
             console.log('\n示例:');
@@ -4116,17 +5028,21 @@ function cmdAdd(name, baseUrl, apiKey, silent = false) {
         }
         throw new Error('名称和URL必填');
     }
+    if (isReservedProviderNameForCreation(providerName)) {
+        if (!silent) console.error('错误: local provider 为系统保留名称，不可新增');
+        throw new Error('local provider 为系统保留名称，不可新增');
+    }
 
     const config = readConfig();
-    if (config.model_providers && config.model_providers[name]) {
-        if (!silent) console.error('错误: 提供商已存在:', name);
+    if (config.model_providers && config.model_providers[providerName]) {
+        if (!silent) console.error('错误: 提供商已存在:', providerName);
         throw new Error('提供商已存在');
     }
 
     const newBlock = `
-[model_providers.${name}]
-name = "${name}"
-base_url = "${baseUrl}"
+[model_providers.${providerName}]
+name = "${providerName}"
+base_url = "${providerBaseUrl}"
 wire_api = "responses"
 requires_openai_auth = false
 preferred_auth_method = "${apiKey || ''}"
@@ -4140,14 +5056,14 @@ stream_idle_timeout_ms = 300000
 
     // 初始化当前模型
     const currentModels = readCurrentModels();
-    if (!currentModels[name]) {
-        currentModels[name] = readModels()[0];
+    if (!currentModels[providerName]) {
+        currentModels[providerName] = readModels()[0];
         writeCurrentModels(currentModels);
     }
 
     if (!silent) {
-        console.log('✓ 已添加提供商:', name);
-        console.log('  URL:', baseUrl);
+        console.log('✓ 已添加提供商:', providerName);
+        console.log('  URL:', providerBaseUrl);
         console.log();
     }
 }
@@ -4168,11 +5084,19 @@ function cmdDelete(name, silent = false) {
 }
 
 // 更新提供商
-function cmdUpdate(name, baseUrl, apiKey, silent = false) {
+function cmdUpdate(name, baseUrl, apiKey, silent = false, options = {}) {
+    const allowManaged = !!(options && options.allowManaged);
     if (!name) {
         if (!silent) console.error('错误: 提供商名称必填');
         throw new Error('提供商名称必填');
     }
+    if (isNonEditableProvider(name) && !allowManaged) {
+        const msg = isDefaultLocalProvider(name)
+            ? 'local provider 为系统保留项，不可编辑'
+            : '本地代理配置为系统内建项，不可编辑';
+        if (!silent) console.error(`错误: ${msg}`);
+        throw new Error(msg);
+    }
 
     const config = readConfig();
     if (!config.model_providers || !config.model_providers[name]) {
@@ -4357,29 +5281,248 @@ function applyToClaudeSettings(config = {}) {
     }
 }
 
-function readClaudeSettingsInfo() {
-    const readResult = readJsonObjectFromFile(CLAUDE_SETTINGS_FILE, {});
-    if (!readResult.ok) {
+function readClaudeSettingsInfo() {
+    const readResult = readJsonObjectFromFile(CLAUDE_SETTINGS_FILE, {});
+    if (!readResult.ok) {
+        return {
+            error: readResult.error || '读取 Claude 配置失败',
+            exists: !!readResult.exists,
+            targetPath: CLAUDE_SETTINGS_FILE
+        };
+    }
+
+    const settings = readResult.data || {};
+    const env = (settings.env && typeof settings.env === 'object' && !Array.isArray(settings.env))
+        ? settings.env
+        : {};
+
+    return {
+        exists: !!readResult.exists,
+        targetPath: CLAUDE_SETTINGS_FILE,
+        apiKey: typeof env.ANTHROPIC_API_KEY === 'string' ? env.ANTHROPIC_API_KEY : '',
+        baseUrl: typeof env.ANTHROPIC_BASE_URL === 'string' ? env.ANTHROPIC_BASE_URL : '',
+        model: typeof env.ANTHROPIC_MODEL === 'string' ? env.ANTHROPIC_MODEL : '',
+        env
+    };
+}
+
+// API: 打包 Claude 配置目录（系统 zip 可用则使用，否则回退 zip-lib）
+async function prepareClaudeDirDownload() {
+    try {
+        if (!fs.existsSync(CLAUDE_DIR)) {
+            return { error: 'Claude 配置目录不存在', path: CLAUDE_DIR };
+        }
+
+        const tempDir = os.tmpdir();
+        const timestamp = Date.now();
+        const zipFileName = `claude-config-${timestamp}.zip`;
+        const zipFilePath = path.join(tempDir, zipFileName);
+
+        const zipTool = resolveZipTool();
+        if (zipTool.type === 'zip') {
+            const cmd = `"${zipTool.cmd}" -0 -q -r "${zipFilePath}" "${CLAUDE_DIR}"`;
+            execSync(cmd, { stdio: 'ignore' });
+        } else {
+            await zipLib.archiveFolder(CLAUDE_DIR, zipFilePath);
+        }
+
+        return {
+            success: true,
+            downloadPath: zipFilePath,
+            fileName: zipFileName,
+            sourcePath: CLAUDE_DIR
+        };
+    } catch (e) {
+        return { error: `打包失败：${e.message}` };
+    }
+}
+
+// API: 打包 Codex 配置目录（同策略）
+async function prepareCodexDirDownload() {
+    try {
+        if (!fs.existsSync(CONFIG_DIR)) {
+            return { error: 'Codex 配置目录不存在', path: CONFIG_DIR };
+        }
+
+        const tempDir = os.tmpdir();
+        const timestamp = Date.now();
+        const zipFileName = `${CODEX_BACKUP_NAME}-${timestamp}.zip`;
+        const zipFilePath = path.join(tempDir, zipFileName);
+
+        const zipTool = resolveZipTool();
+        if (zipTool.type === 'zip') {
+            const cmd = `"${zipTool.cmd}" -0 -q -r "${zipFilePath}" "${CONFIG_DIR}"`;
+            execSync(cmd, { stdio: 'ignore' });
+        } else {
+            await zipLib.archiveFolder(CONFIG_DIR, zipFilePath);
+        }
+
+        return {
+            success: true,
+            downloadPath: zipFilePath,
+            fileName: zipFileName,
+            sourcePath: CONFIG_DIR
+        };
+    } catch (e) {
+        return { error: `打包失败：${e.message}` };
+    }
+}
+
+function copyDirRecursive(srcDir, destDir) {
+    ensureDir(destDir);
+    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        } else if (entry.isSymbolicLink()) {
+            const target = fs.readlinkSync(srcPath);
+            fs.symlinkSync(target, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+function writeUploadZip(base64, prefix, originalName = '') {
+    let buffer;
+    try {
+        buffer = Buffer.from(base64 || '', 'base64');
+    } catch (e) {
+        return { error: '备份文件内容不是有效的 base64 编码' };
+    }
+
+    if (!buffer || buffer.length === 0) {
+        return { error: '备份文件为空' };
+    }
+
+    if (buffer.length > MAX_UPLOAD_SIZE) {
+        return { error: `备份文件过大（>${Math.floor(MAX_UPLOAD_SIZE / 1024 / 1024)}MB）` };
+    }
+
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+    const fileName = path.basename(originalName && typeof originalName === 'string' ? originalName : `${prefix}.zip`);
+    const zipPath = path.join(tempDir, fileName.toLowerCase().endsWith('.zip') ? fileName : `${fileName}.zip`);
+    fs.writeFileSync(zipPath, buffer);
+    return { tempDir, zipPath };
+}
+
+async function extractUploadZip(zipPath, extractDir) {
+    const unzipTool = resolveUnzipTool();
+    ensureDir(extractDir);
+    await unzipWithLibrary(zipPath, extractDir);
+}
+
+function findConfigSourceDir(extractedDir, markerDirName, requiredFileName) {
+    const markerPath = path.join(extractedDir, markerDirName);
+    if (fs.existsSync(markerPath) && fs.statSync(markerPath).isDirectory()) {
+        return markerPath;
+    }
+
+    const entries = fs.readdirSync(extractedDir, { withFileTypes: true }).filter((item) => item.isDirectory());
+    if (entries.length === 1) {
+        const onlyDir = path.join(extractedDir, entries[0].name);
+        const nestedMarker = path.join(onlyDir, markerDirName);
+        if (fs.existsSync(nestedMarker) && fs.statSync(nestedMarker).isDirectory()) {
+            return nestedMarker;
+        }
+        if (fs.existsSync(path.join(onlyDir, requiredFileName))) {
+            return onlyDir;
+        }
+    }
+
+    if (fs.existsSync(path.join(extractedDir, requiredFileName))) {
+        return extractedDir;
+    }
+
+    return extractedDir;
+}
+
+async function backupDirectoryIfExists(dirPath, prefix) {
+    if (!fs.existsSync(dirPath)) {
+        return { backupPath: '' };
+    }
+
+    const tempDir = os.tmpdir();
+    const timestamp = Date.now();
+    const zipFileName = `${prefix}-${timestamp}.zip`;
+    const zipFilePath = path.join(tempDir, zipFileName);
+    const zipTool = resolveZipTool();
+
+    try {
+        if (zipTool.type === 'zip') {
+            const cmd = `"${zipTool.cmd}" -0 -q -r "${zipFilePath}" "${dirPath}"`;
+            execSync(cmd, { stdio: 'ignore' });
+        } else {
+            await zipLib.archiveFolder(dirPath, zipFilePath);
+        }
+        return { backupPath: zipFilePath, fileName: zipFileName };
+    } catch (e) {
+        return { backupPath: '', warning: `备份失败: ${e.message}` };
+    }
+}
+
+async function restoreConfigDirectoryFromUpload(payload, options) {
+    const { targetDir, requiredFileName, markerDirName, tempPrefix, backupPrefix } = options;
+    if (!payload || typeof payload.fileBase64 !== 'string' || !payload.fileBase64.trim()) {
+        return { error: '缺少备份文件内容' };
+    }
+
+    const upload = writeUploadZip(payload.fileBase64, tempPrefix, payload.fileName);
+    if (upload.error) {
+        return { error: upload.error };
+    }
+
+    const tempDir = upload.tempDir;
+    const extractDir = path.join(tempDir, 'extract');
+    let backupPath = '';
+    try {
+        await extractUploadZip(upload.zipPath, extractDir);
+        const sourceDir = findConfigSourceDir(extractDir, markerDirName, requiredFileName);
+        const requiredPath = path.join(sourceDir, requiredFileName);
+        if (!fs.existsSync(requiredPath)) {
+            return { error: `无效备份，缺少 ${requiredFileName}` };
+        }
+
+        const backupResult = await backupDirectoryIfExists(targetDir, backupPrefix);
+        backupPath = backupResult.backupPath || '';
+
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        copyDirRecursive(sourceDir, targetDir);
+
         return {
-            error: readResult.error || '读取 Claude 配置失败',
-            exists: !!readResult.exists,
-            targetPath: CLAUDE_SETTINGS_FILE
+            success: true,
+            targetDir,
+            appliedFrom: payload.fileName || '',
+            backupPath,
+            backupWarning: backupResult.warning || ''
         };
+    } catch (e) {
+        return { error: `导入失败：${e.message}` };
+    } finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
     }
+}
 
-    const settings = readResult.data || {};
-    const env = (settings.env && typeof settings.env === 'object' && !Array.isArray(settings.env))
-        ? settings.env
-        : {};
+async function restoreClaudeDir(payload) {
+    return await restoreConfigDirectoryFromUpload(payload, {
+        targetDir: CLAUDE_DIR,
+        requiredFileName: 'settings.json',
+        markerDirName: '.claude',
+        tempPrefix: 'claude-restore',
+        backupPrefix: 'claude-config'
+    });
+}
 
-    return {
-        exists: !!readResult.exists,
-        targetPath: CLAUDE_SETTINGS_FILE,
-        apiKey: typeof env.ANTHROPIC_API_KEY === 'string' ? env.ANTHROPIC_API_KEY : '',
-        baseUrl: typeof env.ANTHROPIC_BASE_URL === 'string' ? env.ANTHROPIC_BASE_URL : '',
-        model: typeof env.ANTHROPIC_MODEL === 'string' ? env.ANTHROPIC_MODEL : '',
-        env
-    };
+async function restoreCodexDir(payload) {
+    return await restoreConfigDirectoryFromUpload(payload, {
+        targetDir: CONFIG_DIR,
+        requiredFileName: 'config.toml',
+        markerDirName: '.codex',
+        tempPrefix: 'codex-restore',
+        backupPrefix: 'codex-config'
+    });
 }
 
 // CLI: 一行写入 Claude Code 配置
@@ -4436,18 +5579,196 @@ function commandExists(command, args = '') {
     }
 }
 
-const SEVEN_ZIP_PATHS = [
-    'C:\\Program Files\\7-Zip\\7z.exe',
-    'C:\\Program Files (x86)\\7-Zip\\7z.exe',
-    '7z'
+function detectPreferredPackageManager() {
+    const userAgent = typeof process.env.npm_config_user_agent === 'string'
+        ? process.env.npm_config_user_agent.trim().toLowerCase()
+        : '';
+    if (userAgent.startsWith('pnpm/')) return 'pnpm';
+    if (userAgent.startsWith('bun/')) return 'bun';
+    if (userAgent.startsWith('npm/')) return 'npm';
+
+    if (commandExists('pnpm', '--version')) return 'pnpm';
+    if (commandExists('bun', '--version')) return 'bun';
+    return 'npm';
+}
+
+function resolveCommandPath(command) {
+    if (!command) return '';
+    const locator = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const probe = spawnSync(locator, [command], {
+            encoding: 'utf8',
+            windowsHide: true,
+            timeout: 2500
+        });
+        if (probe.error || probe.status !== 0) {
+            return '';
+        }
+        const lines = String(probe.stdout || '')
+            .split(/\r?\n/g)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        return lines[0] || '';
+    } catch (e) {
+        return '';
+    }
+}
+
+function parseBinaryVersionOutput(text) {
+    const raw = typeof text === 'string' ? text : '';
+    const line = raw
+        .split(/\r?\n/g)
+        .map((item) => item.trim())
+        .find(Boolean) || '';
+    if (!line) return '';
+    return line.length > 120 ? `${line.slice(0, 117)}...` : line;
+}
+
+function probeCliBinary(binName) {
+    const attempts = [['--version'], ['-v'], ['version']];
+    let lastError = '';
+
+    for (const args of attempts) {
+        const argString = args.join(' ').trim();
+        const commandLine = argString ? `${binName} ${argString}` : binName;
+        try {
+            const stdout = execSync(commandLine, {
+                encoding: 'utf8',
+                windowsHide: true,
+                timeout: 5000,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: process.platform === 'win32'
+            });
+            const version = parseBinaryVersionOutput(String(stdout || ''));
+            return {
+                installed: true,
+                bin: binName,
+                version: version || 'unknown',
+                path: resolveCommandPath(binName),
+                error: ''
+            };
+        } catch (error) {
+            const err = error || {};
+            const stdout = typeof err.stdout === 'string' ? err.stdout : String(err.stdout || '');
+            const stderr = typeof err.stderr === 'string' ? err.stderr : String(err.stderr || '');
+            const output = `${stdout}\n${stderr}`.trim();
+            const version = parseBinaryVersionOutput(output);
+            const status = Number.isFinite(err.status) ? err.status : null;
+            if (version && status === 0) {
+                return {
+                    installed: true,
+                    bin: binName,
+                    version,
+                    path: resolveCommandPath(binName),
+                    error: ''
+                };
+            }
+            if (version) {
+                lastError = status !== null
+                    ? `${binName} exited with ${status}: ${version}`
+                    : `${binName} failed: ${version}`;
+                continue;
+            }
+            const message = err && err.message ? String(err.message) : '';
+            if (message && !/ENOENT/i.test(message)) {
+                lastError = message;
+            }
+        }
+    }
+
+    return {
+        installed: false,
+        bin: binName,
+        version: '',
+        path: '',
+        error: lastError
+    };
+}
+
+function resolveInstallCommandsByPackageManager(packageManager) {
+    const normalized = String(packageManager || '').trim().toLowerCase();
+    const manager = normalized === 'pnpm' || normalized === 'bun' || normalized === 'npm'
+        ? normalized
+        : 'npm';
+    const commandsByTarget = {};
+
+    for (const target of CLI_INSTALL_TARGETS) {
+        const pkg = target.packageName;
+        if (manager === 'pnpm') {
+            commandsByTarget[target.id] = {
+                install: `pnpm add -g ${pkg}`,
+                update: `pnpm up -g ${pkg}`,
+                uninstall: `pnpm remove -g ${pkg}`
+            };
+            continue;
+        }
+        if (manager === 'bun') {
+            commandsByTarget[target.id] = {
+                install: `bun add -g ${pkg}`,
+                update: `bun update -g ${pkg}`,
+                uninstall: `bun remove -g ${pkg}`
+            };
+            continue;
+        }
+        commandsByTarget[target.id] = {
+            install: `npm install -g ${pkg}`,
+            update: `npm update -g ${pkg}`,
+            uninstall: `npm uninstall -g ${pkg}`
+        };
+    }
+
+    return {
+        packageManager: manager,
+        commandsByTarget
+    };
+}
+
+function buildInstallStatusReport() {
+    const packageManager = detectPreferredPackageManager();
+    const targetReports = CLI_INSTALL_TARGETS.map((target) => {
+        let hit = null;
+        let lastError = '';
+        for (const binName of target.bins) {
+            const probe = probeCliBinary(binName);
+            if (probe.installed) {
+                hit = probe;
+                break;
+            }
+            if (probe.error) {
+                lastError = probe.error;
+            }
+        }
+        return {
+            id: target.id,
+            name: target.name,
+            packageName: target.packageName,
+            installed: !!(hit && hit.installed),
+            bin: hit ? hit.bin : (target.bins[0] || ''),
+            version: hit ? hit.version : '',
+            commandPath: hit ? hit.path : '',
+            error: hit ? '' : lastError
+        };
+    });
+
+    const commandSpec = resolveInstallCommandsByPackageManager(packageManager);
+    return {
+        platform: process.platform,
+        packageManager: commandSpec.packageManager,
+        targets: targetReports,
+        commandsByTarget: commandSpec.commandsByTarget
+    };
+}
+
+const ZIP_PATHS = [
+    'zip'
 ];
 
-function findSevenZipExecutable() {
-    for (const candidate of SEVEN_ZIP_PATHS) {
+function findZipExecutable() {
+    for (const candidate of ZIP_PATHS) {
         try {
-            if (candidate === '7z') {
-                if (commandExists('7z', '--help')) {
-                    return '7z';
+            if (candidate === 'zip') {
+                if (commandExists('zip', '--help')) {
+                    return 'zip';
                 }
             } else if (fs.existsSync(candidate)) {
                 return candidate;
@@ -4458,18 +5779,14 @@ function findSevenZipExecutable() {
 }
 
 function resolveZipTool() {
-    const sevenZipExe = findSevenZipExecutable();
-    if (sevenZipExe) {
-        return { type: '7z', cmd: sevenZipExe };
+    const zipExe = findZipExecutable();
+    if (zipExe) {
+        return { type: 'zip', cmd: zipExe };
     }
     return { type: 'lib', cmd: 'zip-lib' };
 }
 
 function resolveUnzipTool() {
-    const sevenZipExe = findSevenZipExecutable();
-    if (sevenZipExe) {
-        return { type: '7z', cmd: sevenZipExe };
-    }
     return { type: 'lib', cmd: 'zip-lib' };
 }
 
@@ -4486,7 +5803,7 @@ async function unzipWithLibrary(zipPath, outputDir) {
     await zipLib.extract(zipPath, outputDir);
 }
 
-// 压缩（7-Zip 优先）
+// 压缩（系统 zip 优先，其次 zip-lib）
 async function cmdZip(targetPath, options = {}) {
     if (!targetPath) {
         console.error('用法: codexmate zip <文件或文件夹路径> [--max:压缩级别]');
@@ -4516,40 +5833,27 @@ async function cmdZip(targetPath, options = {}) {
     const outputPath = path.join(outputDir, `${baseName}.zip`);
 
     const zipTool = resolveZipTool();
+    const useZipCmd = zipTool.type === 'zip';
 
     console.log('\n压缩配置:');
     console.log('  源路径:', absPath);
     console.log('  输出文件:', outputPath);
-    console.log('  压缩级别:', compressionLevel);
-    console.log('  压缩工具:', zipTool.type === '7z' ? '7-Zip' : 'zip-lib');
-    console.log('  多线程:', zipTool.type === '7z' ? '启用' : '未启用（JS 库）');
-    if (zipTool.type !== '7z') {
-        console.log('  提示: JS 库不支持压缩级别，已忽略 --max');
+    console.log('  压缩工具:', useZipCmd ? '系统 zip' : 'zip-lib');
+    if (useZipCmd) {
+        console.log('  压缩级别:', compressionLevel);
+    } else {
+        console.log('  压缩级别: 固定（zip-lib 不支持 --max，已忽略）');
     }
     console.log('\n开始压缩...\n');
 
     try {
-        if (zipTool.type === '7z') {
-            const cmd = `"${zipTool.cmd}" a -tzip -mmt=on -mx=${compressionLevel} "${outputPath}" "${absPath}"`;
-            const result = execSync(cmd, { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 });
-            const sizeMatch = result.match(/Archive size:\s*(\d+)\s*bytes/);
-            const filesMatch = result.match(/(\d+)\s*files/);
-
-            console.log('✓ 压缩完成!');
-            console.log('  输出文件:', outputPath);
-            if (sizeMatch) {
-                const sizeBytes = parseInt(sizeMatch[1]);
-                const sizeMB = (sizeBytes / 1024 / 1024).toFixed(2);
-                console.log('  压缩大小:', sizeMB, 'MB');
-            }
-            if (filesMatch) {
-                console.log('  文件数量:', filesMatch[1]);
-            }
-            console.log();
-            return;
+        if (useZipCmd) {
+            const cmd = `"${zipTool.cmd}" -${compressionLevel} -q -r "${outputPath}" "${absPath}"`;
+            execSync(cmd, { stdio: 'ignore' });
+        } else {
+            await zipWithLibrary(absPath, outputPath);
         }
 
-        await zipWithLibrary(absPath, outputPath);
         console.log('✓ 压缩完成!');
         console.log('  输出文件:', outputPath);
         console.log();
@@ -4559,7 +5863,7 @@ async function cmdZip(targetPath, options = {}) {
     }
 }
 
-// 解压（7-Zip 优先）
+// 解压（zip-lib）
 async function cmdUnzip(zipPath, outputDir) {
     if (!zipPath) {
         console.error('用法: codexmate unzip <zip文件路径> [输出目录]');
@@ -4591,24 +5895,10 @@ async function cmdUnzip(zipPath, outputDir) {
     console.log('\n解压配置:');
     console.log('  源文件:', absZipPath);
     console.log('  输出目录:', absOutputDir);
-    console.log('  解压工具:', unzipTool.type === '7z' ? '7-Zip' : 'zip-lib');
-    console.log('  多线程:', unzipTool.type === '7z' ? '启用' : '未启用（JS 库）');
+    console.log('  解压工具:', 'zip-lib');
     console.log('\n开始解压...\n');
 
     try {
-        if (unzipTool.type === '7z') {
-            const cmd = `"${unzipTool.cmd}" x -mmt=on -o"${absOutputDir}" "${absZipPath}" -y`;
-            const result = execSync(cmd, { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 });
-            const filesMatch = result.match(/(\d+)\s*files/);
-            console.log('✓ 解压完成!');
-            console.log('  输出目录:', absOutputDir);
-            if (filesMatch) {
-                console.log('  文件数量:', filesMatch[1]);
-            }
-            console.log();
-            return;
-        }
-
         await unzipWithLibrary(absZipPath, absOutputDir);
         console.log('✓ 解压完成!');
         console.log('  输出目录:', absOutputDir);
@@ -4899,6 +6189,9 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                                 initNotice: consumeInitNotice()
                             };
                             break;
+                        case 'install-status':
+                            result = buildInstallStatusReport();
+                            break;
                         case 'list':
                             const listConfigResult = readConfigOrVirtualDefault();
                             const listConfig = listConfigResult.config;
@@ -4911,7 +6204,10 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                                     url: p.base_url || '',
                                     key: maskKey(p.preferred_auth_method || ''),
                                     hasKey: !!(p.preferred_auth_method && p.preferred_auth_method.trim()),
-                                    current: name === current
+                                    current: name === current,
+                                    readOnly: isBuiltinProxyProvider(name),
+                                    nonDeletable: isNonDeletableProvider(name),
+                                    nonEditable: isNonEditableProvider(name)
                                 }))
                             };
                             break;
@@ -5082,6 +6378,61 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                         case 'session-plain':
                             result = await readSessionPlain(params);
                             break;
+                        case 'download-claude-dir':
+                            result = await prepareClaudeDirDownload();
+                            break;
+                        case 'download-codex-dir':
+                            result = await prepareCodexDirDownload();
+                            break;
+                        case 'restore-claude-dir':
+                            result = await restoreClaudeDir(params || {});
+                            break;
+                        case 'restore-codex-dir':
+                            result = await restoreCodexDir(params || {});
+                            break;
+                        case 'list-auth-profiles':
+                            result = {
+                                profiles: listAuthProfilesInfo()
+                            };
+                            break;
+                        case 'import-auth-profile':
+                            result = importAuthProfileFromUpload(params || {});
+                            break;
+                        case 'switch-auth-profile':
+                            {
+                                const profileName = params && typeof params.name === 'string' ? params.name.trim() : '';
+                                if (!profileName) {
+                                    result = { error: '认证名称不能为空' };
+                                } else {
+                                    try {
+                                        result = switchAuthProfile(profileName, { silent: true });
+                                    } catch (e) {
+                                        result = { error: e.message || '切换认证失败' };
+                                    }
+                                }
+                            }
+                            break;
+                        case 'delete-auth-profile':
+                            result = deleteAuthProfile(params && params.name ? params.name : '');
+                            break;
+                        case 'proxy-status':
+                            result = getBuiltinProxyStatus();
+                            break;
+                        case 'proxy-save-config':
+                            result = saveBuiltinProxySettings(params || {});
+                            break;
+                        case 'proxy-start':
+                            result = await startBuiltinProxyRuntime(params || {});
+                            break;
+                        case 'proxy-stop':
+                            result = await stopBuiltinProxyRuntime();
+                            break;
+                        case 'proxy-enable-codex-default':
+                            result = await ensureBuiltinProxyForCodexDefault(params || {});
+                            break;
+                        case 'proxy-apply-provider':
+                            result = applyBuiltinProxyProvider(params || {});
+                            break;
                         default:
                             result = { error: '未知操作' };
                     }
@@ -5126,6 +6477,34 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                         : 'application/octet-stream';
             res.writeHead(200, { 'Content-Type': mime });
             fs.createReadStream(filePath).pipe(res);
+        } else if (requestPath.startsWith('/download/')) {
+            const fileName = requestPath.slice('/download/'.length);
+            const decodedFileName = decodeURIComponent(fileName);
+            const tempDir = os.tmpdir();
+            const filePath = path.join(tempDir, decodedFileName);
+
+            if (!isPathInside(filePath, tempDir)) {
+                res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end('Forbidden');
+                return;
+            }
+            if (!fs.existsSync(filePath)) {
+                res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end('File Not Found');
+                return;
+            }
+            const stat = fs.statSync(filePath);
+            if (!stat.isFile()) {
+                res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end('Not a File');
+                return;
+            }
+            res.writeHead(200, {
+                'Content-Type': 'application/zip',
+                'Content-Disposition': `attachment; filename="${path.basename(filePath)}"`,
+                'Content-Length': stat.size
+            });
+            fs.createReadStream(filePath).pipe(res);
         } else if (requestPath.startsWith('/res/')) {
             const normalized = path.normalize(requestPath).replace(/^([\\.\\/])+/, '');
             const filePath = path.join(__dirname, normalized);
@@ -5229,74 +6608,347 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
 
 // 打开 Web UI
 function cmdStart(options = {}) {
-    // Support both new src/ structure and legacy root structure for zero breaking changes
-    const webDirLegacy = path.join(__dirname, 'web-ui');
-    const webDirSrc = path.join(__dirname, 'src', 'web-ui');
-    const webDir = fs.existsSync(webDirSrc) ? webDirSrc : webDirLegacy;
+    const webDir = path.join(__dirname, 'web-ui');
     const newHtmlPath = path.join(webDir, 'index.html');
     const legacyHtmlPath = path.join(__dirname, 'web-ui.html');
-    const srcHtmlPath = path.join(__dirname, 'src', 'web-ui.html');
-    
-    let htmlPath = newHtmlPath;
-    if (!fs.existsSync(newHtmlPath)) {
-        htmlPath = fs.existsSync(srcHtmlPath) ? srcHtmlPath : legacyHtmlPath;
-    }
-    const assetsDirLegacy = path.join(__dirname, 'res');
-    const assetsDirSrc = path.join(__dirname, 'src', 'res');
-    const assetsDir = fs.existsSync(assetsDirSrc) ? assetsDirSrc : assetsDirLegacy;
+    const htmlPath = fs.existsSync(newHtmlPath) ? newHtmlPath : legacyHtmlPath;
+    const assetsDir = path.join(__dirname, 'res');
     if (!fs.existsSync(htmlPath)) {
         console.error('错误: Web UI 页面不存在（尝试路径: web-ui/index.html, web-ui.html）');
         process.exit(1);
     }
 
-    const port = resolveWebPort();
-    const host = resolveWebHost(options);
-
-    let serverHandle = createWebServer({
-        htmlPath,
-        assetsDir,
-        webDir,
-        host,
-        port,
-        openBrowser: true
-    });
+    const port = resolveWebPort();
+    const host = resolveWebHost(options);
+
+    let serverHandle = createWebServer({
+        htmlPath,
+        assetsDir,
+        webDir,
+        host,
+        port,
+        openBrowser: true
+    });
+
+    const proxySettings = readBuiltinProxySettings();
+    const shouldAutoStartProxy = proxySettings.enabled || hasCodexConfigReadyForProxy();
+    if (shouldAutoStartProxy) {
+        ensureBuiltinProxyForCodexDefault({
+            ...proxySettings,
+            switchToProxy: false
+        }).then((res) => {
+            if (res && res.success && res.runtime && res.runtime.listenUrl) {
+                const entryProvider = res.runtime.provider || DEFAULT_LOCAL_PROVIDER_NAME;
+                const upstreamLabel = res.runtime.upstreamProvider ? `（上游: ${res.runtime.upstreamProvider}）` : '';
+                console.log(`~ 内建代理已启动(${entryProvider}): ${res.runtime.listenUrl}${upstreamLabel}`);
+            } else if (res && res.error) {
+                console.warn(`! 内建代理启动失败: ${res.error}`);
+            }
+        }).catch((err) => {
+            console.warn(`! 内建代理启动失败: ${err && err.message ? err.message : err}`);
+        });
+    }
+
+    const stopWatch = watchPathsForRestart(
+        [webDir, legacyHtmlPath],
+        async (info) => {
+            const fileLabel = info && info.filename ? info.filename : (info && info.target ? path.basename(info.target) : 'unknown');
+            console.log(`\n~ 侦测到前端变更 (${fileLabel})，重启中...`);
+            console.log('  正在停止旧服务...');
+            try {
+                await serverHandle.stop();
+                console.log('  旧服务已停止');
+            } catch (e) {
+                console.warn('! 停止旧服务失败:', e.message || e);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 80));
+            try {
+                serverHandle = createWebServer({
+                    htmlPath,
+                    assetsDir,
+                    webDir,
+                    host,
+                    port,
+                    openBrowser: false
+                });
+                console.log('✓ 已重启 Web UI 服务\n');
+            } catch (e) {
+                console.error('! 重启失败:', e.message || e);
+            }
+        }
+    );
+
+    const handleExit = () => {
+        stopWatch();
+        Promise.allSettled([
+            serverHandle.stop(),
+            stopBuiltinProxyRuntime()
+        ]).finally(() => process.exit(0));
+    };
+
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
+}
+
+function cmdAuth(args = []) {
+    const subcommand = (args[0] || 'list').toLowerCase();
+
+    if (subcommand === 'list') {
+        const profiles = listAuthProfilesInfo();
+        if (profiles.length === 0) {
+            console.log('\n认证列表: (空)\n');
+            return;
+        }
+        console.log('\n认证列表:');
+        profiles.forEach((profile) => {
+            const marker = profile.current ? '●' : ' ';
+            const type = profile.type || 'unknown';
+            const email = profile.email || '(无邮箱)';
+            console.log(` ${marker} ${profile.name}  [${type}]  ${email}`);
+        });
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'status') {
+        const profiles = listAuthProfilesInfo();
+        const current = profiles.find((item) => item.current);
+        if (!current) {
+            console.log('\n当前认证: 未设置\n');
+            return;
+        }
+        console.log('\n当前认证:');
+        console.log('  名称:', current.name);
+        console.log('  类型:', current.type || 'unknown');
+        if (current.email) {
+            console.log('  账号:', current.email);
+        }
+        if (current.expired) {
+            console.log('  过期时间:', current.expired);
+        }
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'import' || subcommand === 'upload') {
+        const filePath = args[1];
+        const nameArg = args[2] && !args[2].startsWith('--') ? args[2] : '';
+        const noActivate = args.includes('--no-activate');
+        if (!filePath) {
+            throw new Error('用法: codexmate auth import <json文件路径> [名称] [--no-activate]');
+        }
+        const result = importAuthProfileFromFile(filePath, {
+            name: nameArg,
+            activate: !noActivate
+        });
+        console.log(`✓ 已导入认证: ${result.profile.name}`);
+        if (result.profile.email) {
+            console.log(`  账号: ${result.profile.email}`);
+        }
+        if (!noActivate) {
+            console.log('  已自动切换为当前认证');
+        }
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'switch' || subcommand === 'use') {
+        const name = args[1];
+        if (!name) {
+            throw new Error('用法: codexmate auth switch <名称>');
+        }
+        switchAuthProfile(name);
+        return;
+    }
+
+    if (subcommand === 'delete' || subcommand === 'remove') {
+        const name = args[1];
+        if (!name) {
+            throw new Error('用法: codexmate auth delete <名称>');
+        }
+        const result = deleteAuthProfile(name);
+        if (result.error) {
+            throw new Error(result.error);
+        }
+        console.log(`✓ 已删除认证: ${name}`);
+        if (result.switchedTo) {
+            console.log(`  已自动切换到: ${result.switchedTo}`);
+        }
+        console.log();
+        return;
+    }
+
+    throw new Error(`未知 auth 子命令: ${subcommand}`);
+}
+
+function parseProxyCliOptions(args = []) {
+    const payload = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--provider') {
+            payload.provider = args[i + 1] || '';
+            i += 1;
+            continue;
+        }
+        if (arg === '--host') {
+            payload.host = args[i + 1] || '';
+            i += 1;
+            continue;
+        }
+        if (arg === '--port') {
+            const raw = args[i + 1];
+            i += 1;
+            if (raw === undefined) {
+                return { error: '--port 缺少值' };
+            }
+            const port = parseInt(raw, 10);
+            if (!Number.isFinite(port)) {
+                return { error: '--port 必须是数字' };
+            }
+            payload.port = port;
+            continue;
+        }
+        if (arg === '--auth-source') {
+            payload.authSource = args[i + 1] || '';
+            i += 1;
+            continue;
+        }
+        if (arg === '--timeout-ms') {
+            const raw = args[i + 1];
+            i += 1;
+            if (raw === undefined) {
+                return { error: '--timeout-ms 缺少值' };
+            }
+            const timeoutMs = parseInt(raw, 10);
+            if (!Number.isFinite(timeoutMs)) {
+                return { error: '--timeout-ms 必须是数字' };
+            }
+            payload.timeoutMs = timeoutMs;
+            continue;
+        }
+        if (arg === '--enable') {
+            payload.enabled = true;
+            continue;
+        }
+        if (arg === '--disable') {
+            payload.enabled = false;
+            continue;
+        }
+        if (arg === '--no-switch') {
+            payload.switchToProxy = false;
+            continue;
+        }
+        return { error: `未知参数: ${arg}` };
+    }
+    return { payload };
+}
+
+async function cmdProxy(args = []) {
+    const subcommand = (args[0] || 'status').toLowerCase();
+    const optionResult = parseProxyCliOptions(args.slice(1));
+    if (optionResult.error) {
+        throw new Error(optionResult.error);
+    }
+    const options = optionResult.payload || {};
+
+    if (subcommand === 'status') {
+        const status = getBuiltinProxyStatus();
+        const settings = status.settings || DEFAULT_BUILTIN_PROXY_SETTINGS;
+        console.log('\n内建代理状态:');
+        console.log('  运行中:', status.running ? '是' : '否');
+        console.log('  启用:', settings.enabled ? '是' : '否');
+        console.log('  监听:', buildProxyListenUrl(settings));
+        console.log('  上游 provider:', settings.provider || '(自动)');
+        console.log('  鉴权来源:', settings.authSource);
+        if (status.runtime) {
+            console.log('  实际上游:', status.runtime.upstreamProvider);
+            console.log('  启动时间:', status.runtime.startedAt);
+        }
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'set' || subcommand === 'config') {
+        const result = saveBuiltinProxySettings(options);
+        if (result.error) {
+            throw new Error(result.error);
+        }
+        const settings = result.settings;
+        console.log('✓ 内建代理配置已保存');
+        console.log('  监听:', buildProxyListenUrl(settings));
+        console.log('  上游 provider:', settings.provider || '(自动)');
+        console.log('  鉴权来源:', settings.authSource);
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'apply' || subcommand === 'apply-provider') {
+        const result = applyBuiltinProxyProvider({
+            switchToProxy: options.switchToProxy !== false
+        });
+        if (result.error) {
+            throw new Error(result.error);
+        }
+        console.log(`✓ 已写入本地代理 provider: ${result.provider}`);
+        console.log(`  URL: ${result.baseUrl}`);
+        if (result.switched) {
+            console.log(`  已切换到 ${result.provider}${result.model ? ` / ${result.model}` : ''}`);
+        }
+        console.log();
+        return;
+    }
 
-    const stopWatch = watchPathsForRestart(
-        [webDir, path.join(__dirname, 'web-ui.html'), path.join(__dirname, 'src', 'web-ui.html')],
-        async (info) => {
-            const fileLabel = info && info.filename ? info.filename : (info && info.target ? path.basename(info.target) : 'unknown');
-            console.log(`\n~ 侦测到前端变更 (${fileLabel})，重启中...`);
-            console.log('  正在停止旧服务...');
-            try {
-                await serverHandle.stop();
-                console.log('  旧服务已停止');
-            } catch (e) {
-                console.warn('! 停止旧服务失败:', e.message || e);
-            }
-            await new Promise((resolve) => setTimeout(resolve, 80));
-            try {
-                serverHandle = createWebServer({
-                    htmlPath,
-                    assetsDir,
-                    webDir,
-                    host,
-                    port,
-                    openBrowser: false
-                });
-                console.log('✓ 已重启 Web UI 服务\n');
-            } catch (e) {
-                console.error('! 重启失败:', e.message || e);
-            }
+    if (subcommand === 'enable' || subcommand === 'default-codex') {
+        const result = await ensureBuiltinProxyForCodexDefault(options);
+        if (result.error) {
+            throw new Error(result.error);
         }
-    );
+        const listenUrl = result.runtime && result.runtime.listenUrl
+            ? result.runtime.listenUrl
+            : buildProxyListenUrl(result.settings || DEFAULT_BUILTIN_PROXY_SETTINGS);
+        console.log('✓ 已启用 Codex 内建代理默认模式');
+        console.log(`  监听: ${listenUrl}`);
+        if (result.runtime && result.runtime.upstreamProvider) {
+            console.log(`  上游 provider: ${result.runtime.upstreamProvider}`);
+        }
+        console.log(`  当前 provider: ${result.provider}${result.model ? ` / ${result.model}` : ''}`);
+        console.log();
+        return;
+    }
 
-    const handleExit = () => {
-        stopWatch();
-        serverHandle.stop().then(() => process.exit(0));
-    };
+    if (subcommand === 'start') {
+        const result = await startBuiltinProxyRuntime({
+            ...options,
+            enabled: true
+        });
+        if (result.error) {
+            throw new Error(result.error);
+        }
+        console.log(`✓ 内建代理已启动: ${result.listenUrl}`);
+        console.log(`  上游 provider: ${result.upstreamProvider}`);
+        console.log('  按 Ctrl+C 停止代理\n');
+
+        await new Promise((resolve) => {
+            let stopping = false;
+            const gracefulStop = async () => {
+                if (stopping) return;
+                stopping = true;
+                await stopBuiltinProxyRuntime();
+                resolve();
+            };
+            process.once('SIGINT', gracefulStop);
+            process.once('SIGTERM', gracefulStop);
+        });
+        return;
+    }
 
-    process.on('SIGINT', handleExit);
-    process.on('SIGTERM', handleExit);
+    if (subcommand === 'stop') {
+        await stopBuiltinProxyRuntime();
+        console.log('✓ 内建代理已停止\n');
+        return;
+    }
+
+    throw new Error(`未知 proxy 子命令: ${subcommand}`);
 }
 
 async function runProxyCommand(displayName, binNames, args = [], installTip = '') {
@@ -5354,6 +7006,16 @@ async function runProxyCommand(displayName, binNames, args = [], installTip = ''
 }
 
 async function cmdCodex(args = []) {
+    const ensureResult = await ensureBuiltinProxyForCodexDefault({});
+    if (!ensureResult || ensureResult.success !== true) {
+        const message = ensureResult && ensureResult.error
+            ? ensureResult.error
+            : '内建代理准备失败';
+        throw new Error(message);
+    }
+    if (ensureResult.runtime && ensureResult.runtime.listenUrl) {
+        console.log(`~ Codex 默认走内建代理: ${ensureResult.runtime.listenUrl}`);
+    }
     return runProxyCommand('Codex', 'codex', args);
 }
 
@@ -5365,16 +7027,783 @@ async function cmdGemini(args = []) {
     return runProxyCommand('Gemini', ['gemini', 'gemini-cli'], args, 'npm install -g @google/gemini-cli');
 }
 
+function parseMcpOptions(args = []) {
+    const options = {
+        subcommand: 'serve',
+        transport: 'stdio',
+        allowWrite: false,
+        help: false
+    };
+
+    const argv = Array.isArray(args) ? [...args] : [];
+    if (argv.length > 0 && !argv[0].startsWith('-')) {
+        options.subcommand = String(argv.shift() || '').trim().toLowerCase() || 'serve';
+    }
+
+    const envAllowWrite = typeof process.env.CODEXMATE_MCP_ALLOW_WRITE === 'string'
+        && ['1', 'true', 'yes', 'on'].includes(process.env.CODEXMATE_MCP_ALLOW_WRITE.trim().toLowerCase());
+    options.allowWrite = envAllowWrite;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg) continue;
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (arg === '--allow-write' || arg === '--allow-write-tools') {
+            options.allowWrite = true;
+            continue;
+        }
+        if (arg === '--read-only') {
+            options.allowWrite = false;
+            continue;
+        }
+        if (arg.startsWith('--transport=')) {
+            options.transport = arg.slice('--transport='.length).trim().toLowerCase() || options.transport;
+            continue;
+        }
+        if (arg === '--transport') {
+            options.transport = String(argv[i + 1] || '').trim().toLowerCase() || options.transport;
+            i += 1;
+            continue;
+        }
+    }
+
+    return options;
+}
+
+function toMcpToolResult(payload) {
+    const structured = payload === undefined
+        ? {}
+        : (payload && typeof payload === 'object' ? payload : { value: payload });
+    const hasError = !!(structured && typeof structured === 'object' && (
+        (typeof structured.error === 'string' && structured.error.trim())
+        || structured.success === false
+    ));
+    const text = JSON.stringify(structured, null, 2);
+    const result = {
+        content: [{ type: 'text', text }],
+        structuredContent: structured
+    };
+    if (hasError) {
+        result.isError = true;
+    }
+    return result;
+}
+
+function buildMcpStatusPayload() {
+    const statusConfigResult = readConfigOrVirtualDefault();
+    const config = statusConfigResult.config;
+    const serviceTier = typeof config.service_tier === 'string' ? config.service_tier.trim() : '';
+    const modelReasoningEffort = typeof config.model_reasoning_effort === 'string' ? config.model_reasoning_effort.trim() : '';
+    return {
+        provider: config.model_provider || '未设置',
+        model: config.model || '未设置',
+        serviceTier,
+        modelReasoningEffort,
+        configReady: !statusConfigResult.isVirtual,
+        configNotice: statusConfigResult.reason || '',
+        initNotice: consumeInitNotice()
+    };
+}
+
+function buildMcpProviderListPayload() {
+    const listConfigResult = readConfigOrVirtualDefault();
+    const listConfig = listConfigResult.config;
+    const providers = listConfig.model_providers || {};
+    const current = listConfig.model_provider;
+    return {
+        configReady: !listConfigResult.isVirtual,
+        providers: Object.entries(providers).map(([name, p]) => ({
+            name,
+            url: p.base_url || '',
+            key: maskKey(p.preferred_auth_method || ''),
+            hasKey: !!(p.preferred_auth_method && p.preferred_auth_method.trim()),
+            current: name === current,
+            readOnly: isBuiltinProxyProvider(name),
+            nonDeletable: isNonDeletableProvider(name),
+            nonEditable: isNonEditableProvider(name)
+        }))
+    };
+}
+
+function buildMcpClaudeSettingsPayload() {
+    const info = readClaudeSettingsInfo();
+    if (!info || typeof info !== 'object') {
+        return { error: '读取 Claude 配置失败' };
+    }
+    if (info.error) {
+        return info;
+    }
+
+    const apiKey = typeof info.apiKey === 'string' ? info.apiKey : '';
+    const baseUrl = typeof info.baseUrl === 'string' ? info.baseUrl : '';
+    const model = typeof info.model === 'string' ? info.model : '';
+    const maskedApiKey = maskKey(apiKey);
+
+    return {
+        exists: !!info.exists,
+        targetPath: info.targetPath || CLAUDE_SETTINGS_FILE,
+        apiKey: maskedApiKey,
+        apiKeyMasked: maskedApiKey,
+        baseUrl,
+        model,
+        env: {
+            ANTHROPIC_API_KEY: maskedApiKey,
+            ANTHROPIC_BASE_URL: baseUrl,
+            ANTHROPIC_MODEL: model
+        },
+        redacted: true
+    };
+}
+
+function normalizeMcpSource(value) {
+    const source = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (!source) return '';
+    if (source === 'codex' || source === 'claude' || source === 'all') {
+        return source;
+    }
+    return null;
+}
+
+function createMcpTools(options = {}) {
+    const allowWrite = !!options.allowWrite;
+    const tools = [];
+
+    const pushTool = (tool) => {
+        if (!tool || typeof tool !== 'object') return;
+        if (!tool.readOnly && !allowWrite) return;
+        tools.push({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema || { type: 'object', properties: {}, additionalProperties: false },
+            annotations: {
+                readOnlyHint: !!tool.readOnly
+            },
+            handler: async (args = {}) => {
+                try {
+                    const payload = await tool.handler(args || {});
+                    return toMcpToolResult(payload);
+                } catch (error) {
+                    return toMcpToolResult({
+                        error: error && error.message ? error.message : String(error || 'Tool execution failed')
+                    });
+                }
+            }
+        });
+    };
+
+    pushTool({
+        name: 'codexmate.status.get',
+        description: 'Get current provider/model status, config readiness and startup notice.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => buildMcpStatusPayload()
+    });
+
+    pushTool({
+        name: 'codexmate.provider.list',
+        description: 'List configured providers with masked key and active flags.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => buildMcpProviderListPayload()
+    });
+
+    pushTool({
+        name: 'codexmate.model.list',
+        description: 'List models from a provider. If provider is omitted, use current provider.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                provider: { type: 'string' }
+            },
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const rawProvider = typeof args.provider === 'string' ? args.provider.trim() : '';
+            let providerName = rawProvider;
+            if (!providerName) {
+                const cfg = readConfigOrVirtualDefault().config || {};
+                providerName = typeof cfg.model_provider === 'string' ? cfg.model_provider.trim() : '';
+            }
+            if (!providerName) {
+                return { error: 'Provider name is required' };
+            }
+            const res = await fetchProviderModels(providerName);
+            if (res.error) {
+                return { error: res.error, models: [], source: 'remote' };
+            }
+            if (res.unlimited) {
+                return { models: [], source: 'remote', provider: res.provider || '', unlimited: true };
+            }
+            return { models: res.models || [], source: 'remote', provider: res.provider || '' };
+        }
+    });
+
+    pushTool({
+        name: 'codexmate.config.template.get',
+        description: 'Get Codex config template with optional provider/model/service tier/reasoning effort.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                provider: { type: 'string' },
+                model: { type: 'string' },
+                serviceTier: { type: 'string' },
+                reasoningEffort: { type: 'string' }
+            },
+            additionalProperties: false
+        },
+        handler: async (args = {}) => getConfigTemplate(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.claude.settings.get',
+        description: 'Read Claude settings.json env values managed by codexmate.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => buildMcpClaudeSettingsPayload()
+    });
+
+    pushTool({
+        name: 'codexmate.openclaw.config.get',
+        description: 'Read OpenClaw config file content and metadata.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => readOpenclawConfigFile()
+    });
+
+    pushTool({
+        name: 'codexmate.session.list',
+        description: 'List sessions from codex/claude/all with filters.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                pathFilter: { type: 'string' },
+                query: { type: 'string' },
+                roleFilter: { type: 'string' },
+                timeRangePreset: { type: 'string' },
+                limit: { type: 'number' },
+                forceRefresh: { type: 'boolean' },
+                queryMode: { type: 'string' },
+                queryScope: { type: 'string' },
+                contentScanLimit: { type: 'number' }
+            },
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const input = args && typeof args === 'object' ? args : {};
+            const source = normalizeMcpSource(input.source);
+            if (source === null) {
+                return { error: 'Invalid source. Must be codex, claude, or all' };
+            }
+            const normalizedInput = {
+                ...input,
+                source: source || 'all'
+            };
+            return {
+                sessions: listAllSessions(normalizedInput),
+                source: source || 'all'
+            };
+        }
+    });
+
+    pushTool({
+        name: 'codexmate.session.detail',
+        description: 'Read a session detail by source + sessionId/file.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                sessionId: { type: 'string' },
+                file: { type: 'string' },
+                maxMessages: { type: ['string', 'number'] }
+            },
+            additionalProperties: true
+        },
+        handler: async (args = {}) => readSessionDetail(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.session.export',
+        description: 'Export session as markdown payload.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                sessionId: { type: 'string' },
+                file: { type: 'string' },
+                maxMessages: { type: ['string', 'number'] }
+            },
+            additionalProperties: true
+        },
+        handler: async (args = {}) => exportSessionData(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.auth.profile.list',
+        description: 'List codex auth profiles.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => ({ profiles: listAuthProfilesInfo() })
+    });
+
+    pushTool({
+        name: 'codexmate.proxy.status',
+        description: 'Get builtin proxy runtime status and persisted config.',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => getBuiltinProxyStatus()
+    });
+
+    pushTool({
+        name: 'codexmate.config.template.apply',
+        description: 'Apply Codex TOML template and sync auth/model pointers.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                template: { type: 'string' }
+            },
+            required: ['template'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => applyConfigTemplate(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.provider.add',
+        description: 'Add provider into config.toml model_providers.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                url: { type: 'string' },
+                key: { type: 'string' }
+            },
+            required: ['name', 'url'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => addProviderToConfig(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.provider.update',
+        description: 'Update provider url/key.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                url: { type: 'string' },
+                key: { type: 'string' }
+            },
+            required: ['name'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => updateProviderInConfig(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.provider.delete',
+        description: 'Delete provider from config.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' }
+            },
+            required: ['name'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => deleteProviderFromConfig(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.claude.config.apply',
+        description: 'Apply Claude env config into ~/.claude/settings.json.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apiKey: { type: 'string' },
+                baseUrl: { type: 'string' },
+                model: { type: 'string' }
+            },
+            required: ['apiKey'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => applyToClaudeSettings(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.openclaw.config.apply',
+        description: 'Apply OpenClaw config content into ~/.openclaw/openclaw.json.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: { type: 'string' },
+                lineEnding: { type: 'string' }
+            },
+            required: ['content'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => applyOpenclawConfig(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.session.delete',
+        description: 'Delete one session or selected records in a session.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                sessionId: { type: 'string' },
+                file: { type: 'string' },
+                recordLineIndex: { type: 'number' },
+                recordLineIndices: { type: 'array', items: { type: 'number' } }
+            },
+            additionalProperties: true
+        },
+        handler: async (args = {}) => deleteSessionData(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.auth.profile.switch',
+        description: 'Switch active auth profile by name.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' }
+            },
+            required: ['name'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const profileName = typeof args.name === 'string' ? args.name.trim() : '';
+            if (!profileName) return { error: '认证名称不能为空' };
+            try {
+                return switchAuthProfile(profileName, { silent: true });
+            } catch (e) {
+                return { error: e.message || '切换认证失败' };
+            }
+        }
+    });
+
+    pushTool({
+        name: 'codexmate.auth.profile.delete',
+        description: 'Delete an auth profile by name.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' }
+            },
+            required: ['name'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => deleteAuthProfile(typeof args.name === 'string' ? args.name : '')
+    });
+
+    pushTool({
+        name: 'codexmate.proxy.start',
+        description: 'Start builtin proxy runtime with optional overrides.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                enabled: { type: 'boolean' },
+                host: { type: 'string' },
+                port: { type: 'number' },
+                provider: { type: 'string' },
+                authSource: { type: 'string' },
+                timeoutMs: { type: 'number' }
+            },
+            additionalProperties: false
+        },
+        handler: async (args = {}) => startBuiltinProxyRuntime(args || {})
+    });
+
+    pushTool({
+        name: 'codexmate.proxy.stop',
+        description: 'Stop builtin proxy runtime.',
+        readOnly: false,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => stopBuiltinProxyRuntime()
+    });
+
+    pushTool({
+        name: 'codexmate.proxy.provider.apply',
+        description: 'Apply builtin proxy provider into codex config.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                switchToProxy: { type: 'boolean' },
+                provider: { type: 'string' }
+            },
+            additionalProperties: true
+        },
+        handler: async (args = {}) => applyBuiltinProxyProvider(args || {})
+    });
+
+    return tools;
+}
+
+function createMcpResources() {
+    return [
+        {
+            uri: 'codexmate://status',
+            name: 'Status',
+            description: 'Current provider/model status snapshot.',
+            mimeType: 'application/json',
+            read: async () => ({
+                contents: [{
+                    uri: 'codexmate://status',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(buildMcpStatusPayload(), null, 2)
+                }]
+            })
+        },
+        {
+            uri: 'codexmate://providers',
+            name: 'Providers',
+            description: 'Configured provider list (masked).',
+            mimeType: 'application/json',
+            read: async () => ({
+                contents: [{
+                    uri: 'codexmate://providers',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(buildMcpProviderListPayload(), null, 2)
+                }]
+            })
+        },
+        {
+            uri: 'codexmate://sessions',
+            name: 'Sessions',
+            description: 'Session listing resource. Query by source/query/pathFilter via URI params.',
+            mimeType: 'application/json',
+            read: async (params = {}) => {
+                const uri = typeof params.uri === 'string' ? params.uri : 'codexmate://sessions';
+                let source = '';
+                let query = '';
+                let pathFilter = '';
+                let roleFilter = '';
+                let timeRangePreset = '';
+                try {
+                    const parsed = new URL(uri);
+                    source = parsed.searchParams.get('source') || '';
+                    query = parsed.searchParams.get('query') || '';
+                    pathFilter = parsed.searchParams.get('pathFilter') || '';
+                    roleFilter = parsed.searchParams.get('roleFilter') || '';
+                    timeRangePreset = parsed.searchParams.get('timeRangePreset') || '';
+                } catch (_) {}
+                const normalizedSource = normalizeMcpSource(source);
+                if (normalizedSource === null) {
+                    return {
+                        contents: [{
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify({ error: 'Invalid source. Must be codex, claude, or all' }, null, 2)
+                        }]
+                    };
+                }
+                const payload = {
+                    source: normalizedSource || 'all',
+                    sessions: listAllSessions({
+                        source: normalizedSource || 'all',
+                        query,
+                        pathFilter,
+                        roleFilter,
+                        timeRangePreset
+                    })
+                };
+                return {
+                    contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(payload, null, 2)
+                    }]
+                };
+            }
+        }
+    ];
+}
+
+function createMcpPrompts() {
+    return [
+        {
+            name: 'codexmate.diagnose_config',
+            description: 'Generate troubleshooting guidance from current codexmate status/providers.',
+            arguments: [],
+            get: async () => {
+                const status = buildMcpStatusPayload();
+                const providers = buildMcpProviderListPayload();
+                return {
+                    messages: [{
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                '请根据以下配置快照进行故障诊断，并给出按优先级排序的修复步骤。',
+                                '要求：先给结论，再给操作清单，最后给风险与回滚建议。',
+                                '',
+                                '[status]',
+                                JSON.stringify(status, null, 2),
+                                '',
+                                '[providers]',
+                                JSON.stringify(providers, null, 2)
+                            ].join('\n')
+                        }
+                    }]
+                };
+            }
+        },
+        {
+            name: 'codexmate.switch_provider_safely',
+            description: 'Guide safe provider switch with pre-check and rollback plan.',
+            arguments: [{
+                name: 'provider',
+                description: 'Target provider name',
+                required: true
+            }],
+            get: async (args = {}) => {
+                const provider = typeof args.provider === 'string' ? args.provider.trim() : '';
+                return {
+                    messages: [{
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                `请为 provider "${provider || '(missing)'}" 生成安全切换步骤。`,
+                                '要求：',
+                                '1) 先检查 provider 是否存在与 key 是否可用',
+                                '2) 给出切换后验证项（模型拉取/健康检查）',
+                                '3) 给出失败时回滚流程（回到旧 provider/model）'
+                            ].join('\n')
+                        }
+                    }]
+                };
+            }
+        },
+        {
+            name: 'codexmate.export_session_for_issue',
+            description: 'Prepare issue report template from a selected session export.',
+            arguments: [{
+                name: 'source',
+                description: 'Session source: codex or claude',
+                required: true
+            }, {
+                name: 'sessionId',
+                description: 'Session id',
+                required: true
+            }],
+            get: async (args = {}) => {
+                const source = typeof args.source === 'string' ? args.source.trim() : '';
+                const sessionId = typeof args.sessionId === 'string' ? args.sessionId.trim() : '';
+                return {
+                    messages: [{
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: [
+                                '请根据会话导出内容生成 issue 报告草稿。',
+                                `source: ${source || '(missing)'}`,
+                                `sessionId: ${sessionId || '(missing)'}`,
+                                '',
+                                '报告需包含：问题现象、复现步骤、预期行为、实际行为、可疑配置项。'
+                            ].join('\n')
+                        }
+                    }]
+                };
+            }
+        }
+    ];
+}
+
+async function cmdMcp(args = []) {
+    const options = parseMcpOptions(args);
+    if (options.help) {
+        console.log('\n用法: codexmate mcp [serve] [--transport stdio] [--allow-write|--read-only]');
+        console.log('  默认 transport=stdio，默认 read-only。');
+        console.log('  设置环境变量 CODEXMATE_MCP_ALLOW_WRITE=1 可默认开启写工具。');
+        console.log();
+        return;
+    }
+
+    if (options.subcommand !== 'serve') {
+        throw new Error(`未知 mcp 子命令: ${options.subcommand}`);
+    }
+    if (options.transport !== 'stdio') {
+        throw new Error(`当前仅支持 stdio 传输，收到: ${options.transport}`);
+    }
+
+    const packageVersion = (() => {
+        try {
+            const pkg = require('./package.json');
+            return pkg && pkg.version ? pkg.version : '0.0.0';
+        } catch (_) {
+            return '0.0.0';
+        }
+    })();
+
+    const server = createMcpStdioServer({
+        protocolVersion: '2025-11-25',
+        serverInfo: {
+            name: 'codexmate-mcp',
+            version: packageVersion
+        },
+        tools: createMcpTools({ allowWrite: options.allowWrite }),
+        resources: createMcpResources(),
+        prompts: createMcpPrompts(),
+        logger: (level, message) => {
+            const label = level === 'error' ? 'ERR' : 'INFO';
+            console.error(`[MCP ${label}] ${message}`);
+        }
+    });
+
+    server.start();
+
+    await new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done) return;
+            done = true;
+            server.stop();
+            stopBuiltinProxyRuntime().finally(() => resolve());
+        };
+        process.once('SIGINT', finish);
+        process.once('SIGTERM', finish);
+        process.stdin.once('end', finish);
+        process.stdin.once('close', finish);
+    });
+}
+
 // ============================================================================
 // 主程序
 // ============================================================================
 async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const isMcpCommand = command === 'mcp';
     const bootstrap = ensureManagedConfigBootstrap();
     if (bootstrap && bootstrap.notice) {
-        console.log(`\n[Init] ${bootstrap.notice}`);
+        // MCP stdio transport requires stdout to be protocol-clean.
+        if (!isMcpCommand) {
+            console.log(`\n[Init] ${bootstrap.notice}`);
+        }
     }
 
-    const args = process.argv.slice(2);
     if (args.length === 0) {
         console.log('\nCodex Mate - Codex 提供商管理工具');
         console.log('\n用法:');
@@ -5389,19 +7818,20 @@ async function main() {
         console.log('  codexmate claude <BaseURL> <API密钥> [模型]  写入 Claude Code 配置');
         console.log('  codexmate add-model <模型> 添加模型');
         console.log('  codexmate delete-model <模型> 删除模型');
+        console.log('  codexmate auth <list|import|switch|delete|status>  认证文件管理');
+        console.log('  codexmate proxy <status|set|apply|enable|start|stop>  内建代理');
         console.log('  codexmate run [--host <HOST>]    启动 Web 界面');
         console.log('  codexmate codex [参数...]  等同于 codex --yolo');
         console.log('  codexmate qwen [参数...]   等同于 qwen --yolo');
         console.log('  codexmate gemini [参数...] 等同于 gemini --yolo');
+        console.log('  codexmate mcp [serve] [--transport stdio] [--allow-write|--read-only]');
         console.log('  codexmate export-session --source <codex|claude> (--session-id <ID>|--file <PATH>) [--output <PATH>] [--max-messages <N|all|Infinity>]');
-        console.log('  codexmate zip <路径> [--max:级别]  压缩（7-Zip 优先）');
-        console.log('  codexmate unzip <zip文件> [输出目录]  解压（7-Zip 优先）');
+        console.log('  codexmate zip <路径> [--max:级别]  压缩（系统 zip 优先，其次 zip-lib）');
+        console.log('  codexmate unzip <zip文件> [输出目录]  解压（zip-lib）');
         console.log('');
         process.exit(0);
     }
 
-    const command = args[0];
-
     switch (command) {
         case 'status': cmdStatus(); break;
         case 'setup': await cmdSetup(); break;
@@ -5414,6 +7844,8 @@ async function main() {
         case 'claude': cmdClaude(args[1], args[2], args[3]); break;
         case 'add-model': cmdAddModel(args[1]); break;
         case 'delete-model': cmdDeleteModel(args[1]); break;
+        case 'auth': cmdAuth(args.slice(1)); break;
+        case 'proxy': await cmdProxy(args.slice(1)); break;
         case 'run': cmdStart(parseStartOptions(args.slice(1))); break;
         case 'start':
             console.error('错误: 命令已更名为 "run"，请使用: codexmate run');
@@ -5434,6 +7866,7 @@ async function main() {
             process.exit(exitCode);
             break;
         }
+        case 'mcp': await cmdMcp(args.slice(1)); break;
         case 'export-session': await cmdExportSession(args.slice(1)); break;
         case 'zip': {
             // 解析 --max:N 参数