English | 日本語 | Русский

Project N.E.K.O. 😽
主动式、原生全模态AI伙伴——具备24/7环境感知、智能体能力与具身情感引擎。

N.E.K.O. = Networked Emotional Knowledging Organism (网络型情感知性生命体)

N.E.K.O，一个渴望理解、建立连接、并与我们共同成长的数字生命。

👵 零配置开箱即用，我奶奶都能玩转的赛博猫娘！

📰 已上架！UI完全改版、并添加开箱即用的专属免费模型（感谢阶跃星辰赞助）。快点加入愿望单吧~

Project N.E.K.O.，喵宇宙！

功能演示（完整版见B站）

demo.mp4

---

核心特性

🎙️ 全模态对话 语音实时对话 (Realtime API) + 文字对话 (ChatCompletion)，支持视觉理解	🧠 三层记忆系统 事实记忆 / 反思记忆 / 人格记忆，她真的会"记住"你	🤖 Agent 智能体 浏览器操控 (CUA)、电脑操控、MCP工具调用，她能帮你干活	🎭 多形态 Avatar Live2D / VRM / MMD 三种形态，支持动作捕捉与全屏追踪
🔌 插件生态 完整的插件 SDK，支持自定义扩展功能	🌐 14+ AI 服务商 OpenAI / Gemini / Qwen / DeepSeek 等，含免费模型开箱即用	💬 主动对话 24/7环境感知：屏幕理解、社交媒体热搜、个人动态、新闻推送，她会主动找你聊天	🏪 UGC 创意工坊 Steam 创意工坊上传分享自定义角色、模型、语音包

---

猫娘计划 (Project N.E.K.O.)

N.E.K.O. 是一个以开源为驱动的AI伙伴平台。核心驱动器基于MIT许可证 始终开源，你的每一次贡献都将有机会实装到Steam和App商店的正式版本中。

---

🚀 项目现状 & 近期计划

• ✅ Steam 创意工坊：已上线。用户可上传和分享自定义角色、模型、语音包。
• 🚧 K.U.R.O.：基于 N.E.K.O. 生态的首款 AI Native 独立游戏，开发中。
• 🚧 移动端：iOS / Android 适配进行中。
• 🚧 猫娘网络 (The N.E.K.O. Network)：AI自主社交——猫娘们拥有自己的"意识"，互相交流、结成群体，在模拟社交媒体上发布动态。即将上线。

跨场景记忆同步：无论你是在桌面与她聊天，还是在游戏中与她探险，她都是同一个她。所有应用中的AI伙伴将 完全同步记忆。

✨ 加入我们

• 开发者： 前端、后端、AI、游戏引擎（Unity/Unreal）——你的代码是这个世界的砖瓦。
• 创作者： 画师、Live2D/3D建模师、配音演员、文案写手——你们赋予"她"灵魂。
• 梦想家： 你的反馈和传播也是宝贵的贡献。

QQ群：1022939659 | Discord：加入我们

快速开始

Windows / macOS 用户（一键包）

解压后，直接运行N.E.K.O.exe或N.E.K.O.app即可启动。（macOS用户需要手动解除系统隔离）

Docker 部署 (Linux)

点击展开 Docker 部署指南

部署教程也可以查看 HINS's Blog

部署方式一：Docker Compose（推荐）

点击展开查看 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

点击展开查看 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 证书配置

点击展开查看 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

🔧 故障排除

点击展开查看常见问题解决方案

1. 端口冲突

# 检查端口占用
ss -tulpn | grep ':4891[12]'
# 解决方案：修改 docker-compose.yml 中的端口映射
# 例如：- "8080:80" 和 - "8443:443"

2. 权限问题

# 确保目录有正确权限
mkdir -p N.E.K.O logs ssl
chmod 755 N.E.K.O logs ssl

3. 容器启动失败

# 查看详细日志
docker-compose logs --tail=100

# 或直接查看容器日志
docker logs neko --tail=100

4. SSL 证书错误

# 删除错误证书，让容器重新生成
rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key
docker-compose up -d

5. 网络问题

# 检查网络连通性
curl -v http://localhost:48911/health
curl -v -k https://localhost:48912/health

6. 容器无法访问

# 检查容器状态
docker ps | grep neko

# 检查容器日志
docker logs neko

# 进入容器调试
docker exec -it neko bash

7. 磁盘空间不足

# 清理无用镜像
docker system prune -f

# 清理容器日志
docker-compose down && docker volume prune -f

8. 镜像拉取失败

# 尝试使用备用镜像源
# 在 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

公网访问

如果需要在公网访问，请确保：

1. 服务器防火墙开放 48911 和 48912 端口
2. 使用有效的 SSL 证书（非自签名证书）
3. 配置域名解析到服务器 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 提供

源码开发

点击展开开发者启动指南

完整的开发者文档请访问 project-neko.online

