[!WARNING] 该项目的作者已暂停开发至二月，不过我（@brrock）会尽力修复漏洞和问题。如果你正在贡献代码，可能需要等到开发恢复后再继续。

🚀 在线演示 | 在下方的【预览】中查看实际体验！

演示对话

• MCP 工具演示: 与工具聊天
• 图像生成演示: 与图像生成聊天

快速开始 🚀

几分钟内即可运行你的应用！无需安装或付费。

你只需要一个 AI 提供商的 API 密钥（如 OpenAI、Claude、Gemini 等）。其他部分都可使用免费层级的服务——数据库、文件存储和托管。

👉 点击此指南，只需几下就能部署你的网站

---

Better Chatbot —— 一款面向个人和团队的更优秀的开源 AI 聊天机器人，灵感来源于 ChatGPT、Claude、Grok 和 Gemini。

• 多 AI 支持 —— 集成所有主流 LLM：OpenAI、Anthropic、Google、xAI、Ollama 等
• 强大工具 —— MCP 协议、网页搜索、JS/Python 代码执行、数据可视化
• 图像生成 —— 使用 AI 模型（OpenAI、Google Gemini、xAI）创建和编辑图像
• 自动化 —— 自定义智能体、可视化工作流、成果物生成
• 协作 —— 与团队共享智能体、工作流和 MCP 配置
• 语音助手 —— 实时语音聊天，全面集成 MCP 工具
• 直观 UX —— 使用 @mention 即可快速调用任何功能
• 快速启动 —— 使用 Vercel 部署按钮即可免费部署

基于 Vercel AI SDK 和 Next.js 构建，将领先 AI 服务的最佳特性整合到一个平台中。

目录

• 目录
• 预览
  • 🧩 使用 Playwright MCP 进行浏览器自动化
  • 🔗 可视化工作流作为自定义工具
  • 🤖 自定义智能体
  • 🎙️ 实时语音助手 + MCP 工具
  • ⚡️ 快速工具提及 (@) & 预设
  • 🧭 工具选择模式
  • 🛠️ 默认工具
    • 🌐 网页搜索
    • ⚡️ JS,PYTHON 执行器
    • 📊 数据可视化工具
• 入门
  • 快速开始（Docker Compose 版本） 🐳
  • 快速开始（本地版本） 🚀
  • 环境变量
• 📘 指南
  • 🔌 MCP 服务器设置 & 工具测试
  • 🐳 Docker 托管指南
  • ▲ Vercel 托管指南
  • 🗂️ 文件存储驱动程序
  • 🎯 系统提示 & 聊天定制
  • 🔐 OAuth 登录设置
  • 🕵🏿 添加类似 OpenAI 的提供商
  • 🧪 E2E 测试指南
• 💡 小贴士
  • 💬 临时聊天窗口
• 🗺️ 路线图
• 🙌 贡献
• 💬 加入我们的 Discord

本项目正以惊人的速度发展！⚡️ 我们不断推出新功能并修复 bug。请 星标此仓库，加入我们，随时了解最新动态！

预览

感受一下用户体验——以下是一些可能的操作示例。

🧩 使用 Playwright MCP 进行浏览器自动化

示例: 使用微软的 playwright-mcp 工具控制网页浏览器。

• LLM 会自主决定如何使用 MCP 服务器上的工具，多次调用它们来完成一个多步骤的任务，并返回最终消息。

示例提示：

1. 使用 @tool('web-search') 查找关于“modelcontetprotocol”的信息。

