【OpenClaw 全面解析：从零到精通】第 005 篇：OpenClaw 在 macOS 上的安装与部署实战

系列说明 ：本系列共计约 20 篇，全面介绍 OpenClaw 开源 AI 智能体框架。本文为系列第 005 篇，聚焦于 OpenClaw 在macOS上的安装与部署实战。建议先阅读第 004 篇：OpenClaw 在 Linux/Ubuntu 上的安装与部署实战。

摘要

本文详细介绍在 macOS 系统上安装和部署 OpenClaw 的完整流程,包括系统要求、环境准备、Homebrew 安装、Node.js 配置、OpenClaw 一键安装、初始化配置向导、M 芯片优化以及安全加固。文章涵盖从零开始到生产环境的最佳实践,帮助 Mac 用户快速搭建本地 AI 助手。

一、系统要求与前期准备

1.1 硬件要求

OpenClaw 在 macOS 上运行的硬件需求取决于使用场景,以下是推荐的配置标准:

配置项	最低要求	推荐配置	说明
处理器	Intel Core i5 (2015+)	Apple M1/M2/M3 芯片	Apple 芯片性能优势显著
内存	8GB RAM	16GB+ RAM	多任务并发时内存需求较大
存储	20GB 可用空间	50GB+ SSD	SSD 显著提升 I/O 性能
网络	稳定互联网连接	高速宽带	部分模型需要在线调用

1.2 系统版本要求

最低版本: macOS 12.0 (Monterey)
推荐版本: macOS 14.0 (Sonoma) 或更新版本
Shell 要求: 默认 Zsh (macOS Catalina 及之后默认)或 Bash

1.3 权限配置

在安装前需要确保以下系统权限已开启:

开发者工具: 安装 Xcode Command Line Tools
终端权限: 允许终端完全控制磁盘访问
网络权限: 允许 Node.js 和 OpenClaw 访问网络

安装命令:

bash 复制代码

# 安装 Xcode Command Line Tools
xcode-select --install

二、安装 Homebrew 包管理器

Homebrew 是 macOS 上最流行的包管理器,可以方便地安装各种开发工具。OpenClaw 的安装依赖项都可以通过 Homebrew 快速安装。

2.1 安装 Homebrew

打开终端(Terminal 或 iTerm2),执行以下命令:

bash 复制代码

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程说明:

安装过程中需要输入 macOS 登录密码
安装时间约 3-5 分钟,需要耐心等待
安装完成后需要配置 PATH 环境变量

配置 PATH (仅 Apple Silicon M 芯片需要):

bash 复制代码

# Apple Silicon 芯片需要添加以下配置
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

2.2 验证安装

bash 复制代码

brew --version

如果输出版本号(如 Homebrew 4.x.x),说明安装成功。

2.3 Homebrew 常用命令

bash 复制代码

# 更新 Homebrew
brew update

# 升级已安装的包
brew upgrade

# 清理旧版本
brew cleanup

# 查看已安装的包
brew list

三、安装 Node.js 运行环境

OpenClaw 基于 Node.js 开发,需要 Node.js 22.0.0 或更高版本。

3.1 通过 Homebrew 安装 Node.js(推荐)

bash 复制代码

# 安装最新稳定版 Node.js
brew install node

# 验证安装
node -v
npm -v

注意事项:

Homebrew 会自动安装 npm(Node.js 包管理器)
安装成功后应看到类似 v24.13.0 的版本号
如果已安装旧版本,可以先卸载再安装

3.2 通过 NVM 安装 Node.js(可选,适合多版本管理)

如果需要在同一台 Mac 上管理多个 Node.js 版本,可以使用 nvm(Node Version Manager):

bash 复制代码

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 加载 nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装 Node.js 22
nvm install 22

# 设置为默认版本
nvm use 22
nvm alias default 22

# 验证安装
node -v

3.3 配置 npm 镜像(可选,国内用户推荐)

bash 复制代码

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

# 验证配置
npm config get registry

四、安装 OpenClaw

OpenClaw 提供了多种安装方式,在 macOS 上推荐使用一键安装脚本。

4.1 一键安装脚本(推荐)

bash 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash

安装过程说明:

脚本会自动下载最新版本的 OpenClaw CLI
安装到 ~/.local/bin/openclaw 目录
会自动将安装路径添加到 ~/.zshrc 配置文件
安装时间约 1-2 分钟

