当前位置：首页 » AI学习教程

从踩坑到精通：OpenClaw Docker 部署实战指南（纯文字版）

1小时前 AI学习教程 12 0

MiniMax M2.7最新模型来了，开启模型的自我进化，用在OpenClaw上是什么体验，今天来实操Docker 部署并接入MiniMax M2.7

在实际部署过程中，我遇到了不少"意外惊喜"——也就是各种坑。

与其让你也踩一遍，不如我把完整的部署流程和解决方案整理出来，希望能为你节省时间。

一、环境前置准备

1.1 系统要求

依赖项	最低版本	说明
操作系统	Windows / macOS / Linux	跨平台支持
Docker	20.10+	需要较新的版本以支持现代特性
系统内存	4GB+	建议预留充足内存
网络	—	需要访问 Docker Hub 和 MiniMax API 服务

1.2 获取 MiniMax API 凭证

部署前需要准备 MiniMax 的 API 密钥。

具体步骤如下：

若尚未订阅 MiniMax 的 Coding Plan 强烈推荐Claude Code和Openclaw 订阅，量大管饱。

可通过我的专属链接享受 9 折专属优惠与 Builder 权益：

https://platform.minimaxi.com/subscribe/coding-plan

注册并登录账户

进入「API 密钥管理」创建新密钥

记录以下信息：

API Key：格式为 sk-cp-xxx

Group ID：在「账户管理」→「基本信息」中查看（部分 API 需要）

二、快速部署流程

2.1 拉取 Docker 镜像

docker pull ghcr.io/openclaw/openclaw:latest

2.2 创建配置文件

在当前工作目录创建 openclaw.json 配置文件：

{
  "meta": {
    "lastTouchedVersion": "2026.3.13"
  },
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax M2.5",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5-highspeed",
            "name": "MiniMax M2.5 Highspeed",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.5"
      },
      "models": {
        "minimax/MiniMax-M2.5": {}
      },
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  }
}

2.3 启动容器

Linux / macOS：

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v $(pwd)/openclaw.json:/home/node/.openclaw/openclaw.json \
  -e MINIMAX_API_KEY="你的API_KEY" \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

Windows PowerShell：

docker run -d `
  --name openclaw `
  -p 18789:18789 `
  -v ${PWD}/openclaw.json:/home/node/.openclaw/openclaw.json `
  -e MINIMAX_API_KEY="你的API_KEY" `
  ghcr.io/openclaw/openclaw:latest `
  node openclaw.mjs gateway --allow-unconfigured

2.4 验证部署状态

# 检查容器是否正常运行
docker ps --filter "name=openclaw"

# 检查模型状态
docker exec openclaw node openclaw.mjs models status

# 获取仪表盘访问地址
docker exec openclaw node openclaw.mjs dashboard --no-open

三、核心配置详解

3.1 配置文件结构

OpenClaw 的配置通常分布在以下位置：

~/.openclaw/
├── openclaw.json                    # 主配置文件
├── agents/
│   └── main/
│       └── agent/
│           ├── auth-profiles.json   # 认证配置
│           └── models.json          # 模型配置（可选）
└── canvas/                          # 画布目录

3.2 主配置文件字段说明

配置项	说明	备注
`models.providers.minimax.baseUrl`	MiniMax API 端点地址	必须使用 https://api.minimaxi.com/anthropic
`models.providers.minimax.api`	API 协议类型	anthropic-messages 表示 Anthropic 兼容协议
`agents.defaults.model.primary`	默认使用的模型	格式为 provider/model-id
`gateway.bind`	网关绑定地址模式	Docker 环境下应设置为 "lan"
`gateway.auth.token`	访问令牌	用于 API 认证，应设置为强密码

3.3 网关绑定模式对比

模式	绑定地址	适用场景
loopback	127.0.0.1	仅限本机访问
lan	0.0.0.0	局域网访问
auto	自动检测	自动选择合适模式

3.4 API 类型说明

API 类型	说明	适配模型
anthropic-messages	Anthropic Messages API	Claude、MiniMax 等
openai-completions	OpenAI Completions API	GPT、DeepSeek 等

四、部署中的常见问题与解决方案

问题 1：网关无法从宿主机访问

表现：容器启动后，查看日志显示绑定到 127.0.0.1，从宿主机无法连接。

[gateway] listening on ws://127.0.0.1:18789

原因：默认配置将网关绑定到容器内部的 loopback 地址，这在 Docker 环境中会被隔离。

解决方案：在 openclaw.json 中设置网关绑定模式：

{
  "gateway": {
    "bind": "lan"
  }
}

验证：重启容器后检查日志

docker restart openclaw
docker logs openclaw 2>&1 | grep "listening on"
# 期望输出: [gateway] listening on ws://0.0.0.0:18789

问题 2：调用模型返回 404 错误

表现：API 调用返回 404 错误响应。

原因：MiniMax 提供了多个 API 端点，使用了错误的地址。

端点	用途	是否正确
api.minimax.io	旧版 API	❌
api.minimax.chat	OpenAI 兼容 API	❌
api.minimaxi.com/anthropic	Anthropic 兼容 API	✅

解决方案：使用正确的 API 地址：

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic"
      }
    }
  }
}

问题 3：配置修改后不生效

表现：修改了配置文件，但容器仍然使用旧配置。

原因：OpenClaw 有多个配置文件位置，优先级不同。主配置文件 openclaw.json 中的 models.providers 优先级最高。

解决方案：确保在正确的位置修改配置。模型配置应在 openclaw.json 主文件中设置：

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "api": "anthropic-messages",
        "models": [...]
      }
    }
  }
}

验证：修改后重启容器并检查配置

docker restart openclaw
docker exec openclaw cat /home/node/.openclaw/openclaw.json

问题 4：文件权限被拒绝

表现：容器日志显示权限错误：

Error: EACCES: permission denied, open '/home/node/.openclaw/agents/main/agent/auth-profiles.json'

原因：通过 docker cp 或宿主机直接写入的文件，所有者为 root</code，而 OpenClaw 以 node 用户运行。

解决方案：修复文件权限：

docker exec -u root openclaw chown -R node:node /home/node/.openclaw
docker exec -u root openclaw chmod -R 755 /home/node/.openclaw

预防措施：使用 volume 挂载而非 docker cp，避免权限问题：

docker run -d \
  --name openclaw \
  -v ./config:/home/node/.openclaw \
  ...

问题 5：API Key 认证失败

表现：调用模型时返回 401 错误：

HTTP 401 authentication_error: invalid api key

原因：API Key 格式错误或未正确配置。MiniMax 支持多种密钥格式。

前缀	类型	说明
sk-api-	API Key	标准 API 密钥
sk-cp-	CP Key	合作伙伴密钥

解决方案：

方案 1：通过环境变量配置

docker run -d \
  -e MINIMAX_API_KEY="sk-api-xxx" \
  ...

方案 2：通过配置文件配置（在 ~/.openclaw/agents/main/agent/auth-profiles.json）：

{
  "profiles": {
    "minimax-manual": {
      "type": "api_key",
      "provider": "minimax",
      "apiKey": "sk-api-xxx"
    }
  }
}

问题 6：不确定是否需要配置 GroupId

背景：MiniMax 的不同 API 端点对 GroupId 的需求不同。

说明：

使用 Anthropic 兼容 API（api.minimaxi.com/anthropic）：无需配置 GroupId
使用 OpenAI 兼容 API 或原生 API：可能需要 GroupId 作为查询参数或请求头

配置示例：

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "api": "anthropic-messages"
        // 无需 groupId 字段
      }
    }
  }
}

五、故障诊断与排查

5.1 常用诊断命令

# 查看容器运行状态
docker ps -a --filter "name=openclaw"

# 查看容器日志（最后 100 行）
docker logs openclaw --tail 100

# 实时监看日志输出
docker logs openclaw -f

# 检查模型状态
docker exec openclaw node openclaw.mjs models status

# 验证配置文件格式
docker exec openclaw node openclaw.mjs config validate

# 进入容器进行交互式调试
docker exec -it openclaw /bin/bash

5.2 常见错误速查表

错误信息	最可能原因	快速解决方案
404 Not Found	API 端点错误	检查 baseUrl 是否为 https://api.minimaxi.com/anthropic
401 invalid api key	API Key 无效或格式错误	检查环境变量或配置文件中的 API Key
EACCES permission denied	文件权限问题	执行 chown -R node:node ~/.openclaw
Config invalid	配置文件格式错误	验证 JSON 格式，使用 config validate 命令
gateway binding to loopback	网关绑定到本地地址	设置 gateway.bind 为 "lan"

5.3 API 连通性测试

测试 MiniMax API 是否正常可达：

docker exec openclaw curl -s "https://api.minimaxi.com/anthropic/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: 你的API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"MiniMax-M2.5","max_tokens":50,"messages":[{"role":"user","content":"hello"}]}'

5.4 配置完整性检查清单

检查配置文件是否存在：docker exec openclaw ls -la /home/node/.openclaw/
检查配置文件内容：docker exec openclaw cat /home/node/.openclaw/openclaw.json
检查认证配置：docker exec openclaw cat /home/node/.openclaw/agents/main/agent/auth-profiles.json
检查环境变量：docker exec openclaw printenv | grep MINIMAX
检查模型可用性：docker exec openclaw node openclaw.mjs models status

六、最佳实践建议

6.1 使用 Docker Compose 管理部署

创建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    environment:
      - MINIMAX_API_KEY=${MINIMAX_API_KEY}
    volumes:
      - ./config:/home/node/.openclaw
    command: node openclaw.mjs gateway --allow-unconfigured
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3

创建 .env 文件：

MINIMAX_API_KEY=sk-api-xxx

启动服务：

docker-compose up -d

6.2 配置备份策略

定期备份配置文件以防数据丢失：

# 备份配置
docker cp openclaw:/home/node/.openclaw ./openclaw-backup-$(date +%Y%m%d)

# 恢复配置
docker cp ./openclaw-backup openclaw:/home/node/.openclaw
docker restart openclaw

6.3 安全加固建议

使用强令牌：生成足够长的随机访问令牌
```
openssl rand -hex 24
```

限制网络访问：使用防火墙限制来源 IP

iptables -A INPUT -p tcp --dport 18789 -s 192.168.1.0/24 -j ACCEPT

定期更新镜像：保持使用最新版本

docker pull ghcr.io/openclaw/openclaw:latest
docker-compose up -d

6.4 性能优化配置

根据实际需求调整并发参数：

{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

七、快速参考

7.1 MiniMax 可用模型列表

模型 ID	上下文长度	推理能力	说明
MiniMax-M2.5	200K	✅	推荐使用
MiniMax-M2.5-highspeed	200K	✅	高速推理版本
MiniMax-M2.1	200K	✅	M2.1 版本
MiniMax-M2	192K	✅	M2 版本
MiniMax-VL-01	200K	❌	视觉语言模型

7.2 关键环境变量

变量名	说明	示例值
MINIMAX_API_KEY	MiniMax API 密钥	sk-api-xxx
MINIMAX_GROUP_ID	MiniMax Group ID	group_xxx（部分 API 需要）
ANTHROPIC_API_KEY	Anthropic API 密钥	sk-ant-xxx
OPENAI_API_KEY	OpenAI API 密钥	sk-xxx

7.3 常用容器命令

# 生命周期管理
docker start openclaw              # 启动容器
docker stop openclaw               # 停止容器
docker restart openclaw            # 重启容器
docker rm openclaw                 # 删除容器

# 日志和调试
docker logs openclaw --tail 50     # 查看最后 50 行日志
docker logs openclaw -f            # 实时查看日志
docker exec -it openclaw /bin/bash # 进入容器 Shell

# 状态检查
docker exec openclaw node openclaw.mjs models status      # 检查模型状态
docker exec openclaw node openclaw.mjs devices list       # 列出设备
docker exec openclaw node openclaw.mjs devices approve ID # 批准设备配对

总结

通过这次完整的部署实践，我深刻理解到：OpenClaw 的部署看似简单，但细节决定成败。六个主要坑点的本质都指向一个共同问题——配置与环境的适配。

作为产品经理，我把这个经验转化为以下认知：

网关绑定地址问题 反映了容器网络隔离的特性，需要主动调整绑定模式
API URL 错误 说明了 API 版本管理的复杂性，使用官方推荐的端点是最稳妥的选择
配置文件位置混乱 暴露了多配置源的设计问题，明确优先级是必要的
文件权限问题 提醒我们 Docker 权限模型与宿主机的差异
API Key 认证 强调了凭证管理的重要性
GroupId 的有选择性 体现了 API 兼容层的复杂度

如果你在部署过程中遇到问题，建议按照「故障排查说明」的清单逐一检查，99% 的问题都能在这个流程中找到原因。

希望这份指南对你的部署之旅有帮助。如果觉得有用，欢迎点赞收藏！

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

未经允许不得转载：从踩坑到精通：OpenClaw Docker 部署实战指南（纯文字版）

请登录后发表评论