照着清单装 OpenClaw：2026 全流程安装配置 Checklist 保姆教程
如果你想边装边确认 OpenClaw 到底有没有装好，不要只看终端最后一行。完整安装至少要过七个检查点：环境、安装、初始化、模型、权限、Dashboard、首次任务。本文把 2026 OpenClaw 安装与配置写成可执行 checklist——任何一项没通过，先停在当前层排查，而不是继续往下做。
等所有检查项通过，再把 OpenClaw 接入真实目录、账号或自动化流程，风险会低很多。先行结论：OpenClaw 的关键不是「装上」，而是每个检查点都可验证；跳过模型、权限、端口或日志检查，后面很容易把「SSH 没转发」误判成「Gateway 挂了」。
下文每条清单采用统一格式：检查项 → 为什么重要 → 通过标准 → 失败先查。命令与路径以 OpenClaw 官方安装文档 为准；发布前请在你本机再跑一遍 openclaw --version 核对版本差异。安装路径选型可参考本站 install.sh、npm 与 Docker 对比文。
先看总清单：七块验收地图
按顺序勾选。某一阶段未通过时，不要进入下一阶段。
| 阶段 | 核心验收 | 关键命令 / 路径 |
|---|---|---|
| ① 安装前 | Node 22+、端口 18789 空闲、测试目录与密钥就绪 | node --version、~/openclaw-workspace |
| ② 安装 | CLI 可用、来源为官方、安装日志无致命错误 | openclaw --version、which openclaw |
| ③ 初始化与模型 | onboard 完成、provider/API Key、默认模型可调用 | openclaw onboard、~/.openclaw/openclaw.json |
| ④ 权限与安全 | 最小工作目录、密钥不入库、Dashboard 不裸暴露 | agents.defaults.workspace |
| ⑤ Dashboard 与服务 | 本机/SSH 转发可访问、Gateway 监听、launchd 正常 | 127.0.0.1:18789、openclaw gateway status |
| ⑥ 首次实战 | 模型回复、文件读写、日志可追溯、可回滚 | 测试目录内 sample.txt |
| ⑦ 交付与维护 | 版本、配置、日志、入口、回滚方式已记录 | openclaw doctor、交付表（见文末） |
1. 安装前检查
在复制任何 curl | bash 之前完成下表。官方安装器会检测系统并可能自动安装 Node；你仍应提前确认硬件与网络，避免装到一半才发现端口被占或 provider 账号未开通。
| ☐ | 检查项 | 为什么重要 | 通过标准 | 失败先查 |
|---|---|---|---|---|
| ☐ | macOS / 芯片 / 内存 | Gateway、本地模型与 Skills 都吃内存；内存不足会 swap 拖垮响应 | Apple Silicon 或 Intel Mac；建议 ≥16GB 统一内存；磁盘预留 ≥10GB | 换轻量模型、关本地 Ollama、或升级机器 |
| ☐ | node --version |
OpenClaw CLI 基于 Node；版本过低会导致安装或 onboard 失败 | 输出 v22.x 或更高（以当前官方文档为准） | nvm/fnm 切换版本；或让官方 install.sh 自动装 Node |
| ☐ | 端口 18789 空闲 | Dashboard / Control UI 默认监听 18789；冲突会导致「装完打不开」 | lsof -nP -iTCP:18789 -sTCP:LISTEN 无输出，或确认为旧 OpenClaw 实例 |
结束占用进程；或 openclaw config set gateway.port <新端口> |
| ☐ | 网络与官方源 | 安装脚本、npm 与 LLM API 都依赖外网；公司代理常导致半截失败 | curl -I https://openclaw.ai 与所选 provider 域名可达 |
代理、DNS、防火墙；勿使用来历不明的第三方一键脚本 |
| ☐ | Provider 账号与 API Key | 没有可用模型，后面所有「任务成功」都是假象 | 已在 provider 控制台创建 Key；余额/限额/地区可用性已自行核对（不写死数字） | 控制台账单、模型 ID 拼写、组织策略 |
| ☐ | 专用测试目录 | 首次任务必须在隔离目录跑，避免误改真实项目 | mkdir -p ~/openclaw-workspace && echo ok > ~/openclaw-workspace/sample.txt |
路径权限、磁盘只读卷 |
| ☐ | 备份旧配置（若有） | 重装或升级可能覆盖 ~/.openclaw |
tar czf ~/openclaw-backup-$(date +%Y%m%d).tgz ~/.openclaw 2>/dev/null || true |
备份路径空间、是否误打包进 git |
2. 安装过程检查
推荐两条官方路径（二选一，不要混用后不记来源）：
- 一键脚本：
curl -fsSL https://openclaw.ai/install.sh | bash - npm 全局：
npm install -g openclaw@latest，然后openclaw onboard --install-daemon
若只要安装、稍后再向导：curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard。安装输出请保存到 ~/openclaw-workspace/install.log，便于排错。
| ☐ | 检查项 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 命令来源 | 脚本域名为 openclaw.ai；npm 包名为 openclaw；which openclaw 指向预期 prefix |
PATH 冲突、多版本 Node、旧别名 |
| ☐ | CLI 版本 | openclaw --version 输出版本号且无 command not found |
重装 npm 全局；SSH 非登录 shell 的 PATH |
| ☐ | 配置目录生成 | ls ~/.openclaw/openclaw.json 存在（onboard 后） |
是否跳过 onboard；OPENCLAW_CONFIG_PATH 自定义路径 |
| ☐ | 双栈版本一致 | CLI 与 ~/.openclaw/lib 时间戳/版本策略不冲突（大版本升级后必查） |
见本站 CLI 与 Gateway 版本不一致 文 |
| ☐ | 官方三联验证 | openclaw --version → openclaw doctor → openclaw gateway status 均可执行 |
doctor 输出项；daemon 是否安装 |
3. 初始化与模型配置检查
运行 openclaw onboard --install-daemon（或安装脚本自动触发的向导）。--install-daemon 会在 macOS 注册 LaunchAgent（默认 label 常为 ai.openclaw.gateway），让 Gateway 在重启后仍可用。
| ☐ | 检查项 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | Provider 与 API Key | Key 写入 secrets/环境变量，未出现在 shell 历史或 git；openclaw doctor 无鉴权类 WARN |
变量名、Key 过期、地区限制 |
| ☐ | 默认模型 | openclaw config get 相关模型键与向导选择一致；试发一条最小 prompt 有 token 消耗或等价成功响应 |
模型 ID、配额 429、provider 故障页 |
| ☐ | 本地模型（可选） | 若用 Ollama：本机 ollama list 含目标模型；OpenClaw 路由指向本地 endpoint 且延迟可接受 |
Ollama 未启动、端口、内存 OOM |
| ☐ | 工作区 workspace | agents.defaults.workspace 指向 ~/openclaw-workspace（或你登记的测试目录） |
配置合并顺序、多 profile 冲突 |
| ☐ | Gateway 认证 | 默认要求 token/密码（gateway.auth.* 或环境变量）；未使用空认证暴露端口 |
openclaw doctor --generate-gateway-token（若文档支持）；重新 onboard |
4. 权限与安全检查
OpenClaw Gateway 属于高权限长期进程。安装阶段就应收敛边界，而不是等出事再改。
| ☐ | 检查项 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 最小工作目录 | 未把 workspace 设为 ~ 或公司主仓库根；工具写文件仅在测试目录可见 |
改 workspace；exec 审批策略 |
| ☐ | macOS 系统权限 | 仅授予 Skills 必需项（辅助功能、文件、自动化等）；无头机避免依赖桌面钥匙串弹窗 | TCC 数据库、换文件型密钥 |
| ☐ | 密钥存放 | ~/.openclaw 权限为当前用户可读；.gitignore 排除 openclaw 配置；永不提交 API Key |
误提交 → 立即轮换 Key |
| ☐ | 端口暴露 | gateway.bind 为 loopback（127.0.0.1）或等价；公网访问必须经 SSH 转发 / 零信任 / 反代 + 认证 |
误绑 0.0.0.0；防火墙规则 |
| ☐ | 日志脱敏 | openclaw logs --follow 抽样检查无完整 Key/token；分享日志前人工脱敏 |
调高日志级别前先确认脱敏策略 |
5. Dashboard 与服务检查
Dashboard（Control UI）默认在 http://127.0.0.1:18789。端口解析顺序一般为：--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789。远程 Mac 上装完向导，在笔记本浏览器直接打开 127.0.0.1 会连到笔记本自己——需要 SSH 转发。详细排错见 Dashboard 18789 + SSH + doctor + launchd。
| ☐ | 检查项 | 通过标准 | 失败先查 |
|---|---|---|---|
| ☐ | 本机监听 | lsof -nP -iTCP:18789 -sTCP:LISTEN 有进程；curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/ 返回非 000 |
openclaw gateway restart；端口占用 |
| ☐ | Gateway 状态 | openclaw gateway status（可加 --deep）显示运行中；openclaw doctor 无未修复 CRITICAL |
doctor --fix；配置 reload 失败 |
| ☐ | SSH 远程访问 | 笔记本执行 ssh -N -L 18789:127.0.0.1:18789 user@remote-mac 后，本地浏览器可开 Dashboard |
SSH 主机是否选对、本地 18789 是否已被占 |
| ☐ | launchd 后台 | launchctl list | grep -i openclaw 中 Gateway label 退出码为 0；plist 内 PATH 含 node/openclaw |
openclaw gateway install；bootout/bootstrap 重复注册 |
| ☐ | 日志流 | openclaw logs --follow 在发起一次测试请求后能看到对应条目 |
日志路径配置、磁盘满 |
6. 首次实战检查
在 ~/openclaw-workspace 完成一次端到端任务，验证「模型 + 工具 + 文件 + 日志 + 回滚」闭环。
- 测试输入：在 Dashboard 或 CLI 发送：「读取
sample.txt，写一份 3 条要点摘要到summary.md，不要访问其他目录。」 - 通过标准：
summary.md生成且内容合理；openclaw logs能对应到该次会话；provider 控制台可见本次调用（若有计费）。 - 回滚：
rm ~/openclaw-workspace/summary.md或git checkout -- .（若目录在 git 内）；确认 agent 未在 workspace 外留下文件。 - 失败先查：模型层（401/429）→ 权限/workspace → Gateway 是否重启 → 日志中的 tool denied。
7. 失败项排查索引
某一项打叉时，按 symptom 回到对应层，避免在 Dashboard 层狂改配置，其实根因是 API Key。
| 现象 | 先回到哪一层 | 首要动作 |
|---|---|---|
command not found: openclaw |
② 安装 | 查 PATH、npm prefix、launchd 环境变量 |
| doctor 报配置/鉴权 WARN | ③ 模型/配置 | openclaw doctor 按提示修复；检查 ~/.openclaw/openclaw.json |
| 0 tokens / 模型无响应 | ③ 模型 | 验证 Key、模型名、provider 状态页 |
| Dashboard 连不上 | ⑤ 服务/网络 | 远端 curl 127.0.0.1:18789；SSH -L；是否误绑 loopback |
| RPC probe failed / 端口占用 | ⑤ 服务 | lsof -i :18789；openclaw gateway --force（调试时） |
| 重启后 Gateway 不起来 | ⑤ launchd | launchctl list；openclaw gateway install；Console 崩溃日志 |
| CLI 新、Gateway 旧 | ② 安装 + ⑤ 服务 | 同步 ~/.openclaw/lib 与 npm；冷重启 LaunchAgent |
8. 安装完成交付清单
团队交接或一个月后你自己回来看，靠这张表就能快速恢复上下文（请把敏感项存密码管理器，表中只写「已配置」）。
| 交付项 | 记录内容（示例） |
|---|---|
| 版本 | openclaw --version 输出；安装日期 2026-05-27 |
| 配置位置 | ~/.openclaw/openclaw.json；若有 OPENCLAW_CONFIG_PATH 写绝对路径 |
| 日志位置 | openclaw logs 指向路径；launchd StandardOutPath（若自定义 plist） |
| 访问入口 | 本机 http://127.0.0.1:18789；远程 ssh -L 18789:127.0.0.1:18789 … |
| 测试目录 | ~/openclaw-workspace |
| 回滚方式 | 配置备份 tgz 路径；openclaw gateway stop；移除 LaunchAgent label |
9. 完成后的维护清单
- ☐ 大版本升级前：
tar备份~/.openclaw，升级后跑openclaw doctor+openclaw gateway restart - ☐ 每月：在 provider 控制台核对用量与限额；轮换长期 API Key
- ☐ 日志轮转：避免
~/.openclaw撑满磁盘；按需归档openclaw logs输出 - ☐ 安全：禁止将 18789 直接映射到公网；定期
openclaw security audit（若版本提供） - ☐ 变更后复验：重复本文「⑤ Dashboard」+「⑥ 首次实战」各一项
全部阶段打勾后，再接入 Telegram/Slack、Skills 链或 CI。若需官方 App 与 CLI 双网关并存，继续读 macOS 官方 App 与 Gateway 外置决策表。
在 Mac mini 上按清单验收，更稳也更安静
OpenClaw 的 Gateway、LaunchAgent 与 Dashboard 都偏爱长期在线、低抖动的环境。macOS 原生支持 launchd、Unix 工具链与 SSH 端口转发，无需 WSL 即可按本文清单逐项打勾；Apple Silicon Mac mini 待机功耗可维持在很低水平，适合作为 7×24 的 agent 节点，把试错限制在 ~/openclaw-workspace，与主力 MacBook 的个人数据隔离。
同价位小型 PC 往往风扇与功耗更高，而 macOS 的 Gatekeeper、SIP 与 FileVault 能降低恶意软件与误配置风险。若你正按 checklist 安装 OpenClaw，Mac mini M4 是目前性价比很高的专用主机——现在即可入手，让清单里的端口监听、doctor 与首次任务在稳定硬件上一次性通过。