macOS LaunchAgent 开机自启服务配置实战：以 OpenClaw 为例

title: “macOS LaunchAgent 开机自启服务配置实战以 OpenClaw 为例”tags:macOSLaunchAgent开机自启launchdOpenClawcategories:macOSdescription: “从原理到实战详解 macOS LaunchAgent 的配置方法以 OpenClaw Gateway 和 CLIProxyAPI 为例手把手教你实现服务的开机自启和崩溃自动重启。”导读macOS 上想让自己的服务开机自启很多人第一反应是往系统设置 → 登录项里塞结果弹个终端窗口出来丑且不靠谱。正确的做法是用 macOS 原生的 launchd 机制通过 LaunchAgent plist 文件来管理。这篇文章我把自己折腾 LaunchAgent 的经验整理出来用 OpenClaw 和 CLIProxyAPI 两个真实案例走一遍完整流程。一、先搞清楚 launchd 是什么launchd 是 macOS 的服务管理器系统启动时由内核第一个拉起来PID 1负责管理所有系统服务和用户服务。你可以把它理解为 macOS 版的 systemd。launchd 通过读取.plist配置文件来决定启动什么、什么时候启动、崩了要不要拉起来。LaunchAgent vs LaunchDaemon这两个东西经常搞混其实区别很简单LaunchAgentLaunchDaemon谁启动用户登录后启动系统启动时不需要登录权限当前用户权限root 权限能弹 GUI 吗能不能配置目录~/Library/LaunchAgents/Library/LaunchDaemons日常开发中我们要自启的服务代理、数据库、开发工具后台服务等99% 用 LaunchAgent 就够了。plist 文件放哪~/Library/LaunchAgents/ ← 用户级登录后启动最常用 /Library/LaunchAgents/ ← 系统级所有用户登录后启动需要 sudo /Library/LaunchDaemons/ ← 系统级开机就启动需要 sudo root /System/Library/LaunchAgents/ ← 苹果系统自带别动 /System/Library/LaunchDaemons/ ← 苹果系统自带别动我们写自己的服务放到~/Library/LaunchAgents/就行不需要 sudo不需要 root。二、plist 配置文件详解一个典型的 LaunchAgent plist 文件长这样?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeyLabel/keystringcom.example.myservice/stringkeyProgramArguments/keyarraystring/usr/local/bin/myservice/stringstring--config/stringstring/path/to/config.yaml/string/arraykeyRunAtLoad/keytrue/keyKeepAlive/keytrue/keyStandardOutPath/keystring/tmp/myservice.log/stringkeyStandardErrorPath/keystring/tmp/myservice.err.log/string/dict/plist关键配置项说明配置项作用常用值Label服务唯一标识必须和文件名一致反域名格式如com.example.myserviceProgramArguments启动命令和参数数组的第一个是可执行文件路径数组形式RunAtLoad加载时是否立即启动true/falseKeepAlive进程退出后是否自动重启true/false/ 字典条件StandardOutPath标准输出日志路径绝对路径StandardErrorPath错误输出日志路径绝对路径WorkingDirectory工作目录绝对路径EnvironmentVariables环境变量字典形式StartInterval定时执行间隔秒整数WatchPaths监控路径文件变化时触发数组ThrottleInterval重启最小间隔秒防频繁重启整数默认 10KeepAlive 的几种写法KeepAlive可以是简单的true也可以是条件式的!-- 无条件自动重启 --keyKeepAlive/keytrue/!-- 仅在退出码非 0 时重启 --keyKeepAlive/keydictkeySuccessfulExit/keyfalse//dict!-- 网络可用时才保持运行 --keyKeepAlive/keydictkeyNetworkState/keytrue//dict我的建议大多数场景直接设true就完事了除非你明确知道进程正常退出后不该重启。三、实战案例一OpenClaw Gateway 自启OpenClaw 是一个开源的个人 AI 助手可以在微信、Telegram、Discord 等平台上运行。它需要一个 Gateway 服务常驻后台。好消息是OpenClaw 安装时自带了 daemon 管理一条命令就能搞定openclaw onboard --install-daemon执行后它会自动在~/Library/LaunchAgents/下生成一个ai.openclaw.gateway.plist文件。我们来拆解一下这个真实的 plist 配置?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeyLabel/keystringai.openclaw.gateway/stringkeyComment/keystringOpenClaw Gateway (v2026.4.9)/stringkeyRunAtLoad/keytrue/keyKeepAlive/keytrue/keyThrottleInterval/keyinteger1/integerkeyProgramArguments/keyarraystring/opt/homebrew/opt/node/bin/node/stringstring/opt/homebrew/lib/node_modules/openclaw/dist/entry.js/stringstringgateway/stringstring--port/stringstring18789/string/arraykeyStandardOutPath/keystring/Users/aiksyuan/.openclaw/logs/gateway.log/stringkeyStandardErrorPath/keystring/Users/aiksyuan/.openclaw/logs/gateway.err.log/stringkeyEnvironmentVariables/keydictkeyHOME/keystring/Users/aiksyuan/stringkeyPATH/keystring/opt/homebrew/opt/node/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin/stringkeyOPENCLAW_GATEWAY_PORT/keystring18789/string/dict/dict/plist这个配置有几个值得注意的点ProgramArguments用了 node 的完整路径/opt/homebrew/opt/node/bin/node而不是直接写node。这是因为 launchd 不会加载你的 shell 环境PATH 变量可能不包含 node。EnvironmentVariables里手动设了 PATH 和 HOME确保进程能找到需要的命令。ThrottleInterval设为 1允许崩溃后快速重启默认是 10 秒。这是 OpenClaw 自动生成的配置不需要手动写。如果你也是 OpenClaw 用户直接跑openclaw onboard --install-daemon就行了。四、实战案例二CLIProxyAPI 自启手动配置CLIProxyAPI 是一个 API 协议转换代理用于让 Codex CLI 等工具接入智谱 GLM 模型。它没有自带的 daemon 管理功能需要我们自己写 plist。4.1 创建 plist 文件vim~/Library/LaunchAgents/com.cli-proxy-api.plist写入以下内容记得把aiksyuan换成你自己的用户名?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeyLabel/keystringcom.cli-proxy-api/stringkeyProgramArguments/keyarraystring/Users/aiksyuan/.codex/cli-proxy-api/stringstring-config/stringstring/Users/aiksyuan/.codex/cliproxy-config.yaml/string/arraykeyRunAtLoad/keytrue/keyKeepAlive/keytrue/keyStandardOutPath/keystring/Users/aiksyuan/.codex/logs/cli-proxy-api.stdout.log/stringkeyStandardErrorPath/keystring/Users/aiksyuan/.codex/logs/cli-proxy-api.stderr.log/string/dict/plist这里几个要点Label是com.cli-proxy-api文件名也是com.cli-proxy-api.plist保持一致。KeepAlive设true代理崩了会自动重启不会出现 Codex CLI 连不上的情况。日志写到~/.codex/logs/方便排查问题。4.2 加载服务# 加载并立即启动launchctl bootstrap gui/$(id-u)~/Library/LaunchAgents/com.cli-proxy-api.plist⚠️ 如果你之前用的是旧版launchctl load命令macOS 10.10 之后推荐用launchctl bootstrap替代。两者的区别bootstrap是基于 domain 的操作语义更清晰。4.3 验证服务# 检查服务状态launchctl print gui/$(id-u)/com.cli-proxy-api# 测试代理是否正常响应curl-s-HAuthorization: Bearer sk-glm-proxyhttp://127.0.0.1:8080/v1/models正常的话应该返回模型列表。五、launchctl 常用命令速查这些命令我日常用得很多建议收藏# 加载服务立即启动 注册开机自启launchctl bootstrap gui/$(id-u)~/Library/LaunchAgents/com.example.plist# 卸载服务停止 取消开机自启launchctl bootout gui/$(id-u)/com.example# 查看服务状态launchctl print gui/$(id-u)/com.example# 列出当前用户所有已加载的服务launchctl list# 列出并过滤特定服务launchctl list|grepopenclaw# 手动启动服务需要已加载launchctl kickstart gui/$(id-u)/com.example# 停止服务不卸载崩溃后会自动重启如果 KeepAlivetruelaunchctlkillSIGTERM gui/$(id-u)/com.examplegui/$(id -u)是当前用户的 launchd domain。$(id -u)获取你的用户 UID通常是 501。你也可以直接写gui/501。六、我踩过的几个坑坑 1launchd 环境里没有你的 PATH这是最多人踩的坑。launchd 不会读.zshrc、.bash_profile这些文件所以你在 shell 里能跑的命令放到 plist 里可能找不到。解决方案在ProgramArguments里写可执行文件的绝对路径或者通过EnvironmentVariables手动设 PATH。keyEnvironmentVariables/keydictkeyPATH/keystring/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin/string/dict坑 2plist 文件权限不对plist 文件必须是644所有者可读写其他人只读且所有者必须是当前用户。如果权限不对launchd 会拒绝加载。chmod644~/Library/LaunchAgents/com.example.plist坑 3改了 plist 不生效修改 plist 文件后必须先 bootout 再 bootstrap否则 launchd 还是用旧的配置launchctl bootout gui/$(id-u)/com.example launchctl bootstrap gui/$(id-u)~/Library/LaunchAgents/com.example.plist坑 4日志目录不存在如果StandardOutPath或StandardErrorPath指向的目录不存在launchd 会静默失败服务起不来但也不报错。确保日志目录已经创建好mkdir-p~/.codex/logsmkdir-p~/.openclaw/logs坑 5Label 和文件名不一致Label的值不要求和文件名完全一致但这是约定俗成的最佳实践。如果 Label 冲突两个 plist 用了同一个 Label后加载的会覆盖前一个。七、用 Shell 脚本包装一下更省心如果你的服务启动前需要一些环境准备工作比如检查端口、创建目录可以把启动逻辑包在 Shell 脚本里然后在 plist 中调用脚本#!/bin/bash# ~/scripts/start-cli-proxy.shLOG_DIR$HOME/.codex/logsmkdir-p$LOG_DIRiflsof-i:8080/dev/null21;thenechoPort 8080 already in use, skippingexit0fiexec$HOME/.codex/cli-proxy-api-config$HOME/.codex/cliproxy-config.yamlplist 中改成keyProgramArguments/keyarraystring/bin/bash/stringstring/Users/aiksyuan/scripts/start-cli-proxy.sh/string/array⚠️ 脚本必须有执行权限chmod x ~/scripts/start-cli-proxy.sh八、定时任务也能用 LaunchAgent除了开机自启LaunchAgent 还能做定时任务。比如每天凌晨 3 点清理日志keyStartCalendarInterval/keydictkeyHour/keyinteger3/integerkeyMinute/keyinteger0/integer/dict或者每隔 5 分钟执行一次keyStartInterval/keyinteger300/integer我之前用 cron 做定时任务后来发现 macOS 对 cron 的支持越来越弱权限还有限制。现在定时任务我全部用 LaunchAgent 来做更原生的方案。九、和系统设置 → 登录项的区别很多人可能在系统设置 → 通用 → 登录项里添加过启动程序。这两者的区别登录项LaunchAgent能跑后台服务吗勉强能但会弹窗口天生为后台服务设计崩溃自动重启不能KeepAlive支持日志管理没有StandardOutPath定时任务不支持StartInterval/StartCalendarInterval环境变量控制继承用户环境手动指定更可控适合场景GUI 应用比如 iTerm、浏览器后台服务、脚本、代理简单说GUI 应用用登录项后台服务用 LaunchAgent。十、常见问题Qlaunchctl bootstrap报5: Input/output error怎么回事多半是服务已经加载过了。先 bootout 再 bootstraplaunchctl bootout gui/$(id-u)/com.example launchctl bootstrap gui/$(id-u)~/Library/LaunchAgents/com.example.plistQ服务状态显示 exit code 1但日志里什么都没有检查一下可执行文件的路径是不是对的用绝对路径。另外看日志目录是否存在。Q怎么查看服务为什么崩了看StandardErrorPath指定的错误日志。另外launchctl print gui/$(id -u)/com.example里会显示最后一次退出状态。Q能不能不重启就测试 plist可以。bootstrap加载后立即启动不需要重启电脑。bootout后服务立即停止。Q卸载服务要不要删 plist 文件不删也行先 bootout 停掉就行。但如果彻底不用了建议 bootout 后删掉 plist 文件保持~/Library/LaunchAgents/干净。参考链接Apple 官方 launchd.plist 文档OpenClaw 官方文档OpenClaw GitHub 仓库launchctl 命令手册