openclaw doctor、Dashboard 令牌仅存本机，并用 curl 探 /health。内链：安装排错、健康守护、Discord 摘要；详见 docs.openclaw.ai。
环境与最小权限准备
痛点：1）0.0.0.0 暴露管理面；2）并行 Job 共用目录致缓存串味；3）launchd 与 shell 的 Node 路径不一致致守护进程异常。
| 维度 | 推荐（生产） | 避免 |
|---|---|---|
| 网关监听 | 127.0.0.1 + SSH 反向隧道 / 内网反代只暴露单一路径 |
Dashboard 与业务口无鉴权直连公网 |
| Node 与自检 | 24 LTS 或文档最低 22.16+；安装后必跑 openclaw doctor |
仅登录 shell 可见的 nvm 别名，launchd 未继承 |
| 令牌与 Jenkins | OpenClaw 令牌写 plist/Keychain；Jenkins 侧仅保存调用预检的只读用户与 API Token | 把双方密钥提交进 Git 或打在镜像层 |
| 健康检查 | 监控脚本轮询本机 /health 与 Jenkins /login |
仅靠人工发现 Webhook 静默失败 |
预检进程单独设置 COMPOSER_CACHE_DIR、npm_config_cache；企业根证书用 NODE_EXTRA_CA_CERTS。跨境 PHP 可为 Composer 配镜像并收紧超时。
健康检查可与导语中 LaunchAgent 守护文一致：定时 curl -sf http://127.0.0.1:<port>/health，失败则 launchctl kickstart 拉起网关，避免 Jenkins 长期 connection refused。
Jenkins Generic Webhook 与签名校验参数
安装 Generic Webhook Trigger 后，在 Job 里生成含随机 token 的 URL，经隧道只映射到 OpenClaw 回环端口。Post content 用 application/json，用 JSONPath 取 job、build、分支与仓库。
防篡改可约定共享密钥：请求头 X-Jenkins-Signature 为 body 的 HMAC-SHA256（十六进制），网关验签后再解析；反代勿改 body。可再加 Authorization: Bearer 静态令牌。
Jenkins 若需回调自身 REST，请使用仅具必要 Job 范围的 API 用户，定期轮换 Token，并禁止把明文密钥写进 Freestyle 的 echo 步骤日志。
OpenClaw 侧接收、调用 composer/npm 等预检命令模板
Handler 流程：验 token/签名 → 解析 job/build/git → 在 /var/tmp/jenkins-preflight-<build> git clone --depth 1 → 串行预检，失败短路并记录退出码。
- ①
openclaw doctor通过后再由 launchd 拉起网关。 - ② 将 Jenkins Webhook 经隧道落到
127.0.0.1业务端口。 - ③ 验 token/HMAC，拒绝非法体与非 JSON。
- ④ 每构建独立 WORK_DIR，注入隔离缓存环境变量。
- ⑤ 执行下方 composer/npm 模板，捕获 stdout/stderr 前 4KB。
- ⑥ 组装
ok、summary、build后回传。
预检脚本建议把标准输出尾部写入摘要字段，并在失败时附带 exit_code，便于 Jenkins 控制台与下游告警对齐。
构建摘要回传（HTTP/Webhook）与失败重试
HTTP 回 Jenkins：POST 到自建端点或经典 REST（先取 /crumbIssuer/api/json 再带 Jenkins-Crumb）。协作侧可用 Incoming Webhook embed，字段对齐导语 Discord 文。
重试：网络错、429、5xx 时最多三次，间隔 1/2/4 秒；幂等键 job+build，成功后去重。单次超时 15 秒。
摘要 JSON 可约定字段 status、preflight、duration_ms，方便 Pipeline 用 readJSON 做门禁、可视化趋势与告警聚合及报表展示。
常见报错排查 FAQ
Jenkins 侧显示 401 或 OpenClaw 记录验签失败？
核对 URL token；HMAC 用原始 body；反代勿改 JSON。
回传 Jenkins API 返回 403 Forbidden？
经典 Jenkins 要 crumb+Cookie；API 用户需 Job 权限；前置 OAuth 时用服务账号路径。
composer/npm 在守护进程里报找不到命令？
LaunchAgent 的 EnvironmentVariables 写全路径 PATH 与 COMPOSER_HOME。
Webhook 重复通知同一构建？
网关侧去重；Jenkins 勿多 Job 共用同一 token 致双倍 POST。