Mac 安装 OpenClaw 完整教程 | 国内网络环境优化指南（2026）

OpenClaw 是一款强大的个人 AI 助手框架，可以在你的 Mac 上运行。但由于网络原因，国内用户在安装过程中常遇到连接超时、下载失败等问题。本教程针对中国大陆网络环境优化，确保每一步都能顺利完成。

💡 适用系统: macOS 12.0+ (Monterey 及更高版本)
💡 适用芯片: Intel / Apple Silicon (M1/M2/M3)
💡 预计时间: 15-30 分钟

第一步：检查系统环境

1.1 确认 macOS 版本

打开终端（Terminal），输入：

sw_vers

确保版本号 ≥ 12.0。如果太低，请先升级系统。

1.2 确认芯片类型

uname -m

输出 arm64 = Apple Silicon (M1/M2/M3)
输出 x86_64 = Intel 芯片

1.3 检查 Homebrew 是否已安装

brew --version

如果提示 command not found，需要安装 Homebrew（见下一步）。

第二步：安装 Homebrew（国内镜像）

Homebrew 是 macOS 的包管理器，OpenClaw 依赖它。

2.1 使用国内镜像安装 Homebrew

官方脚本在国内可能超时，使用中科大镜像：

export HOMEBREW_INSTALL_FROM_API=1
/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/homebrew-install/install.sh)"

2.2 设置 Homebrew 国内镜像源

安装完成后，设置镜像加速：

# Apple Silicon (M1/M2/M3)
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"

# 将配置写入 shell 配置文件
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"' >> ~/.zprofile
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"' >> ~/.zprofile

# 使配置生效
source ~/.zprofile

2.3 验证 Homebrew

brew doctor
brew update

如果显示 Your system is ready to brew，说明安装成功。

第三步：安装 Node.js（国内镜像）

OpenClaw 需要 Node.js 20+ 版本。

3.1 使用 Homebrew 安装 Node.js

brew install node@22

3.2 配置 npm 国内镜像

npm 官方源在国内很慢，使用淘宝镜像：

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

应该输出：https://registry.npmmirror.com

3.3 验证 Node.js 和 npm

node --version
npm --version

Node.js 应该 ≥ v20.0.0
npm 应该 ≥ 9.0.0

第四步：安装 OpenClaw

4.1 使用 npm 全局安装

npm install -g openclaw

如果下载慢或失败，尝试以下方法：

方法 A：使用 npmmirror 镜像

npm install -g openclaw --registry=https://registry.npmmirror.com

方法 B：使用 yarn（如果 npm 一直失败）

# 安装 yarn
npm install -g yarn --registry=https://registry.npmmirror.com

# 设置 yarn 镜像
yarn config set registry https://registry.npmmirror.com

# 安装 OpenClaw
yarn global add openclaw

4.2 验证安装

openclaw --version

应该输出版本号，如 openclaw/x.x.x darwin-arm64 node-v20.x.x

第五步：初始化 OpenClaw

5.1 创建工作区

# 创建工作目录
mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace

# 初始化 OpenClaw
openclaw init

5.2 配置网关（Gateway）

# 启动网关服务
openclaw gateway start

# 检查状态
openclaw gateway status

如果看到 Gateway is running，说明启动成功。

5.3 配置模型（可选）

OpenClaw 支持多种 AI 模型。国内推荐使用：

# 配置阿里云百炼（通义千问）
openclaw configure --model bailian/qwen3.5-plus

国内可用模型推荐：

bailian/qwen3.5-plus – 阿里云通义千问（推荐）
bailian/qwen-max – 通义千问 Max

第六步：验证安装

6.1 运行状态检查

openclaw status

应该显示：

✅ Gateway 运行状态
✅ 当前模型配置
✅ 工作区路径

6.2 测试对话

openclaw chat "你好，测试一下"

如果收到回复，说明安装成功！

第七步：配置飞书集成（可选）

OpenClaw 可以集成到飞书，让你在飞书中与 AI 对话。

7.1 创建飞书应用

访问飞书开放平台
登录企业账号
创建新应用
获取 App ID 和 App Secret

7.2 配置 OpenClaw

openclaw configure --section feishu

按提示输入：

App ID
App Secret
验证令牌（Verification Token）

7.3 发布应用到飞书

在飞书开放平台：

配置事件订阅
配置机器人权限
发布应用

常见问题解决

❓ Q1: Homebrew 安装超时

解决方案： 使用镜像源

# 使用中科大镜像
/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/homebrew-install/install.sh)"

❓ Q2: npm install 卡住不动

解决方案： 切换镜像源

npm config set registry https://registry.npmmirror.com
npm cache clean --force
npm install -g openclaw

❓ Q3: openclaw 命令找不到

解决方案： 检查 PATH

# 查看 npm 全局包路径
npm config get prefix

# 添加到 PATH（根据输出调整）
export PATH="/opt/homebrew/bin:$PATH"  # Apple Silicon
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

❓ Q4: Gateway 启动失败

解决方案： 检查端口占用

# 查看端口占用
lsof -i :8080

# 如果端口被占用，修改配置或关闭占用进程
openclaw gateway stop
openclaw gateway start

❓ Q5: skill 下载不了

解决方案： 使用腾讯镜像加速技能商店
1.在终端中执行以下命令，即可安装 SkillHub CLI

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --no-skills

2.在终端中执行以下命令，即可安装 SkillHub CLI，并且优先采用 SkillHub 加速安装技能

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

性能优化建议

1. 使用 SSD 存储

OpenClaw 工作区建议放在 SSD 上，提升读写速度。

2. 增加内存

建议 Mac 内存 ≥ 8GB，推荐 16GB+。

3. 定期清理缓存

# 清理 npm 缓存
npm cache clean --force

# 清理 Homebrew 缓存
brew cleanup

# 清理 OpenClaw 日志
openclaw logs --clear

4. 使用国内镜像

始终保持以下配置：

# .zprofile 中添加
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export npm_config_registry="https://registry.npmmirror.com"