OpenClaw macOS 完整安装指南

本指南提供在 macOS 系统上安装 OpenClaw 的完整详细步骤,每一步都包含具体的命令和预期结果。

📋 目录

  1. 安装前准备

  2. 安装必要软件

  3. 配置环境

  4. [安装 OpenClaw](#安装 OpenClaw "#%E5%AE%89%E8%A3%85-openclaw")

  5. [配置 OpenClaw](#配置 OpenClaw "#%E9%85%8D%E7%BD%AE-openclaw")

  6. 启动服务

  7. 配置认证

  8. 验证安装

  9. 配置开机自启动

  10. 常见问题解决


安装前准备

步骤 1:检查 macOS 版本

在终端中执行:

bash 复制代码
sw_vers

预期结果

makefile 复制代码
ProductName:    macOS

ProductVersion: 14.x.x

BuildVersion:   23xxx

要求:macOS 12.0 或更高版本

步骤 2:打开终端

方法 1:使用聚焦搜索

  1. Command + 空格 打开聚焦搜索

  2. 输入"终端"

  3. 按 Enter 打开终端

方法 2:使用 Launchpad

  1. 点击 Dock 中的 Launchpad 图标

  2. 搜索"终端"

  3. 点击打开

步骤 3:检查当前 Shell

bash 复制代码
echo $SHELL

预期结果

bash 复制代码
/bin/zsh

如果是 /bin/bash,建议升级到 zsh(macOS Catalina 及更高版本默认使用 zsh)


安装必要软件

步骤 4:检查 Xcode Command Line Tools

bash 复制代码
xcode-select -p

预期结果

复制代码
/Applications/Xcode.app/Contents/Developer

如果提示未安装

bash 复制代码
xcode-select --install

会弹出安装窗口,点击"安装"并等待完成

步骤 5:安装 Homebrew

**官方安装方式(推荐) **:

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

安装过程

  1. 按 Enter 继续

  2. 输入 macOS 密码(输入时不会显示字符)

  3. 等待安装完成(可能需要 5-10 分钟)

安装完成后

bash 复制代码
# 添加 Homebrew 到 PATH(根据你的芯片架构选择)

# Apple Silicon (M1/M2/M3):

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

eval "$(/opt/homebrew/bin/brew shellenv)"

  


# Intel Mac:

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

eval "$(/usr/local/bin/brew shellenv)"

  


# 验证安装

brew --version

预期结果

复制代码
Homebrew 4.x.x

如果官方安装卡住,使用国内镜像源

bash 复制代码
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

步骤 6:安装 Git

bash 复制代码
brew install git

验证安装

bash 复制代码
git --version

预期结果

复制代码
git version 2.x.x

步骤 7:配置 Git

bash 复制代码
git config --global user.name "Your Name"

git config --global user.email "your.email@example.com"

git config --global core.autocrlf input

验证配置

bash 复制代码
git config --list

预期结果:显示包含 user.name 和 user.email 的配置列表

步骤 8:安装 Node.js

bash 复制代码
brew install node

验证安装

bash 复制代码
node --version

npm --version

预期结果

复制代码
v20.x.x

10.x.x

要求:Node.js 16.0 或更高版本


配置环境

步骤 9:配置 npm 使用国内镜像源

bash 复制代码
npm config set registry https://registry.npmmirror.com

验证配置

bash 复制代码
npm config get registry

预期结果

arduino 复制代码
https://registry.npmmirror.com

步骤 10:配置 Git 使用 HTTPS 协议

bash 复制代码
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

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

验证配置

bash 复制代码
git config --list | grep url

预期结果

perl 复制代码
url.https://github.com/.insteadof=ssh://git@github.com/

url.https://github.com/.insteadof=git@github.com:

步骤 11:清除 npm 缓存

bash 复制代码
npm cache clean --force

预期结果

sql 复制代码
npm WARN using --force

I sure hope you know what you are doing.

步骤 12:配置 Shell 别名(可选但推荐)

编辑 .zshrc 文件:

bash 复制代码
nano ~/.zshrc

在文件末尾添加以下内容:

bash 复制代码
# OpenClaw 别名

alias oc='openclaw'

alias oc-start='openclaw start'

alias oc-stop='openclaw stop'

alias oc-status='openclaw status'

alias oc-logs='openclaw logs'

alias oc-restart='openclaw restart'

  


# Git 别名

alias gs='git status'

alias ga='git add'

alias gc='git commit'

alias gp='git push'

alias gl='git log --oneline'

  


# 系统别名

alias ll='ls -la'

alias c='clear'

alias h='cd ~'

保存并退出:

  1. Control + X

  2. Y

  3. Enter

重新加载配置:

bash 复制代码
source ~/.zshrc

安装 OpenClaw

步骤 13:查看 OpenClaw 可用版本

bash 复制代码
npm view openclaw versions --json

预期结果:显示所有可用版本的列表

步骤 14:安装 OpenClaw

**方法 A:使用 npm 安装(推荐) **

bash 复制代码
npm install -g openclaw@latest

预期结果

复制代码
added XX packages in XXs

方法 B:如果方法 A 失败,使用 legacy peer deps

bash 复制代码
npm install -g openclaw@latest --legacy-peer-deps

方法 C:如果 npm 安装失败,使用 pnpm

bash 复制代码
# 安装 pnpm

npm install -g pnpm

  


# 配置 pnpm 镜像源

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

  


# 使用 pnpm 安装 OpenClaw

pnpm add -g openclaw@latest

步骤 15:验证 OpenClaw 安装

bash 复制代码
openclaw --version

预期结果

复制代码
openclaw/2026.3.13 darwin-arm64 node-v20.x.x

如果提示找不到命令

bash 复制代码
# 查看 npm 全局安装路径

npm config get prefix

  


# 查看 npm 全局 bin 路径

npm bin -g

  


# 手动添加到 PATH(临时)

export PATH="$(npm bin -g):$PATH"

  


# 再次验证

openclaw --version

永久添加到 PATH

bash 复制代码
# 编辑 .zshrc

nano ~/.zshrc

  


# 在文件末尾添加(根据你的 npm bin 路径调整)

export PATH="/opt/homebrew/bin:$PATH"

# 或者

export PATH="/usr/local/bin:$PATH"

  


# 保存并退出

# 按 Control + X,然后 Y,然后 Enter

  


# 重新加载配置

source ~/.zshrc

  


# 验证

openclaw --version

配置 OpenClaw

步骤 16:初始化 OpenClaw

bash 复制代码
openclaw init

向导会询问以下问题

问题 1:Gateway 运行位置

  • 输入:local

  • 按 Enter

问题 2:认证方式

  • 输入:oauth(推荐)或 api-key

  • 按 Enter

问题 3:工作区路径

  • 直接按 Enter 使用默认值(~/.openclaw/workspace

问题 4:端口配置

  • 直接按 Enter 使用默认值(3000

预期结果

arduino 复制代码
✓ OpenClaw initialized successfully

✓ Configuration saved to /Users/你的用户名/.openclaw/config.json

步骤 17:检查配置文件

bash 复制代码
cat ~/.openclaw/config.json

预期内容

json 复制代码
{

  "gateway": {

    "mode": "local",

    "host": "localhost",

    "port": 3000,

    "auth": {

      "enabled": true,

      "type": "token"

    }

  },

  "workspace": "/Users/你的用户名/.openclaw/workspace",

  "logging": {

    "level": "info"

  }

}

步骤 18:创建必要的目录

bash 复制代码
mkdir -p ~/.openclaw/credentials

mkdir -p ~/.openclaw/workspace

mkdir -p ~/.openclaw/agents

验证目录创建

bash 复制代码
ls -la ~/.openclaw/

预期结果

erlang 复制代码
total 0

drwxr-xr-x  5 username  staff  160 Mar 15 18:00 .

drwxr-xr-x+ 5 username  staff  160 Mar 15 18:00 ..

drwxr-xr-x  2 username  staff   64 Mar 15 18:00 agents

drwxr-xr-x  2 username  staff   64 Mar 15 18:00 credentials

-rw-r--r--  1 username  staff  256 Mar 15 18:00 config.json

drwxr-xr-x  2 username  staff   64 Mar 15 18:00 workspace

启动服务

步骤 19:启动 OpenClaw Gateway

bash 复制代码
openclaw start

预期结果

javascript 复制代码
✓ OpenClaw Gateway started successfully

✓ Listening on http://localhost:3000

✓ Workspace: /Users/你的用户名/.openclaw/workspace

步骤 20:检查服务状态

bash 复制代码
openclaw status

预期结果

yaml 复制代码
Gateway Status: Running

PID: 12345

Port: 3000

Uptime: 0:00:05

步骤 21:查看日志

bash 复制代码
openclaw logs

预期结果:显示实时日志输出

Control + C 停止查看日志(不会停止服务)

步骤 22:查看最近日志

bash 复制代码
openclaw logs --tail 50

预期结果:显示最近 50 行日志


配置认证

步骤 23:使用 Anthropic OAuth 认证(推荐)

bash 复制代码
openclaw auth oauth

预期结果

r 复制代码
Opening browser for OAuth authentication...

浏览器会自动打开,执行以下操作:

  1. 登录你的 Anthropic 账户(Claude Pro/Max)

  2. 授权 OpenClaw 访问

  3. 复制显示的 code#state

在终端中粘贴并验证

bash 复制代码
openclaw auth verify "YOUR_CODE#STATE_VALUE"

预期结果

bash 复制代码
✓ OAuth authentication successful

✓ Credentials saved to /Users/你的用户名/.openclaw/credentials/oauth.json

步骤 24:验证认证状态

bash 复制代码
openclaw auth status

预期结果

yaml 复制代码
Authentication Status: ✓ Connected

Provider: Anthropic OAuth

Account: your@email.com

Expires: 2026-04-15

备选方案:使用 API Key

如果你有 Anthropic API Key:

bash 复制代码
openclaw auth api-key YOUR_ANTHROPIC_API_KEY

验证安装

步骤 25:健康检查

bash 复制代码
curl http://localhost:3000/health

预期结果

json 复制代码
{

  "status": "healthy",

  "version": "2026.3.13",

  "uptime": 123

}

步骤 26:测试 AI 调用

bash 复制代码
openclaw chat "Hello, can you hear me?"

预期结果

vbnet 复制代码
Assistant: Yes, I can hear you! I'm ready to help you with your tasks.

步骤 27:检查工作区文件

bash 复制代码
ls -la ~/.openclaw/workspace/

预期结果

diff 复制代码
total 32

drwxr-xr-x  5 username  staff  160 Mar 15 18:00 .

drwxr-xr-x  5 username  staff  160 Mar 15 18:00 ..

-rw-r--r--  1 username  staff  256 Mar 15 18:00 AGENTS.md

-rw-r--r--  1 username  staff  256 Mar 15 18:00 IDENTITY.md

-rw-r--r--  1 username  staff  256 Mar 15 18:00 USER.md

-rw-r--r--  1 username  staff  256 Mar 15 18:00 SOUL.md

步骤 28:测试 Webhook(可选)

bash 复制代码
curl -X POST http://localhost:3000/webhook/test \

  -H "Content-Type: application/json" \

  -d '{"message": "test"}'

预期结果

json 复制代码
{

  "status": "success",

  "message": "Webhook test successful"

}

配置开机自启动

步骤 29:创建启动脚本

创建 ~/start-openclaw.sh

bash 复制代码
nano ~/start-openclaw.sh

添加以下内容:

bash 复制代码
#!/bin/bash

  


echo "Starting OpenClaw..."

  


# 检查服务状态

if openclaw status | grep -q "Running"; then

    echo "OpenClaw is already running"

else

    # 启动服务

    openclaw start

    

    # 等待服务启动

    sleep 3

    

    # 检查服务状态

    if openclaw status | grep -q "Running"; then

        echo "OpenClaw started successfully"

    else

        echo "Failed to start OpenClaw"

        exit 1

    fi

fi

  


# 健康检查

curl -s http://localhost:3000/health | python3 -m json.tool

  


echo "OpenClaw is ready!"

保存并退出:

  1. Control + X

  2. Y

  3. Enter

赋予执行权限:

bash 复制代码
chmod +x ~/start-openclaw.sh

步骤 30:创建 Launch Agent 配置

创建 ~/Library/LaunchAgents/com.openclaw.plist

bash 复制代码
nano ~/Library/LaunchAgents/com.openclaw.plist

添加以下内容:

xml 复制代码
<?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</string>

    <key>ProgramArguments</key>

    <array>

        <string>/Users/你的用户名/start-openclaw.sh</string>

    </array>

    <key>RunAtLoad</key>

    <true/>

    <key>KeepAlive</key>

    <true/>

    <key>StandardOutPath</key>

    <string>/tmp/openclaw.log</string>

    <key>StandardErrorPath</key>

    <string>/tmp/openclaw.err</string>

</dict>

</plist>

注意 :将 你的用户名 替换为你的实际用户名

保存并退出:

  1. Control + X

  2. Y

  3. Enter

步骤 31:加载 Launch Agent

bash 复制代码
# 加载配置

launchctl load ~/Library/LaunchAgents/com.openclaw.plist

  


# 启动服务

launchctl start com.openclaw

  


# 检查状态

launchctl list | grep openclaw

预期结果

diff 复制代码
- 0 com.openclaw

步骤 32:验证开机启动

  1. 重启 Mac

  2. 打开终端

  3. 执行:

bash 复制代码
openclaw status

预期结果:显示服务正在运行

步骤 33:管理 Launch Agent

bash 复制代码
# 停止服务

launchctl stop com.openclaw

  


# 卸载配置

launchctl unload ~/Library/LaunchAgents/com.openclaw.plist

  


# 重新加载

launchctl load ~/Library/LaunchAgents/com.openclaw.plist

常见问题解决

问题 1:Homebrew 安装卡住

症状:Homebrew 安装过程中长时间无响应

解决方案

bash 复制代码
# 1. 中断当前安装(Control + C)

  


# 2. 使用国内镜像源重新安装

/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

  


# 3. 安装完成后,配置镜像源

# Apple Silicon:

cd /opt/homebrew

git remote set-url origin https://mirrors.ustc.edu.cn/brew.git

  


# Intel Mac:

cd /usr/local/Homebrew

git remote set-url origin https://mirrors.ustc.edu.cn/brew.git

  


# 4. 更新 Homebrew

brew update

问题 2:找不到 openclaw 命令

症状

bash 复制代码
zsh: command not found: openclaw

解决方案

bash 复制代码
# 1. 查看 npm 全局安装路径

npm config get prefix

  


# 2. 查看 npm 全局 bin 路径

npm bin -g

  


# 3. 手动添加到 PATH(临时)

export PATH="$(npm bin -g):$PATH"

  


# 4. 验证

openclaw --version

  


# 5. 永久添加到 PATH

nano ~/.zshrc

  


# 在文件末尾添加(根据你的 npm bin 路径调整)

export PATH="/opt/homebrew/bin:$PATH"

# 或者

export PATH="/usr/local/bin:$PATH"

  


# 6. 保存并退出

# 按 Control + X,然后 Y,然后 Enter

  


# 7. 重新加载配置

source ~/.zshrc

问题 3:端口被占用

症状

vbnet 复制代码
Error: Port 3000 is already in use

解决方案

bash 复制代码
# 1. 查找占用端口的进程

lsof -i :3000

  


# 2. 杀死进程(替换 PID)

kill -9 PID

  


# 3. 或者更改 OpenClaw 端口

openclaw configure --port 3001

问题 4:Git SSH 权限错误

症状

java 复制代码
git@github.com: Permission denied (publickey)

解决方案

bash 复制代码
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

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

问题 5:依赖安装失败

症状

typescript 复制代码
Error: An unknown git error occurred

解决方案

bash 复制代码
# 方法 1:使用 legacy peer deps

npm install -g openclaw@latest --legacy-peer-deps

  


# 方法 2:清除缓存重试

npm cache clean --force

npm install -g openclaw@latest --legacy-peer-deps

  


# 方法 3:使用 pnpm

npm install -g pnpm

pnpm add -g openclaw@latest

问题 6:服务无法启动

症状

vbnet 复制代码
Error: Failed to start Gateway

解决方案

bash 复制代码
# 1. 查看详细日志

openclaw logs --verbose

  


# 2. 检查配置文件

cat ~/.openclaw/config.json

  


# 3. 重置配置

rm ~/.openclaw/config.json

openclaw init

  


# 4. 重新启动

openclaw start

问题 7:权限错误

症状

javascript 复制代码
Error: Permission denied

解决方案

bash 复制代码
# 1. 修复目录权限

chmod -R 755 ~/.openclaw

  


# 2. 修复文件权限

chmod 644 ~/.openclaw/config.json

chmod 600 ~/.openclaw/credentials/*

问题 8:网络连接问题

症状

javascript 复制代码
Error: Connection refused

解决方案

bash 复制代码
# 1. 检查防火墙设置

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

  


# 2. 检查代理设置

echo $http_proxy

echo $https_proxy

  


# 3. 测试网络连接

curl -I https://api.anthropic.com

  


# 4. 如果需要,配置代理

export http_proxy="http://127.0.0.1:7890"

export https_proxy="http://127.0.0.1:7890"

完整安装检查清单

在完成所有步骤后,确认以下项目:

基础环境

  • macOS 版本已确认(12.0 或更高)

  • 终端已打开

  • Shell 已检查(zsh)

  • Xcode Command Line Tools 已安装

必要软件

  • Homebrew 已安装

  • Git 已安装并配置

  • Node.js 已安装(v20.x 或更高)

  • npm 已安装(v10.x 或更高)

环境配置

  • npm 镜像源已配置

  • Git HTTPS 协议已配置

  • npm 缓存已清除

  • Shell 别名已配置(可选)

OpenClaw 安装

  • OpenClaw 已全局安装

  • openclaw --version 命令可用

  • 配置文件已创建

  • 工作区目录已创建

服务配置

  • Gateway 服务已启动

  • 服务状态检查通过

  • 认证已配置

  • 认证状态检查通过

验证测试

  • 健康检查通过

  • 测试 AI 调用成功

  • 工作区文件已生成

  • 日志输出正常

开机自启动

  • 启动脚本已创建

  • Launch Agent 已配置

  • 服务已加载

  • 开机启动已验证


快速命令参考

服务管理

bash 复制代码
openclaw start      # 启动服务

openclaw stop       # 停止服务

openclaw restart    # 重启服务

openclaw status     # 查看状态

openclaw logs       # 查看日志

配置管理

bash 复制代码
openclaw init       # 初始化配置

openclaw configure  # 重新配置

openclaw config show # 查看配置

认证管理

bash 复制代码
openclaw auth oauth    # OAuth 认证

openclaw auth status   # 查看认证状态

openclaw auth logout  # 登出

Launch Agent 管理

bash 复制代码
launchctl load ~/Library/LaunchAgents/com.openclaw.plist  # 加载配置

launchctl start com.openclaw                          # 启动服务

launchctl stop com.openclaw                           # 停止服务

launchctl unload ~/Library/LaunchAgents/com.openclaw.plist # 卸载配置

常用系统命令

bash 复制代码
~                           # 用户主目录

$HOME                        # 用户主目录环境变量

$PATH                        # PATH 环境变量

npm config get prefix         # npm 全局路径

npm bin -g                  # npm 全局 bin 路径

brew --prefix               # Homebrew 安装路径

终端常用快捷键

| 快捷键 | 功能 |

|--------|------|

| Command + C | 复制选中的文本 |

| Command + V | 粘贴文本 |

| Command + K | 清屏(清除历史记录) |

| Control + C | 中断当前运行的命令 |

| Control + L | 清屏(保留历史记录) |

| Control + A | 移动到行首 |

| Control + E | 移动到行尾 |

| Control + U | 删除到行首 |

| Control + K | 删除到行尾 |

| / | 浏览历史命令 |

| Tab | 自动补全命令或文件名 |


技术支持

获取帮助

相关工具

日志位置

  • OpenClaw 配置 : ~/.openclaw/

  • npm 缓存 : ~/.npm/

  • npm 日志 : ~/.npm/_logs/

  • Launch Agent 日志 : /tmp/openclaw.log


进阶配置

配置环境变量

编辑 ~/.zshrc

bash 复制代码
nano ~/.zshrc

添加以下内容:

bash 复制代码
# OpenClaw 环境变量

export OPENCLAW_HOME="$HOME/.openclaw"

export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"

export OPENCLAW_LOG_LEVEL="info"

重新加载配置:

bash 复制代码
source ~/.zshrc

配置代理

编辑 ~/.zshrc

bash 复制代码
nano ~/.zshrc

添加以下内容:

bash 复制代码
# HTTP/HTTPS 代理

export http_proxy="http://127.0.0.1:7890"

export https_proxy="http://127.0.0.1:7890"

export HTTP_PROXY="http://127.0.0.1:7890"

export HTTPS_PROXY="http://127.0.0.1:7890"

重新加载配置:

bash 复制代码
source ~/.zshrc

配置自动备份

创建 ~/backup-openclaw.sh

bash 复制代码
nano ~/backup-openclaw.sh

添加以下内容:

bash 复制代码
#!/bin/bash

  


BACKUP_DIR="$HOME/.openclaw.backups"

DATE=$(date +%Y%m%d_%H%M%S)

BACKUP_PATH="$BACKUP_DIR/openclaw_$DATE"

  


# 创建备份目录

mkdir -p "$BACKUP_DIR"

  


# 备份配置

cp -r ~/.openclaw "$BACKUP_PATH"

  


# 压缩备份

tar -czf "$BACKUP_PATH.tar.gz" -C "$BACKUP_DIR" "openclaw_$DATE"

rm -rf "$BACKUP_PATH"

  


# 保留最近 7 天的备份

find "$BACKUP_DIR" -name "*.tar.gz" -mtime +7 -delete

  


echo "Backup created: $BACKUP_PATH.tar.gz"

赋予执行权限:

bash 复制代码
chmod +x ~/backup-openclaw.sh

使用:

bash 复制代码
~/backup-openclaw.sh
相关推荐
weixin_382395233 小时前
为小工厂量身打造:本地部署的物料管理系统带缺料计算
前端·制造
__zRainy__4 小时前
解决pnpm v10+不自动构建
前端·pnpm·工程化
猫猫不是喵喵.4 小时前
Vue3 Props 属性
前端·javascript·vue.js
醉城夜风~5 小时前
CSS元素显示模式(display)
前端·css
AI大模型-小华6 小时前
Codex 三方充值快速入门指南
java·前端·数据库·chatgpt·ai编程·codex·chatgpt pro
做前端的娜娜子8 小时前
同一链接实现 PC Web 与移动 H5 自适应
前端·掘金·金石计划
小帅不太帅8 小时前
架构没变、规模没变,DeepSeek V4 Flash 正式版凭什么暴涨 47 分?
前端·aigc·deepseek
jarvisuni9 小时前
DeepSeekFlash前端依旧拉垮,而且变慢了很多!
前端·javascript·算法
卷福同学10 小时前
AI编程出海第二步:验证关键词能否做站
前端·人工智能·后端