OpenClaw AI 助手 Docker Compose 一键部署文档（MacBook Pro 2020 专属版，可下载）

OpenClaw AI 助手 Docker Compose 一键部署文档（MacBook Pro 2020 专属版）

一、文档说明

本文档为 MacBook Pro 2020 专属 的 OpenClaw AI 助手 Docker Compose 一键部署手册，适配该机型 Intel 芯片（13-inch/16-inch）和 M1 芯片版本，包含目录结构、核心配置文件、Mac 专属部署步骤、常用运维命令及机型专属问题排查。文档适配新手使用，所有配置文件可直接复制落地，部署完成后可实现多平台（Telegram/Web）聊天交互及基础 AI 技能调用。

适用环境：MacBook Pro 2020（Intel/M1 芯片通用）、macOS 12.0+（Monterey 及以上，建议升级至最新稳定版）、Docker 20.10+、Docker Compose v2+。

特别说明：MacBook Pro 2020 两种芯片部署流程一致，仅 Docker 安装步骤有细微差异，下文已明确区分，无需额外修改配置文件。

二、部署目录结构

先按以下目录结构创建文件夹（确保文件层级正确，避免部署失败，Mac 端操作更简洁）：

plain 复制代码

openclaw-deploy/          # 主部署目录（可自定义名称，建议放在桌面便于操作）
├── docker-compose.yml    # 核心部署配置文件（必选）
├── config.yaml           # OpenClaw 核心配置文件（必选）
├── gateway-config.yaml   # 网关配置文件（必选）
└── data/                 # 数据存储目录（自动生成，无需手动创建）

Mac 端创建目录快捷操作：打开访达 → 进入桌面 → 右键 → 新建文件夹 → 命名为 openclaw-deploy，后续所有配置文件放入该文件夹。

三、核心配置文件（可直接复制使用，Mac 端无需修改）

3.1 docker-compose.yml（核心部署文件）

作用：定义容器服务、网络、数据卷，实现核心服务与网关服务的隔离部署，自带资源限制和自动重启配置，适配 Mac 端 Docker 运行特性，无需额外调整。

yaml 复制代码

# OpenClaw AI 助手 Docker Compose 配置
# 版本适配 Docker Compose v2+，MacBook Pro 2020 双芯片通用
version: '3.8'

# 定义网络（隔离容器通信，避免端口冲突，适配 Mac 网络环境）
networks:
  openclaw-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16  # 自定义子网，避免与 Mac 本地网络冲突

# 定义数据卷（持久化存储日志、文件、缓存等数据，防止容器删除后数据丢失）
volumes:
  openclaw-data:  # 主数据存储卷
  openclaw-config:  # 配置文件备份卷

services:
  # OpenClaw 核心服务（负责 AI 推理、技能调度，核心中枢）
  openclaw-core:
    # 优先使用官方镜像，自动适配 Mac 芯片（Intel/M1），无需手动选择架构
    image: openclaw/core:latest
    build:
      context: .
      dockerfile: Dockerfile.core  # 备用构建文件（可选，无需修改）
    container_name: openclaw-core  # 容器名称，便于后续运维
    restart: always  # 容器异常时自动重启，保证服务稳定性
    environment:
      - TZ=Asia/Shanghai  # 时区配置，避免日志时间错乱（适配 Mac 系统时区）
      - PYTHONUNBUFFERED=1  # 实时输出日志，便于排查问题
    volumes:
      - ./config.yaml:/app/config.yaml:ro  # 只读挂载核心配置，防止误修改
      - openclaw-data:/app/data  # 持久化挂载数据目录
      - openclaw-config:/app/config-backup  # 配置文件自动备份
    networks:
      - openclaw-network
    # 资源限制（适配 MacBook Pro 2020 硬件，避免占用过多内存/CPU，可按需调整）
    deploy:
      resources:
        limits:
          cpus: '1'  # 限制使用 1 个 CPU 核心（MacBook Pro 2020 建议不超过 2 核）
          memory: 2G  # 限制使用 2G 内存（Mac 建议保留至少 2G 内存给系统）

  # OpenClaw 网关服务（负责多平台聊天接口对接，消息收发）
  openclaw-gateway:
    image: openclaw/gateway:latest  # 自动适配 Mac 双芯片
    container_name: openclaw-gateway
    restart: always
    ports:
      - "8080:8080"  # Web 聊天界面端口（外部可访问，Mac 本地测试直接用 localhost）
      - "8081:8081"  # 网关与核心服务内部通信端口
    environment:
      - TZ=Asia/Shanghai
      - CORE_SERVICE_HOST=openclaw-core  # 指向核心服务容器，自动解析地址
    volumes:
      - ./gateway-config.yaml:/app/gateway-config.yaml:ro  # 只读挂载网关配置
      - openclaw-data:/app/data  # 共享数据目录，与核心服务同步
    networks:
      - openclaw-network
    # 依赖核心服务启动（避免网关先启动导致连接失败）
    depends_on:
      - openclaw-core
    deploy:
      resources:
        limits:
          cpus: '0.5'  # 限制使用 0.5 个 CPU 核心
          memory: 1G  # 限制使用 1G 内存

