MacBook M1 安装 OpenClaw 完整指南

本文记录了在 MacBook M1 (Apple Silicon) 上安装 OpenClaw 的完整过程，包括遇到的坑和解决方案。

前言

OpenClaw 是一个开源的个人 AI 助手，可以连接 WhatsApp、Telegram、Discord、Slack 等多种聊天平台。本文将详细介绍如何在 M1 Mac 上从零开始安装和配置 OpenClaw。

环境要求

要求	说明
Node.js	≥22，必须是 ARM64 原生版本
操作系统	macOS (Apple Silicon)
包管理器	npm 或 pnpm

第一步：检查 Node.js 架构

这是 M1 Mac 上最容易踩的坑！

很多人通过 nvm 安装的 Node.js 实际上是 x86_64 版本（通过 Rosetta 运行），这会导致 OpenClaw 的 node-llama-cpp 依赖安装失败。

检查当前架构

node -p "process.arch"

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

也可以用这个命令确认：

file $(which node)

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

安装 ARM64 版本的 Node.js

如果你用 nvm 管理 Node.js，按以下步骤操作：

# 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 向导

这是配置 OpenClaw 的核心步骤：

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)

注意：如果使用 API Key，一定要选择具体的模型（如 M2.1），不要选择 OAuth 方式。

3.4 配置聊天渠道

可以先跳过，后续通过 openclaw channels add 添加：

◇  Select channel (QuickStart)
│  → Skip for now

3.5 配置 Skills

也可以先跳过，按需配置：

◇  Configure skills now? (recommended)
│  → No

◇  Install missing skill dependencies
│  → Skip for now

3.6 安装 Gateway 服务

向导会自动安装 macOS LaunchAgent 服务：

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

◇  Gateway service installed.

3.7 配置 Shell 补全

选择 Yes 启用命令补全，然后重新加载配置：

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 状态

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/openclaw.json	主配置文件
~/.openclaw/workspace/	Agent 工作区
~/.openclaw/credentials/	凭证存储
~/.openclaw/agents/main/sessions/	会话记录
~/.openclaw/logs/gateway.log	Gateway 日志
~/Library/LaunchAgents/ai.openclaw.gateway.plist	macOS 服务配置

常用命令速查

命令	说明
openclaw --version	查看版本
openclaw gateway status	查看网关状态
openclaw dashboard --no-open	获取带 Token 的控制面板 URL
openclaw status	查看整体状态
openclaw health	健康检查
openclaw doctor	诊断问题
openclaw channels add	添加聊天渠道
openclaw skills	管理 Skills
openclaw configure --section web	配置网页搜索
openclaw security audit --deep	安全审计
openclaw config get gateway.auth.token	获取 Gateway Token

常见问题 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

Token 首次加载后会保存在浏览器的 localStorage 中，之后访问无需重复输入。

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

# 方法 1
node -p "process.arch"

# 方法 2
file $(which node)

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

需要配置 Brave 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 Mac 上安装 OpenClaw 的关键点：

1. 确保 Node.js 是 ARM64 版本 - 这是最容易踩的坑
2. 使用 openclaw onboard --install-daemon - 一键完成配置和服务安装
3. 访问控制面板要带 Token - 使用 openclaw dashboard --no-open 获取完整 URL

完成以上步骤后，就可以通过浏览器访问 OpenClaw 控制面板，开始体验 AI 助手了！🦞

参考链接

• 官方文档: docs.openclaw.ai
• 中文文档: clawcn.net/start/getti...
• GitHub: github.com/openclaw/op...
• 安全指南: docs.openclaw.ai/gateway/sec...
• 控制面板文档: docs.openclaw.ai/web/control...
• Token 问题排查: clawd.org.cn/gateway/tok...