MFW 项目配置方法
适用版本与截图
文字按 v5.8.0-beta.3 后续 dev 版本核对。原有截图来自较早版本,布局可能不同;当前导入成功后目录会锁定,页面不再提供旧版的「内嵌副本」状态表和「换目录」操作。
提示
带有 interface.json 的 MaaFramework 项目,可以尝试用 MFW 脚本接入 AUTO-MAS。项目自己的界面可以是 MFAAvalonia、MXU、MFW-PyQt6 或 MaaPiCli;AUTO-MAS 运行时不启动这层界面。M9A 等项目会在导入后自动识别为对应的风味类型。
什么是 MFW 脚本
MaaFramework 生态里的项目都长一个样:一份 interface.json 声明控制器、资源和任务,一个 resource/ 目录放识别用的图片与流程,有的还带一个 Agent(Python 脚本或可执行文件)处理复杂逻辑,外面再套一层界面程序。
AUTO-MAS 的 MFW 脚本直接读 interface.json,使用项目资源与可用的运行环境,按你排好的任务队列运行。它提供通用接入方式;能否顺利运行,还取决于项目的发行包、控制器和 Agent 是否适合当前电脑。
比如 MaaEnd、识宝、M9A、MPA 等,都是 MFW 生态里的项目
MaaFramework 生态项目列表
此图更新于2026年10月20日21:39:36 
由于 M9A 的权威性,因此下面用它走一遍配置流程。页面会随开发调整,文档更新可能不及时,具体请以使用的版本为准
配置项目
下载并解压
- 从项目自己的发布页下载与你的系统架构匹配的发行包(99% 均为 Windows x64) 项目提供 Mirror 酱时,也可以使用其镜像下载。
- 解压到任意文件夹
- 看好用来选进 AUTO-MAS 的那一级目录,应当直接包含
interface.json,而不是再套一层文件夹,一般就在项目安装目录里,未被其他文件夹包裹 以 M9A 为例,在项目目录里看到interface.json就找对了:

注意
通常不需要先打开项目自己的界面;已经打开过也没有问题。
在 AUTO-MAS 中导入
接下来在 MAS 内进行配置,依旧以 M9A 为例:
进入 托管管理,单击 新建托管,选择 MFW脚本。这里选通用 MFW 是为了演示自动识别;直接选择 M9A脚本也对。

选择项目来源:第一次使用这个项目就选 新建一个别的项目;之前导入过,则可以在下面复用。复用时沿用已管理的项目文件,更节约空间,账号和运行设置仍属于新建的托管。

新建项目时,在 项目目录 处单击 选择本地目录,选中刚才那个包含
interface.json的目录。
目录选到含有
interface.json的这一级:
等待导入完成,再检查项目概览和 运行环境 面板。首次准备可能需要几分钟:先扫描项目文件,再复制运行需要的内容。
扫描项目目录:

复制项目文件:

因为导入的是 M9A,托管会自动识别成 M9A 类型;其他未被风味专项认领的项目会继续显示为通用 MFW。页面随后显示的是 MAS 内部的项目目录,运行也从这里读取项目文件。
MAS 的副本与来源分别保存。未启用「跟随来源目录」时,确认导入成功、试跑正常后,可按需保留或移除来源目录;启用跟随或使用源码项目时必须保留来源。不要让两个程序同时控制同一个游戏或模拟器实例。 副本缺失后需要从来源重建时,也仍需来源目录。

控制方式、更新与运行配置
按引导选择控制方式、游戏资源,以及模拟器或 PC 游戏启动方式。项目不支持的控制方式不要选。下面两张图分别是 ADB 和 Win32 的配置示例:
ADB 与模拟器:

Win32 与 PC 游戏:

PS:尝试修改 Unity 类游戏分辨率会在 MAS 启动游戏前临时修改游戏的注册表设置,结束后还原。提供了两种常用分辨率;分辨率较低时,对电脑性能的要求也较低。

项目更新这一步可选择是否自动更新、更新源和更新通道。众所周知的原因,GitHub 更新速度可能较慢;若设为运行前自动更新,就要给下载留足时间。大项目如 MaaFGO,解压和盘点也会花些时间,请耐心等待,有问题及时反馈。

最后看一下运行配置。这里的单次运行时间限制是硬超时:MFW 项目直接运行在 MAS 上,运行异常时 MAS 能感知到;硬超时用于防止任务一直循环。
项目原来的界面里已有配置时,可以勾选导入;每份选中的配置会转成一个账号。也可以不导入,直接创建第一个账号。
导入已有配置:

从空账号开始:

配置第一个账号
已有导入生成的账号时,直接打开该账号编辑;当前没有账号时,先创建第一个账号。两种情况接下来都为所选账号排一个简单任务试跑,确认环境正常后再添加其他任务。之后需要更多账号时,可从托管列表继续添加。
账号名称可以自己定义。注意:同名账号的历史记录会归为一类,建议用“柒音(M9A)”“柒音(MaaEnd)”这类名称区分不同托管。
以 M9A 为例,风味专项会比通用 MFW 多一些适配:在官服资源下填写 账号,运行时会自动加入“切换账号”任务;其他资源不一定支持。密码仅供本地记录,不会传给脚本。

