Clawdbot整合Qwen3:32B保姆级教程：Docker Compose一键启停与环境变量说明

1. 为什么需要这个组合？

你是不是也遇到过这些情况：想用大模型做本地聊天，但每次都要手动启动Ollama、配置API地址、改Clawdbot的连接参数，一不小心端口就冲突；或者换台机器部署，又要重新查文档、调环境变量、反复试错？更别说团队协作时，每个人配出来的环境还不一样。

Clawdbot + Qwen3:32B 这个组合，就是为了解决“能跑通”和“好维护”之间的断层。它不是简单把两个工具拼在一起，而是通过 Docker Compose 把整个链路封装成可复现、可共享、可一键启停的标准化单元——模型服务、网关代理、前端界面，三者解耦又协同。

这里说的 Qwen3:32B，是通义千问最新发布的高性能版本，32B 参数量带来更强的逻辑推理和多轮对话能力，特别适合做技术咨询、文档解读、代码辅助等深度交互场景。而 Clawdbot 是一个轻量但功能完整的 Web 聊天前端，不依赖云服务，纯本地运行，界面干净、响应快、支持历史会话持久化。

最关键的是：它不碰任何外部 API 密钥，所有流量都在你自己的机器里流转。你掌控模型、掌控数据、掌控端口——这才是真正属于你的 AI 助手。

2. 整体架构一句话说清

整个系统只有三个核心组件，全部运行在你本机（或私有服务器）上：

  • Qwen3:32B 模型服务：由 Ollama 启动，监听 127.0.0.1:11434（默认 Ollama API 端口）
  • Web 网关代理：一个轻量 Node.js 服务，负责把 Clawdbot 的请求转发给 Ollama，并把响应原样返回，同时把 Ollama 的 11434 端口映射到对外友好的 18789
  • Clawdbot 前端：静态 HTML + JS 应用，通过浏览器访问 http://localhost:8080，所有请求都发往 http://localhost:18789（即网关）

它们之间没有中间件、没有数据库、不写日志到磁盘（除非你主动开启），结构极简，故障点少，出问题一眼就能定位到是哪一层。

小提示：你完全不需要懂 Node.js 或 Ollama 内部原理。只要会复制粘贴命令、会改几个文本字段，就能让整套系统跑起来。

3. 准备工作：5分钟搞定基础依赖

在开始之前，请确认你的机器满足以下最低要求：

  • 操作系统：Linux（推荐 Ubuntu 22.04+/Debian 12+）或 macOS（Intel/M1/M2/M3）
  • 内存：≥32GB（Qwen3:32B 推理需约 26–28GB 显存或内存，CPU 模式下走 RAM）
  • 磁盘：预留 ≥15GB 空间（模型文件约 12GB，缓存和镜像约 3GB）
  • 已安装：Docker（≥24.0）、Docker Compose（v2，已集成进 Docker Desktop 或可通过 sudo apt install docker-compose-plugin 安装）

如果你还没装 Ollama，现在就执行这一条命令（Linux/macOS）：

curl -fsSL https://ollama.com/install.sh | sh

安装完成后，验证是否正常：

ollama --version
# 输出类似：ollama version is 0.3.12

注意：不要用 sudo ollama run qwen3:32b 手动拉取模型——我们后面会统一由 Docker Compose 管理，避免权限和路径混乱。

4. 项目结构与文件准备

我们不建复杂目录，只用一个干净的文件夹。建议新建并进入：

mkdir -p ~/clawdbot-qwen3 && cd ~/clawdbot-qwen3

在这个目录下，你需要创建 3 个文件：

  • docker-compose.yml：定义服务编排（Ollama + 网关 + Clawdbot）
  • .env：存放所有可配置参数（端口、模型名、Ollama 地址等）
  • gateway.js：轻量代理脚本（仅 40 行，无需额外依赖）

下面逐个给出完整内容，请严格按格式复制，注意缩进和引号：

4.1 创建 .env 环境变量文件

