MaaAssistantArknights maa-cli 命令行工具实战指南：从安装、任务执行到自定义条件调度

MaaAssistantArknights maa-cli 命令行工具实战指南：从安装、任务执行到自定义条件调度

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

maa-cli 是 MaaAssistantArknights（MAA）项目配套的、使用 Rust 编写的轻量级命令行工具，其核心职责是调用 MaaCore 自动执行《明日方舟》的各类游戏任务，同时提供 MaaCore 与资源的安装更新、日志输出、自定义任务调度等能力。本文以官方 CLI 手册为骨架，完整覆盖安装编译、MaaCore 管理、预定义/自定义任务、日志体系与全套配置文件（自定义任务、连接、资源、CLI 选项），并给出可直接运行的命令示例与多日轮班等实战配置，帮助你从零上手并在日常自动化中落地 maa-cli。

本文基于仓库内的 CLI 用户指南（日文版） 及其同目录下的 使用说明、配置说明、安装与编译、常见问题 编写；仓库还维护了对应的 英文版 与 中文版 手册。当前仓库中src/maa-cli目录对应 maa-cli 的源码模块位置，其余语言与平台绑定由 MaaCore 提供。

maa-cli 能做什么

从 CLI 用户指南 的概述看，maa-cli 的核心能力可以概括为三点：

• 执行任务：运行预定义或自定义任务，例如maa fight刷关卡、maa run <task>运行自定义任务；
• 管理 MaaCore：通过maa install与maa update安装、更新 MaaCore 及其资源文件；
• 自我更新：通过maa self update将 maa-cli 自身更新到新版本。

它的定位非常明确：maa-cli 只是一个命令行前端（CLI），真正的游戏自动化逻辑由 MaaCore 完成。因此，无论使用哪种方式安装 maa-cli，都必须先安装 MaaCore 与对应资源，才能运行任务。

安装与编译

maa-cli 提供了预编译二进制、系统包管理器、cargo源码编译三种安装路径，你可以根据自己的平台与习惯选择。

方式一：预编译二进制（安装脚本）

最简单的安装方式是使用官方安装脚本：

• Linux 与 macOS（bash）

curl -fsSL https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.sh | bash

• Windows（PowerShell）

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.ps1" -OutFile install.ps1; .\install.ps1

安装完成后，可以直接用maa self update命令把 maa-cli 更新到最新版本。如果你的平台不在脚本支持列表内，请改用源码编译。

方式二：系统包管理器

macOS（Homebrew）：官方提供了一个非官方 tap，稳定版与预发布版分别安装：

brew install MaaAssistantArknights/tap/maa-cli # 稳定版 brew install MaaAssistantArknights/tap/maa-cli-beta # 不稳定版 / 预发布版

Arch Linux（AUR）：使用 AUR 助手安装：

paru -S maa-cli # 或 yay -S maa-cli

Nix：稳定版已打包进 nixpkgs，可直接运行；另有 NUR 中的每夜构建版本（使用 Rust beta 工具链，由 GitHub Actions 每日自动构建验证）：

nix run nixpkgs#maa-cli # 稳定版 nix run github:Cryolitia/nur-packages#maa-cli-nightly # 每夜构建

Linux 上的 Homebrew 用户：参考上述 macOS 的安装方式即可。对于其他发行版，请使用安装脚本或源码编译。文档同时欢迎开发者将 maa-cli 提交到更多发行版的官方或用户仓库。

方式三：cargo 源码编译

Rust 开发者可以直接从源码编译：

# 稳定版本 cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --tag stable --locked # 开发版本 cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked

注意：maa-cli 当前的最低支持 Rust 版本（MSRV）为1.88。MSRV 可能随时变更，为获得最佳体验，建议始终使用最新的 Rust 工具链。

编译特性（cargo features）

源码编译时，可以通过--no-default-features关闭默认特性、--features启用指定特性。当前可用的特性如下：

安装 MaaCore 与资源

maa-cli 只提供命令行接口，运行任务必须依赖 MaaCore 与资源文件，不同安装方式下的操作有所区别：

• 预编译二进制或源码编译用户：直接执行maa install，由 maa-cli 负责下载并安装；
• Windows 用户：执行maa install前，需要先以管理员身份在命令提示符或 PowerShell 中安装 VC++ 运行时：

winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force

