QoderWake安装与权限问题需按系统针对性处理：Windows需解除文件锁定并勾选PATH；macOS需在隐私设置中授权全盘访问等权限；Linux需安装libcanberra-gtk3模块。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在初次接触 QoderWake 时遇到安装失败、权限异常、身份初始化中断或配置无法保存等问题，很可能是由于系统环境不匹配、权限未授予或本地沙盒策略限制所致。以下是解决此类问题的具体步骤：
一、Windows 系统安装失败（提示“无法验证发布者”或“已损坏”）
该问题源于 Windows 默认启用的 SmartScreen 筛选器与未签名的邀测版安装包冲突，需手动绕过安全检查但不降低系统防护等级。
1、右键下载完成的 QoderWake_Win_x64_v0.1.0.exe 文件，选择「属性」。
2、在「常规」选项卡底部勾选「解除锁定」，点击「确定」。
3、再次双击运行安装程序；若仍弹出警告，点击「更多信息」→「仍要运行」。
4、安装过程中，在「自定义安装」页务必勾选「添加到系统 PATH」和「创建桌面快捷方式」两项。
二、macOS 安装后无法打开（提示“已损坏，无法打开”）
macOS Gatekeeper 默认阻止非 App Store 或未公证应用的执行，需在系统级授权其运行权限，且该操作仅需一次。
1、前往「系统设置」→「隐私与安全性」→ 滚动至底部「安全性」区域。
2、在「已阻止使用」条目下找到QoderWake，点击右侧「允许」。
3、若未显示该条目，可先尝试在终端执行：xattr -d com.apple.quarantine /Applications/QoderWake.app。
4、重新双击应用程序图标启动。
三、首次启动时卡在“初始化身份”界面无响应
此现象通常由本地沙盒引擎未获取必要系统权限导致，QoderWake 需访问钥匙串、辅助功能及全盘控制权限才能完成员工身份注册流程。
1、打开「系统设置」→「隐私与安全性」→「登录项」，确认QoderWake 已被添加并启用。
2、依次进入「辅助功能」「全盘访问」「屏幕录制」「钥匙串访问」，在每项中点击「+」号，将 QoderWake 应用程序拖入列表。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、重启 QoderWake，首次启动时将自动触发权限请求弹窗，逐项点击「好」。
4、等待约15秒，界面将跳转至「数字员工档案创建」步骤。
四、配置 Skill 后未生效（Quest 模式中技能不识别）
QoderWake 的 Skill 加载依赖于严格路径规范与文件命名约定，任意层级偏差均会导致加载失败，且不报错提示。
1、确认 Skill 存放路径为：~/Library/Application Support/QoderWake/skills/{skillName}/SKILL.md（macOS）或%APPDATA%\QoderWake\skills\{skillName}\SKILL.md（Windows）。
2、检查 {skillName} 文件夹名是否全部为小写字母与短横线组合，例如email-report-v2，禁止出现空格、下划线或大写字母。
3、打开 SKILL.md 文件，首行必须为精确格式的 YAML 前置元数据：---\ntype: skill\nversion: 1.0\nname: email-report-v2\n---。
4、保存文件后，在 QoderWake 主界面按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows） 打开命令面板，输入「Reload Skills」并执行。
五、Linux 系统安装后无法启动（报错：Failed to load module “canberra-gtk-module”）
该错误表明基础音频事件反馈模块缺失，虽不影响核心功能，但会导致身份初始化阶段缺少关键状态提示音，进而被误判为卡死。
1、根据发行版执行对应命令安装依赖：sudo apt install libcanberra-gtk3-module（Ubuntu/Debian）或sudo dnf install libcanberra-gtk3（Fedora/RHEL）。
2、若使用 NixOS，需在 configuration.nix 中的 environment.systemPackages 添加 pkgs.libcanberra_gtk3。
3、执行 systemctl --user restart qoderwake-daemon 重启后台服务进程。
4、重新启动 QoderWake 桌面客户端，观察初始化流程是否继续推进。