3.2 config.yaml（OpenClaw 核心配置）

作用：配置 AI 模型、技能开关，所有必填项已标注「必改」，新手只需替换密钥即可使用，Mac 端无需额外修改配置。

yaml 复制代码

# ==================== 核心 LLM 配置（必改）====================
llm:
  # 模型提供商：可选值（openai/qwen/claude/ernie/chatglm）
  provider: "openai"
  # 替换为你的大模型 API Key（必填，否则无法调用 AI 能力）
  api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  # 模型名称（根据提供商调整，示例为 OpenAI GPT-3.5）
  model: "gpt-3.5-turbo"
  # 国内模型需修改此地址（示例：通义千问地址 https://dashscope.aliyuncs.com/compatible-mode/v1）
  base_url: "https://api.openai.com/v1"
  # 单次回复最大令牌数（新手建议 1000-2000，平衡响应速度和回复长度）
  max_tokens: 1500
  # 随机性（0-1，越小越精准，越大越有创意，新手建议 0.6-0.8）
  temperature: 0.6

# ==================== 技能配置（按需开启）====================
skills:
  web_browser: true        # 网页浏览能力（开启后可让 AI 访问网页）
  file_system: true        # 文件操作能力（仅能访问 data 目录，安全隔离）
  search: false            # 搜索引擎能力（开启需配置下方 serpapi_key）
  automation: false        # 自动化脚本能力（新手建议先关闭，避免配置复杂）
  api_call: false          # 第三方 API 调用能力
  device_control: false    # 设备控制能力（需额外对接智能家居 API）
  # serpapi_key: "你的SerpAPI Key"  # 开启 search 技能时必填，替换为实际密钥

# ==================== 服务基础配置（无需修改，Mac 端适配）====================
service:
  host: "0.0.0.0"          # 监听所有网络地址，允许容器外部访问
  port: 8000               # 核心服务端口（与网关配置一致，无需修改）
  log_level: "INFO"        # 日志级别：DEBUG（详细）/INFO（正常）/WARN（警告）/ERROR（错误）
  log_file: "/app/data/openclaw-core.log"  # 日志存储路径，便于后续排查问题

3.3 gateway-config.yaml（网关配置）

作用：配置多平台聊天接口（Telegram/QQ/飞书/Web），新手优先配置 Telegram 和 Web 接口，快速完成测试，Mac 端无需额外调整。

yaml 复制代码

# ==================== 多平台网关配置（必改）====================
gateways:
  # Telegram 机器人（新手首选，配置最简单，易测试，Mac 端无额外配置）
  telegram:
    enabled: true                          # 是否开启 Telegram 接口（建议开启）
    bot_token: "123456:ABC-DEF1234ghIkl"   # 替换为你的 Telegram Bot Token（必填）
    webhook: false                         # 本地测试用轮询模式，公网部署可改为 true
    webhook_url: ""                        # 公网地址（开启 webhook 时填写，本地测试留空）
  
  # QQ 机器人（需额外配置 go-cqhttp，新手建议先跳过）
  qq:
    enabled: false
    qq_account: 12345678                   # 你的 QQ 账号（开启后填写）
    ws_url: "ws://127.0.0.1:6700"          # go-cqhttp 服务地址（需提前部署）
  
  # 飞书机器人（需在飞书开放平台创建应用，新手可后续尝试）
  feishu:
    enabled: false
    app_id: "cli_xxxxxxxxxxxxxx"           # 飞书 App ID（开启后填写）
    app_secret: "xxxxxxxxxxxxxxxxxxxxxx"   # 飞书 App Secret（开启后填写）
  
  # Web 聊天界面（默认开启，无需额外配置，Mac 本地测试直接访问 localhost:8080）
  webchat:
    enabled: true
    host: "0.0.0.0"
    port: 8080

# ==================== 网关与核心通信配置（无需修改）====================
core:
  host: "openclaw-core"    # Docker 内部容器名称，自动解析地址，无需修改
  port: 8000               # 核心服务端口，与核心配置一致
  timeout: 30              # 通信超时时间（秒），避免长时间等待

四、MacBook Pro 2020 专属快速上手步骤（新手友好）

以下步骤专为 MacBook Pro 2020 设计，区分 Intel/M1 芯片差异，操作简洁，无需复杂命令，一键完成部署：

4.1 前置准备（Mac 专属）

