Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import {
EModelEndpoint,
AgentCapabilities,
BASE_ONLY_CONFIG_PATHS,
normalizeEndpointName,
materializeModelSpecEndpoints,
} from 'librechat-data-provider';
import type {
TEndpoint,
TCustomConfig,
TAgentsEndpoint,
TVertexAISchema,
TVertexAIConfig,
} from 'librechat-data-provider';
import type { AppConfig } from '~/types';
import { readConfigEntryTombstone, getConfigTombstoneSegments } from './collections';
import { azureAssistantsDefaults, assistantsConfigSetup } from './assistants';
import { getAtPath, isPlainRecord, isSegmentPrefix } from './paths';
import { resolveServedAzureGroups } from './azure';
import { validateVertexConfig } from './vertex';
import { agentsConfigSetup } from './agents';
import { isMemoryEnabled } from './memory';
import logger from '~/config/winston';
type JsonRecord = Record<string, unknown>;
/**
* What AppService derives from parts of librechat.yaml at startup, which the merge derives again
* for the parts config overrides change, and which writes are checked against.
*/
export interface ConfigDerivation {
/**
* Expands a custom endpoint's `customParams` as startup does (each parameter definition
* completed from the defaults of `defaultParamsEndpoint`, OpenRouter's defaults added) and
* returns the expanded copy; throws when the definitions are invalid. Without it, custom
* endpoints are served as merged and their parameter definitions are not checked.
*/
expandCustomEndpoint?: (endpoint: TEndpoint) => TEndpoint;
/**
* Whether the merge derives the Azure endpoint (the `groupMap`, model lists and assistant
* models a layer's `groups` resolve to), Vertex AI (`endpoints.anthropic.vertexConfig` and the
* models it serves) and the Azure Assistants endpoint again from what the layers write
* (`CONFIG_REDERIVE_ENDPOINTS`). Without it, those overrides stay inert. Writes are checked
* either way.
*/
rederiveEndpoints?: boolean;
/**
* Whether librechat.yaml configures Vertex AI (`endpoints.anthropic.vertex`, on or off;
* {@link isVertexConfigured}). An override may turn Vertex AI on only where it does: the setup
* runs on librechat.yaml's key file and region, and without them on the deployment's default
* Google credentials. `false` makes an override that turns it on an `invalid_vertex_config`;
* unset, that is not checked. The merge sets it from librechat.yaml itself.
*/
vertexConfigured?: boolean;
}
/** Why a write leaves a derived part of the config unable to load. */
export type DerivedConfigIssueCode =
| 'invalid_azure_groups'
| 'invalid_vertex_config'
| 'invalid_param_definitions'
| 'unknown_spec_endpoint';
/** A derived check that fails, at its place in the merged librechat.yaml-shaped config. */
export interface DerivedConfigIssue {
code: DerivedConfigIssueCode;
path: string[];
}
/**
* Derived issues only writes report: the merge does not strip the value they sit on. A model spec
* whose endpoint is unknown is refused on write; at merge only that spec is left out
* ({@link deriveServedSpecs}), not the layer's whole list.
*/
export const WRITE_ONLY_DERIVED_ISSUES: ReadonlySet<string> = new Set(['unknown_spec_endpoint']);
const ENDPOINTS = 'endpoints';
const AZURE_GROUPS = [ENDPOINTS, EModelEndpoint.azureOpenAI, 'groups'];
const ANTHROPIC = [ENDPOINTS, EModelEndpoint.anthropic];
const VERTEX = [...ANTHROPIC, 'vertex'];
const CUSTOM_ENDPOINTS = [ENDPOINTS, EModelEndpoint.custom];
const SPEC_LIST = ['modelSpecs', 'list'];
function asRecord(value: unknown): JsonRecord | undefined {
return isPlainRecord(value) ? value : undefined;
}
function getEndpointIdentity(name: unknown): string | undefined {
return typeof name === 'string' && name !== '' ? normalizeEndpointName(name) : undefined;
}
/** The custom endpoint identities a list names (as the merge folds them, `ollama` is `Ollama`). */
function getEndpointIdentities(items: unknown): Set<string> {
const identities = new Set<string>();
for (const item of Array.isArray(items) ? items : []) {
const identity = getEndpointIdentity(asRecord(item)?.name);
if (identity != null) {
identities.add(identity);
}
}
return identities;
}
/** The `group` names an Azure `groups` list holds. */
export function getGroupNames(groups: unknown): Set<string> {
const names = new Set<string>();
for (const item of Array.isArray(groups) ? groups : []) {
const name = asRecord(item)?.group;
if (typeof name === 'string') {
names.add(name);
}
}
return names;
}
/** Whether an override sets the value at `segments`. */
function sets(overrides: JsonRecord, segments: readonly string[]): boolean {
return getAtPath(overrides, segments) !== undefined;
}
/** Whether a librechat.yaml-shaped config configures Vertex AI, on or off. */
export function isVertexConfigured(yaml: unknown): boolean {
return asRecord(getAtPath(yaml, VERTEX)) != null;
}
function isUsableVertex(vertex: unknown): boolean {
try {
return validateVertexConfig(vertex as TVertexAISchema)?.isValid === true;
} catch {
return false;
}
}
/** Whether a model spec's endpoint is one the runtime serves (`processModelSpecs`'s rule). */
function isKnownSpecEndpoint(endpoint: string, customEndpoints: ReadonlySet<string>): boolean {
if (endpoint === EModelEndpoint.custom) {
return false;
}
return (
Object.prototype.hasOwnProperty.call(EModelEndpoint, endpoint) ||
customEndpoints.has(normalizeEndpointName(endpoint))
);
}
/**
* What a write breaks in the parts AppService derives from librechat.yaml, judged on `merged`
* (the overrides over the config they land on): Azure `groups` that do not resolve once merged by
* `group`, or whose written groups name an environment variable that is not set
* (`invalid_azure_groups`); a Vertex AI setup that does not load, or that turns Vertex AI on
* where librechat.yaml configures none (`vertexConfigured: false`; `invalid_vertex_config`);
* custom endpoint parameter definitions startup would refuse (`invalid_param_definitions`, when
* `expandCustomEndpoint` is given); and model specs naming an endpoint that is not configured
* (`unknown_spec_endpoint`). Each family is checked only when the overrides write it. All but
* Azure groups also need their section to pass its schema (`validSections`), so a schema issue is
* not reported twice; groups are always checked, since groups a merge cannot resolve stay unread.
* Issues come back in `merged`'s terms, for the caller to attribute.
*/
export function getDerivedConfigIssues(
overrides: JsonRecord,
merged: JsonRecord,
validSections: ReadonlySet<string>,
derivation: ConfigDerivation = {},
): DerivedConfigIssue[] {
const issues: DerivedConfigIssue[] = [];
const groups = getAtPath(overrides, AZURE_GROUPS);
if (
groups !== undefined &&
!resolveServedAzureGroups(getAtPath(merged, AZURE_GROUPS), getGroupNames(groups)).isValid
) {
issues.push({ code: 'invalid_azure_groups', path: AZURE_GROUPS });
}
if (validSections.has(ENDPOINTS)) {
const vertex = asRecord(getAtPath(merged, VERTEX));
if (
sets(overrides, VERTEX) &&
vertex != null &&
vertex.enabled !== false &&
(derivation.vertexConfigured === false || !isUsableVertex(vertex))
) {
issues.push({ code: 'invalid_vertex_config', path: VERTEX });
}
issues.push(...getParamDefinitionIssues(overrides, merged, derivation));
}
if (validSections.has('modelSpecs') && Array.isArray(getAtPath(overrides, SPEC_LIST))) {
issues.push(...getSpecEndpointIssues(merged));
}
return issues;
}
function getParamDefinitionIssues(
overrides: JsonRecord,
merged: JsonRecord,
{ expandCustomEndpoint }: ConfigDerivation,
): DerivedConfigIssue[] {
const written = getEndpointIdentities(getAtPath(overrides, CUSTOM_ENDPOINTS));
const entries = getAtPath(merged, CUSTOM_ENDPOINTS);
if (expandCustomEndpoint == null || written.size === 0 || !Array.isArray(entries)) {
return [];
}
return entries.flatMap((entry: unknown, index): DerivedConfigIssue[] => {
const record = asRecord(entry);
const identity = getEndpointIdentity(record?.name);
if (record == null || identity == null || !written.has(identity)) {
return [];
}
try {
expandCustomEndpoint(record as TEndpoint);
return [];
} catch {
return [
{
code: 'invalid_param_definitions',
path: [...CUSTOM_ENDPOINTS, String(index), 'customParams'],
},
];
}
});
}
function getSpecEndpointIssues(merged: JsonRecord): DerivedConfigIssue[] {
const modelSpecs = materializeModelSpecEndpoints(
asRecord(merged.modelSpecs) as TCustomConfig['modelSpecs'],
);
const customEndpoints = getEndpointIdentities(getAtPath(merged, CUSTOM_ENDPOINTS));
return (modelSpecs?.list ?? []).flatMap((spec, index): DerivedConfigIssue[] => {
const endpoint: unknown = asRecord(asRecord(spec)?.preset)?.endpoint;
if (typeof endpoint !== 'string' || isKnownSpecEndpoint(endpoint, customEndpoints)) {
return [];
}
return [
{ code: 'unknown_spec_endpoint', path: [...SPEC_LIST, String(index), 'preset', 'endpoint'] },
];
});
}
/**
* The paths layers wrote or removed, for the post-merge derivation: each written section's keys
* one or two levels down (`endpoints.azureOpenAI`, `endpoints.anthropic.vertex`), each tombstone,
* and the custom endpoints written, by identity.
*/
export interface ConfigTouches {
paths: string[][];
customEndpoints: Set<string>;
}
export function createConfigTouches(): ConfigTouches {
return { paths: [], customEndpoints: new Set() };
}
/**
* Records what one layer wrote (`applied`, librechat.yaml keys) and the tombstones it applied: a
* keyed tombstone (`endpoints.custom["Name"]…`) by its array, with the custom endpoint it names.
*/
export function recordConfigTouches(
touches: ConfigTouches,
applied: JsonRecord,
tombstones: readonly string[],
): void {
for (const tombstone of tombstones) {
touches.paths.push([...getConfigTombstoneSegments(tombstone)]);
const entry = readConfigEntryTombstone(tombstone);
if (entry != null && isSegmentPrefix(CUSTOM_ENDPOINTS, entry.segments)) {
touches.customEndpoints.add(entry.identity);
}
}
for (const [section, value] of Object.entries(applied)) {
const fields = asRecord(value);
if (fields == null || Object.keys(fields).length === 0) {
touches.paths.push([section]);
continue;
}
for (const [field, child] of Object.entries(fields)) {
const children = asRecord(child);
if (children == null || Object.keys(children).length === 0) {
touches.paths.push([section, field]);
continue;
}
for (const key of Object.keys(children)) {
touches.paths.push([section, field, key]);
}
}
}
for (const identity of getEndpointIdentities(getAtPath(applied, CUSTOM_ENDPOINTS))) {
touches.customEndpoints.add(identity);
}
}
/** Whether any recorded path is `prefix`, lies below it or contains it. */
export function touchesConfig(touches: ConfigTouches, prefix: readonly string[]): boolean {
return touches.paths.some(
(path) => isSegmentPrefix(prefix, path) || isSegmentPrefix(path, prefix),
);
}
/**
* `raw` with librechat.yaml's value at every base-only path (`BASE_ONLY_CONFIG_PATHS`) whose
* parent object `raw` holds.
*/
export function withBaseOnlyValues<T extends JsonRecord>(raw: T, baseYaml: JsonRecord): T {
let result: JsonRecord = raw;
for (const path of BASE_ONLY_CONFIG_PATHS) {
const segments = path.split('.');
const value = getAtPath(baseYaml, segments);
if (getAtPath(result, segments) === value) {
continue;
}
result = replaceAt(result, segments, value);
}
return result as T;
}
/**
* Copies objects along `segments` and sets the last one (or removes it, for `undefined`). Only an
* object that is there is changed: a missing parent (a section a layer removed) stays missing.
*/
function replaceAt(root: JsonRecord, segments: readonly string[], value: unknown): JsonRecord {
const [segment, ...rest] = segments;
const next: JsonRecord = { ...root };
if (rest.length === 0) {
if (value === undefined) {
delete next[segment];
} else {
next[segment] = value;
}
return next;
}
const child = next[segment];
if (!isPlainRecord(child)) {
return root;
}
next[segment] = replaceAt(child, rest, value);
return next;
}
/** `merged` with one endpoint of `endpoints` set (or removed, for `undefined`), copied on the way. */
function setEndpoint<T extends { endpoints?: unknown }>(
merged: T,
endpoint: string,
value: unknown,
): T {
const next: JsonRecord = { ...asRecord(merged.endpoints) };
if (value === undefined) {
delete next[endpoint];
} else {
next[endpoint] = value;
}
return { ...merged, endpoints: next };
}
/**
* The Anthropic endpoint with Vertex AI derived again from `raw` (the librechat.yaml-shaped
* config up to this layer), as `loadEndpoints` derives it at startup: `vertexConfig` from
* `endpoints.anthropic.vertex`, with librechat.yaml's base-only values (key file, region), and
* the models it serves. `enabled: false`, or no `vertex` left, removes `vertexConfig` and serves
* the `endpoints.anthropic.models` the YAML-shaped config holds (none: the provider's defaults).
* Models a layer set, where no later layer removed them (`modelsOverridden`), stay as merged.
* Where librechat.yaml configures no Vertex AI ({@link isVertexConfigured}) nothing is derived,
* so no layer turns it on with the deployment's default Google credentials. A setup that does not
* load is off too, with a warning naming `principal`: a write that would leave it so is left out
* of the merge before it lands (`stripInvalidOverrides`), so only a tombstone of one of its
* settings does, and what the layers leave decides, never a `vertexConfig` derived below it.
*/
export function deriveVertexEndpoint<T extends JsonRecord>(params: {
merged: T;
raw: JsonRecord;
baseYaml: JsonRecord;
modelsOverridden: boolean;
principal: string;
}): T {
const { merged, baseYaml, modelsOverridden, principal } = params;
const anthropic = asRecord(getAtPath(merged, ANTHROPIC));
if (anthropic == null || !isVertexConfigured(baseYaml)) {
return merged;
}
const raw = withBaseOnlyValues(params.raw, baseYaml);
const vertex = asRecord(getAtPath(raw, VERTEX));
let vertexConfig: TVertexAIConfig | null = null;
if (vertex != null && vertex.enabled !== false) {
vertexConfig = isUsableVertex(vertex) ? validateVertexConfig(vertex as TVertexAISchema) : null;
if (vertexConfig == null) {
logger.warn(
`[mergeConfigOverrides] Turning Vertex AI off for ${principal}: endpoints.anthropic.vertex does not load once its tombstones apply`,
);
}
}
const next: JsonRecord = { ...anthropic };
if (vertexConfig == null) {
delete next.vertexConfig;
} else {
next.vertexConfig = vertexConfig;
}
if (!modelsOverridden) {
const models = vertexConfig?.modelNames ?? getAtPath(raw, [...ANTHROPIC, 'models']);
if (models === undefined) {
delete next.models;
} else {
next.models = models;
}
}
return setEndpoint(merged, EModelEndpoint.anthropic, next);
}
/**
* Each custom endpoint a layer wrote, with `customParams` expanded again from the
* librechat.yaml-shaped entry the layers merged to, as startup expands librechat.yaml's: a
* layer's compact definitions get their defaults, a `defaultParamsEndpoint` a layer changes picks
* the defaults of the new endpoint, and an endpoint only a layer defines gets OpenRouter's
* defaults by its name or URL. The served entry's other fields (its name, base URL, key) stay as
* merged. Definitions that do not expand keep librechat.yaml's expanded ones (none for an endpoint
* librechat.yaml does not define), with a warning.
*/
function expandWrittenEndpoints(
merged: AppConfig,
raw: JsonRecord,
base: AppConfig,
touches: ConfigTouches,
expandCustomEndpoint: NonNullable<ConfigDerivation['expandCustomEndpoint']>,
): AppConfig {
const entries = merged.endpoints?.custom;
if (touches.customEndpoints.size === 0 || !Array.isArray(entries)) {
return merged;
}
const byIdentity = (items: unknown): Map<string, JsonRecord> => {
const found = new Map<string, JsonRecord>();
for (const item of Array.isArray(items) ? items : []) {
const record = asRecord(item);
const identity = getEndpointIdentity(record?.name);
if (record != null && identity != null) {
found.set(identity, record);
}
}
return found;
};
const rawEntries = byIdentity(getAtPath(raw, CUSTOM_ENDPOINTS));
let baseEntries: Map<string, JsonRecord> | undefined;
let changed = false;
const next = entries.map((entry) => {
const identity = getEndpointIdentity(entry?.name);
if (identity == null || !touches.customEndpoints.has(identity)) {
return entry;
}
const { customParams: _served, ...served } = entry;
const compact = rawEntries.get(identity)?.customParams;
let customParams: unknown;
try {
customParams = expandCustomEndpoint({
...served,
...(compact !== undefined && { customParams: compact }),
} as TEndpoint).customParams;
} catch {
logger.warn(
`[mergeConfigOverrides] Keeping librechat.yaml's customParams for endpoint "${entry.name}": the merged parameter definitions do not load`,
);
baseEntries ??= byIdentity(base.endpoints?.custom);
customParams = baseEntries.get(identity)?.customParams;
}
changed = true;
return (customParams === undefined ? served : { ...served, customParams }) as typeof entry;
});
if (!changed) {
return merged;
}
return { ...merged, endpoints: { ...merged.endpoints, custom: next } };
}
/**
* The agents endpoint's capabilities derived again, as startup derives them, when a layer wrote
* or removed `memory` or the agents endpoint: from the YAML-shaped `endpoints.agents` (schema
* defaults without one), without `memory` while the merged memory config is off, so a profile
* that turns memory on gets the capability and one that turns it off loses the inert toggle.
* Startup always serves an agents endpoint, so where a tombstone of it (or of `endpoints`) left
* none, it is the one startup derives from what the layers leave, as a tombstone of its
* `capabilities` serves the default capabilities.
*/
function deriveAgentCapabilities(merged: AppConfig, raw: JsonRecord): AppConfig {
let derived: Partial<TAgentsEndpoint>;
try {
derived = agentsConfigSetup(raw as Partial<TCustomConfig>);
} catch {
return merged;
}
const { capabilities } = derived;
if (!Array.isArray(capabilities)) {
return merged;
}
const agents = merged.endpoints?.[EModelEndpoint.agents] ?? derived;
const served = isMemoryEnabled(merged.memory)
? capabilities
: capabilities.filter((capability) => capability !== AgentCapabilities.memory);
return setEndpoint(merged, EModelEndpoint.agents, { ...agents, capabilities: served });
}
/**
* The Azure Assistants endpoint derived again, as `loadEndpoints` derives it: its defaults while
* the merged Azure endpoint turns `assistants` on, the YAML-shaped `endpoints.azureAssistants`
* over them, and nothing when neither is left. One that does not parse stays as merged.
*/
function deriveAzureAssistants(merged: AppConfig, raw: JsonRecord, principals: string): AppConfig {
const assistantsOn = Boolean(merged.endpoints?.[EModelEndpoint.azureOpenAI]?.assistants);
let next: JsonRecord | undefined = assistantsOn ? azureAssistantsDefaults() : undefined;
if (getAtPath(raw, [ENDPOINTS, EModelEndpoint.azureAssistants]) !== undefined) {
try {
next = assistantsConfigSetup(
raw as Partial<TCustomConfig>,
EModelEndpoint.azureAssistants,
next,
) as JsonRecord;
} catch {
logger.warn(
`[mergeConfigOverrides] Keeping endpoints.azureAssistants as merged for ${principals}: it does not parse`,
);
return merged;
}
}
if (next === undefined && merged.endpoints?.[EModelEndpoint.azureAssistants] === undefined) {
return merged;
}
return setEndpoint(merged, EModelEndpoint.azureAssistants, next);
}
/**
* The model specs served without those whose endpoint the YAML-shaped config the layers leave
* (`raw`) does not configure, by the rule startup leaves out librechat.yaml's
* ({@link isKnownSpecEndpoint}, after inferring an agent spec's endpoint): a tombstone of
* `endpoints.custom` or `endpoints` hides the specs of the custom endpoints it removes until a
* layer defines them again, and a spec stored for an endpoint that is not configured is left out
* on its own. Where no spec and no added endpoint is left, no spec list is served, as tenant
* scoping and hidden endpoints leave none, so the controls specs turn off are derived without
* them. `addedEndpoints` stays as merged, as startup keeps it: an endpoint it names that is gone
* is simply not offered, while emptying the list would offer every endpoint (the names of custom
* endpoints the layers remove are scoped out of it after the merge, `keyedTombstones`).
*/
function deriveServedSpecs(merged: AppConfig, raw: JsonRecord, principals: string): AppConfig {
const modelSpecs = materializeModelSpecEndpoints(merged.modelSpecs);
const list = modelSpecs?.list;
if (modelSpecs == null || !Array.isArray(list) || list.length === 0) {
return merged;
}
const customEndpoints = getEndpointIdentities(getAtPath(raw, CUSTOM_ENDPOINTS));
const served = list.filter((spec) => {
const endpoint: unknown = spec?.preset?.endpoint;
return typeof endpoint === 'string' && isKnownSpecEndpoint(endpoint, customEndpoints);
});
if (served.length === list.length) {
return merged;
}
logger.debug(
`[mergeConfigOverrides] Leaving out ${list.length - served.length} model spec(s) for ${principals}: their endpoint is not configured once the layers apply`,
);
if (served.length > 0 || (modelSpecs.addedEndpoints?.length ?? 0) > 0) {
return { ...merged, modelSpecs: { ...modelSpecs, list: served } };
}
const { modelSpecs: _hidden, ...rest } = merged;
return rest;
}
/**
* The derivations that follow a merge, for what its layers touched: custom endpoint parameters
* (with `expandCustomEndpoint`), the model specs whose endpoint is still configured, the agents
* endpoint's memory capability, and (with `rederiveEndpoints`) the Azure Assistants endpoint.
* Untouched parts stay as merged.
*/
export function rederiveMergedConfig(params: {
merged: AppConfig;
raw: JsonRecord;
base: AppConfig;
touches: ConfigTouches;
derivation: ConfigDerivation;
principals: string;
}): AppConfig {
const { raw, base, touches, derivation, principals } = params;
let merged = params.merged;
if (derivation.expandCustomEndpoint != null) {
merged = expandWrittenEndpoints(merged, raw, base, touches, derivation.expandCustomEndpoint);
}
if (touchesConfig(touches, ['modelSpecs']) || touchesConfig(touches, CUSTOM_ENDPOINTS)) {
merged = deriveServedSpecs(merged, raw, principals);
}
if (
touchesConfig(touches, ['memory']) ||
touchesConfig(touches, [ENDPOINTS, EModelEndpoint.agents])
) {
merged = deriveAgentCapabilities(merged, raw);
}
if (
derivation.rederiveEndpoints === true &&
(touchesConfig(touches, [ENDPOINTS, EModelEndpoint.azureOpenAI]) ||
touchesConfig(touches, [ENDPOINTS, EModelEndpoint.azureAssistants]))
) {
merged = deriveAzureAssistants(merged, raw, principals);
}
return merged;
}