MacBook M1安装OpenClaw详细教程与步骤解析

前言

想在M1 Mac上部署一个能打通WhatsApp、Telegram、Discord、Slack等多个聊天平台的开源AI助手吗？OpenClaw是个不错的选择。今天，我们就来手把手走一遍在Apple Silicon Mac上从零安装和配置OpenClaw的全过程。

环境要求

动手之前，先确认你的环境满足以下要求：

第一步：检查 Node.js 架构

这一步是M1/M2/M3 Mac用户最容易栽跟头的地方，务必仔细。

很多朋友习惯用nvm来管理Node.js，但默认安装的版本很可能是x86_64架构的（通过Rosetta转译运行）。而OpenClaw依赖的node-llama-cpp等原生模块，在Rosetta下会直接报错，导致安装失败。

检查当前架构

打开终端，运行以下命令检查你的Node.js架构：

node -p "process.arch"

如果输出是x64，那就说明你安装的是x86_64版本，需要重新来过。

也可以用这个命令再确认一下：

file $(which node)

正确的输出应该包含arm64，而不是x86_64。

安装 ARM64 版本的 Node.js

如果发现架构不对，别慌。如果你用的是nvm，按照下面这个流程操作就能搞定：

# 1. 先切换到其他版本（因为不能卸载正在使用的版本）
source ~/.nvm/nvm.sh
nvm use 20 # 或其他已安装版本

# 2. 卸载 x86_64 版本
nvm uninstall 22

# 3. 在 ARM64 环境下重新安装
arch -arm64 /bin/zsh -c "export NVM_DIR=~/.nvm && source ~/.nvm/nvm.sh && nvm install 22"

# 4. 设置为默认版本
nvm alias default 22
nvm use default

# 5. 验证架构
node -p "process.arch"
# 应输出: arm64

第二步：安装 OpenClaw

确认Node.js架构正确无误后，安装OpenClaw本身就是一条命令的事儿：

npm install -g openclaw@latest

安装完成后，验证一下：

openclaw --version
# 输出: 2026.2.6-3 (或更新版本)

第三步：运行 Onboard 向导

安装好命令行工具，接下来就是核心的配置环节了。运行Onboard向导，它会引导你完成所有必要设置。

openclaw onboard --install-daemon

3.1 安全警告确认

向导启动后，首先会显示一个安全警告，提醒你OpenClaw拥有读取文件和执行操作的权限。这是正常流程，确认后选择“Yes”继续即可。

3.2 选择 Onboarding 模式

这里建议选择QuickStart，这是最简单快捷的配置方式，会使用一组合理的默认值。

◇ QuickStart ─────────────────────────╮
│                                      │
│ Gateway port: 18789                  │
│ Gateway bind: Loopback (127.0.0.1)   │
│ Gateway auth: Token (default)        │
│ Tailscale exposure: Off              │
│                                      │
├──────────────────────────────────────╯

3.3 配置模型认证

这里以使用MiniMax API Key为例：

1. Model/auth provider → 选择 MiniMax
2. MiniMax auth method → 选择 MiniMax M2.1（注意不要选OAuth）
3. Enter MiniMax API key → 输入你的API Key
4. Default model → 选择 Keep current (minimax/MiniMax-M2.1)

3.4 配置聊天渠道

连接WhatsApp、Telegram等聊天平台可以稍后进行，这里先跳过。

◇ Select channel (QuickStart)
│→ Skip for now

3.5 配置 Skills

Skills（技能）也可以按需后续添加，这里同样选择跳过。

◇ Configure skills now? (recommended)
│→ No
◇ Install missing skill dependencies
│→ Skip for now

3.6 安装 Gateway 服务

向导会自动为你安装macOS的LaunchAgent服务，让OpenClaw Gateway在后台持续运行。

◒ Installing Gateway service…
...Installed LaunchAgent: ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs: ~/.openclaw/logs/gateway.log
◇ Gateway service installed.

3.7 配置 Shell 补全

建议选择“Yes”启用命令自动补全功能，之后记得重新加载一下shell配置。

source ~/.zshrc

3.8 完成

配置完成！向导会显示控制面板的访问地址，务必记下。

◇ Control UI ─────────────────────────────────────────────────────────────────────╮
│                                                                                  │
│ Web UI: http://127.0.0.1:18789/                                                  │
│ Web UI (with token):                                                             │
│ http://127.0.0.1:18789/#token=xxxxxx                                             │
│                                                                                  │
├──────────────────────────────────────────────────────────────────────────────────╯
└Onboarding complete. Use the dashboard link above to control OpenClaw.

第四步：验证安装

检查 Gateway 状态

运行以下命令，确认Gateway服务已经正常启动：

openclaw gateway status

看到类似下面的输出，就说明一切正常：

Service: LaunchAgent (loaded)
Runtime: running (pid xxxx)
RPC probe: ok
Listening: 127.0.0.1:18789

访问控制面板

这里有个关键点：不要直接访问 http://127.0.0.1:18789/，这样会因为缺少Token认证而无法连接。

正确的方法是获取带Token的完整URL：

openclaw dashboard --no-open

复制命令输出的完整URL（包含#token=xxx部分），粘贴到浏览器中打开，就能成功进入OpenClaw的控制面板了。

重要文件路径

了解这些核心文件的存放位置，对后续管理和排查问题很有帮助。

常用命令速查

把下面这些常用命令存下来，日常管理会方便很多。

常见问题 FAQ

Q1: 安装时报错 "llama.cpp is not supported under Rosetta"

原因：你的 Node.js 是 x86_64 版本，在 Apple Silicon Mac 上通过 Rosetta 运行。

解决方案：按照本文「第一步」的方法，卸载 x86_64 版本，安装 ARM64 原生版本。

验证方法：

node -p "process.arch"
# 应输出: arm64
file $(which node)
# 应包含: arm64

Q2: 控制面板显示 "unauthorized: gateway token missing" 或 "gateway token mismatch"

原因：直接访问 http://127.0.0.1:18789/ 没有带 Token 认证。

解决方案：

方法一（推荐）：使用命令获取带 Token 的链接

openclaw dashboard --no-open

复制输出的完整 URL 到浏览器打开。

方法二：手动获取 Token

openclaw config get gateway.auth.token

然后在控制面板的设置中粘贴 Token。

方法三：如果 Token 丢失，重新生成

openclaw doctor --generate-gateway-token

Q3: 如何查看 Node.js 架构？

# 方法 1
node -p "process.arch"
# 方法 2
file $(which node)

Q4: 如何让 AI 能搜索网页？

需要配置 Bra ve Search API Key：

openclaw configure --section web

Q5: 如何添加聊天渠道（Telegram/Discord/WhatsApp 等）？

openclaw channels add

Q6: Gateway 服务没有启动怎么办？

# 检查状态
openclaw gateway status

# 手动加载服务
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# 或者前台运行（调试用）
openclaw gateway --port 18789 --verbose

Q7: 如何重新运行 onboard 向导？

openclaw onboard --install-daemon

总结

在 M1/M2/M3 Mac 上成功部署 OpenClaw，其实就抓住三个关键点：

1. 确保 Node.js 是 ARM64 版本 - 这是最容易踩的坑，也是大部分安装失败的根源。
2. 使用 openclaw onboard --install-daemon - 这个向导能一键完成核心配置和后台服务安装。
3. 访问控制面板要带 Token - 记住用 openclaw dashboard --no-open 获取完整 URL，别直接访问IP端口。

搞定这几步，你的个人AI助手就已经在本地跑起来了。接下来，就可以通过浏览器打开控制面板，开始连接各种聊天渠道，或者为AI配置更多实用技能了。