企业官网建设流程全解析

简介：一份面向开发者的容器化 OpenClaw 安装配置实操指南，着力解决快速迭代环境中部署该人工智能系统时的环境搭建与版本管理难题。内容涵盖手动安装完整步骤、通过 Dockerfile 构建自定义镜像的优化做法，并覆盖网关配置、插件冲突规避、网络参数调整等易错环节，适合正在开展模型测试或准备进入生产部署的 Python、运维及算法工程师。压缩包共 8 个文件，大小约 12KB，主要由可执行安装脚本、容器编排文件、配置模板、项目说明文档及忽略清单组成，覆盖 Shell、标记语言、数据序列化等类型，便于直接修改复用。已有 1358 人学习/下载，可作为快速上手与反复回退版本时的参考。借助这套材料，使用者能够按模板完成部署，减少踩坑，并利用容器隔离特性在不同配置间灵活切换，显著提升开发与交付效率。

1. 用Docker装OpenClaw：把AI Agent从环境泥潭里捞出来的省心路径

OpenClaw 是一个能自主拆解任务、调用工具、执行命令并迭代结果的终端 Agent 项目，上手之后能替你跑不少重复的脏活。但多数人第一次部署 OpenClaw 时，真正卡住的不是 Agent 不智能，而是环境装不上——Python 版本对不上、依赖包互相打架、系统缺了某个底层库，一条报错就能耗掉半小时。用 Docker 部署 OpenClaw 的价值恰恰在于此：项目运行所需的整套运行时被冻结进镜像，宿主机只要保留 Docker 运行时，换电脑、迁服务器都能快速拉起同样的环境。这篇面向准备认真用 OpenClaw 的从业者，从镜像选型、容器参数、模型接入到高频翻车点的排查，按可复现的步骤写下来，照着做完能省掉几小时无意义的折腾。

2. 部署前先定方案：镜像标签、Docker 运行时与网络三条线

动手敲 docker run 之前，建议先把三件事定下来：镜像从哪来、宿主机的 Docker 运行时选哪样、容器外网链路怎么走。这三条任何一条没想清楚，后面都会在奇怪的位置卡住，而且排查起来往往比部署本身更耗时。

2.1 拉官方镜像还是本地构建：先查标签，再用 Dockerfile 兜底

配置 OpenClaw 镜像时，优先去 Docker Hub 官方仓库看是否有现成镜像。官方镜像的优势是别人已经把系统依赖、启动脚本和默认配置打包好，你只需要做两件事：选一个合适的 tag，然后把配置目录和密钥挂进去。tag 选型有个原则——别追 latest，去看已发布版本里的稳定号。latest 镜像可能带有未验证的改动，哪天重新拉取后镜像内容变了，agent 行为也跟着变，事后排查会非常费劲。

如果官方仓库找不到可用镜像，或者拉取 Docker Hub 不稳定，就用本地构建兜底。OpenClaw 是 Python 项目，一个最小可用的 Dockerfile 大概长这样：

FROM python:3.11-slim # 装基础工具：git 用来拉代码、curl 用来探活、ca-certificates 解决 HTTPS 证书问题 RUN apt-get update && apt-get install -y --no-install-recommends \ git curl ca-certificates \ && rm -rf /var/lib/apt/lists/* WORKDIR /app # 先单独拷贝依赖声明并安装，利用 Docker 层缓存减少后续构建时间 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "main.py", "run"]

这段 Dockerfile 的核心逻辑是分层缓存。把 requirements.txt 单独拷贝并安装，之后即使项目代码频繁改动，pip install 这一层也不会重新执行，构建速度提升明显。python:3.11-slim 相比完整版镜像少了编译工具链，体积更小，适合只跑不改代码的场景。启动命令用 CMD 而不是 RUN，是为了让容器启动时才拉起 agent 进程，方便通过 docker logs 观察输出。

实际构建时，如果 OpenClaw 依赖某些原生编译库，要在 apt-get install 那行补上对应的 -dev 包，否则 pip 安装阶段会当场报错。我习惯在镜像构建完成后先跑一次 --version 探活，确认进程能起来再进正式部署，避免把构建阶段的问题带到运行阶段去排查。

