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

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 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 证书配置

# 创建证书目录
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

docker exec neko openssl x509 -in /root/ssl/N.E.K.O.crt -noout -text

⚙️ 环境变量配置

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

公网访问

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

1. 服务器防火墙开放 48911 和 48912 端口
2. 使用有效的 SSL 证书（非自签名证书）
3. 配置域名解析到服务器 IP

⏱️ 快速参考

完整的开发者文档请访问 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 并开始使用

开发者建议加入企鹅群 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）
│   └── tts_client.py            # 🔊 TTS引擎适配器
├── 📁 main_routers/             # 🌐 API路由模块（14个路由）
├── 📁 memory/                   # 🧠 五维记忆系统（部分示例）
│   ├── facts/                   # 事实记忆
│   ├── reflection/              # 反思记忆
│   └── persona/                 # 人格记忆
├── 📁 frontend/                 # 🖥️ 现代前端项目
│   ├── react-neko-chat/         # React 聊天窗口组件
│   └── plugin-manager/          # Vue 插件管理面板
├── 📁 plugin/                   # 🔌 插件系统
│   ├── sdk/                     # 插件 SDK
│   └── server/                  # 插件服务端
├── 📁 static/                   # 🌐 前端静态资源（含构建产物）
├── 📁 templates/                # 📄 前端HTML模板（14个页面）
├── 📁 utils/                    # 🛠️ 工具模块
├── 📁 app/                      # 🚀 服务器入口模块
│   ├── main_server.py           # 🌐 主服务器
│   ├── agent_server.py          # 🤖 AI智能体服务器
│   ├── memory_server.py         # 🧠 记忆服务器
│   └── monitor.py               # 📺 独立观看端
└── launcher.py                  # 🎬 一键启动入口（打包入口）

AI 辅助开发：.agent/ 目录遵循 Google Antigravity 开放规范，包含项目的开发规范和技能集。只有 Antigravity 自动读取，其他 AI 工具（含 Claude Code）需手动导入，详见适配指引。

数据流向

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

主页新手引导提示的维护说明见 docs/design/tutorial_prompt_maintenance.zh-CN.md

开发计划

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

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

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

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

遥测说明 (Telemetry)

N.E.K.O. 默认开启匿名 Token 用量遥测，用于跟踪版本兼容性、模型用量分布与异常率。我们认同"用数据改进产品"的合理性，但更认同"不偷不藏"。

一键关闭 (Opt-out)：设置环境变量 DO_NOT_TRACK=1（或 NEKO_DO_NOT_TRACK=1）即可完全禁用遥测，无需重新构建，立刻生效。这是开源界通用的约定，我们也遵守。

我们收集 / 不收集什么：

关于"假名化设备标识"：单向 SHA-256，不可逆、不含用户信息。同一台机器（同一 OS 安装）会复现相同标识，按 GDPR / PIPL 口径属于"假名化标识"而非"完全匿名数据"。仅用于去重 DAU 计数与版本兼容性归因。

关于 Steam64：这是 Steam 客户端在你登录后向所有第三方 SDK 暴露的公开数字 ID（Steam 个人页 URL 末尾就是它）。本身不含邮箱、手机号或真实姓名，但跨会话稳定。触发条件以代码为准：app/main_server.py 启动时无条件调用 initialize_steamworks()，utils/token_tracker.py 的 _get_telemetry_steam_user_id() 只要 SDK 起来且 Users.GetSteamID() 返回非零就上报，并不区分 source / release / steam 这三种 distribution 渠道。典型场景是 Steam 发行版，但源码版如果安装了 steamworks Python 包并保留了 steam_appid.txt、同时 Steam 客户端在登录态，同样会带 Steam64。如果你不希望它被上报：(1) 最稳的 DO_NOT_TRACK=1 全关；(2) 退出 Steam 客户端；(3) 源码用户可在环境中卸载 steamworks 包或移除 steam_appid.txt。

完整实现与传输协议见 utils/token_tracker.py 与 local_server/telemetry_server/README.md：HMAC-SHA256 防篡改、±5min 时间窗防重放、滑动窗口限流（120 req/h/device）、append-only 存储；每个 server 进程最多约 1 次/60s 上报（与本地落盘节流共用同一计时器），不影响主流程性能。