🍎 macOS 系统部署 OpenClaw 完整指南

最后更新： 2026-03-09
版本： v1.0

📋 目录

1. 系统要求
2. 安装步骤
3. 配置说明
4. 启动与验证
5. 常见问题
6. 一键安装脚本
7. 芯片性能对比

系统要求

硬件要求

软件要求

安装步骤

第一步：安装 Homebrew（推荐）

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

验证安装：

brew --version

第二步：安装 Node.js

方式 A：使用 Homebrew（推荐）

brew install node@20

方式 B：从官网下载

1. 访问 https://nodejs.org/
2. 下载 LTS 版本（推荐 v20.x）
3. 运行安装程序

验证安装：

node --version
npm --version

应显示类似：

v20.11.0
10.2.4

第三步：安装 Git

方式 A：使用 Homebrew

brew install git

方式 B：使用 Xcode Command Line Tools

xcode-select --install

验证安装：

git --version

第四步：安装 OpenClaw

方式 A：使用 npm 全局安装（推荐）

npm install -g openclaw

方式 B：从 GitHub 克隆（开发模式）

# 创建安装目录
mkdir ~/OpenClaw
cd ~/OpenClaw

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git .

# 安装依赖
npm install

第五步：初始化配置

# 创建配置目录
mkdir ~/.openclaw

# 生成默认配置
openclaw init

配置说明

配置文件位置

~/.openclaw/openclaw.json

基础配置模板

{
  "version": "1.0",
  "gateway": {
    "port": 18789,
    "host": "localhost"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "你的 App Secret",
          "botName": "大管家"
        }
      }
    },
    "webchat": {
      "enabled": true
    }
  },
  "models": {
    "primary": "bailian/qwen3.5-plus",
    "providers": {
      "bailian": {
        "apiKey": "你的阿里云百炼 API Key",
        "enabled": true
      }
    }
  },
  "workspace": "/Users/<用户名>/Desktop/知识库"
}

推荐模型配置（中国大陆）

获取 API Key：

1. 访问 https://bailian.console.aliyun.com/
2. 注册/登录阿里云账号
3. 开通百炼服务
4. 创建 API Key

macOS 特有配置

Terminal 权限

首次运行可能需要授予 Terminal 完全磁盘访问权限：

系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 添加 Terminal

防火墙设置

如遇到连接问题，允许 Gateway 通过防火墙：

系统设置 → 网络 → 防火墙 → 选项 → 添加 openclaw

启动与验证

启动 Gateway

cd ~/.openclaw
openclaw gateway

验证服务

方式 1：浏览器访问

打开浏览器访问：http://localhost:18789

方式 2：命令行验证

curl http://localhost:18789/health

应返回：

{"status": "ok", "version": "2026.3.2"}

方式 3：查看日志

tail -f ~/.openclaw/logs/gateway.log

停止服务

在运行 Gateway 的终端按 Ctrl + C

开机自启动（可选）

创建 LaunchAgent：

cat > ~/Library/LaunchAgents/com.openclaw.gateway.plist << 'EOF'
<?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>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>gateway</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/<用户名>/.openclaw</string>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<用户名>/.openclaw/logs/openclaw.out</string>
    <key>StandardErrorPath</key>
    <string>/Users/<用户名>/.openclaw/logs/openclaw.err</string>
</dict>
</plist>
EOF

# 加载服务
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

常见问题

问题 1：Gateway 启动失败

错误信息： Error: listen EADDRINUSE: address already in use :::18789

原因： 端口 18789 已被占用

解决方案：

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

# 杀死进程（替换 PID 为实际进程 ID）
kill -9 <PID>

# 或修改配置文件使用其他端口

问题 2：飞书机器人不回复

检查清单：

1. ✅ 飞书应用已发布
2. ✅ 事件订阅已配置（im.message.receive_v1）
3. ✅ App ID 和 App Secret 正确
4. ✅ 机器人已添加到聊天
5. ✅ Gateway 日志显示 WebSocket 连接成功

调试命令：

# 查看飞书通道日志
tail -f ~/.openclaw/logs/gateway.log | grep feishu

问题 3：npm 安装失败

错误信息： npm ERR! code EACCES

解决方案：