提示：自构建镜像虽然稳妥，但每次上游代码更新都要重新 build。如果官方镜像存在，优先用官方镜像是省力路径；本地 Dockerfile 只是兜底方案。

2.2 宿主机运行时怎么选：Windows 选 Docker Desktop，Linux 选原生引擎

宿主机侧的 Docker 运行时，主流选择就两条路：Windows 和 macOS 用 Docker Desktop，Linux 服务器装 Docker Engine。Docker Desktop 对新手友好，安装包点几下就能装好，但它依赖 Windows 的 WSL2 或 Hyper-V 后端；如果机器 BIOS 里没开启虚拟化，装完根本起不来，经典的 "virtualization support not detected" 报错就是从这里来的。

Linux 端直接安装 Docker Engine 即可。Ubuntu 上的常见做法是先卸载旧版本，再通过 apt 仓库安装 docker-ce、containerd 和 runc 组件，装完执行 sudo usermod -aG docker $USER，把当前用户加进 docker 组，注销重新登录后就能免 sudo 敲 docker 命令。这里有个很隐蔽的注意点：加完用户组后，当前终端会话不会立即生效，必须注销重登或重启系统，否则 docker 命令会一直报 permission denied。

运行时选型还要考虑资源预算。Docker Desktop 默认分配的内存通常是 2GB 左右，同时跑多个 agent 容器会很紧张。OpenClaw 这类 Agent 在执行多轮工具调用时，Python 进程加上模型推理的开销并不小，建议把 Docker Desktop 的内存上限调到 4GB 以上。内存给少了，容器会莫名 OOM，日志里还看不出明确原因。

2.3 容器外网链路：先让容器能访问模型 API，再谈部署

几乎所有 OpenClaw 的 agent 行为都依赖 LLM API。容器默认走宿主机的网络栈，但两个典型场景会卡住外网：一是宿主机本身依赖代理才能访问外网，二是企业内网有透明代理或自签证书。Docker 不会自动继承宿主机的代理环境变量，结果容器里 curl 外网 API 直接超时，宿主机却一切正常。

处理办法是在 docker run 或 compose 环境变量里显式注入代理配置：

docker run -d --name openclaw \ -e HTTP_PROXY=http://192.168.1.10:7890 \ -e HTTPS_PROXY=http://192.168.1.10:7890 \ -e NO_PROXY=localhost,127.0.0.1 \ openclaw/openclaw:latest

HTTP_PROXY 和 HTTPS_PROXY 是容器内 Python 请求库普遍识别的环境变量，NO_PROXY 用于排除本地地址，避免容器内其他服务访问被错误绕到代理。如果宿主机代理是明文 HTTP 代理，容器里无需额外处理；如果需要认证，变量写成 http://user:pass@host:port 格式。判断容器网络是否已通，先用 docker exec openclaw curl -I https://dashscope.aliyuncs.com 探一次，能返回 HTTP 状态码就说明链路通了。

镜像来源、运行时选型、外网链路这三条确认完后，再进入部署阶段会比较稳。跳过任意一条，后面大概率要回头返工。

3. 最小部署三步走：docker run、数据卷挂载、接上千问

方案定了就动手。这章按三步往下走：把容器跑起来、把配置和密钥挂载进去、最后把 OpenClaw 接到 LLM 上，并示范用千问作为模型来源的具体配置。

3.1 最小化 docker run：跑出第一个容器

第一次跑 OpenClaw，建议不要加太多参数，先做一个最小可运行容器，确认镜像本身没问题：

docker run -it --rm --name openclaw-test \ openclaw/openclaw:latest \ --version

--rm 表示容器退出后自动删除，适合一次性探活；-it 保留交互终端，方便看到进程直接输出；--name 给容器命名，之后 docker logs openclaw-test 能直接查看它的日志。如果镜像不存在，docker 会自动拉取。这里建议先单独执行 docker pull openclaw/openclaw:latest，把拉取和运行分开，报错时更容易定位是哪一步失败。

确认镜像可用后进入正式运行。正式运行要带上数据卷和密钥，避免每次重启都从零开始：

docker run -d --name openclaw \ -v ~/.openclaw:/root/.openclaw \ -e OPENAI_API_KEY=sk-xxxx \ -e OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" \ -e OPENAI_MODEL_NAME=qwen-plus \ -e TZ=Asia/Shanghai \ --restart unless-stopped \ openclaw/openclaw:latest

