企业官网建设流程全解析

1. 部署前先搞清楚：clawith到底是什么，以及我为什么选它

凡是玩过一段时间AI编程工具的人，大概率都听过Claude Code这个名字——它把一个强大的AI编码助手塞进了命令行终端，你可以在里面直接让它读代码、改代码、跑测试，甚至是维护整个项目。但命令行的方式有个尴尬之处：终端会话绑死在本地机器上，想换个电脑继续对话很难，团队里其他人想共用一套环境更是麻烦。clawith这类应用就是干这个的，它把Claude Code的会话能力包装成一个Web服务，部署到服务器上之后，打开浏览器就能用，不依赖本机终端。

我这边最开始的需求其实很简单：团队里有三个人要同时用Claude Code，各自在本地装一套环境倒也行，可模型配置、API Key管理、历史会话这些都是各管各的，完全没有统一管理的可能性。后来我找了一圈，发现clawith正好能解决这个问题，它本质上是一个自托管的Web封装层，把Claude Code服务端化，使用者只需要登录浏览器页面，不用关心底层用的是哪个模型、配置写在哪。

这篇文章我不会去讲太多官方案例里的套话，就以我的实际部署过程为主线，把整体架构、配置细节、踩坑记录全部摊开来说。如果你也想在本地服务器上跑一个Web版AI编程环境，或者想把它接入Ollama、DeepSeek这类本地模型，这篇文章应该能帮你省下不少折腾时间。

1.1 部署思路整体拆解：一个Web壳子加一个模型通道

clawith的部署逻辑并不复杂，拆开看就是两层。第一层是Web服务本体，它负责渲染聊天界面、管理会话历史、处理用户登录和权限；第二层是模型通道，clawith本身不是一个模型，它需要调用后端的推理服务才能真正回答问题。这个后端可以是Claude官方API，也可以是Ollama拉下来的本地模型，甚至可以是Dify这类已经组装好的Agent平台。

选择这种架构的好处很明显：Web层和模型层解耦。你换模型的时候根本不用动Web界面，改一下后端配置就行。我最早用的是Claude官方API，后来想省点调用费，直接在配置里切换到Ollama跑起来的一个Qwen模型，前端页面完全不用重新部署，无缝就切过去了。

从部署方式来看，我强烈建议用Docker Compose来跑。原因很简单：clawith依赖的组件不止一个，除了Web主程序，还要有Redis做会话缓存、可能有Nginx做反向代理，这些服务如果手动一个个装，环境变量、端口、目录权限光梳理就要半天。用Compose写一个编排文件，一条命令拉起来，后续升级也只改镜像版本号，省心得多。

1.2 适用场景和典型用户：不是所有人都需要它

我得说句实话，clawith不是所有场景的必需品。如果你是个人开发者，就在自己电脑上写代码，那直接开终端跑Claude Code，完全没必要多套一层Web壳。但如果你属于下面这几类情况，那部署一个clawith就非常值得：

第一类是团队协作场景。三五个开发者在同一个项目上用AI编程助手，如果用本地终端，每个人都要配置API Key、安装依赖，而且A同学让AI改过的代码，B同学根本看不到过程。部署了clawith之后，大家统一访问同一个服务，会话记录全留存在服务器上，方便回溯。

第二类是“本机算力不够、想远程调用”的场景。比如你有台配置更高的Linux服务器，或者一台带好显卡的主机，但平时工作用的是MacBook，想在笔记本上直接操作服务器上的模型。这个时候把clawith部署在服务器上，笔记本浏览器访问就行，本地几乎不消耗资源。

第三类是把AI编程能力集成到自有系统里的用户。如果你用Dify搭了工作流，或者用AnythingLLM做了知识库，想把Claude Code变成其中一个可调用的工具节点，那通过clawith暴露一个HTTP接口，会比直接操作终端要友好得多，后续对接运维监控、日志收集也顺手。

2. 部署环境准备：该用什么机器、装什么依赖

这一步看着基础，但往往是翻车的重灾区。我先说说我自己的部署环境，然后把我试过的几种配置方案对比一下，方便你根据自己的条件选。

我的主力部署机是一台4核8G的云服务器，Ubuntu 22.04系统，磁盘60G。这个配置跑clawith本体加上一个7B级别的Ollama模型，能用但不算宽裕——同时开三个会话就会感觉到明显的响应变慢。如果是12核32G的机器，那基本就是比较舒服的状态了。个人测试的话，2核4G也能启动服务，但我建议不要低于这个配置，否则模型加载阶段内存就吃紧了。

2.1 Docker环境搭建与版本要求

