Docker版OpenClaw部署：千问3.5-9B隔离环境方案

1. 为什么选择Docker部署OpenClaw

去年我在本地尝试部署OpenClaw时，被各种依赖冲突折磨得够呛。Python版本不兼容、Node.js环境变量错乱、系统权限问题层出不穷。直到尝试了Docker方案，才发现这才是个人开发者体验OpenClaw的正确打开方式。

Docker的核心价值在于环境隔离和依赖封装。通过容器化部署，我们可以：

• 完全避免污染主机环境
• 一键重建开发环境
• 快速迁移到其他设备
• 实现版本间的秒级切换

特别是当需要对接千问3.5-9B这样的大模型时，Docker能确保模型服务与OpenClaw运行在隔离但互联的网络环境中，既安全又方便。

2. 部署前的准备工作

2.1 硬件与系统要求

我的测试环境是一台配备NVIDIA RTX 3060显卡的Ubuntu 22.04主机，这也是目前性价比比较高的配置方案。实际体验下来，建议至少满足：

• GPU：NVIDIA显卡（支持CUDA 11.7+）
• 内存：16GB以上（千问3.5-9B模型加载需要约10GB显存）
• 存储：50GB可用空间（模型权重文件约18GB）

2.2 基础软件安装

确保主机已安装最新版Docker和NVIDIA容器工具包：

# 安装Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# 安装NVIDIA容器工具包
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
      && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
      && curl -fsSL https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
            sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
            sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

验证安装是否成功：

docker run --rm --gpus all nvidia/cuda:11.7.1-base-ubuntu22.04 nvidia-smi

3. 编写docker-compose编排文件

3.1 基础服务定义

创建docker-compose.yml文件，定义两个核心服务：

version: '3.8'

services:
  qwen-service:
    image: qwen/qwen:3.5-9b-cuda
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - qwen-data:/app/data
    environment:
      - MODEL_NAME=Qwen-3.5-9B
      - MAX_TOKENS=8192

  openclaw:
    image: openclaw/openclaw:latest
    depends_on:
      - qwen-service
    ports:
      - "18789:18789"
    volumes:
      - openclaw-config:/root/.openclaw
      - openclaw-workspace:/root/workspace
    environment:
      - OPENCLAW_MODEL_PROVIDER=qwen-local
      - OPENCLAW_MODEL_BASE_URL=http://qwen-service:8000
      - OPENCLAW_GATEWAY_PORT=18789

volumes:
  qwen-data:
  openclaw-config:
  openclaw-workspace:

这个配置实现了：

1. 千问3.5-9B模型服务运行在8000端口
2. OpenClaw通过内部网络连接到模型服务
3. 关键数据通过卷(volume)持久化存储

3.2 网络连接优化

默认情况下Docker会创建桥接网络，但为了获得更好的网络性能，我推荐使用host模式：

networks:
  default:
    driver: bridge
    name: openclaw-network

# 然后在每个服务的网络配置中添加：
    networks:
      - openclaw-network

这样OpenClaw和千问服务可以通过服务名直接通信，避免了端口映射带来的性能损耗。

4. 启动与配置服务

4.1 一键启动所有服务

docker-compose up -d

首次启动会拉取两个镜像（约20GB），需要耐心等待。启动完成后可以通过以下命令检查状态：

docker-compose ps

4.2 配置OpenClaw连接模型

进入OpenClaw容器进行初始化配置：

docker exec -it openclaw_openclaw_1 bash
openclaw onboard

在配置向导中选择：

• Mode: Advanced
• Provider: Custom
• Base URL: http://qwen-service:8000
• Model: Qwen-3.5-9B

4.3 验证服务连通性

在容器内执行模型测试：

curl -X POST http://qwen-service:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen-3.5-9B",
    "prompt": "介绍一下OpenClaw",
    "max_tokens": 100
  }'

如果返回JSON格式的响应，说明模型服务运行正常。

5. 常见问题与解决方案

5.1 GPU资源不足

如果遇到类似错误：

CUDA out of memory. 

尝试以下解决方案：

1. 降低模型并行度（在qwen-service环境变量中添加）：

environment:
  - TENSOR_PARALLEL_SIZE=1

2. 启用8bit量化：

environment:
  - LOAD_IN_8BIT=true

5.2 端口冲突

如果18789或8000端口被占用，可以修改docker-compose.yml中的端口映射：

ports:
  - "18790:18789" # 主机端口:容器端口

5.3 模型加载失败

检查模型服务日志：

docker-compose logs qwen-service

常见原因是模型权重文件下载不完整，可以手动下载后挂载到容器：

volumes:
  - /path/to/model:/app/model

6. 日常使用与维护技巧

6.1 快速备份环境

整个环境的备份只需要保存两个东西：

1. docker-compose.yml文件
2. 数据卷备份：

docker run --rm -v openclaw-config:/volume -v $(pwd):/backup alpine \
  tar czf /backup/openclaw-config.tar.gz -C /volume ./

6.2 版本升级

升级OpenClaw镜像版本：

docker-compose pull openclaw
docker-compose up -d --force-recreate openclaw

6.3 资源监控

查看容器资源占用：

docker stats

设置资源限制（在docker-compose.yml中）：

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 8G

7. 为什么这个方案适合个人开发者

经过一个月的实际使用，这种Docker化部署方案展现出了几个明显优势：

1. 环境纯净：再也不用担心pip安装污染系统环境
2. 快速迁移：换电脑时只需要拷贝docker-compose.yml和备份文件
3. 版本控制：可以轻松切换不同版本的OpenClaw和模型
4. 资源隔离：模型服务的GPU资源不会影响主机其他任务

特别是当需要同时尝试多个AI项目时，Docker的隔离性让每个项目都能拥有自己独立的环境，不会相互干扰。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。