跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
Shell / BashNode.jsAI

OpenClaw + Docker + MiniMax 本地部署方案

基于 macOS 系统使用 Docker 和 Colima 部署 OpenClaw AI Agent 框架，并配置 MiniMax M2.5 模型作为后端。内容包括环境准备、容器配置、API Key 获取、安全设置及 QQ 机器人接入步骤，并提供常见故障排查指南。

栈溢出发布于 2026/3/15更新于 2026/9/28106 浏览
OpenClaw + Docker + MiniMax 本地部署方案

OpenClaw + Docker + MiniMax 本地部署方案

前言

随着 AI 大模型的快速发展，越来越多的开发者希望在本地搭建自己的 AI 助手。OpenClaw 是一款开源的 AI Agent 框架，支持多种大模型后端，可以轻松构建智能对话系统。MiniMax M2.5 是国内领先的 AI 大模型，具有强大的推理能力和优秀的中文理解能力。

本文将介绍如何在 macOS 系统上，通过 Docker + Colima 部署 OpenClaw，并配置 MiniMax M2.5 作为大模型后端，同时支持 QQ 机器人接入，实现多渠道的 AI 助手服务。

方案优势：

  • 完全本地化部署，数据安全可控
  • 支持多种大模型切换（MiniMax、DeepSeek、OpenAI 等）
  • 支持 QQ 机器人接入，扩展应用场景
  • 安全配置完善，防止数据泄露

一、环境准备

1.1 系统要求
项目要求
操作系统macOS 12+ (Monterey 或更高)
内存建议 8GB+
磁盘空间至少 20GB 可用空间
CPUApple Silicon (M1/M2/M3) 或 Intel
1.2 安装 Homebrew

如果尚未安装 Homebrew，请执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
1.3 安装必要工具
# 安装 Node.js 22+
brew install node@22
# 验证 Node.js 版本
node --version
# 应显示 v22.x.x 或更高
# 安装 Colima (Docker 替代方案，无需安装 Docker Desktop)
brew install colima
# 安装 Docker CLI
brew install docker docker-compose

二、Colima 安装与配置

Colima 是 macOS 上的轻量级 Docker 运行时，相比 Docker Desktop 更加轻量和高效。

2.1 创建 Colima 配置文件

创建 ~/.colima/default/colima.yaml：

# Colima 配置
cpu: 4
memory: 8
disk: 60
# 网络配置
network:
  address: true
  # 允许容器访问主机网络
  # 端口转发
portForwarding:
  - 18789:18789 # OpenClaw Gateway
  - 18790:18790 # OpenClaw Canvas
# 挂载点
mounts:
  - location: ~/openclaw-workspace
    writable: true
  - location: ~/.openclaw
    writable: true
# 环境变量
env:
  - NODE_ENV=production
2.2 启动 Colima
# 创建工作目录
mkdir -p ~/openclaw-workspace
mkdir -p ~/.openclaw
# 启动 Colima
colima start --cpu 4 --memory 8 --disk 60
# 验证 Docker 运行状态
docker ps
2.3 配置 Docker 网络
# 创建专用网络
docker network create openclaw-net
# 验证网络
docker network ls | grep openclaw

三、OpenClaw Docker 部署

3.1 创建目录结构
# 创建配置目录
mkdir -p ~/openclaw-deploy/{config,workspace,logs}
# 设置权限
chmod 700 ~/openclaw-deploy
3.2 创建 Docker Compose 文件

创建 ~/openclaw-deploy/docker-compose.yml：

services:
  openclaw-gateway:
    image: node:22
    container_name: openclaw
    hostname: openclaw
    environment:
      - NODE_ENV=production
      - OPENCLAW_STATE_DIR=/home/node/.openclaw
      - OPENCLAW_WORKSPACE_DIR=/home/node/workspace
      - OPENCLAW_GATEWAY_PORT=18789
      - MINIMAX_API_KEY=${MINIMAX_API_KEY}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - npm_config_registry=https://registry.npmmirror.com
    volumes:
      - ./config:/home/node/.openclaw:rw
      - ./workspace:/home/node/workspace:rw
      - ./logs:/home/node/logs:rw
    ports:
      - "127.0.0.1:18789:18789"
      - "127.0.0.1:18790:18790"
    working_dir: /home/node
    command: >
      bash -c " apt-get update && apt-get install -y git curl cmake make gcc g++ python3 && npm config set registry https://registry.npmmirror.com && npm install -g openclaw@latest && openclaw gateway --port 18789 --bind lan "
    restart: unless-stopped
    networks:
      - openclaw-net
    security_opt:
      - no-new-privileges:true