2. 然后，使用 : @mcp("playwright")
   - 导航到 Google (https://www.google.com)
   - 点击“登录”按钮
   - 输入我的邮箱地址 (neo.cgoing@gmail.com)
   - 点击“下一步”按钮
   - 关闭浏览器

🔗 可视化工作流作为自定义工具

示例: 创建自定义工作流，使其成为聊天对话中可调用的工具。

• 通过连接 LLM 节点（用于 AI 推理）和工具节点（用于 MCP 工具执行）来构建可视化工作流
• 发布工作流，使其在聊天中作为 @workflow_name 工具可用
• 将复杂的多步骤流程串联成可重复使用的自动化序列

🤖 自定义智能体

示例：使用自定义指令和工具访问权限创建专业化的 AI 智能体。

• 定义具有特定系统提示和可用工具的自定义智能体
• 在聊天中通过 @agent_name 轻松调用智能体
• 构建任务专用助手，例如带有议题/PR 工具和项目上下文的 GitHub 管理员智能体

例如，通过以下步骤创建一个 GitHub 管理员智能体：

• 提供 GitHub 工具（创建议题/PR、评论、查询）
• 将项目详情添加到系统提示中
• 使用 @github_manager 调用它来管理你的仓库

🎙️ 实时语音助手 + MCP 工具

此演示展示了基于 OpenAI 新实时 API 构建的 实时语音聊天机器人助手 — 现已扩展为完全集成 MCP 工具。 自然地与助手交谈，观看它实时执行工具操作。

⚡️ 快速工具提及（@）及预设

在聊天过程中，只需输入 @toolname 即可快速调用工具。 无需记忆——只需键入 @ 并从列表中选择即可！

工具选择与提及（@）——何时使用哪种方式：

• 工具选择：使常用工具在所有聊天中始终对 LLM 可用。非常适合方便使用，并可在长时间内保持一致的上下文。
• 提及（@）：仅临时绑定所提及的工具用于该次响应。由于只有提及的工具会被发送给 LLM，这可以节省 token，并提高速度和准确性。

每种方法都有其优势——将它们结合使用，以平衡效率和性能。

你还可以通过仅选择所需的 MCP 服务器或工具来创建 工具预设。 只需单击一下即可立即切换预设——非常适合按任务或工作流程组织工具。

🧭 工具选择模式

使用 工具选择模式 控制每个聊天中工具的使用方式——随时可通过 ⌘P 切换。

• 自动：模型会在需要时自动调用工具。
• 手动：模型将在调用工具前请求您的许可。
• 无：完全禁用工具使用。

这使您能够根据具体情况灵活选择自主、引导或无工具交互。

🛠️ 默认工具

🌐 网络搜索

内置网络搜索功能，由 Exa AI 提供支持。使用语义 AI 搜索网络，并直接在聊天中提取 URL 中的内容。

• 可选：将 EXA_API_KEY 添加到 .env 文件中以启用网络搜索
• 免费层级：每月 1,000 次请求，无需付费，无需信用卡
• 轻松设置：立即在 dashboard.exa.ai 获取 API 密钥

🎨 图像生成

内置图像生成和编辑功能，由 AI 模型提供支持。直接在聊天中创建、编辑和修改图像。

• 支持的操作：图像生成、编辑和合成
• 当前模型：Gemini Nano Banana、OpenAI

⚡️ JS、PYTHON 执行器

这是一个简单的 JS 执行工具。

📊 数据可视化工具

交互式表格：创建功能丰富的数据表格，具备高级功能：

• 排序与筛选：按任意列排序，实时筛选数据
• 搜索与高亮显示：全局搜索并自动高亮文本
• 导出选项：使用惰性加载库导出为 CSV 或 Excel 格式
• 列管理：通过可见性控件显示/隐藏列
• 分页：内置分页功能，可处理大型数据集
• 数据类型支持：正确格式化字符串、数字、日期和布尔值

图表生成：使用各种图表类型（柱状图、折线图、饼图）可视化数据

此外，还提供了许多其他工具，例如用于 API 请求的 HTTP 客户端等。

……还有更多精彩内容等着你。 快来试试看吧！

开始使用

本项目推荐使用 pnpm 作为包管理器。

# 如果尚未安装 pnpm：
npm install -g pnpm

快速开始（Docker Compose 版本） 🐳

# 1. 安装依赖
pnpm i

# 2. 在项目根目录的 .env 文件中，仅填写您想要使用的 LLM 提供商 API 密钥。
# 例如：只需填写 OPENAI_API_KEY，应用即可运行。
# （运行 pnpm i 时会自动创建 .env 文件。）

# 3. 使用 Docker Compose 构建并启动所有服务（包括 PostgreSQL）
pnpm docker-compose:up

快速开始（本地版本） 🚀

pnpm i

#（可选）启动本地 PostgreSQL 实例
# 如果您已经运行了自己的 PostgreSQL，则可以跳过此步骤。
# 在这种情况下，请确保更新 .env 文件中的 PostgreSQL URL。
pnpm docker:pg

# 在 .env 文件中填写必要信息
# .env 文件会自动生成。只需填写所需值即可。
# 为了最快设置，至少提供一个 LLM 提供商的 API 密钥（例如 OPENAI_API_KEY、CLAUDE_API_KEY、GEMINI_API_KEY 等）以及您想要使用的 PostgreSQL URL。

pnpm build:local && pnpm start

#（大多数情况下推荐。可确保正确的 Cookie 设置。）
# 对于支持热重载和调试的开发模式，可以使用：
# pnpm dev

替代方案：仅使用 Docker Compose 运行数据库（通过 pnpm 运行应用）

# 仅通过 compose 启动 Postgres
# 确保您的 .env 包含：POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB，且与 POSTGRES_URL 匹配
docker compose -f docker/compose.yml up -d postgres

# 应用迁移
pnpm db:migrate


# 在本地运行应用
pnpm dev   # 或：pnpm build && pnpm start

在浏览器中打开 http://localhost:3000，即可开始使用。

环境变量

运行 pnpm i 命令会生成一个 .env 文件。请在其中添加您的 API 密钥。

# === LLM 提供商 API 密钥 ===
# 您只需填写计划使用的提供商密钥
GOOGLE_GENERATIVE_AI_API_KEY=****
OPENAI_API_KEY=****
XAI_API_KEY=****
ANTHROPIC_API_KEY=****
OPENROUTER_API_KEY=****
OLLAMA_BASE_URL=http://localhost:11434/api



# Better Auth 的密钥（使用：npx @better-auth/cli@latest secret 生成）
BETTER_AUTH_SECRET=****

#（可选）

# Better Auth 的 URL（您访问应用的 URL）
BETTER_AUTH_URL=

# === 数据库 ===
# 如果您本地没有运行 PostgreSQL，请使用以下命令启动：pnpm docker:pg
POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name

# （可选）
# === 工具 ===
# Exa AI 用于网络搜索和内容提取（可选，但建议用于 @web 和研究功能）
EXA_API_KEY=your_exa_api_key_here


# 是否使用基于文件的 MCP 配置（默认：false）
FILE_BASED_MCP_CONFIG=false

# === 文件存储 ===
# Vercel Blob 是默认的存储驱动程序（在本地开发和生产环境中均可使用）
# 在本地通过 `vercel env pull` 获取令牌
FILE_STORAGE_TYPE=vercel-blob
FILE_STORAGE_PREFIX=uploads
BLOB_READ_WRITE_TOKEN=

# -- S3（即将推出）--
# FILE_STORAGE_TYPE=s3
# FILE_STORAGE_PREFIX=uploads
# FILE_STORAGE_S3_BUCKET=
# FILE_STORAGE_S3_REGION=

# （可选）
# === OAuth 设置 ===
# 仅当您希望启用 Google/GitHub/Microsoft 登录时才填写这些值

# GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# 设置为 1 可强制选择账户
GOOGLE_FORCE_ACCOUNT_SELECTION=


# Microsoft
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
# 可选的租户 ID
MICROSOFT_TENANT_ID=
# 设置为 1 可强制选择账户
MICROSOFT_FORCE_ACCOUNT_SELECTION=

# 将此设置为 1 可禁用用户注册。
DISABLE_SIGN_UP=

# 将此设置为 1 可禁止添加 MCP 服务器。
NOT_ALLOW_ADD_MCP_SERVERS=

📘 指南

逐步设置指南，帮助您运行和配置 better-chatbot。

🔌 MCP 服务器设置与工具测试

• 如何在您的环境中添加和配置 MCP 服务器

🐳 Docker 托管指南

• 如何使用 Docker 自行托管聊天机器人，包括环境配置。

▲ Vercel 托管指南

• 通过简单的设置步骤将聊天机器人部署到 Vercel，以供生产使用。

🗂️ 文件存储驱动程序

• 基于云的文件存储，使用 Vercel Blob（默认）实现开发和生产环境中的无缝上传。S3 支持即将推出。

🎯 系统提示与聊天自定义

• 使用自定义系统提示、用户偏好和 MCP 工具说明，个性化您的聊天机器人体验

🔐 OAuth 登录设置

• 配置 Google、GitHub 和 Microsoft 的 OAuth，以支持安全的用户登录。

🕵🏿 添加类似 OpenAI 的提供商

• 添加类似 OpenAI 的 AI 提供商

🧪 端到端测试指南

• 使用 Playwright 进行全面的端到端测试，包括多用户场景、代理可见性测试以及 CI/CD 集成
  

💡 技巧

💬 临时聊天窗口

• 打开轻量级弹出式聊天窗口，用于快速解答旁支问题或进行测试——与您的主对话线程分开。

🗺️ 路线图

better-chatbot 即将推出的计划功能：

• 文件上传与存储（Vercel Blob 集成）
• 图像生成
• 协作文档编辑（类似于 OpenAI Canvas：用户与助手共同编辑）
• RAG（检索增强生成）
• 基于 Web 的计算（结合 WebContainers 集成）

💡 如果您有任何建议或需要特定功能，请创建一个 issue！

💖 支持

如果该项目对您有所帮助，请考虑支持其开发：

• ⭐ Star 此仓库
• 🐛 报告 问题并提出功能建议
• 💰 成为赞助者，以支持持续开发

您的支持有助于维护和改进该项目。感谢！ 🙏

🙌 贡献

我们欢迎所有贡献！无论是错误报告、功能想法还是代码改进，每一份帮助都能让我们打造最佳的本地 AI 助手。

⚠️ 请在提交任何 Pull Request 或 Issue 之前阅读我们的 贡献指南。 这将帮助我们更高效地合作，并节省大家的时间。

有关详细的贡献指南，请参阅我们的 贡献指南。

语言翻译： 通过添加新的语言翻译，帮助我们让更多的用户能够使用该聊天机器人。有关如何贡献翻译的说明，请参阅 language.md。

让我们一起构建吧 🚀

💬 加入我们的 Discord

在我们的官方 Discord 服务器上与社区交流、提问并获得支持！

Better Chatbot 快速上手指南

Better Chatbot 是一个基于 Next.js 和 Vercel AI SDK 构建的开源 AI 聊天机器人模板。它支持多模型接入（OpenAI, Claude, Gemini 等）、MCP 协议工具调用、代码执行、图像生成及实时语音助手等功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Node.js: 推荐版本 v18.17 或更高
• 包管理器: 项目推荐使用 pnpm
• API Key: 至少需要一个主流大模型提供商的 API Key（如 OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY 等）
• 可选依赖:
  • Docker & Docker Compose: 如果您希望使用容器化部署（包含数据库）。
  • PostgreSQL: 如果选择本地运行且不使用 Docker，需自行准备数据库。

安装步骤

1. 安装 pnpm (如果尚未安装)

npm install -g pnpm

2. 克隆项目并安装依赖

git clone https://github.com/cgoinglove/better-chatbot.git
cd better-chatbot
pnpm i

运行 pnpm i 后，项目根目录会自动生成 .env 文件模板。

3. 配置环境变量

编辑项目根目录下的 .env 文件，填入您的 LLM 提供商 API Key。至少配置一项即可运行。

# .env 文件示例
BETTER_AUTH_SECRET=any_secret_value_here
OPENAI_API_KEY=sk-your-openai-key
# 或者
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
# 或者
GOOGLE_GENERATIVE_AI_API_KEY=your-google-key

# 可选：启用网络搜索功能
EXA_API_KEY=your-exa-key

4. 启动项目

您可以选择以下两种方式之一启动服务：

方式 A：Docker Compose 启动（推荐，包含数据库）

此方式会自动拉起 PostgreSQL 数据库和其他必要服务。

pnpm docker-compose:up

方式 B：本地开发模式启动

如果您已自行配置好本地 PostgreSQL 数据库，可直接运行：

pnpm dev

启动成功后，通常在浏览器访问 http://localhost:3000 即可看到界面。

基本使用

启动项目后，您可以通过以下方式体验核心功能：

1. 基础对话

在聊天框输入问题，系统将自动调用您配置的默认大模型进行回答。

2. 快捷调用工具 (@ 命令)

无需切换菜单，直接在输入框输入 @ 即可唤起工具列表。这是该项目的核心交互方式。

• 调用网络搜索: 输入 @web-search 然后描述查询内容。

  @web-search 查询最新的 Model Context Protocol 文档
  

• 调用代码执行器: 输入 @js 或 @python 让 AI 编写并运行代码。

  @python 计算斐波那契数列的前 10 项并绘制图表
  

• 调用自定义 Agent 或工作流: 如果您创建了特定的 Agent（如 GitHub 管理员），可通过 @agent_name 直接调用。

  @github_manager 检查当前仓库未关闭的 Issue
  

3. 工具控制模式

按下 ⌘P (Mac) 或 Ctrl+P (Windows/Linux) 可快速切换工具使用策略：

• Auto: 模型自动决定何时调用工具。
• Manual: 模型调用工具前需用户确认。
• None: 禁用所有工具，仅进行纯文本对话。

4. 一键部署 (可选)

如果您不想本地运行，可以直接点击项目首页的 Deploy with Vercel 按钮，按照指引填写 API Key 即可在云端免费部署实例。