OpenClaw 一般有三种安装方式：全量安装到宿主机 (Host) 、网关 (Gateway) 在宿主机而 Agent 在 Docker (Sandbox) ，以及全量安装到 Docker 。

本文介绍 macOS 平台下的 全量安装到宿主机 (Host) 这一方式，也是三种方式中最简单的一种。

1 准备工作

macOS 用户推荐使用 zsh 作为默认终端，这也是系统默认的终端。

1.1 安装基础工具

Homebrew 是 macOS 上颇受好评或使用最多的包管理工具，我们建议使用它来管理软件包。此外，Xcode Command Line Tools 也是必不可少的，它是编译 llama.cpp 等原生模块的基础环境。

1. 安装 Xcode Command Line Tools ：

xcode-select --install

2. 安装 Homebrew (使用中科大镜像加速) ：
执行如下指令，检测系统是否已安装 Homebrew ，若未安装则通过设置临时环境变量，使用中科大 (USTC) 镜像源安装 Homebrew ：

if ! command -v brew &> /dev/null; then
    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 HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
    /bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"
fi && brew -v

执行上述指令后，终端会提示 Press RETURN/ENTER to continue ，请根据提示按下 回车键 以继续安装。

这段指令执行过后，终端一般会输出几行文字提示你配置环境变量，如果你没有按照提示配置环境变量，大概率会出现 command not found 的提示，此时，如果你是 M 系列芯片，可以先执行如下指令

– Apple Silicon (M 系列) 芯片；

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc && source ~/.zshrc

– Intel 芯片：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc && source ~/.zshrc

而后，再次执行 brew -v

若在安装日志末尾出现类似如下输出，代表安装成功：

# Homebrew 4.4.2

提示（可选步骤）：上述安装方式使用的镜像源是临时的（仅对当前终端会话有效）。如果你希望以后使用 Homebrew 更新软件时依然保持高速，可以选择执行以下指令将镜像源持久化到你的 .zshrc 配置文件中：

tee -a ~/.zshrc > /dev/null << 'EOF'
# Homebrew Mirror Config
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 HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
EOF

执行如下指令，使配置立即生效：

source ~/.zshrc

3. 安装 CMake ：

执行如下指令，检测系统是否已安装 CMake ，若未安装则通过 Homebrew 进行安装并验证版本：

if ! command -v cmake &> /dev/null; then brew install cmake; fi && cmake --version

若在安装日志末尾出现类似如下输出，代表安装成功：

# cmake version 3.31.0

1.2 安装 nvm

执行如下指令，检测系统是否已安装 nvm ，若未安装则通过 Homebrew 进行安装：

if ! command -v nvm &> /dev/null; then brew install nvm; fi

执行如下指令，一次性完成 nvm 工作目录创建及环境变量配置。请根据你的芯片类型选择对应指令：

npm config set registry https://registry.npmmirror.com

或者使用

mkdir -p ~/.nvm && tee -a ~/.zshrc > /dev/null << 'EOF'
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"  # This loads nvm
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"  # This loads nvm bash_completion
EOF

执行如下指令，使刚才的配置立即生效并验证版本：

source ~/.zshrc && nvm -v

若在安装日志末尾出现类似如下输出，代表安装成功：

# 0.40.4

2 开始安装

完成上述 macOS 特有的环境初始化后，后续介绍 Node.js 安装及 OpenClaw 配置流程。–version

2.1 安装 node

请按照顺序执行如下指令

1. 设置 nvm 使用阿里镜像加速下载

tee -a ~/.zshrc > /dev/null << 'EOF'
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_NPM_MIRROR=https://npmmirror.com/mirrors/npm
EOF

2. 按照 openclaw 官方推荐，安装版本号为 22 的 node

nvm install v22

3. 检测是否安装成功

node -v

出现类似如下输出，代表安装成功：

# v22.22.0

npm -v

出现类似如下输出，代表安装成功：

# 10.9.4

2.2 安装 openclaw

请按照顺序执行如下指令

1. 设置 npm 使用阿里镜像加速下载

npm config -g set registry https://registry.npmmirror.com

2. 安装 openclaw （安装到 node 所在目录）；

npm i -g openclaw

提示：如果在安装过程中遇到 GitHub 访问错误（如 npm error code 128），请查阅 附录。

3. 检测是否安装成功。

出现类似如下输出，代表安装成功：

附录：

Q：在安装 openclaw 或访问 GitHub 过程中，终端抛出类似如下错误：

# npm error code 128
# npm error An unknown git error occurred
# npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
# npm error Connection closed by 127.0.0.1 port 7897
# npm error fatal: Could not read from remote repository.
# npm error Please make sure you have the correct access rights and the repository exists.

A：这是因为 openclaw 的部分三方依赖（如 libsignal-node）托管在 GitHub 仓库中，且配置为通过 SSH 协议进行访问。如果你的服务器未配置 GitHub 的 SSH 密钥，或者 SSH 代理连接中断，则会导致权限验证失败。

解决方案一：Git 协议替换（推荐）

在终端执行以下指令，强制 Git 使用 HTTPS 协议代替 SSH 协议访问 GitHub。这种方式通常不需要配置任何密钥，能解决大部分环境下的权限问题：

# 临时方案（推荐）：在安装 openclaw 前执行

git config --global url."https://github.com/whiskeysockets/".insteadOf "ssh://git@github.com/whiskeysockets/"

或者，在安装命令前加环境变量（某些 npm 版本支持）：

GIT_SSL_NO_VERIFY=true npm i -g openclaw

解决方案二：手动配置 SSH 密钥

如果方案一无效，请按照以下步骤为你的服务器配置 GitHub SSH 密钥：

1. 生成 SSH 密钥（如果已有密钥可跳过此步）：
在终端执行以下指令，并将邮箱替换为你自己的 GitHub 邮箱；

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

提示：一路回车即可，无需设置密码。

2. 获取公钥内容：
执行以下指令查看并复制输出的内容；

cat ~/.ssh/id_ed25519.pub

3. 添加到 GitHub：
复制上述以 ssh-ed25519 开头的整行内容，登录 GitHub，进入 SSH and GPG keys 页面，点击 New SSH key，将内容粘贴进去并保存；

4. 验证连接：
执行以下指令，若看到 Hi [你的用户名]! You’ve successfully authenticated 则表示配置成功。

ssh -T git@github.com