# === 基础配置 ===
COMPOSE_PROJECT_NAME=clawdbot-qwen3

# === 模型服务配置 ===
OLLAMA_HOST=host.docker.internal  # Docker 内部访问宿主机 Ollama
OLLAMA_PORT=11434
MODEL_NAME=qwen3:32b

# === 网关配置 ===
GATEWAY_PORT=18789
GATEWAY_TIMEOUT=120000

# === Clawdbot 配置 ===
CLAWDBOT_PORT=8080
CLAWDBOT_API_BASE=http://localhost:18789

说明：host.docker.internal 是 Docker 提供的特殊 DNS 名，让容器内能直接访问宿主机上的 Ollama 服务。Windows/macOS Docker Desktop 默认支持；Linux 用户如遇问题，可临时替换为宿主机真实 IP（如 192.168.1.100），并在 docker-compose.yml 中加 extra_hosts。

4.2 创建 gateway.js 代理脚本

const http = require('http');
const url = require('url');
const { ClientRequest } = require('http');

const PORT = process.env.GATEWAY_PORT || 18789;
const OLLAMA_URL = `http://${process.env.OLLAMA_HOST}:${process.env.OLLAMA_PORT}`;

const server = http.createServer((req, res) => {
  const proxyUrl = new URL(req.url, OLLAMA_URL);
  const options = {
    method: req.method,
    headers: req.headers,
    timeout: parseInt(process.env.GATEWAY_TIMEOUT) || 120000,
  };

  const proxyReq = http.request(proxyUrl, (proxyRes) => {
    res.writeHead(proxyRes.statusCode, proxyRes.headers);
    proxyRes.pipe(res);
  });

  proxyReq.on('error', (err) => {
    console.error(`[Gateway] Proxy error: ${err.message}`);
    res.writeHead(502, { 'Content-Type': 'text/plain' });
    res.end('Bad Gateway: Ollama unreachable');
  });

  req.pipe(proxyReq);
});

server.listen(PORT, () => {
  console.log(` Gateway running on http://localhost:${PORT}`);
  console.log(`➡  Forwarding to ${OLLAMA_URL}`);
});

保存后，给执行权限（Linux/macOS）：

chmod +x gateway.js

4.3 创建 docker-compose.yml

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-qwen3
    restart: unless-stopped
    volumes:
      - ~/.ollama:/root/.ollama
    ports:
      - "11434:11434"
    environment:
      - OLLAMA_ORIGINS=http://localhost:8080,http://127.0.0.1:8080
    networks:
      - clawdbot-net

  gateway:
    image: node:18-alpine
    container_name: clawdbot-gateway
    restart: unless-stopped
    working_dir: /app
    volumes:
      - ./gateway.js:/app/gateway.js:ro
      - ./.env:/app/.env:ro
    command: sh -c "npm config set registry https://registry.npmjs.org/ && node gateway.js"
    environment:
      - NODE_ENV=production
    ports:
      - "${GATEWAY_PORT}:18789"
    depends_on:
      - ollama
    networks:
      - clawdbot-net

  clawdbot:
    image: ghcr.io/clawdbot/clawdbot:latest
    container_name: clawdbot-ui
    restart: unless-stopped
    environment:
      - VITE_API_BASE=${CLAWDBOT_API_BASE}
    ports:
      - "${CLAWDBOT_PORT}:80"
    depends_on:
      - gateway
    networks:
      - clawdbot-net

networks:
  clawdbot-net:
    driver: bridge

关键设计说明：

  • ollama 容器挂载了宿主机的 ~/.ollama 目录，确保模型一次下载、永久可用；
  • gateway 容器用 Alpine Node 镜像，体积仅 120MB，启动秒级；
  • clawdbot 使用官方预构建镜像，无须构建前端，开箱即用；
  • 所有服务共用 clawdbot-net 网络，内部通信走 Docker DNS，稳定可靠。

5. 一键启动：3条命令完成全部部署

准备好上面 3 个文件后，回到终端，执行以下命令：

