常见问题（FAQ）

安装与环境

WopalSpace 支持哪些操作系统？

  • macOS 10.15+（Intel / Apple Silicon）
  • Linux：Ubuntu 20.04+ / Debian 11+ / Fedora 36+ / Arch
  • Windows 10+（推荐 WSL2）

安装需要 Node.js 吗？

不需要。CLI 与 ellamaka 引擎都是自包含二进制（内置运行时）。唯一硬依赖是 Git 2.30+（本体以 Git worktree 管理）。

安装后提示 command not found？

PATH 未生效。重新加载 shell 配置，并确认 bin 目录已在 PATH 中：

source ~/.zshrc   # 或 ~/.bashrc
echo $PATH | grep wopal

macOS / Linux 的 bin 目录默认是 ~/.wopal/bin；Windows 是 %LOCALAPPDATA%\Programs\Wopal\bin。

installer 报 Permission denied？

多为目录或 PATH 写入权限问题。确认你对 home 目录有写权限；必要时手动把 bin 目录加入 PATH 后重跑 installer。

空间管理

wopal setup 和 wopal space init 有什么区别？

  • wopal setup 是首次编排向导：一次性准备好 WOPAL_HOME、本体、引擎，并创建第一个空间。
  • wopal space init 用于创建更多空间（可指定 --type）。

一个机器可以有多个空间吗？

可以。每个项目目录都可初始化为独立空间，wopal space list 查看全部，wopal space init 创建新的。空间之间完全隔离。

空间数据存在哪？

空间在你指定的路径（默认 ~/WopalSpace）。全局状态在 $WOPAL_HOME（默认 ~/.wopal）。wopal setup --remove 只删全局状态，不影响你的空间文件。

本体与分发

common / coding / content / finance 是什么？

它们是本体的类型分支。common 映射 main（通用基线）；coding / content / finance 在 main 之上叠加特定场景能力。创建空间时用 wopal space init --type <type> 选择。

可以从别人的仓库安装本体吗？

可以，而且这是推荐做法：

wopal ontology install <github-url>

GitHub 就是 registry，没有中心化权威。你也可以 fork 后自主演化，再让别人 install 你的 fork。

本体和我的私人记忆会一起被分发走吗？

不会。个人信息（记忆、STRUCTURE.md、REGULATIONS.md）留在空间运行态；只有本体能力（agents / skills / commands / rules / plugins）可被版本化迁移与分发。

AI 与凭证

怎么配置 AI API Key？

不是环境变量，也不是 settings.jsonc：

wopal ellamaka auth login

或在首次 wopal setup 的 Configure 阶段填写。

Agent（Wopal）在哪里运行？

通过 wopal start 启动 ellamaka 引擎，在浏览器打开 Web Workbench 与 Wopal 对话。slash 命令如 /init、/wopal:evolve、/wopal:memo 都在 Workbench 内使用。

升级与卸载

如何升级？

wopal update              # 升级 wopal 命令
wopal ellamaka install    # 升级引擎
wopal ontology update     # 同步本体能力

如何卸载？

wopal setup --remove

只清理 WOPAL_HOME，保留所有空间与项目。

排错

通用排查顺序

  1. wopal doctor —— 只读诊断
  2. wopal status —— 引擎安装 / 运行状态
  3. wopal space status / wopal ontology status —— 空间 / 本体同步状态
  4. 查看日志：$WOPAL_HOME/logs/ellamaka-serve.log

报告问题需要什么？

运行 wopal status 与 wopal doctor 的输出，加上复现步骤。WopalSpace 的 issue / 讨论区链接见官网。