CodeBuild Build State Change，再由 API Destination 发起 HTTPS——下文把这种出站调用称作类 Webhook。官方 CLI 与网关说明见 docs.openclaw.ai，Node 与 openclaw node 默认端口见 docs.clawd.bot/cli/node。延伸阅读：Bundler 预检与 CI Webhook Playbook、网关健康与 LaunchAgent、CircleCI 出站 Webhook 对照。
安装、Node 版本与网关守护进程
Node：优先 Node 22 LTS（含 22.16+）或 24 LTS。OpenClaw 文档说明 Node 22+ 对网关 WebSocket 开箱即用；若暂时卡在 Node 20–21，需按文档额外安装 ws 依赖，避免运行时握手异常。装完运行 openclaw doctor，确认 which node 在交互 shell 与 launchd 启动的守护进程里指向同一路径。
向导与守护：首次落地可执行 openclaw onboard --install-daemon，在 macOS 上由向导写入 LaunchAgent，让网关机进程随用户会话拉起；若在无图形会话的纯 SSH 场景遇到服务检测失败，先前台 openclaw gateway run 验证，再对照发行说明修复 systemd/launchd 会话问题。
网关端口与健康检查思路：openclaw node run --host 127.0.0.1 --port 18789 表明 Gateway WebSocket 默认端口为 18789（可用 --port 覆盖）。HTTP 管理面仍建议只绑 127.0.0.1，对外用 SSH -R 或边缘反代暴露单一 Webhook 路径。健康检查可用 curl 携带与 handler 一致的 Authorization: Bearer … 访问文档约定的 /health（或等价 JSON），并在 plist 中同步 NODE_BINARY、NODE_EXTRA_CA_CERTS；更细的 plist 与巡检模板见上文内链《网关健康与 LaunchAgent》。
令牌：OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD 与 Dashboard 配置不入库；与 AWS 侧 API Destination Connection 里的静态密钥分开轮换。
对比：CodeBuild 源 Webhook vs EventBridge 出站
| 维度 | CodeBuild 源 Webhook | EventBridge + API Destination（类 Webhook） |
|---|---|---|
| 方向 | Git 托管方 → AWS，用于触发新构建 | AWS → 你的 HTTPS 端点，用于通知构建阶段/结果 |
| 典型 payload | Git push / PR 事件（依提供商） | detail-type 为 CodeBuild Build State Change，含 build-id 等 |
| 与 OpenClaw 衔接 | 不直接调用 Mac 网关 | 规则目标指向隧道后的 URL，handler 做 Bearer 校验与幂等 |
| 依赖预检落点 | 可在 buildspec 的 install/pre_build 失败即红 |
终态事件驱动网关在 Mac 上聚合日志片段与摘要出站 |
EventBridge 规则、API Destination 与 Webhook 校验
在与 CodeBuild 项目相同区域的默认事件总线新建规则："source":["aws.codebuild"] 且 "detail-type":["CodeBuild Build State Change"]；用 detail.project-name / detail.build-status 过滤，避免矩阵构建刷屏。目标选择 API Destination，Endpoint 填公网可达域名（经反代或 SSH -R 转到本机 OpenClaw handler 路径）。Connection 中配置静态 Header（如 Authorization: Bearer <token>），与网关进程读取的密钥一致即可视为最小可行的 Webhook 校验；更高阶可改为 HMAC 自定义头并校验原始 body。
Input transformer：建议只转发 build-id、project-name、build-status、completed-phase、additional-information，减小 Mac 侧解析与日志脱敏成本。联调时用 aws codebuild start-build --project-name … 手工起一条构建，在 CloudWatch「EventBridge 规则指标」里看 Invocations / FailedInvocations。
- 1. Mac 本机
curl -H "Authorization: Bearer …" https://127.0.0.1:…/your-hook发送样例 EventBridge body，确认 2xx。 - 2. 创建 API Destination + Connection，规则目标绑定同一 Connection，打开 DLQ 观察首次真实投递。
- 3. handler 校验 Header 通过后解析 JSON，写入
build-id幂等键，再异步拉日志或触发技能。 - 4. HTTP 响应在数秒内返回 2xx，重查询用 1s / 2s / 4s 退避调用下游 Chat Webhook。
buildspec 依赖预检与网关侧摘要脚本
在 buildspec.yml 的 install 或 pre_build 执行只读预检：npm ci --dry-run、bundle check、容器镜像 curl -fsS 探活等，失败即非零退出，让失败留在 AWS 侧日志。网关收到 FAILED / SUCCEEDED 终态后，再把 CloudWatch 片段与预检结论拼成 Markdown/JSON，经 Slack/企业微信等第二跳发出；字段编排可复用 Bundler 预检 Playbook 中的出站 JSON 约定。
收不到事件与常见故障 FAQ
规则从未触发，Mac 上完全没有日志？
核对区域是否与 CodeBuild 一致；事件模式是否写错 detail-type；组织是否禁用默认总线；用同一账号手动 start-build 复现。若指标显示已调用但 Mac 无流量，优先查 SSH 隧道 / 反代进程是否掉线。
API Destination 一直 401/403？
核对 Connection 授权头与 OpenClaw handler 是否同一令牌；反代是否剥离 Authorization；路径前缀是否与技能路由一致。
EventBridge 重试耗尽或进入 DLQ？
handler 必须快速返回 2xx；把拉日志、发 Slack 放队列；DLQ 消息可用脚本人工重放。观察 FailedInvocations 与目标端 TLS 证书链。
openclaw onboard --install-daemon 后网关仍离线？
log show 过滤 LaunchAgent Label；确认非登录会话是否加载了用户级 Agent；必要时改回前台验证后再写 plist。
检查清单：最小权限、日志字段与重试
| 检查项 | 建议做法 | 失败时重试 / 观测 |
|---|---|---|
| 最小权限 | 规则目标 IAM 角色仅含 events:InvokeApiDestination 等调用目标所需动作；Mac 若需回读 AWS，使用短周期凭据且只读 codebuild:BatchGetBuilds |
CloudTrail 查拒绝原因；收紧策略后重放 DLQ |
| 日志字段 | 结构化打印 build-id、project-name、build-status、completed-phase、请求 ID |
与 CloudWatch Logs 交叉检索；避免打印完整 Bearer |
| 重试 | 依赖 EventBridge 目标指数退避；出站摘要采用 1s / 2s / 4s 手动退避并限流 | 429/5xx 时拉长间隔；合并同一 build-id 的重复通知 |
远程 Mac 扩容：托管网关与跨境拉取同一出口
帮助中心（含 SSH 指南）、购买页扩容算力、首页 均免登录；OpenClaw 相关文章见 技术博客。