安装 WopalSpace

本文档详细介绍如何安装 WopalSpace，以及在安装后如何进入第一个空间。

系统要求

在安装之前，请确认你的系统满足以下最低要求：

操作系统支持

官方安装方式

当前稳定版以官网 installer 为准：

curl -fsSL https://wopal.cn/install.sh | bash

Windows PowerShell：

irm https://wopal.cn/install.ps1 | iex

安装脚本会执行以下操作：

1. 检测操作系统和 CPU 架构
2. 下载对应平台的二进制文件
3. 安装到 ~/.wopal/bin/ 目录
4. 自动配置 PATH 环境变量
5. 验证安装是否成功

如果你担心安全性，可以先查看脚本内容：

curl -fsSL https://wopal.cn/install.sh | less

安装完成后，下一步是运行：

wopal setup

它会准备 WOPAL_HOME、基础能力层与首个 space。之后可通过 wopal ellamaka install / update / serve 管理 engine。

平台特定说明

macOS

macOS 用户可能需要在系统设置中允许运行未签名的应用：

1. 打开 系统偏好设置 → 安全性与隐私
2. 在 通用 标签页中，点击 仍然允许

或者使用命令行解除隔离属性：

xattr -d com.apple.quarantine $(which wopal)

Windows

Windows 用户推荐使用 WSL2（Windows Subsystem for Linux）：

# 在 PowerShell (管理员) 中安装 WSL
wsl --install

# 重启后，在 WSL 中安装 WopalSpace
curl -fsSL https://wopal.cn/install.sh | bash

如果选择在原生 Windows 上运行，请确保：

• 已安装 Git for Windows
• 使用 PowerShell 7+ 或 Windows Terminal
• 已启用开发者模式

Linux

大部分 Linux 发行版可以直接使用安装脚本。如果遇到问题：

# Ubuntu/Debian：安装必要依赖
sudo apt-get update
sudo apt-get install -y curl git nodejs npm

# Fedora
sudo dnf install -y curl git nodejs npm

# Arch Linux
sudo pacman -S curl git nodejs npm

配置

安装完成后，建议进行基础配置：

首次初始化

wopal setup

wopal setup 会准备 WOPAL_HOME、ontology source、基础能力层与首个 space。完成后，再通过 wopal ellamaka serve 启动当前 space，并在会话中运行 /init 完成首次结构校准。

环境变量

可以通过环境变量覆盖默认配置：

# 设置 AI API Key
export WOPAL_API_KEY="sk-xxx"

# 设置默认空间目录
export WOPAL_SPACES_DIR="/custom/path/spaces"

# 设置日志级别
export WOPAL_LOG_LEVEL="debug"

建议将环境变量添加到 shell 配置文件中：

# ~/.bashrc 或 ~/.zshrc
export WOPAL_API_KEY="sk-xxx"
export WOPAL_SPACES_DIR="$HOME/.wopal/spaces"

验证安装

安装完成后，运行以下命令进行全面检查：

# 检查 CLI 版本
wopal --version

# 准备首个空间
wopal setup

升级与卸载

升级到最新版本

# 重新运行 installer
curl -fsSL https://wopal.cn/install.sh | bash

# 更新 ellamaka
wopal ellamaka update

卸载

# 清理配置和数据（可选）
rm -rf ~/.wopal

常见问题

Q: 安装脚本报错 “Permission denied”

A: 尝试使用 sudo 或修改安装目录权限：

curl -fsSL https://wopal.cn/install.sh | bash

Q: 执行 wopal 提示 “command not found”

A: PATH 配置可能未生效，尝试：

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 检查 PATH 是否包含 wopal
echo $PATH | grep wopal

Q: Node.js 版本过低怎么办？

A: 使用 nvm 升级 Node.js：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装并使用 Node.js 20
nvm install 20
nvm use 20