clawith本体对Docker版本没有特别苛刻的要求，但建议至少是Docker 20.10以上，否则Compose V2的语法可能不兼容。我之前在一台旧服务器上装的是18.09版，直接跑docker compose up就报“unknown command”，后来升级了一下才解决。

Ubuntu上装Docker比较简单：

# 更新软件源 sudo apt update # 安装依赖 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 添加软件源 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker Engine sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

装完之后验证一下：docker --version和docker compose version。如果之前装过旧版Docker或者手动装过docker-compose二进制，建议先卸载干净再装，避免命令冲突。

2.2 网络与端口规划：别小看这个细节

clawith默认会监听一个Web端口，不同版本默认端口可能有差异，我习惯在Compose文件里显式映射出来。比如把宿主机的8080端口映射到容器内部的端口，这样外部访问就是http://服务器IP:8080。

这里有个小建议：部署的时候不要直接用80端口。80端口太容易被扫描器光顾，而且在没有配置HTTPS证书的情况下，明文传输会话内容也不安全。我自己是先用8080跑通，后续加了一层Caddy做自动HTTPS，这样才敢让团队成员在外面访问。

如果你的服务器有防火墙，记得放行对应端口。Ubuntu上如果启用了ufw：

sudo ufw allow 8080/tcp

如果用的是云厂商的安全组，也要在控制台上把端口加进白名单。这一条经常被忽略，导致服务明明起来了，外部就是访问不了，排查半天发现是安全组没放行。

2.3 模型后端选型：Ollama、Dify、还是DeepSeek API

clawith部署本身只是第一步，真正决定你用起来爽不爽的是模型后端怎么选。我实际试过的方案有三种，各有利弊，先列个表格给你参考：

我现在的生产环境是“Dify + Ollama”组合：Dify负责工作流编排和知识库检索，Ollama负责跑推理模型。这样做的原因是团队里有一部分需求是私域代码问答，不能把代码片段发给云端API，必须走本地推理。DeepSeek API我留了一条备用的通道，遇到复杂任务需要更强推理能力的时候切换过去。

3. 核心部署步骤：从配置文件到服务启动

这一节是整篇最核心的部分，我尽量写详细，你照着操作应该能把服务完整跑起来。我会按照“创建目录结构 → 编写Compose文件 → 配置模型后端 → 启动服务 → 验证可用性”的顺序来说。

3.1 目录结构与Compose编排文件

我习惯把clawith的项目文件放在/opt/clawith下面，方便统一管理。目录结构大致是这样：

/opt/clawith/ ├── docker-compose.yml ├── .env ├── data/ │ └── sessions/ ├── logs/ └── models/ └── ollama/

其中data/sessions用来持久化会话数据，logs放运行日志，models/ollama映射给Ollama容器存模型文件。为什么要把这些目录单独拎出来？因为容器本身是无状态的，一旦重建，里面的数据就全没了。如果不想每次升级后聊天记录和模型都要重新下载，就必须把数据目录挂载到宿主机上。

下面是一个精简过的docker-compose.yml示例，核心服务有四个：clawith主服务、Redis、Ollama，以及一个反向代理（我习惯用Nginx，Caddy也可以）：

version: "3.8" services: clawith: image: clawith/clawith:latest container_name: clawith restart: unless-stopped ports: - "8080:8080" environment: - REDIS_URL=redis://redis:6379 - SESSION_SECRET=change_this_to_a_random_string - CLAUDE_API_PROVIDER=custom - CUSTOM_API_BASE=http://ollama:11434/v1 - CUSTOM_API_KEY=ollama - CUSTOM_MODEL=qwen2.5-coder:7b volumes: - ./data/sessions:/app/data - ./logs:/app/logs depends_on: - redis - ollama redis: image: redis:7-alpine container_name: clawith-redis restart: unless-stopped volumes: - redis-data:/data ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ./models/ollama:/root/.ollama ports: - "11434:11434" nginx: image: nginx:alpine container_name: clawith-nginx restart: unless-stopped ports: - "443:443" - "80:80" volumes: - ./nginx/conf.d:/etc/nginx/conf.d - ./nginx/certs:/etc/nginx/certs depends_on: - clawith volumes: redis-data:

注意看几个关键点：

第一，SESSION_SECRET这个环境变量一定要改，它用来加密会话Cookie，如果留着默认值，别人可能会伪造会话。第二，我用CUSTOM_API_BASE指向Ollama的地址，这是因为Ollama提供了一个OpenAI兼容的API端点，/v1路径下可以直接调。第三，容器间的通信用的是Compose内部网络，服务名（比如redis、ollama）就相当于域名，不需要手动写IP。

