前言

OpenClaw（原名 ClawdBot / MoltBot）是一个开源的个人 AI 代理框架，支持本地运行，支持 Telegram、Discord、WhatsApp 等通道接入，能执行任务、读写文件（需谨慎开启）。
在 macOS 上推荐使用 Docker 部署：隔离性强、易重置、避免污染系统环境。
本文以 2026 年最新版本为基础，完整记录从环境准备到成功运行的全过程（包括 macOS 常见 bash 版本问题）。准备工作（约 10–30 分钟）

1. 安装 Docker Desktop
   • 从官网下载安装：https://www.docker.com/products/docker-desktop/
   • 安装后启动 Docker，确保菜单栏鲸鱼图标正常运行（绿色）。
   • 推荐启用“Allow the default Docker socket”选项（Settings → Advanced），便于兼容旧脚本。
2. 升级 bash 到 5.x（重要！）
   macOS 自带 bash 3.2 不支持 declare -A 等现代语法，OpenClaw 的 docker-setup.sh 会报错。
   • 安装 Homebrew（如果没有）：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   • 安装新 bash：bash

     brew install bash

   • 把新 bash 加到 PATH（编辑 ~/.zshrc 或 ~/.zprofile）：bash

     export PATH="/usr/local/bin:$PATH"   # Intel Mac
     # 或 /opt/homebrew/bin:$PATH 如果是 M 系列（但本文假设 Intel）
     source ~/.zshrc

   • 验证：bash

     bash --version   # 应显示 5.3.x 或更高

3. 克隆 OpenClaw 仓库bash

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

核心步骤：构建并启动 Docker 镜像（约 5–30 分钟）

1. （可选）加速：使用预构建镜像
   如果不想本地构建（build 过程可能下载依赖较慢），设置环境变量跳过：bash

   export OPENCLAW_IMAGE=alpine/openclaw   # 或官方其他镜像（视最新可用）

2. 运行官方 setup 脚本bash

   bash ./docker-setup.sh   # 明确用新 bash 执行

   • 脚本会：
     • 拉取/构建镜像（openclaw:local）
     • 创建 ~/.openclaw（配置）和 ~/openclaw/workspace（沙箱目录）
     • 启动 docker-compose 服务
   • 构建过程会输出进度，如果卡在 100%，耐心等或检查网络/代理。
3. 常见坑点处理
   • 报 declare -A: invalid option → 确认用 bash 5.x 执行（上面已解决）
   • 报 Cannot connect to the Docker daemon → 启动 Docker Desktop，或 docker context use desktop-linux
   • 权限问题 → sudo chown -R $USER ~/.openclaw ~/openclaw/workspace

配置与首次使用（Onboarding）

1. 启动 onboarding wizardbash

   docker compose run --rm openclaw-cli wizard

   • 选择 QuickStart（推荐，新手友好，后续可手动调整）
   • 阅读安全警告 → Yes 继续
   • 输入模型 API Key（推荐 Groq、Claude、OpenAI 等）
   • 配置通道（Telegram/Discord 推荐先用一个）
   • 生成 pairing code → 在对应平台发给 bot 配对
2. 批准配对（以 Discord 为例）bash

   docker compose run --rm openclaw-cli pairing approve discord <你的配对码>

   • 验证：bash

     docker compose run --rm openclaw-cli devices list

3. 测试
   • 在 Discord/Telegram 发消息给 bot（如 “你好”）
   • 查看日志确认：bash

     docker compose logs -f

日常管理命令

• 启动/重启：docker compose up -d / docker compose restart
• 停止：docker compose down
• 查看状态：docker compose ps
• 打开 Web Dashboard：docker compose run --rm openclaw-cli dashboard（通常 localhost:18789）
• 安全审计：docker compose exec openclaw-gateway openclaw security audit --deep

安全提醒

• Docker 提供隔离，但仍需谨慎开启工具（如文件读写、shell 执行）。
• 不要把高危权限给 bot，启用 allowlist、mention gating。
• 定期运行 openclaw security audit --fix。
• API Key 等敏感信息存储在 ~/.openclaw/，备份好。

总结在 macOS 上通过 Docker 安装 OpenClaw 非常可靠：
准备（Homebrew + bash 升级 + Docker）→ 克隆仓库 → bash ./docker-setup.sh → wizard 配置 → pairing 批准 → 测试聊天
整个过程 30–60 分钟就能跑起本地个人 AI 助手，强烈推荐 Docker 方式，避免直接污染系统。

（完）