配置 PATH :

如果自动配置失败,手动添加以下内容到 ~/.zshrc:

bash 复制代码

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4.2 通过 npm 全局安装(备选方案)

bash 复制代码

# 安装 pnpm 包管理器(OpenClaw 依赖 pnpm)
npm install -g pnpm

# 全局安装 OpenClaw
pnpm add -g openclaw@latest

4.3 验证安装

bash 复制代码

openclaw --version

应该输出类似以下内容:

复制代码

OpenClaw 2026.3.2 (85377a2)

如果出现 "command not found" 错误:

重新执行 source ~/.zshrc
或关闭终端重新打开
检查 ~/.zshrc 文件中 PATH 配置是否正确

五、初始化配置向导

首次运行 OpenClaw 时,会进入交互式配置向导(onboarding),引导完成基本配置。

5.1 启动配置向导

bash 复制代码

openclaw

5.2 配置向导流程

步骤 1: 安全警告确认

复制代码

Security warning: OpenClaw is an AI agent framework that can execute commands on your system.
Are you sure you want to continue? (Y/n)

推荐选择: Yes (个人使用场景)
说明: 确认了解 OpenClaw 的安全风险

步骤 2: 选择配置模式

复制代码

Select onboarding mode:
[1] QuickStart (推荐) - 快速配置,使用默认设置
[2] Advanced - 高级配置,自定义所有选项

推荐选择: QuickStart
说明: 快速配置适合初次使用,后续可以在配置文件中修改

步骤 3: 网关端口配置

复制代码

Gateway port (default: 18789):

推荐选择: 直接回车使用默认端口 18789
说明: Gateway 是 OpenClaw 的 Web 管理界面端口
注意事项: 确保端口未被占用

步骤 4: 选择模型提供商

复制代码

Select model provider:
[1] OpenAI (需要 API Key)
[2] Claude (需要 API Key)
[3] DeepSeek (需要 API Key)
[4] 阿里云百炼 DashScope (国内推荐)
[5] 暂时跳过(后续配置)

推荐选择: 选择"暂时跳过"或选择国内可用的模型
说明: 可以跳过此步骤,后续通过配置文件添加

步骤 5: 选择 Channels 通道

复制代码

Select channels to install:
[1] WhatsApp
[2] Telegram
[3] 飞书
[4] 暂时跳过

推荐选择: 暂时跳过
说明: Channels 用于连接即时通讯平台,初次使用可不配置

步骤 6: 安装 Hooks

复制代码

Install hooks? (Y/n)

推荐选择: Y
说明: Hooks 是 OpenClaw 的钩子系统,支持记忆功能

步骤 7: 安装 Skills

复制代码

Select skills to install (comma-separated, or press Enter to skip):

推荐选择: 直接回车跳过
说明: Skills 是 OpenClaw 的功能插件,可以根据需求后续安装

5.3 配置完成

配置向导完成后,会自动:

创建配置文件 ~/.openclaw/openclaw.json
创建工作目录 ~/.openclaw/workspace
安装后台服务(daemon)
启动 Gateway 网关服务

验证安装:

bash 复制代码

# 检查服务状态
openclaw status

# 访问 Web 控制台
# 在浏览器打开: http://127.0.0.1:18789

六、启动与管理 OpenClaw

6.1 启动 OpenClaw

bash 复制代码

# 启动所有服务(包括 Gateway、Agent 等)
openclaw start

# 仅启动 Gateway 网关
openclaw gateway start

# 查看服务状态
openclaw status

6.2 停止 OpenClaw

bash 复制代码

# 停止所有服务
openclaw stop

# 仅停止 Gateway
openclaw gateway stop

6.3 设置开机自启动

bash 复制代码

# 安开机自启动服务
openclaw gateway install

# 启用开机自启动
brew services start openclaw

6.4 常用管理命令

bash 复制代码

# 查看日志
openclaw logs

# 查看版本信息
openclaw --version

# 更新到最新版本
openclaw update

# 查看帮助信息
openclaw --help

七、配置文件详解

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json,支持 JSON5 格式。

7.1 基本配置结构

json5 复制代码