3.2 模型后端的两种配置方式：直接接API还是本地推理

这里我分别说下两种方式的环境变量配置。如果你用Claude官方API，那么环境变量更简单：

environment: - CLAUDE_API_PROVIDER=anthropic - ANTHROPIC_API_KEY=sk-ant-xxxx - ANTHROPIC_MODEL=claude-sonnet-4-5

如果你用DeepSeek API，那就走OpenAI兼容协议，把base_url换成DeepSeek的地址：

environment: - CLAUDE_API_PROVIDER=custom - CUSTOM_API_BASE=https://api.deepseek.com/v1 - CUSTOM_API_KEY=sk-deepseek-xxxx - CUSTOM_MODEL=deepseek-chat

如果你坚持本地推理，那Ollama的配置就按3.1里面的写法。把这三组配置放在一起对比，你会发现clawith的适配思路很清晰：只要对方提供OpenAI兼容接口，本质上就是改CUSTOM_API_BASE和CUSTOM_API_KEY两个变量的事。

我实际部署的时候还遇到过一个坑：新版Ollama的API Base路径有的同学填的是http://ollama:11434，结果一直报错404。一定要带上/v1，也就是http://ollama:11434/v1，这个前缀不能省。

3.3 首次启动与验证：三步确认服务正常

写完配置文件之后，启动流程很直接：

cd /opt/clawith # 首次启动，拉取镜像并后台运行 docker compose up -d # 查看启动日志，确认没有报错 docker compose logs -f clawith

日志里如果看到类似“Server listening on 0.0.0.0:8080”的字样，说明主服务已经起来了。接下来做三层验证：

第一步，验证Ollama是否可用：

# 在宿主机上执行，检查Ollama容器是否跑起来 docker ps | grep ollama # 进入Ollama容器拉取一个代码模型 docker exec -it ollama ollama pull qwen2.5-coder:7b

模型下载需要一些时间，7B的模型大概有4.7G，取决于网速。这一步可以提前做，不用等clawith完全启动。

第二步，验证clawith的Web页面。浏览器访问http://服务器IP:8080，应该能看到登录页面。首次登录可能需要注册一个管理员账号，按页面提示操作即可。

第三步，发一条测试消息。在页面上输入“你好，请介绍一下你自己”，如果返回了模型回复，说明整条链路已经通了。如果页面转圈半天没反应，大概率是模型后端配置有问题，按第5节的排查表来查。

4. 与本地模型生态的深度集成：Ollama、Dify、DeepSeek、Minimax H3

跑通基础部署之后，下一步就是让clawith更好用。这里我把和本地模型生态集成的经验单独拿出来说，因为这个环节最容易踩坑，而且信息比较散，没人整理的话你得自己试错很久。

4.1 Ollama本地部署实战：从拉模型到多模型调度

Ollama是目前最适合和clawith搭配的本地推理服务，没有之一。它支持市面上绝大多数开源模型，安装简单，API兼容性好。我在3.1里已经把Ollama的容器编排写进去了，这里重点说下模型选择和调度策略。

Ollama拉模型用ollama pull命令，你可以在宿主机上直接执行：

# 拉取Meta的Llama 3.1轻量版本 docker exec -it ollama ollama pull llama3.1:8b # 拉取阿里的Qwen2.5 Coder版本，编程场景效果不错 docker exec -it ollama ollama pull qwen2.5-coder:7b # 拉取DeepSeek的蒸馏版本 docker exec -it ollama ollama pull deepseek-r1:7b

模型按需拉取就好，不用一次性全装。一个7B模型差不多占4-6G磁盘，拉五六个就是30G，磁盘很快就满了。

多模型调度方面，clawith一次只能指定一个默认模型，但你可以随时改环境变量后重启容器来切换。如果你想在Web界面里同时看到多个模型选项，需要看clawith版本是否支持动态模型列表。我用的版本支持通过特殊语法在配置里填多个模型名，用英文逗号分隔，这样聊天界面里就会出现下拉选择器：

environment: - CUSTOM_MODEL=qwen2.5-coder:7b,llama3.1:8b,deepseek-r1:7b

注意，这里能否生效取决于你的clawith版本，如果发现下拉框没有变化，那就老老实实用单模型配置，别在这个功能上死磕。

4.2 Dify本地部署教程要点：从工作流到Clawith的桥接

Dify本身是一个开源的大模型应用开发平台，你可以把它理解成一个AI应用工厂，把模型、知识库、工作流、插件都串联起来。很多团队的玩法是：Dify负责上层业务逻辑，clawith负责提供类似Claude Code的编码对话体验，两者各司其职。