• Arch Linux 用户：可以用maa install安装官方预编译 MaaCore，也可以用 AUR 安装：

paru -S maa-assistant-arknights # 或 yay -S maa-assistant-arknights

• Nix 用户：Nix 版 maa-cli 强依赖 MaaCore，无需（也不应）手动安装。

需要了解的是，maa install下载的是 MAA 官方预编译的 MaaCore；而包管理器安装的 MaaCore 可能采用不同的编译选项或依赖版本，从而在性能与功能上存在细微差异。

MaaCore 管理与 maa-cli 自身更新

安装完成后，日常维护主要通过以下命令完成：

maa install # 安装 MaaCore 与资源 maa update # 更新 MaaCore 与资源 maa self update # 更新 maa-cli 自身

两点提醒：

1. 命令名差异：通过 Windows 包管理器（winget）安装的 maa-cli，其可执行文件名为maa-cli，上面所有命令中的maa都要替换为maa-cli；
2. 包管理器用户：通过 Homebrew、AUR 等包管理器安装的用户，请使用包管理器更新 maa-cli，maa self update对这类安装方式不生效。

初始化配置

MaaCore 安装完成后，通常无需额外配置即可直接运行任务。不过默认配置未必适合所有用户，可以用交互式命令初始化配置：

maa init

该命令会引导你交互式地设置 MaaCore 相关配置（即后文profiles目录下的连接、资源、OCR、触摸模式等选项）。

运行任务：预定义任务

maa-cli 支持两类任务：预定义任务与自定义任务。常见玩法场景对应如下预定义命令：

这些任务还接受多种参数，可用maa <task> --help查看具体选项。官方文档给出的典型示例是：启动游戏、消耗 3 瓶理性药剂刷 BB-7、然后关闭游戏：

maa startup Official && maa fight BB-7 -m 3 && maa closedown

自定义任务：maa run <task>

MAA 支持的任务种类繁多，maa-cli 不可能为所有任务都提供预定义选项；同时你可能需要像上面那样串联多个任务。为此 maa-cli 提供了自定义任务机制：它可以把不同任务自由组合，精细控制每个任务的参数与执行顺序，还支持条件判断——根据条件决定是否执行某个任务、或使用哪套参数执行，非常适合日常任务自动化。

自定义任务通过配置文件定义（存放位置与写法详见 配置文档）。配置文件创建好后，用maa run <task>运行，其中<task>是自定义任务的文件名（不含扩展名）。

任务摘要与日志

任务摘要

无论预定义还是自定义任务，执行结束后 maa-cli 都会输出任务摘要，包含每个子任务的开始时间、结束时间与耗时。部分任务还会输出结果概要：

• fight：关卡名、运行次数、消耗的理性药剂数、掉落统计；
• infrast：各设施安排的干员，制造站与贸易站还包含产物类型；
• recruit：每次公开招募的标签、星级、状态，以及总招募次数；
• roguelike：探索次数、投资次数。

不需要摘要时，加上--no-summary参数即可关闭。

日志体系

maa-cli 的日志级别从低到高为Error、Warn、Info、Debug、Trace，默认级别为Warn。调整方式有三种：

• 环境变量MAA_LOG：例如MAA_LOG=debug；
• -v：提升一级日志级别；
• -q：降低一级日志级别。

日志默认输出到标准错误流（stderr）。若想落盘，使用--log-file选项，日志会保存到$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log，其中$(maa dir log)是日志目录，可用maa dir log查询；也可用--log-file=path/to/log指定自定义日志路径。

默认情况下，所有日志都会带时间戳与日志级别前缀。该行为由环境变量MAA_LOG_PREFIX控制：

其他实用子命令

除上述命令外，maa-cli 还提供以下子命令：

更完整的命令信息用maa help查看，单个命令的用法用maa help <command>查看。

配置详解

配置目录与文件格式

所有 maa-cli 配置文件都位于特定配置目录中：

• 用maa dir config查询配置目录路径；
• 用环境变量MAA_CONFIG_DIR修改配置目录；
• 下文统一用$MAA_CONFIG_DIR指代该目录。

配置文件支持TOML、YAML、JSON三种格式，只要扩展名正确，三种格式可以任意混用。文档示例统一使用 TOML（.toml扩展名）。

