一点击就闪退？openclaw doctor 揪出网关未激活、模型鉴权与六步自救 runbook（2026 Mac）

你双击快捷方式——或在终端里输入 openclaw——窗口一闪就消失了。没有堆栈跟踪，没有友好对话框，只有沉默。与此同时 Slack 仍显示「gateway not active」，模型选择器一直转圈，昨天你点掉的权限弹窗又以红字出现。这不是「你不懂电脑」；这是环境漂移：Node 版本不对、用户不对、配置文件不对，或 gateway 进程根本没在 launchd 下存活。

openclaw doctor 是 OpenClaw 官方自检命令。它会输出结构化清单——CLI 是否在 PATH 上、配置是否可读、gateway 是否可达、认证配置、磁盘余量——让你一行一行修，而不是照着博客重装一遍。本教程是新手救援通道：doctor 检查什么、如何读懂黄行与红行、可粘贴进工单的六步操作手册，以及新手常见两种故障的排查配方。若你在租用 Mac 上完成 onboarding 后需要 SLA 级验收，请读单独的 onboarding 后 doctor 矩阵；本文针对的是「今天又崩了」。

首次提及时可搭配 OpenClaw 零小时安装契约（Node 22+ 底线）、速率限制与预算告警（避免重试被误判为崩溃），以及本地模型替代云密钥时的 OpenClaw + Ollama。上游安装参考：OpenClaw 安装脚本与 gateway 配置示例。硬件背景：Apple Mac mini 规格。

披露说明：仅在租用 Mac 为新手提供干净 SSH shell 运行 openclaw doctor 时提及 KvmZone。多数步骤在你已有的 Mac 上同样适用。

为何 doctor 胜过从零重装

在中国大陆，npm 镜像慢或出口带宽受限时，registry 超时常被误当成「OpenClaw 坏了」——doctor 的网络/TLS 行是你第一份证据。香港或新加坡的租用 Mac 主机对 doctor 本身并非必需。

架构：openclaw doctor 检查什么

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

文件与角色

Doctor 不能替代压测或 webhook POP 规划——那是 onboarding 后矩阵 的事。它能告诉你是否已经有理由怪模型供应商。

决策矩阵：崩溃类型 → 首条命令

推荐路径：若 shell 闪退，先交互式运行 doctor——不要通过 GUI 快捷方式调试。若 doctor 全绿但菜单栏 agent 仍显示 inactive，修 launchd 用户和端口，而不是 LLM API key。

六步 openclaw doctor 救援手册

Step 1 — 打开真实 shell（不要双击别名）

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

保存输出；跳过 login shell 的快捷方式会隐藏 PATH 修复。

Step 2 — 确认 Node 22+ 且 CLI 在 PATH 上

node -v
which openclaw
openclaw --version

通过标准：node 报告 v22 或更新；which openclaw 在 /opt/homebrew 或你文档化的全局前缀下返回单一路径。

Step 3 — 运行 doctor 并保存 transcript

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

将此文件附在任何支持工单上。每做一次修复后重跑——不要堆叠猜测。

Step 4 — 修复第一条 FAIL（通常是 PATH 或 config JSON）

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

若 JSON 失败，从备份恢复：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

Step 5 — 对齐 daemon 用户（gateway inactive 修复）

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

通过标准：交互式与 daemon 两份 transcript 一致，或每个差异都有文档说明。

Step 6 — 重启 gateway 并验证 status

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

通过标准：status 显示监听端口；doctor 无未解释的 FAIL 行。然后——且仅然后——再试 agent 或快捷方式。

对于仅 SSH 的租用主机，使用 远程 Mac SSH 工作流，除非文档化的 GUI 门禁明确要求，否则不要用像素级远程工具。

故障排查

错误模式：zsh: command not found: openclaw（或窗口秒关）

症状：脚本或 .app 包装器在 UI 出现前退出；doctor 从未运行。

修复：

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

在 launchd plist 的 EnvironmentVariables 中对齐相同 PATH（见 零小时契约）。

错误模式：gateway not active / ECONNREFUSED 127.0.0.1

症状：CLI 存在；UI 或 openclaw status 无法连本地 gateway。

修复：

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

若端口被其他用户占用，停止孤儿进程或修改 ~/.openclaw/openclaw.json 中的 gateway.port，然后重跑 doctor。Gateway 稳定后配置 速率限制——重试风暴感觉像崩溃。

FAQ

延伸阅读

• OpenClaw 零小时安装契约 — Node 22+ 纪律
• Onboarding 后 doctor + webhook POP — 回调入口
• OpenClaw 速率限制与预算告警 — 重试风暴 vs 崩溃
• 租用 M4 上的 OpenClaw + Ollama — 无云密钥的本地模型
• 远程 Mac SSH 安全工作流 — 仅 SSH 运维