{
  // Agents 配置
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  },

  // Gateway 配置
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0"
  },

  // 模型配置
  "models": {
    "default": "deepseek-chat",
    "providers": {
      "deepseek": {
        "apiKey": "YOUR_API_KEY"
      }
    }
  },

  // Hooks 配置
  "hooks": {
    "memory": {
      "enabled": true
    }
  }
}

7.2 修改配置文件

bash 复制代码

# 使用编辑器打开配置文件
vim ~/.openclaw/openclaw.json

# 修改后重启服务使配置生效
openclaw restart

八、M 芯片优化与性能调优

Apple Silicon (M1/M2/M3) 芯片在性能和能效比上具有显著优势,OpenClaw 在 M 芯片 Mac 上运行时可以进行以下优化。

8.1 ARM 原生编译

OpenClaw 的部分依赖可能需要重新编译以获得最佳性能:

bash 复制代码

# 重新安装 Node.js 模块
cd ~/.local/lib/node_modules/openclaw
rm -rf node_modules
pnpm install --force

8.2 内存优化

M 芯片 Mac 的内存是统一的,可以通过以下方式优化内存使用:

json5 复制代码

{
  "agents": {
    "defaults": {
      "memoryLimit": "2GB",
      "maxConcurrency": 3
    }
  }
}

8.3 使用 Rosetta 2(如有必要)

如果某些依赖不兼容 ARM 架构,可以启用 Rosetta 2:

bash 复制代码

# 软件设置 → 隐私与安全性 → Rosetta
# 或通过命令行安装
softwareupdate --install-rosetta

8.4 性能监控

bash 复制代码

# 使用 Activity Monitor 监控 OpenClaw 进程
# 或使用命令行工具
top -pid $(pgrep openclaw)

九、安全加固与权限管理

9.1 用户权限隔离

OpenClaw 默认以当前用户身份运行,建议创建专用用户:

bash 复制代码

# 创建专用用户(需要管理员权限)
sudo dscl . -create /Users/openclaw
sudo dscl . -create /Users/openclaw UserShell /bin/zsh
sudo dscl . -create /Users/openclaw RealName "OpenClaw Service"
sudo dscl . -create /Users/openclaw UniqueID 550
sudo dscl . -passwd /Users/openclaw

9.2 防火墙配置

macOS 自带防火墙,建议配置以下规则:

打开系统设置 → 网络 → 防火墙
防火墙选项 → 添加允许的应用
配置端口 18789 的入站规则

9.3 API Key 安全

bash 复制代码

# 创建环境变量文件
cat > ~/.openclaw/.env << EOF
OPENAI_API_KEY=your_openai_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key
EOF

# 设置文件权限
chmod 600 ~/.openclaw/.env

# 在配置文件中引用环境变量

9.4 沙盒隔离

OpenClaw 支持沙盒模式,限制 Agent 的文件访问权限:

json5 复制代码

{
  "sandbox": {
    "enabled": true,
    "allowedPaths": [
      "~/Documents",
      "~/Downloads"
    ]
  }
}

9.5 审计日志

json5 复制代码

{
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/audit.log",
    "auditCommands": true
  }
}

十、常见问题排查

10.1 端口被占用

问题: Gateway 启动失败,提示端口 18789 被占用

解决方法:

bash 复制代码

# 查找占用端口的进程
lsof -i :18789

# 杀死进程
kill -9 <PID>

# 或修改 Gateway 端口
# 编辑 ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18790
  }
}

10.2 Node.js 版本不兼容

问题: OpenClaw 启动失败,提示 Node.js 版本过低

解决方法:

bash 复制代码

# 使用 nvm 安装 Node.js 22
nvm install 22
nvm use 22

# 设置为默认版本
nvm alias default 22

10.3 权限不足

问题: 文件操作失败,提示权限不足

解决方法:

bash 复制代码

# 检查文件权限
ls -la ~/.openclaw

# 修改权限
chmod -R 755 ~/.openclaw

# 修改所有者
sudo chown -R $USER ~/.openclaw

10.4 网络连接失败

问题: 无法连接到模型 API

解决方法:

bash 复制代码

# 测试网络连接
curl -I https://api.openai.com

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 配置代理(如需要)
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

10.5 日志查看与调试

bash 复制代码

# 查看实时日志
openclaw logs --follow

# 查看错误日志
tail -f ~/.openclaw/logs/error.log

