macOS使用LaunchAgent管理OpenClaw守护进程

macOS的服务管理方式

在macOS系统上，管理后台服务的标准方式是使用launchd和LaunchAgent。与Linux的systemd类似，launchd是macOS的系统服务管理器，而LaunchAgent专门用于管理当前用户级别的后台进程。OpenClaw作为AI Agent网关，需要持续运行以接收来自WhatsApp、Telegram、Discord等聊天平台的消息，因此将其配置为LaunchAgent守护进程是macOS上的最佳实践。

自动安装方式

OpenClaw提供了一键安装守护进程的命令。在macOS上，它会自动创建LaunchAgent配置：

openclaw onboard --install-daemon

运行后，OpenClaw会自动在~/Library/LaunchAgents/目录下创建plist配置文件。你可以通过以下命令确认是否安装成功：

launchctl list | grep openclaw

如果看到输出中包含openclaw相关条目，说明守护进程已经配置好了。如果自动安装不生效或你想自定义配置，请继续阅读手动配置部分。

前置条件

在开始手动配置之前，确保以下条件已满足：

macOS系统（支持Ventura 13及更高版本）
已安装Node.js 22+（不要使用Bun，因为在处理WhatsApp和Telegram连接时有已知bug）
已通过npm install -g openclaw@latest安装OpenClaw
已运行openclaw onboard完成初始化配置

确认OpenClaw可以正常运行：

openclaw --version
openclaw doctor

创建LaunchAgent配置文件

LaunchAgent的配置文件是一个XML格式的plist文件，存放在~/Library/LaunchAgents/目录下。

首先确认OpenClaw的安装路径：

which openclaw

常见路径为/usr/local/bin/openclaw或/opt/homebrew/bin/openclaw。记下这个路径。

创建plist文件：

nano ~/Library/LaunchAgents/com.openclaw.agent.plist

写入以下内容：

<?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.openclaw.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>start</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

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

    <key>ThrottleInterval</key>
    <integer>5</integer>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
        <key>NODE_ENV</key>
        <string>production</string>
    </dict>

    <key>StandardOutPath</key>
    <string>/tmp/openclaw.stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/openclaw.stderr.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>

请将/usr/local/bin/openclaw替换为你实际的OpenClaw路径。如果你使用Homebrew安装的Node.js，路径可能是/opt/homebrew/bin/openclaw。

配置说明

Label：服务的唯一标识符，使用反向域名格式
RunAtLoad：设为true表示用户登录时自动启动
KeepAlive：配置自动重启策略。SuccessfulExit为false表示非正常退出时自动重启，NetworkState为true表示仅在网络可用时运行
ThrottleInterval：崩溃后重启的最小间隔秒数，防止频繁重启
EnvironmentVariables：确保PATH中包含Node.js和OpenClaw的路径
ProcessType：标记为后台进程，macOS会据此优化资源调度

加载和管理服务

加载服务

launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

启动服务

launchctl start com.openclaw.agent

检查服务状态

launchctl list | grep openclaw

输出中第一列数字是PID（进程ID），如果不为0说明服务正在运行。第二列是退出状态码，0表示正常。

停止服务

launchctl stop com.openclaw.agent

卸载服务

launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist

查看日志

OpenClaw的标准输出和错误日志分别保存在我们配置的路径中：

tail -f /tmp/openclaw.stdout.log
tail -f /tmp/openclaw.stderr.log

如果你想将日志保存到更持久的位置，可以修改plist中的StandardOutPath和StandardErrorPath为：

<key>StandardOutPath</key>
<string>/Users/你的用户名/.openclaw/logs/stdout.log</string>
<key>StandardErrorPath</key>
<string>/Users/你的用户名/.openclaw/logs/stderr.log</string>

记得先创建日志目录：

mkdir -p ~/.openclaw/logs

修改配置后重新加载

当你修改了plist文件或OpenClaw的配置文件~/.openclaw/openclaw.json后，需要重新加载服务：

launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

访问管理面板

服务运行后，你可以通过浏览器访问OpenClaw的管理面板：

openclaw dashboard

或者直接在浏览器中打开http://localhost:3000。

故障排查

如果服务无法启动，按以下步骤排查：

检查plist语法：plutil -lint ~/Library/LaunchAgents/com.openclaw.agent.plist
查看系统日志：log show --predicate 'senderImagePath CONTAINS "openclaw"' --last 5m
检查错误日志：cat /tmp/openclaw.stderr.log
手动运行测试：openclaw start，观察是否有报错
检查路径正确性：确保plist中的ProgramArguments路径指向实际的openclaw可执行文件
运行诊断：openclaw doctor

常见问题包括PATH环境变量未包含Node.js路径、文件权限不正确、或端口3000被其他应用占用。

总结

通过LaunchAgent管理OpenClaw守护进程，你可以在macOS上实现与Linux systemd同样的服务管理体验：开机自启、崩溃自动恢复、集中日志管理。这确保了你的OpenClaw AI Agent网关可以7x24小时稳定运行，不错过任何来自聊天平台的消息。