Clawith本地部署实战：Docker Compose与Ollama对接全攻略

最近不少人在折腾 clawith 的本地部署，这个项目说白了就是把 Claude 相关能力封装成一个可以自托管的 AI 应用入口，用 Docker 跑起来之后，你就有了一套完全由自己掌控的 AI 对话与任务执行环境。我当时第一次部署它的时候，前后花了大半天，其中一半时间耗在环境依赖和模型对接上，另一半时间在排查各种“容器起来了但用不了”的诡异问题。这篇文章把我踩过的坑、验证过的配置和排查思路完整记录下来，给正准备部署 clawith 的同学一份可以直接照着抄的作业。

先说结论：如果你只是想在本地快速跑起来，最省力的路线是 Docker Compose 一把梭；如果你打算长期用，那网络规划、模型选型和数据持久化这三件事，必须在部署前就想清楚。全文按“规划 -> 配置 -> 实操 -> 排障”的顺序展开，涉及的硬件门槛、配置文件、模型对接方式我都给出了具体参数和踩坑记录。

1. 部署前的整体规划：先搞清楚 clawith 要跑在哪、怎么跑

1.1 理解 clawith 的部署形态与核心架构

我第一次接触 clawith 的时候，第一反应是“这不就是一个普通的 Web 应用吗，装个 Node 跑起来不就完了”。真上手之后才发现，它背后并不是单进程应用，而是一个典型的本地 AI 应用栈，至少包含两个角色：

• 应用服务层：负责 Web 界面、对话管理、会话历史、配置面板这些面向用户的部分，也就是 clawith 主服务本身。
• 模型推理层：负责真正的大模型推理，常见方案有两个——对接本地 Ollama 服务，或者对接云端模型 API。

这两层可以是独立的进程，也可以通过 Docker 容器编排在一起。我在实际部署时采用的是两个容器并行跑在同一个 compose 网络里，clawith 通过服务名直接访问 Ollama。这么做的好处很明显：模型服务和应用服务解耦，将来想换模型、升级模型，不需要动应用层；反过来，应用层升级也不影响已经拉下来的模型文件。

如果你在 Windows 上部署，也可以用 Docker Desktop 跑同一套 compose 配置，只是路径映射和 GPU 透传的写法略有差别，后面我会单独说。理解了这个“应用层 + 推理层”的双层结构，你在看配置文件和查日志的时候就不会一头雾水——很多“应用起来了但答不了话”的问题，根源都在模型层。

1.2 硬件环境与系统选型：不是所有机器都适合跑大模型

部署之前先别急着敲命令，先想清楚你到底要把 clawith 跑在一个什么样的环境里。我自己用的是淘汰下来的 i5-8400 台式机，加了根 16G 内存，显卡是 GTX 1060 6GB，跑 7B 量化模型刚好够用，推理速度大概每秒 15-20 token，日常聊聊天、写写代码够用了。

给你一个可以直接参考的选型逻辑：

• 7B 级别模型（如 Qwen2.5-7B-Instruct）：量化后大约需要 4-6GB 显存，CPU 推理需要 16GB 内存，这是体验合格的入门线。
• 13B 级别模型：量化后至少 8-10GB 显存，CPU 推理建议 32GB 内存，而且速度会比较煎熬。
• 纯 CPU 环境：不是不能跑，7B 量化模型大概每秒 3-5 token，建议只做功能验证，别当主力。

操作系统方面，我的首选是 Ubuntu 22.04 LTS。原因很实际：内核版本高，Docker 支持好，NVIDIA 驱动和 container-toolkit 的兼容性踩坑最少。如果你想用 Windows，Docker Desktop 的 WSL2 后端也能跑，但 GPU 透传偶尔会有小毛病，排查起来比 Linux 麻烦。不建议在生产环境用 macOS 做容器化部署，Apple Silicon 的 GPU 架构和 NVIDIA 不一样，模型推理层很难直接复用。

1.3 Docker 环境准备：部署前的最后一道门槛

既然方案定的是容器化部署，那 Docker 环境就是硬前提。Ubuntu 上我建议直接装 Docker Engine 全家桶，不要用 snap 版（我遇到过 snap 版 Docker 在权限和网络模式上的坑）：

bash复制# 安装必要依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥和软件源
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine 和 Compose 插件
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 把当前用户加入 docker 组，免去每次 sudo
sudo usermod -aG docker $USER

