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 2020Intel/M1 芯片通用、macOS 12.0Monterey 及以上建议升级至最新稳定版、Docker 20.10、Docker Compose v2。特别说明MacBook Pro 2020 两种芯片部署流程一致仅 Docker 安装步骤有细微差异下文已明确区分无需额外修改配置文件。二、部署目录结构先按以下目录结构创建文件夹确保文件层级正确避免部署失败Mac 端操作更简洁openclaw-deploy/ # 主部署目录可自定义名称建议放在桌面便于操作 ├── docker-compose.yml # 核心部署配置文件必选 ├── config.yaml # OpenClaw 核心配置文件必选 ├── gateway-config.yaml # 网关配置文件必选 └── data/ # 数据存储目录自动生成无需手动创建Mac 端创建目录快捷操作打开访达 → 进入桌面 → 右键 → 新建文件夹 → 命名为 openclaw-deploy后续所有配置文件放入该文件夹。三、核心配置文件可直接复制使用Mac 端无需修改3.1 docker-compose.yml核心部署文件作用定义容器服务、网络、数据卷实现核心服务与网关服务的隔离部署自带资源限制和自动重启配置适配 Mac 端 Docker 运行特性无需额外调整。# OpenClaw AI 助手 Docker Compose 配置# 版本适配 Docker Compose v2MacBook Pro 2020 双芯片通用version:3.8# 定义网络隔离容器通信避免端口冲突适配 Mac 网络环境networks:openclaw-network:driver:bridgeipam:config:-subnet:172.20.0.0/16# 自定义子网避免与 Mac 本地网络冲突# 定义数据卷持久化存储日志、文件、缓存等数据防止容器删除后数据丢失volumes:openclaw-data:# 主数据存储卷openclaw-config:# 配置文件备份卷services:# OpenClaw 核心服务负责 AI 推理、技能调度核心中枢openclaw-core:# 优先使用官方镜像自动适配 Mac 芯片Intel/M1无需手动选择架构image:openclaw/core:latestbuild:context:.dockerfile:Dockerfile.core# 备用构建文件可选无需修改container_name:openclaw-core# 容器名称便于后续运维restart:always# 容器异常时自动重启保证服务稳定性environment:-TZAsia/Shanghai# 时区配置避免日志时间错乱适配 Mac 系统时区-PYTHONUNBUFFERED1# 实时输出日志便于排查问题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-gatewayrestart:alwaysports:-8080:8080# Web 聊天界面端口外部可访问Mac 本地测试直接用 localhost-8081:8081# 网关与核心服务内部通信端口environment:-TZAsia/Shanghai-CORE_SERVICE_HOSTopenclaw-core# 指向核心服务容器自动解析地址volumes:-./gateway-config.yaml:/app/gateway-config.yaml:ro# 只读挂载网关配置-openclaw-data:/app/data# 共享数据目录与核心服务同步networks:-openclaw-network# 依赖核心服务启动避免网关先启动导致连接失败depends_on:-openclaw-coredeploy:resources:limits:cpus:0.5# 限制使用 0.5 个 CPU 核心memory:1G# 限制使用 1G 内存3.2 config.yamlOpenClaw 核心配置作用配置 AI 模型、技能开关所有必填项已标注「必改」新手只需替换密钥即可使用Mac 端无需额外修改配置。# 核心 LLM 配置必改llm:# 模型提供商可选值openai/qwen/claude/ernie/chatglmprovider:openai# 替换为你的大模型 API Key必填否则无法调用 AI 能力api_key:sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx# 模型名称根据提供商调整示例为 OpenAI GPT-3.5model:gpt-3.5-turbo# 国内模型需修改此地址示例通义千问地址 https://dashscope.aliyuncs.com/compatible-mode/v1base_url:https://api.openai.com/v1# 单次回复最大令牌数新手建议 1000-2000平衡响应速度和回复长度max_tokens:1500# 随机性0-1越小越精准越大越有创意新手建议 0.6-0.8temperature:0.6# 技能配置按需开启skills:web_browser:true# 网页浏览能力开启后可让 AI 访问网页file_system:true# 文件操作能力仅能访问 data 目录安全隔离search:false# 搜索引擎能力开启需配置下方 serpapi_keyautomation: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 端无需额外调整。# 多平台网关配置必改gateways:# Telegram 机器人新手首选配置最简单易测试Mac 端无额外配置telegram:enabled:true# 是否开启 Telegram 接口建议开启bot_token:123456:ABC-DEF1234ghIkl# 替换为你的 Telegram Bot Token必填webhook:false# 本地测试用轮询模式公网部署可改为 truewebhook_url:# 公网地址开启 webhook 时填写本地测试留空# QQ 机器人需额外配置 go-cqhttp新手建议先跳过qq:enabled:falseqq_account:12345678# 你的 QQ 账号开启后填写ws_url:ws://127.0.0.1:6700# go-cqhttp 服务地址需提前部署# 飞书机器人需在飞书开放平台创建应用新手可后续尝试feishu:enabled:falseapp_id:cli_xxxxxxxxxxxxxx# 飞书 App ID开启后填写app_secret:xxxxxxxxxxxxxxxxxxxxxx# 飞书 App Secret开启后填写# Web 聊天界面默认开启无需额外配置Mac 本地测试直接访问 localhost:8080webchat:enabled:truehost:0.0.0.0port:8080# 网关与核心通信配置无需修改core:host:openclaw-core# Docker 内部容器名称自动解析地址无需修改port:8000# 核心服务端口与核心配置一致timeout:30# 通信超时时间秒避免长时间等待四、MacBook Pro 2020 专属快速上手步骤新手友好以下步骤专为 MacBook Pro 2020 设计区分 Intel/M1 芯片差异操作简洁无需复杂命令一键完成部署4.1 前置准备Mac 专属安装 Docker 和 Docker ComposeMac 双芯片区分步骤必做Intel 芯片MacBook Pro 2020 13-inch/16-inch Intel访问 Docker 官网https://www.docker.com/products/docker-desktop/下载「Mac with Intel chip」版本双击下载的 .dmg 文件将 Docker 拖入应用程序文件夹打开 Docker首次打开会提示「是否允许 Docker 运行」点击允许等待 Docker 启动菜单栏出现鲸鱼图标即启动成功。M1 芯片MacBook Pro 2020 M1 版本访问 Docker 官网下载「Mac with Apple chip」版本安装步骤与 Intel 芯片一致启动后需在「设置 → Resources」中调整内存分配建议分配 4G 内存避免部署后卡顿注意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。启动服务核心步骤打开终端输入命令进入部署目录桌面路径可直接复制cd ~/Desktop/openclaw-deploy # 若文件夹不在桌面替换为实际路径执行启动命令后台运行首次启动会自动拉取镜像Mac 端因网络原因可能需要 5-10 分钟耐心等待docker-compose up -d查看启动日志确认服务无报错出现「OpenClaw AI Core started successfully」即正常docker-compose logs -f日志查看完成后按「Control C」退出日志查看模式服务仍在后台运行。4.3 验证部署结果Mac 端专属测试方法Telegram 测试打开 TelegramMac 端可下载 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 Webhttps://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 端无需额外调整直接替换即可llm:provider:qwenapi_key:你的通义千问API Key# 从通义千问开放平台获取model:qwen-turbobase_url:https://dashscope.aliyuncs.com/compatible-mode/v16.3 MacBook Pro 2020 专属问题排查高频坑点Docker 启动失败最常见Intel 芯片检查 macOS 版本是否为 12.0若版本过低升级系统后重新安装 DockerM1 芯片若提示「无法打开 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 专属问题排查」。