QClaw服务无法启动或微信扫码无响应，需依次检查微信授权与邀请码有效性、macOS辅助功能权限、M芯片Rosetta兼容性、网络代理/防火墙拦截及本地配置文件完整性与路径权限。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您尝试部署 QClaw，但服务无法启动或微信扫码后无响应，则可能是由于环境依赖缺失、微信授权链路中断或本地系统权限限制所致。以下是解决此问题的步骤：
一、检查微信授权与邀请码有效性
QClaw 启动依赖有效邀请码及微信扫码绑定流程，若未完成授权，进程将静默退出且不报错。该环节为前置强校验，失败会导致后续所有模块不加载。
1、确认邀请码是否已过期或被使用超过上限次数。每个邀请码仅支持单设备首次激活。
2、打开微信，进入「我 → 设置 → 隐私 → 授权管理」，查找 QClaw 条目，点击进入并选择「重新授权」。
3、在 QClaw 安装界面点击「关联微信」后，必须在 5秒内完成手机端扫码并点击“确认登录”，超时将导致 token 失效并返回空白页。
二、验证 macOS 系统权限与辅助功能授权
QClaw 在苹果设备上需调用 Accessibility API 实现桌面操作，若未授予权限，技能执行将始终返回空响应或卡在“正在执行”状态。
1、前往「系统设置 → 隐私与安全性 → 辅助功能」，在应用列表中查找 QClaw。
2、如未出现，手动点击左下角「+」号，通过访达定位到应用程序文件夹中的 QClaw.app 并添加。
3、确保勾选状态为开启，且 重启 QClaw 应用后再测试技能，否则权限不会生效。
三、排查 M 芯片设备 Rosetta 兼容性问题
部分早期发布的 QClaw 二进制包未原生适配 Apple Silicon 架构，强制运行于 Rosetta 2 环境下可能引发 Ollama 连接失败或 TTS 模块崩溃。
1、右键 QClaw.app → 「显示简介」，检查「使用 Rosetta 打开」选项是否被勾选。
2、若已勾选，取消该选项并关闭窗口；若未勾选但运行异常，反向勾选并重启应用。
3、验证当前架构：在终端执行 arch 命令，输出应为 arm64；若为 i386，则说明系统正强制降级运行。
四、诊断网络代理与企业防火墙拦截
QClaw 初始化阶段需连接腾讯云鉴权服务器（qclaw-auth.tencentcloudapi.com）及微信开放平台接口，若本地启用代理或处于企业网络环境，可能导致握手失败且日志无明确提示。
1、临时关闭系统代理：「系统设置 → 网络 → 高级 → 代理」，取消所有代理协议勾选。
2、在终端执行：curl -v https://qclaw-auth.tencentcloudapi.com/health，观察是否返回 HTTP 200。
3、若请求超时或拒绝连接，需联系网络管理员放行 *.tencentcloudapi.com 域名及 443 端口，不可仅开放 IP 段。
五、检查本地配置文件完整性与路径权限
QClaw 启动时自动读取 ~/Library/Application Support/QClaw/config.json，若该文件损坏、权限错误或被其他进程锁定，会导致初始化中断并回退至初始设置页。
1、在终端执行：ls -l ~/Library/Application\ Support/QClaw/，确认 config.json 存在且属主为当前用户。
2、若显示 permission denied，执行：chmod 755 ~/Library/Application\ Support/QClaw 及 chmod 644 ~/Library/Application\ Support/QClaw/config.json。
3、若 config.json 内容为空或含非法 JSON 字符，删除该文件后重启 QClaw，触发自动重建，勿手动编辑原始配置。
