若QClaw配置后出现网关无法启动、微信扫码失败等问题，应依次检查.env文件格式、执行qclaw config rollback --force回滚、重配微信绑定、确认Node.js≥22.0.0并重装依赖、检查18789端口占用及gateway.yaml认证配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您完成QClaw配置后程序出现异常行为，例如网关无法启动、微信扫码失败、任务无响应或子任务静默中断，则很可能是配置文件错误、环境变量缺失或权限冲突所致。以下是修复此问题的步骤：
一、检查并重置 .env 配置文件
QClaw依赖.env文件加载API密钥、模型名称等核心参数，若格式错误或字段缺失，会导致Gateway初始化失败或技能执行返回空响应。
1、打开QClaw项目根目录，定位到.env文件。
2、确认文件中至少包含以下两行，且等号两侧无空格：
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
MODEL_NAME=gpt-4
3、若存在多余空行、中文字符、注释符号#后紧跟非空格内容，全部删除。
4、保存文件后，在终端执行qclaw gateway restart命令重启网关。
二、执行一键回滚配置
当手动修改配置引发不可逆异常时，QClaw内置的一键回滚功能可将所有用户级配置还原至最近一次成功运行时的状态，避免逐项排查。
1、确保QClaw进程正在运行（可通过qclaw status验证）。
2、在终端输入命令：qclaw config rollback --force。
3、等待终端输出Rollback completed. Gateway will restart automatically.提示。
4、观察左下角弹窗是否重新出现微信配置引导界面。
三、验证微信远程控制配置完整性
QClaw需通过微信扫码绑定个人账号以实现消息收发，若扫码后无响应或弹窗闪退，通常因微信协议适配失败或临时凭证过期。
1、关闭当前微信客户端（包括PC版与手机后台进程）。
2、在QClaw Web UI中点击Settings → WeChat → Re-pair。
3、使用手机微信扫描新生成的二维码，并在弹出页面中点击确认登录（非“取消”或“稍后再说”）。
4、若扫码后5秒内无反应，立即在终端执行：qclaw wechat clear-cache，再重试配对。
四、校验Node.js版本与路径一致性
QClaw要求Node.js版本≥22.0.0，但系统可能仍调用旧版node.exe，尤其在安装过nvm或多版本管理器的环境中，导致配置解析阶段崩溃。
1、在终端运行：node -v，确认输出为v22.x.x或更高。
2、若版本不符，执行：nvm use 22（nvm用户）或重新下载安装Node.js 22 LTS官方安装包。
3、运行：where node（Windows）或which node（macOS/Linux），确保路径指向新版安装目录。
4、删除node_modules与package-lock.json，执行pnpm install重装依赖。
五、检查Gateway端口与认证状态
QClaw Gateway默认监听18789端口，若该端口被占用或未启用认证，会导致WebSocket连接中断、pairing required错误或refusing to bind提示。
1、在终端执行：netstat -ano | findstr :18789（Windows）或lsof -i :18789（macOS/Linux）。
2、若发现占用进程PID，运行：taskkill /PID [PID] /F（Windows）或kill -9 [PID]（macOS/Linux）强制终止。
3、编辑config/gateway.yaml，确认auth.enabled: true且mode: local已设置。
4、保存后执行：qclaw gateway stop && qclaw gateway start。
