前置条件（Node 24 / 网关）
痛点拆解：① 机型与系统需长期在线，磁盘与日志目录独立挂载避免打满根分区；② 网关与 Runner 若 Node 主版本不一致，易出现原生模块与 TLS 行为分叉；③ 多租户密钥不可写进 Git，需统一走 plist 或只读 env 文件。
| 维度 | 推荐 | 避免 |
|---|---|---|
| 运行时 | 全链路固定 Node 24 LTS | 交互 shell 22、服务 20 混用 |
| 网络 | 出口稳定、可配 HTTPS 代理与企业证书 | 仅本机 curl 通、launchd 未继承代理 |
| 观测 | 独立日志卷与按天轮转 | stdout 只进控制台不落盘 |
安装与要点
按官方入口完成 CLI 与网关组件安装后，在同一用户下依次执行 node -v（应显示 24.x）、openclaw doctor，再对照 launchctl print 中 EnvironmentVariables 是否含 HTTPS_PROXY、NO_PROXY、NODE_EXTRA_CA_CERTS。💡 可引用：变更网关配置后务必 launchctl kickstart -k 对应 Label，避免热更未加载。
多兼容端点与路由配置步骤表
在网关配置中为每个 OpenAI 兼容后端登记 base URL、鉴权引用与超时；路由按模型名前缀优先、通配兜底排序，避免宽规则吃掉窄规则。
| 步骤 | 动作 | 校验方式 |
|---|---|---|
| 1 | 登记后端 A/B（含内网推理与公有云） | curl -sS -o /dev/null -w "%{http_code}" 探根路径 |
| 2 | 写路由：如 gpt-*→A，claude-*→B，其余→默认 |
最小 chat 请求返回 200 且后端日志出现对应 trace |
| 3 | 为每路设 connect 超时与失败回退次数 | 人为断一路后自动切备用并在日志打 fallback 标记 |
| 4 | 打开请求级路由决策日志（脱敏） | grep 某 request_id 可还原命中规则 |
可引用：建议单路首次建立 TLS 超时 8–15 秒、业务重试不超过 2 次，以免雪崩占满连接池。
/健康检查
为网关暴露 /health（或文档约定的等价路径），JSON 中返回进程存活、各后端最近一次 RTT与配置版本号。外部可用简单脚本 curl -fsS --max-time 3 localhost:端口/health，失败则 exit 1 触发 LaunchAgent 或监控重启。与仅打 chat 接口相比，聚合健康能把「网关活着但后端全挂」的情况提前暴露。
与 CI Webhook / 日志摘要联动示例
在流水线末尾增加一步：把 git rev-parse --short HEAD、变更文件列表（如前二十行）、是否重启网关、以及构建结论写入 CI_ARTIFACT_DIR/summary.json，再用 curl -H "Content-Type: application/json" -d @summary.json POST 到内网只读 Webhook（带 HMAC 或 mTLS）。OpenClaw 侧可用插件读该摘要驱动「变更后自动拉模型清单」或与 分层模型缓存 HowTo 对齐预热策略。💻 这样研发不用登录 CI 网页也能在网关日志里看到本次发布与推理路由的上下文。
常见报错 FAQ
Chat 接口 404？
检查 base URL 是否已含 /v1 又再拼接一遍；用 curl 直连后端 /v1/models 对照路径。
401 invalid_api_key？
多为 launchd 未加载密钥而 SSH 会话有 export。把 Key 放进 plist 或引用 env 文件并 kickstart 服务。
路由总走默认后端？
把更具体的模型前缀规则移到通配规则之上；核对客户端传入的 model 字符串大小写与空格。