另外，部分任务接受filename参数。使用相对路径时，路径以配置目录下的对应子目录为基准，例如：自定义基建方案文件相对$MAA_CONFIG_DIR/infrast，保全派驻作业文件相对$MAA_CONFIG_DIR/ssscopilot。

自定义任务的配置

每个自定义任务是一个独立文件，必须放在$MAA_CONFIG_DIR/tasks目录下。

基本结构

任务文件包含多个子任务，每个子任务对应一个 MAA 任务：

[[tasks]] name = "启动游戏" # 任务名，可选，默认取任务类型 type = "StartUp" # 任务类型 params = { client_type = "Official", start_game_enabled = true } # 任务参数

具体任务类型与参数见 MAA 集成文档。注意：maa-cli 目前不校验参数名与参数值，写错也不会立刻报错，只有 MaaCore 在运行时检测到错误才会暴露问题。

任务条件（variants）

当你希望在不同条件下用不同参数运行同一任务时，可以为任务定义多个变体（variants），通过condition字段决定使用哪个变体。以下示例按时间段切换基建方案：

[[tasks]] name = "基建换班" type = "Infrast" [tasks.params] mode = 10000 facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] dorm_trust_enabled = true filename = "normal.json" # 自定义基建方案文件名，需放在 $MAA_CONFIG_DIR/infrast # 18:00:00 至次日 04:00:00 使用方案 0，12:00:00 前使用方案 1，之后使用方案 2 [[tasks.variants]] condition = { type = "Time", start = "18:00:00", end = "04:00:00" } # 结束时间小于开始时间时，视为次日时间 params = { plan_index = 0 } [[tasks.variants]] condition = { type = "Time", end = "12:00:00" } # 省略 start，当前时间小于 end 时匹配 params = { plan_index = 1 } [[tasks.variants]] condition = { type = "Time", start = "12:00:00" } # 省略 end，当前时间大于 start 时匹配 params = { plan_index = 2 }

这里的condition决定使用哪个变体，匹配到的变体的params会合并进任务参数。

基建文件的重要提醒：自定义基建方案文件使用相对路径时以$MAA_CONFIG_DIR/infrast为基准；并且基建文件是由 MaaCore 读取的（不是 maa-cli），因此格式必须是 JSON。同时 maa-cli 不会读取基建文件内容，也不会根据其中定义的时间段自动选择子方案，所以你必须在condition中为对应时间段显式指定正确的plan_index参数，才能保证在合适的时间使用正确的基建方案。

除了Time条件，还有DateTime（指定日期时间段）、Weekday（指定星期几）、DayMod（自定义周期中的特定日期）等条件：

[[tasks]] type = "Fight" # 夏活期间刷 SL-8 [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } # 非夏活期间的火、木、六刷 CE-6 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"], timezone = "Official"} params = { stage = "CE-6" } # 其他时间刷 1-7 [[tasks.variants]] params = { stage = "1-7" }

关于时区（timezone）：上面所有时间相关条件都可通过timezone参数指定时区。它的取值有两种：

• 数值：表示相对 UTC 的偏移，例如 UTC+8 写timezone = 8；
• 客户端类型：例如timezone = "Official"，表示按官服对应的服务器时间判定。注意官服时区不是 UTC+8 而是UTC+4，因为游戏内一天的开始是 04:00:00 而不是 00:00:00。

不指定timezone时，默认使用本地时区。

事件条件（OnSideStory）：除上述确定性条件外，还有一个依赖热更新资源的条件OnSideStory。启用后 maa-cli 会加载对应资源，判断当前是否有进行中的活动，有则匹配对应变体。例如上面的夏活刷SL-8条件可以简化为{ type = "OnSideStory", client = "Official" }。这里的client参数决定使用的客户端（不同客户端活动时间不同），官服或 B 服用户可省略。这个条件的价值在于：每次活动更新时，你只需更新要刷的关卡，而不用手动编辑活动举办时间。

条件逻辑组合：可以使用{ type = "And", conditions = [...] }、{ type = "Or", conditions = [...] }、{ type = "Not", condition = ... }进行逻辑运算。

多日轮班实战示例：想排跨多日的基建轮班，可以把DayMod与Time组合使用。例如实现"2 天 6 班"的轮班：