networks:
  openclaw-net:
    driver: bridge

重要说明：

  • 使用 node:22 (Debian) 而非 node:22-alpine，因为 Alpine 缺少编译 llama.cpp 所需的系统头文件
  • 配置淘宝 npm 镜像加速下载
3.3 创建环境变量文件

创建 ~/openclaw-deploy/.env：

# MiniMax API 密钥（从 MiniMax 平台获取）
# https://platform.minimaxi.com
MINIMAX_API_KEY=your-minimax-api-key-here
# Gateway 访问令牌（请设置强密码）
OPENCLAW_GATEWAY_TOKEN=your-secure-token-here

安全提示：请将 your-minimax-api-key-here 和 your-secure-token-here 替换为您的实际值。

四、MiniMax M2.5 模型配置

4.1 获取 MiniMax API Key
  1. 访问 MiniMax 开放平台：
    • 国内版：https://platform.minimaxi.com/user-center/basic-info
    • 国际版：https://platform.minimax.io/user-center/basic-info
  2. 注册/登录账号
  3. 在「API Keys」页面创建新的 API Key
  4. 复制 API Key 并保存到 .env 文件
4.2 创建 OpenClaw 配置文件

创建 ~/openclaw-deploy/config/openclaw.json：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "controlUi": {
      "allowedOrigins": ["http://127.0.0.1:18789", "http://localhost:18789"]
    }
  },
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "apiKey": "${MINIMAX_API_KEY}",
        "models": [
          { "id": "MiniMax-M2.5", "name": "MiniMax M2.5" },
          { "id": "MiniMax-M2.5-highspeed", "name": "MiniMax M2.5 Highspeed" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "minimax/MiniMax-M2.5",
      "workspace": "/home/node/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "profile": "minimal",
    "deny": ["gateway", "cron", "sessions_spawn", "sessions_send"],
    "fs": {
      "workspaceOnly": true
    },
    "exec": {
      "security": "deny"
    },
    "elevated": {
      "enabled": false
    }
  },
  "logging": {
    "redactSensitive": "tools"
  },
  "discovery": {
    "mdns": {
      "mode": "off"
    }
  }
}
4.3 配置字段说明
配置项说明
baseUrlMiniMax API 地址（推荐使用 Anthropic 兼容端点）
apiKey从环境变量 ${MINIMAX_API_KEY} 读取，避免硬编码
models必须是数组格式
agents.defaults.model必须是字符串格式 provider/model-id
4.4 更新 models.json 文件（重要！）

这是关键步骤！ OpenClaw 会读取 models.json 文件中的配置：

docker exec openclaw sh -c "API_KEY=\$MINIMAX_API_KEY && cat > /home/node/.openclaw/agents/main/agent/models.json << EOF
{
  \"providers\": {
    \"minimax\": {
      \"baseUrl\": \"https://api.minimaxi.com/anthropic\",
      \"api\": \"anthropic-messages\",
      \"models\": [
        {
          \"id\": \"MiniMax-M2.5\",
          \"name\": \"MiniMax M2.5\",
          \"reasoning\": true,
          \"input\": [\"text\"],
          \"cost\": {\"input\": 0.3, \"output\": 1.2, \"cacheRead\": 0.03, \"cacheWrite\": 0.12},
          \"contextWindow\": 204800,
          \"maxTokens\": 8192
        },
        {
          \"id\": \"MiniMax-M2.5-highspeed\",
          \"name\": \"MiniMax M2.5 Highspeed\",
          \"reasoning\": true,
          \"input\": [\"text\"],
          \"cost\": {\"input\": 0.1, \"output\": 0.8, \"cacheRead\": 0.01, \"cacheWrite\": 0.08},
          \"contextWindow\": 204800,
          \"maxTokens\": 8192
        }
      ],
      \"apiKey\": \"\$API_KEY\"
    }
  }
}
EOF"
4.5 MiniMax M2.5 模型列表
模型 ID说明上下文长度
MiniMax-M2.5M2.5 完整版（推荐）204800
MiniMax-M2.5-highspeedM2.5 高速版204800
4.6 重要注意事项
  1. API 端点选择：
    • Anthropic 兼容端点（推荐）：https://api.minimaxi.com/anthropic
      • API 模式：anthropic-messages
      • 支持推理（reasoning）功能
    • OpenAI 兼容端点：https://api.minimaxi.com/v1
      • API 模式：openai-completions
      • 不支持推理功能
  2. 必须更新 models.json：
    • 仅修改 openclaw.json 不够，OpenClaw 会从 models.json 读取实际配置
    • models.json 中的 api 字段必须与 baseUrl 匹配
  3. 模型 ID 大小写敏感：
    • 正确：MiniMax-M2.5、MiniMax-M2.5-highspeed
    • 错误：minimax-m2.5、MiniMax-m2.5

