常见问题

先在“活动记录”查看最近一次运行的具体原因，再按下列问题排查。需要完整输出时，从“更多”打开诊断日志。

macOS 提示“Apple 无法验证 AutoMAA.app”

当前公开安装包尚未经过 Apple 公证。确认来源与校验值后，按安装指南使用系统的“仍要打开”流程，不要全局关闭 Gatekeeper。

找不到 maa-cli

在终端执行：

which maa
maa version

把 which maa 输出的完整路径填入“全局设置”。Homebrew 通常为 /opt/homebrew/bin/maa；尚未安装时，先完成MAA 安装。

提示 MaaCore 或资源缺失

首次安装运行 maa install；已有安装可在“全局设置”选择“更新 MAA”。若下载失败，检查上游连接或代理设置，不要先删除仍在使用的 MAA 目录。

无法连接 MaaTools

依次确认：

1. 游戏能手动启动，且已启用 MaaTools；
2. 游戏窗口显示的地址与 AutoMAA 客户端设置一致；
3. 上一个客户端已完全退出，没有其他游戏或 MAA 占用相同端口。

本机默认端口通常是 1717。检查占用者可执行：

lsof -nP -iTCP:1717

使用自定义端口时替换命令中的端口号。不要在不清楚进程身份时强制结束它；先确认并手动关闭冲突客户端，再运行方案。AutoMAA 无法唯一确认端口归属时会停止，避免操作错误实例。

提示游戏连接已离线（GameOffline）

先检查网络和代理是否能正常连接当前服务器，再手动进入游戏主界面。代理节点不可用、维护、登录、更新或异常弹窗都可能让游戏无法继续；仅凭 GameOffline 不能确定具体原因，也不代表本机 MaaTools 端口被占用。

AutoMAA 会为当前账号尝试重启客户端一次，仍未恢复时跳过该客户端的待执行任务，并保留其他客户端的运行机会。前一个账号恢复成功不会耗尽后续账号的重启机会；同一账号的准备与非作战任务共用一次重启机会。恢复后可再次运行原方案，继续当天未完成的步骤，无需清除成功记录。

账号准备失败且报告 ScreencapFailed 时，也会进入受控重启。它表示截图连接出现异常，仅凭该错误无法确定是客户端、MaaTools 还是运行环境导致；反复出现时，请先确认游戏可以手动进入主界面、MaaTools 已启用且窗口可以正常交互。

多账号匹配失败

先按服务器支持范围确认能否自动切换。支持多账号的客户端中：

• 在游戏登录页检查实际显示的账号文字；
• 为每个启用账号填写非空、不同且足够唯一的短片段；
• 不使用所有账号都相同的掩码部分，也不填写密码或完整手机号。

匹配失败会跳过该账号，同客户端其他账号仍可继续。国际服、日服使用当前已登录的单个账号，匹配片段保持为空。

今天的任务被自动跳过

同一方案会跳过当天已成功的步骤。确实需要重跑时，在“全局设置”选择“重置今日完成记录…”。它不会恢复已消耗的理智或道具，详见当日续跑规则。

定时任务没有执行

依次检查：

1. 对应方案已启用定时，星期和时间正确。
2. 到点时用户已登录，系统唤醒，游戏可交互；显示器熄灭不应同时让系统睡眠。
3. 当时没有其他 AutoMAA 工作流正在运行。
4. AutoMAA App 仍位于注册定时时的位置；刚更新过 App 时，先打开一次新版本。
5. “活动记录”和数据目录的 Logs/ 中是否有对应时间的 Runner 错误。

主 App 无需一直打开。睡眠与合盖不能保证准时运行，详细条件见每周定时运行。

应用内更新失败

确认 AutoMAA 位于可写目录，且能访问 GitHub Release。若校验失败或重启后仍是旧版本，可重新检查更新，或从本仓库 Release 手动覆盖安装。不要复用校验失败的安装包；用户配置保存在 App 外的数据目录中。

安装和说明读取是独立操作。若只是“更新内容”无法读取，可以稍后重试说明，或查看发布页。更新范围见更新应用与 MAA。

更新长时间没有结束或被取消

查看当前阶段和已用时间，取消后等待清理完成再重试。识别数据总时限为 3 分钟，完整更新为 15 分钟；提前失败可能是网络或校验错误，详见耗时与取消。

提示 MaaCore 与热更新资源不兼容

先尝试“更新 MAA”。稳定版仍无法加载这批资源时，可明确确认尝试 Beta，或等待稳定版修复。失败的候选不会启用；当前安装本身不可用时，也不会启动游戏。详见更新失败时的处理。

配置被重置或需要恢复备份

查看启动提示和数据目录中的 config-schema-v*.backup.json。先保留备份，再按备份与恢复确认版本兼容性；不要反复覆盖损坏或不兼容的配置。

怎样提交有效的问题报告

从 GitHub Issues选择问题类型，提供：

• “关于 AutoMAA”复制的版本与环境信息；
• 服务器类型、复现步骤、预期行为和实际结果；
• 与出错步骤相邻的少量活动或诊断日志，必要时附截图。

不要上传整个数据目录。检查并移除账号片段、手机号、邮箱、令牌和私人路径，见日志分享。可能涉及漏洞或隐私泄露的问题使用私密安全报告。