[[tasks]] name = "基建换班 (2天6班)" type = "Infrast" [tasks.params] mode = 10000 facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] dorm_trust_enabled = true filename = "normal.json" # 第 1 班，第 1 天 4:00:00 - 12:00:00 [[tasks.variants]] params = { plan_index = 0 } [tasks.variants.condition] type = "And" conditions = [ # divisor 指定周期，remainder 指定偏移 # 偏移等于 num_days_since_ce % divisor # num_days_since_ce 是以公元 1 年 1 月 1 日（0001-01-01）为第 1 天的累计天数 # 当日偏移可用 `maa remainder <divisor>` 获取 # 例如 2024-1-27 是第 738,912 天，738912 % 2 = 0，当日偏移为 0，匹配此条件 { type = "DayMod", divisor = 2, remainder = 0 }, { type = "Time", start = "04:00:00", end = "12:00:00" }, ] # 第 2 班，第 1 天 12:00:00 - 20:00:00 [[tasks.variants]] params = { plan_index = 1 } [tasks.variants.condition] type = "And" conditions = [ { type = "DayMod", divisor = 2, remainder = 0 }, { type = "Time", start = "12:00:00", end = "20:00:00" }, ] # 第 3 班，第 1 天 20:00:00 - 第 2 天 4:00:00 [[tasks.variants]] params = { plan_index = 2 } [tasks.variants.condition] # 这里必须用 Or：不能直接用 Time { start = "20:00:00", end = "04:00:00" } # 否则第 2 天的 00:00:00 - 04:00:00 无法匹配 # 当然，调整班次时间避免跨日才是更好的选择，这里仅作演示 type = "Or" conditions = [ { type = "And", conditions = [ { type = "DayMod", divisor = 2, remainder = 0 }, { type = "Time", start = "20:00:00" }, ] }, { type = "And", conditions = [ { type = "DayMod", divisor = 2, remainder = 1 }, { type = "Time", end = "04:00:00" }, ] }, ] # 第 4 班，第 2 天 4:00:00 - 12:00:00 [[tasks.variants]] params = { plan_index = 3 } [tasks.variants.condition] type = "And" conditions = [ { type = "DayMod", divisor = 2, remainder = 1 }, { type = "Time", start = "04:00:00", end = "12:00:00" }, ] # 第 5 班，第 2 天 12:00:00 - 20:00:00 [[tasks.variants]] params = { plan_index = 4 } [tasks.variants.condition] type = "And" conditions = [ { type = "DayMod", divisor = 2, remainder = 1 }, { type = "Time", start = "12:00:00", end = "20:00:00" }, ] # 第 6 班，第 2 天 20:00:00 - 第 3 天（新的第 1 天）4:00:00 [[tasks.variants]] params = { plan_index = 5 } [tasks.variants.condition] type = "Or" conditions = [ { type = "And", conditions = [ { type = "DayMod", divisor = 2, remainder = 1 }, { type = "Time", start = "20:00:00" }, ] }, { type = "And", conditions = [ { type = "DayMod", divisor = 2, remainder = 0 }, { type = "Time", end = "04:00:00" }, ] }, ]

匹配策略：first与merge

默认策略下，多个变体同时匹配时采用第一个；未写condition的变体恒匹配，因此常把无条件的变体放在最后充当"默认情况"。

通过strategy字段可以切换匹配策略：

[[tasks]] type = "Fight" strategy = "merge" # 或 "first"（默认） # 周日晚上，把快过期的理性药剂全部用掉 [[tasks.variants]] params = { medicine_expire_days = 2 } [tasks.variants.condition] type = "And" conditions = [ { type = "Time", start = "18:00:00" }, { type = "Weekday", weekdays = ["Sun"] }, ] # 默认刷 1-7 [[tasks.variants]] params = { stage = "1-7" } # 火、木、六刷 CE-6 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } params = { stage = "CE-6" } # 夏活期间刷 SL-8 [[tasks.variants]] params = { stage = "SL-8" } condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }

merge策略下，多个变体匹配时，后匹配变体的参数会合并进先匹配变体的参数；多个变体携带同一参数时，后者覆盖前者。上面的例子与前面刷关示例效果相同，但周日晚会额外使用临期药剂。

没有变体匹配时任务不执行——这可以用于实现"仅在特定条件下执行子任务"：

# 仅在 18:00:00 之后执行信用商店相关操作 [[tasks]] type = "Mall" [[tasks.variants]] condition = { type = "Time", start = "18:00:00" }

