LibreChat 把多个模型塞进同一个对话框，密钥和模型映射先在配置文件里对齐

LibreChat 把多个模型放进同一个对话框，靠的不是在页面上临时添加，而是一份配置文件加一组环境变量：端点地址和模型清单写在 librechat.yaml 的自定义端点里，密钥写在 .env 中，再通过端点条目里的引用字段把两者绑到一起。只改文件不重启，前端模型下拉不会出现新条目；密钥变量名和引用名对不上，条目会出现但请求报鉴权错误。判断顺序通常是：先确认端点声明，再确认密钥绑定，最后用重启后的日志和下拉列表验收。

LibreChat 的多模型聚合由配置文件驱动：端点地址和模型清单写在 librechat.yaml 的自定义端点里，密钥写在 .env，并通过对端点的引用字段绑进去，两层缺一不可。改完要重启 api 容器，在日志里确认配置加载无报错，再把前端模型下拉能否列出新条目当作验收点。字段名随版本变化，动手前对照当前版本文档，不要照抄别处的旧写法。

在配置文件里声明第一个自定义端点

端点分两层理解：一层是内置的官方端点，一层是你自己加的 custom 端点。要接一个不在内置列表里的服务，就在配置文件里新增一个 custom 条目。配置文件路径通常由环境变量 CONFIG_PATH 指定，容器内常见的默认值是 /app/librechat.yaml，以你部署时的挂载为准。下面是一个骨架，字段名以项目当前版本文档为准，不同版本对字段的取舍并不一致。

endpoints:
  custom:
    - name: "my-cloud"                    # 端点标识，日志和前端分组会用到
      baseURL: "https://api.example.com/v1"  # 端点地址占位，通常带版本路径
      apiKey: "${MY_CLOUD_KEY}"            # 值来自环境变量，不写真密钥
      models:
        default:
          - "model-a"                      # 会被原样当作请求里的 model 参数
          - "model-b"
        fetch: false                       # 是否从端点自动拉取模型列表

各字段的作用：name 是这个端点在配置里的标识；baseURL 决定请求发到哪里；models.default 是希望出现在下拉里的模型名清单。写进清单的名字一般会被直接当成请求中的 model 参数，除非当前版本支持把显示名和请求名分开写。自动拉取列表的开关在不同版本里默认行为不一样，先用显式清单更容易定位问题。改这个文件不等于生效，端点声明只是“登记”，还不能发请求。

把密钥放进环境变量并和端点对上号

密钥不要写在 yaml 里。yaml 中写的应该是变量名，真正的值放 .env，两者靠同名变量关联：

LibreChat 把多个模型塞进同一个对话框，密钥和模型映射先在配置文件里对齐

# .env
MY_CLOUD_KEY=sk-replace-with-your-key
CONFIG_PATH=/app/librechat.yaml

引用关系是：端点条目里 apiKey 的值必须与 .env 中某个键完全同名，只差一对 ${} 包裹。只改 .env 的键名不改进 yaml 的引用，或者反过来，表现都是条目存在、请求失败，容器日志里通常能看到鉴权失败或密钥缺失一类的提示。还有一个容易忽略的点：docker compose restart 只重启进程，不一定重新注入修改过的环境变量，改完 .env 建议用 docker compose up -d 让容器按新变量重建，更稳妥。

重启后在模型下拉里确认新条目

重启命令在 docker-compose.yml 所在目录执行，然后盯住 api 容器的日志：

docker compose up -d
 docker compose logs -f api | grep -i -E "config|endpoint|yaml"

日志里关注几类行：配置文件的实际加载路径、解析是否成功、识别到的端点和模型数量，以及任何 YAML 语法报错。如果这一层就报错，前端下拉不会有任何变化，先把日志里的报错解决掉，再往下看。配置加载正常之后，刷新页面（必要时强制刷新，避免前端沿用旧的模型列表），新建对话，打开模型选择下拉，预期能看到你声明的端点分组和其中的模型条目；models.default 里写了两个模型，就应该出现两项。看不到时按三种情况分头排查：配置没加载、加载了但模型清单为空、加载了但前端没刷新，不要凭感觉判断。

同时接两个端点时处理模型重名与默认模型

两个端点同时接入，最容易踩的是重名。云端的模型和本地部署的模型用了同一个模型名时，下拉里会出现两个看起来一样的条目，选错的那一次请求会发到另一个端点，表现是模型不存在或鉴权失败，而不是配置报错，排查方向很容易被带偏。处理方式是让显示名和请求名分开：如果当前版本支持在模型条目上同时写请求名与显示名，就给本地那份加“本地”之类的前缀作为显示名，请求名保持原样；如果不支持，就在端点层面用 name 或分组标签把来源标出来，至少让下拉里能一眼区分。

默认模型通常有两处来源：一处在配置文件里针对界面或端点的默认预设，另一处在页面上的模型选择，后者往往会被写进用户偏好。两边不一致时，刷新后看到选中项回落到第一个可用条目，是常见的表现。建议先把下拉中每个条目的归属端点确认清楚，再固定默认模型；重名没理清之前，不要靠改默认值绕过去，否则问题只是被藏起来了。整套流程的边界也很清楚：配置字段、容器日志和前端下拉的行为是可验证的，模型本身的能力和额度不由这些文件决定，遇到了要去对应服务侧查。