安装路径选择：一键脚本 vs npm 全局安装 vs git 开发安装
OpenClaw 的安装方式有三种，各自的适用场景与注意点如下：
一键安装脚本（推荐路径）：执行 `curl -fsSL https://openclaw.ai/install.sh | bash`。脚本会自动检测 Node.js 版本（需 ≥ 22），如未安装则提示安装；随后通过 npm 全局安装 openclaw CLI；最后自动启动 onboarding 向导。适合绝大多数想在干净系统快速上手的用户。
npm 全局安装：`npm install -g openclaw@latest` 后手动运行 `openclaw onboard`。适用于已具备 Node 22+ 环境、或需要在 CI/CD 脚本中自动部署的场景。优势在于可精确控制版本与安装参数。
git 开发安装：从 GitHub 克隆源码后 `npm install`，适合需要修改核心逻辑或参与社区开发的进阶用户。注意：开发模式不自动注册 daemon，需手动执行 `openclaw onboard --install-daemon`。
无论选择哪种方式，必须在安装完成后立即运行 `openclaw onboard --install-daemon`，否则 Gateway 仅在当前终端会话内运行，重启后丢失。
Gateway 服务化：systemd / LaunchAgent / Windows 计划任务
`--install-daemon` 会在不同平台注册对应的用户级服务，确保持久化运行：
| 平台 | 服务类型 | 验证命令 | 管理命令 |
|---|---|---|---|
| Linux (systemd) | 用户级 systemd unit | `systemctl --user is-enabled openclaw-gateway.service` | `systemctl --user start|stop|restart openclaw-gateway` |
| macOS (launchd) | LaunchAgent plist | `launchctl list | grep openclaw` | `launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist` 再 `load` |
| Windows (WSL2) | 计划任务（Scheduled Task） | `schtasks /Query /TN "OpenClaw Gateway"` | `schtasks /Run /TN "OpenClaw Gateway"` |
关键注意点：
用户级而非系统级：OpenClaw daemon 默认以当前用户身份运行，不需要 root。使用 `systemctl --user` 而非 `sudo systemctl`；root 级命令找不到该服务。
端口 18789 占用检查：若 Gateway 启动失败，常见原因是端口被占用。执行 `lsof -i :18789`（macOS/Linux）或 `netstat -ano | findstr :18789`（Windows）定位并终止占用进程。
状态目录位置：默认 `~/.openclaw/`。若需自定义，通过环境变量 `OPENCLAW_STATE_DIR` 指定；禁止放在 iCloud、Dropbox 等云同步目录，会导致锁竞争与数据不一致。
Windows WSL2 特别说明：WSL2 中安装需确保 Node.js 在 WSL 环境内，且使用 `openclaw onboard --install-daemon` 会创建 WSL 用户级 service。外部访问需在 Windows 防火墙放行 18789 端口或通过 SSH 隧道。
配置基线：gateway.bind、gateway.auth 与状态目录
安装后首次运行 `openclaw onboard` 会生成 `~/.openclaw/openclaw.json`。以下是必须核验的基线配置字段：
gateway.bind（绑定地址）：默认 `127.0.0.1`（loopback），仅本机访问。若需从外网访问（如将 Gateway 放在 VPS），必须改为 `0.0.0.0` 或具体 IP，并同步配置鉴权。注意：绑定非 loopback 地址时若未设置 token/password，Gateway 会拒绝启动（安全保护）。
gateway.auth（鉴权方式）：支持 `token` 或 `password`。Token 模式下，通过 `openclaw config set gateway.auth.token
OPENCLAW_STATE_DIR（状态目录）：存放数据库、会话与技能缓存。生产环境建议放在本地 SSD，禁止挂载云同步盘（OneDrive、iCloud、Dropbox 等），会导致并发写入冲突与数据损坏。可通过环境变量或 config 中 `state.dir` 指定。
gateway.port：默认 18789。若该端口被占用，可通过 `openclaw gateway --port
健康检查阶梯：status → logs → doctor → channels probe
当 Gateway 行为异常时，按以下顺序逐层检查，避免盲目重启：
openclaw gateway status：查看 Gateway 进程状态（running/stopped/error）、监听地址与端口、已连接通道列表。若显示 `disconnected` 或 `unauthorized`，进入下一步。
openclaw logs --follow：实时日志流。重点关注 ERROR 与 WARN 级别的消息，常见线索包括：端口绑定失败、config key 错误、鉴权失败、通道连接被拒。日志位置也可直接查看 `~/.openclaw/logs/` 目录。
openclaw doctor：自动健康诊断工具。检查项包括：Node 版本、端口可用性、配置文件语法、state dir 权限、API 密钥有效性、通道配对状态。doctor 输出通常包含可执行的修复命令建议。
openclaw channels status --probe：通道级探測。列出所有已配置通道（Telegram、Discord 等）的连接状态、配对请求、消息发送成功率。若通道显示 `pairing required` 或 `disconnected`，需重新执行配对流程。
该阶梯的核心思想是先服务层（gateway status）→ 再日志层（logs）→ 然后配置层（doctor）→ 最后业务层（channels），层层递进，避免在错误层面浪费时间。
常见故障恢复清单：端口、环境变量、config key 漂移等
以下是高频故障场景与对应的修复步骤，可按表排查：
Gateway 启动失败：端口 18789 被占用：执行 `lsof -i :18789` 定位占用进程 PID，`kill -9
Daemon 未自启（ reboot 后未运行）：验证服务是否注册：`systemctl --user is-enabled openclaw-gateway.service`（Linux）或 `launchctl list | grep openclaw`（macOS）。如未注册，重新执行 `openclaw onboard --install-daemon`。
环境变量未加载：若通过 systemd/LaunchAgent 启动，确保必要环境变量（如 `ANTHROPIC_API_KEY`）已配置在服务单元文件中，或写入 `~/.config/environment.d/`。手动启动正常但 daemon 启动失败时，优先检查此点。
升级后 config key 漂移：OpenClaw 2026.4.x 将 `gateway.token` 重命名为 `gateway.auth.token`，将 `gateway.mode` 的默认值从空调整为需显式设置。升级后运行 `openclaw doctor` 查看迁移建议，或手动编辑 `openclaw.json` 对齐新 schema。
非 loopback 绑定却无鉴权：当 `gateway.bind` 设为 `0.0.0.0` 或外网 IP 时，必须同时设置 `gateway.auth.token` 或 `gateway.auth.password`，否则 Gateway 拒绝启动并提示 "non‑loopback binding requires authentication"。
通道配对失效（Token 过期/ Bot 被删）：进入 Control UI (http://127.0.0.1:18789) → Devices 页面，删除失效设备后重新 `openclaw onboard` 完成配对；或使用 `openclaw pairing list --channel
Docker 部署的 bind 模式陷阱：官方 Docker 配置中 `gateway.bind` 应使用 `lan`（内网）而非 `localhost` 或 `0.0.0.0`；若容器内通过 `172.x.x.x` 访问，需重置 `openclaw config set gateway.bind lan` 并重启容器。
注意：任何修改配置后，优先使用 `openclaw gateway restart` 重启服务；若无效，使用 `systemctl --user restart openclaw-gateway`（Linux）或 `launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway`（macOS）强制重新加载。
可能原因：① 未运行 `openclaw onboard --install-daemon`，Gateway 仅在当前会话存活；② Node.js 版本 < 22，需先升级；③ 端口 18789 被占用。解决：依次执行 `openclaw onboard --install-daemon` → `openclaw gateway status` → `openclaw doctor` 诊断。
先运行 `openclaw doctor`，它会提示 config 迁移（如 `gateway.token` → `gateway.auth.token`、`gateway.mode` 需显式设置）。按建议修改 `~/.openclaw/openclaw.json` 后，执行 `openclaw gateway restart`。若仍无效，用 `systemctl --user restart openclaw-gateway` 强制重载服务单元。
云上 Mac（如 MESHLAUNCH 裸金属节点）可提供 7×24 在线、免睡眠、低延迟、易于公网暴露（配安全组与反代）的环境，适合作为常驻 Gateway 宿主。与本地 Mac 相比，避免了家庭网络 ISP 波动、设备休眠、电力中断等问题，是生产环境推荐架构。详情可见 价格页。
Windows 原生安装需用 PowerShell 脚本 `iwr -useb https://openclaw.ai/install.ps1 | iex`；建议使用 WSL2（Ubuntu）以获得与 Linux/macOS 一致的行为。daemon 会注册为 Windows 计划任务，需以管理员权限运行首次 onboard。更多环境变量与路径问题参考官方文档。
替代方案的局限：仅依赖本地 Mac 跑 Gateway 会受睡眠、网络波动、家庭宽带 IP 变更等影响；仅用 Docker 但未配置持久化 volume 会导致状态丢失；单纯用手动启动忘记加入开机自启，必然导致服务中断。对于更稳定、更适合 AI Agent 自动化的生产环境，MESHLAUNCH 的 Mac Mini 云端常驻节点配合正确的服务化配置（systemd/LaunchAgent）与鉴权策略，是保障 Gateway 7×24 可用的更优解。