2026年 OpenClaw 定时任务与调度在 macOS 无头远程 Mac 上不执行或超时？Gateway 生命周期、环境变量与 launchd 对照的可复现排错清单 + FAQ
定时任务「到了点却没动静」或「跑一半就超时」，在无头远程 Mac 上往往不是单一原因：Gateway 进程是否在、调度器绑在哪个用户会话里、以及 launchd 拉起时的环境是否与你在 SSH 里手动执行时一致——下面按可复现顺序拆。
1. 先把现象说清楚：不执行 vs 超时
建议你在 Runbook 里区分三类记录：完全没触发（日志里没有计划条目）、触发了但立刻失败（退出码非 0、找不到命令）、触发了但久拖不决（最终被客户端或网关判超时）。三类对应的假设集合不同：前两类优先查进程是否在、PATH 与 plist 环境；第三类优先查 Gateway 侧队列、下游 API 延迟与并发上限。
安装路径与包管理器会决定「非交互 shell 里 openclaw 命令在哪」，这与
OpenClaw 安装路径（install.sh / npm / Docker）选型
直接相关：同一台机器上，登录会话与 launchd 子进程看到的 PATH 可能不一致。
2. Gateway 生命周期：谁在跑调度
若 OpenClaw 的「定时 / 调度」由 Gateway 或常驻代理进程驱动，则该进程存活是前置条件。无头场景下常见坑包括：仅在你 SSH 登录时手动拉起过 Gateway，退出会话后子树被收紧；或存在多个 Gateway 配置（不同端口、不同工作目录）导致你以为在 A 上排了任务，实际调度器在 B。
- 用
ps/pgrep对照文档中的进程名，确认与 LaunchAgent 的ProgramArguments指向同一二进制路径。 - 对监听端口做
lsof -nP -iTCP -sTCP:LISTEN交叉验证（端口以你的配置为准）。 - 重启后是否自动恢复：若否，检查 plist 是否在正确的域（用户
LaunchAgentsvs 系统LaunchDaemons），以及是否依赖已登录 GUI 会话。
若你还同时跑 CI 或长驻构建，可把「定时任务」与「构建队列」的职责边界写清楚，避免争用 CPU / 磁盘导致「看起来像超时」——思路可参考 远程 Mac mini 上从 Xcode 到 TestFlight 的 CI 流程 中的资源与队列意识。
3. 环境变量与 PATH：SSH 里能跑，launchd 里不能
在交互式 SSH 中，你可能通过 ~/.zshrc、~/.zprofile 注入了 PATH、API Key、NODE_PATH 等；而 launchd 启动的任务默认不会执行登录 shell 的整段 profile，除非你在 plist 里显式设置 EnvironmentVariables 或使用包装脚本先 source 再 exec。
可复现对照步骤：
- 在同一用户下，交互 shell 执行
which openclaw（或实际调度命令），记下绝对路径。 - 在 plist 的
ProgramArguments中尽量使用绝对路径，避免依赖 PATH。 - 对敏感变量：不要把密钥写进可被全局读取的 plist；优先钥匙串、受控配置文件或 CI 秘密注入，并限制 plist 权限（
chmod 600）。
4. launchd 对照清单（LaunchAgent）
下面检查项适用于「由 launchd 常驻拉起 OpenClaw 相关进程」的团队 Runbook；标签名请替换为你环境中的真实 Label。
| 检查项 | 建议动作 |
|---|---|
| 服务是否在跑 | launchctl list | grep -i openclaw，关注最后一列退出码是否为 0 |
| 修改 plist 后是否重载 | 按系统版本使用 bootout/bootstrap 或 unload/load，避免旧配置残留 |
| 工作目录 | 在 plist 中设置 WorkingDirectory，与配置文件、相对路径假设一致 |
| 节流与崩溃退避 | 若 ThrottleInterval、崩溃重试过密，可能造成「很久才再试一次」的错觉 |
| 日志 | log show 过滤进程名或关键词；同时保留 OpenClaw 自身日志目录 |
5. 「超时」侧：别急着调大阈值
若任务实际在执行但耗时超过网关或客户端默认等待时间，应先确认：下游网络（模型 API、内网服务）是否抖动、是否触发了速率限制、以及机器是否在同期跑重负载。盲目增大超时可能掩盖背压问题，让队列堆积更难排查。
6. FAQ
Q：为什么我在 SSH 里手动执行正常，一到点就失败？
A：高度怀疑 launchd 环境缺少 PATH/变量，或定时任务跑在不同用户下。用绝对路径 + 显式环境变量复现。
Q：无头 Mac 没有登录桌面，会影响 LaunchAgent 吗？
A：取决于 plist 是否要求 GUI 会话、以及是否放在用户 Agents 目录且该用户从未触发过登录上下文。必要时评估 Daemon 域或确保开机后用户层已正确 bootstrap。
Q：双网关 / 双 Agent 并存时定时任务乱套？
A：先统一配置真源与 Label，再对齐端口与数据目录；与「双 LaunchAgent 并行」类问题同属一类治理题。
在无头远程 Mac mini 上跑 OpenClaw：稳定比「偶尔能跑」更重要
定时调度与网关常驻，本质是在要可预期的进程生命周期与可复现的环境。Apple Silicon Mac mini 在同价位常见小型主机中，往往具备更好的能效与静音表现，适合作为家庭或小团队的 7×24 节点；macOS 与 launchd 的组合也让「plist + launchctl」成为团队容易写成 Runbook 的运维语言。原生 Unix 工具链、SSH 与脚本化观测成本较低，长期无人值守时系统崩溃率与意外重启带来的心智负担也更可控。
结合 Gatekeeper、SIP、FileVault 等机制，攻击面与误操作面也更容易做基线。若你希望把本文中的排错清单落在安静、省电、可长期在线的硬件上，Mac mini M4 是当前很有性价比的起点；现在即可入手，让 Gateway 与定时任务真正按你的节奏稳定执行。