用户输入：Input与Select

部分任务希望在运行时输入参数（如关卡名）。将需要输入的参数设置为Input或Select类型即可：

[[tasks]] type = "Fight" # 选择关卡 [[tasks.variants]] condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } [tasks.variants.params.stage] # 可选关卡，至少提供 1 个选项 # 选项可以是纯值，也可以是同时包含值与说明的表格 alternatives = [ "SL-7", # 显示为 "1. SL-7" { value = "SL-8", desc = "轻锰矿" } # 显示为 "2. SL-8 (轻锰矿)" ] default_index = 1 # 默认值下标，从 1 开始；不设置则默认选第一个 description = "a stage to fight in summer event" # 说明，可选 allow_custom = true # 是否允许输入自定义值，默认 false；允许时，非整数输入视为自定义值 # 无需输入 [[tasks.variants]] condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } params = { stage = "CE-6" } # 输入关卡 [[tasks.variants]] [tasks.variants.params.stage] default = "1-7" # 默认关卡，可选（无默认值时输入空值会要求重新输入） description = "a stage to fight" # 说明，可选 # 当输入的关卡是 1-7 时，还需要输入使用的理性药剂数 [tasks.variants.params.medicine] # 参数可设为条件参数，仅在满足条件时要求输入 # conditions 字段是表格：键为同一层级其他参数名，值为期望值 # 这里的条件是 stage 为 1-7；多个条件需全部满足 conditions = { stage = "1-7" } default = 1000 description = "medicine to use"

行为说明：

• Input类型：任务执行时提示输入值；输入空值时若有默认值则使用默认值，否则要求重新输入；
• Select类型：任务执行时提示输入下标或自定义值（若允许）；输入空值则使用默认值；
• --batch选项可以跳过任务执行时的所有输入，直接使用默认值；存在无默认值的输入时会报错。

MaaCore 相关配置（profiles）

MaaCore 相关配置存放在$MAA_CONFIG_DIR/profiles目录，该目录下每个文件都是一份配置。通过-p或--profile选项指定配置文件名；不指定时，尝试加载名为default的配置文件。

当前支持的配置字段完整示例如下：

[connection] preset = "MuMuPro" adb_path = "adb" address = "emulator-5554" config = "CompatMac" [resource] global_resource = "YoStarEN" platform_diff_resource = "iOS" user_resource = true [static_options] cpu_ocr = false gpu_ocr = 1 [instance_options] touch_mode = "MaaTouch" deployment_with_pause = false adb_lite_enabled = false kill_adb_on_exit = false [behavior] auto_reconnect = true

连接配置[connection]

该节用于指定 MaaCore 连接游戏的参数：

[connection] adb_path = "adb" # adb 可执行文件路径，默认 "adb"，表示在 PATH 中查找 address = "emulator-5554" # 连接地址，如 "emulator-5554" 或 "127.0.0.1:5555" config = "General" # 连接配置，一般无需修改

• adb_path：adb 可执行文件路径。可以显式指定路径，也可以把它放进环境变量PATH让 MaaCore 自动查找。大多数模拟器自带 adb，可直接使用无需额外安装；不附带的需要自行安装 adb。
• address：adb 连接地址。模拟器一般用127.0.0.1:[端口号]，常用模拟器端口号见 常见问题。不指定address时，会尝试用adb devices获取已连接的设备：多台设备取第一台，找不到设备则尝试连接emulator-5554。
• config：平台/模拟器相关配置。Linux 默认CompatPOSIXShell，macOS 默认CompatMac，Windows 默认General。更多可选配置可在资源文件夹的config.json文件中查看。

模拟器预设（preset）：对常用模拟器可以直接使用预设：

[connection] preset = "MuMuPro" # 使用 MuMuPro 预设连接配置 adb_path = "/path/to/adb" # 如需覆盖预设的 adb 路径（多数情况不需要） address = "127.0.0.1:7777" # 如需覆盖预设的地址

当前内置两个模拟器预设：MuMuPro与Androws。Androws面向 Windows 上的腾讯应用宝模拟器，会通过注册表自动检测其自带的 adb，默认连接地址为127.0.0.1:5555。欢迎为其他常用模拟器提交预设（issue 或 PR）。

特殊预设：

