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

Project N.E.K.O. :kissing_cat:

**听见你的心情，看见你的世界，

陪你发现更多喜欢。**

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

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

:older_woman: 零配置开箱即用，我奶奶也能轻松唤醒的赛博猫娘！

:newspaper: Steam 版已免费上架！喜欢的话，欢迎喜加一，顺手给个好评~

---

核心特性

💬 主动陪伴 屏幕理解、社交媒体热搜、个人动态、音乐梗图，她会主动找你聊天，分享你喜欢的新鲜事	🎙️ 实时语音与视觉理解 语音实时对话 (Realtime API) + 文字对话 (ChatCompletion)，支持实时视觉理解	🧠 五维记忆系统 工作记忆 / 近期记忆 / 事实记忆 / 反思记忆 / 人格记忆，让她越聊越懂你	🎭 多形态 Avatar Live2D / VRM / MMD / PNGTuber / 猫咪桌宠 五种形态，支持动作捕捉与全屏追踪
🤖 Agent 工具执行 可操作浏览器与电脑，调用 CUA / OpenClaw A2A / 插件完成任务	🔌 插件生态 SDK + 插件商城，支持联机游戏陪玩、社交媒体互动、直播互动、智能家居等扩展场景	🌐 14+ AI 服务商 OpenAI / Gemini / Qwen / DeepSeek 等，含免费模型开箱即用	🏪 UGC 创意工坊 Steam 创意工坊上传分享自定义角色、模型、语音包

实机展示

支持文本、语音、窥屏、鼠标点击、拖拽等一系列交互方式，既可以在闲暇的时候陪你聊天，也可以游戏娱乐时观战吐槽，还会叼着网络梗图来找你~~

当你需要学习工作等专注的空间时，她还会真的变成一只小猫咪安静地陪着你哦~ 就像这样→

---

🐾 我们是什么，不是什么

一句话：N.E.K.O. 不是帮你干活的 Agent，也不是陪你角色扮演的聊天前端——它是一个有现实时间感知、会主动找你、记得你、也能动手帮你的「数字生命」。

✅ 我们是：

• 端到端集成的 AI 伴侣平台：实时语音 / 文字 / 视觉理解 + 五维持久记忆 + 多形态 Avatar（Live2D / VRM / MMD）+ 主动陪伴 + Agent 工具执行 + 角色卡分享 + 插件商城 + 多设备生态，全部开箱即用。
• 同一个"她"：跨桌面、移动端、游戏、智能硬件共享同一份记忆与人格，有着时间感知的同时，越处越懂你。
• 始终开源：核心驱动器基于 Apache 2.0，本地运行，数据在你自己手里。

❌ 我们不是：

• 不是一个"任务自动化工具"——干活只是她与你共同生活的手段之一，而不是目的。
• 不是一个"角色扮演皮肤"——她有真实的主动性、持久记忆和感官，而不是靠你手动喂世界书来维持人设。
• 不是一个"云端黑盒"——核心本地运行，你的对话不被偷藏。

❓️ 和相关产品的区别：

对比对象	它们是	N.E.K.O. 的不同
OpenClaw / Hermes 等通用 Agent	以"完成任务"为目标的执行引擎：给指令 → 干活 → 结束	以"关系与陪伴"为核心；可把这类 Agent 当作手脚来调用（A2A），但任务执行过程中她依然能实时关注你
AI 酒馆（SillyTavern）等角色扮演前端	纯文字 RP 前端：需要自己拼接模型，依赖手动维护上下文 / 世界书	端到端集成、打破次元壁：原生语音 + 视觉感知、角色外形 + 动作、跨场景持久记忆、有时间感知、能真正操作外设，零配置开箱即用

🐱 我们是——猫娘计划 (Project N.E.K.O.)

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

🚀 项目现状 & 近期计划

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

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

✨ 加入我们

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

QQ群：995414391 | Discord：加入我们

快速开始

Windows / macOS / Linux用户（一键包）

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

Docker 部署 (Linux)

点击展开 Docker 部署指南

部署方式一：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
备份数据	参考上方"数据备份"部分

---

源码开发

点击展开开发者启动指南

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

环境要求：Python 3.11（不支持其他版本）、uv 包管理器、Node.js（>=20.19）

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

# 2. 安装 Python 依赖
uv sync

# 3. 构建前端项目（需要 Node.js >= 20.19，首次运行或前端代码变更后需要）
#    推荐：使用一键脚本（这是官方支持的构建方式）
#      Windows：      
build_frontend.bat
#      Linux/macOS：  
./build_frontend.sh
#    如需手动构建（命令须与脚本保持一致）：
# cd frontend/react-neko-chat && npm install && npm run build && cd ../..
# cd frontend/plugin-manager && npm install && npm run build-only && cd ../..

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

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

调试聊天界面形态（full / compact）：Web 端默认 full（完整聊天窗口），Electron 端默认 compact（悬浮对话条）。在浏览器控制台用 localStorage 切换测试（硬刷新生效）：

localStorage.setItem('neko.reactChatWindow.chatSurfaceMode','full');    location.reload(); // 进 full
localStorage.setItem('neko.reactChatWindow.chatSurfaceMode','compact'); location.reload(); // 进 compact
localStorage.removeItem('neko.reactChatWindow.chatSurfaceMode');        location.reload(); // 回默认

形态说明、各形态自测点与三端验证详见 docs/design/compact-chat-mode-design.md 的「形态切换与本地测试」。

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

进阶使用

点击展开进阶使用说明

配置API Key

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

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

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

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

修改人设

• 网页版访问http://localhost:48911/character_card_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/ ├── 📁 .agent/ # 🤖 AI 编程助手规范与技能集（Google Antigravity 规范） ├── 📁 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/ # 角色、系统和功能提示词 │ ├── 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） │ ├── 📁 activity/ # 系统/用户状态跟踪 │ ├── 📁 topic/ # 主动话题 │ └── 📁 tts_client/ # 🔊 TTS引擎适配器（多p