OpenClaw macOS 完整安装指南📋 目录安装前准备安装必要软件配置环境安装 OpenClaw 配置

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

📋 目录

安装前准备
安装必要软件
配置环境
安装 OpenClaw
配置 OpenClaw
启动服务
配置认证
验证安装
配置开机自启动
常见问题解决

安装前准备

步骤 1：检查 macOS 版本

在终端中执行：


sw_vers

预期结果：


ProductName:    macOS

ProductVersion: 14.x.x

BuildVersion:   23xxx

要求：macOS 12.0 或更高版本

步骤 2：打开终端

方法 1：使用聚焦搜索

按 Command + 空格 打开聚焦搜索
输入"终端"
按 Enter 打开终端

方法 2：使用 Launchpad

点击 Dock 中的 Launchpad 图标
搜索"终端"
点击打开

步骤 3：检查当前 Shell


echo $SHELL

预期结果：


/bin/zsh

如果是 /bin/bash，建议升级到 zsh（macOS Catalina 及更高版本默认使用 zsh）

安装必要软件

步骤 4：检查 Xcode Command Line Tools


xcode-select -p

预期结果：


/Applications/Xcode.app/Contents/Developer

如果提示未安装：


xcode-select --install

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

步骤 5：安装 Homebrew

**官方安装方式（推荐） **：


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

安装过程：

按 Enter 继续
输入 macOS 密码（输入时不会显示字符）
等待安装完成（可能需要 5-10 分钟）

安装完成后：


# 添加 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

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


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

步骤 6：安装 Git


brew install git

验证安装：


git --version

预期结果：


git version 2.x.x

步骤 7：配置 Git


git config --global user.name "Your Name"

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

git config --global core.autocrlf input

验证配置：


git config --list

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

步骤 8：安装 Node.js


brew install node

验证安装：


node --version

npm --version

预期结果：


v20.x.x

10.x.x

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

配置环境

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


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

验证配置：


npm config get registry

预期结果：


https://registry.npmmirror.com

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


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

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

验证配置：


git config --list | grep url

预期结果：


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

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

步骤 11：清除 npm 缓存


npm cache clean --force

预期结果：


npm WARN using --force

I sure hope you know what you are doing.

步骤 12：配置 Shell 别名（可选但推荐）

编辑 .zshrc 文件：


nano ~/.zshrc

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


# 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 ~'

保存并退出：

按 Control + X
按 Y
按 Enter

重新加载配置：


source ~/.zshrc

安装 OpenClaw

步骤 13：查看 OpenClaw 可用版本


npm view openclaw versions --json

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

步骤 14：安装 OpenClaw

**方法 A：使用 npm 安装（推荐） **


npm install -g openclaw@latest

预期结果：


added XX packages in XXs

方法 B：如果方法 A 失败，使用 legacy peer deps


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

方法 C：如果 npm 安装失败，使用 pnpm


# 安装 pnpm

npm install -g pnpm

  


# 配置 pnpm 镜像源

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

  


# 使用 pnpm 安装 OpenClaw

pnpm add -g openclaw@latest

步骤 15：验证 OpenClaw 安装


openclaw --version

预期结果：


openclaw/2026.3.13 darwin-arm64 node-v20.x.x

如果提示找不到命令：


# 查看 npm 全局安装路径

npm config get prefix

  


# 查看 npm 全局 bin 路径

npm bin -g

  


# 手动添加到 PATH（临时）

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

  


# 再次验证

openclaw --version

永久添加到 PATH：


# 编辑 .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


openclaw init

向导会询问以下问题：

问题 1：Gateway 运行位置

输入：local
按 Enter

问题 2：认证方式

输入：oauth（推荐）或 api-key
按 Enter

问题 3：工作区路径

直接按 Enter 使用默认值（~/.openclaw/workspace）

问题 4：端口配置

直接按 Enter 使用默认值（3000）

预期结果：


✓ OpenClaw initialized successfully

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

步骤 17：检查配置文件


cat ~/.openclaw/config.json

预期内容：


{

  "gateway": {

    "mode": "local",

    "host": "localhost",

    "port": 3000,

    "auth": {

      "enabled": true,

      "type": "token"

    }

  },

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

  "logging": {

    "level": "info"

  }

}