安装 Docker 和 Docker Compose（Mac 双芯片区分步骤，必做）：
- Intel 芯片（MacBook Pro 2020 13-inch/16-inch Intel）：
  1. 访问 Docker 官网（https://www.docker.com/products/docker-desktop/），下载「Mac with Intel chip」版本；
  2. 双击下载的 .dmg 文件，将 Docker 拖入应用程序文件夹，打开 Docker；
  3. 首次打开会提示「是否允许 Docker 运行」，点击允许，等待 Docker 启动（菜单栏出现鲸鱼图标即启动成功）。
- M1 芯片（MacBook Pro 2020 M1 版本）：
  1. 访问 Docker 官网，下载「Mac with Apple chip」版本；
  2. 安装步骤与 Intel 芯片一致，启动后需在「设置 → Resources」中调整内存分配（建议分配 4G 内存，避免部署后卡顿）；
  3. 注意：M1 芯片首次启动 Docker 可能需要输入 Mac 开机密码，且密码输入时屏幕无任何显示（隐形密码），直接盲打输入后回车即可，无需担心键盘故障。
- 验证安装成功：打开 Mac 终端（快捷键：Command + 空格键，输入「Terminal」回车），执行以下两条命令，均显示版本号即正常：
  docker -v # 显示 Docker 版本（需 20.10+） docker compose -v # 显示 Docker Compose 版本（需 v2+）
准备密钥：提前获取 LLM API Key（如 OpenAI、通义千问）、Telegram Bot Token（创建方法见下文补充），建议复制到备忘录，便于后续粘贴。
Mac 终端基础操作提示（新手必看）：
- 终端输入命令后，按回车执行；
- 若提示「Permission denied」（权限不足），在命令前加「sudo 」（如 sudo docker-compose up -d），输入 Mac 开机密码（隐形密码）后回车即可；
- 终端中复制命令：选中命令 → 按 Command + C；粘贴命令：按 Command + V。

4.2 部署操作（Mac 端专属简化步骤）

创建部署目录：
- 打开访达 → 进入桌面 → 右键 → 新建文件夹 → 命名为「openclaw-deploy」；
- 将本文档中 3 个配置文件（docker-compose.yml、config.yaml、gateway-config.yaml）复制粘贴到该文件夹中（可直接复制代码，在访达中新建对应文件，粘贴内容并保存）。
填写密钥（必做）：
- 打开「openclaw-deploy」文件夹 → 双击打开 config.yaml → 替换「llm.api_key」为你的大模型 API Key → 保存（Command + S）；
- 双击打开 gateway-config.yaml → 替换「telegram.bot_token」为你的 Telegram Bot Token → 保存（Command + S）。
启动服务（核心步骤）：
1. 打开终端，输入命令（进入部署目录，桌面路径可直接复制）：
  cd ~/Desktop/openclaw-deploy # 若文件夹不在桌面，替换为实际路径
2. 执行启动命令（后台运行，首次启动会自动拉取镜像，Mac 端因网络原因可能需要 5-10 分钟，耐心等待）：
  docker-compose up -d
3. 查看启动日志（确认服务无报错，出现「OpenClaw AI Core started successfully」即正常）：
  docker-compose logs -f
4. 日志查看完成后，按「Control + C」退出日志查看模式，服务仍在后台运行。

4.3 验证部署结果（Mac 端专属测试方法）

Telegram 测试：打开 Telegram（Mac 端可下载 Telegram 客户端），找到你的 Bot，发送 /start，若能收到 AI 回复，说明核心服务与 Telegram 网关正常。
Web 聊天测试（最便捷，优先测试）：打开 Mac 浏览器（Safari/Chrome 均可），输入 http://localhost:8080，打开聊天界面发送消息，能收到回复即 Web 网关正常。
容器状态检查：回到终端，执行以下命令，若两个容器（openclaw-core、openclaw-gateway）的状态均为 Up，说明部署成功：
docker-compose ps

五、MacBook Pro 2020 常用运维命令（适配 Mac 终端）

后续维护服务时，可使用以下命令（均在部署目录下执行，复制粘贴即可，适配 Mac 终端）：

操作目的	命令	说明（Mac 端专属）
启动所有服务	`docker-compose up -d`	后台启动，不占用终端，Mac 端无需额外权限
停止所有服务	`docker-compose down`	停止并删除容器，数据卷（data）保留，重启后数据不丢失
重启所有服务	`docker-compose restart`	修改配置后需执行，使配置生效，Mac 端无需重启 Docker
查看核心服务日志	`docker-compose logs -f openclaw-core`	排查 AI 核心相关报错，按 Control + C 退出
查看网关服务日志	`docker-compose logs -f openclaw-gateway`	排查聊天接口相关报错，Mac 端网络问题优先看此日志
查看容器状态	`docker-compose ps`	确认容器是否正常运行，Mac 端若显示 Exited，需查看日志排查
删除容器+数据（谨慎）	`docker-compose down -v`	彻底删除容器和数据卷，适用于重新部署，Mac 端删除后需重新创建目录

