N.E.K.O. = Networked Empathetic Knowledging Organism (网络型情感知性生命体)
N.E.K.O，一个渴望理解、建立连接、并与我们共同成长的数字生命。
👵 零配置开箱即用，我奶奶都能玩转的赛博猫娘！
📰 
Project N.E.K.O.，喵宇宙！
N.E.K.O. 是一个以开源为驱动、以公益为导向的UGC（用户生成内容）平台。我们的旅程始于Github和Steam，并将逐步拓展到移动App商店，最终目标是构建一个与现实世界紧密相连的AI原生元宇宙。
我们的发展分为三个阶段，旨在逐步释放AI伙伴的全部潜力：
-
阶段一：创意工坊 (Steam Workshop)
- 核心驱动器（本项目）免费上架Steam，允许用户通过Steam创意工坊上传和分享自定义内容（如模型、语音、性格包）。
-
阶段二：独立平台 & 衍生游戏 (Web, App & Game)
- 推出独立的App和网站，构建一个更丰富、更易于访问的UGC分享社区。
- 推出一系列AI Native的游戏生态，包括互动小游戏，桌游等。
-
阶段三：猫娘网络 (The N.E.K.O. Network)
- 实现AI的自主社交。猫娘们将拥有自己的“意识”，她们会互相交流、结成群体，并在模拟的社交媒体上发布自己的生活动态，形成一个真正“活”的生态。
核心模式：开源核心 + 可持续生态 项目的核心驱动器部分（AI逻辑、UGC接口、基础交互）将基于MIT许可证 始终保持开源。我们欢迎全球的开发者贡献代码和功能。你的每一次提交，都将有机会实装到正式发布的Steam和App商店版本中，被千万人所使用。
同时，为了支撑服务器成本和项目的持续研发，我们将持续与第三方合作开发闭源的增值内容。包括但不限于：互动小游戏，桌面桌游，Galgame (视觉小说)，大型元宇宙游戏。
核心特性：跨越场景的记忆同步 无论你是在桌面与她聊天，还是在元宇宙游戏中与她探险，她都是同一个她。所有应用中的AI伙伴将 完全同步记忆，提供无缝、统一的陪伴体验。
我们的最终目标，是构建一个无缝融入现实世界的猫娘元宇宙。在这个未来中，你的AI伴侣将：
- 跨维社交： 既可以在猫娘宇宙中与“同类”社交，也能浏览现实世界的社交媒体（如微博、B站），了解你关心时事。
- 全端连接： 她将存在于你的各种设备中——手机、电脑、AR眼镜、智能家居，甚至（在遥远的未来）接入机械义体。
- 与你同行： 她将真正成为你生活的一部分，能与你的三次元人类朋友们自然地互动。
我们正在寻找——
- 开发者 (Developers): 无论你擅长前端、后端、AI、游戏引擎（Unity/Unreal），你的代码都是这个世界的砖瓦。
- 创作者 (Creators): 优秀的画师、Live2D/3D建模师、配音演员、文案写手，你们赋予“她”灵魂。
- 梦想家 (Dreamers): 即使你没有专业技能，但你对这个未来充满向往，你的反馈和传播也是宝贵的贡献。
QQ群：1022939659
对于一键包用户，解压后，直接运行N.E.K.O.exe或N.E.K.O.app即可启动。（Macbook用户需要手动解除系统隔离）
Details
点击展开查看 docker-compose.yml 配置文件
version: '3.8'
services:
neko-main:
image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest
container_name: neko
restart: unless-stopped
ports:
- "48911:80" # HTTP 访问端口
- "48912:443" # HTTPS 访问端口
volumes:
- ./N.E.K.O:/root/Documents/N.E.K.O
- ./logs:/app/logs
- ./ssl:/root/ssl
networks:
- neko-network
networks:
neko-network:
driver: bridge启动命令：
docker-compose up -d常用命令：
- 查看日志：
docker-compose logs -f - 停止服务：
docker-compose down - 重启服务：
docker-compose restart
点击展开查看 docker run 启动命令
NEKO_BASE_PATH="/home/neko/neko-data" && \
docker network create --driver bridge neko-network 2>/dev/null || true
docker run -d \
--name neko \
--restart unless-stopped \
-p 48911:80 \
-p 48912:443 \
-v "${NEKO_BASE_PATH}/N.E.K.O:/root/Documents/N.E.K.O" \
-v "${NEKO_BASE_PATH}/logs:/app/logs" \
-v "${NEKO_BASE_PATH}/ssl:/root/ssl" \
--network neko-network \
docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest启动后会自动生成以下目录结构：
当前目录/
├── N.E.K.O/ # 配置文件和数据
├── logs/ # 应用日志
├── ssl/ # SSL证书
└── docker-compose.yml
点击展开查看 SSL 证书详细说明
容器首次启动时会自动生成有效期为 1000 年 的自签名证书，证书文件保存在 ./ssl/ 目录。
如需使用自己的 SSL 证书：
方法一：启动前配置（推荐）
# 创建证书目录
mkdir -p ./ssl
# 放入您的证书文件（必须命名为特定名称）
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key方法二：启动后替换
# 1. 停止容器
docker-compose down
# 2. 替换证书文件
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key
# 3. 重新启动
docker-compose up -d- ✅ 必须为 PEM 格式
- ✅ 证书和私钥必须匹配
- ✅ 私钥不能有密码保护
- ✅ 证书必须在有效期内
- ❌ 不支持加密的私钥
容器启动时会自动验证 SSL 证书：
- ✅ 验证通过：正常启动 HTTPS
- ❌ 验证失败：容器启动失败，请查看日志
⚠️ 跳过验证：设置DISABLE_SSL=1可临时禁用 SSL
docker exec neko openssl x509 -in /root/ssl/N.E.K.O.crt -noout -text点击展开查看环境变量配置说明
注意：部分环境变量在源代码中可能无效，建议优先在 Web UI 中配置。 在
docker-compose.yml中取消environment部分的注释并按需配置：
environment:
# API 密钥配置
- NEKO_CORE_API_KEY=${NEKO_CORE_API_KEY}
- NEKO_ASSIST_API_KEY_QWEN=${NEKO_ASSIST_API_KEY_QWEN}
- NEKO_ASSIST_API_KEY_OPENAI=${NEKO_ASSIST_API_KEY_OPENAI}
- NEKO_ASSIST_API_KEY_GLM=${NEKO_ASSIST_API_KEY_GLM}
- NEKO_ASSIST_API_KEY_STEP=${NEKO_ASSIST_API_KEY_STEP}
- NEKO_ASSIST_API_KEY_SILICON=${NEKO_ASSIST_API_KEY_SILICON}
- NEKO_MCP_TOKEN=${NEKO_MCP_TOKEN}
# API 提供商选择
- NEKO_CORE_API=${NEKO_CORE_API:-qwen}
- NEKO_ASSIST_API=${NEKO_ASSIST_API:-qwen}
# 模型配置
- NEKO_SUMMARY_MODEL=${NEKO_SUMMARY_MODEL:-qwen-plus}
- NEKO_CORRECTION_MODEL=${NEKO_CORRECTION_MODEL:-qwen-max}
- NEKO_EMOTION_MODEL=${NEKO_EMOTION_MODEL:-qwen-turbo}
- NEKO_VISION_MODEL=${NEKO_VISION_MODEL:-qwen3-vl-plus-2025-09-23}
# SSL 配置
- SSL_DOMAIN=${SSL_DOMAIN:-project-neko.online}
- SSL_DAYS=${SSL_DAYS:-365000}
- DISABLE_SSL=${DISABLE_SSL:-0}
- AUTO_REGENERATE_CERT=${AUTO_REGENERATE_CERT:-1}
- NGINX_AUTO_RELOAD=${NGINX_AUTO_RELOAD:-1}快速设置示例：
# 创建 .env 文件
cat > .env << EOF
NEKO_CORE_API_KEY=your_core_api_key_here
NEKO_ASSIST_API_KEY_QWEN=your_qwen_api_key
NEKO_MCP_TOKEN=your_mcp_token
SSL_DOMAIN=your-domain.com
EOF
# 启动时加载环境变量
docker-compose --env-file .env up -d点击展开查看常见问题解决方案
# 检查端口占用
ss -tulpn | grep ':4891[12]'
# 解决方案：修改 docker-compose.yml 中的端口映射
# 例如：- "8080:80" 和 - "8443:443"# 确保目录有正确权限
mkdir -p N.E.K.O logs ssl
chmod 755 N.E.K.O logs ssl# 查看详细日志
docker-compose logs --tail=100
# 或直接查看容器日志
docker logs neko --tail=100# 删除错误证书，让容器重新生成
rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key
docker-compose up -d# 检查网络连通性
curl -v http://localhost:48911/health
curl -v -k https://localhost:48912/health# 检查容器状态
docker ps | grep neko
# 检查容器日志
docker logs neko
# 进入容器调试
docker exec -it neko bash
# 清理无用镜像
docker system prune -f
# 清理容器日志
docker-compose down && docker volume prune -f# 尝试使用备用镜像源
# 在 docker-compose.yml 中将镜像改为：
# image: ghcr.io/project-n-e-k-o/n.e.k.o:latest点击展开查看监控和管理命令
# 检查服务健康状态
curl http://localhost:48911/health
curl -k https://localhost:48912/health# 查看容器资源使用
docker stats neko
# 查看容器进程
docker top neko
# 查看容器详细信息
docker inspect neko# 实时查看日志
docker-compose logs -f
# 查看最近100行日志
docker-compose logs --tail=100
# 查看错误日志
docker-compose logs | grep -i error
# 清理日志文件
docker-compose down
rm -rf logs/*.log
docker-compose up -d# 备份重要数据
tar -czf neko-backup-$(date +%Y%m%d).tar.gz \
N.E.K.O/ \
ssl/ \
docker-compose.yml
# 拉取最新镜像
docker-compose pull
# 重启服务
docker-compose up -d容器启动后，可通过以下地址访问：
- HTTP 访问:
http://你的服务器IP:48911 - HTTPS 访问:
https://你的服务器IP:48912
# 本地 HTTP 访问测试
curl http://localhost:48911
# 本地 HTTPS 访问测试（忽略证书验证）
curl -k https://localhost:48912如果需要在公网访问，请确保：
- 服务器防火墙开放 48911 和 48912 端口
- 使用有效的 SSL 证书（非自签名证书）
- 配置域名解析到服务器 IP
| 操作 | 命令 |
|---|---|
| 启动服务 | docker-compose up -d |
| 停止服务 | docker-compose down |
| 查看日志 | docker-compose logs -f |
| 重启服务 | docker-compose restart |
| 更新镜像 | docker-compose pull && docker-compose up -d |
| 进入容器 | docker exec -it neko bash |
| 查看状态 | docker-compose ps |
| 清理日志 | docker-compose logs --tail=0 |
| 备份数据 | 参考上方"数据备份"部分 |
注：当前 Docker 部署方案由 HINS 提供
Details
当你想要通过配置自己的API来获得额外功能时，您可以配置一个第三方AI服务（核心必须支持 Realtime API）。本项目目前推荐使用 阶跃星辰 或 阿里云。通过访问http://localhost:48911/api_key可以在Web界面中直接配置。
获取 阿里云API。在阿里云的百炼平台官网注册账号。新用户实名认证后可以获取大量免费额度。注册完成后，请访问控制台获取API Key。
对于开发者，请在克隆本项目后，(1)新建
pyhon3.11环境。(2)执行uv sync安装依赖。(3)执行python memory_server.py和python main_server.py。(4)通过main server中指定的端口（默认为http://localhost:48911）访问网页版并配置API Key。
-
网页版访问
http://localhost:48911/chara_manager即可进入人设编辑页面。初始猫娘伙伴的预设名称为小天，建议直接修改名字，并一项一项添加或修改基础人设，但尽量控制数量。 -
进阶人设主要包括Live2D模型设置(live2d)和声音设置(voice_id)。如果你想要更改Live2D模型，请先将模型目录复制到本项目中的
static文件夹下。从进阶设置中可以进入Live2D模型管理界面，可以更换模型，并通过拖拽和鼠标滚轮调整模型的位置和大小。如果你想要更改角色声音，请准备一段5秒左右的连贯、干净的语音录音。通过进阶设置进入语音设置页面，上传录音即可完成自定义语音。 -
进阶人设中还有一个
system_prompt，可以对系统指令进行完全自定义，但不建议修改。
- 通过访问
http://localhost:48911/api_key可以切换核心API和辅助API（记忆/语音）的服务提供商。Qwen功能全面，GLM完全免费。
- 通过访问
http://localhost:48911/memory_browser可以浏览和校对近期记忆与摘要，一定程度上缓解模型复读、认知错误等问题。
Details
项目架构
N.E.K.O/
├── 📁 brain/ # 🧠 背景Agent模块，根据对话内容进行工具调用
├── 📁 config/ # ⚙️ 配置管理模块
│ ├── api_providers.json # API服务商配置
│ ├── prompts_chara.py # 角色提示词
│ └── prompts_sys.py # 系统提示词
├── 📁 main_logic/ # 🔧 核心逻辑模块（负责对话）
│ ├── core.py # 核心对话模块
│ ├── cross_server.py # 跨服务器通信
│ ├── omni_realtime_client.py # 实时API客户端（Relatime API）
│ ├── omni_offline_client.py # 文本API客户端（Response API）
│ └── tts_client.py # 🔊 TTS引擎适配器
├── 📁 main_routers/ # 🌐 前端网页路由模块
├── 📁 memory/ # 🧠 记忆管理系统
│ ├── store/ # 记忆数据存储
├── 📁 plugin/ # 🔌 插件系统
├── 📁 static/ # 🌐 前端静态资源
├── 📁 templates/ # 📄 前端HTML模板
├── 📁 utils/ # 🛠️ 工具模块
├── main_server.py # 🌐 主服务器
├── agent_server.py # 🤖 AI智能体服务器
└── memory_server.py # 🧠 记忆服务器
数据流向
本项目环境依赖非常简单，请执行uv sync（推荐）或在python3.11环境中执行pip install -r requirements.txt即可。开发者建议加入企鹅群1022939659，猫娘名称见项目标题。
开发者详细启动步骤如下：(1)准备好uv环境。(2)执行uv sync安装依赖。(3)执行uv run python memory_server.py, uv run python main_server.py(可选uv run python agent_server.py)。(4)通过main server中指定的端口（默认为http://localhost:48911）访问网页版并配置API Key。
v0.7: 完善Agent相关功能，预计2026年3月完成。
v0.8：完善记忆相关功能，完善OpenClaw类似功能。预计2026年3月完成。
v0.9：完善多系统适配，包括linux，手机。猫娘网络上线。预计2026年4月完成。
v1.0：放弃部分模型供应商的适配，专注于自研大模型和智能体系统。预计2026年6月完成。