各参数的含义需要仔细说。 -d 让容器在后台运行，日志交给 docker logs 查看，不会因为关掉终端就杀掉 agent。 -v ~/.openclaw:/root/.openclaw 是数据卷挂载，把容器内 agent 的会话、配置、临时文件都落到宿主机目录，这是整个部署里最关键的一个参数，后面避坑章节会展开讲它为什么关键。 -e OPENAI_BASE_URL 指向千问的 OpenAI 兼容接口，表示模型调用走 OpenAI 协议。当前很多国产模型的云服务都提供这种兼容端点，OpenClaw 这类项目也优先支持该协议。 -e OPENAI_MODEL_NAME 指定模型名，qwen-plus 是千问的中端均衡型号，适合日常任务；要更强推理可换 qwen-max，要更快更便宜则换 qwen-turbo。 -e TZ=Asia/Shanghai 设置容器时区，避免 agent 任务里涉及时间判断时出现八小时偏差。--restart unless-stopped 让容器在宿主机重启或进程崩溃后自动拉起，但这个策略不会在你手动 docker stop 时复活容器，行为上相对可控。

容器起来后第一件事是看日志，而不是直接发任务：

docker logs -f openclaw

如果日志里出现 agent 启动成功的标志，说明容器本身没问题，接下来把配置挂载补齐就行。如果日志里没有输出或者卡住不动，跳到第 4 章的对应排查条目处理。

3.2 用 docker-compose 编排：把参数写成可提交的配置文件

docker run 适合首次验证，参数一多就难维护。长期使用建议换成 docker-compose.yml，把镜像、数据卷、密钥、代理全部写进一个文件，团队协作时还能把配置文件作为项目代码提交。

services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped volumes: - ./data:/root/.openclaw environment: - OPENAI_API_KEY=${OPENAI_API_KEY} - OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 - OPENAI_MODEL_NAME=qwen-plus - HTTP_PROXY=${HTTP_PROXY} - HTTPS_PROXY=${HTTPS_PROXY} - NO_PROXY=localhost,127.0.0.1 - TZ=Asia/Shanghai

这套 compose 文件的要点有三个。第一，数据卷从宿主机绝对路径改成相对路径 ./data，整个目录随项目走，换机器时拷贝项目目录就能带走配置和会话。第二，密钥从 environment 里直接写值改成 ${OPENAI_API_KEY}，配合同目录下的 .env 文件存放真实值，避免把密钥明文提交进 git 仓库。第三，restart 策略在 compose 里直接写成配置，省去 docker run 时的手动参数。

从 docker run 切换到 compose 后，日常管理动作变成：

docker compose up -d docker compose logs -f docker compose down

只改了环境变量或挂载路径时，不用整个删除重建，执行 docker compose up -d 会自动识别配置变更并重建容器。这里要提醒一句：compose 重建容器时如果数据卷没挂对，可能产生一个全新空状态，因此升级配置前先备份 ./data 目录。Compose 的真正优势在于可复现：一个 yml 文件加一个 .env 文件，到哪台机器都能拉起同一套环境，比 docker run 的长命令可靠得多。

3.3 选择 channel：终端、网页还是 Teams

OpenClaw 支持通过不同渠道与 agent 交互，官方常见的有终端直连、Web 界面、以及对接外部团队协作工具。channel 的选择直接决定部署形态，因为不同 channel 的依赖和服务方式差别很大，需要在镜像构建或容器参数里提前考虑。

终端 channel 最省事，容器启动后直接在 TTY 里和 agent 对话，适合本地调试和逻辑验证。注意容器以 -d 后台运行时，终端 channel 就不可用了，因为没有交互终端挂在进程上。这种情况下可以进入容器附加交互会话：

docker exec -it openclaw python main.py run --channel terminal

--channel 参数用于指定渠道，terminal 代表终端直连。docker exec 进入容器后运行的进程会绑定到当前终端，agent 输出实时显示，方便观察完整的一轮任务执行过程。Web 和 Teams 这类 channel 适合长时间挂机运行：容器启动后 agent 在后台待命，你通过网页或 Teams 发任务给它。这类 channel 需要额外配置对应的 token 或 webhook。切换 channel 时，先确认该 channel 的依赖包是否已经打进镜像，没有的话要么改 Dockerfile 重新构建，要么在容器里 pip 安装后重启进程。

