launchagent 是 macos 中由 launchd 管理的用户级服务配置文件，本质是 plist 文件，用于静默、可靠地自动化任务；它不同于“登录项”，不弹窗、支持崩溃自启、可设环境变量与日志路径，且不显示在系统设置中。
macos 的后台服务不是靠“开机自动打开应用”这种表面操作维持的，而是由系统级进程 launchd 统一调度管理。launchagent 是其中面向用户的一类服务单元，它不等于“登录项”，也不依赖图形界面——它是 macos 原生、稳定、可编程的自动化机制。
LaunchAgent 是什么，和“登录项”有啥区别？
LaunchAgent 是一个 plist 配置文件，告诉 launchd：“当用户登录后，请以当前用户身份运行这个程序，并按需重启、记录日志、响应事件”。它和系统设置里的“登录项”根本不是一回事：
- 登录项只是把 App 或脚本丢进启动队列，会弹终端窗口、没日志、崩了不管、无法设定时或监听路径变化
- LaunchAgent 运行在用户会话上下文中，能静默执行、支持崩溃自启（KeepAlive）、可指定工作目录、环境变量、标准输出/错误重定向
- 它不显示在“系统设置 → 登录项”里，也不会出现在 Dock 或菜单栏（除非你写的程序自己加）
配置文件必须写对的几个硬性要点
一个错字、一个斜杠、一个没展开的 ~，都可能导致加载失败或静默失效：
Work Productivity Agent Browser Workflow Helper
下载
帮助用户满足已验证的需求：代理用户在Clawhub上对类似浏览器的工作流程需求强烈，需要实际的帮助来修复Bug、强化系统。
-
Label 必须唯一且规范：推荐用反向域名格式，如
com.yourname.mybackup；不能含空格、特殊符号，也不能和系统或其他服务重复 -
ProgramArguments 是数组，不是字符串：首项是解释器或可执行文件路径（如
/usr/bin/python3），后续每一项是一个独立参数（不能合并成一行命令） -
路径必须绝对，~ 不会被自动替换：写
/Users/alex/Scripts/backup.sh，别写~/Scripts/backup.sh -
布尔值必须用
<true></true>或<false></false>：写yes、1或true都会解析失败 -
环境变量不会继承 shell 的 PATH：如果脚本依赖 brew 安装的工具，需显式设置
EnvironmentVariables字典，比如{"PATH": "/opt/homebrew/bin:/usr/bin:/bin"}
怎么让服务真正生效？三步缺一不可
写完 plist 只是第一步，launchd 不会主动扫描目录。要让它干活，得手动介入：
-
放对位置：用户级服务一律放进
~/Library/LaunchAgents/（注意是波浪号，不是 root 目录） -
加载配置：运行
launchctl load ~/Library/LaunchAgents/com.yourname.service.plist—— 这步注册服务，但不一定立刻运行 -
触发启动：若设置了
RunAtLoad <true></true>，加载后自动启动；否则需手动launchctl start com.yourname.service
排查问题时最该看的三样东西
服务没反应？别猜，直接查：
-
状态码：运行
launchctl list | grep yourlabel，看到数字是0表示正常运行，-1表示未运行（可能没启动或已退出），78表示权限错误 -
日志路径：在 plist 中设置
StandardOutPath和StandardErrorPath，然后用tail -f /path/to/out.log实时观察输出 - 控制台 App：打开“控制台”，在搜索框输入你的 Label 名，筛选出 launchd 记录的加载、启动、崩溃等事件
