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

首页

AI教程

热心网友

转载

2026-05-28

前言

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

MacBook M1 安装 OpenClaw 完整指南

环境要求

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

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

第一步：检查 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为例：

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)

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: https://127.0.0.1:18789/                                                  │
│ Web UI (with token):                                                             │
│ https://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

访问控制面板

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

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

openclaw dashboard --no-open

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

重要文件路径

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

路径	说明
`~/.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"

原因：直接访问 https://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