2025超详细AI Town搭建指南：从本地部署到定制化虚拟世界全流程

【免费下载链接】ai-town A MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize. 项目地址: https://gitcode.com/gh_mirrors/ai/ai-town

你是否曾梦想创建一个属于自己的虚拟世界，让AI角色在其中生活、交流并形成独特的社会网络？AI Town作为MIT许可的开源项目，提供了完整的基础框架，让你无需从零开始构建。本文将带你逐步完成从环境配置到自定义角色的全过程，即使是非技术背景的用户也能轻松上手。

项目概览：AI Town是什么？

AI Town是一个基于浏览器的虚拟社区模拟平台，灵感来源于斯坦福大学《生成式智能体》研究论文。与传统游戏不同，这里的AI角色拥有持久记忆、社交关系和自主行为能力，能够形成动态变化的虚拟社会。

项目核心优势：

• 全栈JavaScript/TypeScript开发，降低AI应用开发门槛
• 支持本地部署，保护数据隐私
• 高度可定制的角色、场景和交互规则
• 兼容多种LLM（大语言模型），包括本地Ollama和云端API

项目结构概览：

• 前端界面代码：基于React和PixiJS构建的可视化界面
• 后端逻辑：Convex提供的实时数据库和服务器函数
• 角色定义：AI居民的属性和初始设定
• 地图资源：虚拟世界的视觉元素

准备工作：环境配置指南

系统要求与依赖

AI Town支持Windows、macOS和Linux系统，但在Windows上需要通过WSL2运行。以下是最低配置要求：

• 处理器：4核CPU（推荐6核及以上）
• 内存：8GB RAM（AI模型运行建议16GB+）
• 存储空间：至少10GB（含Node依赖和LLM模型）

基础环境安装

首先确保系统已安装以下工具：

• Node.js 18.x（推荐使用nvm管理版本）
• Git
• Docker（可选，用于容器化部署）

# Ubuntu/Debian系统依赖安装示例
sudo apt update
sudo apt install -y git curl build-essential

获取项目代码

通过Git克隆仓库（国内用户推荐使用GitCode镜像）：

git clone https://gitcode.com/gh_mirrors/ai/ai-town.git
cd ai-town

快速启动：三种部署方式对比

1. 标准本地开发模式（推荐新手）

这种方式直接在本地运行前后端服务，适合开发和调试：

# 安装依赖
npm install

# 启动开发服务器
npm run dev

启动成功后，访问 http://localhost:5173 即可进入AI Town。首次启动会自动初始化数据库并创建默认角色。

2. Docker容器化部署（适合生产环境）

使用Docker Compose可以一键部署完整环境，包含前端、后端和数据库：

# 构建并启动容器
docker compose up --build -d

# 生成管理员密钥（首次运行需要）
docker compose exec backend ./generate_admin_key.sh

Docker方式会创建三个服务：

• 前端服务：http://localhost:5173
• 后端API：http://localhost:3210
• 管理面板：http://localhost:6791

3. 云部署方案（适合公网访问）

如果需要让互联网用户访问你的AI Town，可以部署到Vercel等平台：

# 安装Vercel CLI
npm install -g vercel

# 部署前端
vercel --prod

后端Convex函数需要单独部署：

npx convex deploy
npx convex run init --prod

配置AI大脑：连接大语言模型

本地LLM：使用Ollama（推荐）

Ollama允许在本地运行开源大语言模型，无需联网即可为AI角色提供对话能力：

1. 安装Ollama：下载地址
2. 拉取并启动模型：

# 下载Llama 3模型（约4.7GB）
ollama pull llama3

# 测试模型响应
ollama run llama3 "你好，我是AI Town的居民"

3. 配置AI Town连接Ollama：

npx convex env set OLLAMA_HOST http://localhost:11434

云端API：OpenAI/Together.ai

如果本地硬件配置有限，可以使用云端LLM服务：