装完之后记得注销重登或者执行 newgrp docker 让用户组生效。验证是否装好，跑一下 docker compose version，能看到版本号说明 Compose 插件已经就绪。如果你之前装过老版本的 docker-compose（带横杠的那个），注意命令是 docker compose（带空格），两个写法不一样，别搞混。

2. 核心细节解析：镜像、配置与密钥管理

2.1 镜像选择：版本锁定比追新更重要

部署 clawith 之前，一定要去项目仓库的 Releases 页面看一眼当前稳定版本号。我见过太多人图省事直接 latest 标签拉镜像，结果某天 docker compose pull && docker compose up -d 之后，容器起不来了，一查日志发现是新版本改了环境变量名或者数据结构不兼容。

我的习惯是：首次部署锁定具体版本号，比如 clawith/clawith:0.4.2（具体名称以你所用仓库为准），跑稳定之后再看更新说明决定要不要升级。这样做的核心价值在于可复现——半年后你想迁移到新机器，一条 docker compose up -d 就能恢复一模一样的版本，而不是拉到一个变了样的最新版。

镜像拉取慢的问题，国内网络环境下很常见。Docker Hub 的官方源在部分地区速度不稳定，我一般会配置镜像加速器，在 /etc/docker/daemon.json 里写好之后重启 Docker：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

配置完执行 sudo systemctl restart docker，再拉镜像速度会明显改善。这一步不是必须的，但能省不少等待时间。

2.2 docker-compose.yml 关键项逐行解读

clawith 的部署我强烈推荐 Docker Compose，而不是裸 docker run。原因很简单：Compose 把网络、卷、环境变量、重启策略一次性声明清楚，后续维护、迁移、回滚都方便。下面是我现在正在用的 compose 配置，你直接复制改一下就能用：

yaml复制services:
  clawith:
    image: clawith/clawith:0.4.2
    container_name: clawith
    ports:
      - "3000:80"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    depends_on:
      - ollama
    restart: unless-stopped

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ./ollama-models:/root/.ollama
    restart: unless-stopped

几个关键项我拆开讲：

• ports: "3000:80"：宿主机 3000 端口映射到容器内部 80 端口。前面是宿主机端口，后面是容器端口。如果你 3000 被占了，改成 "8080:80" 就行。
• volumes: ./data:/app/data：把宿主机 ./data 目录挂载进容器，会话记录、配置都存在这里。没有这行，容器一删数据全没。
• depends_on：声明 clawith 依赖 ollama，启动顺序有先后，但注意它只等容器启动，不等服务就绪。极端情况下 clawith 会先于 Ollama 就绪，不过因为后面的应用层有重试机制，问题不大。
• restart: unless-stopped：机器重启、进程崩溃时自动拉起，除非你手动 docker compose stop。这个策略对长期运行很重要，生产环境别用 always 之外的策略。

2.3 环境变量与密钥管理：别把 Key 写进配置文件

clawith 的很多配置是通过环境变量注入的，比如模型服务地址、API Key、日志级别这些。最容易犯的错误是图省事直接写在 docker-compose.yml 的 environment 里。我吃过这个亏：有一次把配置发给前端同事调试，里面带着真实的 API Key，后面只能紧急轮换密钥。

正确的做法是单独建一个 .env 文件，然后在 compose 里用 env_file 引用。.env 文件长这样：

bash复制# clawith 配置
CLAWITH_MODEL_PROVIDER=ollama
CLAWITH_MODEL_NAME=qwen2.5:7b
CLAWITH_OLLAMA_BASE_URL=http://ollama:11434
CLAWITH_PORT=80
LOG_LEVEL=info

# 如果走云端 API，需要配 Key，但别写死在这里
# CLAWITH_API_KEY=sk-xxxx

把 .env 加进 .gitignore，防止误提交。这一点对任何涉及密钥的项目都适用，尤其是 AI 应用，Key 泄露意味着别人可以拿你的额度去调用模型，跑一次大规模任务账单就飞了。

另外补充一个细节：http://ollama:11434 这个地址，ollama 不是域名，而是 Compose 自动创建的服务名。同一个 compose 网络里的容器，可以直接用服务名互相访问，不需要关心容器 IP。这是我强烈推荐 Compose 的另一个原因——你不需要手动查 IP，网络通了服务名就能解析。

2.4 模型服务对接：Ollama 本地模型与云端 API 的取舍

