尧图网页设计 
简介一份面向开发者的容器化 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 DesktopLinux 选原生引擎宿主机侧的 Docker 运行时主流选择就两条路Windows 和 macOS 用 Docker DesktopLinux 服务器装 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_PROXYhttp://192.168.1.10:7890 \ -e HTTPS_PROXYhttp://192.168.1.10:7890 \ -e NO_PROXYlocalhost,127.0.0.1 \ openclaw/openclaw:latestHTTP_PROXY 和 HTTPS_PROXY 是容器内 Python 请求库普遍识别的环境变量NO_PROXY 用于排除本地地址避免容器内其他服务访问被错误绕到代理。如果宿主机代理是明文 HTTP 代理容器里无需额外处理如果需要认证变量写成 http://user:passhost: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_KEYsk-xxxx \ -e OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 \ -e OPENAI_MODEL_NAMEqwen-plus \ -e TZAsia/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 TZAsia/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_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 - OPENAI_MODEL_NAMEqwen-plus - HTTP_PROXY${HTTP_PROXY} - HTTPS_PROXY${HTTPS_PROXY} - NO_PROXYlocalhost,127.0.0.1 - TZAsia/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终端、网页还是 TeamsOpenClaw 支持通过不同渠道与 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 的使用体验。下表是千问几个常用模型的选择参考模型名定位适合场景qwen-turbo快速低成本日常问答、轻量任务qwen-plus均衡默认选择覆盖大多数任务qwen-max强推理复杂代码生成、多步工具调用如果走 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 里的烟雾测试重跑一遍。这个习惯帮我避免过很多次以为升级了模型实际配置没生效的尴尬。希望帮到你。本文还有配套的精品资源点击获取 Docker部署OpenClaw实战：容器化AI Agent的安装、配置与避坑指南
简介一份面向开发者的容器化 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 DesktopLinux 选原生引擎宿主机侧的 Docker 运行时主流选择就两条路Windows 和 macOS 用 Docker DesktopLinux 服务器装 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_PROXYhttp://192.168.1.10:7890 \ -e HTTPS_PROXYhttp://192.168.1.10:7890 \ -e NO_PROXYlocalhost,127.0.0.1 \ openclaw/openclaw:latestHTTP_PROXY 和 HTTPS_PROXY 是容器内 Python 请求库普遍识别的环境变量NO_PROXY 用于排除本地地址避免容器内其他服务访问被错误绕到代理。如果宿主机代理是明文 HTTP 代理容器里无需额外处理如果需要认证变量写成 http://user:passhost: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_KEYsk-xxxx \ -e OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 \ -e OPENAI_MODEL_NAMEqwen-plus \ -e TZAsia/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 TZAsia/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_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 - OPENAI_MODEL_NAMEqwen-plus - HTTP_PROXY${HTTP_PROXY} - HTTPS_PROXY${HTTPS_PROXY} - NO_PROXYlocalhost,127.0.0.1 - TZAsia/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终端、网页还是 TeamsOpenClaw 支持通过不同渠道与 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 的使用体验。下表是千问几个常用模型的选择参考模型名定位适合场景qwen-turbo快速低成本日常问答、轻量任务qwen-plus均衡默认选择覆盖大多数任务qwen-max强推理复杂代码生成、多步工具调用如果走 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 里的烟雾测试重跑一遍。这个习惯帮我避免过很多次以为升级了模型实际配置没生效的尴尬。希望帮到你。本文还有配套的精品资源点击获取