# 使用OpenAI API示例
npx convex env set OPENAI_API_KEY "你的API密钥"

# 编辑配置文件切换模型
# [LLM配置文件](https://link.gitcode.com/i/604d61846233282c6c5b702763b9feda)

⚠️ 注意：云端API会产生费用，建议先设置使用限额。切换模型后需要运行npx convex run testing:wipeAllTables重置数据库。

定制你的虚拟世界

创建独特角色

AI Town的角色定义在data/characters.ts文件中。每个角色包含以下属性：

• 基本信息：姓名、年龄、外貌
• 性格特征：内向/外向、兴趣爱好
• 初始关系：与其他角色的社会连接
• 行为模式：日常活动偏好

修改示例：

// 添加新角色
export const characters = [
  // ...现有角色
  {
    name: "张小明",
    textureUrl: "/assets/32x32folk.png",
    spritesheetData: f3SpritesheetData,
    speed: 0.12,
    // 角色描述会被LLM用来生成对话和行为
    description: "30岁的程序员，喜欢科幻小说和咖啡，周末常去图书馆",
    // 初始位置
    x: 12,
    y: 8
  }
];

修改后需要重置数据库使新角色生效：

npx convex run testing:wipeAllTables
npm run dev

编辑地图与场景

AI Town使用瓦片地图系统，你可以通过以下步骤自定义场景：

1. 下载地图编辑器：Tiled Map Editor
2. 打开现有地图文件：gentle.js
3. 修改地形、建筑和资源点
4. 使用转换工具更新格式：

node data/convertMap.js your_map.json assets/tileset.png 16 16

提示：可以在public/assets/spritesheets/目录中添加自定义纹理，创建独特风格的世界。

添加互动元素

通过修改convex/aiTown/interaction.ts文件，可以添加新的交互规则：

• 对话触发条件
• 情绪影响机制
• 任务与成就系统

高级操作：性能优化与扩展

提升运行效率

如果模拟人数较多导致卡顿，可以尝试以下优化：

• 减少同时活跃角色数量
• 降低AI思考频率（修改constants.ts中的THINK_INTERVAL_MS）
• 使用轻量级模型（如7B参数的Llama 3）

数据管理命令

AI Town提供了多种工具命令帮助管理虚拟世界：

# 暂停/恢复模拟
npx convex run testing:stop
npx convex run testing:resume

# 存档/重置世界
npx convex run testing:archive
npx convex run testing:wipeAllTables

# 查看角色行为日志
npx convex logs --function aiTown/agent:think

常见问题解决

启动故障排除

问题症状	可能原因	解决方案
前端空白页	后端未启动	运行npm run dev:backend单独启动后端
AI不说话	Ollama未运行	检查Ollama服务状态：systemctl status ollama
内存占用过高	LLM模型过大	切换至更小的模型，如llama3:8b

网络连接问题

Docker环境下Ollama连接失败时：

# 设置Docker内部网络访问
npx convex env set OLLAMA_HOST http://host.docker.internal:11434

Windows系统特殊配置：

# WSL2端口转发
socat TCP-LISTEN:11434,fork TCP:$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):11434 &

总结与进阶方向

通过本指南，你已经掌握了AI Town的基本部署和定制方法。这个虚拟世界可以作为多种AI应用的实验平台：

进阶探索方向：

1. 扩展角色记忆系统：实现长期记忆和知识积累
2. 添加任务系统：让AI居民完成目标驱动行为
3. 开发多人交互功能：支持真实用户参与虚拟世界

项目资源：

• 官方文档：更详细的技术说明
• API参考：Convex函数接口文档
• 社区案例：其他开发者的创意实现

现在，你的AI Town已经准备就绪。看着这些虚拟居民发展关系、形成社区，你可能会惊讶于他们展现出的"自主性"。这只是AI模拟的开始，未来还有更多可能性等待探索！

【免费下载链接】ai-town A MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize. 项目地址: https://gitcode.com/gh_mirrors/ai/ai-town