模型侧的配置同样影响 channel 的使用体验。下表是千问几个常用模型的选择参考：

如果走 OpenAI 官方模型，只需把 BASE_URL 改成官方端点并填写对应 key；如果接本地模型或内网模型服务，BASE_URL 指向局域网地址即可。注意容器内访问宿主机局域网服务时，地址不要写 localhost，要写宿主机在 Docker 网络里的网关地址，或在 compose 里用 extra_hosts 把宿主机域名映射到固定 IP。

4. OpenClaw 容器部署避坑：现象、原因、解决

这一章是实际部署中价值最高的部分。下面每条都按现象、原因、解决三段来写，便于直接对照排查。

4.1 session file locked 超时：碰到的第一个锁问题

现象：容器起来后发第一条消息，agent 没有回应，日志里出现 agent failed before reply: session file locked (timeout 60000ms)，整个会话像被冻住，等一分钟左右才报错。

原因：OpenClaw 用会话文件持久化对话进度，为保证并发安全，每个会话文件带锁机制。出现这个报错通常是上次进程异常退出，锁文件残留在会话目录里；或者同时启动了两个 agent 实例，指向同一个会话目录，互相争锁谁也不让谁。

解决：先停容器，进会话目录清理 .lock 残留文件，再启动。

docker stop openclaw find ~/.openclaw -name "*.lock" -delete docker start openclaw

如果问题来自多实例竞争，检查是否用同一个数据卷启动了多个容器。生产环境要并发跑多个 agent，必须给每个实例分配独立的会话目录，绝对不要共享同一个 ~/.openclaw 卷。我第一次遇到这个报错时查了半天网络，最后才发现是文件锁，属于典型的血泪经验。

4.2 容器里连不上模型 API，宿主机 curl 却正常

现象：agent 一直报模型调用超时，但在宿主机上 curl 同一个 API 地址能正常返回。

原因：宿主机和容器网络栈并不一致。Docker 默认 bridge 网络本身能出外网，但宿主机开着代理时，容器不会继承代理变量。另外一类是 DNS 问题，容器内 /etc/resolv.conf 指向的 DNS 服务器解析不了外网域名。

解决：按优先级做三件事。先确认容器内能否解析域名：docker exec openclaw getent hosts dashscope.aliyuncs.com，解析不通就加 --dns 参数指定公共 DNS，比如 223.5.5.5。解析通了还是超时，就把宿主机代理地址注入容器环境变量，并确认变量真的传进去了：docker exec openclaw env | grep -i proxy。如果都没有问题，再检查宿主机防火墙或安全组是否放行了容器所在网段的出站流量。

这条坑在网络排查里常被描述得很玄学，一会儿说是容器网络问题，一会儿说是镜像问题，实际上九成是代理变量没传进去。

4.3 重启容器后 Agent 失忆：数据卷根本没挂上

现象：容器跑了一天，docker restart 之后 agent 不认识之前的会话，任务历史全部消失。

原因：数据卷挂载失败。最常见的是 docker run 时宿主机目录写错，Docker 会悄悄创建一个空目录当数据卷，而不会报错。比如 -v ~/.openclaw:/root/.openclaw，如果家目录下本来没有 .openclaw 文件夹，Docker 会直接新建一个空目录，容器内看到的永远是空会话。

解决：先验证数据卷挂载是否真实生效：docker inspect openclaw --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{end}}'，确认宿主机路径。然后停容器，把当前容器里的会话文件 cp 出来，再重新挂载到正确路径。以后启动任何带数据卷的容器，第一件事就是往会话目录写一个测试文件，重启容器确认文件还在，再跑正式任务。这个习惯能省掉一大类难以察觉的状态丢失问题。

4.4 Docker Desktop 启动失败：virtualization support 未开启

现象：Windows 上装完 Docker Desktop，双击启动报错，日志提示 virtualization support not detected，或者 vmmem 进程根本没起来。

原因：Windows 的 Docker Desktop 依赖 Hyper-V 或 WSL2 后端，两者都要求主板虚拟化（VT-x 或 AMD-V）在 BIOS 里开启。很多品牌机默认关闭虚拟化，装完 Docker 启动时才暴露出来。

