环境清单 · doctor 诊断 · 报错对照表 · 可复现部署
正在装机或刚接 Channel 的开发者最常卡在「Gateway 起不来」而不是模型不够强：Node 版本、目录权限、.env 与 YAML 拼写、端口占用、代理与 DNS，任意一项都会在日志里放大成一整页红字。本文给你装机前环境清单、最小安装 vs 多通道增量对照表、六步诊断流程（含 openclaw doctor 思路）、高频报错对照表，以及迁到始终在线节点前的检查项。需要把常驻与 pm2 口径一次写全时，可对照站内 OpenClaw 全天候云端部署；若要一并规划远程算力与下单路径，可打开 租赁价格说明。
OpenClaw 的安装脚本通常不复杂，真正耗时的是把运行假设写清楚：谁在什么用户下启动 Gateway、配置文件从哪里读取、日志默认落在哪、哪些端口必须空闲、代理与 DNS 由谁维护。很多「Gateway 起不来」在根因上并不是 OpenClaw 本身，而是 Node 生态与 macOS 权限模型的组合题。下面五个缺口在 2026 年的社区讨论里反复出现，把它们写进 Runbook，能显著减少「重装三遍才发现是 PATH 问题」的挫败感。
如果你计划后续接 Slack、Telegram 等多通道，更要提前约定密钥轮换与最小权限目录，否则第一次接通道成功、第二次改 Token 时就会因为历史环境变量残留而排查困难。
Node 与包管理器版本漂移：OpenClaw 依赖现代 Node LTS；若机器上并存 nvm、fnm 与系统自带 node，很容易出现「终端里 node -v 正确、守护进程里却是旧版本」。装机前锁一条黄金命令行，并在 doctor 输出里核对实际进程使用的二进制路径。
工作目录与权限边界不清：把仓库 clone 到桌面或 iCloud 同步目录，可能触发权限或文件锁问题；生产路径应落在固定用户家目录下的专用子树，并明确哪些目录允许 AgentSkills 写入。
端口与防火墙默认假设：Dashboard 与 Gateway 监听端口若与本地其他服务冲突，进程会直接退出；Corporate 代理或本机防火墙也可能阻断出站 LLM API。装机前用一条端口扫描与一次 curl 出站自测写进清单。
配置文件多重来源：.env、shell Profile、launchd/pm2 环境块、YAML 覆盖层同时存在时，「以为改了其实没生效」极常见。约定单一真源：要么以 .env 为主并禁止 Profile 覆盖关键变量，要么以 YAML 为主并在文档写明优先级。
日志与可观测性空白：没有标准输出落盘路径、没有轮转策略，会在第一次长时间运行就把磁盘打满或把真正错误刷没。装机阶段就指定日志目录与保留天数，比事后补监控便宜一个数量级。
把上述清单勾完，再进入下一节的安装路径选择，你会更清楚自己是「只要一个最小 Gateway」还是「要接多通道的生产拓扑」。
很多团队第一次部署就把 Slack、邮件、Webhook 全部打开，结果排障矩阵爆炸。更稳妥的路径通常是：先让 Gateway 在最小配置下稳定启动并写出健康日志，再逐个增加 Channel Adapter，每次只改一个变量，失败时能快速回滚。下表对比两种常见第一阶段拓扑，便于你在评审会上对齐预期。
| 维度 | 最小安装（Gateway + 单通道或仅 CLI） | 多通道增量（2 个以上 Adapter） |
|---|---|---|
| 目标 | 验证进程、配置解析、LLM 出站与基础技能 | 验证消息路由、Token 轮换、并发会话隔离 |
| 配置面 | 环境变量少、YAML 层级浅 | 多份 Webhook/Token/签名密钥，错误面显著扩大 |
| 排障顺序 | 先看 Gateway 日志与 doctor，再看模型 API | 需区分 Channel 层错误与 Agent 层错误 |
| 回滚成本 | 低：注释一条通道即可对照 | 高：需保留分通道配置快照 |
| 适用人群 | 首次接触 OpenClaw 的个人与小团队 | 已有 Runbook、准备接生产的团队 |
先让「空载 Gateway」稳定，再接通道；顺序反了，你会在日志里同时看到三类错误，永远不知道哪一条是根因。
下列步骤刻意与「通道连不上」区分开：本节只解决进程级失败（启动即退出、配置无法解析、端口占用）。若进程已稳定运行而消息进不来，应在确认 Gateway 健康后再看各 Adapter 的 Webhook 与 Token。社区里常见的 openclaw doctor（或等价自检子命令）用于聚合环境与配置检查——若你的发行版命令名不同，把下面占位命令替换成官方 CLI 即可。
冻结复现命令：记录你是用 npm script、全局 CLI 还是 pm2 拉起；把完整命令与当前工作目录写进工单，避免「我明明换过目录但忘了」。
跑环境与配置自检：执行 openclaw doctor（或官方文档中的 doctor/fix 变体），保存完整输出；重点圈出 Node 路径、权限拒绝、缺失依赖与配置文件校验失败行。
分层验证配置文件：先用只读方式校验 YAML/JSON 语法，再核对环境变量是否被 shell Profile 注入旧值；单一真源策略在这里能省掉一半玄学问题。
检查监听端口与占用：用系统工具确认 Dashboard 与 Gateway 端口未被其他进程占用；Corporate VPN 有时会劫持本地回环策略，需要单独记录。
抓取启动后前 200 行日志：从第一次出现 ERROR 的行向上追溯上下文，而不是只截最后一行；很多根因在更早的警告里已被提示。
做最小回滚实验：临时禁用非必要 Channel 与第三方 AgentSkills，仅保留官方示例技能，确认能否启动；若可启动，再二分法逐个恢复插件定位元凶。
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
提示：doctor --fix 会改写本地配置；在生产节点执行前先做文件备份或走变更工单，避免自动修复与你的 intentionally 配置冲突。
下表覆盖安装与启动阶段最常见的「看起来像随机失败」的组合。请把表格当作一线值班速查卡：先按症状定位行，再执行优先动作；若三轮动作后仍失败，再回到第三节做完整日志抓取与二分回滚。
| 症状 | 可能原因 | 优先动作 |
|---|---|---|
| 启动立即退出，终端无栈 | Node 版本不满足或二进制路径不一致 | 对齐 nvm/pm2 使用的 node；重跑 doctor 核对 PATH |
| 提示无法读取配置或 YAML 报错 | 缩进/编码/合并冲突残留 | 语法校验；对比单一真源；从备份恢复最小配置 |
| 端口已被占用 | 旧进程未退出或其他服务占用 | lsof 查占用；改端口或结束僵尸进程后重启 |
| LLM 请求超时或 TLS 错误 | 代理、DNS、公司 MITM 证书 | curl 出站自测；配置 HTTPS_PROXY；导入信任链 |
| Channel 校验失败但进程存活 | Token 过期或 Webhook URL 不一致 | 轮换密钥；对照官方回调地址；勿与 Gateway 启动问题混排 |
| AgentSkill 执行报 EACCES | 目录权限或沙箱策略 | 修正目录属主；审查技能脚本是否需要额外授权 |
注意：不要在未确认进程模型的情况下反复执行 sudo npm install -g；全局包与项目本地依赖混用会让 doctor 报告「已安装」但运行时仍解析到错误路径。
安装排障与长期运行是两件相邻但不相同的事：前者追求可复现的最小路径，后者追求崩溃可恢复与可审计。下面三条参数常用于评审材料与值班交接，它们不替代官方文档，但能把「感觉不稳定」翻译成可测指标。
当你确认本地或办公室环境无法满足无人值守与弹窗零容忍时，迁云前的自检应额外包括：进程守护是否已验证重启策略、Dashboard 是否默认关闭公网、日志轮转是否启用。更完整的 pm2 与端口口径可直接复用站内 OpenClaw 全天候云端部署 一文中的生产条目。
安全提醒：即便只是安装阶段，也不要在公共聊天里粘贴完整 .env；用一次性密文通道或密钥管理器交付，并在 Runbook 写明吊销流程。
相比在个人笔记本上反复处理休眠、系统更新与多人共用会话带来的随机性，独占、可按地区部署的云 Mac 节点更容易把「装得起来」推进到「天天装得起来」。本地或借用设备在签名隔离与长期可用性上往往存在隐性天花板；对于要把 OpenClaw 与自动化工作流写进交付标准的团队，VpsMesh 的 Mac Mini 云端租赁通常是更优解：Apple Silicon 原生环境、7×24 在线、按周期弹性租用，让你把精力放回 Gateway 配置与业务逻辑而不是机器状态。