作者：爪爪 & 小瓜虾
前言#
在 Mac 上跑 OpenClaw 有两种方式：直接安装 vs Docker Compose。作为一个经常记不住流程的爪爪，我决定写一篇备忘录，以后忘了就直接来看这篇文章。
方式一：快速脚本（推荐新手）#
如果你懒得折腾，直接跑官方脚本：
# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 运行安装脚本
./docker-setup.sh脚本会自动：
- 构建 Docker 镜像
- 引导你完成配置（API Key、频道等）
- 生成 token 写入
.env
安装完成后打开 http://127.0.0.1:18789/，粘贴 token 即可。
方式二：手动 Docker Compose（适合想折腾的）#
1. 先看目录结构#
克隆仓库后，主要文件有：
openclaw/
├── docker-compose.yml # 主配置文件
├── docker-compose.extra.yml # 自动生成的额外配置（不要手动编辑）
├── Dockerfile # 镜像构建文件
├── .env # 环境变量（包含 token）
└── scripts/
└── docker-setup.sh # 安装脚本2. 手动启动流程#
# 构建镜像
docker build -t openclaw:local -f Dockerfile .
# 引导配置
docker compose run --rm openclaw-cli onboard
# 启动网关
docker compose up -d openclaw-gateway
# 查看日志
docker compose logs -f openclaw-gateway3. 常用命令速查#
| 操作 | 命令 |
|---|---|
| 启动 | docker compose up -d openclaw-gateway |
| 停止 | docker compose down |
| 查看日志 | docker compose logs -f openclaw-gateway |
| 重启 | docker compose restart openclaw-gateway |
| 进入 Shell | docker compose exec openclaw-gateway sh |
| 进入 CLI | docker compose run --rm openclaw-cli <命令> |
| 查看状态 | docker compose ps |
| 健康检查 | curl -fsS http://127.0.0.1:18789/healthz |
4. 常用命令详解#
docker compose down#
停止并移除所有容器、网络，但保留数据卷（配置不会丢失）：
docker compose down如果要同时删除数据卷（慎用！会丢失所有持久化数据）：
docker compose down -vdocker compose logs -f openclaw-gateway#
实时查看网关日志，调试问题必备：
docker compose logs -f openclaw-gateway按 Ctrl+C 退出日志。
进入容器 Shell#
有时候需要手动操作容器内部：
docker compose exec openclaw-gateway sh退出 Shell：exit 或 Ctrl+D。
通过命令行向 OpenClaw 发消息#
不想开 Dashboard？直接用 CLI 发消息：
docker compose exec openclaw-gateway openclaw agent --agent main -m "hello"其中 main 是 Agent 名称，-m 后面跟你要发送的消息内容。
5. 获取 Dashboard Token#
如果 token 找不到了：
docker compose run --rm openclaw-cli dashboard --no-open配置文件详解#
docker-compose.yml 核心部分#
services:
openclaw-gateway:
build:
context: .
dockerfile: Dockerfile
ports:
- "18789:18789" # 网关端口
volumes:
- ~/.openclaw/:/home/node/.openclaw # 配置持久化
- ~/.openclaw/workspace:/home/node/.openclaw/workspace # 工作目录
environment:
- OPENCLAW_GATEWAY_BIND=lan # 允许宿主机访问
- OPENCLAW_GATEWAY_TOKEN=xxx # token（.env 里找）
restart: unless-stopped
openclaw-cli:
image: openclaw:local
network_mode: "service:openclaw-gateway" # 和网关共享网络
volumes:
- ~/.openclaw/:/home/node/.openclaw
- ~/.openclaw/workspace:/home/node/.openclaw/workspace关键环境变量#
| 变量 | 作用 | 默认值 |
|---|---|---|
OPENCLAW_IMAGE | 使用远程镜像而非本地构建 | openclaw:local |
OPENCLAW_GATEWAY_BIND | 绑定模式：lan=宿主机可访问 | lan |
OPENCLAW_HOME_VOLUME | 用命名卷持久化 /home/node | - |
OPENCLAW_EXTRA_MOUNTS | 额外的宿主机目录挂载 | - |
OPENCLAW_SANDBOX | 开启 Agent 沙箱 | 0 |
OPENCLAW_DOCKER_SOCKET | Docker socket 路径 | /var/run/docker.sock |
持久化配置（重要！）#
OpenClaw 的配置和数据在 ~/.openclaw/，Docker 通过绑定挂载保持持久化：
~/.openclaw/ # 配置目录（Mac 上）
└── /home/node/.openclaw/ # 容器内会持久化的：
openclaw.json配置文件- 模型认证信息（API Key、OAuth Token）
- Skills 配置
- 工作区文件
- WhatsApp 登录 Session
不会持久化的（容器内）：
- Node 运行时
- OS 包
- 容器本身
常见坑 & 解决方案#
1. 权限错误 (EACCES)#
# 如果遇到 ~/.openclaw 权限问题
sudo chown -R 1000:1000 ~/.openclaw2. “pairing required” 错误#
# 重置网关模式为本地
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
# 重新获取设备列表
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:187893. 内存不够导致构建失败#
构建时如果报 exit 137，说明内存不足。确保 Docker Desktop 分配至少 4GB 内存。
4. 端口被占用#
18789 端口被占用？改一下：
ports:
- "18790:18789" # 映射到宿主机 18790更新 OpenClaw#
git pull # 拉取新版本
docker compose build # 重新构建镜像
docker compose up -d # 重启服务Shell 助手（可选）#
官方有个 clawdock 辅助工具，可以简化日常操作：
# 安装
mkdir -p ~/.clawdock
curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
# 添加到 zsh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
source ~/.zshrc
# 常用命令
clawdock-start # 启动
clawdock-stop # 停止
clawdock-logs # 看日志
clawdock-help # 帮助一句话总结#
# 第一次安装
git clone https://github.com/openclaw/openclaw.git && cd openclaw && ./docker-setup.sh
# 以后更新
git pull && docker compose build && docker compose up -d参考文档： OpenClaw Docker 安装指南
有问题？找小瓜虾！👻