qclaw安装遇“权限不足”需按序排查：一、升级node.js至≥22；二、切换npm全局目录至用户可写路径；三、windows需修复powershell执行策略；四、linux/macos可临时sudo安装；五、可修改默认全局目录权限。
如果您在安装 qclaw 时遇到“权限不足”提示，这通常源于操作系统对全局命令安装路径的写入限制、当前用户缺乏管理员角色，或 npm 全局目录配置不当。以下是多种可立即执行的解决方案：
一、检查并升级 Node.js 版本
QClaw 要求 Node.js ≥22，低版本不仅功能缺失，还会触发隐性权限校验失败，导致安装中途被系统拦截。
1、打开终端（Windows 使用 PowerShell 或 Windows 终端，macOS/Linux 使用 Terminal）。
2、输入命令检查当前版本：node -v。
3、若输出版本低于 v22.0.0，则需升级：使用 nvm install 22 && nvm use 22（推荐），或从官网重新下载安装包覆盖安装。
4、升级完成后重新打开终端，再次运行 node -v 确认生效。
二、切换 npm 全局安装目录（推荐方案）
避免使用 sudo 或管理员权限，通过重定向 npm 全局模块存储位置至用户可写目录，实现安全、持久的权限解耦。
1、创建本地全局目录：mkdir ~/.npm-global。
2、配置 npm 使用该目录：npm config set prefix '~/.npm-global'。
3、将新 bin 路径加入 shell 配置文件：编辑 ~/.bashrc（Linux/macOS Bash）或 ~/.zshrc（macOS Zsh / Linux 默认），追加一行：export PATH=~/.npm-global/bin:$PATH。
4、重载配置：source ~/.bashrc 或 source ~/.zshrc。
5、验证路径生效：npm config get prefix 应返回 /home/用户名/.npm-global 或 /Users/用户名/.npm-global。
三、Windows 系统 PowerShell 执行策略修复
PowerShell 默认阻止未签名脚本执行，而 QClaw 的安装脚本（如 install.ps1）会被拦截，报错信息含 “cannot be loaded because running scripts is disabled”。
1、以管理员身份启动 PowerShell：按 Win+X，选择“Windows 终端（管理员）”。
2、执行策略变更命令：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。
3、关闭并重新打开普通 PowerShell（非管理员），再运行安装命令。
四、Linux/macOS 临时提权安装（仅限验证）
当需快速验证是否为纯权限问题时，可启用临时提权，但不建议长期依赖。
1、确认当前用户属于 sudo 组：groups，输出应含 sudo 或 admin。
2、执行带 sudo 的全局安装：sudo npm install -g qclaw@latest。
3、安装后立即测试命令可用性：qclaw --version。
五、修改安装目标目录权限（精准定位）
若已知 npm 默认全局路径（如 Linux 的 /usr/local/lib/node_modules），且该路径存在所有权锁定，可针对性修复。
1、查询当前 npm 全局路径：npm config get prefix。
2、进入其 lib/node_modules 子目录：cd $(npm config get prefix)/lib/node_modules。
3、将当前用户设为所有者：sudo chown -R $USER:$(id -gn) .。
4、重置目录权限为用户可读写：chmod -R u+rw .。
