Nuwax

Nuwax AI - 轻松构建和部署您的私有智能体AI解决方案。

官方网站：https://nuwax.com

演示：https://agent.nuwax.com

中文文档|English Doc | Contributing | Documentation

安装与部署

使用官方的 nuwax-cli 命令工具，可快速在本地部署服务。

快速开始

环境准备

系统要求

• 系统要求：Ubuntu 22.04 LTS 或更高版本（其他 Linux 发行版尚未完全测试）、macOS 10.15+、Windows 10/11（支持即将推出）
• 硬件要求：4 核 8GB 内存或更高
• 环境要求：Docker、Docker Compose V2 环境 Docker 安装指南

支持的平台

• Linux：x86_64、ARM64
  • Ubuntu 22.04 LTS（推荐）
  • 当前用户需要 Docker 权限，可通过 docker ps 进行验证。若遇到权限问题，可使用 sudo 权限运行。
  • 建议使用阿里云镜像加速。
• macOS：Intel、Apple Silicon（M1/M2）、Universal
  • macOS 10.15（Catalina）及更高版本
  • 推荐使用 OrbStack（个人使用免费，性能更优）
  • 确保 OrbStack 或 Docker Desktop 已启动。
  • 首次使用可能需要允许未知开发者：系统偏好设置 → 安全与隐私。

本地部署服务指南

共有两种部署服务：

• 主项目服务（必选）
• 智能体计算机（沙箱）部署指南（可选）

在主本地服务中，配置一个或多个智能体计算机部署地址，即可使用智能体计算机（沙箱）。由于“智能体计算机（沙箱）”包含一台个人计算机（沙箱），需要更多资源，因此支持跨多台服务器单独部署。

部署主服务

安装文档

智能体计算机（沙箱）部署指南

您可以在多台不同的服务器上部署智能体计算机服务，通过配置实现分布式智能体沙箱功能。

环境要求：每台服务器都需要安装 Docker 和 Docker Compose 环境，请参考 Docker 安装文档。

安装文档

常用管理命令

服务管理

• 启动服务：./nuwax-cli docker-service start
• 停止服务：./nuwax-cli docker-service stop
• 重启服务：./nuwax-cli docker-service restart
• 查看状态：./nuwax-cli docker-service status

备份管理

备份服务需要停止 Docker 应用服务器，建议在业务低峰期操作。

• 一键备份（推荐）：
  • 手动执行备份：./nuwax-cli auto-backup run
  • 列出所有备份：./nuwax-cli list-backups
  • 从备份恢复：./nuwax-cli rollback [BACKUP_ID]

升级管理

应用服务升级时，使用命令 ./nuwax-cli auto-upgrade-deploy run 将自动检测并下载新版本进行部署。

完整升级流程如下：

# 检查部署客户端是否有新版本并更新
./nuwax-cli check-update install
# 更新应用服务
./nuwax-cli auto-upgrade-deploy run

Docker 环境安装

重要提示：Docker 和 Docker Compose 是运行本服务的核心依赖，必须正确安装。

如果您的系统尚未安装 Docker 环境，请参阅详细的 Docker 环境安装指南。

本安装指南包含以下平台的详细安装步骤：

• Ubuntu 24.04.3 LTS（推荐的 Linux 发行版）
• macOS（支持 OrbStack 和 Docker Desktop）
• 镜像加速配置（适用于中国大陆用户）

推荐：一键 Docker 安装脚本

社区提供的一键 Docker 安装脚本

该脚本支持 13 种 Linux 发行版，包括国产操作系统（openEuler、Anolis OS、OpenCloudOS、Alinux、Kylin Linux），可一键安装 Docker 和 Docker Compose，并自动配置玄元镜像加速。

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本特点与优势

✅ 支持 13 种主流发行版：openEuler、OpenCloudOS、Anolis OS、Alinux（阿里云）、Kylin Linux、Fedora、Rocky Linux、AlmaLinux、Ubuntu、Debian、CentOS、RHEL、Oracle Linux

✅ 完整支持国产操作系统：深度适配国产 OS（openEuler、Anolis OS、OpenCloudOS、Alinux、Kylin Linux），支持自动检测版本并进行最优配置

✅ 智能多镜像源切换：内置 6 个以上国内镜像源，包括阿里云、腾讯云、华为云、中科大、清华等，自动检测并选择最快的源

✅ 特殊处理老旧系统：支持已过期的系统，如 Ubuntu 16.04、Debian 9/10，自动配置兼容的安装方案

✅ 双重安装保障：若包管理器安装失败，会自动切换到二进制安装，确保安装成功率

✅ macOS/Windows 友好提示：自动检测 macOS 和 Windows 系统，提供合适的 Docker Desktop 安装指导

快速 Docker 安装验证：

# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker compose version

# 运行测试容器
docker run hello-world

若上述命令均成功运行，则您的 Docker 环境已准备就绪，可以继续进行 Nuwax 服务的部署。

架构图