clawith 默认支持对接本地推理服务，这也是它跟直接调用云端 API 最大的区别。我在部署时认真对比过两条路线：

如果你只是自己用、或者公司内部做知识库助手，本地 Ollama 是性价比最高的方案。我个人主力是 qwen2.5:7b-instruct，中文理解和代码生成都不错，量化后体积也不夸张。如果想更进一步，可以试 qwen2.5:14b，但显存低于 10GB 就不建议了，CPU 推理会很煎熬。

Ollama 拉到本地的方式是在 Ollama 容器里执行：

bash复制docker exec -it ollama ollama pull qwen2.5:7b

如果你宿主机直接装了 Ollama（不在容器里），也可以在本机执行 ollama pull qwen2.5:7b。核心原则只有一个：clawith 配置的模型名，必须和 Ollama 里已经拉下来的模型名完全一致，包括冒号和标签。模型名不一致是最常见的报错原因之一，后面排障部分我会再提。

3. 实操过程：从零启动 clawith 的全部步骤

3.1 初始化目录结构与配置文件

我习惯把部署相关的文件都放在一个独立目录里，不散落在用户目录下。这样后续备份、迁移、清理都清晰：

bash复制mkdir -p ~/clawith-deploy/{data,ollama-models}
cd ~/clawith-deploy
touch .env

目录建好之后，先把 .env 内容写好（参考 2.3 节），再创建 docker-compose.yml。这一步的顺序不要反，因为 docker compose up 启动时会先读 .env，如果你在后启动时改了配置，需要 docker compose up -d 重新加载。

3.2 编写 docker-compose.yml：一个可以直接抄的完整示例

完整的配置我放在下面，你可以直接用。注意我把 Ollama 和 clawith 放在同一个 compose 文件里，用同一个网络，这样服务名互通不需要额外配置：

yaml复制services:
  clawith:
    image: clawith/clawith:0.4.2
    container_name: clawith
    ports:
      - "3000:80"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    depends_on:
      - ollama
    restart: unless-stopped

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ./ollama-models:/root/.ollama
    restart: unless-stopped

写完之后执行 docker compose config 验证一下语法和变量引用是否正确。这个命令会解析整个 compose 文件并打印最终生效配置，如果 .env 里有变量没设置，它会在这一步报错。这个习惯我强烈建议保留——能在启动前发现的问题，不要在启动后日志里找。

3.3 启动服务并观察日志

启动只需要一条命令：

bash复制docker compose up -d

-d 是后台运行。第一次启动会拉镜像，时间取决于网络。拉完之后执行 docker compose ps 看状态，正常情况下两个服务都应该是 Up 状态。

然后我建议立刻跟着日志看启动过程，而不是直接去访问页面：

bash复制docker compose logs -f clawith

日志里重点观察几点：有没有报数据库初始化错误（第一次启动常见于数据目录权限不足）、有没有打印监听端口、有没有尝试连接 Ollama 并成功。看到类似于“listening on 0.0.0.0:80”或者“connected to model server”的字样，说明应用层已经起来了。如果是红灯一片，先别急，后面第 4 节的排查表基本能覆盖 90% 的场景。

3.4 为 clawith 配置本地模型（Ollama 对接实操）

应用起来之后，还没法直接聊天，因为模型还没拉。我的流程是这样：

先进入 Ollama 容器拉模型：

bash复制docker exec -it ollama ollama pull qwen2.5:7b

拉取过程会显示进度条。等它完成之后，验证一下模型是否存在：

bash复制docker exec -it ollama ollama list

看到 qwen2.5:7b 出现在列表里，说明模型层就绪了。这时候再到 clawith 的 Web 界面里做模型绑定。在浏览器打开 http://localhost:3000，进入设置页面，模型提供方选 Ollama，模型名称填 qwen2.5:7b，API 地址填 http://ollama:11434——这里必须填服务名 ollama，不能填 localhost，因为 clawith 容器里的 localhost 指向它自己，不是 Ollama 容器。

填好保存之后，我习惯先在界面上发一句最简单的测试消息，比如“你好，请回复 OK”。如果返回正常，链路就通了。

3.5 访问验证与第一轮对话

到这里整个部署的完整链路是：浏览器 -> clawith 容器（80 端口）-> Ollama 容器（11434 端口）-> 模型推理 -> 返回结果展示在页面。

我验证的时候会做三件事：

