From ba912acf72bbb20a83f651f204265c03d0af6a90 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Tue, 11 Aug 2026 21:45:56 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E5=91=98=E6=A8=A1=E5=9E=8B=E9=85=8D=E7=BD=AE=E9=A1=B5=E9=9D=A2?=
 =?UTF-8?q?=E4=B8=8E=20config.yaml=20=E6=A8=A1=E5=9E=8B=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=20API?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 /api/admin/models 路由（读写 config.yaml models 段、连接测试、写前备份），以及工作区「模型配置」管理页与侧栏入口。

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .gitignore                                    |   7 +-
 frontend-web/src/components/page-sidebar.tsx  |  15 +
 frontend-web/src/core/model-management/api.ts | 107 +++++
 .../src/core/model-management/hooks.ts        |  38 ++
 .../src/core/model-management/index.ts        |   2 +
 .../src/pages/ModelManagementPage.tsx         | 246 ++++++++++
 frontend-web/src/pages/WorkspaceRoutes.tsx    |  13 +
 .../backend/app/gateway/app.py                |  11 +-
 .../app/gateway/routers/model_management.py   | 437 ++++++++++++++++++
 .../backend/tests/test_model_management.py    |  92 ++++
 10 files changed, 962 insertions(+), 6 deletions(-)
 create mode 100644 frontend-web/src/core/model-management/api.ts
 create mode 100644 frontend-web/src/core/model-management/hooks.ts
 create mode 100644 frontend-web/src/core/model-management/index.ts
 create mode 100644 frontend-web/src/pages/ModelManagementPage.tsx
 create mode 100644 offline-backend-20260512/backend/app/gateway/routers/model_management.py
 create mode 100644 offline-backend-20260512/backend/tests/test_model_management.py

diff --git a/.gitignore b/.gitignore
index 7f1164a1..64e2ad7d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -80,8 +80,11 @@ offline-backend-20260512/backend/skill_evolution.json
 skills/
 hermes-agent-main/
 .gitignore
