OpenClaw + Docker + MiniMax 本地部署“龙虾”方案教程

2026-06-17阅读 0热度 0

OpenClaw

OpenClaw + Docker + MiniMax 本地养“龙虾”方案

前言

AI 大模型赛道越来越热闹，想在本地跑一套自己的智能助手？OpenClaw 这个开源 Agent 框架挺对胃口，支持多模型后端，搭起来就能当私人助理。MiniMax M2.5 是国内大模型里的尖子生，推理能力强，中文理解也很自然。

这次分享如何在 macOS 上借助 Docker + Colima 部署 OpenClaw，换掉默认模型，换上 MiniMax M2.5 作为后盾，顺便还能接上 QQ 机器人，一套方案打通多个渠道。

方案的核心优势：

全部跑在本地，数据不怕外泄
模型随便换（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

访问 MiniMax 开放平台：
- 国内版：https://platform.minimaxi.com/user-center/basic-info
- 国际版：https://platform.minimax.io/user-center/basic-info
注册/登录账号
在「API Keys」页面创建新的 API Key
复制 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 里的配置，光改 openclaw.json 不够。

# 进入容器更新 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 完整版（推荐）204800MiniMax-M2.5-highspeedM2.5 高速版204800

4.6 重要注意事项

API 端点选择：
- Anthropic 兼容端点（推荐）：https://api.minimaxi.com/anthropic
  - API 模式：anthropic-messages
  - 支持推理（reasoning）功能
- OpenAI 兼容端点：https://api.minimaxi.com/v1
  - API 模式：openai-completions
  - 不支持推理功能
必须更新 models.json：
- 仅修改 openclaw.json 不够，OpenClaw 会从 models.json 读取实际配置
- models.json 中的 api 字段必须与 baseUrl 匹配
模型 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 连接

# 测试 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 助手聊天了。QQ官方龙虾专用入口。

7.1 功能特性

支持私聊和群聊（@机器人触发）
OpenClaw 被动接收消息，不能主动发起 QQ 消息
支持沙箱测试环境

7.2 创建 QQ 机器人

访问 QQ 开放平台：https://bot.q.qq.com
完成开发者认证
创建机器人，获取 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

解决:

在 docker-compose.yml 的启动命令中添加 --bind lan 参数
在 openclaw.json 中添加 controlUi.allowedOrigins 配置

8.5 Gateway Token 认证问题

问题: 界面显示 “unauthorized: gateway token missing”

解决:

方式一：在界面 Settings 中输入 Token
方式二：通过 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）
0 0 * * * find ~/openclaw-deploy/logs -name "*.log" -mtime +7 -delete

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

OpenClaw 支持多种兼容 OpenAI API 的模型提供商，切换方式大同小异。

10.1 国内其他模型提供商

提供商API 地址获取 API Key模型示例 DeepSeekhttps://api.deepseek.com/v1 https://platform.deepseek.comdeepseek-chat智谱 AIhttps://open.bigmodel.cn/api/paas/v4 https://open.bigmodel.cnglm-4阿里通义https://dashscope.aliyuncs.com/compatible-mode/v1 https://dashscope.console.aliyun.comqwen-turbo

10.2 切换步骤

修改 .env 文件中的 API Key
修改 docker-compose.yml 中的环境变量引用
修改 config/openclaw.json 中的模型提供商配置
重启服务：docker-compose restart openclaw-gateway

总结

这篇方案完整覆盖了在 macOS 上通过 Docker + Colima 部署 OpenClaw，并配置 MiniMax M2.5 的每一个步骤。核心要点再梳理一下：

环境准备：装好 Colima、Docker CLI 等工具
OpenClaw 部署：用 Docker Compose 一键启动
MiniMax 配置：API 端点选择和 models.json 的坑都标出来了
安全配置：文件访问限制、网络隔离，防患于未然
QQ 机器人接入：给 AI 助手加个社交入口
故障排查：常见问题直接对应解决

按照这个流程，很快就能跑起一套安全可控的本地 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