MacOS Ventura中个人LaunchAgents故障：停止定时运行，仅登录时执行

问题背景 #

我多年来编写了多个Launch Agent用于自动化简单任务，例如将笔记本电脑中的音乐和照片通过rsync同步到NAS。近期发现它们不再像以往那样每日运行，仅在我登录时才会执行。

示例Launch Agent配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.mwheinz.backup_photos</string>
    <key>Program</key>
      <string>/Users/michaelheinz/bin/backup_photos</string>
    <key>StartInterval</key>
    <integer>86400</integer>
    <key>RunAtLoad</key>
    <true/>
  </dict>
</plist>

使用debug命令时的输出：

~ » sudo launchctl debug gui/501/com.mwheinz.backup_books
Password:
Service configured for next launch.

另外注意到launchd现在要求以gui/501/<label>而非仅<label>的形式引用这些Agent。

解决步骤 #

1. 区分运行上下文：Launch Agent vs Launch Daemon #

Launch Agent是用户上下文服务，仅在用户登录后才会启动，这就是任务只在登录时执行的核心原因。如果需要系统级每日自动运行（无论用户是否登录），需改为Launch Daemon：

• 将plist文件移至/Library/LaunchDaemons/路径（而非用户目录的~/Library/LaunchAgents/）
• 修改plist权限：执行sudo chown root:wheel /Library/LaunchDaemons/com.mwheinz.backup_photos.plist
• 若脚本需要以你的用户身份执行，在plist中添加指定用户的键：

  <key>UserName</key>
  <string>michaelheinz</string>
  

2. 修复用户上下文Agent的定时问题（若需保留） #

如果必须在用户上下文运行，检查以下几点：

• 开启用户账户的自动登录，否则系统重启后未登录时Agent不会启动
• 添加KeepAlive配置，确保Agent意外退出后重启，配合StartInterval保证定时执行：

  <key>KeepAlive</key>
  <dict>
    <key>SuccessfulExit</key>
    <false/>
  </dict>
  

• 检查电脑休眠/节能设置，深度睡眠会暂停StartInterval计时，可按需开启“唤醒以供网络访问”或调整节能策略

3. 适配launchd的命名空间规则 #

从macOS Catalina开始，launchd引入服务命名空间，用户级Agent必须用gui/<UID>/<label>格式引用，这是正常行为：

• 加载Agent：launchctl load gui/501/com.mwheinz.backup_photos.plist
• 查看状态：launchctl list gui/501/com.mwheinz.backup_photos
• 无需修改plist本身，仅命令行操作时使用完整命名空间路径即可

4. 验证配置与日志排查 #

• 用launchctl print gui/501/com.mwheinz.backup_photos查看详细配置，确认StartInterval等参数是否生效
• 查看系统日志定位错误：log show --predicate 'process == "launchd" AND message CONTAINS "com.mwheinz.backup_photos"' --info

内容的提问来源于stack exchange，提问作者Mike Heinz