步骤 18：创建必要的目录


mkdir -p ~/.openclaw/credentials

mkdir -p ~/.openclaw/workspace

mkdir -p ~/.openclaw/agents

验证目录创建：


ls -la ~/.openclaw/

预期结果：


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


openclaw start

预期结果：


✓ OpenClaw Gateway started successfully

✓ Listening on http://localhost:3000

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

步骤 20：检查服务状态


openclaw status

预期结果：


Gateway Status: Running

PID: 12345

Port: 3000

Uptime: 0:00:05

步骤 21：查看日志


openclaw logs

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

按 Control + C 停止查看日志（不会停止服务）

步骤 22：查看最近日志


openclaw logs --tail 50

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

配置认证

步骤 23：使用 Anthropic OAuth 认证（推荐）


openclaw auth oauth

预期结果：


Opening browser for OAuth authentication...

浏览器会自动打开，执行以下操作：

登录你的 Anthropic 账户（Claude Pro/Max）
授权 OpenClaw 访问
复制显示的 code#state 值

在终端中粘贴并验证：


openclaw auth verify "YOUR_CODE#STATE_VALUE"

预期结果：


✓ OAuth authentication successful

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

步骤 24：验证认证状态


openclaw auth status

预期结果：


Authentication Status: ✓ Connected

Provider: Anthropic OAuth

Account: your@email.com

Expires: 2026-04-15

备选方案：使用 API Key

如果你有 Anthropic API Key：


openclaw auth api-key YOUR_ANTHROPIC_API_KEY

验证安装

步骤 25：健康检查


curl http://localhost:3000/health

预期结果：


{

  "status": "healthy",

  "version": "2026.3.13",

  "uptime": 123

}

步骤 26：测试 AI 调用


openclaw chat "Hello, can you hear me?"

预期结果：


Assistant: Yes, I can hear you! I'm ready to help you with your tasks.

步骤 27：检查工作区文件


ls -la ~/.openclaw/workspace/

预期结果：


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（可选）


curl -X POST http://localhost:3000/webhook/test \

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

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

预期结果：


{

  "status": "success",

  "message": "Webhook test successful"

}

配置开机自启动

步骤 29：创建启动脚本

创建 ~/start-openclaw.sh：


nano ~/start-openclaw.sh

添加以下内容：


#!/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!"

保存并退出：

按 Control + X
按 Y
按 Enter

赋予执行权限：


chmod +x ~/start-openclaw.sh

步骤 30：创建 Launch Agent 配置

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


nano ~/Library/LaunchAgents/com.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>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>

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

保存并退出：

按 Control + X
按 Y
按 Enter

步骤 31：加载 Launch Agent


# 加载配置

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

  


# 启动服务

launchctl start com.openclaw

  


# 检查状态

launchctl list | grep openclaw

预期结果：


- 0 com.openclaw

步骤 32：验证开机启动

重启 Mac
打开终端
执行：


openclaw status

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

步骤 33：管理 Launch Agent


# 停止服务

launchctl stop com.openclaw

  


# 卸载配置

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

  


# 重新加载

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

常见问题解决

问题 1：Homebrew 安装卡住

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

解决方案：


# 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 命令

症状：


zsh: command not found: openclaw

解决方案：


# 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：端口被占用

症状：


Error: Port 3000 is already in use

解决方案：


# 1. 查找占用端口的进程

lsof -i :3000

  


# 2. 杀死进程（替换 PID）

kill -9 PID

  


# 3. 或者更改 OpenClaw 端口

openclaw configure --port 3001

问题 4：Git SSH 权限错误

症状：


git@github.com: Permission denied (publickey)

解决方案：


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

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

问题 5：依赖安装失败

症状：


Error: An unknown git error occurred

解决方案：


# 方法 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：服务无法启动

症状：


Error: Failed to start Gateway

解决方案：


# 1. 查看详细日志

openclaw logs --verbose

  


# 2. 检查配置文件

cat ~/.openclaw/config.json

  


# 3. 重置配置

rm ~/.openclaw/config.json

openclaw init

  


# 4. 重新启动

openclaw start

问题 7：权限错误

症状：


Error: Permission denied

解决方案：


# 1. 修复目录权限

chmod -R 755 ~/.openclaw

  


