macOS 安装方法 1：Docker 安装（推荐）

这是官方推荐的 macOS 安装方式。通过 Docker Desktop 容器技术，你可以获得最佳的隔离性和安全性，避免与系统其他软件冲突。

安装方式	推荐等级	隔离性	资源占用	适用场景
Docker	⭐⭐⭐⭐⭐ 推荐	优秀	可忽略	大多数用户的首选
直接安装	⭐⭐ 不推荐	无	最低	仅限无敏感数据的专用 Mac

为什么推荐 Docker 安装？

环境隔离：OpenClaw 运行在独立容器中，不影响 macOS 系统
易于管理：一键启动、停止、升级
可重复性：在任何 Mac 上获得一致的运行环境
安全性：容器隔离降低潜在风险
易于卸载：删除容器即可完全清理，不留系统残留

前置条件

macOS 12 (Monterey) 或更高版本
Apple Silicon (M1/M2/M3) 或 Intel 芯片
至少 4GB 可用内存
至少 15GB 可用磁盘空间
管理员权限

遇到任何安装失败，请直接看文末的失败指引。

步骤 1：安装 Docker Desktop

先执行共享安装步骤：

Docker 安装（共享步骤）

在共享页中，选择“macOS 安装 Docker Desktop”章节执行完成后，再继续本页后续步骤。

步骤 2：启动 Docker Desktop

首次启动 Docker Desktop 时：

授权权限：macOS 会请求管理员权限以安装网络组件
完成设置向导：按照提示完成初始设置（可跳过教程）
等待启动：菜单栏出现 Docker 鲸鱼图标，表示 Docker 正在运行

判断"没问题"可以看这几点：

菜单栏出现 Docker 鲸鱼图标（不闪烁）
点击图标显示 "Docker Desktop is running"
终端运行 docker --version 能正常输出版本号

示例输出：

Docker version 27.0.0, build 1234567

步骤 3：配置 Docker 镜像加速（推荐先做）

点击菜单栏 Docker 图标 → Settings (Preferences) 进行配置：

资源分配：

保持默认即可
如果你的机器较老、同时跑很多软件，或后续下载了大量镜像再按需调高

Docker Engine 配置：

在 Docker Engine 设置中添加国内镜像加速器（如果网络较慢）：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

点击 "Apply & Restart" 使配置生效。

步骤 4：验证 Docker 安装

打开终端（Terminal 或 iTerm2），运行：

# 检查 Docker 版本
docker --version

# 运行测试容器
docker run hello-world

如果看到 "Hello from Docker!" 消息，说明 Docker 已正确安装。

以下步骤与 OpenClaw 官方 Docker 文档一致：在仓库根目录用 Compose 跑 openclaw-gateway / openclaw-cli，本地构建镜像。

步骤 5：获取 OpenClaw 源码

git clone https://github.com/openclaw/openclaw.git
cd openclaw

后续所有 docker compose 命令均应在该仓库根目录执行（与官方一致）。

步骤 6：一键安装（推荐）

./docker-setup.sh

脚本会：构建 Gateway 镜像、运行新手引导、可选提供商提示、用 Docker Compose 启动 Gateway、生成令牌并写入项目根目录的 .env。

可选环境变量（在运行 ./docker-setup.sh 之前导出，见官方文档）：

变量	作用
`OPENCLAW_DOCKER_APT_PACKAGES`	构建镜像时额外安装的 apt 包（空格分隔）
`OPENCLAW_EXTRA_MOUNTS`	额外主机绑定挂载（逗号分隔列表；macOS/Windows 路径须在 Docker Desktop 中允许共享）
`OPENCLAW_HOME_VOLUME`	用命名卷持久化容器内 `/home/node`

若设置了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，脚本会生成 docker-compose.extra.yml。之后执行 Compose 时需带上该文件，例如：

docker compose -f docker-compose.yml -f docker-compose.extra.yml up -d

步骤 7：手动流程（可选）

与官方「手动流程」一致，仍在仓库根目录执行：

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

步骤 8：完成后的访问与令牌

浏览器打开：http://127.0.0.1:18789/
在控制 UI（设置 → token）粘贴网关令牌（docker-setup.sh 会写入 .env）
需要带令牌的仪表板链接且不自动打开浏览器时：

docker compose run --rm openclaw-cli dashboard --no-open

若出现未授权或配对提示，官方建议：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

主机侧配置与工作区路径（官方说明）：~/.openclaw/、~/.openclaw/workspace。

验证安装

docker compose ps

健康检查（需能读取 .env 中的 OPENCLAW_GATEWAY_TOKEN，例如先 export 该变量）：

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

常用命令

均在克隆下来的 openclaw 仓库根目录执行；若你使用了 docker-compose.extra.yml，把下面的 docker compose 换成带 -f docker-compose.yml -f docker-compose.extra.yml 的形式。

# 网关日志
docker compose logs -f openclaw-gateway

# 停止 / 启动
docker compose down
docker compose up -d

# 代码更新后重建并启动
docker compose build && docker compose up -d

