Agnaistic（Agnai）· 可自托管的 AI 角色扮演聊天前端 · 部署与使用全指南
项目仓库： https://github.com/agnaistic/agnai
开源协议：AGPL-3.0 · 运行时：Node.js + pnpm · 持久化：MongoDB（可选） · 消息：Redis（可选） · 默认端口：3001 · 在线版：agnai.chat · 仓库分支：dev
说明：任务清单登记仓库为
Agnaistic/Agnaistic，该仓库已更名为agnaistic/agnai，本文按当前官方仓库撰写。
1 项目简介
Agnaistic（Agnai）是一个可自托管的 AI 角色扮演聊天前端：用你自己选择的 AI 服务，与个性化角色聊天。它早期基于 PygmalionAI 的 Galatea-UI 发展而来，定位是多用户、多机器人的群组聊天与角色扮演平台，支持接入 Kobold、Novel、AI Horde、Goose、OpenAI、Claude、Replicate、OpenRouter、Mancer 等多种后端。
它以 NPM 包形式发布，一条 npm install agnai -g
即可全局安装；也提供 Docker 镜像与源码自构建路径。MongoDB 与 Redis
都是可选的——没有 MongoDB 时自动进入 Guest Only（仅匿名）模式。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Agnaistic（Agnai） |
| 仓库地址 | github.com/agnaistic/agnai |
| 项目定位 | 可自托管的 AI 角色扮演聊天前端 |
| 开源协议 | AGPL-3.0 |
| 运行时 | Node.js + pnpm v8 |
| 持久化 | MongoDB（可选，无库则 Guest Only 模式） |
| 消息总线 | Redis（可选，WebSocket 分布式消息） |
| 默认端口 | 3001（http://localhost:3001） |
| 数据目录 | ~/.agnai |
| 在线版 | agnai.chat |
1.2 适用场景
- 想在自托管环境里玩多角色、多机器人的 AI 角色扮演聊天。
- 希望接入多种 AI 后端（OpenAI、Claude、Kobold、AI Horde 等）而不自建模型。
- 需要多租户：用户认证、每人自己的 AI 服务设置与生成预设。
1.3 能力边界（官方口径）
- MongoDB 与 Redis 均为可选；无 MongoDB 时以匿名模式运行，数据存在浏览器本地存储，不能跨设备共享。
- 可选 Pipeline 功能（长期记忆、Wikipedia/PDF 向量化）需额外启用。
- 项目本身不提供模型，需自行配置后端 API。
2 功能特性
- 群组对话：多用户 + 多机器人。
- 多 AI 服务：Kobold、Novel、AI Horde、Goose、OpenAI、Claude、Replicate、OpenRouter、Mancer。
- 多种人设格式：W++、Square bracket（SBF）、Boostyle、纯文本。
- 多租户：用户认证、独立设置、独立生成预设。
- 记忆与世界书：Memory/Lore books；AI 生成角色；第三方图像生成。
- 可选 Pipeline：长期记忆、Wikipedia 文章与 PDF 向量化嵌入。
3 官方界面预览
本仓库 README 未提供界面截图，实际界面以浏览器访问
http://localhost:3001 或在线版 agnai.chat 为准。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/agnaistic/agnai | 源码与 Docker 镜像 |
| 在线版 | https://agnai.chat | 官方在线版本 |
| Discord | https://discord.agnai.chat | 官方社区 |
| 上游原型 | PygmalionAI/galatea-ui | 早期基础 |
5 前置要求与服务器配置
5.1 软件前提
- Node.js：从 nodejs.org 安装。
- MongoDB（可选）：提供持久化与多用户能力。
- Redis（可选）：WebSocket 分布式消息。
- Docker（容器方式）：可选。
5.2 硬件建议
| 项目 | 建议 |
|---|---|
| 部署方式 | 前端较轻，2C2G 即可；MongoDB 另配 |
| 端口 | 3001 |
| 存储 | ~/.agnai 存图片与 JSON |
6 方式一：NPM 全局安装（最快）
# 安装或更新
npm install agnai -g
# 启动
agnai
# 查看启动选项
agnai help
# 启用 Pipeline 功能
agnai --pipeline数据存放在 ~/.agnai（Linux 示例
/home/<user>/.agnai/，macOS 为
/Users/<user>/.agnai，Windows 为
C:\Users\<user>\.agnai）。
7 方式二：Docker 部署
7.1 无 MongoDB（最快）
docker run -dt --restart=always -p 3001:3001 ghcr.io/agnaistic/agnaistic:latest访问 http://localhost:3001。
7.2 带 MongoDB（完整功能）
git clone https://github.com/agnaistic/agnai.git
cd agnaistic
docker compose -p agnai -f self-host.docker-compose.yml up -d8 方式三：源码手动运行
# 1. 克隆
git clone https://github.com/agnaistic/agnai.git
cd agnai
# 2. 安装依赖（每次更新后都跑）
npm run deps
# 3. 构建
npm run build:all
# 4. 启动（Mac/Linux）
npm run start
# Windows
npm run start:win
# 对外 Local Tunnel
npm run start:public # Win: npm run start:public:win9 配置项说明
| 配置 | 位置 | 说明 |
|---|---|---|
settings.json |
仓库根目录 | 全局应用级配置，示例见
template.settings.json，改后需重启 |
baseEndTokens |
settings.json | 在基础结束 token 上追加 |
| 匿名访问 | settings.json | 可禁用匿名访问 |
| 数据目录 | ~/.agnai |
图片与 JSON 存储 |
| 端口 | 3001 | 浏览器访问 |
10 常用运维命令
# NPM 方式启动
agnai
# Docker 查看日志
docker logs -f <container>
# 源码开发：用 Docker 起 MongoDB
npm run up
# 一键起全部（Linux/macOS）
npm run start:all11 常见故障排查
- 无 MongoDB 时只能匿名：官方称未检测到数据库时进入 Guest Only 模式，数据存浏览器本地；需要多用户请部署 MongoDB。
- 端口 3001 冲突：改端口或停占用进程。
- 依赖安装失败：
npm run deps基于 pnpm v8，更新仓库后务必重跑。 - settings.json 不生效：修改后需重启 Agnai。
12 风险与合规说明
- 许可证：AGPL-3.0，二次分发与网络服务须开源对应修改。
- 后端 API 合规：接入的 OpenAI/Claude 等服务须遵守其服务条款与密钥安全。
- 内容合规：角色扮演内容需自行负责。
- 非官方声明：本文基于官方仓库 README 整理，仓库已由
Agnaistic/Agnaistic更名为agnaistic/agnai，命令以 dev 分支最新为准。