┌────────────────────────────────────────────────────────────────────────────┐
│                           前端层                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────────────┐  │
│  │  PC Web  │  │   H5     │  │ Mini App │  │  IM (飞书/钉钉/  │  │
│  │          │  │          │  │          │  │   钉钉/Slack)         │  │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                        接入层                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────────┐   │
│  │  REST API    │  │  长        │  │       WebSocket             │   │
│  │              │  │ 连接       │  │                             │   │
│  └──────────────┘  └──────────────┘  └──────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                      应用层                                     │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              组件库                                       │  │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │  │
│  │  │ Model│ │Know- │ │ Data │ │Plugin│ │ Work-│ │  MCP │ │ Skill│ │  │
│  │  │      │ │ ledge│ │ Table│ │      │ │ flow │ │      │ │      │ │  │
│  │  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              管理后台                                        │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │  用户    │ │  审计   │ │  公共  │ │ 内容  │ │   任务   │ │  │
│  │  │管理    │ │管理   │ │  模型   │ │管理   │ │管理   │ │  │
│  │  ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ │  │
│  │  │   日志    │ │   菜单   │ │ 系统   │ │          │ │          │ │  │
│  │  │  查询   │ │权限   │ │  配置  │ │          │ │          │ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              产品应用                                    │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │  │
│  │  │   Web App    │  │   Q&A        │  │    General Agent         │  │  │
│  │  │              │  │   Agent      │  │                          │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                    基础设施层                                    │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                    底层组件                            │  │
│  │                                                                       │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────────┐ │  │
│  │  │   Cloud     │  │  nuwaclaw   │  │   General Agent Engine     │ │  │
│  │  │   Sandbox   │  │  PC Client │  │                            │ │  │
│  │  │             │  │ (mac/win/   │  │  ┌───────────────────────┐ │  │
│  │  │             │  │  docker)    │  │  │  MCP Integration      │ │  │
│  │  │             │  │             │  │  ├───────────────────────┤ │  │
│  │  │             │  │             │  │  │  文件管理     │ │  │
│  │  │             │  │             │  │  │  技能管理     │ │  │
│  │  │             │  │             │  │  │  ACP适配器层    │ │  │
│  │  │             │  │             │  │  │  ┌─────────────────┐ │ │  │
│  │  │             │  │             │  │  │  │ 支持的Agent:│ │ │  │
│  │  │             │  │             │  │  │  │ claudecode      │ │ │  │
│  │  │             │  │             │  │  │  │ opencode        │ │ │  │
│  │  │             │  │             │  │  │  │ codex           │ │ │  │
│  │  │             │  │             │  │  │  │ openclaw        │ │ │  │
│  │  │             │  │             │  │  │  │ kimicli         │ │ │  │
│  │  │             │  │             │  │  │  └─────────────────┘ │ │  │
│  │  │             │  │             │  │  ├───────────────────────┤ │  │
│  │  │             │  │             │  │  │  浏览器             │ │  │
│  │  │             │  │             │  │  │  自动化          │ │  │
│  │  │             │  │             │  │  │  GUI自动化      │ │  │
│  │  │             │  │             │  │  │  网络通道     │ │  │
│  │  │             │  │             │  │  │  运行时集成     │ │  │
│  │  │             │  │             │  │  └───────────────────────┘ │  │
│  │  │             │  │             │  └─────────────────────────────┘ │  │
│  │  └─────────────┘  └─────────────┘                                   │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                    核心基础设施                                │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐  │  │
│  │  │ Database │ │  Cache   │ │  Vector  │ │  Search  │ │ Model │  │  │
│  │  │  MySQL   │ │  Redis   │ │  Milvus  │ │ Elastic  │ │ Proxy│  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────┘  │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘

项目仓库概览

Nuwax AI 智能体平台由多个相互关联的仓库组成：

前端与移动端

仓库	描述	URL
nuwax	前端 Web	https://github.com/nuwax-ai/nuwax
nuwax-mobile	移动应用	https://github.com/nuwax-ai/nuwax-mobile
noVNC	基于 Web 的 VNC 客户端	https://github.com/nuwax-ai/noVNC

后端与应用层

仓库	描述	URL
nuwax-backend	应用层（后端）	https://github.com/nuwax-ai/nuwax-backend

智能体引擎与客户端

仓库	描述	URL
nuwaclaw	智能体 PC 客户端（mac/win/docker）	https://github.com/nuwax-ai/nuwaclaw
nuwaxcode	Nuwa 智能体引擎（基于开源 opencode）	https://github.com/nuwax-ai/nuwaxcode
claude-code-acp-ts	基于 Zed 的 Claude Code ACP	https://github.com/nuwax-ai/claude-code-acp-ts

基础设施与服务

仓库	描述	URL
rcoder	沙箱与容器调度（包含通用智能体引擎）	https://github.com/nuwax-ai/rcoder
mcp-proxy	MCP 服务（供沙箱使用）	https://github.com/nuwax-ai/mcp-proxy
nuwax-file-server	文件服务（供沙箱和 nuwaclaw 使用，包含技能同步）	https://github.com/nuwax-ai/nuwax-file-server

Web 应用开发