1. 功能验证：问一个需要推理能力的问题，比如“用 Python 写一个快速排序”，确认不是简单关键词匹配。
2. 性能验证：连续发 5 条消息，感受首 token 延迟和平均生成速度。7B 量化模型在 GTX 1060 上首 token 大概 1-2 秒，续写速度 15-20 token/s，这个数据可以当基准参考。
3. 稳定性验证：跑一个长对话（超过 20 轮），观察会不会内存溢出或者上下文越改越卡。

如果你发现页面上能打开但是回答一直转圈，优先怀疑模型名不匹配或者 Ollama 服务没起来。用 docker compose logs ollama 看一眼，90% 的问题都能在日志里找到答案。

4. 常见问题与排查技巧实录

4.1 端口被占用导致容器启动失败

症状：docker compose up -d 报错 port is already allocated，或者 Bind for 0.0.0.0:3000 failed: port is already allocated。

原因：宿主机上已经有进程占用了 3000 端口。排查命令：

bash复制ss -lntp | grep 3000

拿到占用进程的 PID 之后，确认是不是必须保留的服务。如果是，就把 compose 里的端口映射改掉，比如改成 "3001:80"，重启服务。这里我不建议直接 kill -9 占用的进程，稳妥做法是换个端口，避免误杀其他应用。

4.2 容器启动后立即退出的常见原因

症状：docker compose ps 里显示 Exit 1 或者一直在 Restarting 状态，日志只有几行。

原因排查优先级：

1. 环境变量缺失：env_file 指向的 .env 不存在，或者里面少了必填变量。执行 docker compose config 就能看出来。
2. 数据目录权限不对：容器内的用户没有写 /app/data 的权限。解决：chmod -R 777 data 或者把宿主目录 owner 改成容器内 UID（可以在 compose 里 user: "1000:1000" 指定）。
3. 配置文件格式错误：compose 文件里多了 tab 或者缩进不对。同样用 docker compose config 检查。

我见过最多的情况是第二种，因为很多镜像默认用非 root 用户启动，宿主机挂载目录的权限它写不进去，启动时初始化数据库就会失败。遇到这个不要慌，看日志里有没有 permission denied 关键字，有的话直接调目录权限。

4.3 GPU 设备无法识别

如果你用 NVIDIA GPU 且 Docker 里看不到设备，执行 docker exec ollama nvidia-smi 报错 could not select device driver "" with capabilities: [[gpu]]，那说明 nvidia-container-toolkit 没装。

安装步骤：

bash复制distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | 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

重启后，在 compose 里给 Ollama 加上 GPU 声明：

yaml复制  ollama:
    image: ollama/ollama:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

然后 docker compose up -d 重建容器。注意 Windows 上没法直接透传 GPU 给 Linux 容器，除非用 WSL2 且安装了对应的 NVIDIA Windows 驱动，否则建议回退到 CPU 方案或者换一台 Linux 机器。

4.4 模型拉取慢或超时

症状：ollama pull 进度条卡住，或者最终报 connection error。

解决思路：Ollama 默认从官方仓库拉模型，国内网络环境经常不稳定。可以配置镜像加速地址，参考项目文档里推荐的方案。我实测下来，用可用的镜像地址之后，拉取速度提升非常明显。

还有一个经验：如果模型拉了一半失败了，重新 ollama pull 会断点续传，不需要从头再来。所以遇到超时别急着删除重来，多试几次大概率能拉完。

4.5 数据持久化与容器重建

症状：docker compose down && docker compose up -d 之后，登录态、会话记录全没了。

原因：没有挂载数据卷，或者挂载路径写错了。clawith 的数据默认写在容器内 /app/data，Ollama 模型默认在 /root/.ollama。你需要确保 compose 里 volumes 写的是这两个路径，而不是随便挂一个空目录。

我在踩过一次坑之后养成的习惯是：每次 docker compose down 之前，先看一眼 docker compose config 确认 volume 挂载正确；升级镜像之前，先把 data 目录 tar 打包备份一次。容器可以删了重建，数据必须留底。

4.6 快速排查清单

这套清单我贴在工位上，每次部署故障基本按这个顺序走就能定位。

最后再分享一个小技巧：clawith 和 Ollama 之间，尽量不要用 localhost 跨容器通信，用 Compose 服务名更稳。如果你手头有闲置的旧电脑，非常建议拿来专门跑这个部署，把容器堆在一起也不影响日常使用。部署不是终点，模型选好、数据备份好、端口规划好，后面的维护才会省心。