五、安全配置

5.1 限制文件访问
{
  "agents": {
    "defaults": {
      "workspace": "/home/node/workspace",
      "sandbox": {
        "mode": "off"
      }
    }
  },
  "tools": {
    "fs": {
      "workspaceOnly": true
    }
  }
}
5.2 限制危险操作
{
  "tools": {
    "profile": "minimal",
    "fs": {
      "workspaceOnly": true
    },
    "exec": {
      "security": "deny"
    },
    "elevated": {
      "enabled": false
    }
  }
}

说明：

  • tools.fs.workspaceOnly: true - 限制文件操作仅在工作空间内
  • tools.exec.security: "deny" - 禁止执行命令
  • tools.elevated.enabled: false - 禁用提权操作
5.3 网络隔离
ports:
  # 仅绑定本地回环地址
  - "127.0.0.1:18789:18789"
  - "127.0.0.1:18790:18790"

六、验证与测试

6.1 启动服务
cd ~/openclaw-deploy
# 启动 Colima（如未启动）
colima start
# 启动 OpenClaw
docker-compose up -d
# 查看日志
docker-compose logs -f openclaw-gateway
6.2 验证服务状态
# 检查容器状态
docker ps | grep openclaw
# 检查端口监听
lsof -i :18789
# 测试 Web 界面
curl -s http://127.0.0.1:18789/ | head -20
6.3 验证 MiniMax API 连接
docker exec openclaw sh -c 'curl -s -X POST https://api.minimaxi.com/anthropic/v1/messages \
-H "x-api-key: $MINIMAX_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d "{\"model\":\"MiniMax-M2.5\",\"max_tokens\":10,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}"'
6.4 访问 Web 界面

打开浏览器访问：http://127.0.0.1:18789

首次访问需要输入 Gateway Token（在 .env 文件中配置的 OPENCLAW_GATEWAY_TOKEN）。

七、QQ 机器人接入（可选）

OpenClaw 支持通过 QQ 官方机器人平台接入，实现 QQ 用户与 AI 助手的交互。

7.1 功能特性
  • 支持私聊和群聊（@机器人触发）
  • OpenClaw 被动接收消息，不能主动发起 QQ 消息
  • 支持沙箱测试环境
7.2 创建 QQ 机器人
  1. 访问 QQ 开放平台：https://bot.q.qq.com
  2. 完成开发者认证
  3. 创建机器人，获取 AppID 和 App Secret
7.3 配置环境变量

在 .env 文件中添加：

QQ_APP_ID=your-qq-app-id-here
QQ_APP_SECRET=your-qq-app-secret-here
7.4 安装中国区插件
docker exec openclaw openclaw plugins install @openclaw-china/channels
7.5 配置通道

在 config/openclaw.json 中添加：

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "${QQ_APP_ID}",
      "clientSecret": "${QQ_APP_SECRET}",
      "dmPolicy": "open",
      "groupPolicy": "open"
    }
  }
}
7.6 重启服务
docker-compose restart openclaw-gateway
7.7 验证连接
docker logs openclaw 2>&1 | grep qqbot
# 应看到：[qqbot] gateway ready

八、故障排查

8.1 模型配置错误

问题: agents.defaults.model: Invalid input

