macos-launchd

macos-launchd

用途

此技能用于管理 macOS launchd 服务，包括 LaunchDaemons 和 LaunchAgents，可用于运行后台进程、处理登录项以及设置 OpenClaw 网关服务等任务。它侧重于通过 plist 文件和 launchctl 创建、加载和控制服务。

适用场景

当你需要自动化 macOS 服务时，可使用此技能，例如在系统启动时运行脚本（LaunchDaemon）、在用户登录时运行应用（LaunchAgent），或确保 OpenClaw 网关服务在重启后仍能持续运行。对于需要持久运行的系统级任务，或需要将 OpenClaw 集成到 macOS 环境中的场景，也可使用此技能。

主要功能

• 创建和编辑 LaunchDaemons/Agents 的 plist 文件，并指定 Label、ProgramArguments 和 RunAtLoad 等键。
• 使用 launchctl 加载/卸载服务，以控制其运行。
• 通过 AppleScript 中的 System Events 或 launchctl 等效命令管理登录项。
• 通过配置运行网关的服务与 OpenClaw 集成，并使用 $OPENCLAW_API_KEY 等环境变量进行身份验证。
• 处理服务状态，例如启用/禁用服务，并通过 Console.app 监控日志。

使用模式

要完成任务，首先在 /Library/LaunchDaemons（系统范围）或 ~/Library/LaunchAgents（特定用户）中创建 plist 文件。使用 launchctl 命令管理该文件。要集成 OpenClaw，请在 plist 中写入网关命令并引用环境变量。加载前务必验证 plist 语法。要以编程方式访问，可使用 AppleScript 添加登录项，例如通过 osascript。

常用命令/API

• 使用 launchctl load [-w] /path/to/com.example.plist 加载服务；-w 标志会将设置写入持久存储。
• 使用 launchctl unload [-w] /path/to/com.example.plist 卸载服务。
• 启动/停止服务：launchctl start com.example.label 或 launchctl stop com.example.label。
• plist 格式示例（XML）：

  <?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.example.service</string>
      <key>ProgramArguments</key><array><string>/usr/bin/python3</string><string>/path/to/script.py</string></array>
      <key>RunAtLoad</key><true/>
    </dict>
  </plist>
  

• 对于 OpenClaw 网关，使用 launchctl list | grep openclaw 检查状态。
• API 说明：没有直接的 API；可通过 launchctl CLI 或 Swift 中的 SystemConfiguration framework 进行交互，例如使用 SCDynamicStoreCopyConsoleUser() 获取用户上下文。

集成说明

与 OpenClaw 集成时，将网关服务放在 plist 的 ProgramArguments 下，例如 <string>/path/to/openclaw-gateway --key $OPENCLAW_API_KEY</string>。在 plist 中设置环境变量：EnvironmentVariablesOPENCLAW_API_KEYyour_key。通过添加 UserNameyourusername，确保服务以正确的用户身份运行。要进行跨技能集成，请引用 macos 集群；导出路径，例如 export PATH=$PATH:/usr/bin，以便访问 launchctl。

错误处理

检查 launchctl 退出代码：成功时为 0，出错时为非零值（例如 plist 无效时为 78）。加载前使用 plutil -lint /path/to/com.example.plist 验证并解析错误。如果服务失败，可使用 launchctl error <label>，或通过 log show --predicate 'subsystem == "com.apple.launchd"' 查看系统日志。对于 OpenClaw，如果身份验证失败，请确保已设置 $OPENCLAW_API_KEY 且未过期；可通过 launchctl kickstart -k com.openclaw.gateway 重启服务来处理。编辑后务必卸载并重新加载服务，以避免冲突。

使用示例

1. 创建一个在登录时运行脚本的 LaunchAgent：首先，按照上述格式在 ~/Library/LaunchAgents/com.example.login.plist 中编写 plist 文件，然后运行 launchctl load -w ~/Library/LaunchAgents/com.example.login.plist。要验证结果，请使用 launchctl list | grep com.example。
2. 将 OpenClaw 网关设置为 LaunchDaemon：创建 /Library/LaunchDaemons/com.openclaw.gateway.plist，其中包含 ProgramArguments/path/to/openclaw-gateway--key$OPENCLAW_API_KEY，然后执行 sudo launchctl load -w /Library/LaunchDaemons/com.openclaw.gateway.plist。使用 launchctl list com.openclaw.gateway 进行监控。

图关系

• 相关于：macos（集群），因为它共享“macos”和“services”等标签。
• 链接到：launchd（标签），适用于系统管理等依赖技能；openclaw（嵌入提示），适用于特定于网关的集成。
• 通过以下内容关联：plist（标签），可能关联到文件管理技能；launchctl（描述），适用于 macos 集群中的命令行工具。