AI / 自动化 2026年4月25日

2026-04-25 在租用的无头云端 Mac 上，OpenClaw doctor、CLI 配置与模型白名单：升级后排查

MacXCode 技术团队 2026年4月25日 约 17 分钟阅读

在 香港 / 日本 / 韩国 / 新加坡 / 美国 租用的 Mac mini M4 上，你通常 先 SSH，只有必须图形界面时才用 VNC。这正是 OpenClaw 针对的失败模式：长期存活的 gateway、JSON 形配置、以及 npm 快速迭代——你的 git diff 没动，生产仍可能因依赖收紧校验、迁移默认值或 模型白名单 变严而挂掉。这份 2026-04-25 手册是排查路径，不重复 出站与 DNS 或 首次安装与守护。它串联：openclaw doctor（与可选的 --fix）、CLI 管理 的键与手改文件的分工、如何证明 LaunchAgent 读到的 ~/.openclaw，以及如何避免「在交互式 ssh -t shell 里能跑、在 launchd 下挂掉」的经典坑。当 doctor 提示陈旧原生模块或重复 gateway 时，把 npm 与双重重启 写进回滚故事。

为何升级会在无头 Mac 上冒出「幽灵」问题

存在三套环境时钟：你的笔记本（PATH 丰富、.zshrc、HTTPS_PROXY 来自你忘了的 VPN）、自动化用的 类 CI SSH 会话、以及应对 守护进程 的 launchd 环境（这才是唯一应生效的那套）。在 npm -g 或带标签的 OpenClaw 发布之后，模式校验可能开始拒绝你四月以来一直带着的键；gateway 可能写出 第二份 PID 文件；或以往隐式的工具调用需要显式 审批/能力 且只在 verbose 日志里出现。把 就绪探针 当作对 127.0.0.1:18789 监听端口的快速筛子，而不是「整套人格配置仍一致」的证书——就绪必要，但不足以保证「各通道聊天都通」。

前 90 秒：先跑 openclaw doctor（与 --fix）

先做非破坏检查，再做可回滚的修复：openclaw status --all 打印版本、PID、监听端口与部件概览；openclaw doctor 校验模式、发现陈旧或冲突键、（视版本）引导到受支持路径；openclaw doctor --fix 在 CLI 能安全清理明显残留时使用——例如崩溃后过期的 ~/.openclaw/gateway.pid、或迁移器可重写的已弃用子键。在内部 wiki 中固化 顺序：先 kill -9 再 doctor 与先 openclaw gateway stop 再 doctor 输出会不同。若 doctor 报插件加载失败，请与生态里常提到的 WebSocket 1006 类错误对照；不要看到「另有 gateway 在监听」就停，还要排查旧装遗留的 clawdbot 类进程，社区已多次记录。

单一真相：CLI config 与磁盘上的 JSON

更倾向用 openclaw config set <key> <value> 与 openclaw config get <key>（随版本而异的表面）来改配置——很多团队因手改 ~/.openclaw/openclaw.json 多一个逗、或 UI 曾写入而 CLI 不再序列化的键而产生模式漂移。手改后务必再跑 doctor。热重载覆盖许多 agent/模型/提示 值，但 gateway.port 与 gateway.bind 仍值得按上游热重载约定做 完整 openclaw gateway restart，如同你只改了 nginx + Webhook 栈的一半时。密钥放在 ~/.openclaw/.env，通过已为 launchd 中的 API 密钥 使用的同一套 EnvironmentVariables 继承，而不是你在入职时 cat >> ~/.zshrc 写的一次性 export。

模型白名单：「不允许」常是策略，不是故障

当厂商重命名模型串，而你的技能仍引用 anthropic/claude-3-5-sonnet-latest、gateway 只放行固定列表时，错误会像凭证问题。检查有效白名单：openclaw config get agents.defaults.models（或你版本暴露的最近似项），让字符串与目标目录 完全一致——大小写、厂商前缀、插槽（主/备）都重要。与 出站 文互参：若错误在 TLS 与 HTTP/2 之后，是模型路由；若 TCP 都未完成，你要查 DNS/TLS。若你增加 cron 或子 agent 负载，它们不能落在你忘记合并的 更薄 的独立白名单上。为每个计划任务记录 实际解析的 模型，而不是你在 Slack 里打的易读标签。

Gateway、PID 文件与「我已经 kill 了」

两个监听器叠在一起时，常是 用户 LaunchAgent 重启而手工前台 进程仍占口，或升级留下被 launchd 收养的 子 Node。lsof -iTCP:18789 -sTCP:LISTEN 与 ps -ax | grep -i openclaw 要在 拥有 plist 的同一账户 上跑——不是 root。若必须强制结束，先按文档推荐的 有序 停止，再 doctor 后启动。这与 gateway 升级/回滚 矩阵配套：在工单模板里同时记下旧 PID、node 版本与 sidecar 原生构建用的 DEVELOPER_DIR，坏发布更容易现形。

合并不阻塞规则： 在可丢弃的 租用 预发机上升级后、CI 中跑通绿色 openclaw doctor 并保留 status --all 日志，胜过一张只证明手机端能看到 Telegram 的聊天截图。

症状 / 层次表（配置 vs 服务 vs 网络）

症状 层次 稳定化
小版本刚升完就出现「模型不在白名单」 配置策略 扩展白名单、固定字符串、在 debug 下单次对话重试
doctor 正常，shell 里新密钥仍 403 launchd 环境 / 出站 从运行中 PID 打印环境；再做出站 TLS 检查
加插件后 WebSocket 1006 Node 插件图 重跑 npm install，读 gateway stderr；对照 子 agent 笔记

把运维主链接起来：ClawHub 技能 规定你能自动化什么；结构化日志 让错模型与错路由看起来不同；当 100.64/ 与公网主机名是设计的一部分时读 Tailscale。若仍在冷启动，先看 安装与守护 前置文。同系列另一篇讲 CI 测覆盖率与门控：xcodebuild 测试、覆盖率与 JUnit 门限。

常见问题：共享构建机上的 doctor

问题 实务建议
是否每次发版前都要跑 doctor？ 至少 npm 变更与 gateway/二进制升级后跑；与周末聊天断连相比，它够快。
手改 JSON 可以接受吗？ 若合并上游示例——立刻 doctor + 对话烟测，而不是盲重启。
若香港区域比美国晚收到镜像？ 时间差正常；策略 与 出站 差异则不正常。用 租约 标签拆仪表盘，通过 各区域方案 扩容。

五区裸金属 M4 为何仍占优

诊断与 gateway 工作负载更在意 抖动 与 可重复 I/O 而非峰值算力。MacXCode 上的 Mac mini M4 提供单租 NVMe 保留冗长 JSON 日志、持久 SSH，并可在按国家拆分 provider 白名单时水平加节点。若 2026 年你要把 OpenClaw 与真正 的发布流水线一起跑，同一家族节点也能承担平台另一组手册中的 Xcode 测试 + 覆盖率 门限——把租约当成可用 p95 度量 的容量，而不是黑盒一直重启到绿。

在稳定、以 SSH 为先的 Mac 上运行 OpenClaw

港 · 日 · 韩 · 新 · 美 · 可选 VNC