解决: 使用正确的模型格式 provider/model-id：

// 正确格式
"model": "minimax/MiniMax-M2.5"
8.2 MiniMax API 404 错误

问题: Web 界面发送消息返回 HTTP 404: 404 page not found

原因: models.json 中 api 字段与 baseUrl 不匹配

解决：

  • Anthropic 端点：baseUrl: "https://api.minimaxi.com/anthropic" + api: "anthropic-messages"
  • OpenAI 端点：baseUrl: "https://api.minimaxi.com/v1" + api: "openai-completions"
8.3 网络连接问题

问题: npm error code ECONNRESET

解决: 配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com
8.4 Colima 端口转发问题

问题: 浏览器无法访问 http://127.0.0.1:18789

解决：

  1. 在 docker-compose.yml 的启动命令中添加 --bind lan 参数
  2. 在 openclaw.json 中添加 controlUi.allowedOrigins 配置
8.5 Gateway Token 认证问题

问题: 界面显示 'unauthorized: gateway token missing'

解决：

  1. 方式一：在界面 Settings 中输入 Token
  2. 方式二：通过 URL 参数传递 Token：http://127.0.0.1:18789/?token=your-token-here

九、运维指南

9.1 日常运维命令
# 查看服务状态
docker-compose ps
# 查看实时日志
docker-compose logs -f --tail=100 openclaw-gateway
# 重启服务
docker-compose restart openclaw-gateway
# 停止服务
docker-compose down
# 更新 OpenClaw
docker-compose down
docker-compose up -d
9.2 日志管理
# 日志位置
~/openclaw-deploy/logs/
# 日志轮转配置（添加到 crontab）
00 * * * find ~/openclaw-deploy/logs -name"*.log" -mtime +7 -delete

十、切换其他模型（扩展）

OpenClaw 支持多种兼容 OpenAI API 的模型提供商，切换方式类似。

10.1 国内其他模型提供商
提供商API 地址获取 API Key模型示例
DeepSeekhttps://api.deepseek.com/v1https://platform.deepseek.comdeepseek-chat
智谱 AIhttps://open.bigmodel.cn/api/paas/v4https://open.bigmodel.cnglm-4
阿里通义https://dashscope.aliyuncs.com/compatible-mode/v1https://dashscope.console.aliyun.comqwen-turbo
10.2 切换步骤
  1. 修改 .env 文件中的 API Key
  2. 修改 docker-compose.yml 中的环境变量引用
  3. 修改 config/openclaw.json 中的模型提供商配置
  4. 重启服务：docker-compose restart openclaw-gateway

总结

本文详细介绍了在 macOS 上通过 Docker + Colima 部署 OpenClaw，并配置 MiniMax M2.5 作为大模型后端的完整方案。主要内容包括：

  1. 环境准备：安装 Colima、Docker CLI 等必要工具
  2. OpenClaw 部署：通过 Docker Compose 快速部署
  3. MiniMax 配置：详细说明 API 端点选择和 models.json 配置
  4. 安全配置：文件访问限制、网络隔离等安全措施
  5. QQ 机器人接入：扩展应用场景
  6. 故障排查：常见问题及解决方案

通过本方案，您可以快速搭建一个安全、可控的本地 AI 助手服务，并根据需要切换不同的大模型后端。

参考链接

  • OpenClaw 官网：https://openclaw.ai
  • OpenClaw GitHub：https://github.com/openclaw/openclaw
  • MiniMax 开放平台：https://platform.minimaxi.com
  • QQ 开放平台：https://bot.q.qq.com
  • OpenClaw 文档：https://docs.openclaw.ai

