MacBook M1安装OpenClaw完整指南

目录

• 前言
• 环境要求
• 第一步：检查 Node.js 架构
• 检查当前架构
• 安装 ARM64 版本的 Node.js
• 第二步：安装 OpenClaw
• 第三步：运行 Onboard 向导
• 3.1 安全警告确认
• 3.2 选择 Onboarding 模式
• 3.3 配置模型认证
• 3.4 配置聊天渠道
• 3.5 配置 Skills
• 3.6 安装 Gateway 服务
• 3.7 配置 Shell 补全
• 3.8 完成
• 第四步：验证安装
• 检查 Gateway 状态
• 访问控制面板
• 重要文件路径
• 常用命令速查
• 常见问题 FAQ
• Q1: 安装时报错 "llama.cpp is not supported under Rosetta"
• Q2: 控制面板显示 "unauthorized: gateway token missing" 或 "gateway token mismatch"
• Q3: 如何查看 Node.js 架构？
• Q4: 如何让 AI 能搜索网页？
• Q5: 如何添加聊天渠道（Telegram/Discord/WhatsApp 等）？
• Q6: Gateway 服务没有启动怎么办？
• Q7: 如何重新运行 onboard 向导？
• 总结
• 参考链接

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

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

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

这是 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。

如果你用 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

确认 Node.js 架构正确后，安装 OpenClaw：

npm install -g openclaw@latest

验证安装：

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

这是配置 OpenClaw 的核心步骤：

openclaw onboard --install-daemon

向导首先会显示安全警告，提醒你 OpenClaw 可以读取文件和执行操作。确认后选择 Yes 继续。

选择 QuickStart，这是最简单的配置方式：

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

我使用的是 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 方式。

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

◇  Select channel (QuickStart)
│  → Skip for now

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

◇  Configure skills now? (recommended)
│  → No

◇  Install missing skill dependencies
│  → Skip for now

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

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

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

source ~/.zshrc

向导完成后会显示控制面板地址：

◇  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.

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

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

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

验证方法：

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

原因：直接访问 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 中，之后访问无需重复输入。

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

需要配置 Brave Search API Key：

openclaw configure --section web

openclaw channels add

# 检查状态
openclaw gateway status
# 手动加载服务
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 或者前台运行（调试用）
openclaw gateway --port 18789 --verbose

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
• 中文文档
• GitHub
• 安全指南
• 控制面板文档
• Token 问题排查

到此这篇关于MacBook M1安装OpenClaw完整指南的文章就介绍到这了,更多相关MacBook M1安装OpenClaw内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！