# 启用调试模式
DEBUG=* openclaw start

十一、生产环境部署建议

11.1 使用 Mac Mini 作为专用服务器

Mac Mini 是理想的 OpenClaw 专用服务器:

优势: 低功耗、静音、高性能(M 芯片)
配置: M2 Pro/Max + 16GB RAM + 512GB SSD
部署: 设置远程登录,无需显示器维护

11.2 监控与告警

bash 复制代码

# 使用 Supervisor 或 launchd 管理服务
# 创建 plist 文件: ~/Library/LaunchAgents/openclaw.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>openclaw</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<username>/.local/bin/openclaw</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

加载服务:

bash 复制代码

launchctl load ~/Library/LaunchAgents/openclaw.plist

11.3 数据备份

bash 复制代码

# 备份配置和工作目录
rsync -av ~/.openclaw /backup/openclaw_$(date +%Y%m%d)

# 定时备份(crontab)
0 2 * * * rsync -av ~/.openclaw /backup/openclaw_$(date +\%Y\%m\%d)

11.4 性能优化

json5 复制代码

{
  "performance": {
    "maxConcurrency": 5,
    "cacheSize": "1GB",
    "logLevel": "warn"
  }
}

十二、总结

在 macOS 上安装和部署 OpenClaw 是一个相对简单的过程,本文涵盖了从环境准备到生产部署的完整流程。通过以下步骤,Mac 用户可以快速搭建自己的本地 AI 助手:

环境准备: 确保系统版本和硬件配置满足要求
工具安装: 使用 Homebrew 安装 Node.js 等依赖
一键安装: 使用官方安装脚本快速部署 OpenClaw
配置向导: 通过交互式向导完成基本配置
安全加固: 配置权限、防火墙、API Key 安全等
性能优化: 针对 M 芯片进行优化配置

Mac 特别是 Apple Silicon 设备的出色性能,使 OpenClaw 能够高效运行,为用户提供流畅的 AI 助手体验。后续文章将介绍 Windows/WSL2 环境下的部署方法,以及在云端服务器上的部署实践。

上一篇 ：[第 004 篇] OpenClaw 在 macOS 上的安装与部署

下一篇 ：[第 006 篇] OpenClaw 在 Windows/WSL2 上的安装与部署实战

【OpenClaw 全面解析：从零到精通】第 005 篇：OpenClaw 在 macOS 上的安装与部署实战

摘要

一、系统要求与前期准备

1.1 硬件要求

1.2 系统版本要求

1.3 权限配置

二、安装 Homebrew 包管理器

2.1 安装 Homebrew

2.2 验证安装

2.3 Homebrew 常用命令

三、安装 Node.js 运行环境

3.1 通过 Homebrew 安装 Node.js(推荐)

3.2 通过 NVM 安装 Node.js(可选,适合多版本管理)

3.3 配置 npm 镜像(可选,国内用户推荐)

四、安装 OpenClaw

4.1 一键安装脚本(推荐)

4.2 通过 npm 全局安装(备选方案)

4.3 验证安装

五、初始化配置向导

5.1 启动配置向导

5.2 配置向导流程

步骤 1: 安全警告确认

步骤 2: 选择配置模式

步骤 3: 网关端口配置

步骤 4: 选择模型提供商

步骤 5: 选择 Channels 通道

步骤 6: 安装 Hooks

步骤 7: 安装 Skills

5.3 配置完成

六、启动与管理 OpenClaw

6.1 启动 OpenClaw

6.2 停止 OpenClaw

6.3 设置开机自启动

6.4 常用管理命令

七、配置文件详解

7.1 基本配置结构

7.2 修改配置文件

八、M 芯片优化与性能调优

8.1 ARM 原生编译

8.2 内存优化

8.3 使用 Rosetta 2(如有必要)

8.4 性能监控

九、安全加固与权限管理

9.1 用户权限隔离

9.2 防火墙配置

9.3 API Key 安全

9.4 沙盒隔离

9.5 审计日志

十、常见问题排查

10.1 端口被占用

10.2 Node.js 版本不兼容

10.3 权限不足

10.4 网络连接失败

10.5 日志查看与调试

十一、生产环境部署建议

11.1 使用 Mac Mini 作为专用服务器

11.2 监控与告警

11.3 数据备份

11.4 性能优化

十二、总结

参考资源