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

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

随着 AI 大模型的快速发展,越来越多的开发者希望在本地搭建自己的 AI 助手。OpenClaw 是一款开源的 AI Agent 框架,支持多种大模型后端,可以轻松构建智能对话系统。MiniMax M2.5 是国内领先的 AI 大模型,具有强大的推理能力和优秀的中文理解能力。
本文将介绍如何在 macOS 系统上,通过 Docker + Colima 部署 OpenClaw,并配置 MiniMax M2.5 作为大模型后端,同时支持 QQ 机器人接入,实现多渠道的 AI 助手服务。
方案优势:
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS 12+ (Monterey 或更高) |
| 内存 | 建议 8GB+ |
| 磁盘空间 | 至少 20GB 可用空间 |
| CPU | Apple Silicon (M1/M2/M3) 或 Intel |
如果尚未安装 Homebrew,请执行:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 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 是 macOS 上的轻量级 Docker 运行时,相比 Docker Desktop 更加轻量和高效。
创建 ~/.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
# 创建工作目录
mkdir -p ~/openclaw-workspace
mkdir -p ~/.openclaw
# 启动 Colima
colima start --cpu 4 --memory 8 --disk 60
# 验证 Docker 运行状态
docker ps
# 创建专用网络
docker network create openclaw-net
# 验证网络
docker network ls | grep openclaw
# 创建配置目录
mkdir -p ~/openclaw-deploy/{config,workspace,logs}
# 设置权限
chmod 700 ~/openclaw-deploy
创建 ~/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 所需的系统头文件创建 ~/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 替换为您的实际值。
.env 文件创建 ~/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"
}
}
}
| 配置项 | 说明 |
|---|---|
baseUrl | MiniMax API 地址(推荐使用 Anthropic 兼容端点) |
apiKey | 从环境变量 ${MINIMAX_API_KEY} 读取,避免硬编码 |
models | 必须是数组格式 |
agents.defaults.model | 必须是字符串格式 provider/model-id |
这是关键步骤! 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"
| 模型 ID | 说明 | 上下文长度 |
|---|---|---|
MiniMax-M2.5 | M2.5 完整版(推荐) | 204800 |
MiniMax-M2.5-highspeed | M2.5 高速版 | 204800 |
https://api.minimaxi.com/anthropic
anthropic-messageshttps://api.minimaxi.com/v1
openai-completionsopenclaw.json 不够,OpenClaw 会从 models.json 读取实际配置models.json 中的 api 字段必须与 baseUrl 匹配MiniMax-M2.5、MiniMax-M2.5-highspeedminimax-m2.5、MiniMax-m2.5{
"agents": {
"defaults": {
"workspace": "/home/node/workspace",
"sandbox": {
"mode": "off"
}
}
},
"tools": {
"fs": {
"workspaceOnly": true
}
}
}
{
"tools": {
"profile": "minimal",
"fs": {
"workspaceOnly": true
},
"exec": {
"security": "deny"
},
"elevated": {
"enabled": false
}
}
}
说明:
tools.fs.workspaceOnly: true - 限制文件操作仅在工作空间内tools.exec.security: "deny" - 禁止执行命令tools.elevated.enabled: false - 禁用提权操作ports:
# 仅绑定本地回环地址
- "127.0.0.1:18789:18789"
- "127.0.0.1:18790:18790"
cd ~/openclaw-deploy
# 启动 Colima(如未启动)
colima start
# 启动 OpenClaw
docker-compose up -d
# 查看日志
docker-compose logs -f openclaw-gateway
# 检查容器状态
docker ps | grep openclaw
# 检查端口监听
lsof -i :18789
# 测试 Web 界面
curl -s http://127.0.0.1:18789/ | head -20
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\"}]}"'
打开浏览器访问:http://127.0.0.1:18789
首次访问需要输入 Gateway Token(在 .env 文件中配置的 OPENCLAW_GATEWAY_TOKEN)。
OpenClaw 支持通过 QQ 官方机器人平台接入,实现 QQ 用户与 AI 助手的交互。
在 .env 文件中添加:
QQ_APP_ID=your-qq-app-id-here
QQ_APP_SECRET=your-qq-app-secret-here
docker exec openclaw openclaw plugins install @openclaw-china/channels
在 config/openclaw.json 中添加:
{
"channels": {
"qqbot": {
"enabled": true,
"appId": "${QQ_APP_ID}",
"clientSecret": "${QQ_APP_SECRET}",
"dmPolicy": "open",
"groupPolicy": "open"
}
}
}
docker-compose restart openclaw-gateway
docker logs openclaw 2>&1 | grep qqbot
# 应看到:[qqbot] gateway ready
问题: agents.defaults.model: Invalid input
解决: 使用正确的模型格式 provider/model-id:
// 正确格式
"model": "minimax/MiniMax-M2.5"
问题: Web 界面发送消息返回 HTTP 404: 404 page not found
原因: models.json 中 api 字段与 baseUrl 不匹配
解决:
baseUrl: "https://api.minimaxi.com/anthropic" + api: "anthropic-messages"baseUrl: "https://api.minimaxi.com/v1" + api: "openai-completions"问题: npm error code ECONNRESET
解决: 配置淘宝镜像源:
npm config set registry https://registry.npmmirror.com
问题: 浏览器无法访问 http://127.0.0.1:18789
解决:
--bind lan 参数controlUi.allowedOrigins 配置问题: 界面显示 'unauthorized: gateway token missing'
解决:
http://127.0.0.1:18789/?token=your-token-here# 查看服务状态
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
# 日志位置
~/openclaw-deploy/logs/
# 日志轮转配置(添加到 crontab)
00 * * * find ~/openclaw-deploy/logs -name"*.log" -mtime +7 -delete
OpenClaw 支持多种兼容 OpenAI API 的模型提供商,切换方式类似。
| 提供商 | API 地址 | 获取 API Key | 模型示例 |
|---|---|---|---|
| DeepSeek | https://api.deepseek.com/v1 | https://platform.deepseek.com | deepseek-chat |
| 智谱 AI | https://open.bigmodel.cn/api/paas/v4 | https://open.bigmodel.cn | glm-4 |
| 阿里通义 | https://dashscope.aliyuncs.com/compatible-mode/v1 | https://dashscope.console.aliyun.com | qwen-turbo |
.env 文件中的 API Keydocker-compose.yml 中的环境变量引用config/openclaw.json 中的模型提供商配置docker-compose restart openclaw-gateway本文详细介绍了在 macOS 上通过 Docker + Colima 部署 OpenClaw,并配置 MiniMax M2.5 作为大模型后端的完整方案。主要内容包括:
通过本方案,您可以快速搭建一个安全、可控的本地 AI 助手服务,并根据需要切换不同的大模型后端。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online