细粒度访问控制

LibreChat 附带了一套完整的授权系统，建立在身份验证之上。访问权限并非“全有或全无”：应用中的每个可共享实体（智能体、提示词、MCP 服务器、远程智能体、文件、对话）都有其自己的访问控制列表 (ACL)，并且每个功能都可以针对用户、群组、角色或公开进行独立启用或限制。

本页面介绍了各组件是如何协同工作的，以便您可以根据组织需求对权限进行建模，无论是适用于所有人自由共享的小型团队，还是包含同步 Entra ID 组、自定义角色和委派管理员的企业级部署。

访问模型概览

LibreChat 的授权包含三个相互独立的层级，它们共同构成了完整的授权体系：

这三者均针对以下四种主要类型进行评估：

• User: 一个独立的 LibreChat 账户
• Group: 用户集合（本地用户或从 Entra ID 同步的用户）
• Role: 一个命名的权限配置文件（例如 USER、ADMIN 或任何自定义角色）
• Public: 实例上的每一位已认证用户

层级 1：功能权限（基于角色）

功能级权限控制着应用程序中特定角色的全部功能。它们回答了诸如_“此角色的用户是否可以创建智能体？”、“他们是否被允许公开分享提示词？”、“他们是否可以调用代码解释器？”_之类的问题。

内置系统角色

LibreChat 附带两个始终存在且无法删除的系统角色：

• ADMIN：分配给在该实例上注册的第一个账户。管理员可以查看所有资源、修改任何设置、访问管理面板并配置整个平台的行为。
• USER: 分配给每个新账户的默认角色。

管理员可以通过更新 MongoDB 中的用户文档来手动提升权限，请参阅 Administrator Controls。

权限类型

每个角色都包含一个 权限类型 × 操作 的矩阵：

SHARE 和 SHARE_PUBLIC 之间的区别非常重要：你可以允许某个角色与_特定_用户或群组共享智能体（SHARE），而不必让他们将智能体对实例上的_所有人_可见（SHARE_PUBLIC）。

配置功能权限

管理功能权限的推荐方式是使用 LibreChat Admin Panel，它直接编辑每个角色（包括您创建的任何自定义角色）的权限矩阵。更改无需重新部署 LibreChat 即可生效，并且作用于您想要修改的具体角色，而不是全局的 USER 默认设置。

自定义角色

除了 USER 和 ADMIN 之外，管理员还可以创建具有自定义功能权限矩阵的自定义角色（于 v0.8.5 版本引入；参见 #12528）。一个用户可以拥有多个角色，其最终有效权限为所有持有角色的权限并集。自定义角色可在管理面板中进行管理。

基于角色和群组的配置覆盖