任务可以逐个添加,也可以应用项目资源里的预设模板快速填入。接下来逐项调整任务选项即可,修改会实时保存。

有些项目还会在任务说明中附图:

任务说明里的图片支持点击放大
彩蛋
我们还藏了一些彩蛋,比如识宝导入后的托管名称和 tag~


至于头像和卫星,下次一定.jpg
内嵌副本
MFW 脚本在 AUTO-MAS 管理的副本上运行;你首次选择的目录是导入来源。导入会把运行所需内容放入 AUTO-MAS 的数据目录,项目自己的界面程序通常不在运行副本中。运行和项目更新针对副本,不会修改来源目录。
导入成功后,项目目录显示 MAS 内部的副本路径,目录选择按钮会锁定。要换成别的项目,请新建托管;不要按旧教程在已有托管上换目录。
导入后的基本信息区还提供 跟随来源目录(开发者模式):
- 通常保持关闭,项目通过 项目更新 下载新版本。健康副本不依赖来源目录;需要从来源重建时仍需保留或重新提供来源。
- 开启后,每次运行前会检查并同步来源目录的变动;也可以点击 立即同步。此时不执行项目更新,必须保留来源目录。
- 源码形态的项目始终跟随来源,开关会锁定为开启。它需要保留本地源码及其依赖;不要删除来源目录。
- 同步或准备失败时,查看 运行环境 日志中的原因,修正后使用页面提供的 重试 或 立即同步。它们不是更换项目的入口。
多个托管与旧配置
- 同一项目可创建多个托管,各自有独立的运行视图和账号配置。普通托管中,同一项目、同一更新通道会跟随同一项目版本;开启跟随来源的托管使用自己的来源,不跟随这一共享更新版本。
- 旧 MFW 托管首次使用新版本时会尝试导入原目录。请在升级后检查运行环境并试跑。
- 删除托管会移除其运行视图,来源目录不动。删除前先确认是否需要其中的运行期数据。
控制方式与游戏资源
| 配置项 | 说明 |
|---|---|
| 控制方式 | 从 interface.json 声明的控制器里选:安卓(ADB)还是 PC 窗口(Win32) |
| 游戏资源 | 从 interface.json 声明的资源里选,一般对应服务器(官服 / B 服 / 国际服…)。留空时自动选匹配当前控制方式的第一个 |
| 模拟器 / 模拟器实例 | 控制方式是 ADB 时必填,先在 模拟器管理 里配好模拟器 |
| 游戏包名 | 控制方式是 ADB 时使用。选定资源后 AUTO-MAS 会从项目里自动推断并填好,推不出来就留空 |
| PC 游戏启动方式 | 控制方式是 Win32 时出现:让 MAS 启动游戏(填游戏本体的 exe,结束后由 MAS 关闭)或 使用其他方式启停游戏(由脚本或你自己启停,MAS 只接管已运行的窗口) |
| 启动后再等(秒) | 只在由 MAS 启动游戏时生效:窗口出现后再等这么久才下发第一个任务,给游戏加载画面留时间 |
| 尝试修改 Unity 类游戏分辨率 | 只对 Unity 引擎的游戏有效:MAS 启动游戏前把它临时改成所选尺寸的窗口模式,游戏关闭后恢复原值;游戏已经在运行时不改 |
运行配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 账号单日代理次数上限 | 单个账号每天最多代理几次,0 是不限制 | 0 |
| 代理重试次数限制 | 任务失败后最多重试几次 | 3 |
| 单次运行时间限制(分钟) | 单个账号一次运行最多跑几分钟,超时强制结束 | 120 |
| 每日 / 每周 / 每月完成后跳过 | 选中的任务在当天 / 本周 / 本月成功过一次之后,后续运行自动跳过 | 不选 |
项目更新
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 更新源 | GitHub:无需配置,直接从项目的 GitHub Release 下载;Mirror 酱:需要 CDK,下载快且校验 sha256 | GitHub |
| 更新通道 | 稳定版 / 测试版,以项目实际发布的为准 | 稳定版 |
| Mirror 酱 CDK | 默认带入 MAS 更新设置里填过的那份,可以单独改成本托管专用的 | |
| 自动更新 | 运行前:运行前检查并更新项目;不更新:只手动更新。旧版「运行后」设置会按「运行前」处理;失败时查看更新过程与运行提示 | 运行前 |
未启用跟随来源时,页面上也可以 检查更新 或 立即更新,下方的 更新过程 面板会实时显示下载、覆盖、校验的进度和日志。有可靠更新基线时走增量包,否则下全量包。更新只写副本,来源目录不动;托管正在运行时不能更新,等它跑完。
账号与任务配置速查
之后要增加账号,可在 托管管理 的托管列表内单击 添加账号。AUTO-MAS 会按账号列表顺序执行各自的任务队列。通用 MFW 的账号栏通常只作本地记录;风味专项可能赋予它具体用途,例如 M9A 官服的自动切号。密码仅作本地记录。
任务队列
- 任务列表就是这个项目
interface.json里声明的任务,选中一个加入队列,再拖动调整顺序。 - 项目自带 预设模板 时(比如"日常"),点一下就能批量加入一组任务。
- 每个任务的 任务配置 对应项目自己界面上的那些选项(服务器、关卡、次数……),默认值与项目一致。
- 通用 MFW 按选中的队列运行;风味专项可能在运行前自动补充或调整任务。例如 M9A 会管理启动、切号和关闭游戏,具体以对应项目页面的提示为准。
每次运行发生了什么
- 副本缺失时先尝试从来源重建;跟随来源的托管会检查并同步来源变动。
- 未启用跟随来源时,按 自动更新 的设置检查并更新副本。
- 确认运行环境:MaaFramework 运行时、Agent 环境还在不在、有没有随项目更新而变化。
- 启动模拟器或游戏,连接控制器,加载资源,拉起 Agent。
- 按队列逐个执行任务;失败按 代理重试次数限制 重试。
- 结束后关闭由 MAS 启动的模拟器 / 游戏,写入历史记录并推送通知。
你的项目目录会被改坏吗
不会。运行、更新、日志、这次要跑的配置全部落在副本里,未启用跟随来源时,来源目录只在导入或重建时读取;启用跟随时,运行前还会检查并同步来源变动。副本里 interface.json 和 config/ 每次运行前会归档一份,账号页的 配置恢复 里可以随时预览、恢复。
常见问题
Q:运行环境面板一直红,提示准备失败
A:部分项目首次运行需要下载 MaaFramework 或 Agent 依赖,检查网络或代理后点 重试(同一个按钮,失败时会变成重试)。项目目录选错(里面没有 interface.json)也会停在这里。
Q:任务没跑就结束了,运行页提示"检查未通过"
A:最常见的是所选 游戏资源 不支持当前 控制方式(比如键鼠专用的资源配了安卓控制器),换一个资源;或者控制方式是 ADB 但没选模拟器实例。
Q:第一次运行提示 Agent 进程已退出 / 连接超时
A:先看运行日志和 运行环境 面板,确认项目要求的 Agent 依赖是否已准备好。不同项目的安装方式不同;需要在项目原生界面完成初始化的,请按项目说明操作,再按页面提示同步来源或重新准备运行环境。
Q:导入自来源 v3.10,概览表却显示 v3.16
A:前者是导入时来源目录的版本,后者是副本当前的版本——副本自己更新过了。更新来源目录不会自动改变普通托管的项目版本;日常更新使用 项目更新。开发时需要同步本地改动,再启用 跟随来源目录。
Q:我把原目录删了
A:未启用跟随来源且副本健康时,仍可运行和更新。开启跟随或使用源码项目时,应先恢复来源目录。副本也丢失时,先恢复来源;页面允许选择目录时,再选择重新下载的完整项目包。
Q:想看副本在哪
A:AUTO-MAS 安装目录下的 data/mfw/<托管 ID 前 12 位>/。这里有脚本运行期间产生的数据,请不要手动编辑或删除;副本异常时先查看页面状态与日志,再按页面提示重新准备运行环境;启用跟随来源时可使用 立即同步。
Q:托管正在运行,想看 MaaFramework 的原生日志
A:跑完的一轮,打开 历史记录 中对应记录的详情,在 附件 中下载 MaaFramework 原生日志。不要按旧版的日期/用户名目录查找,当前归档使用独立记录目录。还在跑的日志在这个托管的副本目录里,按下面的步骤找:
在 托管管理(旧版本叫 脚本管理)里打开这个托管任意一个账号的编辑页,单击右上角 打开配置文件夹。