# 修复 npm 权限
sudo chown -R $(whoami) ~/.npm

# 或使用 Homebrew 安装的 Node.js
brew install node@20

问题 4：模型 API 调用失败

检查清单：

1. ✅ API Key 正确且未过期
2. ✅ 账户余额充足
3. ✅ 网络连接正常
4. ✅ 模型 ID 拼写正确

测试命令：

curl -H "Authorization: Bearer 你的 API Key" https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation

问题 5：Apple Silicon 兼容性问题

错误信息： bad CPU type in executable

原因： Intel 版本的 Node.js 在 M 系列芯片上运行

解决方案：

# 卸载 Intel 版本
brew uninstall node

# 安装 ARM64 版本
arch -arm64 brew install node@20

问题 6：权限错误

错误信息： EPERM: operation not permitted

解决方案：

# 修复配置目录权限
chmod -R 755 ~/.openclaw

# 修复技能目录权限
chmod -R 755 ~/.agents/skills

一键安装脚本

创建文件 install-openclaw.sh：

#!/bin/bash

# OpenClaw macOS 一键安装脚本
# 使用方法：bash install-openclaw.sh

echo "======================================"
echo "  OpenClaw macOS 安装脚本"
echo "======================================"
echo ""

# 检查 Homebrew
echo "[1/6] 检查 Homebrew..."
if command -v brew &> /dev/null; then
    echo "  ✓ Homebrew 已安装：$(brew --version)"
else
    echo "  ✗ Homebrew 未安装"
    echo "  正在安装 Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi

# 检查 Node.js
echo "[2/6] 检查 Node.js..."
if command -v node &> /dev/null; then
    echo "  ✓ Node.js 已安装：$(node --version)"
else
    echo "  ✗ Node.js 未安装，正在安装..."
    brew install node@20
fi

# 检查 Git
echo "[3/6] 检查 Git..."
if command -v git &> /dev/null; then
    echo "  ✓ Git 已安装：$(git --version)"
else
    echo "  ✗ Git 未安装，正在安装..."
    brew install git
fi

# 安装 OpenClaw
echo "[4/6] 安装 OpenClaw..."
npm install -g openclaw
if [ $? -eq 0 ]; then
    echo "  ✓ OpenClaw 安装成功"
else
    echo "  ✗ OpenClaw 安装失败"
    exit 1
fi

# 创建配置目录
echo "[5/6] 创建配置目录..."
OPENCLAW_DIR="$HOME/.openclaw"
if [ ! -d "$OPENCLAW_DIR" ]; then
    mkdir -p "$OPENCLAW_DIR"
    echo "  ✓ 配置目录已创建：$OPENCLAW_DIR"
else
    echo "  ✓ 配置目录已存在"
fi

# 初始化配置
echo "[6/6] 初始化配置..."
openclaw init
if [ $? -eq 0 ]; then
    echo "  ✓ 配置初始化完成"
else
    echo "  ⚠ 配置初始化失败，可手动创建配置文件"
fi

echo ""
echo "======================================"
echo "  安装完成！"
echo "======================================"
echo ""
echo "下一步："
echo "1. 编辑配置文件：$OPENCLAW_DIR/openclaw.json"
echo "2. 配置飞书/Telegram 凭证"
echo "3. 配置模型 API Key"
echo "4. 启动服务：openclaw gateway"
echo ""

使用方法：

# 1. 下载脚本
curl -O https://example.com/install-openclaw.sh

# 2. 赋予执行权限
chmod +x install-openclaw.sh

# 3. 执行脚本
bash install-openclaw.sh

芯片性能对比

附录：目录结构

/Users/<用户名>/.openclaw/
├── openclaw.json           # 主配置文件
├── .env                    # 环境变量（API Keys）
├── logs/
│   └── gateway.log        # Gateway 日志
├── workspace/             # 工作空间
│   ├── SOUL.md           # Agent 身份定义
│   ├── AGENTS.md         # Agent 配置
│   ├── MEMORY.md         # 长期记忆
│   └── skills/           # 已安装技能
└── cron/
    └── jobs.json         # 定时任务配置

参考资源

工程师 🔧 | 文档版本：v1.0 | 最后更新：2026-03-09