# 2. 修复文件权限

chmod 644 ~/.openclaw/config.json

chmod 600 ~/.openclaw/credentials/*

问题 8：网络连接问题

症状：


Error: Connection refused

解决方案：


# 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 已配置
服务已加载
开机启动已验证

快速命令参考

服务管理


openclaw start      # 启动服务

openclaw stop       # 停止服务

openclaw restart    # 重启服务

openclaw status     # 查看状态

openclaw logs       # 查看日志

配置管理


openclaw init       # 初始化配置

openclaw configure  # 重新配置

openclaw config show # 查看配置

认证管理


openclaw auth oauth    # OAuth 认证

openclaw auth status   # 查看认证状态

openclaw auth logout  # 登出

Launch Agent 管理


launchctl load ~/Library/LaunchAgents/com.openclaw.plist  # 加载配置

launchctl start com.openclaw                          # 启动服务

launchctl stop com.openclaw                           # 停止服务

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

常用系统命令


~                           # 用户主目录

$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 官方文档: docs.openclaw.ai
OpenClaw GitHub: github.com/openclaw/op…
问题反馈: github.com/openclaw/op…
新手引导: docs.openclaw.ai/zh-CN/start…

日志位置

OpenClaw 配置: ~/.openclaw/
npm 缓存: ~/.npm/
npm 日志: ~/.npm/_logs/
Launch Agent 日志: /tmp/openclaw.log

进阶配置

配置环境变量

编辑 ~/.zshrc：


nano ~/.zshrc

添加以下内容：


# OpenClaw 环境变量

export OPENCLAW_HOME="$HOME/.openclaw"

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

export OPENCLAW_LOG_LEVEL="info"

重新加载配置：


source ~/.zshrc

配置代理

编辑 ~/.zshrc：


nano ~/.zshrc

添加以下内容：


# 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"

重新加载配置：


source ~/.zshrc

配置自动备份

创建 ~/backup-openclaw.sh：


nano ~/backup-openclaw.sh

添加以下内容：


#!/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"

赋予执行权限：


chmod +x ~/backup-openclaw.sh

使用：


~/backup-openclaw.sh

OpenClaw macOS 完整安装指南

📋 目录

安装前准备

步骤 1：检查 macOS 版本

步骤 2：打开终端

步骤 3：检查当前 Shell

安装必要软件

步骤 4：检查 Xcode Command Line Tools

步骤 5：安装 Homebrew

步骤 6：安装 Git

步骤 7：配置 Git

步骤 8：安装 Node.js

配置环境

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

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

步骤 11：清除 npm 缓存

步骤 12：配置 Shell 别名（可选但推荐）

安装 OpenClaw

步骤 13：查看 OpenClaw 可用版本

步骤 14：安装 OpenClaw

步骤 15：验证 OpenClaw 安装

配置 OpenClaw

步骤 16：初始化 OpenClaw

步骤 17：检查配置文件

步骤 18：创建必要的目录

启动服务

步骤 19：启动 OpenClaw Gateway

步骤 20：检查服务状态

步骤 21：查看日志

步骤 22：查看最近日志

配置认证

步骤 23：使用 Anthropic OAuth 认证（推荐）

步骤 24：验证认证状态

验证安装

步骤 25：健康检查

步骤 26：测试 AI 调用

步骤 27：检查工作区文件

步骤 28：测试 Webhook（可选）

配置开机自启动

步骤 29：创建启动脚本

步骤 30：创建 Launch Agent 配置

步骤 31：加载 Launch Agent

步骤 32：验证开机启动

步骤 33：管理 Launch Agent

常见问题解决

问题 1：Homebrew 安装卡住

问题 2：找不到 openclaw 命令

问题 3：端口被占用

问题 4：Git SSH 权限错误

问题 5：依赖安装失败

问题 6：服务无法启动

问题 7：权限错误

问题 8：网络连接问题

完整安装检查清单

基础环境

必要软件

环境配置

OpenClaw 安装

服务配置

验证测试

开机自启动

快速命令参考

服务管理

配置管理

认证管理

Launch Agent 管理

常用系统命令

终端常用快捷键

技术支持

获取帮助

相关工具

日志位置

进阶配置

配置环境变量

配置代理

配置自动备份