第一次装 OpenClaw，卡住你的往往不是「不会复制命令」，而是不知道每一步在验证什么。终端没报错、Dashboard 能打开、模型能回答、文件能写入——这是四个不同检查点。本文按准备 → 安装 → 配置 → 权限 → Dashboard → 首次测试一条主线走完，失败时知道去哪看日志。
〇 这篇教程会帮你完成什么
跟完本文，你应能确认四件事：① CLI 与 Gateway 已安装；② 模型 provider 与 API Key 已连通；③ 浏览器能打开本机 Control UI；④ 在测试目录里完成一次低风险读写。目标不是「装上了」，而是「在可控范围内能工作，且出错能自查」。
一 安装前准备：Mac、网络与测试目录
做什么：在动手前把环境凑齐。为什么：缺一项会在中途反复试错。成功标志：你能打开终端、访问 官方安装文档，并已在桌面建好测试文件夹。
- 系统 — macOS（Apple Silicon 或 Intel 均可）。官方要求 Node 24（推荐）或 Node 22.19+；用官方安装脚本时会自动处理 Node，不必提前折腾 Homebrew（可选）。
- 网络与权限 — 能访问 openclaw.ai 与模型服务商；安装与写配置需要本机管理员密码（改系统设置、LaunchAgent 时）。
- 模型账号 — 在 Anthropic、OpenAI、OpenRouter 等任选一家注册，拿到 API Key（模型服务凭证，相当于密码，勿分享、勿提交 Git）。
- 测试目录 — 例如
~/openclaw-test，里面放一份notes.txt。工作目录即 Agent 允许操作的范围，第一次只开这里。
二 安装：只用官方来源，并保存输出
做什么：安装 OpenClaw CLI 与 Gateway。为什么：非官方包可能被篡改。成功标志：openclaw --version 有版本号。
Mac 推荐（会自动检测系统、安装 Node、启动引导）：
curl -fsSL https://openclaw.ai/install.sh | bash
若你已自行管理 Node，也可用：npm install -g openclaw@latest，然后执行 openclaw onboard --install-daemon（安装 macOS 后台服务 LaunchAgent）。
安装结束后请保存终端里的版本号与完整输出（截图或复制到备忘录），报错时对照官方 Troubleshooting。验证三连：
openclaw --version · openclaw doctor · openclaw gateway status
三 配置：provider、API Key 与配置文件
几个词先对齐（不展开成百科）：模型 provider 是哪家云服务（如 Anthropic）；API Key 是访问凭证；环境变量 是终端里的临时配置（如 export ANTHROPIC_API_KEY=...）；配置文件 是持久设置，默认在 ~/.openclaw/openclaw.json（JSON5 格式）；本地模型 指在本机跑 Ollama 等——新手第一次用云端 Key 即可，不必强行上本地推理。
运行引导向导（按提示选 provider、粘贴 Key、选默认模型）：
openclaw onboard --install-daemon
成功标志：openclaw doctor 无阻塞性报错；在 Dashboard 或 CLI 里发一句「你好」能收到模型回复。失败先查：Key 是否复制完整、账户余额/限额、本机代理是否拦截 HTTPS。
四 权限：第一次只开放测试目录
做什么：限制 Agent 能读写的路径，并谨慎对待 macOS 弹窗。为什么：全盘授权等于把整台 Mac 交给自动化工具。成功标志：测试任务只能在 ~/openclaw-test 内创建/修改文件。
系统设置里的「文件与文件夹」「自动化」「辅助功能」等名称会随 macOS 版本变化——以你屏幕上为准逐项核对。建议：
- 只勾选测试目录，不要一开始给「整个磁盘」或 iCloud 根目录。
- 日历、通讯录、屏幕录制等与首次跑通无关的权限先拒绝，需要时再开。
- 不要把 Gateway 端口暴露到公网；家庭网络保持本机或 VPN 访问即可。
五 打开 Dashboard：本机地址与远程 Mac
做什么：用浏览器打开 Control UI。为什么：可视化确认 Gateway 在跑、会话正常。成功标志：页面能加载且可发消息。
终端执行 openclaw dashboard，或浏览器访问官方默认地址 http://127.0.0.1:18789/（仅本机）。
| 现象 | 更可能原因 | 先做什么 |
|---|---|---|
| 无法连接 | Gateway 未启动 | openclaw gateway status，必要时 openclaw onboard --install-daemon |
| 本机能开、别的机器不行 | 只监听了 127.0.0.1 | 远程 Mac 用 SSH 转发：ssh -L 18789:127.0.0.1:18789 user@mac，再在本地浏览器打开上述地址 |
| 地址对仍白屏 | 浏览器缓存/插件 | 换 Safari 无痕窗口，或禁用广告拦截后重试 |
日志是排错证据：Gateway 异常时结合 openclaw doctor 输出与官方 Help / Troubleshooting 对照，不要凭感觉改配置。
六 首次运行：低风险测试任务
在 ~/openclaw-test/notes.txt 写两行字，例如「项目代号：Alpha」。在 Dashboard 或 CLI 发送：
请读取 openclaw-test 目录下的 notes.txt，用三句话总结，并把 summary.md 写在同一目录。
算跑通的标准：① 模型回复内容与文件一致；② 目录里出现 summary.md；③ openclaw doctor 仍正常；④ 日志里有对应请求记录（非空）。若写入失败，先看 macOS 是否拒绝文件访问，而不是先怀疑模型「变笨」。
七 新手常见错误速查
command not found
PATH 未包含 npm 全局 bin → 改 ~/.zshrc 后重开终端。
API Key 无效 / 401
重新生成 Key，确认 provider 与 onboard 选项一致，检查是否多了空格。
Dashboard 打不开
先 gateway status，再查端口与是否用错机器（本机 vs 远程）。
权限拒绝 / 写不进文件
系统设置 → 隐私与安全性 → 给终端或 OpenClaw 相关进程开测试目录，勿全盘授权。
测试案例通过后，再逐步接入真实项目目录、Telegram/Slack 等频道、日历或提醒事项。每扩一步，重复「小范围试 → 看日志 → 再放大」。
- 1把允许目录从测试文件夹扩到一个真实但非生产的 repo
- 2在
openclaw.json里加频道白名单（如allowFrom） - 3需要 24/7 时确认 LaunchAgent 开机自启，定期
openclaw doctor
八 在 Mac mini 上跑 OpenClaw 更省心
OpenClaw 是自托管 Gateway：要长期在线、又要控制权限边界，放在主力 MacBook 上容易和日常办公抢资源。Mac mini M4 体积小、待机功耗约 4W 级、适合静默 24/7；macOS 原生 Unix 环境让官方安装脚本、LaunchAgent 守护与 SSH 远程维护都更顺；Gatekeeper、SIP 与 FileVault 也便于把 Agent 限制在专用账户与测试目录里。若你打算把 OpenClaw 当成家庭或小团队的常驻节点，Mac mini M4 是目前性价比很清晰的硬件起点——先在本机跑通测试案例，再把它迁到专用 Mac mini 上长期运行。
OpenClaw 常驻 · 低功耗 24/7获取 Mac mini，搭建你的 OpenClaw 节点
分钟级开通 · 远程 SSH · 稳定网络 · 适合自托管 AI Gateway 与 Dashboard 长期运行。