在动手之前，请先确认一个关键前提：系统环境与基础工具链是否已准备就绪。如果这一步没有做到位，后续所有操作都可能失败——你可能会遇到安装路径混乱、权限报错、CLI无法识别、服务无法启动等令人头疼的问题，而根本原因往往在于跳过了关键的初始化环节，或者绑定顺序出错。

QoderWake并非那种开箱即用的纯前端工具，它依赖底层运行时环境，各组件缺一不可。打开终端（Windows 使用 PowerShell，macOS 或 Linux 使用默认 Terminal），依次输入以下三条命令进行验证：node -v → npm -v → qodercli --version。如果其中任何一条命令提示“command not found”，说明对应的组件要么尚未安装，要么未添加到 PATH 环境变量中，需要先补齐。

需特别注意版本门槛：Node.js 必须为 v18.19.0 或更高版本，npm 不低于 9.0.0。低版本会触发 SDK 兼容性中断，导致 Quest Mode 无法加载技能，并且错误日志中不会明确提示版本问题——这种隐蔽的坑最容易消耗时间。如果 node 和 npm 均已就位，唯独缺少 qodercli，直接执行 curl -fsSL https://qoder.com/install | bash 即可，该脚本会自动检测并补全 CLI，无需手动配置 PATH。

完成 QoderWake 核心安装

请根据操作系统选择一种方式，三种方法互斥，切勿混用。

方法一：npm 全局安装（推荐给开发者）
执行 npm install -g @qoder-ai/qoderwake，安装完成后运行 qoderwake --version，确认输出为 0.3.5 或更新版本。

方法二：curl 脚本安装（macOS/Linux 专用）
执行 curl -fsSL https://qoder.com/install-wake | bash，脚本将自动下载二进制文件、设置权限并写入 /usr/local/bin/。安装完成后务必运行 sudo chmod +x /usr/local/bin/qoderwake，否则权限不足会导致服务启动失败——这个细节常被忽略。

方法三：离线包部署（企业内网/无外网环境）
下载 qoderwake-core-v1.3.0.tar.gz（SHA256 校验值：a7f9b1e8c2d5f4a3b6c7e8d9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b），解压到 /opt/qoder/，然后运行 /opt/qoder/core/bin/init-sandbox.sh 初始化沙盒目录结构。

执行五步初始化设置

安装只是热身，下面五项必须按顺序完成，缺一不可。跳过任意一项，QoderWake 将无法连接 GitHub、无法保存记忆、无法执行真实操作。

第一步：授予文件与文件夹访问权限
打开系统设置 → 隐私与安全性 → 文件与文件夹 → 找到 QoderWake → 勾选所有文件夹，额外将下载文件夹和桌面也打开。如果漏掉下载文件夹，本地文档上传会失败，且系统不会给出明确报错提示。

第二步：绑定 GitHub 账户并启用长期记忆
启动 QoderWake → 点击右上角用户图标 → 「登录账户」 → 选择 GitHub（不支持邮箱直登） → 登录后进入「设置 → 记忆管理」 → 打开“跨会话持久化记忆”开关。脱离账户时，所有历史任务上下文都会丢失，一旦丢失无法恢复。

第三步：配置 GitHub Connector
进入「设置 → Connectors」 → 点击「+ 添加」 → 选择 GitHub → 按 OAuth 流程授权 → 确认勾选「Read all repositories」权限。此权限未勾选时，QoderWake 无法读取 PR 描述、Issue 内容和代码变更，所有分析类 Quest 任务都会返回空结果。

第四步：加载默认权限红线策略集
进入「设置 → 权限红线」 → 点击「加载默认策略集」 → 确认「修改主干分支」「删除数据库表」「向客户群发送消息」三项均处于启用状态 → 点击「保存并激活策略」。系统会自动重启 Agent 沙盒环境，整个过程大约 8 秒，界面会短暂灰显。

第五步：执行 Git 仓库分析 Quest 任务闭环验证
在任意项目根目录下打开终端，执行 qwake quest analyze-repo --auto-fix。如果输出中能看到三行标记——「✅ Repo indexed」「✅ Vulnerabilities scanned」「✅ PR draft generated」——则说明所有模块已就绪，可以正式开始工作。