打开的是
data\<托管 ID>\<账号 ID>,这个文件夹可能是空的,不影响。记下地址栏里data后面那一段托管 ID,例如b7c3bb03-52a5-47c1-a8fc-502c0ffa64cd。
回到
data,进入mfw,找名字是托管 ID 去掉横线后前 12 位的文件夹:上例是b7c3bb03接52a5,即b7c3bb0352a5。直接拿带横线的完整 ID 是找不到的。
里面和项目原本的目录一样,日志在
debug里:debug\maafw.log:正在写的 MaaFramework 日志。debug\maafw.bak.<时间>.log:maafw.log写大以后,MaaFramework 会把它改成这个名字,再开一个新的maafw.log。一轮跑得久时,开头那一段在这里。- 项目的 Agent 自己写的日志也在
debug下,例如 M9A 的debug\agent\maafw.log。

发给别人之前
任务选项里填过密码的话,debug\maafw.log 里可能有原文。历史记录中归档的 MaaFramework 日志会按本轮已知凭据脱敏,能等这一轮跑完的话,优先从历史附件下载;分享前仍需检查其他隐私信息。
Q:升级后 MFW 脚本第一次运行多等了十几秒
A:那可能是在从原目录导入副本。未启用跟随来源时,完成并试跑后日常运行一般不再读取原目录;副本缺失后的重建仍需要它。启用跟随时,每轮还会检查来源变动。
给开发者
如果项目需要自己的脚本类型、提示或运行前任务编排,请看 风味专项开发。