• PlayCover（macOS）：用于直连 macOS 上通过 PlayCover 原生运行的游戏客户端。此模式无需指定adb_path，address也不是 adb 连接地址，而是 PlayTools 的地址。具体用法见 PlayCover 支持文档。
• Waydroid（Linux）：用于直连 Linux 上通过 Waydroid 原生运行的游戏客户端。此模式仍需指定adb_path。具体用法见 Waydroid 支持文档。

资源配置[resource]

该节指定 MaaCore 加载的资源：

[resource] global_resource = "YoStarEN" # 非简中客户端资源 platform_diff_resource = "iOS" # 非 Android 客户端资源 user_resource = true # 是否加载用户自定义资源

使用非简中游戏客户端时，MaaCore 默认加载的资源是简中版，需要通过global_resource指定非简中资源；使用 iOS 客户端时，需要通过platform_diff_resource指定 iOS 资源。两者均可省略（不需要时可置空）。它们也可能被自动设置：startup任务指定了client_type时，global_resource会自动设为对应客户端资源；使用PlayTools连接时，platform_diff_resource会自动设为iOS。最后，若要加载用户自定义资源，需将user_resource设为true。

静态选项[static_options]

[static_options] cpu_ocr = false # 是否使用 CPU OCR，默认使用 CPU OCR gpu_ocr = 1 # 使用 GPU OCR 时的 GPU ID；该值为空时使用 CPU OCR

实例选项[instance_options]

[instance_options] touch_mode = "ADB" # 触摸模式："ADB"、"MiniTouch"、"MaaTouch"、"MacPlayTools" 或 "MaaFwAdb" deployment_with_pause = false # 部署时是否暂停游戏 adb_lite_enabled = false # 是否使用 adb-lite kill_adb_on_exit = false # 退出时是否强制结束 adb

注意：touch_mode的可选值MacPlayTools与连接方式PlayTools绑定——使用PlayTools连接时，touch_mode会被强制设为MacPlayTools。

CLI 相关配置（cli.toml）

CLI 自身配置位于$MAA_CONFIG_DIR/cli.toml，当前包含的配置项如下：

# GitHub 代理前缀。设置后，GitHub release 的下载地址会被透明改写为经由该代理的地址 # github_proxy = "https://gh-proxy.org/" # MaaCore 安装与更新相关配置 [core] channel = "Stable" # 更新频道："Alpha"、"Beta"、"Stable"，默认 "Stable" test_time = 0 # 测试镜像速度所用时间；0 表示不测试，默认 3 # 查询 MaaCore 最新版本的 API 地址，留空使用默认地址 api_url = "https://api.maa.plus/MaaAssistantArknights/api/version/" # 是否安装 MaaCore 的对应组件。已弃用：单独安装可能因版本不一致产生问题，此选项可能在未来版本移除 [core.components] library = true # 是否安装 MaaCore 库，默认 true resource = true # 是否安装 MaaCore 资源，默认 true # CLI 更新相关配置 [cli] channel = "Stable" # 更新频道："Alpha"、"Beta"、"Stable"，默认 "Stable" # 查询 maa-cli 最新版本的 API 地址，留空使用默认地址 api_url = "https://github.com/MaaAssistantArknights/maa-cli/raw/version/" # 预编译二进制下载地址，留空使用默认地址 download_url = "https://github.com/MaaAssistantArknights/maa-cli/releases/download/" # 是否安装 maa-cli 的对应组件 [cli.components] binary = true # 是否安装 maa-cli 二进制，默认 true # 资源热更新相关配置 [resource] auto_update = true # 每次运行任务前是否自动更新资源，默认 false warn_on_update_failure = true # 更新失败时是直接报错还是仅告警 backend = "libgit2" # 资源热更新后端："git" 或 "libgit2"，默认 "git" # 资源热更新的远程仓库配置 [resource.remote] branch = "main" # 远程仓库分支，留空使用远程仓库默认分支 # 远程资源仓库 URL，留空使用默认 URL # GitHub 仓库可用 HTTPS 与 SSH 两种协议访问；HTTPS 无需额外配置，推荐使用 url = "https://github.com/MaaAssistantArknights/MaaResource.git" # url = "git@github.com:MaaAssistantArknights/MaaResource.git" # 使用 SSH 协议时需提供 SSH 密钥，最简单的方式是指定密钥路径 ssh_key = "~/.ssh/id_ed25519" # SSH 密钥路径 # maa 的默认密钥未加密。若密钥有口令保护，需要提供解密口令： # 注意：只有使用 libgit2 后端时，maa 才会把口令传给 libgit2 # 使用 git 后端时，由 git 自行提示输入口令 # 使用 git 后端且密钥有口令保护时，请用 ssh-agent 管理密钥 passphrase = "password" # SSH 密钥口令 # 但把明文口令写进配置文件不安全，有几种替代方案： # 1. 将 passphrase 设为 true，maa-cli 每次询问口令（安全但繁琐，batch 模式不可用） # passphrase = true # 2. 将 passphrase 设为环境变量名，maa-cli 从环境变量读取口令 # 比明文安全，但环境变量可能被任意程序访问，仍有一定风险 # passphrase = { env = "MAA_SSH_PASSPHRASE" } # 3. 将 passphrase 设为一条命令，maa-cli 执行该命令获取口令 # 若用密码管理器管理口令，这是最安全方便的方式 # passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] } # 4. 用 ssh-agent 管理密钥（推荐） # ssh-agent 把密钥保存在内存中，无需每次输入口令 # 需确保 ssh-agent 已启动、密钥已添加、SSH_AUTH_SOCK 环境变量已设置 # use_ssh_agent = true # 设为 true 时忽略 ssh_key 与 passphrase 字段 # 活动信息与热更新资源文件的下载配置 [hot_update] # 查询活动信息与下载热更新资源文件的 API 地址，留空使用默认地址 api_url = "https://api.maa.plus/MaaAssistantArknights/api" # 检查间隔（秒），超过该时间会重新下载文件；0 表示禁用缓存，默认 600 check_interval = 600

