自动化平台最怕网关返回 401／unauthorized，而聊天渠道表面仍「在线」。在 Mac mini M4 上，根因往往不是密码学——而是两份配置：交互 shell 读到的 openclaw.json 与重启后 LaunchAgent 守护进程看到的那份是否一致。本文给出 gateway.auth 对齐矩阵、令牌轮换要点，以及八条可复现步骤，可与健康探针、doctor 输出一并使用。
诊断：openclaw doctor 与健康诊断。就绪：健康与就绪探针。launchd：launchd 与网关就绪。价格：定价；帮助：帮助。
故障模式矩阵
| 现象 | 可能漂移 | 首选修复 |
|---|---|---|
| 网关令牌缺失 | CLI 只把令牌写在 shell 环境 | 写入 JSON 的 gateway.auth；重跑 doctor |
| 回环 RPC 探针失败 | 端口冲突或陈旧锁文件 | lsof -i :端口；结束多余进程后重启 |
| 重启后失效 | 守护进程用户未加载 LaunchAgent | 核对 plist 路径，对登录用户执行 launchctl bootstrap |
| 渠道在线但 UI 401 | 反向代理剥离 Authorization |
与 出站 TLS 指南 对齐透传策略 |
配置单一事实来源
| 层级 | 负责内容 | 审计方式 |
|---|---|---|
~/.openclaw/openclaw.json |
网关鉴权、绑定模式、渠道 | openclaw config get gateway.auth.token（以版本文档为准） |
| LaunchAgent plist | HOME、TMPDIR、显式环境覆盖 |
与交互式 printenv 做 diff |
| 密钥库 | 不入 Git 的长期令牌 | 轮换 runbook + CMDB 校验和 |
无头 Mac 提示： 若网关需在无 GUI 登录下 survive 重启，请验证安装落在 LaunchAgents 还是 LaunchDaemons——行为不同，runbook 写清取舍。
八步排查清单
- 复现上下文： 区分仅交互失败还是仅守护进程失败。
- 运行 doctor： stdout/stderr 附到工单或 CI 产物。
- 比对配置： 对服务账户与 shell 用户的
openclaw.json做哈希。 - 校验令牌字段： 与当前 CLI 大版本文档中的键名一致。
- 干净重启： 停网关，在文档允许时清陈旧锁，再拉起。
- 回环探针： 对齐就绪文 p95 目标（< 200 ms）。
- 日志片段： 附脱敏后最近 200 行。
- 事后： 当
gateway status日抖动 > 3 次时告警。
常见问题
为什么 OpenClaw 网关在终端正常，在 launchd 下失败？
交互式 shell 会加载 profile 与环境变量，LaunchAgent 默认不继承。令牌与代理应写在 ~/.openclaw/openclaw.json 或 plist 的 EnvironmentVariables 中，而不能仅 export 在 shell 里。
2026 年 macOS 上网关鉴权令牌应放在哪里？
优先放在守护进程实际读取的 JSON 配置中的 gateway.auth 相关字段（以所用 CLI 大版本文档为准）。缺失时用 openclaw doctor 生成或修复，然后重启网关并用 openclaw gateway status 验证。
建议先在可丢弃的 Mac mini M4 租用机上演练令牌轮换与 plist 修改，再动生产网关。NodeMac 在香港、日本、韩国、新加坡、美国提供带 SSH／VNC 的独占 Apple Silicon，便于快照故障布局而无需采购备机。