2026 OpenClaw 全网最完整安装与配置指南：从 0 到跑通的保姆教程

4. 按官方方式安装 OpenClaw

目的：用 OpenClaw 官方维护的安装入口，让 install.sh 自动处理 Node 与 CLI。来源：官方 Installation 文档（发布前请再核对是否有新版本号或额外参数）。

4.1 推荐：官方 install.sh（macOS / Linux）

curl -fsSL https://openclaw.ai/install.sh | bash

# 仅安装、稍后自行 onboard：
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

安装器会检测系统、按需安装 Node（文档推荐 Node 24，或 Node 22.19+），并安装 OpenClaw CLI。典型目录（以当前文档为准，发布前请再核对）：

• 用户配置：~/.openclaw/（含 openclaw.json5、secrets/、状态与日志）
• Gateway 默认端口：18789（本机 Control UI / WebSocket）
• macOS 后台：openclaw onboard --install-daemon 注册 LaunchAgent

4.2 初始化：onboard 向导

openclaw onboard --install-daemon

# 验证安装（官方推荐三连）：
openclaw --version
openclaw doctor
openclaw gateway status

向导会引导选择模型 provider、写入 API Key、配置 Gateway。切忌执行未知来源的安装脚本；不要把密钥提交到 git 或截图发到群聊。

4.3 安装后必做记录

source ~/.zshrc          # 或新开一个终端窗口
openclaw --version         # 记录版本号到笔记，便于日后排错
openclaw doctor            # 自动诊断缺失项；可加 --fix 尝试修复

通过标准：which openclaw 指向 PATH 中的 openclaw（常见为 npm 全局 bin）；openclaw doctor 无阻塞性 FAIL。失败先看：安装脚本最后 20 行日志 → PATH → 是否 Node 版本低于官方要求，或 PATH 未包含 npm 全局 bin openclaw 文件（应使用 venv 启动器）。

切忌：安装失败后不要立刻「删掉 ~/.openclaw 再装」——先保存终端输出与 openclaw doctor 结果，否则难以区分是网络问题还是权限问题。

5. 配置模型与 API Key

目的：让 OpenClaw Agent 能调用你选的 LLM provider。通过标准：非交互式冒烟收到合理回复；openclaw auth list 或 .env 中有对应项且不在 shell history 明文长期停留。

5.1 交互式配置（首次推荐）

openclaw onboard        # 交互式向导：模型、密钥、Gateway（可与 --install-daemon 合用）
# 密钥也可通过 auth-profiles / 环境变量注入，详见官方 Authentication 文档

5.2 环境变量与配置文件

主配置一般在 ~/.openclaw/openclaw.json5；密钥引用多在 ~/.openclaw/.env（用 openclaw config path、openclaw config env-path 确认实际路径）。示例（变量名以你所选 provider 的官方文档为准，勿照抄过期名称）：

# 示例：OpenRouter（请替换为你的 key，勿提交到 git）
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 或直接编辑 .env（chmod 600 ~/.openclaw/.env）
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

边界提示：模型价格、API 限额、地区可用性与隐私政策会随 provider 调整——上线前务必阅读其最新条款。本文不绑定某一固定模型名。

6. 工作目录、权限与日志

目的：装好后「可追踪、可限制、可回滚」。原则：最小权限——先只允许动测试目录，再逐步放开真实项目。

• 工作区：在 openclaw.json5 或会话中指定 ~/openclaw-lab；可在该目录放 AGENTS.md 描述允许的工具与边界（参见官方 Context Files 文档）。
• macOS 权限：若启用终端/文件类工具，系统可能提示「完全磁盘访问」——首次验收阶段可只授予测试目录相关权限，避免对整个磁盘放权。
• 日志目录：默认 ~/.openclaw/logs/（含 agent.log、errors.log、gateway.log）。用 openclaw logs list、openclaw logs errors --since 30m 查看。
• 密钥安全：chmod 600 ~/.openclaw/.env；备份 zip 不要放进同步盘；勿让 Agent 读取 ~/.ssh、支付或生产 kubeconfig。
• 后台运行（可选）：需要 Telegram/Discord 等网关时，用 openclaw gateway setup 与 openclaw gateway install；长期运维见本站OpenClaw 7×24 网关运维指南。

通过标准：对 Agent 说「只读写 ~/openclaw-lab」后，尝试访问主目录外路径应被拒绝或在日志中留下审计记录。

