MacBook M1 安装 OpenClaw 完整指南OpenClaw 是一个开源的个人 AI 助手，可以连接 What

本文记录了在 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：

Model/auth provider → 选择 MiniMax
MiniMax auth method → 选择 MiniMax M2.1（不要选 OAuth）
Enter MiniMax API key → 输入你的 API Key
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 的关键点：

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

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

MacBook M1 安装 OpenClaw 完整指南

前言