5.1 第一步：拉取并加载 Qwen3:32B 模型（仅首次需要）

ollama pull qwen3:32b

小技巧：如果网络慢，可提前在另一终端运行 ollama serve，再开新窗口执行 pull，速度提升明显。模型约 12GB，视带宽需 10–30 分钟。

5.2 第二步：启动整个服务栈

docker compose up -d

你会看到类似输出：

[+] Running 3/3
 ✔ Network clawdbot-net  Created                                                                 0.0s
 ✔ Container ollama-qwen3     Started                                                             0.5s
 ✔ Container clawdbot-gateway Started                                                             0.6s
 ✔ Container clawdbot-ui      Started                                                             0.7s

5.3 第三步：确认服务状态

docker compose ps

正常应显示三行，状态均为 running。再检查日志是否报错：

docker compose logs -f gateway
# 应看到： Gateway running on http://localhost:18789
#         ➡  Forwarding to http://host.docker.internal:11434

验证连通性（可选）：
在宿主机执行：

curl -s http://localhost:18789/api/tags | jq '.models[].name'

如果返回 "qwen3:32b"，说明网关已成功连接 Ollama。

6. 访问与使用：打开浏览器，开始对话

现在，打开你的浏览器，访问：

http://localhost:8080

你会看到 Clawdbot 的简洁界面——左侧是会话列表，右侧是聊天窗口，顶部有模型选择下拉框（默认已设为 qwen3:32b）。

试着输入一句：

你好，你是谁？用中文回答，不超过30个字。

几秒后，你应该看到 Qwen3:32B 的回复，例如：

我是通义千问Qwen3，320亿参数的大语言模型，专注高质量对话。

成功！你已经拥有了一个完全本地、无需联网、一键启停、模型可控的 AI 聊天平台。

📸 页面截图说明（对应原文图示）：

  • 启动教程图：展示 docker compose up -d 终端输出效果；
  • 使用页面图：Clawdbot 界面，左栏会话、右栏输入框、顶部模型切换；
  • 内部说明图：架构流程图，清晰标注 Ollama → Gateway(18789) → Clawdbot(8080) 数据流向。

7. 环境变量详解：哪些可以改？怎么改才安全？

.env 文件里的每一项，都对应一个实际作用。我们按使用频率排序说明：

变量名 默认值 是否建议修改 说明
GATEWAY_PORT 18789 强烈建议 如果你本机 18789 被占用，直接改成 18790 等空闲端口，重启即可生效
CLAWDBOT_PORT 8080 推荐 若 8080 已被其他服务占用（如本地开发服务器），改为 8081 或 3000
MODEL_NAME qwen3:32b 谨慎 想换模型（如 qwen2.5:7b），只需改此项 + ollama pull 新模型，无需改代码
OLLAMA_HOST host.docker.internal ❌ 不建议 Linux 用户若无法解析，可改为宿主机 IP，并在 docker-compose.yml 的 ollama 服务下添加：
extra_hosts:
- "host.docker.internal:192.168.1.100"
GATEWAY_TIMEOUT 120000（2分钟） 大模型长思考时建议调大 Qwen3:32B 处理复杂问题可能超 60 秒，设为 300000（5分钟）更稳妥

🛑 绝对不要改的项：

  • COMPOSE_PROJECT_NAME：影响容器命名和网络隔离，改了会导致 docker compose down 清不干净；
  • OLLAMA_PORT：Ollama 固定为 11434，改了要同步改 ollama 容器端口映射；
  • VITE_API_BASE：Clawdbot 前端编译时已固化，必须与网关暴露端口一致。

改完 .env 后，只需执行：

docker compose down && docker compose up -d

无需重拉镜像、无需重下模型，3 秒内完成热更新。

8. 日常运维：启停、日志、清理全指南

这套系统设计之初就考虑了“随时可停、随时可走”。以下是高频操作清单：

8.1 一键停止所有服务

docker compose down