7. 打开 Dashboard 并验证 Gateway（端口 18789）

目的：确认 Control UI 与 WebSocket Gateway 正常。通过标准：本机 http://127.0.0.1:18789 可加载；openclaw gateway status 显示监听 18789。

openclaw gateway status
openclaw dashboard
# 浏览器也可直接访问：
# http://127.0.0.1:18789/

# 远程 Mac（SSH 转发，勿把 18789 裸露到公网）：
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# 端口占用排查：
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

失败先看：端口被占用 → lsof 结束冲突进程；Dashboard 空白但 status 正常 → 浏览器缓存或 WebSocket 被代理拦截；远程访问失败 → 是否只做 SSH 本地转发而非公网暴露。launchd：若 onboard 时加了 --install-daemon，重启 Mac 后应仍 openclaw gateway status 为 running；否则检查 LaunchAgent 日志与用户是否一致（详见本站 launchd 环境变量 一文）。

8. 首次运行验收：七步 Runbook

下面七步把「配置完成」推到「实战可用」的门槛——建议原样执行并保存输出截图或日志片段。

1. 诊断：openclaw doctor --fix → 无未处理 FAIL。
2. 模型 ping：openclaw agent --message "Reply with exactly: OPENCLAW_OK" → 回复含 OPENCLAW_OK。
3. 文件读：让 Agent 读取 ~/openclaw-lab/inbox/sample.txt 并复述首句。
4. 文件写：写入 ~/openclaw-lab/outbox/ping.txt → cat 可见。
5. 日志：openclaw logs errors --since 10m → 无新 ERROR（或已知可忽略项已记录）。
6. 关终端：关闭窗口，新开终端重复步骤 2 → 排除 PATH 仅当前 session 生效。
7. 可选重启：重启 Mac 后再跑步骤 2（若已装 gateway，再加 openclaw gateway status）。

可引用阈值（个人验收参考，非官方 SLA）：冒烟回复 < 60s；errors.log 10 分钟内 0 条未解释 ERROR；测试文件写入后 ls -la ~/openclaw-lab/outbox 可见新文件。

9. 跑通第一个实战案例：摘要 + 待办 + 可回滚输出

场景设计：在测试目录读取样本文本，生成中文摘要与 3 条待办，写入 Markdown，并保留回滚副本。该案例同时覆盖安装结果（CLI）、配置结果（模型）、真实 workflow（读→推理→写→日志）。

# 1. 准备输入（若第 3 节已创建可跳过）
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
本周完成：OpenClaw 安装文档草稿。
待跟进：配置 OpenRouter 预算告警；下周评估 gateway 接 Telegram。
风险：勿把 API Key 提交到 git。
EOF

# 2. 启动交互会话（或使用一条复合指令）
openclaw
# 在会话中发送（示例提示词）：
# 「请只使用 ~/openclaw-lab 目录。读取 inbox/weekly-notes.txt，
#   用中文写 150 字以内摘要 + 3 条待办，保存到 outbox/summary-and-todos.md，
#   并把原文件复制到 archive/weekly-notes.bak」

# 3. 非交互验收
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

通过标准：

• summary-and-todos.md 含摘要与 3 条待办，且与源文件语义一致。
• archive/ 下有备份，可用 diff 对比。
• 日志中有对应 tool call 记录；provider 账单/dashboard 有本次调用（便于核对成本）。

回滚：rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt。失败先看：模型是否因上下文截断未读完文件 → 权限是否拒绝写入 outbox → errors.log 中 tool 报错详情。

10. 常见问题排查：按层定位，避免盲目重装

发布前事实核对清单（维护者用）：官方 install.sh URL、最低 macOS、默认目录名、CLI 子命令、provider 环境变量名、日志路径——任一项变更都应先改文档再发布。读者侧只需记住：遇错先 openclaw doctor，再查 errors.log，最后才考虑重装。

11. 下一步怎么扩展：从测试目录到真实 workflow

验收通过后，建议按下面节奏扩展，不要一步接入生产仓库或支付系统：

1. 把单个真实 side project 目录加入白名单，仍禁止 ~/.ssh 与全局 * 读写。
2. 启用 openclaw cron 跑每日低风险任务（如整理下载文件夹清单——仍限测试目录）。
3. 配置一个消息网关（Telegram/Discord）并用配对模式限制陌生人（见官方 Security 文档）。
4. 建立 openclaw backup --quick 的每周节奏，再读长期维护文做升级与回滚演练。