Dify的部署同样是Docker Compose一把梭，但依赖的服务比较多，包括PostgreSQL、Redis、Weaviate、Sandbox等。如果你只是想和clawith对接，只启动核心服务就够了，不用全家桶都上。

Dify和clawith对接的方式是通过API。在Dify后台创建应用之后，会生成一个API Key，然后你在clawith侧把模型后端指向Dify的接口地址：

environment: - CLAUDE_API_PROVIDER=custom - CUSTOM_API_BASE=http://dify:5001/v1 - CUSTOM_API_KEY=app-xxxxx - CUSTOM_MODEL=your-workflow-name

这里的核心逻辑是：clawith发出的请求走的是OpenAI兼容协议，而Dify也支持这个协议，所以两边能直接通话。但你要注意，Dify的响应格式和标准OpenAI稍有差异，如果发现请求成功但回答解析不了，可能需要在clawith侧开启一个“兼容模式”开关，具体参数名要看版本文档。

就我的实际体验来说，Dify接入clawith更适合做知识库问答场景，不适合当默认编码后端，因为中间多做了一层工作流处理，响应延迟会明显高一些。

4.3 DeepSeek与Minimax H3本地部署的取舍

关于DeepSeek，这里要区分两个概念：DeepSeek官方API和DeepSeek开源模型本地部署。官方API的接入方式在3.2里已经写了，性价比很高，中文能力也强。如果你想本地部署DeepSeek模型，那本质上就是用Ollama或vLLM跑推理服务，然后把clawith的CUSTOM_API_BASE指过去。

Minimax H3是另一家模型的本地版本，它最大的特点是长上下文处理能力做得不错。我测试过Minimax H3的本地部署，过程其实和部署其他大模型没太大差别，核心步骤就三个：下载模型权重、用推理框架启动、配置API地址。之所以单独提它，是因为它的参数规模和显存要求跟常见的7B模型不太一样，部署前务必确认服务器显卡的显存足够——如果显存不足，强行加载会直接OOM，进程崩溃。

另外我踩过的一个坑是：本地部署DeepSeek或者Minimax H3的时候，环境变量里的模型名称一定要和模型文件里的名称准确对应。Ollama里可以用ollama list查看模型名，有些同学图省事随便填了个别名，结果clawith那边一直报“model not found”，白白折腾了半个小时。

4.4 ComfyUI、AnythingLLM等周边工具的接入思路

搜索热词里还有一圈周边工具，比如ComfyUI本地部署和AnythingLLM离线部署。这些虽然跟clawith的核心功能不冲突，但你可以把它们组合成一条完整的AI工作链路。

举个例子，ComfyUI是做AI绘画的界面工具，AnythingLLM是做知识库问答的工具。如果我的工作流里同时有代码生成和文生图的需求，我可以让clawith处理代码逻辑，ComfyUI处理图片生成，AnythingLLM处理文档检索。三者之间通过Dify工作流串联：clawith先分析用户意图，需要找资料的时候调用AnythingLLM的API，需要生成示意图的时候调用ComfyUI的接口，最终把结果汇总给用户。

这种组合方式看起来很酷，但实际操作中要注意一个问题：每个服务都会占一部分端口、内存和CPU资源，一台8G内存的服务器如果全跑起来会非常紧张。建议按需启动，不要所有服务常驻后台。我是用systemd管理这些容器的启停，需要哪个服务就启动哪个，用完就停。

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

部署过程中我前前后后踩了不少坑，这一节我把高频问题和排查思路整理出来，按“症状→原因→解法”的格式列出来，方便你遇到问题时直接对照。

5.1 页面打不开或登录异常

我自己遇到最多的是第一种和第三种。第一种主要是云服务器安全组没放行，页面一直转圈。第三种是因为我开始图省事用的SESSION_SECRET太简单，容器一重启会话就失效，换了个长随机串后就好了。

5.2 模型没有响应或报错信息一堆

这里多嘴一句：Ollama的/v1/models接口是一个很好的自检工具。如果你不确定本地模型服务是否正常，在宿主机上执行这条命令，能返回模型列表就说明Ollama没问题，问题出在clawith侧的配置上。

5.3 容器资源占用过高与优化

clawith主体本身不算吃资源，真正吃资源的是模型推理服务。一个7B模型在CPU上推理时，8G内存的机器基本会被占到80%以上。如果你的服务响应越来越慢，可以从几个方向优化：

第一，限制Ollama的并发数。Ollama默认会接受所有请求，如果多个用户同时提问，推理任务排队会让每个请求都变慢。在Compose文件里可以设置OLLAMA_NUM_PARALLEL=1，强制串行处理。

第二，给容器设置内存上限。在Compose文件里：