解决：重启进 BIOS 设置，找到 Intel Virtualization Technology 或 SVM Mode，改成 Enabled，保存重启。进 Windows 后再检查功能开关：控制面板里启用"虚拟机平台"和"适用于 Linux 的 Windows 子系统"。偶尔还要在 PowerShell 里执行 wsl --update 更新 WSL 内核，Docker Desktop 才能正确识别后端。这个耗时点在部署 OpenClaw 之前先确认掉，不然等容器起不来才发现 BIOS 没开，属于典型的纯浪费时间。

4.5 容器一直运行但日志毫无输出：把黑匣子拆开看

现象：docker ps 显示容器 Up 状态，docker logs 却什么都没有，发任务也没反应。

原因：agent 进程在等待输入，或者 stdout 被缓冲。Python 进程在非交互模式下 stdout 默认是块缓冲，输出不会实时写入日志。Docker 里跑 Python agent 特别容易遇到这个，日志空着看起来像死机，实际进程在等输入或任务队列。

解决：改启动命令让 Python 以无缓冲模式执行：

docker run -d --name openclaw \ python -u main.py run

在 Dockerfile 的 CMD 里加上 -u，或者 docker run 时覆盖启动命令。同时确认 agent 是否在等交互式配置输入，有些 channel 启动时需要确认 token，容器没有终端挂着就会卡在那里。遇到这种情况，用 docker attach openclaw 附加到容器，看进程到底卡在哪一步，把黑匣子打开再判断。

4.6 数据目录权限错乱：容器内 root 与宿主机用户的冲突

现象：容器能跑，但 agent 写会话文件时报 Permission denied，或者宿主机上打开挂载目录发现所有文件 owner 都是 root，无法直接用普通用户编辑。

原因：容器内进程默认以 root 运行，挂载目录里的文件自然归属 root。宿主机普通用户读取没问题，但写入或删除会受限。反过来，如果挂载目录 owner 是宿主机普通用户，容器内 root 反而写不进去，这取决于目录权限位和挂载选项。

解决：简单粗暴的做法是让容器以宿主机用户 UID 运行：

docker run -d --name openclaw \ --user $(id -u):$(id -g) \ -v ~/.openclaw:/root/.openclaw \ openclaw/openclaw:latest

--user 指定容器内进程的 UID 和 GID，与宿主机当前用户保持一致，写出的文件宿主机就能直接管理。注意改成普通用户后，容器内如果还需要写 /root 下的某些配置，要确保该路径对当前 UID 可写，否则要额外调整挂载目标目录的权限。

5. 部署收尾：三个验证方法确认 agent 真的在干活

容器起来了、日志也有了，不代表 OpenClaw 可用。我会用三个方法确认整条链路是真正通的，而不是表面 Up 实际空转。

5.1 跑一个必成功的小任务当烟雾测试

不要一上来就让它写代码做分析，先让它执行一个确定不会失败、但必须经过模型调用的任务，比如"用一句话介绍你自己"。这个任务能正常返回，说明模型接入、会话锁、网络链路都是通的。接着跑一个需要工具调用的任务，比如"列出当前目录的文件"。这个任务会触发 agent 实际执行 shell 命令，能确认工具执行链路没有断。

5.2 检查会话文件与日志级别

任务跑完，去挂载目录里确认会话文件是否更新了时间戳，工具调用日志里有没有记录执行命令和返回结果。如果 agent 项目支持日志级别调整，把日志调到 debug，能看到模型请求和响应的完整记录。docker logs 只能看到进程 stdout，落盘文件的明细才是排查的依据。

5.3 并发与重启压测

如果准备让 OpenClaw 长期挂机，最后做一次并发测试：同时发两个独立任务，确认没有互相踩锁。踩锁的表现就是前面说的 session file locked。确认无问题后，执行 docker compose restart 一次，再看会话是否延续。这步通过说明你的部署扛得住重启，数据卷和重启策略都正确。

我自己的习惯是每次换模型、改 channel 或升级镜像后，都把 5.1 里的烟雾测试重跑一遍。这个习惯帮我避免过很多次"以为升级了模型，实际配置没生效"的尴尬。希望帮到你。

本文还有配套的精品资源，点击获取