痛点拆解
其一安装器在干净 Runner 上尝试装 Homebrew 失败时无日志，门禁直接红。其二多 Job 共用同一数据根，热写与探针并发产生幽灵状态。其三合并请求里只看标准输出，标准错误里的 doctor 告警被埋没。
前置版本与目录隔离
用 node -p process.version 确认主版本不低于二十二点一四或切到二十四 LTS；全局 openclaw 与 CLI 发行说明同周对齐。每个 CI Job 导出独立 OPENCLAW_HOME，例如 /tmp/oc-job-${CI_JOB_ID}，避免与七乘二十四常驻实例抢锁。网关监听默认 一万八千七百八十九，并行 Job 请设 OPENCLAW_GATEWAY_PORT 递增并在探针 URL 中写明。
| 布局 | 适用 | 风险 |
|---|---|---|
| 共享 HOME | 单人调试机 | 流水线互相覆盖配置 |
| 每 Job 子目录 | 合并门禁与多分支并发 | 需清理磁盘缓存策略 |
非交互参数表（环境变量与占位）
| 变量或开关 | 含义与写法 |
|---|---|
OPENCLAW_HOME |
数据与缓存根；与 LaunchAgent 工作目录必须同值再跑 doctor。 |
CI_SECRET_* |
由 GitLab GitHub 等密钥库映射为模型与网关令牌；禁止写进仓库明文。 |
| onboard 非交互 flag | 以当前 CLI 帮助为准，常见组合含跳过向导与接受默认路径；先 --help 钉入流水线注释。 |
与 CI Job 串联的门禁脚本骨架
顺序建议：预检→检查点 tarball→安装或跳过→非交互 onboard→doctor→校验或状态探针→单行摘要。合并日志示例（占位命令请按你们固定版本替换）：
doctor 输出解析：对表格或勾选行用 grep 关键字失败即短路；与 只读 config validate 分阶段，避免修复型子命令污染合并分支。
常见报错 FAQ（端口、PATH、令牌）
端口占用或拒绝连接
默认一万八千七百八十九被旧进程占用时改端口并重启探针；同一主机多网关必须端口与 HOME 双隔离。
命令未找到
Runner 非登录 shell 未加载 nvm；在脚本首部导出 PATH 或使用 $(npm root -g)/../bin 绝对路径。
令牌无效或未注入
核对密钥变量是否映射到执行 openclaw 的同一 Unix 用户；仅 Job 可见而 LaunchAgent 不可见会导致本地过线、线上四零一。
七乘二十四与可引用检查条
常驻网关应落在低抖动的租用金属或独占 Runner；门禁 Job 可与守护分池，避免编译型任务抢满磁盘 I O。固定出口与白名单见 WireGuard 出站 Playbook。可引用：一万八千七百八十九默认端口；二四八秒退避探针；检查点文件名带时间戳与合并请求号。
- 预检 Node 与安装器横幅已写入合并日志。
- 检查点 tarball 生成后再改配置。
- doctor 无错误签名再合并。