services: ollama: deploy: resources: limits: memory: 8G

注意这个语法在Docker Compose V2里是支持的，但某些老版本可能需要用mem_limit这种写法。

第三，如果长期使用，建议优先用GPU推理。在Compose里加上显卡映射：

services: ollama: deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

前提是你装了NVIDIA Container Toolkit。GPU推理的速度比CPU快一个数量级，8G显存跑7B模型很流畅，基本可以实时显示了。

5.4 离线环境的部署方案

有些内网环境不能直接拉镜像和模型，这时候部署会多几步手工操作。我的经验是分两条路走：

镜像传输：在一台能上网的机器上先把镜像打出来，然后导入到目标机器。

# 在能上网的机器上 docker pull clawith/clawith:latest docker save clawith/clawith:latest -o clawith.tar # 拷贝到目标机器后 docker load -i clawith.tar

模型传输：Ollama的模型文件都在/root/.ollama/models目录下，把整个目录打包传到目标机器上，再挂载到容器的对应路径就行。

# 在源机器上 tar czf ollama-models.tar.gz /root/.ollama/models # 在目标机器上解压到./models/ollama/，保持目录结构一致 tar xzf ollama-models.tar.gz -C /opt/clawith/models/ollama

AnythingLLM离线部署也适用类似的思路，它额外依赖Elasticsearch或LanceDB做向量存储，这三套容器全部离线导入即可。

5.5 日志查看与持久化排查

如果服务还是有问题，最后一个可靠的排查手段就是看日志。Docker Compose统一管理了所有容器的日志，可以按服务查看：

# 查看clawith的最近100行日志 docker compose logs --tail=100 clawith # 实时跟踪日志输出 docker compose logs -f --tail=50 clawith

日志文件我习惯同时持久化到宿主机上，这样即使容器销毁了，历史日志也还在。方式是在Compose文件里把/app/logs目录挂载出来，然后配合logrotate做轮转，防止日志文件无限膨胀。我这边设置的是每天轮转一次，保留14天。

6. 从部署到稳定运行的几点个人体会

坦白说，clawith的部署难度不算高，真正花时间的是把它调试到“让团队用得顺手”的状态。这里分享几条我个人在实践中总结的经验，想到哪说到哪，没有严格的逻辑顺序，但每一条都是真金白银换来的。

第一，部署前先想清楚模型后端的定位。如果只是个人尝鲜，直接连Claude官方API或者DeepSeek API就行，五分钟搞定。但如果你是给团队搭服务，千万别一上来就把API Key裸放在配置里——建议用Docker的secret机制或者环境变量管理工具来保存密钥，同时配合Dify的权限控制，让普通用户接触不到底层Key。

第二，升级要谨慎。clawith和Ollama版本更新都比较勤，我吃过一次亏：某次例行升级clawith版本后，Ollama的兼容协议变了，导致Web界面全部报错。所以升级前一定先看release notes，备份data/sessions和docker-compose.yml，尽量在非工作时间操作，升级后立刻回归测试。

第三，别忽视日常巡检。我写了几个简单的定时脚本，每天检查一下容器状态和磁盘空间：

# 检查所有容器健康状态 docker ps --filter "status=running" # 查看磁盘使用率 df -h /opt/clawith

这些操作配到crontab里，每天早上推一条通知到群里，哪个容器挂了、磁盘满了，第一时间就能发现，不用等用户反馈才知道出问题。

第四，关于扩展性的建议。如果团队规模变大，clawith跑在单机上的瓶颈会越来越明显，尤其是会话并发多了以后，单机部署很难扛住。这时候可以考虑把Ollama单独拆到一台带GPU的机器上，clawith和Ollama之间走内网API通信，Web服务和推理服务分离。我后续规划就是往这个方向走，再配合Kubernetes做容器编排，不过这是后话了，对于中小团队来说，单机部署加一台GPU推理机已经能覆盖绝大部分场景。

部署这件事，从来不是“跑起来就完事”。从最初的个人尝鲜，到后来团队共用，再到跟Dify、Ollama这些生态工具打通，整个过程中我踩过的每一个坑，回头看都是对这套系统理解更深一层的机会。如果你照着这篇文章把clawith跑起来了，大概率也会遇到一些我没提到的新问题，别怕，多看看日志、多翻翻官方文档，大部分问题都有迹可循。

最后再分享一个小技巧：在clawith的配置文件里，环境变量改动后不用删除整个容器，只需要docker compose up -d重新应用配置即可，它会自动重建受影响的容器。这个操作比docker stop、docker rm再docker run一步步来要安全得多，也快得多。希望这篇文章能让你少走一些弯路。