除了功能标志外，v0.8.5 还引入了基于数据库的配置覆盖系统 (#12354)。这允许你为特定的组或角色分配_不同的 librechat.yaml 风格配置_。例如，“研究”组可能比默认配置拥有更多的 endpoint 访问权限、更高的递归限制以及不同的智能体功能。覆盖配置会在登录时解析，并叠加在基础配置之上。

Layer 2: Resource ACLs (Per-Entity Sharing)

LibreChat 中的每个可共享资源都有其自己的访问控制列表，独立于基于角色的权限。这就是拥有 SHARE 权限的个人用户选择_谁_可以访问_他们_的 Agent、提示词或 MCP 服务器的方式。

资源类型

资源 ACL 目前适用于：

• 智能体 (agent)
• 提示词 / 提示词组 (promptGroup)
• MCP 服务器 (mcpServer)
• 远程代理 (remoteAgent)，适用于 Agents API
• 文件 (file)，通常继承自使用它们的相关资源
• Projects (project)，支持继承，因此共享给项目的资源会自动继承 ACL。

访问角色（权限预设）

与其向最终用户公开原始权限位，共享功能为每种资源类型使用了三个命名角色：

在底层实现中，权限作为位掩码（permBits）存储在每个（资源，主体）对中；超集会自动处理，因此授予 Editor 权限意味着同时也授予了 Viewer 权限。

通过 UI 授予访问权限

1. 打开资源（Agent 构建器、提示词表单、MCP 服务器设置等）
2. 点击 Share 按钮（当您是所有者、管理员或已被授予 SHARE 权限时可见）
3. 在分享对话框中：
   • 使用人员选择器搜索要添加的用户、组或角色
   • 为每个主体选择一个访问角色（Viewer / Editor / Owner）
   • 可以选择性地切换 Public access，使该资源对实例上的所有人可见（需要 SHARE_PUBLIC 功能权限）
4. 保存。受赠者在下次刷新时即可看到该资源。

授权用户所见

• 查看者在相关选择器（例如 agent 下拉菜单）中将资源视为可直接使用的项目。他们无法打开构建器、查看原始指令或修改设置。
• Editors 可以打开资源的配置并进行修改，但不能删除或重新共享它。
• Owners 拥有与原始作者相同的 UI，并且可以自由删除和重新共享。
• 原始作者无论 ACL 状态如何，始终保留完全控制权，且管理员可以管理实例上的任何资源。

项目继承

权限可以从父级 project 继承。当 ACL 条目被继承时，inheritedFrom 链接会指向源头。这就是 LibreChat 中“全局 (Global)”项目的功能实现方式，添加到全局项目中的资源无需为每个主体单独添加条目，即可供所有用户使用。

层级 3：系统授权（管理员功能）

系统授权（System grants）是一个独立的授权表，用于管理员级别的功能，用于回答诸如_“该用户能否访问管理面板？”或“该群组能否全局管理 MCP 服务器？”_之类的问题。它们始终限定于主体（用户、群组或角色）以及一个功能字符串。

规范功能包括：

管理（Manage）权限隐含了其对应的读取（Read）权限（例如，拥有 manage:users 会自动授予 read:users 权限）。SystemRoles.ADMIN 用户隐式拥有所有权限；授权功能允许您将部分管理员权限委派给非管理员主体，而无需将其设为完全的管理员。

系统权限通过管理面板进行授予和撤销。

Principals in Depth

用户

标准的 LibreChat 账户。用户可以是本地账户（电子邮件/密码）或联合账户（OAuth2、OIDC、SAML、LDAP）。联合用户可以匹配到外部身份（idOnTheSource）；对于 Entra ID，这是 OID，它也是实现组同步的关键。

组

组是用户的命名集合。LibreChat 支持两个来源：

• 本地组 (Local groups)：在管理面板中创建和管理，或直接在数据库中进行管理。成员为 LibreChat 用户 ID。
• Entra ID (Azure AD) 组：当用户通过启用了 token reuse 的 Azure OIDC 登录时，这些组会从 Microsoft Graph 同步。每个同步的组都会将其 Entra 对象 ID 存储为 idOnTheSource，这使得 LibreChat 能够与租户成员资格保持同步。

组可以出现在任何 ACL、peoplePicker 搜索中，并作为配置覆盖或系统授权的主要目标。与一个 500 人的组共享的单个资源仅占用一个 ACL 条目（而非 500 个），且 Entra 中的成员资格变更会在下次登录时自动同步。

角色

任何系统角色或自定义角色都可以用作主体。将 Agent 与角色（例如 SupportEngineers）共享，即可让当前拥有该角色的所有用户获得访问权限，而无需逐一列出个人。对于角色共享仅限管理员操作的环境，可以通过 interface.peoplePicker.roles 在人员选择器中隐藏这些角色。

公共

一个匹配所有已认证用户的特殊主体。仅当授予权限的用户针对该资源类型拥有 SHARE_PUBLIC 功能权限时，才允许授予公开权限。

人员选择器可见性

人员选择器（共享对话框中的搜索框）可以在实例级别进行限制，以隐藏与您的部署无关的主体类型：

interface:
  peoplePicker:
    users: true
    groups: true
    roles: false

这仅影响 搜索 UI；现有的针对隐藏主体类型的 ACL 条目将继续正常工作并被强制执行。

从 ACL 之前的版本进行迁移

v0.8.0-rc3 之前的版本使用了更简单的所有权模型。升级需要运行 ACL 迁移，以确保现有的 Agent 和提示词仍然可以访问：

预演（预览更改）：

npm run migrate:agent-permissions:dry-run
npm run migrate:prompt-permissions:dry-run

执行：

npm run migrate:agent-permissions
npm run migrate:prompt-permissions

请参阅 agents 迁移指南 以了解 Docker 变体和 batch-size 选项。

相关文档

• 智能体：共享与权限
• 界面配置（功能权限）
• 身份验证
• OpenID Connect 令牌重用（Entra ID 组同步所必需）
• Azure / Entra ID OAuth2
• SharePoint 集成
• Agents API (Remote Agents)
• LibreChat 管理面板