效果：停止并移除容器，但保留卷（~/.ollama 模型仍在）、网络、镜像。下次 up 秒启。

8.2 查看实时日志（聚焦某服务）

# 看网关转发是否正常
docker compose logs -f gateway

# 看 Ollama 是否收到请求（调试用）
docker compose logs ollama \| grep "POST /api/chat"

# 看 Clawdbot 前端错误（如 CORS、404）
docker compose logs clawdbot

8.3 清理无用镜像与构建缓存（每月一次）

# 清理已停止容器、悬空镜像、构建缓存
docker system prune -a --volumes -f

# 单独清理 Ollama 模型缓存（谨慎！会删掉所有模型）
# ollama rm qwen3:32b

8.4 升级到新版 Clawdbot 或 Ollama

# 更新 Clawdbot 前端（拉取最新镜像）
docker compose pull clawdbot

# 更新 Ollama（注意：可能重置模型，建议先备份 ~/.ollama）
docker compose pull ollama

# 重启生效
docker compose up -d

进阶提示：你可以把整个 ~/clawdbot-qwen3 文件夹加入 Git，提交 .env（记得 .gitignore 排除敏感值）、docker-compose.yml、gateway.js —— 团队成员 git clone && docker compose up -d 即可获得完全一致环境。

9. 常见问题与解决方法（实测版）

我们整理了 5 个新手最常卡住的点，附带一行命令修复方案：

现象 原因 一行修复命令
curl: (7) Failed to connect to localhost port 18789 网关容器没启动或端口被占 docker compose logs gateway | head -5 → 查端口冲突 → 改 .env 中 GATEWAY_PORT
Clawdbot 页面空白，控制台报 Failed to fetch VITE_API_BASE 和网关端口不一致 grep VITE_API_BASE .env 对比 GATEWAY_PORT，确保一致
Ollama 报错 model not found 模型没拉取或名字拼错 ollama list → 确认输出含 qwen3:32b → 若无，ollama pull qwen3:32b
输入后无响应，日志显示 timeout 网关超时太短或模型加载中 sed -i 's/GATEWAY_TIMEOUT=120000/GATEWAY_TIMEOUT=300000/' .env && docker compose up -d
Linux 下 host.docker.internal 解析失败 Docker 默认不支持该 DNS echo '192.168.1.100 host.docker.internal' >> /etc/hosts（替换成你宿主机 IP）

所有修复都不需要重装、不丢失数据、不重下模型。

10. 总结：你真正掌握的不只是部署

读完这篇教程，你拿到的不是一个“能跑的 demo”，而是一套可理解、可修改、可迁移的本地大模型工作流：

  • 你知道了 为什么用 Docker Compose 而不是裸跑：它让服务依赖显性化、端口管理集中化、启停操作原子化；
  • 你掌握了 网关存在的真正价值：不是多此一举，而是解耦前端与模型、屏蔽 Ollama 版本差异、统一超时与错误处理；
  • 你理解了 环境变量驱动配置 的工程意义：同一套代码，改 3 个字段就能切模型、换端口、适配不同机器；
  • 你获得了 可持续维护的能力：从日志定位、一键重启、到版本升级，每一步都有明确指令和预期结果。

这不是终点，而是起点。接下来，你可以：

  • 把 gateway.js 改造成支持流式响应（SSE），让 Clawdbot 实现“打字机效果”；
  • 加入 Redis 缓存会话历史，让重启后聊天记录不丢失；
  • 用 Nginx 做反向代理 + HTTPS，让家人也能通过域名访问你的 AI 助手。

真正的掌控感，从来不是“点开就用”，而是“我知道它在哪、怎么修、怎么变”。

获取更多AI镜像

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

Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

Codex 额度不够用，买 Credits 还是升级 Pro？按一个月使用量判断

avatar AI编程社区
cover

我用这两个skill，把小红书带货图文流水线彻底跑通了

avatar AI编程社区
cover

AI编写代码，谁来保证质量？

avatar AI编程社区