仓库	描述	URL
xagi-frontend-templates	Web 应用开发模板	https://github.com/nuwax-ai/xagi-frontend-templates
vite-plugin-design-mode	可视化编辑器 Vite 插件	https://github.com/nuwax-ai/vite-plugin-design-mode
dev-inject	Web 应用智能脚本注入	https://github.com/nuwax-ai/dev-inject

插件与脚本执行

仓库	描述	URL
run_code_rmcp	插件脚本执行（TypeScript/JavaScript/Python）	https://github.com/nuwax-ai/run_code_rmcp

网络与工具

仓库	描述	URL
lanproxy-go-client	网络隧道客户端（供 nuwaclaw 使用）	https://github.com/ffay/lanproxy-go-client

智能体平台前端

中文文档 | 英文文档

贡献指南

1. Fork 该项目
2. 创建功能分支
3. 提交代码更改
4. 创建 Pull Request

社区与支持

加入 Nuwax AI 智能体平台社区，获取技术支持和最新动态！

官方链接

• 官网: https://nuwax.com
• 演示: https://agent.nuwax.com

社区渠道

渠道	描述
GitHub Issues	提交问题
微信社群	添加助手 nuwax-ai
QQ 群	群号: 1041169423
微信公众号	关注“女娲智能体”以获取反馈
抖音/视频号	关注以获取最新视频内容

📱 如需 微信社群、公众号及抖音二维码，请访问 用户手册

许可证

Apache 2.0 许可证 - 详情请参阅 LICENSE。

Nuwax 快速上手指南

Nuwax 是一个用于轻松构建和部署私有化 Agentic AI 解决方案的开源平台。本指南将帮助中国开发者快速完成本地环境的搭建与服务部署。

1. 环境准备

在开始部署前，请确保您的服务器满足以下系统要求并安装了必要的依赖。

系统要求

• 操作系统：
  • Linux: Ubuntu 22.04 LTS 或更高版本（推荐），支持 x86_64 和 ARM64 架构。
  • macOS: 10.15 (Catalina) 及以上（Intel 或 Apple Silicon M1/M2）。
  • 注：Windows 支持即将推出，目前建议使用 WSL2 或 Linux 环境。
• 硬件配置：至少 4 核 CPU，8GB 内存。
• 前置依赖：必须安装 Docker 和 Docker Compose V2。

推荐：一键安装 Docker 环境（国内加速）

针对中国大陆用户，推荐使用社区提供的一键脚本，该脚本自动配置阿里云、腾讯云等国内镜像源加速，并适配多种国产操作系统（如 openEuler, Anolis OS, 麒麟等）。

执行以下命令自动安装 Docker 及 Docker Compose：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

验证安装是否成功：

docker --version
docker compose version
docker run hello-world

若上述命令正常输出且 hello-world 容器运行成功，则环境准备完毕。

macOS 用户提示：推荐使用 OrbStack 替代 Docker Desktop 以获得更佳性能。首次运行可能需要在“系统设置 -> 隐私与安全性”中允许未知开发者。

2. 安装步骤

Nuwax 通过官方 CLI 工具 nuwax-cli 进行管理服务。主要服务分为“主项目服务”（必选）和"Agent Computer 沙箱服务”（可选，用于分布式执行）。以下为主服务的快速部署流程。

部署主服务

请参考官方详细部署文档获取最新的 nuwax-cli 安装包及初始化命令： 安装文档

通常部署流程如下（具体以官网最新指令为准）：

1. 下载并解压 nuwax-cli。
2. 执行初始化配置。
3. 启动服务。

常用服务管理命令

部署完成后，使用以下命令管理服务生命周期：

# 启动服务
./nuwax-cli docker-service start

# 停止服务
./nuwax-cli docker-service stop

# 重启服务
./nuwax-cli docker-service restart

# 查看服务状态
./nuwax-cli docker-service status

3. 基本使用

服务启动成功后，您可以通过浏览器访问前端界面进行 Agent 的构建与管理。

访问入口

• 默认访问地址：通常在本地 http://localhost:PORT 或服务器 IP 对应端口（具体端口请在部署配置中确认）。
• 在线演示：https://agent.nuwax.com

核心功能概览

登录管理后台后，您可以：

1. 模型管理：配置大模型 API Key。
2. 知识库构建：上传文档数据供 Agent 检索。
3. 工作流编排：通过可视化界面组合插件、技能和 MCP 工具。
4. 应用发布：将构建好的 Agent 发布为 Web 应用、H5 或集成到飞书/钉钉/企微等 IM 平台。

升级与备份

应用升级： 自动检测并下载新版本进行部署：

# 检查并更新部署客户端
./nuwax-cli check-update install
# 执行应用服务升级
./nuwax-cli auto-upgrade-deploy run

数据备份： 建议在业务低峰期执行备份（需停止部分服务）：

# 执行一键备份
./nuwax-cli auto-backup run

# 列出所有备份
./nuwax-cli list-backups

# 从指定备份恢复
./nuwax-cli rollback [BACKUP_ID]

---

更多详细架构说明及 Agent Computer 分布式部署指南，请访问 Nuwax 官方文档。