Aionclaw启动闪退需按顺序排查：先确认系统环境（Python 3.10+、CUDA 12.1+等）、再隔离Python环境、禁用输入法热键；接着验证GPU配置（禁用CUDA或调低显存池）；然后修复配置文件（备份、重置最小配置、逐项恢复）；最后清理残留进程、端口与IPC文件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当Aionclaw启动后瞬间闪退、无报错窗口或弹出“已停止工作”提示时，说明进程在初始化阶段即被系统强制终止，常见于配置冲突、GPU资源抢占或运行环境缺失等底层问题。
确认基础运行环境是否完备
第一步：检查系统是否满足最低要求。Aionclaw依赖Python 3.10+、CUDA 12.1+（启用GPU加速时）及OpenCL 3.0运行时。Windows用户需确保已安装Visual C++ 2015–2022 Redistributable；macOS用户需验证Xcode Command Line Tools是否激活（执行xcode-select --install可触发安装）。缺少任一组件将导致main.py加载失败，直接退出而不抛出详细错误。
第二步：验证Python环境隔离性。若全局Python中混装了多个AI框架（如PyTorch、TensorFlow），其CUDA版本可能相互覆盖。建议新建虚拟环境：python -m venv aionclaw-env && aionclaw-env\Scripts\activate（Windows）或source aionclaw-env/bin/activate（macOS/Linux），再执行安装命令。
第三步：禁用第三方输入法热键冲突。搜狗、QQ拼音等输入法的全局快捷键（如Ctrl+Shift+Z）会劫持Aionclaw主窗口消息循环，造成UI线程卡死→系统判定无响应→强制结束进程。临时切换为微软拼音或系统默认英文输入法后重试。
排查GPU加速引发的崩溃
方法一：强制禁用GPU推理
在启动前设置环境变量：export AIONCLAW_DISABLE_CUDA=1（macOS/Linux）或set AIONCLAW_DISABLE_CUDA=1（Windows CMD），然后运行aionclaw start。若此时能稳定启动，说明显卡驱动或CUDA Toolkit与当前Aionclaw二进制不兼容——【必须使用NVIDIA官方驱动535.129或更高版本】，旧版驱动对虚幻引擎渲染管线存在内存映射缺陷，会触发0xC0000005访问冲突。
方法二：重置GPU缓冲池参数
编辑~/.aionclaw/config.yaml，定位到graphics:区块，将gpu_vram_pool_mb: 6144改为gpu_vram_pool_mb: 3072。该值超过物理显存70%时，Aionclaw的异步纹理上传线程会因等待超时而主动终止进程，而非降级回CPU模式。
修复配置文件损坏导致的启动失败
第一步：备份原始配置
执行cp ~/.aionclaw/config.yaml ~/.aionclaw/config.yaml.bak（macOS/Linux）或copy %USERPROFILE%\.aionclaw\config.yaml %USERPROFILE%\.aionclaw\config.yaml.bak（Windows）。
第二步：生成最小可用配置
运行aionclaw init --minimal，该命令将清除所有自定义参数，仅保留model_provider:、ui_port:和log_level:三项必要字段。此操作可绕过prefs.xml中因手动编辑引入的XML格式错误（如未闭合标签、非法字符）——这类错误不会被日志捕获，但会使YAML解析器静默失败并退出。
第三步：逐项恢复关键配置
从备份文件中提取agents:、skills:等区块内容，粘贴至新生成的config.yaml对应位置。注意：每个区块末尾必须保留空行，否则YAML解析器会将下一块首行误判为当前块的延续值，引发ParserError: while parsing a block mapping异常并闪退。
清理残留进程与端口占用
① 执行aionclaw kill --force终止所有相关进程（包括后台守护线程与WebUI服务）。
② 检查18789端口是否仍被占用：lsof -i :18789（macOS）或netstat -ano | findstr :18789（Windows）。若返回PID，记录该数字后执行kill -9 [PID]或taskkill /F /PID [PID]。
③ 清理临时IPC文件：rm -rf /tmp/aionclaw-*（macOS/Linux）或删除%TEMP%\aionclaw-*（Windows）。这些文件在异常退出时未被自动清除，下次启动会尝试复用已损坏的共享内存段，直接触发segmentation fault。
④ 重启Aionclaw：aionclaw start。
