Cron Worker 安全护栏（POSIX）

面向可靠性的检查清单，适用于 OpenClaw cron workers 及任何无人值守的自动化任务。

适用范围（重要）

• 本技能聚焦于 POSIX 环境（示例使用 bash/sh）。
• 原则 具有可移植性，但若你运行在 Windows/PowerShell 环境下，则需采用等效模式。

NO_REPLY 约定

许多 OpenClaw 部署将精确输出 NO_REPLY 视为“静默成功”（不向人工发送通知）。

• 若你的运行时环境不支持 NO_REPLY，请将其理解为：成功时不打印任何内容。

快速上手

1. 脚本优先： 将逻辑移入代码仓库中的脚本（推荐路径：tools/.py 或 tools/.sh）。
2. cron 中仅执行一条命令： cron 应仅调用 一条简短命令（避免使用多行 bash -lc '...'）。
3. 确定性的当前工作目录与环境： 使用 cd 切换至代码仓库根目录（或由脚本自行完成），并明确记录所需环境变量。
4. 成功时保持静默： 执行成功时不得输出任何内容（或仅输出精确的 NO_REPLY）；仅在异常时输出简短告警信息。

另请参阅：

• references/cron-agent-contract.md
• references/pitfalls.md

本技能存在的原因

Cron 失败极少源于“逻辑缺陷”。实践中，常见原因包括：

• 脆弱的 Shell 引号嵌套（如 bash -lc '...' 中引号配对错误）
• 命令替换引发的意外行为（$(...)）
• 隐藏转义缺陷的一行式命令（如 python -c "..."）
• 当前工作目录或环境变量漂移（“本地运行正常，cron 中失败”）
• 管道因非预期原因失败（pipefail 与 head / SIGPIPE 组合）

解决方案虽显枯燥，但极为有效：脚本优先 + 确定性执行 + 成功时静默。

可移植性规则（仍须遵守）

即使在 POSIX 系统上，也切勿硬编码与单台机器绑定的、部署特定的绝对路径。

推荐做法：

• 使用相对于代码仓库的路径
• 使用已明文记录的环境变量
• 采用极简封装脚本，并在其中执行 cd 进入代码仓库根目录

常见失败模式 → 对应修复方案

1) unexpected EOF while looking for matching ')'

可能成因：

• 命令替换中 $(...) 未正确闭合
• bash -lc ' ... ' 中嵌套引号损坏

修复模式：

• 将整个多行 Shell 块替换为独立脚本。
• cron 仅调用一条简短命令，例如：
  • python3 tools/.py

2) 因 pipefail + head 导致的误报失败（SIGPIPE）

典型现象：

• 命令以非零退出码终止，但你所需的实际输出完全正常

修复模式：

• 在向 head 管道传输时，避免启用 pipefail
• 更优方案：将过滤逻辑移入脚本中实现（仅读取所需数据）

3) “本地运行正常，cron 中失败”

常见成因：

• 当前工作目录错误
• 缺失必需的环境变量
• PATH 不一致

修复模式：

• 显式 cd 进入代码仓库根目录（或由脚本完成）
• 确保依赖关系明确且已文档化

Git 风险点：git push 被拒绝（非快进式更新）

典型现象：

• 自动化流程向 长期存活的 PR/功能分支 推送时出现 ! [rejected] ... (non-fast-forward)。

保守修复方案（不使用 force-push）：

• 遭遇拒绝后，先拉取远程分支最新状态，再将本地新增提交变基（cherry-pick）到该分支之上，随后重试一次推送。

复制粘贴加固标头（可移植）

建议将以下两行低干扰标头置于 cron 任务配置顶部：

• 加固要求（必须遵守）： 遵循 references/cron-agent-contract.md（脚本优先、确定性 cwd、成功时静默）。
• 同时应用 cron-worker-guardrails 技能。若涉及解析或多步骤逻辑，请编写并运行一个小型 tools/*.py 脚本。