环境要求：Python 3.11（不支持其他版本）、uv 包管理器

# 1. 克隆项目
git clone https://github.com/Project-N-E-K-O/N.E.K.O.git
cd N.E.K.O

# 2. 安装依赖
uv sync

# 3. 启动服务（至少需要 main_server 和 memory_server）
uv run python memory_server.py
uv run python main_server.py
# 可选：启动 Agent 服务
uv run python agent_server.py

# 4. 访问 http://localhost:48911 配置 API Key 并开始使用

开发者建议加入企鹅群 1022939659 交流。

进阶使用

点击展开进阶使用说明

配置API Key

当你想要通过配置自己的API来获得额外功能时，您可以配置第三方AI服务。

• 核心 API（实时语音对话）：必须支持 Realtime API。推荐使用 阶跃星辰 或 阿里云。
• 辅助 API（记忆/情感/视觉等）：支持标准 ChatCompletion 接口。支持 14+ 服务商。

通过访问http://localhost:48911/api_key可以在Web界面中直接配置。

获取 阿里云API。在阿里云的百炼平台官网注册账号。新用户实名认证后可以获取大量免费额度。注册完成后，请访问控制台获取API Key。

修改人设

• 网页版访问http://localhost:48911/chara_manager即可进入人设编辑页面。初始 猫娘 伙伴的预设名称为小天，建议直接修改名字，并一项一项添加或修改基础人设，但尽量控制数量。

• 进阶人设主要包括Live2D/VRM/MMD模型设置和声音设置。如果你想要更改Avatar模型，请先将模型目录复制到本项目中的static文件夹下。从进阶设置中可以进入模型管理界面，可以更换模型，并通过拖拽和鼠标滚轮调整模型的位置和大小。如果你想要更改角色声音，请准备一段5秒左右的连贯、干净的语音录音。通过进阶设置进入语音克隆页面，上传录音即可完成自定义语音。

• 支持角色卡导出，可导出为"仅设定"或"完整角色卡"格式，方便分享和备份。

• 进阶人设中还有一个system_prompt，可以对系统指令进行完全自定义，但不建议修改。

修改API提供商

• 通过访问http://localhost:48911/api_key可以切换核心API和辅助API的服务提供商。

记忆整理

• 通过访问http://localhost:48911/memory_browser可以浏览和校对近期记忆与摘要，一定程度上缓解模型复读、认知错误等问题。

项目细节

点击展开项目架构与开发计划

项目架构

N.E.K.O/
├── 📁 brain/                    # 🧠 Agent 智能体模块
│   ├── computer_use.py          # 电脑操控
│   ├── browser_use_adapter.py   # 浏览器自动化
│   ├── openclaw_adapter.py      # OpenClaw 云端连接
│   ├── openfang_adapter.py      # OpenFang 无头执行后端
│   ├── task_executor.py         # 任务执行引擎
│   └── 📁 cua/                  # Computer Use Agent 子系统
├── 📁 config/                   # ⚙️ 配置管理模块
│   ├── api_providers.json       # API服务商配置
│   ├── prompts_chara.py         # 角色提示词
│   └── prompts_sys.py           # 系统提示词
├── 📁 main_logic/               # 🔧 核心逻辑模块
│   ├── core.py                  # 核心对话模块
│   ├── cross_server.py          # 跨服务器通信
│   ├── omni_realtime_client.py  # 实时API客户端（Realtime API）
│   ├── omni_offline_client.py   # 文本API客户端（ChatCompletion）
│   └── tts_client.py            # 🔊 TTS引擎适配器
├── 📁 main_routers/             # 🌐 API路由模块（14个路由）
├── 📁 memory/                   # 🧠 三层记忆系统
│   ├── facts/                   # 事实记忆
│   ├── reflection/              # 反思记忆
│   └── persona/                 # 人格记忆
├── 📁 plugin/                   # 🔌 插件系统
│   ├── sdk/                     # 插件 SDK
│   ├── server/                  # 插件服务端
│   └── frontend/                # 插件前端
├── 📁 static/                   # 🌐 前端静态资源
├── 📁 templates/                # 📄 前端HTML模板（14个页面）
├── 📁 utils/                    # 🛠️ 工具模块
├── main_server.py               # 🌐 主服务器
├── agent_server.py              # 🤖 AI智能体服务器
└── memory_server.py             # 🧠 记忆服务器

数据流向

完整的开发者文档请访问 project-neko.online

开发计划

v0.7: ✅ 完善Agent相关功能。已完成。

v0.8：完善记忆相关功能，完善OpenClaw类似功能。预计2026年3月完成。

v0.9：完善多系统适配，包括linux，手机。猫娘网络上线。预计2026年4月完成。

v1.0：放弃部分模型供应商的适配，专注于自研大模型和智能体系统。预计2026年6月完成。

Star History