danny-avila/LibreChat · 上手攻略

  • 仓库：danny-avila/LibreChat
  • 链接：https://github.com/danny-avila/LibreChat
  • 分类：agent / ai
  • 作者：Jay
  • 更新：2026-07-09

这是什么

LibreChat 是一个开源自托管 AI 聊天平台，核心定位是"统一所有主流 AI provider 的 ChatGPT 增强克隆"。它支持 Anthropic Claude、OpenAI（含 GPT-4o / o1 / GPT-5）、Azure OpenAI、Google Gemini、AWS Bedrock、DeepSeek、Mistral、OpenRouter 等几乎所有主流大模型 API，一个界面自由切换，无需为每个 provider 单独开工具。

在此基础上，LibreChat 还提供：AI Agents（含无代码构建助手 + Agent 市场）、MCP（Model Context Protocol）工具支持、Code Interpreter（沙箱代码执行）、Artifacts 代码画布、对话分支/Fork、多用户认证管理、Web Search、图片生成等企业级功能。

Stars 4 万（ trending，周增 +210），主分类 agent，成熟度 production，MIT 协议。

解决什么问题

  1. 不想被单一 AI provider 绑定：ChatGPT Plus 只能 OpenAI，Claude App 只能 Anthropic——LibreChat 一个界面聚合所有，随便换。
  2. 需要 AI Agent 但不想自己搭 infra：内置无代码 Agent 构建器 + MCP 支持，开箱即用。
  3. 需要私有化部署：数据完全在自己服务器上，适合企业内网、医疗/法律等敏感场景。
  4. 需要 Code Interpreter：在对话中实时运行 Python / Node.js / Go / C / Java / PHP / Rust / Fortran 代码。
  5. 团队多人使用：内置多用户认证、角色权限管理、Token 用量控制。
  6. 多语言界面：支持 30+ 种语言 UI，包括中文简繁体。

快速安装

Docker（推荐，最简单）

依赖：Git + Docker Desktop。

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

# 创建环境配置文件
cp .env.example .env

# 启动（首次拉取镜像需要几分钟）
docker compose up -d

# 打开浏览器访问
# http://localhost:3080
# 第一个注册的账号自动成为管理员

Apple Silicon Mac 用户注意：M 系列芯片不支持 AVX 指令，默认 MongoDB 镜像会崩溃。需要创建 docker-compose.override.yml 改用 mongo:4.4.18 镜像。

配置 AI API Keys

编辑 .env 文件，填入你需要 provider 的 API Key。默认 .env 包含各 provider 的环境变量注释模板，常见配置：

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# 可选：自定义 OpenAI 兼容端点（如本地 Ollama）
OPENAI_REVERSE_PROXY=http://localhost:11434/v1/chat/completions

默认 .env 可直接跑基础功能，但使用任何 AI 模型都需要填入对应 provider 的 API key。

平台一键部署

不想自己维护 Docker？官方提供多个平台的一键部署模板：

平台 地址
Railway railway.com/deploy（参考文档）
Zeabur zeabur.com/templates
Sealos template.cloud.sealos.io

核心功能与用法

1. 多模型自由切换

对话界面左上角模型选择器，支持在任意对话中实时切换 provider 和模型。支持的 provider 包括（部分）：

  • Anthropic：Claude 3.5 / Claude 3 Opus
  • OpenAI：GPT-4o、o1、GPT-5（需账号权限）
  • Azure OpenAI：企业用户
  • Google：Gemini 系列
  • AWS Bedrock：Claude / Llama / Mistral
  • DeepSeek：DeepSeek Chat / Coder
  • Ollama：本地模型（需自托管）
  • OpenRouter：聚合 100+ 模型

2. LibreChat Agents（无代码构建 AI 助手）

在对话界面左侧边栏创建专属 Agent，无需写代码：

  • 设置 Agent 的系统提示词（角色定位）
  • 选择 Agent 可使用的工具（MCP、搜索、代码执行等）
  • 设置工具使用权限
  • 发布到 Agent 市场（可选）

3. MCP 支持

LibreChat 是官方 MCP 客户端，支持连接任意 MCP Server 来扩展工具能力。配置方法：

  1. 在设置中添加 MCP Server URL 和 API Key
  2. MCP Server 提供的工具自动出现在 Agent 工具列表中
  3. 支持过滤不需要的工具

4. Code Interpreter（沙箱代码执行）

在对话中直接执行代码，支持 8 种语言：

你：帮我用 Python 写一个快速排序
（Agent 写出代码，自动在沙箱中执行，返回结果）

执行完全隔离，安全限制防止恶意操作。

5. 多用户与权限管理

内置 Admin Panel，可： - 管理用户、群组、角色 - 设置每个角色的功能权限（能否用 DALL-E、Code Interpreter 等） - 实时修改配置，无需重新部署 - 查看 Token 用量

开启后 Agent 可实时搜索互联网并获取结果作为上下文。支持自定义搜索 provider 和 Jina Reranking。

典型适用场景

场景 为什么用 LibreChat
企业私有 AI 平台 完全自托管，数据不外流
多模型对比评测 同一问题同时问 Claude、GPT-4o、Gemini
团队 AI 工具共享 多用户 + 权限管理 + 用量控制
AI 助手市场 Agent 可以在社区分享
需要 Code Interpreter 对话中实时执行代码并看结果
受监管行业（医疗/法律） 自托管 + 审计日志

坑与注意

  1. 第一个注册的账号 = 管理员：没有默认密码，第一步就注册你自己的账号。注册完记得去 Admin Panel 配置安全策略。
  2. Apple Silicon Mac 必须用 MongoDB 4.4：具体做法：在项目根目录创建 docker-compose.override.yml，内容如下：

yaml services: mongodb: image: mongo:4.4.18

  1. Port 3080 被占用：修改 docker-compose.override.yml：

yaml services: api: ports: - "3081:3080"

然后访问 http://localhost:3081。

  1. 更新版本：先 docker compose down，再 git pull，最后 docker compose up -d。注意先备份 .env 和数据卷。
  2. 容器启动崩溃：先 docker compose logs api 看日志，常见原因：.env 文件缺失、librechat.yaml 语法错误。
  3. OpenAI 配额限制：如果用 OpenRouter 或其他反向代理，配额政策各有不同，注意别超限导致服务中断。
  4. 中文界面：LibreChat UI 支持中文，但 Agent 的系统提示词仍需自己翻译配置。

与同类对比

维度 LibreChat Open WebUI Chatbot UI Jan
Provider 支持数量 20+ Ollama 为主 OpenAI only 主要是本地
AI Agents ✅ 内置无代码构建 ❌ ❌ ❌
MCP 支持 ✅ 官方支持 插件 ❌ ❌
Code Interpreter ✅ 沙箱执行 ❌ ❌ ❌
多用户/权限 ✅ 完整 基础 ❌ ❌
自托管 ✅ Docker 一键 ✅ ✅ ✅
Artifacts 画布 ✅ ❌ ❌ ❌
中文 UI ✅ ❌ ❌ ❌

LibreChat 是功能最全的开源自托管 ChatGPT 克隆——不只是换皮，而是一个完整的 AI 工作站，支持 Agent 构建、MCP 扩展、企业级多用户管理。缺点是配置项多（好处是灵活），新手建议先用 Docker 默认配置跑起来再逐步定制。

一句话推荐结论

如果你需要把主流 AI 模型统一到一个界面、自托管部署、支持团队多人使用且有 Agent 构建能力，LibreChat 是目前功能最完整、文档最完善的开源方案——Docker 一行命令跑起来，不需要懂运维。