配置注意事项：

1. MaaCore 更新频道中的Alpha仅 Windows 可用；
2. 部分默认链接指向 GitHub，国内访问可能存在问题。可以通过设置api_url、download_url使用镜像，也可以设置顶层github_proxy让 GitHub release 下载经由代理加速；
3. 即使启用了资源热更新，仍需安装 MaaCore 资源：热更新只包含部分可更新的资源文件，基础资源文件必须随 MaaCore 一起安装；
4. 资源热更新通过 Git 拉取远程仓库实现，backend设为git时需要系统可用git命令行工具；
5. 通过 SSH 协议拉取远程仓库时，需设置ssh_key字段指向 SSH 私钥路径；
6. SSH 私钥受口令保护时，需要提供解密口令或用 ssh-agent 管理密钥；
7. 远程仓库的url配置目前仅在资源首次安装时生效。想更换远程仓库地址，需用git命令行手动修改，或删除对应仓库（仓库位置可用maa dir hot-update查询）。

配置参考与 JSON Schema

官方提供了 配置示例 供参考。此外，maa-cli 提供 JSON Schema 文件，可用于校验配置文件或在编辑器中获得自动补全：

• 自定义任务文件：task.schema.json
• MaaCore 配置：asst.schema.json
• CLI 配置：cli.schema.json

常见问题：macOS 下改用 XDG 风格配置目录

由于 Rust 的 Directories 库在 macOS 上默认采用 Apple 风格目录，maa-cli 在 macOS 上默认也会使用 Apple 风格配置目录。但 XDG 风格目录对命令行程序更合适。想要 XDG 风格目录，有两种方式：

1. 设置环境变量：export XDG_CONFIG_HOME="$HOME/.config"，maa-cli 会改用 XDG 风格配置目录；
2. 创建符号链接（不想设置环境变量时）：

mkdir -p "$HOME/.config/maa" ln -s "$HOME/.config/maa" "$(maa dir config)"

小结

从 CLI 用户指南 出发，可以看到 maa-cli 是围绕"MaaCore 的调用与管理"构建的完整命令行生态：预定义命令覆盖启动/关闭、刷关、自动作业、保全派驻、悖论模拟、集成战略与生息演算等主流玩法；自定义任务通过 variants + condition 实现了按时间、星期、周期甚至游戏活动动态调度的能力；profiles 与 cli.toml 则分别管理 MaaCore 运行参数与 CLI 自身的安装更新行为。建议新手先maa install完成环境准备，再以maa fight 1-7验证链路，随后逐步尝试自定义任务与条件调度，即可将日常长草流程完全自动化。更多任务类型与参数细节，可查阅 MAA 集成文档。

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights