Docker 部署 OpenClaw 并接入第三方大模型 (MiniMax) 完整排坑指南

在专属算力云服务器（Ubuntu + 3090）上使用 Docker 部署 OpenClaw，并尝试接入兼容 OpenAI 格式的第三方大模型 API（以 MiniMax 为例）时，遇到了环境变量不生效、模型名称无法识别等各种"隐形坑"。

经过一系列摸索，终于跑通了最标准的配置流程。为了避免下次踩坑，特此记录这份最终版标准作业程序（SOP）。

🚨 核心避坑总结（先看这里）

不要盲目相信网上的环境变量设置！ 很多教程教你在 docker run 里加 -e PROVIDER_OPENAI_KEY=xxx，但如果你的宿主机和容器之间没有正确挂载配置文件目录，容器每次重启都会覆盖你的环境变量，或者干脆不识别这些非标准字段。
必须挂载 .openclaw 隐藏目录！ 这是 OpenClaw 的命脉，所有的网关 Token 和模型配置都存在这里。
放弃手动改 JSON，用官方可视化向导！ OpenClaw 的 openclaw.json 具有极严格的格式校验机制，手动加前缀极易报错（如 Unknown model）。最稳妥的方式是进入容器内部，调用官方自带的 openclaw configure 命令行向导。

🛠️ 终极配置实操步骤

第一步：正确启动 Docker 容器（关键在于目录映射）

清理掉旧的、报错的容器后，使用以下命令启动全新容器。注意看第 4 行 ，必须把宿主机的 ~/.openclaw 映射到容器的 /home/node/.openclaw：

Bash

复制代码

docker run -d \
  --name openclaw \
  --network host \
  -v ~/.openclaw:/home/node/.openclaw \
  -v ~/openclaw/data:/app/data \
  --restart always \
  ghcr.nju.edu.cn/openclaw/openclaw:latest

第二步：使用官方交互向导注入 API 配置（最稳妥的方案）

容器启动后，不要去手搓配置文件！直接在终端执行以下命令，唤起 OpenClaw 自带的配置向导：

Bash

复制代码

docker exec -it openclaw openclaw configure

进入向导后，通过键盘的上下键和回车键，依次进行如下选择和填写（以接入 MiniMax 为例）：

Select sections to configure: 选择 Model
Model/auth provider: 选择 Custom Provider (自定义提供商)
API Base URL: 填入带有版本号的兼容地址，例如 https://minimax.a7m.com.cn/v1
How do you want to provide this API key? 选择 Paste API key now
API Key: 粘贴你的 sk-xxxxxx 密钥
Endpoint compatibility: 选择 OpenAI-compatible (因为 URL 带了 /v1)
Model ID: 必须一字不差 地填入官方模型名称，例如 MiniMax-M2.7-highspeed

(此时系统会自动测试连通性，如果出现 Verification successful. 说明网络和密钥都没问题！)
Endpoint ID: 直接回车保持默认（例如 custom-minimax-a7m-com-cn）
Model alias (optional): 可以给它起个好记的别名，例如 xuning，然后回车保存。

向导结束后，配置会自动写入本地的 openclaw.json 并生效。

第三步：获取网关 Token (登录密码)

OpenClaw 的 Web 界面需要"网关令牌"才能连接服务器。这个令牌在你第一次成功启动容器时，就已经自动生成并保存在了配置文件里。

在宿主机终端查看这个 Token：

Bash

复制代码

cat ~/.openclaw/openclaw.json

在输出的代码中找到 gateway -> auth -> token 字段，复制那一长串字符（例如 33123c312b...）。这就是你的登录密码。

第四步：登录 Web UI 并开始对话

打开控制台： 如果在本地有端口转发，直接访问 http://127.0.0.1:18789/__openclaw__/canvas/。

如果是云服务器，请确保安全组放行了 18789 端口，然后访问 http://<服务器公网IP>:18789/__openclaw__/canvas/。
输入令牌： 在弹出的界面的"网关令牌"框中，粘贴刚才获取的 Token。底下的"密码"留空不填，直接点击连接。
选择模型开聊： 进入聊天界面后，点击顶部输入框的下拉菜单，选中你刚才配置好的模型别名（如 xuning）或全称。

发送一句"你好"，享受秒回的快感吧！

总结： 部署这类封装度极高的开源 AI 代理框架，最忌讳就是用传统 Docker 环境变量的思维去硬碰硬。顺着它自带的底层 CLI 工具（openclaw configure）去配置，才是真正的康庄大道。