安装aionclaw失败需优先查看logs/install.log定位错误阶段：①install-python-deps失败则清理python环境或换清华pip源；②configure-model-channel失败需验证taotoken key、base url及网络访问；③grant-system-permissions失败需启用uac（win）或授权完全磁盘访问/辅助功能（macos）。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
安装 AionClaw 时卡在中间步骤、报错退出、界面闪退或提示“依赖缺失”“权限拒绝”“模型通道未响应”，说明本地环境存在硬性阻断点，必须逐层验证才能继续。这不是网络波动或临时缓存问题，而是安装流程中某个环节的前置条件没满足，系统已主动终止后续动作。
先确认失败发生在哪个阶段
打开安装目录下的 【logs/install.log】 文件（Windows 默认在 C:\Program Files\AionClaw\logs\，macOS 在 ~/Library/Logs/AionClaw/），用记事本或文本编辑器打开，拉到最底部，找到以 [ERROR] 或 Failed at step: 开头的最后一行。常见失败位置有三类：
① step: install-python-deps → Python 环境冲突或 pip 源不可达；
② step: configure-model-channel → TaoToken Key 无效、Base URL 填错或本地无法访问 https://taotoken.net/api；
③ step: grant-system-permissions → Windows 用户账户控制（UAC）被禁用，或 macOS 未授权「辅助功能」「完全磁盘访问」。
针对 step: install-python-deps 失败
方法一：手动清理残留 Python 环境
卸载所有非系统自带的 Python 版本（尤其是通过 Microsoft Store 安装的 Python），保留系统默认 Python（Windows 11 自带，macOS 自带 /usr/bin/python3）。然后删除 AionClaw\venv\ 文件夹（Windows）或 ~/Library/Application Support/AionClaw/venv/（macOS），再双击安装包重试。
方法二：换国内 pip 源强制重装
打开终端（Windows 用 PowerShell，macOS 用 Terminal），执行：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
这一步能绕过原生 pip 源超时问题，尤其对校园网、企业内网用户关键。
注意：不要自行升级 pip 到 24.3 以上版本，AionClaw 内置的 Python 3.11.9 与新版 pip 存在兼容性 bug，会导致 install-python-deps 死循环。
针对 step: configure-model-channel 失败
第一步：验证 TaoToken Key 是否可用
打开浏览器，访问 https://www.php.cn/link/ecd058faafa18f55f81d730b142f8fd3，确认你创建的 Key 状态为 【Active】，且未被误删或过期。Key 名称建议含日期，比如 aionclaw-202610-prod，避免和测试 Key 混淆。
第二步：检查 Base URL 填写是否精确
必须填 【https://taotoken.net/api】，不能多一个斜杠、不能少 https、不能带 utm 参数——哪怕只多一个空格，AionClaw 启动时就会因 HTTP 404 直接中断配置流程。
第三步：绕过本地代理或防火墙干扰
临时关闭 Clash、Surge、企业级上网行为管理软件。如果公司网络限制外连，需联系 IT 部门将 【taotoken.net】 加入白名单，仅放行该域名，其他模型服务商域名无需开通。
针对 step: grant-system-permissions 失败
Windows 用户：
右键「开始」→「运行」→ 输入 msconfig → 「工具」选项卡 → 找到「启用或禁用 UAC」→ 点击「启动」→ 重启电脑。安装时务必右键安装包 → 「以管理员身份运行」，否则权限校验必然失败。
macOS 用户：
前往「系统设置」→「隐私与安全性」→ 拉到最底部「完全磁盘访问」和「辅助功能」→ 点「+」号 → 选择 【AionClaw.app】（不是安装包，是已解压出的主程序）→ 勾选两项。若找不到，先在终端执行：xattr -rd com.apple.quarantine "/Applications/AionClaw.app" 清除隔离属性。
这一步不做，AionClaw 后续无法读取桌面文件、无法操作 Excel、无法自动点击飞书窗口——所有技能都会报「Permission denied」。
终极兜底：跳过图形安装，用命令行静默重装
① 卸载当前残留：Windows 进控制面板卸载，macOS 直接拖 AionClaw.app 到废纸篓；
② 下载最新安装包：访问官网下载页，核对 SHA256 校验值，确保不是缓存旧版；
③ 打开终端 → 进入安装包所在目录 → 执行：AionClaw-Installer.exe --silent --model-url=https://taotoken.net/api --api-key=sk-xxx（Windows）open AionClaw-Installer.dmg && ./AionClaw-Installer.app/Contents/MacOS/AionClaw-Installer --silent --model-url=https://taotoken.net/api --api-key=sk-xxx（macOS）
④ 观察终端输出，出现 Installation completed successfully 即完成。