目录

  1. OpenClaw + Docker + MiniMax 本地部署方案
  2. 前言
  3. 一、环境准备
  4. 1.1 系统要求
  5. 1.2 安装 Homebrew
  6. 1.3 安装必要工具
  7. 安装 Node.js 22+
  8. 验证 Node.js 版本
  9. 应显示 v22.x.x 或更高
  10. 安装 Colima (Docker 替代方案，无需安装 Docker Desktop)
  11. 安装 Docker CLI
  12. 二、Colima 安装与配置
  13. 2.1 创建 Colima 配置文件
  14. Colima 配置
  15. 网络配置
  16. 允许容器访问主机网络
  17. 端口转发
  18. 挂载点
  19. 环境变量
  20. 2.2 启动 Colima
  21. 创建工作目录
  22. 启动 Colima
  23. 验证 Docker 运行状态
  24. 2.3 配置 Docker 网络
  25. 创建专用网络
  26. 验证网络
  27. 三、OpenClaw Docker 部署
  28. 3.1 创建目录结构
  29. 创建配置目录
  30. 设置权限
  31. 3.2 创建 Docker Compose 文件
  32. 3.3 创建环境变量文件
  33. MiniMax API 密钥（从 MiniMax 平台获取）
  34. https://platform.minimaxi.com
  35. Gateway 访问令牌（请设置强密码）
  36. 四、MiniMax M2.5 模型配置
  37. 4.1 获取 MiniMax API Key
  38. 4.2 创建 OpenClaw 配置文件
  39. 4.3 配置字段说明
  40. 4.4 更新 models.json 文件（重要！）
  41. 4.5 MiniMax M2.5 模型列表
  42. 4.6 重要注意事项
  43. 五、安全配置
  44. 5.1 限制文件访问
  45. 5.2 限制危险操作
  46. 5.3 网络隔离
  47. 仅绑定本地回环地址
  48. 六、验证与测试
  49. 6.1 启动服务
  50. 启动 Colima（如未启动）
  51. 启动 OpenClaw
  52. 查看日志
  53. 6.2 验证服务状态
  54. 检查容器状态
  55. 检查端口监听
  56. 测试 Web 界面
  57. 6.3 验证 MiniMax API 连接
  58. 6.4 访问 Web 界面
  59. 七、QQ 机器人接入（可选）
  60. 7.1 功能特性
  61. 7.2 创建 QQ 机器人
  62. 7.3 配置环境变量
  63. 7.4 安装中国区插件
  64. 7.5 配置通道
  65. 7.6 重启服务
  66. 7.7 验证连接
  67. 应看到：[qqbot] gateway ready
  68. 八、故障排查
  69. 8.1 模型配置错误
  70. 8.2 MiniMax API 404 错误
  71. 8.3 网络连接问题
  72. 8.4 Colima 端口转发问题
  73. 8.5 Gateway Token 认证问题
  74. 九、运维指南
  75. 9.1 日常运维命令
  76. 查看服务状态
  77. 查看实时日志
  78. 重启服务
  79. 停止服务
  80. 更新 OpenClaw
  81. 9.2 日志管理
  82. 日志位置
  83. 日志轮转配置（添加到 crontab）
  84. 十、切换其他模型（扩展）
  85. 10.1 国内其他模型提供商
  86. 10.2 切换步骤
  87. 总结
  88. 参考链接

更多推荐文章

查看全部
  • JeecgBoot 低代码平台 AI 功能与零代码开发指南
  • 三省六部架构：基于古代官制的 AI Agent 协作框架 Edict
  • 宜搭低代码开发师（高级）认证实操：待办列表功能实现
  • C++ STL 容器详解与选型指南
  • Python 与 Excel 自动化处理指南：5 步实现高效数据处理
  • 基于 Go 语言构建命令行 AI 对话客户端实战
  • Python 列表内存存储本质：差异原因与优化建议
  • uv 安装多版本 Python 及虚拟环境使用指南（替代 pyenv + pip）
  • Python 使用 Plottable 库绘制精美数据表格
  • Python 入门指南：从安装到实战
  • 分裂二叉树的最大乘积
  • iOS 设备运行 Minecraft Java 版：PojavLauncher 部署与性能优化指南
  • Dubbo 服务降级：Mock 机制原理与实战
  • C++ 备忘录模式：一个可撤销状态的实现与权衡
  • Java AI 辅助在线图书借阅平台开发实践指南
  • 大模型 AI Agent 实现 Action 的机制与流程详解
  • Helm 安装指南
  • OpenClaw Windows 部署指南：本地 AI 助手搭建与公网访问
  • 大模型微调框架 Firefly vs LLaMA Factory 对比与选型建议
  • 海光 DCU K100-AI 环境部署 Ollama 与 DeepSeek

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online

  • Markdown转HTML

    将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online