fix(proxy): resolve merge conflict in claude adapter — combine smart URL path detection with beta=true

Merge both features from feat/smart-url-path-detection and main: - Smart URL path detection: skip appending endpoint when base_url already ends with API path - URL suffix preservation: preserve query/fragment from base_url via split_url_suffix - v1 dedup: boundary-safe deduplication of /v1/v1 - ?beta=true: auto-append for /v1/messages endpoints (DuckCoding compatibility) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
fix(proxy): unify proxy requirement check to backend and add OpenClaw support
2026-04-28 05:33:10 +08:00 · 2026-02-20 18:09:05 +08:00 · 2026-02-15 14:07:46 +08:00 · 2026-02-15 13:48:28 +08:00 · 2026-02-12 23:00:46 +08:00 · 2026-02-12 14:49:51 +08:00
28 changed files with 1281 additions and 176 deletions
--- a/src-tauri/src/commands/proxy.rs
+++ b/src-tauri/src/commands/proxy.rs
@@ -407,3 +407,43 @@ pub async fn get_circuit_breaker_stats(
    let _ = (state, provider_id, app_type);
    Ok(None)
 }
+
+// ==================== URL 预览相关命令 ====================
+
+use crate::app_config::AppType;
+use crate::proxy::url_builder::{self, UrlPreview};
+
+/// 构建 URL 预览
+///
+/// 根据 app_type、base_url 和 api_format 计算直连和代理模式的请求地址。
+/// 这个命令与后端代理的 URL 构建逻辑保持一致。
+#[tauri::command]
+pub fn build_url_preview(
+    app_type: String,
+    base_url: String,
+    api_format: Option<String>,
+) -> Result<UrlPreview, String> {
+    let app = app_type.parse::<AppType>().map_err(|e| e.to_string())?;
+    Ok(url_builder::build_url_preview(
+        &app,
+        &base_url,
+        api_format.as_deref(),
+    ))
+}
+
+/// 检查是否需要代理
+///
+/// 返回需要代理的原因（openai_chat_format, full_url, url_mismatch），
+/// 或 null 表示不需要代理。
+#[tauri::command]
+pub fn check_proxy_requirement(
+    app_type: String,
+    base_url: String,
+    api_format: Option<String>,
+) -> Result<Option<String>, String> {
+    let app = app_type.parse::<AppType>().map_err(|e| e.to_string())?;
+    Ok(
+        url_builder::check_proxy_requirement(&app, &base_url, api_format.as_deref())
+            .map(|s| s.to_string()),
+    )
+}
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -971,6 +971,9 @@ pub fn run() {
            commands::get_circuit_breaker_config,
            commands::update_circuit_breaker_config,
            commands::get_circuit_breaker_stats,
+            // URL preview (for endpoint field)
+            commands::build_url_preview,
+            commands::check_proxy_requirement,
            // Failover queue management
            commands::get_failover_queue,
            commands::get_available_providers_for_failover,
--- a/src-tauri/src/proxy/forwarder.rs
+++ b/src-tauri/src/proxy/forwarder.rs
@@ -749,15 +749,17 @@ impl RequestForwarder {
        // 检查是否需要格式转换
        let needs_transform = adapter.needs_transform(provider);

-        let effective_endpoint =
-            if needs_transform && adapter.name() == "Claude" && endpoint == "/v1/messages" {
-                "/v1/chat/completions"
-            } else {
-                endpoint
-            };
+        let effective_endpoint = if needs_transform
+            && adapter.name() == "Claude"
+            && endpoint.starts_with("/v1/messages")
+        {
+            transform_claude_messages_endpoint(endpoint)
+        } else {
+            endpoint.to_string()
+        };

        // 使用适配器构建 URL
-        let url = adapter.build_url(&base_url, effective_endpoint);
+        let url = adapter.build_url(&base_url, &effective_endpoint);

        // 应用模型映射（独立于格式转换）
        let (mapped_body, _original_model, _mapped_model) =
@@ -927,3 +929,57 @@ fn extract_error_message(error: &ProxyError) -> Option<String> {
        _ => Some(error.to_string()),
    }
 }
+
+fn transform_claude_messages_endpoint(endpoint: &str) -> String {
+    let transformed = endpoint.replacen("/v1/messages", "/v1/chat/completions", 1);
+
+    let Some((path, query)) = transformed.split_once('?') else {
+        return transformed;
+    };
+
+    // 转换到 chat/completions 时，显式移除 beta=true，避免把旧接口参数带到新接口。
+    let filtered_params: Vec<&str> = query
+        .split('&')
+        .filter(|segment| !segment.is_empty())
+        .filter(|segment| !is_beta_true_query_pair(segment))
+        .collect();
+
+    if filtered_params.is_empty() {
+        path.to_string()
+    } else {
+        format!("{path}?{}", filtered_params.join("&"))
+    }
+}
+
+fn is_beta_true_query_pair(segment: &str) -> bool {
+    let Some((key, value)) = segment.split_once('=') else {
+        return false;
+    };
+    key.eq_ignore_ascii_case("beta") && value.eq_ignore_ascii_case("true")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::transform_claude_messages_endpoint;
+
+    #[test]
+    fn transform_claude_messages_endpoint_strips_beta_true_only() {
+        let endpoint = "/v1/messages?beta=true&foo=1";
+        let transformed = transform_claude_messages_endpoint(endpoint);
+        assert_eq!(transformed, "/v1/chat/completions?foo=1");
+    }
+
+    #[test]
+    fn transform_claude_messages_endpoint_drops_empty_query_after_strip() {
+        let endpoint = "/v1/messages?beta=true";
+        let transformed = transform_claude_messages_endpoint(endpoint);
+        assert_eq!(transformed, "/v1/chat/completions");
+    }
+
+    #[test]
+    fn transform_claude_messages_endpoint_keeps_other_query_values() {
+        let endpoint = "/v1/messages?beta=false&foo=1";
+        let transformed = transform_claude_messages_endpoint(endpoint);
+        assert_eq!(transformed, "/v1/chat/completions?beta=false&foo=1");
+    }
+}
--- a/src-tauri/src/proxy/handler_config.rs
+++ b/src-tauri/src/proxy/handler_config.rs
@@ -42,22 +42,6 @@ fn claude_model_extractor(events: &[Value], request_model: &str) -> String {
    request_model.to_string()
 }

-/// OpenAI Chat Completions 流式响应模型提取（优先使用 usage.model）
-fn openai_model_extractor(events: &[Value], request_model: &str) -> String {
-    // 首先尝试从解析的 usage 中获取模型
-    if let Some(usage) = TokenUsage::from_openai_stream_events(events) {
-        if let Some(model) = usage.model {
-            return model;
-        }
-    }
-    // 回退：从事件中直接提取
-    events
-        .iter()
-        .find_map(|e| e.get("model")?.as_str())
-        .unwrap_or(request_model)
-        .to_string()
-}
-
 /// Codex 智能流式响应模型提取（自动检测格式）
 fn codex_auto_model_extractor(events: &[Value], request_model: &str) -> String {
    // 首先尝试从解析的 usage 中获取模型
@@ -107,14 +91,6 @@ pub const CLAUDE_PARSER_CONFIG: UsageParserConfig = UsageParserConfig {
    app_type_str: "claude",
 };

-/// OpenAI Chat Completions API 解析配置（用于 Codex /v1/chat/completions）
-pub const OPENAI_PARSER_CONFIG: UsageParserConfig = UsageParserConfig {
-    stream_parser: TokenUsage::from_openai_stream_events,
-    response_parser: TokenUsage::from_openai_response,
-    model_extractor: openai_model_extractor,
-    app_type_str: "codex",
-};
-
 /// Codex 智能解析配置（自动检测 OpenAI 或 Codex 格式）
 pub const CODEX_PARSER_CONFIG: UsageParserConfig = UsageParserConfig {
    stream_parser: TokenUsage::from_codex_stream_events_auto,
@@ -160,15 +136,6 @@ pub const CLAUDE_HANDLER_CONFIG: HandlerConfig = HandlerConfig {
    parser_config: &CLAUDE_PARSER_CONFIG,
 };

-/// Codex Chat Completions Handler 配置
-#[allow(dead_code)]
-pub const CODEX_CHAT_HANDLER_CONFIG: HandlerConfig = HandlerConfig {
-    app_type: AppType::Codex,
-    tag: "Codex",
-    app_type_str: "codex",
-    parser_config: &OPENAI_PARSER_CONFIG,
-};
-
 /// Codex Responses Handler 配置
 #[allow(dead_code)]
 pub const CODEX_RESPONSES_HANDLER_CONFIG: HandlerConfig = HandlerConfig {
--- a/src-tauri/src/proxy/handlers.rs
+++ b/src-tauri/src/proxy/handlers.rs
@@ -9,9 +9,7 @@

 use super::{
    error_mapper::{get_error_message, map_proxy_error_to_status},
-    handler_config::{
-        CLAUDE_PARSER_CONFIG, CODEX_PARSER_CONFIG, GEMINI_PARSER_CONFIG, OPENAI_PARSER_CONFIG,
-    },
+    handler_config::{CLAUDE_PARSER_CONFIG, CODEX_PARSER_CONFIG, GEMINI_PARSER_CONFIG},
    handler_context::RequestContext,
    providers::{get_adapter, streaming::create_anthropic_sse_stream, transform},
    response_processor::{create_logged_passthrough_stream, process_response, SseUsageCollector},
@@ -56,6 +54,7 @@ pub async fn get_status(State(state): State<ProxyState>) -> Result<Json<ProxySta
 /// - 现在 OpenRouter 已推出 Claude Code 兼容接口，默认不再启用该转换（逻辑保留以备回退）
 pub async fn handle_messages(
    State(state): State<ProxyState>,
+    uri: axum::http::Uri,
    headers: axum::http::HeaderMap,
    Json(body): Json<Value>,
 ) -> Result<axum::response::Response, ProxyError> {
@@ -67,12 +66,18 @@ pub async fn handle_messages(
        .and_then(|s| s.as_bool())
        .unwrap_or(false);

+    // 透传客户端 query 参数（例如 ?beta=true），路径统一为 /v1/messages
+    let endpoint = uri
+        .query()
+        .map(|q| format!("/v1/messages?{q}"))
+        .unwrap_or_else(|| "/v1/messages".to_string());
+
    // 转发请求
    let forwarder = ctx.create_forwarder(&state);
    let result = match forwarder
        .forward_with_retry(
            &AppType::Claude,
-            "/v1/messages",
+            &endpoint,
            body.clone(),
            headers,
            ctx.get_providers(),
@@ -266,47 +271,6 @@ async fn handle_claude_transform(
 // Codex API 处理器
 // ============================================================================

-/// 处理 /v1/chat/completions 请求（OpenAI Chat Completions API - Codex CLI）
-pub async fn handle_chat_completions(
-    State(state): State<ProxyState>,
-    headers: axum::http::HeaderMap,
-    Json(body): Json<Value>,
-) -> Result<axum::response::Response, ProxyError> {
-    let mut ctx =
-        RequestContext::new(&state, &body, &headers, AppType::Codex, "Codex", "codex").await?;
-
-    let is_stream = body
-        .get("stream")
-        .and_then(|v| v.as_bool())
-        .unwrap_or(false);
-
-    let forwarder = ctx.create_forwarder(&state);
-    let result = match forwarder
-        .forward_with_retry(
-            &AppType::Codex,
-            "/chat/completions",
-            body,
-            headers,
-            ctx.get_providers(),
-        )
-        .await
-    {
-        Ok(result) => result,
-        Err(mut err) => {
-            if let Some(provider) = err.provider.take() {
-                ctx.provider = provider;
-            }
-            log_forward_error(&state, &ctx, is_stream, &err.error);
-            return Err(err.error);
-        }
-    };
-
-    ctx.provider = result.provider;
-    let response = result.response;
-
-    process_response(response, &ctx, &state, &OPENAI_PARSER_CONFIG).await
-}
-
 /// 处理 /v1/responses 请求（OpenAI Responses API - Codex CLI 透传）
 pub async fn handle_responses(
    State(state): State<ProxyState>,
--- a/src-tauri/src/proxy/mod.rs
+++ b/src-tauri/src/proxy/mod.rs
@@ -24,6 +24,8 @@ pub mod session;
 pub mod thinking_budget_rectifier;
 pub mod thinking_rectifier;
 pub(crate) mod types;
+pub mod url_builder;
+pub(crate) mod url_utils;
 pub mod usage;

 // 公开导出给外部使用（commands, services等模块需要）
--- a/src-tauri/src/proxy/providers/claude.rs
+++ b/src-tauri/src/proxy/providers/claude.rs
@@ -14,6 +14,7 @@
 use super::{AuthInfo, AuthStrategy, ProviderAdapter, ProviderType};
 use crate::provider::Provider;
 use crate::proxy::error::ProxyError;
+use crate::proxy::url_utils::{dedup_v1_v1_boundary_safe, split_url_suffix};
 use reqwest::RequestBuilder;

 /// Claude 适配器
@@ -252,16 +253,34 @@ impl ProviderAdapter for ClaudeAdapter {
        // 现在 OpenRouter 已推出 Claude Code 兼容接口，因此默认直接透传 endpoint。
        // 如需回退旧逻辑，可在 forwarder 中根据 needs_transform 改写 endpoint。

-        let mut base = format!(
-            "{}/{}",
-            base_url.trim_end_matches('/'),
-            endpoint.trim_start_matches('/')
-        );
+        let (base, suffix) = split_url_suffix(base_url);
+        let base_trimmed = base.trim_end_matches('/');
+        let endpoint_trimmed = endpoint.trim_start_matches('/');
+
+        // 检测 base_url 是否已经以 API 路径结尾（用户填写了完整路径）
+        // 支持的 API 路径模式：/v1/messages, /messages, /v1/chat/completions, /chat/completions
+        let api_path_patterns = [
+            "/v1/messages",
+            "/messages",
+            "/v1/chat/completions",
+            "/chat/completions",
+        ];
+
+        let base_ends_with_api_path = api_path_patterns
+            .iter()
+            .any(|pattern| base_trimmed.to_lowercase().ends_with(pattern));
+
+        // 如果 base_url 已经以 API 路径结尾，直接使用 base_url，不再追加 endpoint
+        let base = if base_ends_with_api_path {
+            base_trimmed.to_string()
+        } else {
+            format!("{base_trimmed}/{endpoint_trimmed}")
+        };

        // 去除重复的 /v1/v1（可能由 base_url 与 endpoint 都带版本导致）
-        while base.contains("/v1/v1") {
-            base = base.replace("/v1/v1", "/v1");
-        }
+        let base = dedup_v1_v1_boundary_safe(base);
+
+        let url = format!("{base}{suffix}");

        // 为 Claude 原生 /v1/messages 端点添加 ?beta=true 参数
        // 这是某些上游服务（如 DuckCoding）验证请求来源的关键参数
@@ -271,10 +290,11 @@ impl ProviderAdapter for ClaudeAdapter {
        if endpoint.contains("/v1/messages")
            && !endpoint.contains("/v1/chat/completions")
            && !endpoint.contains('?')
+            && !url.contains('?')
        {
-            format!("{base}?beta=true")
+            format!("{url}?beta=true")
        } else {
-            base
+            url
        }
    }

@@ -487,7 +507,6 @@ mod tests {
    #[test]
    fn test_build_url_anthropic() {
        let adapter = ClaudeAdapter::new();
-        // /v1/messages 端点会自动添加 ?beta=true 参数
        let url = adapter.build_url("https://api.anthropic.com", "/v1/messages");
        assert_eq!(url, "https://api.anthropic.com/v1/messages?beta=true");
    }
@@ -495,7 +514,6 @@ mod tests {
    #[test]
    fn test_build_url_openrouter() {
        let adapter = ClaudeAdapter::new();
-        // /v1/messages 端点会自动添加 ?beta=true 参数
        let url = adapter.build_url("https://openrouter.ai/api", "/v1/messages");
        assert_eq!(url, "https://openrouter.ai/api/v1/messages?beta=true");
    }
@@ -503,7 +521,7 @@ mod tests {
    #[test]
    fn test_build_url_no_beta_for_other_endpoints() {
        let adapter = ClaudeAdapter::new();
-        // 非 /v1/messages 端点不添加 ?beta=true
+        // 非 /v1/messages 端点保持原样
        let url = adapter.build_url("https://api.anthropic.com", "/v1/complete");
        assert_eq!(url, "https://api.anthropic.com/v1/complete");
    }
@@ -516,6 +534,56 @@ mod tests {
        assert_eq!(url, "https://api.anthropic.com/v1/messages?foo=bar");
    }

+    #[test]
+    fn test_build_url_full_path_messages() {
+        let adapter = ClaudeAdapter::new();
+        // base_url 已包含完整路径 /v1/messages，不再追加
+        let url = adapter.build_url("https://example.com/api/v1/messages", "/v1/messages");
+        assert_eq!(url, "https://example.com/api/v1/messages?beta=true");
+    }
+
+    #[test]
+    fn test_build_url_full_path_chat_completions() {
+        let adapter = ClaudeAdapter::new();
+        // base_url 已包含完整路径 /v1/chat/completions，不再追加
+        let url = adapter.build_url(
+            "https://opencode.ai/zen/v1/chat/completions",
+            "/v1/chat/completions",
+        );
+        assert_eq!(url, "https://opencode.ai/zen/v1/chat/completions");
+    }
+
+    #[test]
+    fn test_build_url_full_path_short_suffix() {
+        let adapter = ClaudeAdapter::new();
+        // base_url 以 /messages 结尾（无 /v1 前缀）
+        let url = adapter.build_url("https://example.com/api/messages", "/v1/messages");
+        assert_eq!(url, "https://example.com/api/messages?beta=true");
+
+        // base_url 以 /chat/completions 结尾（无 /v1 前缀）
+        let url2 = adapter.build_url(
+            "https://example.com/api/chat/completions",
+            "/v1/chat/completions",
+        );
+        assert_eq!(url2, "https://example.com/api/chat/completions");
+    }
+
+    #[test]
+    fn test_build_url_v1_base_dedup() {
+        let adapter = ClaudeAdapter::new();
+        // base_url 以 /v1 结尾，endpoint 也以 /v1 开头，应该去重
+        // 场景：https://integrate.api.nvidia.com/v1 + /v1/chat/completions
+        let url = adapter.build_url(
+            "https://integrate.api.nvidia.com/v1",
+            "/v1/chat/completions",
+        );
+        assert_eq!(url, "https://integrate.api.nvidia.com/v1/chat/completions");
+
+        // 另一个场景：/v1 + /v1/messages
+        let url2 = adapter.build_url("https://api.example.com/v1", "/v1/messages");
+        assert_eq!(url2, "https://api.example.com/v1/messages?beta=true");
+    }
+
    #[test]
    fn test_build_url_no_beta_for_openai_chat_completions() {
        let adapter = ClaudeAdapter::new();
--- a/src-tauri/src/proxy/providers/codex.rs
+++ b/src-tauri/src/proxy/providers/codex.rs
@@ -8,6 +8,7 @@
 use super::{AuthInfo, AuthStrategy, ProviderAdapter};
 use crate::provider::Provider;
 use crate::proxy::error::ProxyError;
+use crate::proxy::url_utils::{dedup_v1_v1_boundary_safe, split_url_suffix};
 use regex::Regex;
 use reqwest::RequestBuilder;
 use std::sync::LazyLock;
@@ -138,9 +139,23 @@ impl ProviderAdapter for CodexAdapter {
    }

    fn build_url(&self, base_url: &str, endpoint: &str) -> String {
-        let base_trimmed = base_url.trim_end_matches('/');
+        let (base, suffix) = split_url_suffix(base_url);
+        let base_trimmed = base.trim_end_matches('/');
        let endpoint_trimmed = endpoint.trim_start_matches('/');

+        // 检测 base_url 是否已经以 API 路径结尾（用户填写了完整路径）
+        // 仅支持 Responses API 路径模式：/v1/responses, /responses
+        let api_path_patterns = ["/v1/responses", "/responses"];
+
+        let base_ends_with_api_path = api_path_patterns
+            .iter()
+            .any(|pattern| base_trimmed.to_lowercase().ends_with(pattern));
+
+        // 如果 base_url 已经以 API 路径结尾，直接使用 base_url，不再追加 endpoint
+        if base_ends_with_api_path {
+            return format!("{base_trimmed}{suffix}");
+        }
+
        // OpenAI/Codex 的 base_url 可能是：
        // - 纯 origin: https://api.openai.com  (需要自动补 /v1)
        // - 已含 /v1: https://api.openai.com/v1 (直接拼接)
@@ -167,11 +182,8 @@ impl ProviderAdapter for CodexAdapter {
        };

        // 去除重复的 /v1/v1（可能由 base_url 与 endpoint 都带版本导致）
-        while url.contains("/v1/v1") {
-            url = url.replace("/v1/v1", "/v1");
-        }
-
-        url
+        url = dedup_v1_v1_boundary_safe(url);
+        format!("{url}{suffix}")
    }

    fn add_auth_headers(&self, request: RequestBuilder, auth: &AuthInfo) -> RequestBuilder {
@@ -268,6 +280,31 @@ mod tests {
        assert_eq!(url, "https://www.packyapi.com/v1/responses");
    }

+    #[test]
+    fn test_build_url_full_path_responses() {
+        let adapter = CodexAdapter::new();
+        // base_url 已包含完整路径 /v1/responses，不再追加
+        let url = adapter.build_url("https://example.com/v1/responses", "/responses");
+        assert_eq!(url, "https://example.com/v1/responses");
+    }
+
+    #[test]
+    fn test_build_url_full_path_short_suffix() {
+        let adapter = CodexAdapter::new();
+        // base_url 以 /responses 结尾（无 /v1 前缀）
+        let url = adapter.build_url("https://example.com/api/responses", "/responses");
+        assert_eq!(url, "https://example.com/api/responses");
+    }
+
+    #[test]
+    fn test_build_url_v1_base_dedup() {
+        let adapter = CodexAdapter::new();
+        // base_url 以 /v1 结尾，endpoint 也以 /v1 开头，应该去重
+        // 场景：https://integrate.api.nvidia.com/v1 + /v1/responses
+        let url = adapter.build_url("https://integrate.api.nvidia.com/v1", "/v1/responses");
+        assert_eq!(url, "https://integrate.api.nvidia.com/v1/responses");
+    }
+
    // 官方客户端检测测试
    #[test]
    fn test_is_official_client_vscode() {
--- a/src-tauri/src/proxy/providers/gemini.rs
+++ b/src-tauri/src/proxy/providers/gemini.rs
@@ -9,6 +9,7 @@
 use super::{AuthInfo, AuthStrategy, ProviderAdapter, ProviderType};
 use crate::provider::Provider;
 use crate::proxy::error::ProxyError;
+use crate::proxy::url_utils::split_url_suffix;
 use reqwest::RequestBuilder;

 /// Gemini 适配器
@@ -200,7 +201,8 @@ impl ProviderAdapter for GeminiAdapter {
    }

    fn build_url(&self, base_url: &str, endpoint: &str) -> String {
-        let base_trimmed = base_url.trim_end_matches('/');
+        let (base, suffix) = split_url_suffix(base_url);
+        let base_trimmed = base.trim_end_matches('/');
        let endpoint_trimmed = endpoint.trim_start_matches('/');

        let mut url = format!("{base_trimmed}/{endpoint_trimmed}");
@@ -214,7 +216,7 @@ impl ProviderAdapter for GeminiAdapter {
            }
        }

-        url
+        format!("{url}{suffix}")
    }

    fn add_auth_headers(&self, request: RequestBuilder, auth: &AuthInfo) -> RequestBuilder {
--- a/src-tauri/src/proxy/server.rs
+++ b/src-tauri/src/proxy/server.rs
@@ -218,20 +218,6 @@ impl ProxyServer {
            // Claude API (支持带前缀和不带前缀两种格式)
            .route("/v1/messages", post(handlers::handle_messages))
            .route("/claude/v1/messages", post(handlers::handle_messages))
-            // OpenAI Chat Completions API (Codex CLI，支持带前缀和不带前缀)
-            .route("/chat/completions", post(handlers::handle_chat_completions))
-            .route(
-                "/v1/chat/completions",
-                post(handlers::handle_chat_completions),
-            )
-            .route(
-                "/v1/v1/chat/completions",
-                post(handlers::handle_chat_completions),
-            )
-            .route(
-                "/codex/v1/chat/completions",
-                post(handlers::handle_chat_completions),
-            )
            // OpenAI Responses API (Codex CLI，支持带前缀和不带前缀)
            .route("/responses", post(handlers::handle_responses))
            .route("/v1/responses", post(handlers::handle_responses))
--- a/src-tauri/src/proxy/url_builder.rs
+++ b/src-tauri/src/proxy/url_builder.rs
@@ -0,0 +1,437 @@
+//! URL 构建工具模块
+//!
+//! 提供统一的 URL 构建逻辑，供前端预览和后端代理使用。
+
+use crate::app_config::AppType;
+use crate::proxy::providers::{ClaudeAdapter, CodexAdapter, ProviderAdapter};
+use crate::proxy::url_utils::{dedup_v1_v1_boundary_safe, split_url_suffix};
+use serde::{Deserialize, Serialize};
+
+/// URL 预览结果
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UrlPreview {
+    /// 直连模式请求地址
+    pub direct_url: String,
+    /// 代理模式请求地址
+    pub proxy_url: String,
+    /// 是否为全链接（base_url 已包含 API 路径）
+    pub is_full_url: bool,
+}
+
+/// API 路径模式
+struct ApiPathPatterns {
+    /// 直连模式默认端点
+    direct_endpoint: &'static str,
+    /// 代理模式端点（根据 api_format 可能不同）
+    proxy_endpoint: &'static str,
+    /// 识别为全链接的路径后缀
+    full_url_patterns: &'static [&'static str],
+}
+
+impl ApiPathPatterns {
+    fn for_claude(api_format: Option<&str>) -> Self {
+        // 根据 API 格式决定端点和全链接检测模式
+        if api_format == Some("openai_chat") {
+            Self {
+                direct_endpoint: "/v1/messages",
+                proxy_endpoint: "/v1/chat/completions",
+                // 与运行时 ClaudeAdapter 保持一致：同时识别 messages/chat 两类完整路径
+                full_url_patterns: &[
+                    "/v1/messages",
+                    "/messages",
+                    "/v1/chat/completions",
+                    "/chat/completions",
+                ],
+            }
+        } else {
+            Self {
+                direct_endpoint: "/v1/messages",
+                proxy_endpoint: "/v1/messages",
+                // 与运行时 ClaudeAdapter 保持一致：同时识别 messages/chat 两类完整路径
+                full_url_patterns: &[
+                    "/v1/messages",
+                    "/messages",
+                    "/v1/chat/completions",
+                    "/chat/completions",
+                ],
+            }
+        }
+    }
+
+    fn for_codex(api_format: Option<&str>) -> Self {
+        let _ = api_format;
+        Self {
+            direct_endpoint: "/responses",
+            proxy_endpoint: "/responses",
+            full_url_patterns: &["/v1/responses", "/responses"],
+        }
+    }
+
+    fn for_gemini() -> Self {
+        Self {
+            direct_endpoint: "/v1beta/models",
+            proxy_endpoint: "/v1beta/models",
+            full_url_patterns: &["/v1beta/models"],
+        }
+    }
+}
+
+/// 检测 URL 是否以指定的 API 路径结尾
+fn url_ends_with_api_path(url: &str, patterns: &[&str]) -> bool {
+    let (base, _) = split_url_suffix(url);
+    let path_part = base.trim_end_matches('/').to_lowercase();
+    patterns
+        .iter()
+        .any(|pattern| path_part.ends_with(&pattern.to_lowercase()))
+}
+
+/// 硬拼接 URL（用于直连地址）
+///
+/// 始终将 endpoint 拼接到 base_url 后面，不做任何智能检测或去重。
+fn build_direct_url(base_url: &str, endpoint: &str) -> String {
+    let (base, suffix) = split_url_suffix(base_url);
+    let base_trimmed = base.trim_end_matches('/');
+    let endpoint_trimmed = endpoint.trim_start_matches('/');
+
+    // 直接拼接，不做任何去重
+    format!("{base_trimmed}/{endpoint_trimmed}{suffix}")
+}
+
+/// 智能构建 URL（用于代理地址）
+///
+/// 如果 base_url 已经以 API 路径结尾，直接返回；否则追加 endpoint。
+pub fn build_smart_url(base_url: &str, endpoint: &str, full_url_patterns: &[&str]) -> String {
+    let (base, suffix) = split_url_suffix(base_url);
+    let base_trimmed = base.trim_end_matches('/');
+    let endpoint_trimmed = endpoint.trim_start_matches('/');
+
+    // 检测 base_url 是否已经以 API 路径结尾
+    if url_ends_with_api_path(base_trimmed, full_url_patterns) {
+        return format!("{base_trimmed}{suffix}");
+    }
+
+    // 拼接 URL
+    let url = format!("{base_trimmed}/{endpoint_trimmed}");
+    let url = dedup_v1_v1_boundary_safe(url);
+    format!("{url}{suffix}")
+}
+
+fn build_runtime_like_url(
+    app_type: &AppType,
+    base_url: &str,
+    endpoint: &str,
+    is_proxy: bool,
+) -> String {
+    match app_type {
+        // Claude 代理预览需要展示与运行时一致的 URL 归一化结果
+        AppType::Claude if is_proxy => ClaudeAdapter::new().build_url(base_url, endpoint),
+        // Codex/OpenCode 预览复用运行时 /v1 归一化规则
+        AppType::Codex | AppType::OpenCode | AppType::OpenClaw => {
+            CodexAdapter::new().build_url(base_url, endpoint)
+        }
+        _ => build_direct_url(base_url, endpoint),
+    }
+}
+
+/// 构建 URL 预览
+///
+/// 根据 app_type、base_url 和 api_format 计算直连和代理模式的请求地址。
+/// - 直连地址：始终硬拼接默认后缀
+/// - 代理地址：智能检测，如果已包含 API 路径则不重复拼接
+pub fn build_url_preview(
+    app_type: &AppType,
+    base_url: &str,
+    api_format: Option<&str>,
+) -> UrlPreview {
+    let patterns = match app_type {
+        AppType::Claude => ApiPathPatterns::for_claude(api_format),
+        AppType::Codex => ApiPathPatterns::for_codex(api_format),
+        AppType::Gemini => ApiPathPatterns::for_gemini(),
+        AppType::OpenCode => ApiPathPatterns::for_codex(api_format), // OpenCode 使用 Codex 逻辑
+        AppType::OpenClaw => ApiPathPatterns::for_codex(api_format), // OpenClaw 使用 Codex 逻辑
+    };
+
+    let is_full_url = url_ends_with_api_path(base_url, patterns.full_url_patterns);
+
+    // 直连地址：默认硬拼接；Codex/OpenCode 复用运行时规则（含 origin-only /v1 归一化）
+    let direct_url = build_runtime_like_url(app_type, base_url, patterns.direct_endpoint, false);
+    // 代理地址：Claude/Codex/OpenCode 复用运行时规则；Gemini 继续使用通用智能拼接
+    let proxy_url = match app_type {
+        AppType::Claude | AppType::Codex | AppType::OpenCode | AppType::OpenClaw => {
+            build_runtime_like_url(app_type, base_url, patterns.proxy_endpoint, true)
+        }
+        _ => build_smart_url(
+            base_url,
+            patterns.proxy_endpoint,
+            patterns.full_url_patterns,
+        ),
+    };
+
+    UrlPreview {
+        direct_url,
+        proxy_url,
+        is_full_url,
+    }
+}
+
+/// 检查是否需要代理
+///
+/// 返回需要代理的原因，None 表示不需要代理
+pub fn check_proxy_requirement(
+    app_type: &AppType,
+    base_url: &str,
+    api_format: Option<&str>,
+) -> Option<&'static str> {
+    // Claude OpenAI Chat 格式必须开启代理（需要格式转换）
+    if matches!(app_type, AppType::Claude) && api_format == Some("openai_chat") {
+        return Some("openai_chat_format");
+    }
+
+    // base_url 缺失时无法做 full_url / url_mismatch 判断，避免误判
+    if base_url.trim().is_empty() {
+        return None;
+    }
+
+    let preview = build_url_preview(app_type, base_url, api_format);
+
+    // 如果是全链接且以直连后缀结尾，需要代理
+    if preview.is_full_url {
+        // 检查是否以直连后缀结尾
+        let direct_suffixes: &[&str] = match app_type {
+            AppType::Claude => &[
+                "/v1/messages",
+                "/messages",
+                "/v1/chat/completions",
+                "/chat/completions",
+            ],
+            AppType::Codex | AppType::OpenCode | AppType::OpenClaw => &["/v1/responses", "/responses"],
+            _ => return None,
+        };
+
+        if url_ends_with_api_path(base_url, direct_suffixes) {
+            return Some("full_url");
+        }
+    }
+
+    // 如果直连地址和代理地址路径不同，需要代理（忽略查询参数差异）
+    let (direct_base, _) = split_url_suffix(&preview.direct_url);
+    let (proxy_base, _) = split_url_suffix(&preview.proxy_url);
+    if direct_base != proxy_base {
+        return Some("url_mismatch");
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_build_url_preview_claude_anthropic() {
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com",
+            Some("anthropic"),
+        );
+        assert_eq!(preview.direct_url, "https://api.example.com/v1/messages");
+        assert_eq!(preview.proxy_url, "https://api.example.com/v1/messages");
+        assert!(!preview.is_full_url);
+    }
+
+    #[test]
+    fn test_build_url_preview_claude_openai_chat() {
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com",
+            Some("openai_chat"),
+        );
+        assert_eq!(preview.direct_url, "https://api.example.com/v1/messages");
+        assert_eq!(
+            preview.proxy_url,
+            "https://api.example.com/v1/chat/completions"
+        );
+        assert!(!preview.is_full_url);
+    }
+
+    #[test]
+    fn test_build_url_preview_claude_full_url() {
+        // 全链接时：直连会硬拼接后缀，代理保持原地址
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/messages",
+            Some("anthropic"),
+        );
+        assert_eq!(
+            preview.direct_url,
+            "https://api.example.com/v1/messages/v1/messages"
+        );
+        assert_eq!(preview.proxy_url, "https://api.example.com/v1/messages");
+        assert!(preview.is_full_url);
+    }
+
+    #[test]
+    fn test_build_url_preview_codex_responses() {
+        let preview = build_url_preview(
+            &AppType::Codex,
+            "https://api.openai.com/v1",
+            Some("responses"),
+        );
+        assert_eq!(preview.direct_url, "https://api.openai.com/v1/responses");
+        assert_eq!(preview.proxy_url, "https://api.openai.com/v1/responses");
+        assert!(!preview.is_full_url);
+    }
+
+    #[test]
+    fn test_build_url_preview_codex_origin_normalizes_v1() {
+        let preview =
+            build_url_preview(&AppType::Codex, "https://api.openai.com", Some("responses"));
+        assert_eq!(preview.direct_url, "https://api.openai.com/v1/responses");
+        assert_eq!(preview.proxy_url, "https://api.openai.com/v1/responses");
+        assert!(!preview.is_full_url);
+    }
+
+    #[test]
+    fn test_build_url_preview_codex_full_url() {
+        // 全链接时：直连/代理均保持原地址（运行时适配器规则）
+        let preview = build_url_preview(
+            &AppType::Codex,
+            "https://api.example.com/v1/responses",
+            Some("responses"),
+        );
+        assert_eq!(preview.direct_url, "https://api.example.com/v1/responses");
+        assert_eq!(preview.proxy_url, "https://api.example.com/v1/responses");
+        assert!(preview.is_full_url);
+    }
+
+    #[test]
+    fn test_check_proxy_requirement_claude_openai_chat() {
+        let result = check_proxy_requirement(
+            &AppType::Claude,
+            "https://api.example.com",
+            Some("openai_chat"),
+        );
+        assert_eq!(result, Some("openai_chat_format"));
+    }
+
+    #[test]
+    fn test_check_proxy_requirement_claude_full_url() {
+        let result = check_proxy_requirement(
+            &AppType::Claude,
+            "https://api.example.com/v1/messages",
+            Some("anthropic"),
+        );
+        assert_eq!(result, Some("full_url"));
+    }
+
+    #[test]
+    fn test_check_proxy_requirement_codex_full_url() {
+        let result = check_proxy_requirement(
+            &AppType::Codex,
+            "https://api.example.com/v1/responses",
+            Some("responses"),
+        );
+        assert_eq!(result, Some("full_url"));
+    }
+
+    #[test]
+    fn test_check_proxy_requirement_codex_origin_none() {
+        let result =
+            check_proxy_requirement(&AppType::Codex, "https://api.openai.com", Some("responses"));
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn test_check_proxy_requirement_none() {
+        let result = check_proxy_requirement(
+            &AppType::Claude,
+            "https://api.example.com",
+            Some("anthropic"),
+        );
+        assert_eq!(result, None);
+    }
+
+    #[test]
+    fn test_v1_dedup() {
+        // 代理地址使用 build_smart_url，会去重 /v1/v1
+        let url = build_smart_url("https://api.example.com/v1", "/v1/messages", &[]);
+        assert_eq!(url, "https://api.example.com/v1/messages");
+    }
+
+    #[test]
+    fn test_direct_url_no_dedup() {
+        // 直连地址硬拼接，不做任何去重
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1",
+            Some("anthropic"),
+        );
+        assert_eq!(preview.direct_url, "https://api.example.com/v1/v1/messages");
+        // 代理地址按运行时规则构建，会进行路径去重
+        assert_eq!(preview.proxy_url, "https://api.example.com/v1/messages");
+    }
+
+    #[test]
+    fn test_query_suffix_preserved_in_preview() {
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com?beta=true",
+            Some("anthropic"),
+        );
+        assert_eq!(
+            preview.direct_url,
+            "https://api.example.com/v1/messages?beta=true"
+        );
+        assert_eq!(
+            preview.proxy_url,
+            "https://api.example.com/v1/messages?beta=true"
+        );
+        assert!(!preview.is_full_url);
+    }
+
+    #[test]
+    fn test_fragment_suffix_preserved_and_full_url_detected() {
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/messages#frag",
+            Some("anthropic"),
+        );
+        assert_eq!(
+            preview.proxy_url,
+            "https://api.example.com/v1/messages#frag"
+        );
+        assert!(preview.is_full_url);
+    }
+
+    #[test]
+    fn test_claude_full_url_detection_is_api_format_agnostic() {
+        // 与运行时 ClaudeAdapter 一致：/messages 与 /chat/completions 都视为全链接
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/messages",
+            Some("anthropic"),
+        );
+        assert!(preview.is_full_url);
+
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/chat/completions",
+            Some("anthropic"),
+        );
+        assert!(preview.is_full_url);
+
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/chat/completions",
+            Some("openai_chat"),
+        );
+        assert!(preview.is_full_url);
+
+        let preview = build_url_preview(
+            &AppType::Claude,
+            "https://api.example.com/v1/messages",
+            Some("openai_chat"),
+        );
+        assert!(preview.is_full_url);
+    }
+}
--- a/src-tauri/src/proxy/url_utils.rs
+++ b/src-tauri/src/proxy/url_utils.rs
@@ -0,0 +1,96 @@
+//! URL utilities shared across proxy modules.
+//!
+//! This module intentionally avoids full URL parsing to keep behavior aligned with
+//! existing "stringly-typed" base_url configurations while fixing common edge cases
+//! (query/fragment handling and safe path de-duplication).
+
+/// Split a URL-like string into `(base, suffix)` where suffix starts with `?` or `#`.
+///
+/// Example:
+/// - `https://x/v1?token=1` => (`https://x/v1`, `?token=1`)
+/// - `https://x/v1#frag` => (`https://x/v1`, `#frag`)
+pub(crate) fn split_url_suffix(input: &str) -> (&str, &str) {
+    match input.find(['?', '#']) {
+        Some(idx) => (&input[..idx], &input[idx..]),
+        None => (input, ""),
+    }
+}
+
+/// De-duplicate repeated `/v1/v1` only when it occurs on a segment boundary.
+///
+/// This avoids corrupting valid paths such as `/v1/v1beta/...`.
+pub(crate) fn dedup_v1_v1_boundary_safe(mut url: String) -> String {
+    const NEEDLE: &str = "/v1/v1";
+    let mut search_start = 0usize;
+
+    loop {
+        let Some(rel_pos) = url[search_start..].find(NEEDLE) else {
+            break;
+        };
+        let pos = search_start + rel_pos;
+        let after = pos + NEEDLE.len();
+
+        let boundary_ok = after == url.len()
+            || matches!(
+                url.as_bytes().get(after),
+                Some(b'/') | Some(b'?') | Some(b'#')
+            );
+
+        if boundary_ok {
+            url.replace_range(pos..after, "/v1");
+            // Continue searching from the same position in case we created a new boundary match.
+            search_start = pos;
+        } else {
+            // Skip forward to find later occurrences that might be valid boundary matches.
+            search_start = pos + 1;
+        }
+    }
+
+    url
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn split_url_suffix_handles_query() {
+        let (base, suffix) = split_url_suffix("https://example.com/v1?token=1");
+        assert_eq!(base, "https://example.com/v1");
+        assert_eq!(suffix, "?token=1");
+    }
+
+    #[test]
+    fn split_url_suffix_handles_fragment() {
+        let (base, suffix) = split_url_suffix("https://example.com/v1#frag");
+        assert_eq!(base, "https://example.com/v1");
+        assert_eq!(suffix, "#frag");
+    }
+
+    #[test]
+    fn dedup_v1_v1_only_on_boundary() {
+        let url = "https://example.com/v1/v1/messages".to_string();
+        assert_eq!(
+            dedup_v1_v1_boundary_safe(url),
+            "https://example.com/v1/messages"
+        );
+    }
+
+    #[test]
+    fn dedup_v1_v1_does_not_corrupt_v1beta() {
+        let url = "https://example.com/v1/v1beta/models".to_string();
+        assert_eq!(
+            dedup_v1_v1_boundary_safe(url.clone()),
+            "https://example.com/v1/v1beta/models"
+        );
+    }
+
+    #[test]
+    fn dedup_v1_v1_skips_v1beta_but_dedups_later_occurrence() {
+        let url = "https://example.com/v1/v1beta/v1/v1/messages".to_string();
+        assert_eq!(
+            dedup_v1_v1_boundary_safe(url),
+            "https://example.com/v1/v1beta/v1/messages"
+        );
+    }
+}
--- a/src-tauri/src/services/proxy.rs
+++ b/src-tauri/src/services/proxy.rs
@@ -830,7 +830,7 @@ impl ProxyService {
    ///
    /// 代理服务器的路由已经根据 API 端点自动区分应用类型：
    /// - `/v1/messages` → Claude
-    /// - `/v1/chat/completions`, `/v1/responses` → Codex
+    /// - `/v1/responses` → Codex
    /// - `/v1beta/*` → Gemini
    ///
    /// 因此不需要在 URL 中添加应用前缀。
--- a/src-tauri/src/services/stream_check.rs
+++ b/src-tauri/src/services/stream_check.rs
@@ -293,11 +293,11 @@ impl StreamCheckService {
        timeout: std::time::Duration,
    ) -> Result<(u16, String), AppError> {
        let base = base_url.trim_end_matches('/');
-        // URL 必须包含 ?beta=true 参数（某些中转服务依赖此参数验证请求来源）
+        // 健康检查不强制附加查询参数，保持与默认 Claude 路径一致
        let url = if base.ends_with("/v1") {
-            format!("{base}/messages?beta=true")
+            format!("{base}/messages")
        } else {
-            format!("{base}/v1/messages?beta=true")
+            format!("{base}/v1/messages")
        };

        let body = json!({
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -229,7 +229,10 @@ function App() {
    deleteProvider,
    saveUsageScript,
    setAsDefaultModel,
-  } = useProviderActions(activeApp);
+  } = useProviderActions(activeApp, {
+    isProxyRunning,
+    isTakeoverActive: isCurrentAppTakeoverActive,
+  });

  const disableOmoMutation = useDisableCurrentOmo();
  const handleDisableOmo = () => {
@@ -1022,7 +1025,10 @@ function App() {
              <>
                {activeApp !== "opencode" && activeApp !== "openclaw" && (
                  <>
-                    <ProxyToggle activeApp={activeApp} />
+                    <ProxyToggle
+                      activeApp={activeApp}
+                      currentProvider={providers[currentProviderId] || null}
+                    />
                    <div
                      className={cn(
                        "transition-all duration-300 ease-in-out overflow-hidden",
--- a/src/components/providers/forms/ClaudeFormFields.tsx
+++ b/src/components/providers/forms/ClaudeFormFields.tsx
@@ -169,6 +169,8 @@ export function ClaudeFormFields({
              : t("providerForm.apiHint")
          }
          onManageClick={() => onEndpointModalToggle(true)}
+          appType="claude"
+          apiFormat={apiFormat}
        />
      )}

--- a/src/components/providers/forms/CodexFormFields.tsx
+++ b/src/components/providers/forms/CodexFormFields.tsx
@@ -94,6 +94,8 @@ export function CodexFormFields({
          placeholder={t("providerForm.codexApiEndpointPlaceholder")}
          hint={t("providerForm.codexApiHint")}
          onManageClick={() => onEndpointModalToggle(true)}
+          appType="codex"
+          apiFormat="responses"
        />
      )}

--- a/src/components/providers/forms/ProviderForm.tsx
+++ b/src/components/providers/forms/ProviderForm.tsx
@@ -43,7 +43,10 @@ import {
 import { OpenCodeFormFields } from "./OpenCodeFormFields";
 import { OpenClawFormFields } from "./OpenClawFormFields";
 import type { UniversalProviderPreset } from "@/config/universalProviderPresets";
-import { applyTemplateValues } from "@/utils/providerConfigUtils";
+import {
+  applyTemplateValues,
+  setCodexWireApi,
+} from "@/utils/providerConfigUtils";
 import { mergeProviderMeta } from "@/utils/providerMetaUtils";
 import { getCodexCustomTemplate } from "@/config/codexTemplates";
 import CodexConfigEditor from "./CodexConfigEditor";
@@ -405,14 +408,13 @@ export function ProviderForm({
    onConfigChange: (config) => form.setValue("settingsConfig", config),
  });

-  const [localApiFormat, setLocalApiFormat] = useState<ClaudeApiFormat>(() => {
-    if (appId !== "claude") return "anthropic";
-    return initialData?.meta?.apiFormat ?? "anthropic";
-  });
-
-  const handleApiFormatChange = useCallback((format: ClaudeApiFormat) => {
-    setLocalApiFormat(format);
-  }, []);
+  const [localClaudeApiFormat, setLocalClaudeApiFormat] =
+    useState<ClaudeApiFormat>(() => {
+      if (appId !== "claude") return "anthropic";
+      return initialData?.meta?.apiFormat === "openai_chat"
+        ? "openai_chat"
+        : "anthropic";
+    });

  const {
    codexAuth,
@@ -440,6 +442,10 @@ export function ProviderForm({
    [originalHandleCodexConfigChange, debouncedValidate],
  );

+  const handleClaudeApiFormatChange = useCallback((format: ClaudeApiFormat) => {
+    setLocalClaudeApiFormat(format);
+  }, []);
+
  useEffect(() => {
    if (appId === "codex" && !initialData && selectedPresetId === "custom") {
      const template = getCodexCustomTemplate();
@@ -1361,7 +1367,7 @@ export function ProviderForm({
        const authJson = JSON.parse(codexAuth);
        const configObj = {
          auth: authJson,
-          config: codexConfig ?? "",
+          config: setCodexWireApi(codexConfig ?? "", "responses"),
        };
        settingsConfig = JSON.stringify(configObj);
      } catch (err) {
@@ -1496,6 +1502,11 @@ export function ProviderForm({
      }
    }

+    const providerApiFormat =
+      appId === "claude" && category !== "official"
+        ? localClaudeApiFormat
+        : undefined;
+
    const baseMeta: ProviderMeta | undefined =
      payload.meta ?? (initialData?.meta ? { ...initialData.meta } : undefined);
    payload.meta = {
@@ -1510,10 +1521,7 @@ export function ProviderForm({
        pricingConfig.enabled && pricingConfig.pricingModelSource !== "inherit"
          ? pricingConfig.pricingModelSource
          : undefined,
-      apiFormat:
-        appId === "claude" && category !== "official"
-          ? localApiFormat
-          : undefined,
+      apiFormat: providerApiFormat,
    };

    onSubmit(payload);
@@ -1768,9 +1776,9 @@ export function ProviderForm({
    );

    if (preset.apiFormat) {
-      setLocalApiFormat(preset.apiFormat);
+      setLocalClaudeApiFormat(preset.apiFormat);
    } else {
-      setLocalApiFormat("anthropic");
+      setLocalClaudeApiFormat("anthropic");
    }

    form.reset({
@@ -1953,8 +1961,8 @@ export function ProviderForm({
            defaultOpusModel={defaultOpusModel}
            onModelChange={handleModelChange}
            speedTestEndpoints={speedTestEndpoints}
-            apiFormat={localApiFormat}
-            onApiFormatChange={handleApiFormatChange}
+            apiFormat={localClaudeApiFormat}
+            onApiFormatChange={handleClaudeApiFormatChange}
          />
        )}

--- a/src/components/providers/forms/shared/EndpointField.tsx
+++ b/src/components/providers/forms/shared/EndpointField.tsx
@@ -1,7 +1,11 @@
+import { useState, useEffect, useRef } from "react";
 import { useTranslation } from "react-i18next";
 import { FormLabel } from "@/components/ui/form";
 import { Input } from "@/components/ui/input";
-import { Zap } from "lucide-react";
+import { Zap, AlertTriangle, Server, Unplug } from "lucide-react";
+import { proxyApi, type UrlPreview } from "@/lib/api/proxy";
+
+type AppType = "claude" | "codex" | "gemini";

 interface EndpointFieldProps {
  id: string;
@@ -13,6 +17,11 @@ interface EndpointFieldProps {
  showManageButton?: boolean;
  onManageClick?: () => void;
  manageButtonLabel?: string;
+  // 应用类型和 API 格式
+  appType?: AppType;
+  apiFormat?: string;
+  // 是否显示请求地址预览
+  showUrlPreview?: boolean;
 }

 export function EndpointField({
@@ -25,13 +34,48 @@ export function EndpointField({
  showManageButton = true,
  onManageClick,
  manageButtonLabel,
+  appType,
+  apiFormat,
+  showUrlPreview = true,
 }: EndpointFieldProps) {
  const { t } = useTranslation();
+  const [urlPreview, setUrlPreview] = useState<UrlPreview | null>(null);
+  const lastRequestIdRef = useRef(0);

  const defaultManageLabel = t("providerForm.manageAndTest", {
    defaultValue: "管理和测速",
  });

+  // 调用后端 API 获取 URL 预览
+  useEffect(() => {
+    if (!value || !appType || !showUrlPreview) {
+      // 标记当前所有已发出的请求为过期，避免旧请求回写
+      lastRequestIdRef.current += 1;
+      setUrlPreview(null);
+      return;
+    }
+
+    // 防抖：延迟 300ms 后请求
+    const timer = setTimeout(async () => {
+      const requestId = ++lastRequestIdRef.current;
+      try {
+        const preview = await proxyApi.buildUrlPreview(
+          appType,
+          value,
+          apiFormat,
+        );
+        if (requestId !== lastRequestIdRef.current) return;
+        setUrlPreview(preview);
+      } catch (error) {
+        console.error("Failed to build URL preview:", error);
+        if (requestId !== lastRequestIdRef.current) return;
+        setUrlPreview(null);
+      }
+    }, 300);
+
+    return () => clearTimeout(timer);
+  }, [value, appType, apiFormat, showUrlPreview]);
+
  return (
    <div className="space-y-2">
      <div className="flex items-center justify-between">
@@ -55,6 +99,68 @@ export function EndpointField({
        placeholder={placeholder}
        autoComplete="off"
      />
+
+      {/* 请求地址预览 */}
+      {showUrlPreview && urlPreview && (
+        <div className="p-2 bg-muted/50 border border-border rounded-md space-y-2">
+          {/* CLI 直连请求地址 */}
+          <div>
+            <p className="text-xs text-muted-foreground mb-0.5 flex items-center gap-1">
+              <Unplug className="h-3 w-3" />
+              {t("providerForm.directRequestUrl", {
+                defaultValue: "CLI 直连请求地址：",
+              })}
+            </p>
+            <p className="text-xs font-mono text-foreground break-all pl-4">
+              {urlPreview.direct_url}
+            </p>
+            <p className="text-xs text-muted-foreground/70 mt-0.5 pl-4">
+              {t("providerForm.directRequestUrlDesc", {
+                defaultValue: "CLI 直连模式下的实际请求地址",
+              })}
+            </p>
+          </div>
+
+          {/* CCS 代理请求地址 */}
+          <div className="pt-1.5 border-t border-border/50">
+            <p className="text-xs text-muted-foreground mb-0.5 flex items-center gap-1">
+              <Server className="h-3 w-3" />
+              {t("providerForm.proxyRequestUrl", {
+                defaultValue: "CCS 代理请求地址：",
+              })}
+            </p>
+            <p className="text-xs font-mono text-foreground break-all pl-4">
+              {urlPreview.proxy_url}
+            </p>
+            <p className="text-xs text-muted-foreground/70 mt-0.5 pl-4">
+              {t("providerForm.proxyRequestUrlDesc", {
+                defaultValue: "CCS 智能拼接后转发到上游的地址",
+              })}
+            </p>
+          </div>
+        </div>
+      )}
+
+      {/* 全链接警告 */}
+      {urlPreview?.is_full_url && (
+        <div className="flex items-start gap-2 p-2 bg-orange-50 dark:bg-orange-950/30 border border-orange-200 dark:border-orange-800 rounded-md">
+          <AlertTriangle className="h-4 w-4 text-orange-500 mt-0.5 flex-shrink-0" />
+          <div className="flex-1">
+            <p className="text-xs text-orange-600 dark:text-orange-400 font-medium">
+              {t("providerForm.fullUrlWarningTitle", {
+                defaultValue: "检测到完整 API 路径",
+              })}
+            </p>
+            <p className="text-xs text-orange-600/80 dark:text-orange-400/80 mt-0.5">
+              {t("providerForm.fullUrlWarning", {
+                defaultValue:
+                  "填写了包含 API 路径的完整地址，此配置仅在代理模式下生效。直连模式下请只填写基础地址。",
+              })}
+            </p>
+          </div>
+        </div>
+      )}
+
      {hint ? (
        <div className="p-3 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-700 rounded-lg">
          <p className="text-xs text-amber-600 dark:text-amber-400">{hint}</p>
--- a/src/components/proxy/ProxyToggle.tsx
+++ b/src/components/proxy/ProxyToggle.tsx
@@ -6,27 +6,91 @@
 */

 import { Radio, Loader2 } from "lucide-react";
+import { useState } from "react";
 import { Switch } from "@/components/ui/switch";
 import { useProxyStatus } from "@/hooks/useProxyStatus";
 import { cn } from "@/lib/utils";
 import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
 import type { AppId } from "@/lib/api";
+import { proxyApi } from "@/lib/api/proxy";
+import type { Provider } from "@/types";
+import { extractProviderBaseUrl } from "@/utils/providerBaseUrl";

 interface ProxyToggleProps {
  className?: string;
  activeApp: AppId;
+  currentProvider?: Provider | null;
 }

-export function ProxyToggle({ className, activeApp }: ProxyToggleProps) {
+export function ProxyToggle({
+  className,
+  activeApp,
+  currentProvider,
+}: ProxyToggleProps) {
  const { t } = useTranslation();
+  const [isCheckingRequirement, setIsCheckingRequirement] = useState(false);
  const { isRunning, takeoverStatus, setTakeoverForApp, isPending, status } =
    useProxyStatus();

  const handleToggle = async (checked: boolean) => {
+    // 关闭代理时，检查当前供应商是否是全链接配置
+    if (
+      !checked &&
+      currentProvider &&
+      currentProvider.category !== "official"
+    ) {
+      const baseUrl = extractProviderBaseUrl(currentProvider, activeApp);
+      const apiFormat = currentProvider.meta?.apiFormat;
+      setIsCheckingRequirement(true);
+      try {
+        let proxyRequirement: string | null = null;
+        if (baseUrl || apiFormat) {
+          proxyRequirement = await proxyApi.checkProxyRequirement(
+            activeApp,
+            baseUrl || "",
+            apiFormat,
+          );
+        }
+
+        if (proxyRequirement) {
+          const warningKey =
+            proxyRequirement === "openai_chat_format"
+              ? "notifications.openAIChatFormatWarningOnDisable"
+              : proxyRequirement === "url_mismatch"
+                ? "notifications.urlMismatchWarningOnDisable"
+                : "notifications.fullUrlWarningOnDisable";
+
+          toast.warning(
+            t(warningKey, {
+              defaultValue:
+                "当前供应商配置可能依赖代理模式，关闭代理后可能无法正常工作。建议更换为基础地址配置或保持代理开启。",
+            }),
+            { duration: 6000, closeButton: true },
+          );
+        }
+      } catch (error) {
+        console.error("Failed to check proxy requirement:", error);
+      } finally {
+        setIsCheckingRequirement(false);
+      }
+    }
+
    try {
      await setTakeoverForApp({ appType: activeApp, enabled: checked });
    } catch (error) {
      console.error("[ProxyToggle] Toggle takeover failed:", error);
+      toast.error(
+        t("proxy.takeover.toggleFailed", {
+          defaultValue: "切换接管状态失败",
+        }),
+        {
+          description: t("proxy.takeover.toggleFailedDesc", {
+            defaultValue: "请检查代理服务状态与权限，然后重试。",
+          }),
+          closeButton: true,
+        },
+      );
    }
  };

@@ -61,7 +125,7 @@ export function ProxyToggle({ className, activeApp }: ProxyToggleProps) {
      )}
      title={tooltipText}
    >
-      {isPending ? (
+      {isPending || isCheckingRequirement ? (
        <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
      ) : (
        <Radio
@@ -76,7 +140,7 @@ export function ProxyToggle({ className, activeApp }: ProxyToggleProps) {
      <Switch
        checked={takeoverEnabled}
        onCheckedChange={handleToggle}
-        disabled={isPending}
+        disabled={isPending || isCheckingRequirement}
      />
    </div>
  );
--- a/src/hooks/useProviderActions.ts
+++ b/src/hooks/useProviderActions.ts
@@ -3,6 +3,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import { toast } from "sonner";
 import { useTranslation } from "react-i18next";
 import { providersApi, settingsApi, openclawApi, type AppId } from "@/lib/api";
+import { proxyApi } from "@/lib/api/proxy";
 import type {
  Provider,
  UsageScript,
@@ -17,13 +18,25 @@ import {
  useSwitchProviderMutation,
 } from "@/lib/query";
 import { extractErrorMessage } from "@/utils/errorUtils";
+import { extractProviderBaseUrl } from "@/utils/providerBaseUrl";
 import { openclawKeys } from "@/hooks/useOpenClaw";

+interface UseProviderActionsOptions {
+  /** 代理服务是否正在运行 */
+  isProxyRunning?: boolean;
+  /** 当前应用的代理接管是否激活 */
+  isTakeoverActive?: boolean;
+}
+
 /**
 * Hook for managing provider actions (add, update, delete, switch)
 * Extracts business logic from App.tsx
 */
-export function useProviderActions(activeApp: AppId) {
+export function useProviderActions(
+  activeApp: AppId,
+  options: UseProviderActionsOptions = {},
+) {
+  const { isProxyRunning = false, isTakeoverActive = false } = options;
  const { t } = useTranslation();
  const queryClient = useQueryClient();

@@ -133,30 +146,11 @@ export function useProviderActions(activeApp: AppId) {
  // 切换供应商
  const switchProvider = useCallback(
    async (provider: Provider) => {
-      try {
-        await switchProviderMutation.mutateAsync(provider.id);
-        await syncClaudePlugin(provider);
-
-        // 根据供应商类型显示不同的成功提示
-        if (
-          activeApp === "claude" &&
-          provider.category !== "official" &&
-          provider.meta?.apiFormat === "openai_chat"
-        ) {
-          // OpenAI Chat 格式供应商：显示代理提示
-          toast.info(
-            t("notifications.openAIChatFormatHint", {
-              defaultValue:
-                "此供应商使用 OpenAI Chat 格式，需要开启代理服务才能正常使用",
-            }),
-            {
-              duration: 5000,
-              closeButton: true,
-            },
-          );
-        } else {
-          // 普通供应商：显示切换成功
-          // OpenCode/OpenClaw: show "added to config" message instead of "switched"
+      // 官方供应商不需要检查
+      if (provider.category === "official") {
+        try {
+          await switchProviderMutation.mutateAsync(provider.id);
+          await syncClaudePlugin(provider);
          const isMultiProviderApp =
            activeApp === "opencode" || activeApp === "openclaw";
          const messageKey = isMultiProviderApp
@@ -165,7 +159,94 @@ export function useProviderActions(activeApp: AppId) {
          const defaultMessage = isMultiProviderApp
            ? "已添加到配置"
            : "切换成功！";
+          toast.success(
+            t(messageKey, { defaultValue: defaultMessage }),
+            {
+              closeButton: true,
+            },
+          );
+        } catch {
+          // 错误提示由 mutation 处理
+        }
+        return;
+      }

+      // 提取 base URL 和 API 格式
+      const baseUrl = extractProviderBaseUrl(provider, activeApp);
+      const apiFormat = provider.meta?.apiFormat;
+
+      // 调用后端 API 检查是否需要代理（统一由后端控制）
+      let proxyRequirement: string | null = null;
+      let proxyRequirementCheckFailed = false;
+      if (baseUrl || apiFormat) {
+        try {
+          proxyRequirement = await proxyApi.checkProxyRequirement(
+            activeApp,
+            baseUrl || "",
+            apiFormat,
+          );
+        } catch (error) {
+          console.error("Failed to check proxy requirement:", error);
+          proxyRequirementCheckFailed = true;
+        }
+      }
+
+      // 如果需要代理但代理未激活，阻止切换并提示
+      if (proxyRequirement && !(isProxyRunning && isTakeoverActive)) {
+        let message: string;
+
+        if (proxyRequirement === "openai_chat_format") {
+          message = t("notifications.openAIChatFormatRequiresProxy", {
+            defaultValue:
+              "此供应商使用 OpenAI Chat 格式，需要开启代理服务进行格式转换才能正常使用。请先开启代理并接管当前应用。",
+          });
+        } else if (proxyRequirement === "full_url") {
+          // 用户填了全链接（如 /v1/messages 结尾）
+          message = t("notifications.fullUrlRequiresProxy", {
+            defaultValue:
+              "此供应商配置了完整 API 路径，直连模式下客户端可能会重复追加路径。请先开启代理并接管当前应用。",
+          });
+        } else {
+          // url_mismatch: 直连地址和代理地址不匹配
+          message = t("notifications.urlMismatchRequiresProxy", {
+            defaultValue:
+              "此供应商的请求地址配置与 API 格式不匹配，直连模式下无法正常工作。请先开启代理并接管当前应用。",
+          });
+        }
+
+        toast.warning(message, {
+          duration: 6000,
+          closeButton: true,
+        });
+        return; // 阻止切换
+      }
+
+      try {
+        await switchProviderMutation.mutateAsync(provider.id);
+        await syncClaudePlugin(provider);
+
+        const isMultiProviderApp =
+          activeApp === "opencode" || activeApp === "openclaw";
+        const messageKey = isMultiProviderApp
+          ? "notifications.addToConfigSuccess"
+          : "notifications.switchSuccess";
+        const defaultMessage = isMultiProviderApp ? "已添加到配置" : "切换成功！";
+
+        if (proxyRequirementCheckFailed && baseUrl) {
+          toast.success(
+            t("notifications.switchAppliedUnverified", {
+              defaultValue: "切换已应用（未验证直连兼容性）",
+            }),
+            {
+              description: t("notifications.switchAppliedUnverifiedDesc", {
+                defaultValue:
+                  "未能验证该端点是否需要代理。如果切换后无法正常使用，请开启代理并接管当前应用。",
+              }),
+              closeButton: true,
+              duration: 6000,
+            },
+          );
+        } else {
          toast.success(t(messageKey, { defaultValue: defaultMessage }), {
            closeButton: true,
          });
@@ -174,7 +255,14 @@ export function useProviderActions(activeApp: AppId) {
        // 错误提示由 mutation 处理
      }
    },
-    [switchProviderMutation, syncClaudePlugin, activeApp, t],
+    [
+      switchProviderMutation,
+      syncClaudePlugin,
+      activeApp,
+      t,
+      isProxyRunning,
+      isTakeoverActive,
+    ],
  );

  // 删除供应商
--- a/src/i18n/locales/en.json
+++ b/src/i18n/locales/en.json
@@ -167,6 +167,14 @@
    "settingsSaved": "Settings saved",
    "settingsSaveFailed": "Failed to save settings: {{error}}",
    "openAIChatFormatHint": "This provider uses OpenAI Chat format and requires the proxy service to be enabled",
+    "openAIChatFormatRequiresProxy": "This provider uses OpenAI Chat format and requires the proxy service for format conversion. Please enable the proxy and takeover the current app first.",
+    "fullUrlRequiresProxy": "This provider is configured with a full API path. The client may append duplicate paths in direct connection mode. Please enable the proxy and takeover the current app first.",
+    "urlMismatchRequiresProxy": "This provider's request URL configuration does not match the API format. It cannot work properly in direct connection mode. Please enable the proxy and takeover the current app first.",
+    "fullUrlWarningOnDisable": "The current provider is configured with a full API path or special format. It may not work properly after disabling the proxy. Consider switching to a base URL configuration or keep the proxy enabled.",
+    "openAIChatFormatWarningOnDisable": "The current provider uses OpenAI Chat format. It may not work properly after disabling the proxy. Consider keeping the proxy enabled.",
+    "urlMismatchWarningOnDisable": "The current provider's request URL configuration may rely on the proxy. It may not work properly after disabling the proxy. Consider switching to a base URL configuration or keep the proxy enabled.",
+    "switchAppliedUnverified": "Switch applied (direct mode not verified)",
+    "switchAppliedUnverifiedDesc": "Unable to verify whether this endpoint requires the proxy. If it doesn't work after switching, enable the proxy and takeover the current app.",
    "openLinkFailed": "Failed to open link",
    "openclawModelsRegistered": "Models have been registered to /model list",
    "openclawDefaultModelSet": "Set as default model",
@@ -594,6 +602,12 @@
    "apiHint": "💡 Fill in Claude API compatible service endpoint, avoid trailing slash",
    "apiHintOAI": "💡 Fill in OpenAI Chat Completions compatible service endpoint, avoid trailing slash",
    "codexApiHint": "💡 Fill in service endpoint compatible with OpenAI Response format",
+    "directRequestUrl": "CLI Direct Request URL:",
+    "directRequestUrlDesc": "Actual request URL after CLI appends default suffix",
+    "proxyRequestUrl": "CCS Proxy Request URL:",
+    "proxyRequestUrlDesc": "URL forwarded to upstream after CCS smart path detection",
+    "fullUrlWarningTitle": "Full API path detected",
+    "fullUrlWarning": "The URL contains a full API path. This configuration only works in proxy mode. For direct connection mode, please enter only the base URL.",
    "fillSupplierName": "Please fill in provider name",
    "fillConfigContent": "Please fill in configuration content",
    "fillParameter": "Please fill in {{label}}",
@@ -1488,6 +1502,10 @@
    }
  },
  "proxy": {
+    "takeover": {
+      "toggleFailed": "Failed to toggle takeover",
+      "toggleFailedDesc": "Check proxy service status and permissions, then try again."
+    },
    "panel": {
      "serviceAddress": "Service Address",
      "addressCopied": "Address copied",
--- a/src/i18n/locales/ja.json
+++ b/src/i18n/locales/ja.json
@@ -167,6 +167,14 @@
    "settingsSaved": "設定を保存しました",
    "settingsSaveFailed": "設定の保存に失敗しました: {{error}}",
    "openAIChatFormatHint": "このプロバイダーは OpenAI Chat フォーマットを使用しており、プロキシサービスの有効化が必要です",
+    "openAIChatFormatRequiresProxy": "このプロバイダーは OpenAI Chat フォーマットを使用しており、フォーマット変換のためにプロキシサービスが必要です。先にプロキシを有効にして、現在のアプリをテイクオーバーしてください。",
+    "fullUrlRequiresProxy": "このプロバイダーは完全な API パスで構成されています。直接接続モードではクライアントがパスを重複追加する可能性があります。先にプロキシを有効にして、現在のアプリをテイクオーバーしてください。",
+    "urlMismatchRequiresProxy": "このプロバイダーのリクエスト URL 設定が API フォーマットと一致しません。直接接続モードでは正常に動作しません。先にプロキシを有効にして、現在のアプリをテイクオーバーしてください。",
+    "fullUrlWarningOnDisable": "現在のプロバイダーは完全な API パスまたは特殊なフォーマットで構成されています。プロキシを無効にすると正常に動作しない可能性があります。ベース URL 設定に変更するか、プロキシを有効のままにすることをお勧めします。",
+    "openAIChatFormatWarningOnDisable": "現在のプロバイダーは OpenAI Chat フォーマットを使用しています。プロキシを無効にすると正常に動作しない可能性があります。プロキシを有効のままにすることをお勧めします。",
+    "urlMismatchWarningOnDisable": "現在のプロバイダーのリクエスト URL 設定はプロキシに依存している可能性があります。プロキシを無効にすると正常に動作しない可能性があります。ベース URL 設定に変更するか、プロキシを有効のままにすることをお勧めします。",
+    "switchAppliedUnverified": "切り替えを適用しました（直接接続は未検証）",
+    "switchAppliedUnverifiedDesc": "このエンドポイントがプロキシを必要とするか検証できませんでした。切り替え後に動作しない場合は、プロキシを有効にして現在のアプリをテイクオーバーしてください。",
    "openLinkFailed": "リンクを開けませんでした",
    "openclawModelsRegistered": "モデルが /model リストに登録されました",
    "openclawDefaultModelSet": "デフォルトモデルに設定しました",
@@ -594,6 +602,12 @@
    "apiHint": "💡 Claude API 互換サービスのエンドポイントを入力してください。末尾にスラッシュを付けないでください",
    "apiHintOAI": "💡 OpenAI Chat Completions 互換サービスのエンドポイントを入力してください。末尾にスラッシュを付けないでください",
    "codexApiHint": "💡 OpenAI Response 互換のサービスエンドポイントを入力してください",
+    "directRequestUrl": "CLI 直接リクエスト URL：",
+    "directRequestUrlDesc": "CLI がデフォルトサフィックスを追加した後の実際のリクエスト URL",
+    "proxyRequestUrl": "CCS プロキシリクエスト URL：",
+    "proxyRequestUrlDesc": "CCS がスマートパス検出後にアップストリームへ転送する URL",
+    "fullUrlWarningTitle": "完全な API パスを検出",
+    "fullUrlWarning": "URL には完全な API パスが含まれています。この設定はプロキシモードでのみ有効です。直接接続モードではベース URL のみを入力してください。",
    "fillSupplierName": "プロバイダー名を入力してください",
    "fillConfigContent": "設定内容を入力してください",
    "fillParameter": "{{label}} を入力してください",
@@ -1486,6 +1500,10 @@
    }
  },
  "proxy": {
+    "takeover": {
+      "toggleFailed": "テイクオーバーの切り替えに失敗しました",
+      "toggleFailedDesc": "プロキシサービスの状態と権限を確認して、もう一度お試しください。"
+    },
    "panel": {
      "serviceAddress": "サービスアドレス",
      "addressCopied": "アドレスをコピーしました",
--- a/src/i18n/locales/zh.json
+++ b/src/i18n/locales/zh.json
@@ -167,6 +167,14 @@
    "settingsSaved": "设置已保存",
    "settingsSaveFailed": "保存设置失败：{{error}}",
    "openAIChatFormatHint": "此供应商使用 OpenAI Chat 格式，需要开启代理服务才能正常使用",
+    "openAIChatFormatRequiresProxy": "此供应商使用 OpenAI Chat 格式，需要开启代理服务进行格式转换才能正常使用。请先开启代理并接管当前应用。",
+    "fullUrlRequiresProxy": "此供应商配置了完整 API 路径，直连模式下客户端可能会重复追加路径。请先开启代理并接管当前应用。",
+    "urlMismatchRequiresProxy": "此供应商的请求地址配置与 API 格式不匹配，直连模式下无法正常工作。请先开启代理并接管当前应用。",
+    "fullUrlWarningOnDisable": "当前供应商配置了完整 API 路径或特殊格式，关闭代理后可能无法正常工作。建议更换为基础地址配置或保持代理开启。",
+    "openAIChatFormatWarningOnDisable": "当前供应商使用 OpenAI Chat 格式，关闭代理后可能无法正常工作。建议保持代理开启。",
+    "urlMismatchWarningOnDisable": "当前供应商的请求地址配置可能依赖代理模式，关闭代理后可能无法正常工作。建议更换为基础地址配置或保持代理开启。",
+    "switchAppliedUnverified": "切换已应用（未验证直连兼容性）",
+    "switchAppliedUnverifiedDesc": "未能验证该端点是否需要代理。如果切换后无法正常使用，请开启代理并接管当前应用。",
    "openLinkFailed": "链接打开失败",
    "openclawModelsRegistered": "模型已注册到 /model 列表",
    "openclawDefaultModelSet": "已设为默认模型",
@@ -594,6 +602,12 @@
    "apiHint": "💡 填写兼容 Claude API 的服务端点地址，不要以斜杠结尾",
    "apiHintOAI": "💡 填写兼容 OpenAI Chat Completions 的服务端点地址，不要以斜杠结尾",
    "codexApiHint": "💡 填写兼容 OpenAI Response 格式的服务端点地址",
+    "directRequestUrl": "CLI 直连请求地址：",
+    "directRequestUrlDesc": "CLI 硬拼接默认后缀后的实际请求地址",
+    "proxyRequestUrl": "CCS 代理请求地址：",
+    "proxyRequestUrlDesc": "CCS 智能拼接后转发到上游的地址",
+    "fullUrlWarningTitle": "检测到完整 API 路径",
+    "fullUrlWarning": "填写了包含 API 路径的完整地址，此配置仅在代理模式下生效。直连模式下请只填写基础地址。",
    "fillSupplierName": "请填写供应商名称",
    "fillConfigContent": "请填写配置内容",
    "fillParameter": "请填写 {{label}}",
@@ -1488,6 +1502,10 @@
    }
  },
  "proxy": {
+    "takeover": {
+      "toggleFailed": "切换接管状态失败",
+      "toggleFailedDesc": "请检查代理服务状态与权限，然后重试。"
+    },
    "panel": {
      "serviceAddress": "服务地址",
      "addressCopied": "地址已复制",
--- a/src/lib/api/proxy.ts
+++ b/src/lib/api/proxy.ts
@@ -117,4 +117,40 @@ export const proxyApi = {
  async setPricingModelSource(appType: string, value: string): Promise<void> {
    return invoke("set_pricing_model_source", { appType, value });
  },
+
+  // ========== URL 预览 API ==========
+
+  /**
+   * 构建 URL 预览
+   * 根据 app_type、base_url 和 api_format 计算直连和代理模式的请求地址
+   */
+  async buildUrlPreview(
+    appType: string,
+    baseUrl: string,
+    apiFormat?: string,
+  ): Promise<UrlPreview> {
+    return invoke("build_url_preview", { appType, baseUrl, apiFormat });
+  },
+
+  /**
+   * 检查是否需要代理
+   * 返回需要代理的原因，null 表示不需要代理
+   */
+  async checkProxyRequirement(
+    appType: string,
+    baseUrl: string,
+    apiFormat?: string,
+  ): Promise<string | null> {
+    return invoke("check_proxy_requirement", { appType, baseUrl, apiFormat });
+  },
 };
+
+/** URL 预览结果 */
+export interface UrlPreview {
+  /** 直连模式请求地址 */
+  direct_url: string;
+  /** 代理模式请求地址 */
+  proxy_url: string;
+  /** 是否为全链接（base_url 已包含 API 路径） */
+  is_full_url: boolean;
+}
--- a/src/types.ts
+++ b/src/types.ts
@@ -140,10 +140,13 @@ export interface ProviderMeta {
  costMultiplier?: string;
  // 供应商计费模式来源
  pricingModelSource?: string;
-  // Claude API 格式（仅 Claude 供应商使用）
+  // 供应商 API 格式
+  // Claude:
  // - "anthropic": 原生 Anthropic Messages API 格式，直接透传
  // - "openai_chat": OpenAI Chat Completions 格式，需要格式转换
-  apiFormat?: "anthropic" | "openai_chat";
+  // Codex:
+  // - "responses": OpenAI Responses API
+  apiFormat?: "anthropic" | "openai_chat" | "responses";
 }

 // Skill 同步方式
--- a/src/utils/providerBaseUrl.ts
+++ b/src/utils/providerBaseUrl.ts
@@ -0,0 +1,43 @@
+import type { AppId } from "@/lib/api";
+import type { Provider } from "@/types";
+import { extractCodexBaseUrl } from "@/utils/providerConfigUtils";
+
+/**
+ * 从 provider 配置中提取 base URL（用于代理检查/预览）
+ */
+export function extractProviderBaseUrl(
+  provider: Provider,
+  appId: AppId,
+): string | null {
+  try {
+    const config = provider.settingsConfig;
+    if (!config) return null;
+
+    if (appId === "claude") {
+      const envUrl = config?.env?.ANTHROPIC_BASE_URL;
+      return typeof envUrl === "string" ? envUrl.trim() : null;
+    }
+
+    if (appId === "codex" || appId === "opencode") {
+      const tomlConfig = config?.config;
+      if (typeof tomlConfig === "string") {
+        return extractCodexBaseUrl(tomlConfig) ?? null;
+      }
+
+      const baseUrl = config?.base_url;
+      return typeof baseUrl === "string" ? baseUrl.trim() : null;
+    }
+
+    if (appId === "gemini") {
+      const envUrl = config?.env?.GOOGLE_GEMINI_BASE_URL;
+      if (typeof envUrl === "string") return envUrl.trim();
+
+      const baseUrl = config?.GEMINI_API_BASE || config?.base_url;
+      return typeof baseUrl === "string" ? baseUrl.trim() : null;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
--- a/src/utils/providerConfigUtils.ts
+++ b/src/utils/providerConfigUtils.ts
@@ -468,6 +468,41 @@ export const setCodexBaseUrl = (
  return `${prefix}${replacementLine}\n`;
 };

+// 在 Codex 的 TOML 配置文本中写入或更新 wire_api 字段（仅保留 responses）
+export const setCodexWireApi = (
+  configText: string,
+  wireApi: "responses" = "responses",
+): string => {
+  const normalizedText = normalizeQuotes(configText);
+  const replacementLine = `wire_api = "${wireApi}"`;
+  const pattern = /^wire_api\s*=\s*(["'])(responses|chat)\1/m;
+
+  if (pattern.test(normalizedText)) {
+    return normalizedText.replace(pattern, replacementLine);
+  }
+
+  // 优先插入到 base_url 后，提升可读性
+  const baseUrlPattern = /^base_url\s*=\s*["'][^"']+["']/m;
+  const match = normalizedText.match(baseUrlPattern);
+  if (match && match.index !== undefined) {
+    const endOfLine = normalizedText.indexOf("\n", match.index);
+    if (endOfLine !== -1) {
+      return (
+        normalizedText.slice(0, endOfLine + 1) +
+        replacementLine +
+        "\n" +
+        normalizedText.slice(endOfLine + 1)
+      );
+    }
+  }
+
+  const prefix =
+    normalizedText && !normalizedText.endsWith("\n")
+      ? `${normalizedText}\n`
+      : normalizedText;
+  return `${prefix}${replacementLine}\n`;
+};
+
 // ========== Codex model name utils ==========

 // 从 Codex 的 TOML 配置文本中提取 model 字段（支持单/双引号）
Author	SHA1	Message	Date
YoVinchen	6637858f42	fix(proxy): resolve merge conflict in claude adapter — combine smart URL path detection with beta=true Merge both features from feat/smart-url-path-detection and main: - Smart URL path detection: skip appending endpoint when base_url already ends with API path - URL suffix preservation: preserve query/fragment from base_url via split_url_suffix - v1 dedup: boundary-safe deduplication of /v1/v1 - ?beta=true: auto-append for /v1/messages endpoints (DuckCoding compatibility) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-20 18:09:05 +08:00
YoVinchen	b8e2573730	fix(proxy): unify proxy requirement check to backend and add OpenClaw support	2026-02-15 14:07:46 +08:00
YoVinchen	98f9b8fb3c	Merge branch 'main' into feat/smart-url-path-detection # Conflicts: # src/App.tsx # src/hooks/useProviderActions.ts # src/i18n/locales/en.json # src/i18n/locales/ja.json # src/i18n/locales/zh.json	2026-02-15 13:48:28 +08:00
YoVinchen	c1048ebcbe	refactor(proxy): remove Codex Chat Completions API format support Codex CLI only uses OpenAI Responses API. Remove unused Chat Completions routes, handler, parser config, URL builder branches, frontend API format selector, and stale i18n keys. Claude openai_chat support is preserved.	2026-02-12 23:00:46 +08:00
YoVinchen	fad81d6fa4	fix(proxy): strip beta=true query param when transforming to chat/completions	2026-02-12 14:49:51 +08:00
YoVinchen	f0e09da83b	fix(proxy): passthrough client query params instead of forcing beta=true	2026-02-12 14:14:50 +08:00
YoVinchen	b3188c242a	fix(proxy): only append beta=true query param for /v1/messages endpoint	2026-02-12 13:50:59 +08:00
YoVinchen	e2c8a2ba15	Merge branch 'main' into feat/smart-url-path-detection	2026-02-11 23:39:21 +08:00
YoVinchen	246ec65789	fix(proxy): unify preview/runtime URL rules and proxy checks - align Codex preview URL building with runtime /v1 normalization - align Claude full-url detection with runtime adapter patterns - reflect Claude ?beta=true in proxy preview and avoid query-only mismatch false positives - enforce openai_chat proxy requirement even when baseUrl is missing - wire Codex api format selector through ProviderForm and persist meta/config - fix EndpointField stale async preview race on clear - add pending feedback for ProxyToggle pre-disable checks - deduplicate provider baseUrl extraction into a shared util	2026-02-11 23:37:38 +08:00
YoVinchen	fd2793abc4	merge: resolve i18n conflicts between smart-url-path-detection and main	2026-02-09 12:58:01 +08:00
YoVinchen	08bbfc3d3a	merge: resolve conflict in SessionManagerPage with main Accept main's removal of local terminalTarget state, which was replaced by global settings in refactor(terminal) commit.	2026-02-06 16:27:49 +08:00
YoVinchen	75d78da920	fix(proxy): preserve URL query/fragment and improve error handling Extract shared URL utilities to handle query strings and fragments correctly. Add race condition fix for URL preview, improve proxy toggle error feedback, and support Codex chat format proxy endpoint.	2026-02-05 16:48:44 +08:00
YoVinchen	b12d12790b	refactor(proxy): unify URL building logic in backend Move URL preview and proxy requirement checks from frontend to a centralized Rust module. This ensures consistency between the endpoint field preview and actual proxy behavior.	2026-02-05 14:30:15 +08:00
YoVinchen	7f6ce72a88	feat(proxy): add smart URL path detection for full API endpoints - Detect when base URL already contains API path suffix (/v1/messages, /v1/chat/completions, etc.) - Show direct and proxy request URL previews in endpoint field - Block provider switch when proxy is required but not active - Add API format selector for Codex providers (Responses/Chat)	2026-02-05 00:52:10 +08:00
YoVinchen	4b18c232f4	style: format code and apply clippy lint fixes	2026-02-04 10:44:45 +08:00