feat(proxy): add full URL mode and refactor endpoint rewriting (#1561)

* feat(proxy): add full URL mode and refactor endpoint rewriting

- Add `isFullUrl` provider meta to treat base_url as complete API endpoint
- Remove hardcoded `?beta=true` from Claude adapter, pass through from client
- Refactor forwarder endpoint rewriting with proper query string handling
- Block provider switching when proxy is required but not running
- Add full URL toggle UI in endpoint field with i18n (zh/en/ja)

* refactor(proxy): remove beta query handling

* fix(proxy): strip beta query when rewriting Claude endpoints

* feat(codex): complete full URL support

* refactor(ui): refine full URL endpoint hint

src/App.tsx

@@ -255,7 +255,7 @@ function App() {
     deleteProvider,
     saveUsageScript,
     setAsDefaultModel,
-  } = useProviderActions(activeApp);
+  } = useProviderActions(activeApp, isProxyRunning);
 
   const disableOmoMutation = useDisableCurrentOmo();
   const handleDisableOmo = () => {

src/components/providers/forms/ClaudeFormFields.tsx

@@ -108,6 +108,10 @@ interface ClaudeFormFieldsProps {
   // Auth Field (ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY)
   apiKeyField: ClaudeApiKeyField;
   onApiKeyFieldChange: (field: ClaudeApiKeyField) => void;
+
+  // Full URL mode
+  isFullUrl: boolean;
+  onFullUrlChange: (value: boolean) => void;
 }
 
 export function ClaudeFormFields({
@@ -149,6 +153,8 @@ export function ClaudeFormFields({
   onApiFormatChange,
   apiKeyField,
   onApiKeyFieldChange,
+  isFullUrl,
+  onFullUrlChange,
 }: ClaudeFormFieldsProps) {
   const { t } = useTranslation();
   const hasAnyAdvancedValue = !!(
@@ -379,6 +385,9 @@ export function ClaudeFormFields({
                 : t("providerForm.apiHint")
           }
           onManageClick={() => onEndpointModalToggle(true)}
+          showFullUrlToggle={true}
+          isFullUrl={isFullUrl}
+          onFullUrlChange={onFullUrlChange}
         />
       )}
 

src/components/providers/forms/CodexFormFields.tsx

@@ -22,6 +22,8 @@ interface CodexFormFieldsProps {
   shouldShowSpeedTest: boolean;
   codexBaseUrl: string;
   onBaseUrlChange: (url: string) => void;
+  isFullUrl: boolean;
+  onFullUrlChange: (value: boolean) => void;
   isEndpointModalOpen: boolean;
   onEndpointModalToggle: (open: boolean) => void;
   onCustomEndpointsChange?: (endpoints: string[]) => void;
@@ -49,6 +51,8 @@ export function CodexFormFields({
   shouldShowSpeedTest,
   codexBaseUrl,
   onBaseUrlChange,
+  isFullUrl,
+  onFullUrlChange,
   isEndpointModalOpen,
   onEndpointModalToggle,
   onCustomEndpointsChange,
@@ -93,6 +97,9 @@ export function CodexFormFields({
           onChange={onBaseUrlChange}
           placeholder={t("providerForm.codexApiEndpointPlaceholder")}
           hint={t("providerForm.codexApiHint")}
+          showFullUrlToggle
+          isFullUrl={isFullUrl}
+          onFullUrlChange={onFullUrlChange}
           onManageClick={() => onEndpointModalToggle(true)}
         />
       )}

src/components/providers/forms/ProviderForm.tsx

@@ -162,6 +162,11 @@ export function ProviderForm({
   const [endpointAutoSelect, setEndpointAutoSelect] = useState<boolean>(
     () => initialData?.meta?.endpointAutoSelect ?? true,
   );
+  const supportsFullUrl = appId === "claude" || appId === "codex";
+  const [localIsFullUrl, setLocalIsFullUrl] = useState<boolean>(() => {
+    if (!supportsFullUrl) return false;
+    return initialData?.meta?.isFullUrl ?? false;
+  });
 
   const [testConfig, setTestConfig] = useState<ProviderTestConfig>(
     () => initialData?.meta?.testConfig ?? { enabled: false },
@@ -201,6 +206,9 @@ export function ProviderForm({
       setDraftCustomEndpoints([]);
     }
     setEndpointAutoSelect(initialData?.meta?.endpointAutoSelect ?? true);
+    setLocalIsFullUrl(
+      supportsFullUrl ? (initialData?.meta?.isFullUrl ?? false) : false,
+    );
     setTestConfig(initialData?.meta?.testConfig ?? { enabled: false });
     setProxyConfig(initialData?.meta?.proxyConfig ?? { enabled: false });
     setPricingConfig({
@@ -212,7 +220,7 @@ export function ProviderForm({
         initialData?.meta?.pricingModelSource,
       ),
     });
-  }, [appId, initialData]);
+  }, [appId, initialData, supportsFullUrl]);
 
   const defaultValues: ProviderFormData = useMemo(
     () => ({
@@ -941,6 +949,10 @@ export function ProviderForm({
         localApiKeyField !== "ANTHROPIC_AUTH_TOKEN"
           ? localApiKeyField
           : undefined,
+      isFullUrl:
+        supportsFullUrl && category !== "official" && localIsFullUrl
+          ? true
+          : undefined,
     };
 
     await onSubmit(payload);
@@ -1180,6 +1192,7 @@ export function ProviderForm({
     }
 
     setLocalApiKeyField(preset.apiKeyField ?? "ANTHROPIC_AUTH_TOKEN");
+    setLocalIsFullUrl(false);
 
     form.reset({
       name: preset.nameKey ? t(preset.nameKey) : preset.name,
@@ -1402,6 +1415,8 @@ export function ProviderForm({
             onApiFormatChange={handleApiFormatChange}
             apiKeyField={localApiKeyField}
             onApiKeyFieldChange={handleApiKeyFieldChange}
+            isFullUrl={localIsFullUrl}
+            onFullUrlChange={setLocalIsFullUrl}
           />
         )}
 
@@ -1418,6 +1433,8 @@ export function ProviderForm({
             shouldShowSpeedTest={shouldShowSpeedTest}
             codexBaseUrl={codexBaseUrl}
             onBaseUrlChange={handleCodexBaseUrlChange}
+            isFullUrl={localIsFullUrl}
+            onFullUrlChange={setLocalIsFullUrl}
             isEndpointModalOpen={isCodexEndpointModalOpen}
             onEndpointModalToggle={setIsCodexEndpointModalOpen}
             onCustomEndpointsChange={

src/components/providers/forms/shared/EndpointField.tsx

@@ -1,7 +1,8 @@
 import { useTranslation } from "react-i18next";
 import { FormLabel } from "@/components/ui/form";
 import { Input } from "@/components/ui/input";
-import { Zap } from "lucide-react";
+import { Switch } from "@/components/ui/switch";
+import { Link2, Zap } from "lucide-react";
 
 interface EndpointFieldProps {
   id: string;
@@ -13,6 +14,9 @@ interface EndpointFieldProps {
   showManageButton?: boolean;
   onManageClick?: () => void;
   manageButtonLabel?: string;
+  showFullUrlToggle?: boolean;
+  isFullUrl?: boolean;
+  onFullUrlChange?: (value: boolean) => void;
 }
 
 export function EndpointField({
@@ -25,18 +29,56 @@ export function EndpointField({
   showManageButton = true,
   onManageClick,
   manageButtonLabel,
+  showFullUrlToggle = false,
+  isFullUrl = false,
+  onFullUrlChange,
 }: EndpointFieldProps) {
   const { t } = useTranslation();
 
   const defaultManageLabel = t("providerForm.manageAndTest", {
     defaultValue: "管理和测速",
   });
+  const effectiveHint =
+    showFullUrlToggle && isFullUrl
+      ? t("providerForm.fullUrlHint", {
+          defaultValue:
+            "💡 请填写完整请求 URL，并且必须开启代理后使用；代理将直接使用此 URL，不拼接路径",
+        })
+      : hint;
 
   return (
     <div className="space-y-2">
-      <div className="flex items-center justify-between">
-        <FormLabel htmlFor={id}>{label}</FormLabel>
-        {showManageButton && onManageClick && (
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div className="flex flex-wrap items-center gap-3">
+          <FormLabel htmlFor={id}>{label}</FormLabel>
+          {showFullUrlToggle && onFullUrlChange ? (
+            <div className="flex items-center gap-2 rounded-full border border-border/70 bg-muted/30 px-2.5 py-1">
+              <Link2
+                className={`h-3.5 w-3.5 ${
+                  isFullUrl ? "text-primary" : "text-muted-foreground"
+                }`}
+              />
+              <span
+                className={`text-xs font-medium ${
+                  isFullUrl ? "text-foreground" : "text-muted-foreground"
+                }`}
+              >
+                {t("providerForm.fullUrlLabel", {
+                  defaultValue: "完整 URL",
+                })}
+              </span>
+              <Switch
+                checked={isFullUrl}
+                onCheckedChange={onFullUrlChange}
+                aria-label={t("providerForm.fullUrlLabel", {
+                  defaultValue: "完整 URL",
+                })}
+                className="h-5 w-9"
+              />
+            </div>
+          ) : null}
+        </div>
+        {showManageButton && onManageClick ? (
           <button
             type="button"
             onClick={onManageClick}
@@ -45,7 +87,7 @@ export function EndpointField({
             <Zap className="h-3.5 w-3.5" />
             {manageButtonLabel || defaultManageLabel}
           </button>
-        )}
+        ) : null}
       </div>
       <Input
         id={id}
@@ -55,9 +97,11 @@ export function EndpointField({
         placeholder={placeholder}
         autoComplete="off"
       />
-      {hint ? (
+      {effectiveHint ? (
         <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>
+          <p className="text-xs text-amber-600 dark:text-amber-400">
+            {effectiveHint}
+          </p>
         </div>
       ) : null}
     </div>

src/hooks/useProviderActions.ts

@@ -23,7 +23,7 @@ import { openclawKeys } from "@/hooks/useOpenClaw";
  * 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, isProxyRunning?: boolean) {
   const { t } = useTranslation();
   const queryClient = useQueryClient();
 
@@ -139,6 +139,26 @@ export function useProviderActions(activeApp: AppId) {
   // 切换供应商
   const switchProvider = useCallback(
     async (provider: Provider) => {
+      const requiresProxyForSwitch =
+        !isProxyRunning &&
+        provider.category !== "official" &&
+        ((activeApp === "claude" &&
+          (provider.meta?.isFullUrl ||
+            provider.meta?.apiFormat === "openai_chat" ||
+            provider.meta?.apiFormat === "openai_responses")) ||
+          (activeApp === "codex" && provider.meta?.isFullUrl));
+
+      if (
+        requiresProxyForSwitch
+      ) {
+        toast.warning(
+          t("notifications.proxyRequiredForSwitch", {
+            defaultValue: "此供应商需要代理服务，请先启动代理",
+          }),
+        );
+        return;
+      }
+
       try {
         const result = await switchProviderMutation.mutateAsync(provider.id);
         await syncClaudePlugin(provider);
@@ -192,7 +212,7 @@ export function useProviderActions(activeApp: AppId) {
         // 错误提示由 mutation 处理
       }
     },
-    [switchProviderMutation, syncClaudePlugin, activeApp, t],
+    [switchProviderMutation, syncClaudePlugin, activeApp, isProxyRunning, t],
   );
 
   // 删除供应商

src/i18n/locales/en.json

@@ -176,6 +176,7 @@
     "settingsSaveFailed": "Failed to save settings: {{error}}",
     "openAIChatFormatHint": "This provider uses OpenAI Chat format and requires the proxy service to be enabled",
     "openAIFormatHint": "This provider uses OpenAI-compatible format and requires the proxy service to be enabled",
+    "proxyRequiredForSwitch": "This provider requires the proxy service. Start the proxy first.",
     "openLinkFailed": "Failed to open link",
     "openclawModelsRegistered": "Models have been registered to /model list",
     "openclawDefaultModelSet": "Set as default model",
@@ -743,6 +744,10 @@
     "anthropicReasoningModel": "Reasoning Model (Thinking)",
     "apiFormat": "API Format",
     "apiFormatHint": "Select the input format for the provider's API",
+    "fullUrlLabel": "Full URL",
+    "fullUrlEnabled": "Full URL Mode",
+    "fullUrlDisabled": "Mark as Full URL",
+    "fullUrlHint": "💡 Enter the full request URL. This mode requires the proxy to be enabled, and the proxy will use the URL as-is without appending a path",
     "apiFormatAnthropic": "Anthropic Messages (Native)",
     "apiFormatOpenAIChat": "OpenAI Chat Completions (Requires proxy)",
     "apiFormatOpenAIResponses": "OpenAI Responses API (Requires proxy)",

src/i18n/locales/ja.json

@@ -176,6 +176,7 @@
     "settingsSaveFailed": "設定の保存に失敗しました: {{error}}",
     "openAIChatFormatHint": "このプロバイダーは OpenAI Chat フォーマットを使用しており、プロキシサービスの有効化が必要です",
     "openAIFormatHint": "このプロバイダーは OpenAI 互換フォーマットを使用しており、プロキシサービスの有効化が必要です",
+    "proxyRequiredForSwitch": "このプロバイダーにはプロキシサービスが必要です。先にプロキシを起動してください",
     "openLinkFailed": "リンクを開けませんでした",
     "openclawModelsRegistered": "モデルが /model リストに登録されました",
     "openclawDefaultModelSet": "デフォルトモデルに設定しました",
@@ -743,6 +744,10 @@
     "anthropicReasoningModel": "推論モデル（Thinking）",
     "apiFormat": "API フォーマット",
     "apiFormatHint": "プロバイダー API の入力フォーマットを選択",
+    "fullUrlLabel": "フル URL",
+    "fullUrlEnabled": "フル URL モード",
+    "fullUrlDisabled": "フル URL として設定",
+    "fullUrlHint": "💡 完全なリクエスト URL を入力してください。このモードはプロキシを有効にして使用する必要があり、プロキシはこの URL をそのまま使用し、パスを追加しません",
     "apiFormatAnthropic": "Anthropic Messages（ネイティブ）",
     "apiFormatOpenAIChat": "OpenAI Chat Completions（プロキシが必要）",
     "apiFormatOpenAIResponses": "OpenAI Responses API（プロキシが必要）",

src/i18n/locales/zh.json

@@ -176,6 +176,7 @@
     "settingsSaveFailed": "保存设置失败：{{error}}",
     "openAIChatFormatHint": "此供应商使用 OpenAI Chat 格式，需要开启代理服务才能正常使用",
     "openAIFormatHint": "此供应商使用 OpenAI 兼容格式，需要开启代理服务才能正常使用",
+    "proxyRequiredForSwitch": "此供应商需要代理服务，请先启动代理",
     "openLinkFailed": "链接打开失败",
     "openclawModelsRegistered": "模型已注册到 /model 列表",
     "openclawDefaultModelSet": "已设为默认模型",
@@ -743,6 +744,10 @@
     "anthropicReasoningModel": "推理模型 (Thinking)",
     "apiFormat": "API 格式",
     "apiFormatHint": "选择供应商 API 的输入格式",
+    "fullUrlLabel": "完整 URL",
+    "fullUrlEnabled": "完整 URL 模式",
+    "fullUrlDisabled": "标记为完整 URL",
+    "fullUrlHint": "💡 请填写完整请求 URL，并且必须开启代理后使用；代理将直接使用此 URL，不拼接路径",
     "apiFormatAnthropic": "Anthropic Messages (原生)",
     "apiFormatOpenAIChat": "OpenAI Chat Completions (需开启代理)",
     "apiFormatOpenAIResponses": "OpenAI Responses API (需开启代理)",

src/types.ts

@@ -163,6 +163,8 @@ export interface ProviderMeta {
   authBinding?: AuthBinding;
   // Claude 认证字段名
   apiKeyField?: ClaudeApiKeyField;
+  // 是否将 base_url 视为完整 API 端点（代理直接使用此 URL，不拼接路径）
+  isFullUrl?: boolean;
   // Prompt cache key for OpenAI-compatible endpoints (improves cache hit rate)
   promptCacheKey?: string;
   // 供应商类型（用于识别 Copilot 等特殊供应商）