# CLI 一次性任务
docker compose run --rm openclaw-cli dashboard --no-open

# 进入网关容器调试（示例）
docker compose exec openclaw-gateway sh

数据持久化说明

官方 Compose 会把配置与工作区落在主机 ~/.openclaw/ 与 ~/.openclaw/workspace。默认镜像以非 root 用户 node（uid 1000）运行；若在挂载目录上出现权限问题，可参考官方文档在 Linux 上对目录做 chown（macOS 上多数情况由 Docker Desktop 处理绑定挂载）。

备份示例：

tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz -C ~ .openclaw
# 恢复
tar -xzf openclaw-backup-20240101.tar.gz -C ~

失败指引（折叠）

安装或运行失败时请展开

1. Docker Desktop 安装失败

"Docker Desktop is damaged" 错误

macOS 安全机制可能阻止未签名应用：

# 移除隔离属性
sudo xattr -cr /Applications/Docker.app

Apple Silicon 安装问题

确保下载了正确版本：

检查芯片：点击苹果菜单 → "关于本机"
M1/M2/M3 芯片：下载 "Mac with Apple silicon" 版本
Intel 芯片：下载 "Mac with Intel chip" 版本

Homebrew 安装失败

# 更新 Homebrew
brew update

# 清理旧版本
brew uninstall docker
brew install --cask docker

2. Docker Desktop 无法启动

虚拟化未启用

Apple Silicon Mac：

确保 macOS 为 12.0 或更高版本
重启 Mac 并按住电源键进入恢复模式
在"实用工具"中启用虚拟化

Intel Mac：

重启并按住 Command+R 进入恢复模式
打开"终端"，运行 csrutil enable
重启

权限问题

# 重置 Docker 权限
sudo /Applications/Docker.app/Contents/MacOS/Docker --uninstall
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

# 重新安装
open /Applications/Docker.app

网络问题

# 重置 Docker 网络
# 在 Docker Desktop 菜单中：Troubleshoot → Reset to factory defaults

3. 网关容器无法启动

端口已被占用

lsof -i :18789
# 结束占用进程后，在 openclaw 仓库根目录重启
# docker compose down && docker compose up -d

权限 / 挂载问题

chmod 700 ~/.openclaw
ls -la ~/.openclaw
# 查看网关日志
cd /path/to/openclaw && docker compose logs openclaw-gateway

4. 性能问题

内存不足

调整 Docker Desktop 资源分配：

点击菜单栏 Docker 图标 → Settings
进入 Resources 标签
增加 Memory 到 4GB 或更多
点击 "Apply & Restart"

磁盘空间不足

# 查看 Docker 占用空间
docker system df

# 清理未使用的资源
docker system prune -a

# 在 Docker Desktop 中清理
# Settings → Resources → Advanced → Clean / Purge data

Apple Silicon 与本机构建镜像

本地 docker build 得到的镜像名一般为 openclaw:local（以官方 Dockerfile 为准）。可检查架构：

docker inspect openclaw:local | grep Architecture

5. 网络连接问题

无法拉取镜像

配置镜像加速器：

Docker Desktop → Settings → Docker Engine
添加配置：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live"
  ]
}

点击 "Apply & Restart"

VPN 冲突

如果使用 VPN：

在 Docker Desktop → Settings → Resources → Network 中配置代理
或临时禁用 VPN 测试

6. `docker build` 或基础镜像拉取失败

官方流程需要拉取 Dockerfile 中的基础镜像（如 node 等）。若超时或失败：

确认已按上文「步骤 3：配置 Docker 镜像加速」完成镜像源设置
检查代理 / VPN 是否与 Docker Desktop 网络设置冲突
在仓库根目录重试：docker build -t openclaw:local -f Dockerfile .

7. 网关容器启动后立即退出

cd /path/to/openclaw
docker compose logs openclaw-gateway
ls -la ~/.openclaw/

# 配置异常时可备份后清理再跑引导（在仓库根目录）
# docker compose run --rm openclaw-cli onboard

8. macOS 防火墙阻止连接

系统偏好设置 → 安全性与隐私 → 防火墙

点击"防火墙选项"
确保 "Docker" 允许传入连接
或临时关闭防火墙测试

9. 完全重置 Docker Desktop

警告：这会删除所有容器、镜像和数据

点击菜单栏 Docker 图标 → Troubleshoot
选择 "Reset to factory defaults"
确认重置
备份并删除 OpenClaw 数据：

tar -czf openclaw-backup.tar.gz ~/.openclaw
rm -rf ~/.openclaw

10. 卸载并重新安装 Docker Desktop

# 停止 Docker Desktop
# 在菜单栏点击 Docker 图标 → Quit Docker Desktop

# 卸载
/Applications/Docker.app/Contents/MacOS/Docker --uninstall

# 清理残留文件
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker
rm -rf ~/Library/HTTPStorages/com.docker.docker

# 重新下载并安装
# 访问 https://www.docker.com/products/docker-desktop/