-offline-backend-20260512/backend/tests/*
-deploy
+offline-backend-20260512/backend/tests/*
+# Keep the model configuration regression coverage versioned even though
+# this deployment repository otherwise ignores newly added backend tests.
+!offline-backend-20260512/backend/tests/test_model_management.py
+deploy
 .history
 
 # Cloned third-party repos (local only)
diff --git a/frontend-web/src/components/page-sidebar.tsx b/frontend-web/src/components/page-sidebar.tsx
index eb1f0bd1..5119a2ba 100644
--- a/frontend-web/src/components/page-sidebar.tsx
+++ b/frontend-web/src/components/page-sidebar.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 import {
   Bell,
+  Cpu,
   ChevronLeft,
   ChevronRight,
   ChevronsUpDown,
@@ -252,6 +253,14 @@ function SecondaryNavSidebar({ headerHidden }: { headerHidden: boolean }) {
                       白名单管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/models")}
+                    >
+                      <Cpu className="size-4" />
+                      模型配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/settings/model-concurrency")}
@@ -555,6 +564,12 @@ function LegacyAccordionSidebar({
                   岗位角色配置
                 </DropdownMenuItem>
               )}
+              {isAdmin && (
+                <DropdownMenuItem onClick={() => navigate("/page/workspace/admin/models")}>
+                  <Cpu className="size-4" />
+                  模型配置
+                </DropdownMenuItem>
+              )}
               {isAdmin && (
                 <DropdownMenuItem onClick={() => navigate("/page/strategy/admin/login-whitelist")}>
                   <ShieldCheck className="size-4" />
diff --git a/frontend-web/src/core/model-management/api.ts b/frontend-web/src/core/model-management/api.ts
new file mode 100644
index 00000000..aaa74bef
--- /dev/null
+++ b/frontend-web/src/core/model-management/api.ts
@@ -0,0 +1,107 @@
+import { apiFetch } from "@/core/api";
+import { getBackendBaseURL } from "@/core/config";
+
+export interface ManagedModel {
+  name: string;
+  display_name: string | null;
+  description: string | null;
+  use: string;
+  model: string;
+  base_url: string | null;
+  request_timeout: number | null;
+  max_retries: number | null;
+  max_tokens: number | null;
+  temperature: number | null;
+  stream_usage: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled: Record<string, unknown> | null;
+  when_thinking_disabled: Record<string, unknown> | null;
+  thinking: Record<string, unknown> | null;
+  use_responses_api: boolean | null;
+  output_version: string | null;
+  extra_settings: Record<string, unknown>;
+  api_key_configured: boolean;
+  api_key_source: string | null;
+  source: "config.yaml";
+}
+
+export interface ManagedModelsResponse {
+  models: ManagedModel[];
+  config_path: string;
+  updated_at: string | null;
+}
+
+export interface ModelSavePayload {
+  name: string;
+  display_name?: string | null;
+  description?: string | null;
+  use: string;
+  model: string;
+  api_key?: string;
+  clear_api_key?: boolean;
+  base_url?: string | null;
+  request_timeout?: number | null;
+  max_retries?: number | null;
+  max_tokens?: number | null;
+  temperature?: number | null;
+  stream_usage?: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled?: Record<string, unknown> | null;
+  when_thinking_disabled?: Record<string, unknown> | null;
+  thinking?: Record<string, unknown> | null;
+  use_responses_api?: boolean | null;
+  output_version?: string | null;
+  extra_settings: Record<string, unknown>;
+}
+
+export interface ModelConnectionTestResult {
+  success: boolean;
+  latency_ms: number;
+  message: string;
+  preview?: string | null;
+}
+
+async function readError(response: Response, fallback: string): Promise<never> {
+  const payload = await response.json().catch(() => null) as { detail?: string } | null;
+  throw new Error(payload?.detail || fallback);
+}
+
+export async function loadManagedModels(): Promise<ManagedModelsResponse> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`);
+  if (!response.ok) return readError(response, "加载模型配置失败");
+  return response.json() as Promise<ManagedModelsResponse>;
+}
+
+export async function createManagedModel(payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "创建模型失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function updateManagedModel(name: string, payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "保存模型配置失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function testManagedModel(model: ModelSavePayload): Promise<ModelConnectionTestResult> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model }),
+  });
+  if (!response.ok) return readError(response, "模型连接测试失败");
+  return response.json() as Promise<ModelConnectionTestResult>;
+}
diff --git a/frontend-web/src/core/model-management/hooks.ts b/frontend-web/src/core/model-management/hooks.ts
new file mode 100644
index 00000000..65a9e4b7
--- /dev/null
+++ b/frontend-web/src/core/model-management/hooks.ts
@@ -0,0 +1,38 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import {
+  createManagedModel,
+  loadManagedModels,
+  testManagedModel,
+  updateManagedModel,
+  type ModelSavePayload,
+} from "./api";
+
+export const MANAGED_MODELS_QUERY_KEY = ["admin", "model-config"] as const;
+
+export function useManagedModels() {
+  return useQuery({
+    queryKey: MANAGED_MODELS_QUERY_KEY,
+    queryFn: loadManagedModels,
+    staleTime: 10_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useSaveManagedModel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ name, payload, isNew }: { name: string; payload: ModelSavePayload; isNew: boolean }) =>
+      isNew ? createManagedModel(payload) : updateManagedModel(name, payload),
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: MANAGED_MODELS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: ["models"] }),
+      ]);
+    },
+  });
+}
+
+export function useTestManagedModel() {
+  return useMutation({ mutationFn: testManagedModel });
+}
diff --git a/frontend-web/src/core/model-management/index.ts b/frontend-web/src/core/model-management/index.ts
new file mode 100644
index 00000000..35312304
--- /dev/null
+++ b/frontend-web/src/core/model-management/index.ts
@@ -0,0 +1,2 @@
+export * from "./api";
+export * from "./hooks";
diff --git a/frontend-web/src/pages/ModelManagementPage.tsx b/frontend-web/src/pages/ModelManagementPage.tsx
new file mode 100644
index 00000000..567a867b
--- /dev/null
+++ b/frontend-web/src/pages/ModelManagementPage.tsx
@@ -0,0 +1,246 @@
+import {
+  BotIcon,
+  ChevronDownIcon,
+  CircleAlertIcon,
+  CpuIcon,
+  EyeIcon,
+  KeyRoundIcon,
+  LoaderCircleIcon,
+  PlusIcon,
+  RefreshCwIcon,
+  Settings2Icon,
+  SparklesIcon,
+  WrenchIcon,
+} from "lucide-react";
+import { useMemo, useState, type ReactNode } from "react";
+import {
+  Button as TButton,
+  Dialog,
+  Input,
+  InputNumber,
+  MessagePlugin,
+  Select,
+  Switch,
+  Tag,
+  Textarea,
+} from "tdesign-react";
+
+import {
+  type ManagedModel,
+  type ModelSavePayload,
+  useManagedModels,
+  useSaveManagedModel,
+  useTestManagedModel,
+} from "@/core/model-management";
+import {
+  WorkspaceBody,
+  WorkspaceContainer,
+  WorkspaceHeader,
+} from "@/components/workspace/workspace-container";
+
+type ModelDraft = ModelSavePayload & {
+  api_key: string;
+  keep_existing_key: boolean;
+  extra_settings_text: string;
+};
+
+const PROVIDER_OPTIONS = [
+  { label: "OpenAI 兼容接口", value: "langchain_openai:ChatOpenAI" },
+  { label: "Anthropic", value: "langchain_anthropic:ChatAnthropic" },
+  { label: "Google Gemini", value: "langchain_google_genai:ChatGoogleGenerativeAI" },
+  { label: "Groq", value: "langchain_groq:ChatGroq" },
+  { label: "Ollama", value: "langchain_ollama:ChatOllama" },
+];
+
+const emptyDraft = (): ModelDraft => ({
+  name: "",
+  display_name: "",
+  description: "",
+  use: "langchain_openai:ChatOpenAI",
+  model: "",
+  api_key: "",
+  keep_existing_key: false,
+  clear_api_key: false,
+  base_url: "",
+  request_timeout: 30,
+  max_retries: 2,
+  max_tokens: undefined,
+  temperature: undefined,
+  stream_usage: true,
+  supports_thinking: false,
+  supports_reasoning_effort: false,
+  supports_vision: false,
+  when_thinking_enabled: null,
+  when_thinking_disabled: null,
+  thinking: null,
+  use_responses_api: null,
+  output_version: null,
+  extra_settings: {},
+  extra_settings_text: "{}",
+});
+
+function draftFromModel(model: ManagedModel): ModelDraft {
+  return {
+    ...model,
+    api_key: "",
+    keep_existing_key: model.api_key_configured,
+    clear_api_key: false,
+    extra_settings_text: JSON.stringify(model.extra_settings ?? {}, null, 2),
+  };
+}
+
+function optionalString(value: string | null | undefined): string | null {
+  const normalized = (value ?? "").trim();
+  return normalized || null;
+}
+
+function toNumber(value: number | string | null | undefined): number | undefined {
+  if (value === "" || value === null || value === undefined) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function buildPayload(draft: ModelDraft): ModelSavePayload {
+  let extraSettings: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(draft.extra_settings_text || "{}") as unknown;
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error("额外参数必须是 JSON 对象");
+    }
+    extraSettings = parsed as Record<string, unknown>;
+  } catch (error) {
+    throw error instanceof Error ? error : new Error("额外参数不是有效 JSON");
+  }
+  const payload: ModelSavePayload = {
+    name: draft.name.trim(),
+    display_name: optionalString(draft.display_name),
+    description: optionalString(draft.description),
+    use: draft.use.trim(),
+    model: draft.model.trim(),
+    clear_api_key: Boolean(draft.clear_api_key),
+    base_url: optionalString(draft.base_url),
+    request_timeout: toNumber(draft.request_timeout),
+    max_retries: toNumber(draft.max_retries),
+    max_tokens: toNumber(draft.max_tokens),
+    temperature: toNumber(draft.temperature),
+    stream_usage: draft.stream_usage,
+    supports_thinking: draft.supports_thinking,
+    supports_reasoning_effort: draft.supports_reasoning_effort,
+    supports_vision: draft.supports_vision,
+    when_thinking_enabled: draft.when_thinking_enabled,
+    when_thinking_disabled: draft.when_thinking_disabled,
+    thinking: draft.thinking,
+    use_responses_api: draft.use_responses_api,
+    output_version: optionalString(draft.output_version),
+    extra_settings: extraSettings,
+  };
+  if (draft.api_key.trim()) payload.api_key = draft.api_key.trim();
+  return payload;
+}
+
+function StatCard({ icon: Icon, label, value }: { icon: typeof CpuIcon; label: string; value: number }) {
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3 shadow-sm">
+      <span className="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary"><Icon className="size-5" /></span>
+      <div><div className="text-xl font-semibold tabular-nums">{value}</div><div className="text-xs text-muted-foreground">{label}</div></div>
+    </div>
+  );
+}
+
+function Field({ label, required = false, children }: { label: string; required?: boolean; children: ReactNode }) {
+  return <label className="space-y-1.5 text-sm font-medium">{label}{required && <span className="ml-1 text-destructive">*</span>}{children}</label>;
+}
+
+function ModelEditor({ model, onClose }: { model: ManagedModel | null; onClose: () => void }) {
+  const isNew = model === null;
+  const [draft, setDraft] = useState<ModelDraft>(() => model ? draftFromModel(model) : emptyDraft());
+  const [advanced, setAdvanced] = useState(false);
+  const [testResult, setTestResult] = useState<{ success: boolean; latency: number; message: string; preview?: string | null } | null>(null);
+  const save = useSaveManagedModel();
+  const test = useTestManagedModel();
+  const patch = (next: Partial<ModelDraft>) => setDraft((current) => ({ ...current, ...next }));
+
+  const handleTest = async () => {
+    try {
+      const payload = buildPayload(draft);
+      const result = await test.mutateAsync(payload);
+      setTestResult({ success: result.success, latency: result.latency_ms, message: result.message, preview: result.preview });
+      if (!result.success) return void MessagePlugin.error(`连接失败：${result.message}`);
+      MessagePlugin.success(`连接成功${result.latency_ms ? `，${result.latency_ms} ms` : ""}`);
+    } catch (error) {
+      MessagePlugin.error(error instanceof Error ? error.message : "连接测试失败");
+    }
+  };
+
+  const handleSave = async () => {
+    try {
+      const payload = buildPayload(draft);
+      if (!payload.name || !payload.use || !payload.model) {
+        return void MessagePlugin.warning("请填写模型标识、驱动与实际模型名");
+      }
+      await save.mutateAsync({ name: model?.name ?? payload.name, payload, isNew });
+      MessagePlugin.success(isNew ? "模型已添加，所有页面的模型选择器已刷新" : "模型配置已保存并立即生效");
+      onClose();
+    } catch (error) {
+      MessagePlugin.error(error instanceof Error ? error.message : "保存模型配置失败");
+    }
+  };
+
+  return (
+    <Dialog
+      visible
+      header={isNew ? "添加模型" : `编辑模型：${model?.display_name || model?.name}`}
+      placement="center"
+      width={860}
+      zIndex={3200}
+      confirmBtn={{ content: isNew ? "添加并启用" : "保存配置", theme: "primary" }}
+      cancelBtn="取消"
+      confirmLoading={save.isPending}
+      onClose={onClose}
+      onConfirm={() => void handleSave()}
+      onCancel={onClose}
+    >
+      <div className="max-h-[70vh] space-y-5 overflow-y-auto px-1 py-1 pr-3">
+        <div className="rounded-lg border border-primary/20 bg-primary/5 px-3 py-2 text-sm text-muted-foreground">
+          保存会直接更新当前部署的 <code className="rounded bg-background px-1 py-0.5">config.yaml</code> 模型段，自动备份并热刷新；不会中断已开始的会话。
+        </div>
+        <section className="grid gap-4 md:grid-cols-2">
+          <Field label="稳定标识" required><Input value={draft.name} disabled={!isNew} placeholder="例如 deepseek-chat" tips={isNew ? "保存后不可修改，用于智能体和运行配置引用。" : "稳定标识不可修改，避免已有配置失效。"} onChange={(value) => patch({ name: String(value) })} /></Field>
+          <Field label="显示名称"><Input value={draft.display_name ?? ""} placeholder="例如 DeepSeek Chat" onChange={(value) => patch({ display_name: String(value) })} /></Field>
+          <Field label="模型驱动" required><Select value={draft.use} options={PROVIDER_OPTIONS} filterable creatable inputProps={{ placeholder: "选择或输入 use 类路径" }} onChange={(value) => patch({ use: String(value) })} /></Field>
+          <Field label="实际模型名" required><Input value={draft.model} placeholder="例如 deepseek-chat" onChange={(value) => patch({ model: String(value) })} /></Field>
+          <Field label="Base URL"><Input value={draft.base_url ?? ""} type="url" placeholder="https://api.example.com/v1" onChange={(value) => patch({ base_url: String(value) })} /></Field>
+          <Field label="API Key"><Input value={draft.api_key} type="password" placeholder={draft.keep_existing_key && !draft.clear_api_key ? "已配置，留空则保持不变" : "可填写密钥或 $ENVIRONMENT_VARIABLE"} onChange={(value) => patch({ api_key: String(value), clear_api_key: false })} /></Field>
+          {draft.keep_existing_key && !draft.api_key && <div className="md:col-span-2 flex items-center gap-2 text-xs text-muted-foreground"><KeyRoundIcon className="size-3.5" />已配置密钥{model?.api_key_source ? `（环境变量 ${model.api_key_source}）` : ""}，不会回显。<TButton theme="default" variant="text" size="small" onClick={() => patch({ clear_api_key: !draft.clear_api_key })}>{draft.clear_api_key ? "撤销清除" : "清除密钥"}</TButton></div>}
+          <div className="md:col-span-2"><Field label="描述"><Textarea value={draft.description ?? ""} autosize={{ minRows: 2, maxRows: 4 }} placeholder="说明模型适用的任务与限制" onChange={(value) => patch({ description: String(value) })} /></Field></div>
+        </section>
+        <section className="rounded-lg border border-border p-4">
+          <div className="mb-2"><h3 className="font-medium">能力声明</h3><p className="mt-1 text-xs text-muted-foreground">这些标识决定哪些页面会向模型提供思考、视觉或工具调用入口。</p></div>
+          <div className="flex flex-wrap gap-x-5 gap-y-3 text-sm"><span className="flex items-center gap-2"><Switch value={draft.supports_thinking} onChange={(value) => patch({ supports_thinking: Boolean(value) })} />支持思考</span><span className="flex items-center gap-2"><Switch value={draft.supports_vision} onChange={(value) => patch({ supports_vision: Boolean(value) })} />支持视觉</span><span className="flex items-center gap-2"><Switch value={draft.supports_reasoning_effort} onChange={(value) => patch({ supports_reasoning_effort: Boolean(value) })} />推理档位</span></div>
+        </section>
+        <div className="flex items-center justify-between border-t pt-4"><TButton theme="default" variant="outline" loading={test.isPending} onClick={() => void handleTest()}><WrenchIcon className="mr-1.5 size-4" />测试连接</TButton><TButton theme="default" variant="text" onClick={() => setAdvanced((value) => !value)}><Settings2Icon className="mr-1.5 size-4" />高级配置 <ChevronDownIcon className={`ml-1 size-4 transition-transform ${advanced ? "rotate-180" : ""}`} /></TButton></div>
+        {testResult && <div className={`rounded-lg border px-3 py-2 text-sm ${testResult.success ? "border-primary/20 bg-primary/5 text-foreground" : "border-destructive/25 bg-destructive/5 text-destructive"}`}><div className="font-medium">{testResult.success ? "连接成功" : "连接失败"}{testResult.success && testResult.latency ? ` · ${testResult.latency} ms` : ""}</div><p className="mt-1 break-words text-xs opacity-80">{testResult.preview || testResult.message}</p></div>}
+        {advanced && <section className="space-y-4 rounded-lg border border-dashed border-border bg-muted/10 p-4"><div className="grid gap-4 md:grid-cols-3"><Field label="请求超时（秒）"><InputNumber value={draft.request_timeout ?? ""} min={1} max={600} onChange={(value) => patch({ request_timeout: toNumber(value) })} /></Field><Field label="最大重试次数"><InputNumber value={draft.max_retries ?? ""} min={0} max={20} onChange={(value) => patch({ max_retries: toNumber(value) })} /></Field><Field label="最大输出 Token"><InputNumber value={draft.max_tokens ?? ""} min={1} max={1_000_000} onChange={(value) => patch({ max_tokens: toNumber(value) })} /></Field><Field label="温度"><InputNumber value={draft.temperature ?? ""} min={0} max={2} step={0.1} decimalPlaces={1} onChange={(value) => patch({ temperature: toNumber(value) })} /></Field><span className="flex items-end gap-2 pb-1 text-sm font-medium"><Switch value={draft.stream_usage ?? true} onChange={(value) => patch({ stream_usage: Boolean(value) })} />流式 Token 统计</span></div><Field label="额外参数 JSON"><Textarea value={draft.extra_settings_text} autosize={{ minRows: 4, maxRows: 10 }} placeholder={'{\n  "extra_body": {}\n}'} onChange={(value) => patch({ extra_settings_text: String(value) })} /><p className="text-xs font-normal text-muted-foreground">保留并编辑配置文件中未在基础表单展示的兼容参数。必须为 JSON 对象。</p></Field></section>}
+      </div>
+    </Dialog>
+  );
+}
+
+export default function ModelManagementPage() {
+  const { data, isLoading, error, refetch, isFetching } = useManagedModels();
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState<"all" | "thinking" | "vision">("all");
+  const [editor, setEditor] = useState<ManagedModel | null | "new">(null);
+  const models = useMemo(() => {
+    const keyword = search.trim().toLowerCase();
+    return (data?.models ?? []).filter((model) => {
+      const matchesFilter = filter === "all" || (filter === "thinking" ? model.supports_thinking : model.supports_vision);
+      const matchesSearch = !keyword || [model.name, model.display_name, model.model, model.use].filter(Boolean).join(" ").toLowerCase().includes(keyword);
+      return matchesFilter && matchesSearch;
+    });
+  }, [data?.models, filter, search]);
+  const stats = useMemo(() => ({ total: data?.models.length ?? 0, thinking: data?.models.filter((item) => item.supports_thinking).length ?? 0, vision: data?.models.filter((item) => item.supports_vision).length ?? 0 }), [data?.models]);
+  return (
+    <WorkspaceContainer><WorkspaceHeader /><WorkspaceBody><main className="flex size-full min-h-0 flex-col overflow-y-auto bg-background px-6 py-5 md:px-8"><div className="mx-auto flex w-full max-w-7xl flex-col gap-5"><header className="flex flex-wrap items-start justify-between gap-4"><div><div className="flex items-center gap-2"><span className="flex size-9 items-center justify-center rounded-lg bg-primary/10 text-primary"><CpuIcon className="size-5" /></span><h1 className="text-2xl font-semibold tracking-tight">模型配置</h1></div><p className="mt-2 max-w-3xl text-sm leading-6 text-muted-foreground">管理当前部署 <code className="rounded bg-muted px-1 py-0.5">config.yaml</code> 中的对话模型。保存后所有页面立即可选；密钥仅可写入，永不回显。</p></div><div className="flex flex-wrap items-center gap-2"><TButton theme="default" variant="outline" loading={isFetching} onClick={() => void refetch()}><RefreshCwIcon className="mr-1.5 size-4" />刷新</TButton><TButton theme="primary" onClick={() => setEditor("new")}><PlusIcon className="mr-1.5 size-4" />添加模型</TButton></div></header><div className="grid gap-3 sm:grid-cols-3"><StatCard icon={BotIcon} label="已配置模型" value={stats.total} /><StatCard icon={SparklesIcon} label="支持思考" value={stats.thinking} /><StatCard icon={EyeIcon} label="支持视觉" value={stats.vision} /></div><section className="rounded-xl border border-border bg-card shadow-sm"><div className="flex flex-wrap items-center justify-between gap-3 border-b px-4 py-3"><div className="flex flex-wrap items-center gap-2">{([ ["all", "全部"], ["thinking", "支持思考"], ["vision", "支持视觉"] ] as const).map(([value, label]) => <TButton key={value} theme={filter === value ? "primary" : "default"} variant={filter === value ? "base" : "text"} size="small" onClick={() => setFilter(value)}>{label}</TButton>)}</div><Input value={search} placeholder="搜索名称、模型或驱动" clearable className="w-full sm:w-72" onChange={(value) => setSearch(String(value))} /></div>{isLoading && <div className="flex h-52 items-center justify-center gap-2 text-sm text-muted-foreground"><LoaderCircleIcon className="size-4 animate-spin" />加载模型配置…</div>}{error && <div className="m-4 flex items-start gap-2 rounded-lg border border-destructive/25 bg-destructive/5 p-3 text-sm text-destructive"><CircleAlertIcon className="mt-0.5 size-4" />{error.message}</div>}{!isLoading && !error && models.length === 0 && <div className="flex h-52 flex-col items-center justify-center gap-2 text-sm text-muted-foreground"><CpuIcon className="size-7" />没有匹配的模型配置</div>}{!isLoading && !error && models.length > 0 && <div className="grid gap-3 p-4 lg:grid-cols-2">{models.map((model) => <article key={model.name} className="rounded-lg border border-border bg-background p-4 transition-colors hover:border-primary/35"><div className="flex items-start justify-between gap-3"><div className="min-w-0"><div className="flex flex-wrap items-center gap-2"><h2 className="truncate font-semibold">{model.display_name || model.name}</h2><Tag theme="success" variant="light" size="small">config.yaml</Tag></div><p className="mt-1 truncate font-mono text-xs text-muted-foreground">{model.name}</p></div><TButton theme="default" variant="outline" size="small" onClick={() => setEditor(model)}>配置</TButton></div>{model.description ? <p className="mt-3 line-clamp-2 min-h-10 text-sm leading-5 text-muted-foreground">{model.description}</p> : <p className="mt-3 min-h-10 text-sm leading-5 text-muted-foreground">未填写描述</p>}<div className="mt-3 grid gap-2 border-t pt-3 text-xs text-muted-foreground sm:grid-cols-2"><span className="truncate" title={model.use}>驱动：{model.use}</span><span className="truncate" title={model.model}>模型：{model.model}</span></div><div className="mt-3 flex flex-wrap gap-1.5">{model.api_key_configured && <Tag size="small" variant="light"><KeyRoundIcon className="mr-1 size-3" />已配置密钥</Tag>}{model.supports_thinking && <Tag theme="primary" size="small" variant="light"><SparklesIcon className="mr-1 size-3" />思考</Tag>}{model.supports_vision && <Tag theme="warning" size="small" variant="light"><EyeIcon className="mr-1 size-3" />视觉</Tag>}{model.supports_reasoning_effort && <Tag size="small" variant="light">推理档位</Tag>}</div></article>)}</div>}</section>{data?.config_path && <p className="text-xs text-muted-foreground">当前配置文件：<code>{data.config_path}</code>{data.updated_at ? ` · 最近更新 ${new Date(data.updated_at).toLocaleString()}` : ""}</p>}</div></main></WorkspaceBody>{editor !== null && <ModelEditor key={editor === "new" ? "new" : editor.name} model={editor === "new" ? null : editor} onClose={() => setEditor(null)} />}</WorkspaceContainer>
+  );
+}
diff --git a/frontend-web/src/pages/WorkspaceRoutes.tsx b/frontend-web/src/pages/WorkspaceRoutes.tsx
index ab1b01c3..ea425f4e 100644
--- a/frontend-web/src/pages/WorkspaceRoutes.tsx
+++ b/frontend-web/src/pages/WorkspaceRoutes.tsx
@@ -43,6 +43,7 @@ import MemoryPage from './MemoryPage';
 import PromptPrefixSettingsPage from './PromptPrefixSettingsPage';
 import PrivateSquareSettingsPage from './PrivateSquareSettingsPage';
 import ModelConcurrencySettingsPage from './ModelConcurrencySettingsPage';
+import ModelManagementPage from './ModelManagementPage';
 import PublishSquaresSettingsPage from './PublishSquaresSettingsPage';
 import SkillCompressionSettingsPage from './SkillCompressionSettingsPage';
 import SkillEvolutionPage from './SkillEvolutionPage';
@@ -786,6 +787,18 @@ export default function WorkspaceRoutes({
             )
           }
         />
+        <Route
+          path="admin/models"
+          element={
+            getStoredAuth()?.system_role === 'admin' ? (
+              <WorkspaceLayout {...layoutProps}>
+                <ModelManagementPage />
+              </WorkspaceLayout>
+            ) : (
+              <Navigate to="/page/workspace/chats/new" replace />
+            )
+          }
+        />
         <Route
           path="settings/model-concurrency"
           element={
diff --git a/offline-backend-20260512/backend/app/gateway/app.py b/offline-backend-20260512/backend/app/gateway/app.py
index dec93fda..e2e2d541 100644
--- a/offline-backend-20260512/backend/app/gateway/app.py
+++ b/offline-backend-20260512/backend/app/gateway/app.py
@@ -47,8 +47,9 @@ from app.gateway.routers import (
     llm_metrics,
     mcp,
     memory,
-    menu_overrides,
-    models,
+    menu_overrides,
+    model_management,
+    models,
     multi_agent,
     notifications,
     open_3qfx,
@@ -1425,8 +1426,10 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
         )
 
     # Include routers
-    # Models API is mounted at /api/models
-    app.include_router(models.router)
+    # Models API is mounted at /api/models
+    app.include_router(models.router)
+    # Administrator-managed config.yaml model settings and connection tests.
+    app.include_router(model_management.router)
 
     # MCP API is mounted at /api/mcp
     app.include_router(mcp.router)
diff --git a/offline-backend-20260512/backend/app/gateway/routers/model_management.py b/offline-backend-20260512/backend/app/gateway/routers/model_management.py
new file mode 100644
index 00000000..eba39fb2
--- /dev/null
+++ b/offline-backend-20260512/backend/app/gateway/routers/model_management.py
@@ -0,0 +1,437 @@
+"""Administrator model configuration backed by DeerFlow's ``config.yaml``.
+
+The public ``/api/models`` endpoint intentionally stays small and never
+returns secrets.  This router is the complementary administrator surface: it
+edits only the top-level ``models:`` section in the active DeerFlow config,
+keeps a disk backup before every write, and swaps the gateway's runtime config
+after validation so new requests can use the change without a restart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import logging
+import os
+import re
+import shutil
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+import yaml
+from fastapi import APIRouter, HTTPException, Request
+from langchain_core.messages import HumanMessage
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.gateway.deps import get_optional_user_from_request
+from deerflow.config.app_config import AppConfig, reload_app_config
+from deerflow.config.model_config import ModelConfig
+from deerflow.models.factory import create_chat_model
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/admin/models", tags=["admin-models"])
+
+_MODEL_BLOCK_RE = re.compile(r"(?m)^models:[^\r\n]*(?:\r?\n|$)")
+_TOP_LEVEL_KEY_RE = re.compile(r"(?m)^[A-Za-z_][A-Za-z0-9_-]*:[^\r\n]*(?:\r?\n|$)")
+_BACKUP_DIR_NAME = ".model-config-backups"
+_MUTATION_LOCK = asyncio.Lock()
+
+_EDITOR_FIELDS = frozenset(
+    {
+        "name",
+        "display_name",
+        "description",
+        "use",
+        "model",
+        "api_key",
+        "base_url",
+        "request_timeout",
+        "max_retries",
+        "max_tokens",
+        "temperature",
+        "stream_usage",
+        "supports_thinking",
+        "supports_reasoning_effort",
+        "supports_vision",
+        "when_thinking_enabled",
+        "when_thinking_disabled",
+        "thinking",
+        "use_responses_api",
+        "output_version",
+    }
+)
+_PRESERVED_FIELDS = frozenset(ModelConfig.model_fields) | _EDITOR_FIELDS
+
+
+class ModelAdminItem(BaseModel):
+    """A model configuration safe to return to an administrator browser."""
+
+    name: str
+    display_name: str | None = None
+    description: str | None = None
+    use: str
+    model: str
+    base_url: str | None = None
+    request_timeout: float | None = None
+    max_retries: int | None = None
+    max_tokens: int | None = None
+    temperature: float | None = None
+    stream_usage: bool | None = None
+    supports_thinking: bool = False
+    supports_reasoning_effort: bool = False
+    supports_vision: bool = False
+    when_thinking_enabled: dict[str, Any] | None = None
+    when_thinking_disabled: dict[str, Any] | None = None
+    thinking: dict[str, Any] | None = None
+    use_responses_api: bool | None = None
+    output_version: str | None = None
+    extra_settings: dict[str, Any] = Field(default_factory=dict)
+    api_key_configured: bool = False
+    api_key_source: str | None = None
+    source: str = "config.yaml"
+
+
+class ModelAdminListResponse(BaseModel):
+    models: list[ModelAdminItem]
+    config_path: str
+    updated_at: str | None = None
+
+
+class ModelUpsertRequest(BaseModel):
+    """Editable subset of the ``ModelConfig`` schema plus safe extra fields."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1, max_length=160)
+    display_name: str | None = Field(default=None, max_length=160)
+    description: str | None = Field(default=None, max_length=1000)
+    use: str = Field(min_length=1, max_length=255)
+    model: str = Field(min_length=1, max_length=255)
+    # ``None`` means "keep the currently configured secret" on update.
+    # The value is write-only in practice: it is never part of a response.
+    api_key: str | None = Field(default=None, max_length=4096)
+    clear_api_key: bool = False
+    base_url: str | None = Field(default=None, max_length=2048)
+    request_timeout: float | None = Field(default=None, ge=1, le=600)
+    max_retries: int | None = Field(default=None, ge=0, le=20)
+    max_tokens: int | None = Field(default=None, ge=1, le=1_000_000)
+    temperature: float | None = Field(default=None, ge=0, le=2)
+    stream_usage: bool | None = None
+    supports_thinking: bool = False
+    supports_reasoning_effort: bool = False
+    supports_vision: bool = False
+    when_thinking_enabled: dict[str, Any] | None = None
+    when_thinking_disabled: dict[str, Any] | None = None
+    thinking: dict[str, Any] | None = None
+    use_responses_api: bool | None = None
+    output_version: str | None = Field(default=None, max_length=128)
+    extra_settings: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("name", "use", "model")
+    @classmethod
+    def _trim_required(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("value cannot be empty")
+        return normalized
+
+    @field_validator("display_name", "description", "base_url", "api_key", "output_version")
+    @classmethod
+    def _trim_optional(cls, value: str | None) -> str | None:
+        return value.strip() if isinstance(value, str) else value
+
+
+class ModelTestRequest(BaseModel):
+    model: ModelUpsertRequest
+
+
+class ModelTestResponse(BaseModel):
+    success: bool
+    latency_ms: int
+    message: str
+    preview: str | None = None
+
+
+def _mask_env_source(value: Any) -> str | None:
+    if isinstance(value, str) and value.startswith("$") and len(value) > 1:
+        return value[1:]
+    return None
+
+
+def _to_admin_item(raw: dict[str, Any]) -> ModelAdminItem:
+    api_key = raw.get("api_key")
+    extra = {
+        key: copy.deepcopy(value)
+        for key, value in raw.items()
+        if key not in _PRESERVED_FIELDS
+    }
+    return ModelAdminItem(
+        name=str(raw.get("name") or ""),
+        display_name=raw.get("display_name"),
+        description=raw.get("description"),
+        use=str(raw.get("use") or ""),
+        model=str(raw.get("model") or ""),
+        base_url=raw.get("base_url"),
+        request_timeout=raw.get("request_timeout"),
+        max_retries=raw.get("max_retries"),
+        max_tokens=raw.get("max_tokens"),
+        temperature=raw.get("temperature"),
+        stream_usage=raw.get("stream_usage"),
+        supports_thinking=bool(raw.get("supports_thinking", False)),
+        supports_reasoning_effort=bool(raw.get("supports_reasoning_effort", False)),
+        supports_vision=bool(raw.get("supports_vision", False)),
+        when_thinking_enabled=copy.deepcopy(raw.get("when_thinking_enabled")),
+        when_thinking_disabled=copy.deepcopy(raw.get("when_thinking_disabled")),
+        thinking=copy.deepcopy(raw.get("thinking")),
+        use_responses_api=raw.get("use_responses_api"),
+        output_version=raw.get("output_version"),
+        extra_settings=extra,
+        api_key_configured=bool(api_key),
+        api_key_source=_mask_env_source(api_key),
+    )
+
+
+def _resolve_config_path() -> Path:
+    return AppConfig.resolve_config_path()
+
+
+def _read_config_data(path: Path) -> tuple[str, dict[str, Any], list[dict[str, Any]]]:
+    raw_text = path.read_text(encoding="utf-8")
+    try:
+        data = yaml.safe_load(raw_text) or {}
+    except yaml.YAMLError as exc:
+        raise HTTPException(status_code=500, detail=f"Unable to parse active config.yaml: {exc}") from exc
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=500, detail="The active config.yaml root must be a mapping")
+    raw_models = data.get("models") or []
+    if not isinstance(raw_models, list) or not all(isinstance(item, dict) for item in raw_models):
+        raise HTTPException(status_code=500, detail="config.yaml models must be a list of mappings")
+    return raw_text, data, [copy.deepcopy(item) for item in raw_models]
+
+
+def _render_models_block(models: list[dict[str, Any]], newline: str) -> str:
+    rendered = yaml.safe_dump(
+        {"models": models},
+        allow_unicode=True,
+        sort_keys=False,
+        default_flow_style=False,
+        width=120,
+    )
+    if newline != "\n":
+        rendered = rendered.replace("\n", newline)
+    return rendered if rendered.endswith(newline) else f"{rendered}{newline}"
+
+
+def _replace_models_block(raw_text: str, models: list[dict[str, Any]]) -> str:
+    """Replace the active model entries without touching other config sections.
+
+    PyYAML does not retain comments.  Keep every comment found in the old
+    model section as documentation after the newly rendered model list rather
+    than silently deleting an operator's notes or disabled examples.
+    """
+
+    block_match = _MODEL_BLOCK_RE.search(raw_text)
+    if block_match is None:
+        raise HTTPException(status_code=500, detail="The active config.yaml has no top-level models section")
+    newline = "\r\n" if "\r\n" in raw_text else "\n"
+    next_key = _TOP_LEVEL_KEY_RE.search(raw_text, block_match.end())
+    end = next_key.start() if next_key else len(raw_text)
+    previous_section = raw_text[block_match.end() : end]
+    preserved_comments = "".join(
+        line
+        for line in previous_section.splitlines(keepends=True)
+        if line.lstrip().startswith("#")
+    )
+    rendered = _render_models_block(models, newline)
+    if preserved_comments:
+        if not preserved_comments.endswith(("\n", "\r")):
+            preserved_comments = f"{preserved_comments}{newline}"
+        rendered = f"{rendered}{preserved_comments}"
+    return f"{raw_text[:block_match.start()]}{rendered}{raw_text[end:]}"
+
+
+def _backup_and_write_config(path: Path, raw_before: str, raw_after: str) -> Path:
+    backup_dir = path.parent / _BACKUP_DIR_NAME
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    backup_path = backup_dir / f"{path.stem}.{stamp}.yaml"
+    # Persist the exact text that was read for this mutation.  This makes the
+    # rollback deterministic even if another operator changes the file while
+    # the gateway is processing a request.
+    with backup_path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(raw_before)
+
+    fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+            handle.write(raw_after)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    except Exception:
+        try:
+            os.unlink(temp_name)
+        except OSError:
+            pass
+        raise
+    return backup_path
+
+
+def _restore_backup(path: Path, backup_path: Path) -> None:
+    try:
+        shutil.copy2(backup_path, path)
+    except Exception:
+        logger.exception("Failed to restore model config backup at %s", backup_path)
+
+
+def _request_to_raw_model(payload: ModelUpsertRequest, existing: dict[str, Any] | None = None) -> dict[str, Any]:
+    merged = copy.deepcopy(existing or {})
+    supplied = payload.model_dump(exclude={"extra_settings", "clear_api_key"}, exclude_none=True)
+    merged.update(supplied)
+    for key, value in payload.extra_settings.items():
+        normalized = str(key).strip()
+        if not normalized:
+            raise HTTPException(status_code=422, detail="Extra setting names cannot be blank")
+        if normalized in _EDITOR_FIELDS or normalized in {"api_key", "clear_api_key", "extra_settings"}:
+            raise HTTPException(status_code=422, detail=f"Extra setting '{normalized}' duplicates a managed field")
+        merged[normalized] = copy.deepcopy(value)
+    if payload.clear_api_key:
+        merged.pop("api_key", None)
+    elif payload.api_key is None and existing is not None and "api_key" in existing:
+        merged["api_key"] = existing["api_key"]
+
+    # Validate the raw schema without resolving `$ENV_VAR` values.  Environment
+    # resolution happens during the post-write runtime reload and is rolled back
+    # if unavailable.
+    try:
+        ModelConfig.model_validate(merged)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail=f"Invalid model configuration: {exc}") from exc
+    return merged
+
+
+def _redact_text(value: str, secrets: list[str]) -> str:
+    result = value
+    for secret in secrets:
+        if secret:
+            result = result.replace(secret, "***")
+    return result[:800]
+
+
+async def _require_admin(request: Request) -> None:
+    user = getattr(request.state, "user", None)
+    if user is None:
+        user = await get_optional_user_from_request(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Authentication is required")
+    if getattr(user, "system_role", None) != "admin":
+        raise HTTPException(status_code=403, detail="Model configuration requires an administrator")
+
+
+async def _save_models(request: Request, raw_before: str, models: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    path = _resolve_config_path()
+    raw_after = _replace_models_block(raw_before, models)
+    backup_path = await asyncio.to_thread(_backup_and_write_config, path, raw_before, raw_after)
+    try:
+        config = reload_app_config(str(path))
+        request.app.state.config = config
+    except Exception as exc:
+        logger.warning("Updated model configuration could not be activated: %s", type(exc).__name__)
+        await asyncio.to_thread(_restore_backup, path, backup_path)
+        try:
+            request.app.state.config = reload_app_config(str(path))
+        except Exception:
+            logger.exception("Failed to reload restored model config")
+        raise HTTPException(
+            status_code=422,
+            detail="The model configuration could not be activated; the previous config was restored.",
+        ) from exc
+    return models
+
+
+@router.get("", response_model=ModelAdminListResponse)
+async def list_model_configurations(request: Request) -> ModelAdminListResponse:
+    await _require_admin(request)
+    path = _resolve_config_path()
+    _, _, models = await asyncio.to_thread(_read_config_data, path)
+    updated_at = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC).isoformat()
+    return ModelAdminListResponse(
+        models=[_to_admin_item(item) for item in models],
+        config_path=str(path),
+        updated_at=updated_at,
+    )
+
+
+@router.post("", response_model=ModelAdminItem, status_code=201)
+async def create_model_configuration(body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
+    await _require_admin(request)
+    async with _MUTATION_LOCK:
+        path = _resolve_config_path()
+        raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
+        if any(str(item.get("name")) == body.name for item in models):
+            raise HTTPException(status_code=409, detail=f"A model named '{body.name}' already exists")
+        created = _request_to_raw_model(body)
+        await _save_models(request, raw_before, [*models, created])
+    return _to_admin_item(created)
+
+
+@router.put("/{model_name}", response_model=ModelAdminItem)
+async def update_model_configuration(model_name: str, body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
+    await _require_admin(request)
+    if body.name != model_name:
+        raise HTTPException(status_code=422, detail="A model's stable name cannot be changed; edit its display name instead")
+    async with _MUTATION_LOCK:
+        path = _resolve_config_path()
+        raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
+        index = next((i for i, item in enumerate(models) if str(item.get("name")) == model_name), None)
+        if index is None:
+            raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
+        updated = _request_to_raw_model(body, models[index])
+        next_models = [*models]
+        next_models[index] = updated
+        await _save_models(request, raw_before, next_models)
+    return _to_admin_item(updated)
+
+
+@router.post("/test", response_model=ModelTestResponse)
+async def test_model_connection(body: ModelTestRequest, request: Request) -> ModelTestResponse:
+    """Perform one bounded minimal completion without persisting the draft."""
+
+    await _require_admin(request)
+    path = _resolve_config_path()
+    _, _, models = await asyncio.to_thread(_read_config_data, path)
+    existing = next((item for item in models if str(item.get("name")) == body.model.name), None)
+    candidate = _request_to_raw_model(body.model, existing)
+    candidate_secret = str(candidate.get("api_key") or "")
+    secrets = [candidate_secret]
+    try:
+        runtime_candidate = AppConfig.resolve_env_variables(copy.deepcopy(candidate))
+        # An environment-variable API key is resolved only in memory for this
+        # request. Redact both forms because provider exceptions can include
+        # either the original `$NAME` reference or its resolved value.
+        resolved_secret = str(runtime_candidate.get("api_key") or "")
+        secrets = [candidate_secret, resolved_secret]
+        model_config = ModelConfig.model_validate(runtime_candidate)
+        base_config = request.app.state.config
+        test_config = base_config.model_copy(update={"models": [model_config]})
+        chat_model = create_chat_model(model_config.name, app_config=test_config, force_disable_thinking=True)
+        started = perf_counter()
+        response = await asyncio.wait_for(
+            chat_model.ainvoke([HumanMessage(content="Reply with exactly: OK")]),
+            timeout=min(float(candidate.get("request_timeout") or 30), 45),
+        )
+        latency_ms = round((perf_counter() - started) * 1000)
+        preview = _redact_text(str(getattr(response, "content", "OK")), secrets)
+        return ModelTestResponse(success=True, latency_ms=latency_ms, message="Connection successful", preview=preview)
+    except Exception as exc:
+        # Provider errors sometimes echo a credential.  Never log the full
+        # exception or return it without redacting the submitted key.
+        logger.warning("Model connection test failed for '%s': %s", candidate.get("name"), type(exc).__name__)
+        return ModelTestResponse(
+            success=False,
+            latency_ms=0,
+            message=_redact_text(str(exc) or type(exc).__name__, secrets),
+        )
diff --git a/offline-backend-20260512/backend/tests/test_model_management.py b/offline-backend-20260512/backend/tests/test_model_management.py
new file mode 100644
index 00000000..728e6708
--- /dev/null
+++ b/offline-backend-20260512/backend/tests/test_model_management.py
@@ -0,0 +1,92 @@
+"""Focused regression tests for administrator model configuration helpers."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+import yaml
+
+from app.gateway.routers import model_management as router
+
+
+def test_replace_models_block_keeps_other_sections_and_comments() -> None:
+    raw = """config_version: 1
+models:
+  # Existing provider note
+  - name: old-model
+    use: langchain_openai:ChatOpenAI
+    model: old-model
+# Disabled provider example remains useful to operators.
+# - name: disabled-model
+#   model: disabled-model
+agents:
+  default: lead_agent
+"""
+
+    replaced = router._replace_models_block(
+        raw,
+        [
+            {
+                "name": "new-model",
+                "use": "langchain_openai:ChatOpenAI",
+                "model": "new-model",
+            }
+        ],
+    )
+
+    parsed = yaml.safe_load(replaced)
+    assert parsed["models"] == [
+        {
+            "name": "new-model",
+            "use": "langchain_openai:ChatOpenAI",
+            "model": "new-model",
+        }
+    ]
+    assert parsed["agents"] == {"default": "lead_agent"}
+    assert "# Existing provider note" in replaced
+    assert "# Disabled provider example remains useful to operators." in replaced
+
+
+def test_connection_error_redaction_hides_literal_and_resolved_keys() -> None:
+    message = "provider rejected raw-secret and resolved-secret"
+    assert router._redact_text(message, ["raw-secret", "resolved-secret"]) == "provider rejected *** and ***"
+
+
+@pytest.mark.asyncio
+async def test_connection_test_uses_one_minimal_prompt_without_writing_config(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    config_path = tmp_path / "config.yaml"
+    original = "models: []\nagent: lead_agent\n"
+    config_path.write_text(original, encoding="utf-8")
+    messages_seen = []
+
+    class FakeChatModel:
+        async def ainvoke(self, messages):
+            messages_seen.extend(messages)
+            return SimpleNamespace(content="OK")
+
+    monkeypatch.setattr(router, "_resolve_config_path", lambda: config_path)
+    monkeypatch.setattr(router, "create_chat_model", lambda *_args, **_kwargs: FakeChatModel())
+    request = SimpleNamespace(
+        state=SimpleNamespace(user=SimpleNamespace(system_role="admin")),
+        app=SimpleNamespace(state=SimpleNamespace(config=SimpleNamespace(model_copy=lambda **_kwargs: SimpleNamespace()))),
+    )
+    body = router.ModelTestRequest(
+        model=router.ModelUpsertRequest(
+            name="test-model",
+            use="langchain_openai:ChatOpenAI",
+            model="test-model",
+            api_key="raw-secret",
+        )
+    )
+
+    result = await router.test_model_connection(body, request)
+
+    assert result.success is True
+    assert result.preview == "OK"
+    assert len(messages_seen) == 1
+    assert messages_seen[0].content == "Reply with exactly: OK"
+    assert config_path.read_text(encoding="utf-8") == original