OpenClaw Mac 安装详细教程：macOS 零基础 CLI Onboarding 看图操作版
这篇文章属于 OpenClaw 的 macOS 新手安装细化篇
如果你想看最细的 Mac 安装步骤，这篇最适合；如果你想回到整个系列的总入口，可以先去专题页，再按自己的阶段继续往下看。
本文按 2026 年 4 月 1 日可查到的 OpenClaw 官方 Getting Started、Onboarding Wizard、Dashboard、FAQ 与 doctor 文档整理。由于不同版本的界面文字可能略有变化，本文采用“看到什么就选什么”的写法，并结合实际截图，把每一步都尽量讲到零基础也能照着点。
先说结论：Mac 新手第一次安装，最稳的路线只有这一条
如果你是第一次接触 OpenClaw，不要一开始就研究 Docker、源码安装、Telegram、Tailscale 或公网访问。
最稳的顺序是：
- 用官方安装脚本安装
OpenClaw - 运行
openclaw onboard --install-daemon - 按向导把本地 Gateway 配好
- 用
openclaw gateway status确认服务正常 - 用
openclaw dashboard打开浏览器并完成第一次聊天
先把这 5 步跑通，你后面再接手机聊天渠道、做远程访问、配技能和自动化，排错难度都会低很多。
这篇教程适合谁
这篇文章特别适合下面这几种情况：
- 你用的是
macOS - 你几乎没有命令行经验
- 你想按官方推荐方式先把 OpenClaw 装起来
- 你不想一上来就接 Telegram、Discord 或 WhatsApp
- 你想要的是“每一步点什么、输什么、看到什么算正常”
如果你现在的目标只是“先在这台 Mac 上把浏览器聊天跑通”，那这篇就是最适合你的版本。
开始前要准备什么
正式开始前，你只需要准备 3 样东西。
1. 一台能正常联网的 Mac
- 建议你使用自己的管理员账号
- 安装过程中可能会弹出系统权限确认
- 网络需要能访问 OpenClaw 官方安装脚本和你使用的模型服务
2. 一个可用的模型 API Key
OpenClaw 本身不是模型提供商，它只是 Gateway 和控制层。
所以你至少要准备一种可用的模型接入方式。
对零基础新手来说，第一次最省事的是：
- 你已经有
OpenAI API Key - 或者你已经有
Anthropic API Key
如果你没有 API Key，也不是完全不能安装，但最后大概率会卡在“界面能打开，却聊不起来”。
3. 一个打开终端的方法
按下面操作：
- 键盘按
Command + Space - 输入
Terminal - 回车打开
后面的命令都在这个窗口里执行。
第一步：运行官方安装命令
把下面这条命令完整复制到终端里，然后回车：
1 | curl -fsSL https://openclaw.ai/install.sh | bash |
这是截至 2026 年 4 月 1 日，官方 Getting Started 页面给出的 macOS / Linux 快速安装命令。
这一步正常会发生什么
安装脚本运行后，你可能会看到这些提示：
- 检测系统环境
- 检测
Node - 检测
Git - 检测或安装
Homebrew - 检测或安装
OpenClaw CLI
只要没有看到明确的报错中断，就继续等它跑完。
Node 版本要不要自己先装
官方当前文档里写的是：
Node 24为推荐版本Node 22.14+仍支持
对新手来说，最简单的做法不是自己先折腾 Node，而是让安装脚本自动处理。
第二步：如果没有自动进入向导，就手动启动 onboarding
如果安装脚本跑完后没有自动进入新手引导，就手动执行：
1 | openclaw onboard --install-daemon |
这条命令的作用是：
- 打开官方推荐的 CLI onboarding 向导
- 让你选择模型、Gateway 和工作区
- 顺便把后台服务也装好
你可以把它理解成“把 OpenClaw 真正配置成可用状态”的那一步。
先看懂向导怎么操作
很多新手第一次看到这个界面，会先被它的终端样式吓到。其实它的操作非常简单：
↑↓：上下移动到别的选项←→：在同一行里切换Yes / NoSpace：勾选或取消勾选Enter：确认当前选择并继续- 绿色圆点或高亮项：就是你现在选中的那个
你不用懂命令行原理，只要记住一句话：看到哪一屏，就把光标移动到本文说的那个选项，再按回车。
第三步：按这次实拍截图的顺序，一屏一屏这样选
下面这组截图，基本就是一次完整的 macOS QuickStart onboarding 流程。
我直接按截图出现的顺序来讲，这样你最容易照着走。
1. 看到安全提醒页：选 Yes
这一屏的意思不是“你装错了”，而是在提醒你：
- OpenClaw 默认更适合个人使用
- 如果你要做多人共享，后面要把安全设置再收紧
- 官方建议定期跑安全检查
对大多数第一次安装的新手来说，这里直接选：
Yes
这样选的前提是：
- 这是你自己的 Mac
- 你现在只是想先本地跑通
- 你没有打算马上把它暴露给公网或多人共用
如果你本来就打算做团队共享入口，那这一步先别急着继续，应该先认真看完官方安全文档再配置。
2. 看到 Setup mode：选 QuickStart
这一屏直接选：
QuickStart
不要选：
Manual
原因很简单：
QuickStart就是官方给新手准备的默认路线- 它会优先帮你把最基本的本地可用状态跑通
- 你后面真想改高级参数，再用
openclaw configure回来改也不晚
如果你现在的目标只是“先装好、先能聊”，那 QuickStart 几乎就是标准答案。
3. 看到 Model/auth provider：选你手里已经有 Key 的那家
这一步最重要，不要机械照抄截图里的厂商名称。
图里选中的是：
Anthropic
但你真正应该选的是：
- 你有
Anthropic API Key，就选Anthropic - 你有
OpenAI API Key，就选OpenAI - 你明确自己在用别的 provider，才选对应那一项
第一次安装最省心的原则只有一个：
- 选你现在已经能拿出有效凭证的那个提供商
选完以后，向导一般会继续让你填写或确认 API Key。
你就把自己的 Key 粘进去即可。
如果你现在没有任何 Key，也可以继续安装，但要提前知道：后面大概率只能打开界面，没法真正正常聊天。
4. 看到 Select channel (QuickStart)：第一次本地安装先选 Skip for now
这一屏最容易让新手走偏。
图里当前光标停在：
Zalo (Personal Account)
但这不代表你第一次安装就应该选它。
它只是说明这份截图截到的时候，列表正好滚到了这一段。
如果你现在的目标只是：
- 先把这台 Mac 的本地浏览器聊天跑通
那你应该做的是：
- 继续往上或往下找
- 找到
Skip for now、None、No channel之类的选项 - 选那个跳过渠道配置的选项
第一次不要急着接：
TelegramDiscordSlackWhatsAppZalo- 其他任何外部聊天渠道
因为你现在最需要先确认的是：
- OpenClaw 已经装好
- Gateway 确实在跑
- 浏览器聊天先成功
只要本地最小闭环先跑通，后面你再回来加渠道，排错会轻松很多。
5. 看到 Web search：按“先跑通聊天，再补搜索”的原则选
这一屏不同版本的 onboarding，提供商列表可能会有变化。
本文截图里选中的是：
DuckDuckGo Search (experimental)
如果你的界面和截图一样，那它对新手确实很友好，因为它的特点是：
- 不需要额外 API Key
- 能先给你一个可用的搜索兜底
如果你看到的是 Brave、Perplexity、Gemini、Grok、Kimi 之类的别家 provider，也按同一个原则处理：
- 手里已经有对应 Key，再选那一项
- 只是想先把安装流程跑通，就直接
Skip for now
所以这一屏最稳的两种选法是：
- 截图里如果有
DuckDuckGo Search (experimental)，想顺手把搜索功能也开上，就选它 - 只想先把聊天装好，就选
Skip for now
无论你选哪一个，都不会影响“先把本地聊天跑起来”这个大目标。
6. 看到 Configure skills now?：选 Yes
这一屏建议直接选：
Yes
原因不是让你一次性把所有技能都配完，而是：
- 让向导先帮你检查本机哪些技能已经能用
- 顺便告诉你缺了哪些依赖
- 你后面好知道哪些先跳过，哪些以后再装
对零基础新手来说，这一步选 Yes 不等于“我要现在就全部折腾完”，只是先看清楚情况。
7. 看到 Install missing skill dependencies：第一次选 Skip for now
很多人到这一屏会慌，因为一下子看到一长串陌生名字：
1passwordapple-notesblogwatchergithubgoplaces- 还有很多别的
第一次安装最稳的做法是：
- 选
Skip for now
原因很直接：
- 这些不是你把 OpenClaw 基本跑通的必需品
- 一次性装太多额外依赖，只会把变量变多
- 你后面真正需要哪个技能，再单独补就行
对于完全新手，我更建议先把“能聊天”这件事跑通，再回头研究技能生态。
8. 看到一连串 Set ... API KEY?：如果你不知道它是干什么的，就统一选 No
这一步通常不会只问一条，而是连续问你好几个，比如：
Set GOOGLE_PLACES_API_KEY for goplaces?Set NOTION_API_KEY for notion?Set OPENAI_API_KEY for openai-whisper-api?Set ELEVENLABS_API_KEY for sag?
第一次安装时，你可以直接按这个原则处理：
- 你已经明确在用这个服务，也已经有对应 Key，才选
Yes - 你不知道它是什么，或者暂时用不到，就选
No
对绝大多数新手来说，这一段可以几乎一路：
NoNoNo
这样完全正常，不代表你装失败了。
它只是在问你要不要顺手把一些可选插件也配置掉。
9. 看到 Enable hooks?：第一次选 Skip for now
Hooks 可以理解成“自动触发的小动作”，比如：
- 新会话时自动写入记忆
- 某些命令触发时自动做额外处理
这类能力很有用，但不适合第一次安装就一起上。
这一屏最稳的选择是：
Skip for now
原因是：
- Hooks 属于自动化增强，不是基础安装必需项
- 你现在先把本地聊天跑通，比先上自动化更重要
10. 看到 How do you want to hatch your bot?：选 Hatch in TUI (recommended)
这一屏说明 onboarding 已经差不多走完了。
这里直接选：
Hatch in TUI (recommended)
如果你看到：
ws://127.0.0.1:18789agent mainsession main- 下面还有一段欢迎语或首次启动提示
通常就说明两件事：
- 本地 Gateway 已经起来了
- OpenClaw 已经能创建本地会话
你这时可以做两种事：
- 先在 TUI 里试着发一条消息
- 或者按
Ctrl + C回到终端，继续执行openclaw dashboard用浏览器聊天
对大多数新手来说，我更建议继续做下面的验收动作，因为浏览器聊天才是你这篇文章真正要跑通的目标。
11. 如果停在这个 TUI 窗口，不知道怎么退出
很多新手第一次跑到这里，会以为：
- 是不是卡住了
- 这个窗口是不是不能关
- 我一关掉会不会把整个 OpenClaw 弄坏
其实不是。
这个窗口只是 OpenClaw 的 TUI 终端聊天界面，你可以正常退出。
按官方文档，常见的退出方式有 3 种：
- 按
Ctrl + D：直接退出当前TUI - 输入
/exit后回车：退出当前TUI - 连按两次
Ctrl + C：退出当前TUI
如果你只是想把这个窗口关掉，最稳的顺序是：
- 先用上面任意一种方式退出
TUI - 回到普通终端提示符后，再关闭这个终端窗口
这里一定要分清两件事：
- 关掉这个
TUI窗口，不等于后台Gateway也停了 - 如果你装的是后台服务模式，
TUI只是聊天界面，关掉后后台可能还在继续运行
如果你想的是“我连后台也不要继续跑了”，那就在退出 TUI 后执行：
1 | openclaw gateway stop |
如果你后面还想再打开：
1 | openclaw tui |
前一条会重新打开终端聊天界面，后一条会直接打开浏览器聊天页。
12. 如果 TUI 底部出现 gateway disconnected: closed | idle
这种情况的意思通常不是“你的消息有问题”，而是：
- 当前
TUI已经和本地Gateway断开了 - 或者后台
Gateway根本没正常跑起来
很多新手会把屏幕上的：
1 | gateway disconnected: closed | idle |
误以为是一条要输入的命令。
其实它只是 TUI 底部的一行状态提示，不要直接把它敲进终端。
如果你看到这个状态，最省事就按下面 4 条命令顺序执行：
1 | openclaw gateway install |
这 4 条分别是在做：
- 重新安装本地
Gateway服务 - 启动
Gateway - 确认服务现在是不是已经正常运行
- 重新打开浏览器聊天页
如果你执行完前 3 条后，gateway status 仍然显示服务没起来，再继续执行：
1 | openclaw logs --follow |
优先看有没有下面这类问题：
- 端口
18789被别的进程占用了 - 旧服务没清干净
- 当前配置没被正确加载
如果你已经能打开 dashboard 链接，但浏览器里仍提示 unauthorized，再执行：
1 | openclaw config get gateway.auth.token |
把输出的 token 粘到 dashboard 设置里即可。
如果你的向导比截图多出几屏，按下面这样选
不同版本的 onboarding，可能会把一些问题拆开单独问，也可能直接帮你套进 QuickStart 默认值。
如果你额外看到了下面这些页面，可以直接照这个规则选。
1. Existing config / Keep / Modify / Reset
第一次安装通常不会看到这一步。
如果看到了，说明这台 Mac 以前装过 OpenClaw 或留下过旧配置。
建议这样选：
- 完全不确定以前配过什么，选
Reset - 想保留旧配置再调整，选
Modify - 明确知道旧配置没问题，才选
Keep
2. Default model
这里的原则非常简单：
- 选当前账户里能用的模型
- 优先选推荐项
- 第一次不要手填自定义模型名
3. Workspace
第一次安装直接保留默认值：
1 | ~/.openclaw/workspace |
不要急着改路径。
默认路径最利于后面查日志、查配置和排错。
4. Gateway
第一次安装建议按下面思路选：
Port：18789Bind：loopback或本机访问Auth mode：tokenToken storage：默认自动生成Tailscale：先关掉
新手第一次一定记住两条：
- 不要先改成公网绑定
- 不要先关闭认证
5. Daemon
这里选：
Install
如果还让你选 runtime，优先：
Node
在 macOS 上，这通常会把 Gateway 注册成 LaunchAgent，以后就不需要每次手动启动。
6. Health Check
这一屏通常不用你做复杂选择，等它跑完就行。
你主要看三件事：
- Gateway 成功启动
- 健康检查通过
- 没有关键错误中断
第四步：安装完成后，马上做这 6 个验收动作
很多人装完就结束了，但真正重要的是“验收”。
1. 先确认命令已经可用
1 | openclaw --version |
如果它能正常输出版本号，说明 CLI 至少已经装上了。
2. 确认 Gateway 正在运行
1 | openclaw gateway status |
按官方 Getting Started 文档，正常情况下你应该看到 Gateway 在 18789 端口监听。
3. 打开浏览器 Dashboard
1 | openclaw dashboard |
这条命令会尝试：
- 打开浏览器
- 给出 dashboard 链接
- 如果界面还没保存认证信息，就提示你补
gateway.auth.token
4. 在浏览器里发第一条测试消息
你可以直接发这句：
1 | 你好，请先做个自我介绍，并告诉我你现在已经连接了哪些能力。 |
只要它能正常回复，说明你已经跑通了最小闭环。
5. 做一次巡检
1 | openclaw doctor |
官方 doctor 文档把它定位成“健康检查 + 快速修复入口”。
第一次安装后跑一遍，很有必要。
6. 如果 doctor 提示 Memory search 警告，最省事就先这样处理
很多新手第一次跑完 openclaw doctor，会看到类似这种提示：
Memory search is enabled, but no embedding provider is readyNo API key found for provider "openai"- 或者它提醒你去补
OPENAI_API_KEY、GOOGLE_API_KEY、VOYAGE_API_KEY
这通常不代表你“装坏了”，更不代表 OpenClaw 不能用了。
对第一次安装的新手来说，它更常见的意思只是：
- 语义记忆检索功能已经开着
- 但你还没有给它配置好 embeddings 提供商
如果你现在的目标只是“先能正常聊天”，最省事就直接粘这 3 条：
1 | openclaw config set agents.defaults.memorySearch.enabled false |
这 3 条分别是在做：
- 关掉当前最容易让新手困惑的
Memory search警告 - 重启
Gateway让新配置生效 - 直接打开浏览器聊天页
如果你想再补一条确认，也可以执行：
1 | openclaw gateway status |
如果浏览器里这时又提示 unauthorized，再执行：
1 | openclaw config get gateway.auth.token |
把输出的 token 粘到 dashboard 里即可。
等你后面想用更完整的记忆检索，再回头补 embeddings 也完全来得及。
第一次安装的核心目标，还是先把本地聊天跑通。
第五步：如果中间出错，优先按这个顺序排查
下面这些是新手最容易遇到的情况。
情况 1：终端提示 openclaw: command not found
先别急着重装，按这个顺序处理：
- 关掉当前终端
- 重新打开一个新的终端窗口
- 再执行一次：
1 | openclaw --version |
如果还是不行，再执行：
1 | export PATH="$(npm prefix -g)/bin:$PATH" |
然后把这一行写进 ~/.zshrc，再开新终端。
情况 2：浏览器里出现 unauthorized 或 1008
这是新手很常见的问题，但通常不是安装失败。
官方 Dashboard 和 FAQ 文档给出的优先处理方法是：
- 重新执行：
1 | openclaw dashboard |
打开它打印出来的 dashboard 链接
如果界面提示认证，再把
gateway.auth.token粘到 Control UI 设置里
如果还不行，再取出当前 token：
1 | openclaw config get gateway.auth.token |
然后把这个 token 粘到 dashboard 的设置里。
如果根本没有 token，官方 FAQ 允许你直接生成一个：
1 | openclaw doctor --generate-gateway-token |
情况 3：明明 token 改过了，还是一直认证失败
官方 doctor 文档专门提到过一个 macOS 常见坑：
- 你以前通过
launchctl setenv设置过旧 token - 系统环境变量把当前配置覆盖掉了
先检查：
1 | launchctl getenv OPENCLAW_GATEWAY_TOKEN |
如果查到了旧值，再清掉：
1 | launchctl unsetenv OPENCLAW_GATEWAY_TOKEN |
然后重新执行：
1 | openclaw gateway status |
情况 4：Gateway 看起来在跑，但页面还是不正常
这时候不要只盯着“有没有进程”。
按官方排错思路，至少一起看这几项：
1 | openclaw gateway status |
尤其要注意：
- Gateway 是否真的能被当前认证方式访问
- 当前连接的是本地 Gateway，还是不小心指向了 remote
- 是否存在旧配置、旧认证、旧服务残留
第六步：怎样才算你已经真的装成功了
对零基础新手来说，最实用的成功标准不是“命令跑完了”，而是下面这 4 条同时成立：
openclaw gateway status正常openclaw dashboard能打开浏览器界面- 你在浏览器里发消息能收到回复
openclaw doctor没有关键错误
只要这 4 条成立，你就已经完成了一次合格的本地部署。
第七步：第一次跑通后，下一步应该做什么
很多新手装成功后，会马上想做更多事情。
我的建议是按这个顺序继续：
- 先熟悉 dashboard 里的基本聊天和设置
- 再只接入一个聊天渠道，例如
Telegram - 再考虑技能、自动化、远程访问
- 最后再研究
Tailscale、SSH tunnel或公网方案
原因很简单：每次只增加一个变量，你后面才容易定位问题。
一份适合保存的极简命令清单
如果你只想留一版最核心的命令，可以保存下面这组：
1 | curl -fsSL https://openclaw.ai/install.sh | bash |
如果安装后网页提示 unauthorized，优先再执行：
1 | openclaw dashboard |
最后再提醒一次：新手第一次不要做的 4 件事
- 不要一开始就选
Remote - 不要一开始就接多个聊天渠道
- 不要把 dashboard 直接暴露到公网
- 不要还没跑通本地聊天，就先折腾高级配置
你第一次安装的目标只有一个：
把本地浏览器聊天先跑通。
只要这一步成功，后面的事情就都好办了。