本地怎么跑起来？最容易踩哪些坑？

[XYAIStudio]

问题

第一次 clone 后，推荐的最短启动步骤是什么？哪些环境/配置问题最常见？

[XYAIStudio]

答案（维护者）

最短路径（Node.js ≥ 20.19）：

git clone https://github.com/XYAIStudio/openXYOS.git
cd openXYOS
npm ci
cp .env.example .env   # PowerShell: Copy-Item .env.example .env
npm run dev

然后打开 http://localhost:5174；API 默认 http://localhost:3000/api。

常见坑：

1. 没换密钥： 启动前务必改 .env 里的 JWT_SECRET / COOKIE_SECRET，且不要提交 .env。
2. Node 太旧： 低于 20.19 容易装依赖或跑脚本失败。
3. 指望内置管理员密码： 项目不内置管理员密码。演示数据默认关闭；仅本地评估时可设 SEED_DEMO_DATA=true，并自备至少 12 位密码。
4. 把求助发成 Issue： 安装/用法问题请到 Discussions Q&A，可先看 新手角。
5. 截图里带密钥： 发帖前打码 Cookie、Token、数据库路径。

提交前建议：npm run lint && npm run i18n:check && npm run typecheck；完整门禁用 npm run ci。

更全的安装索引：docs/i18n/README.md