六、补充说明（MacBook Pro 2020 专属）

6.1 Telegram Bot Token 获取方法（Mac 端操作）

打开 Mac 浏览器，访问 Telegram Web（https://web.telegram.org/），登录你的 Telegram 账号；
搜索 @BotFather（官方机器人），点击进入聊天界面；
发送 /newbot，按提示设置 Bot 名称（如 OpenClawBot）和用户名（需以 bot 结尾，如 OpenClaw_Ai_Bot）；
生成成功后，会收到包含 Bot Token 的消息，复制该 Token 填入 gateway-config.yaml 即可（Mac 端复制快捷键：Command + C）。

6.2 国内模型配置示例（通义千问，Mac 端通用）

若使用国内大模型（如通义千问），修改 config.yaml 中的 llm 部分，Mac 端无需额外调整，直接替换即可：

yaml 复制代码

llm:
  provider: "qwen"
  api_key: "你的通义千问API Key"  # 从通义千问开放平台获取
  model: "qwen-turbo"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

6.3 MacBook Pro 2020 专属问题排查（高频坑点）

Docker 启动失败（最常见）：
- Intel 芯片：检查 macOS 版本是否为 12.0+，若版本过低，升级系统后重新安装 Docker；
- M1 芯片：若提示「无法打开 Docker，因为无法验证开发者」，打开「系统设置 → 隐私与安全性 → 通用」，点击「仍要打开」，允许 Docker 运行；若启动后卡顿，在 Docker 设置中调整内存分配（建议 4G）。
终端执行命令提示「Permission denied」：
- 在命令前加「sudo 」（如 sudo docker-compose up -d），输入 Mac 开机密码（隐形密码，盲打输入后回车）；
- 若仍报错，检查部署目录权限：右键「openclaw-deploy」文件夹 → 显示简介 → 权限 → 确保当前用户有「读与写」权限。
容器启动成功，但 Web 页面无法访问（localhost:8080 打不开）：
- 检查 Docker 是否正常运行（菜单栏有鲸鱼图标）；
- 确认端口 8080 未被占用：在终端执行lsof -i:8080，若有进程占用，关闭对应进程，或修改 docker-compose.yml 中的端口映射（如 8082:8080），重启服务。
AI 不回复或 Telegram 无法连接（Mac 端网络坑点）：
- Mac 端终端程序默认不走系统代理，若需访问外网模型（如 OpenAI），需在终端设置代理环境变量（具体命令可根据你的代理工具调整）；
- 测试网络连通性：在终端执行 curl -v https://api.openai.com/v1（替换为你的模型地址），能返回数据即网络正常，否则检查代理或网络设置。
M1 芯片镜像拉取失败：Docker 会自动适配 M1 芯片，若拉取镜像超时，可更换 Docker 镜像源（在 Docker 设置 → Docker Engine 中添加国内镜像源，重启 Docker 后重试）。

七、后续扩展（Mac 端适配）

部署成功后，可参考以下方向扩展功能，适配 MacBook Pro 2020 特性：

开启高级技能：在 config.yaml 中开启 search、automation 等技能，填写对应 API 密钥即可使用，Mac 端无需额外配置。
添加多平台接口：在 gateway-config.yaml 中开启 QQ、飞书接口，配置对应密钥和服务地址，Mac 端可直接部署 go-cqhttp（用于 QQ 机器人），无需额外虚拟机。
容器化优化：Mac 端可使用 Docker Desktop 自带的日志查看功能，无需复杂命令，点击容器即可查看日志；可设置 Docker 开机自启，避免每次手动启动。
自定义技能：编写技能插件，接入 Mac 本地服务（如本地文件查询、Mac 系统快捷操作），适配 MacBook Pro 2020 硬件特性。

八、文档说明（Mac 端下载使用）

本文档为 MacBook Pro 2020 专属版本，可直接复制保存为 .md 文件（Markdown 格式），下载后可离线查看、编辑：

Mac 端保存方法：选中全文 → 复制 → 打开「文本编辑」→ 粘贴 → 点击「文件 → 保存」→ 格式选择「纯文本」，后缀改为 .md（如 openclaw-mac-deploy.md）。
所有配置文件可直接复制到 Mac 桌面的 openclaw-deploy 文件夹，替换占位符后即可使用，无需额外修改。
若部署过程中遇到任何问题，可查看终端日志排查，或提供报错信息寻求技术支持，优先参考本文档「6.3 专属问题排查」。