OPENCLAW 2026
POST_INSTALL_
GATEWAY_
PATH_FORCE.
许多人在 macOS 或远程 Mac 上执行 npm install -g openclaw 或官方脚本后，终端里没有明显报错，但紧接着 openclaw ask 卡住、openclaw-gateway: command not found，或 openclaw gateway status 显示二进制缺失/未注册——这不是「模型坏了」，而是安装语义只完成了「CLI 包」却没把 Gateway 服务单元落到可执行路径与常驻配置。本文给出症状—证据—动作分层矩阵、五步首跑 Runbook、可引用数字门槛与 FAQ；并与站内《install.sh 零到生产》《LaunchAgent 与 gateway token》《Chrome Relay 18792》《v2026.5.x 分层运维》交叉阅读。若你需要路径干净、可对照第二套黄金环境的 Apple Silicon，可把本 Runbook 原样复制到 MACGPU 远程 Mac 上执行。
1. 痛点拆解：为什么「装完」仍像没装？
1）npm 全局前缀与 PATH 漂移：包管理器把可执行文件放在 ~/.npm-global/bin 或 nvm 的 shims 下，但当前 shell 未加载对应 PATH，导致 openclaw 偶现而 openclaw-gateway 不在同一搜索顺序里。2）Gateway 注册步骤被跳过：部分环境只完成了包下载，没有执行 openclaw gateway install 或等价注册，CLI 能打印帮助但没有本地监听进程。3）Node 22 门槛与多 Node 并存：系统自带旧 Node 被优先命中，安装脚本在 A Node 下成功、你却在 B Node 的 shell 里执行命令。4）远程 Mac 的 launchd 与交互 shell 不是同一套环境：SSH 里「看起来好了」，LaunchAgent 里仍缺 PATH 或 OPENCLAW_*，表现为「人登录能用、无人值守就挂」。这四类问题都不该先用大模型 API 或渠道限流来解释，否则会在错误层烧掉半天。
2. 症状—证据矩阵：先判定缺的是哪一层
| 你看到的 | 优先怀疑 | 首选证据命令/文件 |
|---|---|---|
openclaw-gateway: command not found | PATH / 前缀未生效 | which openclaw、npm prefix -g、echo $PATH |
openclaw gateway status 报未安装或未运行 | Gateway 未注册或二进制未落盘 | openclaw gateway install --force 前后对比、安装日志 |
| 本机 OK、launchd 下失败 | LaunchAgent 环境缺失 | plist 内 EnvironmentVariables、launchctl print |
| 仅远程 Mac 必现 | SSH 非登录 shell / 多用户路径 | ssh -t 与交互 profile 对照、whoami 与 home |
3. 五步首跑 Runbook（每次新机器必跑）
Step 1 冻结运行时三元组
记录 node -v（须与官方文档的 22+ 对齐）、npm -v、以及 which node 的绝对路径；禁止「终端里能跑就行」的模糊描述。
Step 2 校验全局前缀与 PATH
执行 npm config get prefix，确认全局 bin 已加入 shell 配置（zsh 为 ~/.zshrc）；若曾用 sudo npm 装过包，必须停止继续 sudo，改为用户前缀并重装，避免权限分裂。
Step 3 显式注册 Gateway
在维护窗内执行 openclaw gateway install；若 doctor 仍提示异常或旧残留，使用 --force 覆盖注册并与站内 token 稿对齐令牌与 LaunchAgent 内嵌变量。
Step 4 端口与健康检查
按环境核对默认监听（以你版本文档为准），并结合 Chrome Relay 稿对 18792 等健康探针做本机回环 vs SSH 隧道语义区分，避免把「没监听」误判成「提供商挂了」。
Step 5 冷启动对照与日志切片
完整退出 Gateway 后再启动，导出固定时间窗的 openclaw logs，把「安装阶段」「注册阶段」「首次 ask」分成三段附件，写进工单。
4. 三道门禁（写进值班表）
第一道：which openclaw-gateway 非空且与 openclaw 同属一前缀树，否则禁止宣告「安装成功」。第二道：openclaw gateway status 未进入文档所述健康态前，禁止把业务渠道切到生产。第三道：远程 Mac 上未跑通非交互 launchd 冷启动前，禁止把笔记本隧道当作唯一依赖。
5. 深度案例：四小时「全怪 OpenAI」的复盘
「npm 装完没报错，openclaw -h 有输出，但 ask 永远转圈；团队先换了三次 API Key，又怀疑被限流，最后发现 LaunchAgent 里根本没把 ~/.npm-global/bin 写进 PATH，gateway 二进制装在用户前缀下却永远起不来。」
某小团队在 2026 年 5 月把 OpenClaw 装在一台远程 Mac mini 上跑 7×24。白天工程师 SSH 登录调试时，profile 会把 nvm 与 npm 前缀注入 PATH，因此手工执行「看似一切正常」；夜间无人登录时，launchd 子进程以最小环境启动，只找到系统旧 Node，Gateway 注册步骤写进用户目录却从未被正确拉起。他们在错误层做了大量尝试：调低温度参数、换模型名、甚至重建 workspace——直到按本文矩阵检查 which 与 plist 环境变量，才发现同一台机器存在两套「真相」。修复组合为：统一 Node 22 路径写进 plist、用 openclaw gateway install --force 重建服务单元、并在维护窗内跑完 install.sh 稿中的 channels probe 门禁。此后 ask 首包稳定，值班表增加「冷启动对照」条目。该案例说明：远程常驻场景里，交互 shell 与 launchd 的路径语义必须分开验收，否则排错会被 API 日志带偏。
对照站内 v2026.5.x 运维稿可知：即便上游插件与 Gateway 启动语义在变，「二进制是否在 PATH」「服务是否被 launchd 正确继承环境」仍是底座；底座不稳时，上层 TTS/渠道分层只会放大噪声。若你已在生产窗内遇到类似「人登录就好、人走就坏」，优先回到本篇五步，再打开 5.x 分层矩阵。
6. 行业洞察：代理栈「包管理化」后，底座验收反而更重要
2026 年主流自建代理项目普遍把 Gateway、插件与 CLI 拆成可独立升级的单元；这意味着「一次 npm 成功」不再等价于「运行时闭环」。团队若仍用 2024 年的「装完就跑 ask」脚本，会在多 Node、多用户、远程 launchd 场景里反复交学费。与「盲目加机器配置」相比，更现实的杠杆是：PATH 与注册步骤写进可审计清单、维护窗内冷启动对照、以及一台变量更少的黄金对照机。
若你的主开发机是 Windows 或 Linux，仅把 macOS 当作「顺便能跑」的附属环境，图形工具链与 Apple 生态脚本往往更难对齐；当你要证明「是 Gateway 没注册而不是网络抖动」时，**少一个变量就少一轮会议**。此时租一台已预置干净 Node 前缀与可写日志路径的远程 Apple Silicon，把本篇 Runbook 原样跑一遍，通常比继续在本机叠补丁更快得到结论。若你希望减少自建摩擦、把对照实验落到独占节点，可考虑租赁 MACGPU 远程 Mac，把五步与三道门禁固化为上线模板。
Windows 或 Linux 上自建 Gateway 并非不可行，但在桌面会话、浏览器工具链与部分渠道驱动混合的场景里，变量更多；当你需要「与生产 macOS 对齐的第二现场」时，远程 Mac 仍是低摩擦对照面。基于可复现排错与稳定监听而非品牌教条，我们建议把黄金环境放在 Apple Silicon 上完成底座验收后，再讨论是否扩展异构节点。
7. 可引用数字门槛（写进变更单）
① 冷启动到 openclaw gateway status 健康：>90 秒 必须触发架构评审（是否扫描/磁盘过慢）。② 首次 openclaw ask 探针在本地回环：>25 秒 无回执必须先查 Gateway 层，再查模型层。③ 同一维护窗内 gateway install --force 重试 >2 次必须停手做人肉 diff（避免脚本与手工双写）。④ 远程 Mac plist 中 PATH 条目少于 3 个关键路径（node、npm-global、openclaw）时默认视为不合格配置。
补充一条磁盘与权限门槛：若 Gateway 日志目录落在无写权限的只读卷或网络盘上，安装脚本可能「表面成功」但服务单元反复崩溃；此时除 PATH 外还要检查 StandardOutPath/StandardErrorPath 与 workspace 是否同用户属主。再补充并发门槛：维护窗内禁止同事并行执行互相覆盖的 npm -g 与 pnpm 全局安装，否则会出现「刚 which 到、下一秒又找不到」的竞态，这类竞态在远程共享账号场景里尤其常见，应把安装动作串行化并写锁文件到工单。
8. FAQ
问：doctor 全绿还要检查 which 吗？答：要；doctor 覆盖配置语义，which 覆盖可执行文件是否真的在同 shell 可见。问：与 token_mismatch 怎么区分？答：token 问题多在鉴权回执与 401；本篇症状多在进程未起或二进制缺失，先对照 token 稿排除后再合并结论。问：可以用 sudo npm 快速修吗？答：不建议；会把前缀分裂成 root 与 user 两套，后续更难排。问：Chrome Relay 红但 gateway status 绿？答：进入 Chrome Relay 分层稿，不要回到安装层重装机。
问：install.sh 与纯 npm 混用会怎样？答：极易留下双源元数据；选一条路并在工单写明。问：远程 Mac 最小改动是什么？答：plist 内显式 PATH + Node 绝对路径 + 固定日志目录。问：五步跑完仍失败？答：打开 WebSocket 握手稿与 5.x 运维稿做第二层；但仍需保留本篇附件作为底座证据。