Docker部署OpenClaw全攻略：从环境准备到进阶玩法-代码聚汇网

Docker部署OpenClaw全攻略：从环境准备到进阶玩法

Nicholas Qin·2026-09-02·阅读 22 GEO检测（免费）

DockerOpenClaw容器化部署

|难度：普通|阅读约 32 分钟

折腾了好几天，终于把 OpenClaw 用 Docker 跑通了。期间踩的坑足够写一篇长文：Windows 桌面版的虚拟化检测、Linux 服务器上的镜像加速、容器起来之后 Control UI 不自动启动、模型名写错导致 Agent 直接不回复……每个问题单独拎出来都够劝退一批人。这篇文章把完整过程整理出来，包括环境准备、容器启动、模型接入、高频报错排查，以及接入钉钉/微信、配多模型和长期记忆这类进阶玩法，给想用 Docker 部署 OpenClaw 的朋友一条能直接照着走的路径。

1. 为什么 OpenClaw 用 Docker 跑比裸装更划算

我最早是在本机直接装 OpenClaw 的，结果装了三次，三次都因为环境依赖问题半途而废。这个框架对运行时的要求比普通 Node 项目更复杂，启动 Agent 需要拉起 Python 子进程做 Skill 调用、用 Node 运行时跑交互主进程，还有一堆 npm 原生模块要编译。裸装方式下，只要本机之前装过其他 AI 项目，Python 版本、Node 版本、各种 .dll/.so 链接库就很容易打架。

1.1 裸装 OpenClaw 容易翻车的几个点

依赖冲突：OpenClaw 依赖的某个库版本和你本机已有的版本冲突，装到一半报错，解决完一个又冒出来一个。
Node 运行时找不到：就像常见报错 oneclaw node runtime not found，明明装了 Node，但框架找不到，本质就是环境变量和安装路径没对上。
卸载不干净：想删掉重装时，目录还被进程锁着，Windows 上经常报 EBUSY: resource busy or locked，删个文件夹都费劲。
换机器重来一遍：本机调好的一套配置，搬到另一台电脑就要重新装、重新配、重新踩坑。

1.2 Docker 带来的本质改变

Docker 的核心价值不是“把文件打进镜像”，而是把运行时环境和宿主机隔离。OpenClaw 需要 Python 就给它 Python，需要 Node 就给它 Node，这些依赖只存在于容器内部，不污染宿主机，也不会被宿主机上其他项目干扰。

容器还天然解决了可移植性问题。我在 Windows 开发机上把镜像跑通之后，把同一个镜像扔到云服务器上，容器一起来，效果完全一致。包括环境变量、数据目录、Skill 文件，全部通过挂载和配置管理，换机器成本几乎为零。

1.3 我实际对比过的三种部署方式

部署方式	优点	缺点	适合场景
本机裸装	启动最快，调试直观	依赖容易冲突，换机成本高	只想体验几分钟
Docker Desktop	环境隔离，安装相对简单	占用磁盘空间大，Windows 需要 WSL2	日常开发和调试
云服务器 Docker	7×24 运行，可接入消息平台	内存/显存有限，需要公网配置	长期跑 Agent 服务

如果你只是好奇 OpenClaw 是什么，裸装试一下没问题。但如果你想长期维护、接消息平台、做二次开发，建议直接上 Docker。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Docker 环境准备：桌面版和服务器版各有各的坑

说句实话，OpenClaw 本身的配置不算难，真正卡住大部分人的，是 Docker 环境本身。尤其是 Windows 用户，很多人第一步就卡在 Docker Desktop 启动失败上。

2.1 Windows 上安装 Docker Desktop 的完整流程

下载 Docker Desktop 安装包后，安装向导会提示是否使用 WSL2 作为后端。这里建议直接选 WSL2，性能和兼容性都优于旧版 Hyper-V 方案。

安装完成后，最常见的问题就是启动报错：Docker Desktop failed to start because virtualisation support wasn't detected。

这个报错不代表 Docker 坏了，而是你的系统没有开启虚拟化支持。排查路径如下：

打开任务管理器 -> 性能 -> CPU，看右下角“虚拟化”是否显示“已启用”。
如果显示“已禁用”，需要进主板 BIOS 开启 Intel VT-x 或 AMD-V。不同主板入口不一样，一般开机按 F2 / Del 进入，在 Advanced -> CPU Configuration 里找。
在 Windows 功能里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，然后重启。
确认 WSL2 已启用：管理员 PowerShell 执行 wsl --status，如果没安装内核，按提示 wsl --update。

还有一个常见问题是 Windows 版本过旧，会提示 we've detected that you have an incompatible version of Windows。Docker Desktop 新版要求 Windows 10 21H2 或更高版本，系统太老就只能换 Docker Toolbox 或直接用 Linux 服务器了。

2.2 Linux 服务器上安装 Docker Engine

服务器部署比桌面版简单很多，官方一行命令即可：

bash复制curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

启动并设置开机自启：

bash复制systemctl enable --now docker

把当前用户加入 docker 组，免去每次 sudo：

bash复制sudo usermod -aG docker $USER
newgrp docker

这里有个真实经验：云服务器厂商自带的操作系统镜像里，有些 Docker 版本很旧。装完务必执行 docker --version 确认一下，版本太老建议先卸载再装官方脚本版本，否则后面 OpenClaw 镜像的某些高级配置可能不生效。

2.3 镜像加速：不配置这一步，你连镜像都拉不动

我最初在服务器上直接 docker pull OpenClaw 镜像，等了十分钟还在转圈。后来才发现，默认官方源在国内网络环境下经常连接超时。解决办法是配置镜像加速器。

编辑 /etc/docker/daemon.json：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}

然后重启 Docker：

bash复制sudo systemctl daemon-reload
sudo systemctl restart docker

注意镜像加速源稳定性差异较大，同一个源今天快明天慢很正常。如果拉取仍然失败，建议多配几个备选源。实在不行，可以手动指定镜像 tag 拉取，例如先拉 openclaw/openclaw:latest，如果这个 tag 不存在就搜下是不是有其他命名。镜像仓库的名字在不同版本之间有过调整，最稳妥的方式还是看官方文档的最新安装命令。

3. OpenClaw 镜像拉取与容器启动：看似简单，细节不少

环境准备好之后，OpenClaw 容器化部署的正式步骤就三条：拉镜像、写配置、启动容器。但我在实际操作中发现，这三步每一步都有值得注意的细节。

3.1 拉取镜像与基础启动命令

OpenClaw 镜像本身包含完整的运行时，拉取命令示例如下：

bash复制docker pull openclaw/openclaw:latest

启动容器时，最基础的命令长这样：

bash复制docker run -d \
  --name openclaw \
  -p 3000:3000 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENCLAW_MODEL=deepseek-chat \
  -e OPENCLAW_API_KEY=你的密钥 \
  -e TZ=Asia/Shanghai \
  openclaw/openclaw:latest

几个关键点我拆开解释。

端口映射：OpenClaw 的 Control UI 默认跑在容器内 3000 端口，-p 3000:3000 把宿主机的 3000 端口映射到容器内，浏览器直接访问 http://localhost:3000 就能控制台。

数据目录挂载：-v ~/.openclaw:/root/.openclaw 是容器化部署的生命线。OpenClaw 的所有配置、Skill、日志、记忆数据都存放在这个目录里。如果不挂载，容器一删数据全没。

环境变量：模型配置、API Key 这类敏感信息通过环境变量传入，避免写死在镜像里，这一点对后续升级容器版本尤其重要。

3.2 首次启动后 Control UI 没自动启动

很多人在这一步遇到 openclaw control ui did not start。现象是容器起来了，但浏览器访问 3000 端口一直转圈。

排查思路是先看容器日志：

bash复制docker logs -f openclaw

如果日志里出现 Control UI 启动失败的报错，多半是端口被占用或初始化异常。试一下重启容器：

bash复制docker restart openclaw

大多数情况下重启一次就能恢复。如果仍然不行，检查宿主机 3000 端口是否被其他程序占用。Windows 下可以执行：

powershell复制netstat -ano | findstr :3000

把占用端口的进程结束后再重启容器。实际上，Control UI 这步在 Docker 里比裸装稳定很多，裸装经常因为 Node 版本不对导致 UI 进程闪退，容器里则很少遇到这种问题。

3.3 用 Docker Compose 管理更省心

跑单个 docker run 没问题，但后续改配置、升级镜像、加环境变量时，长命令会越来越难维护。我建议直接用 Docker Compose，写一个 docker-compose.yml：

yaml复制services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "3000:3000"
    volumes:
      - ~/.openclaw:/root/.openclaw
    environment:
      - OPENCLAW_MODEL=deepseek-chat
      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
      - TZ=Asia/Shanghai
    restart: unless-stopped

启动命令：

bash复制docker compose up -d

升级时只需要拉新镜像再重建容器：

bash复制docker compose pull
docker compose up -d

数据全部在挂载目录里，容器随便重建都不怕丢。环境变量里的 API Key 可以从 .env 文件读取，这样 compose 文件本身可以提交到 Git，密钥不会泄漏。

4. 模型接入与 Agent 对话：真正决定好不好用的部分

容器能起来只是第一步，真正决定 OpenClaw 好不好用的是模型接入。所以第四件事是配置模型，以及让容器里的 Agent 真正能和你对话。

4.1 模型配置的环境变量逻辑

OpenClaw 的模型配置核心通过环境变量完成。至少需要配置模型名称和 API Key 两个变量。启动命令中的 OPENCLAW_MODEL 和 OPENCLAW_API_KEY 就是直接起到这个作用。

这里必须提醒一个高频报错：agent failed before reply: unknown model: deepseek。这个报错的原因通常是模型名只写了简称，比如 deepseek，但 OpenClaw 需要的是完整的模型标识，例如 deepseek-chat 或者带厂商前缀的完整名称。不同提供商的模型命名体系不一样，配置前先确认你使用的模型服务商给出的标准名称是什么。

另一个需要留意的是 Base URL。如果使用第三方兼容接口或自建网关，需要额外配置 API 地址，让容器内请求指向正确的端点。容器内访问宿主机上的本地服务时，不能用 localhost，要用 host.docker.internal，这是容器与宿主机通信的特殊域名。

4.2 接入 NVIDIA NIM 跑本地模型

热词里反复出现 OpenClaw 配置 NVIDIA NIM，这也是很多人想用 Docker 部署的核心原因之一——把模型跑在本地或内网，不把数据送到外部 API。

NVIDIA NIM（NVIDIA Inference Microservices）会把主流大模型封装成 OpenAI 兼容的推理服务。OpenClaw 只需要把模型请求的 Base URL 指向 NIM 服务地址即可。

例如 NIM 服务跑在宿主机 8000 端口，容器启动时增加环境变量：

bash复制-e OPENCLAW_BASE_URL=http://host.docker.internal:8000/v1
-e OPENCLAW_MODEL=deepseek-ai/deepseek-r1

注意模型名称要写 NIM 服务里实际暴露的模型标识，不能想当然。配置好之后，OpenClaw 就能调用本地模型推理，数据不出内网，延迟也低不少。

4.3 OpenClaw Companion 本地模型模式

热词里还有一条 openclaw companion 本地模型，这个功能是把 Agent 能力带到手机等移动端。Companion 模式同样需要模型在本地或内网可达，对计算机性能要求更高，起码要 8GB 可用内存，跑较大模型还需要独显和足够显存。

如果你只有一台普通办公电脑，建议 Companion 本地模型开一个小参数模型，或者干脆优先用云端 API 体验功能，把本地模型作为进阶优化项。

4.4 测试对话与 Skill 扩展

模型配置好，打开 Control UI 就能直接和 Agent 对话。建议先做一次简单测试，比如问“你现在基于什么模型运行？”，确认 Agent 能正确回复。

接下来值得研究的就是 Skill 扩展机制。OpenClaw 的 Skill 是让 Agent 具备特定能力的插件模块。Skill 文件放在挂载数据目录的 skills 文件夹下，不用进入容器就能修改，修改完成后重启容器或重新加载即可生效。

举个例子，写一个取时间的 Skill，可以按框架约定的格式写成一个脚本或配置文件，在对话中触发“现在几点了”，Agent 会调用 Skill 获取系统时间。这类扩展玩法是 OpenClaw 比较有意思的部分，值得花时间研究。

5. 高频踩坑实录：这些问题我全遇到一遍

下面这些坑我都是实际踩过的。每个问题单独看都不难，但连续遇到时真的会让人崩溃。把完整排查链路写出来，你能少走很多弯路。

5.1 Docker Desktop 启动失败：virtualisation support wasn't detected

这是 Windows 用户的第一大拦路虎。现象很明确：安装 Docker Desktop 后点启动，小鲸鱼图标转一下就变回停止状态，弹窗提示虚拟化支持未检测到。

本质上，Docker Desktop 在 Windows 上运行 Linux 容器，依赖 WSL2 或 Hyper-V，两者都需要 CPU 虚拟化能力。系统没开启虚拟化时，Docker 无从下手。

完整的处理顺序是：

任务管理器 -> 性能 -> CPU，确认“虚拟化”状态。
如果禁用，进 BIOS 开启 VT-x（Intel）或 AMD-V 并保存重启。
管理员 PowerShell 执行：

powershell复制wsl --status

如果 WSL 没有发行版，执行 wsl --install。

确保“虚拟机平台”功能已开启：

powershell复制dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启系统后再打开 Docker Desktop。

只要 BIOS 虚拟化打开，这个报错基本 90% 能解决。剩下的情况是杀毒软件拦截了 Docker 服务，把 Docker Desktop 加入白名单即可。最稳妥的方案是彻底不折腾 Windows，直接用云服务器跑 Docker Engine，省心很多。

5.2 镜像拉不下来的终极解法

这个问题在服务器上很常见。docker pull 卡在等待响应，或者拉取到一半中断。除了配置镜像加速源，还可以用下面的办法：

切换镜像源地址，不同网络环境下加速源的连通性不同。
使用 docker manifest inspect 确认镜像 tag 是否存在，避免拉一个不存在的版本等超时。
如果网络实在不稳定，可以在加速源配置里加上 "https://dockerproxy.net" 这类备用地址，保证至少有一个源可用。
某些大镜像可以分阶段拉取：先 docker pull 基础镜像，再拉业务镜像，有时能绕过比较严重的网络拥堵。

5.3 `failed to remove ~/.openclaw: error: EBUSY` 资源锁定

这个报错在 Windows 上高频出现，场景通常是你想删掉 ~/.openclaw 目录重装，结果系统提示文件被占用。

根因是 OpenClaw 的某个进程还在运行，Node 或 Python 子进程锁住了目录里的文件。直接删除就会 EBUSY。处理步骤是：

停止并删除所有相关容器：docker stop openclaw && docker rm openclaw。
在任务管理器里检查是否有 node.exe / python.exe 进程残留，如果有就结束。
等几秒再执行删除，不要反复重试，Windows 文件索引有时会有延迟。
如果还删不掉，用 PowerShell 的 Remove-Item -Recurse -Force 强删。

后来我学乖了：不要在 Windows 上直接管理和删除挂载目录，所有数据操作都通过容器或 WSL 进行。你要真想清理环境，进 WSL 里删比在 Windows 文件资源管理器里拖拽可靠得多。

5.4 `unknown model: deepseek` 模型名错误

开始接入模型时，我填了一个模型简称，结果 Agent 启动正常，但一对话就报 failed before reply: unknown model: deepseek。日志里明确提示模型识别失败。

排查后发现，OpenClaw 的模型解析是按服务商前缀匹配的，只写 deepseek 会被识别成某个不存在的内部模型名。正确做法是写完整的模型标识，比如 deepseek-chat。如果是其他厂商模型，配置前先去服务商文档查官方标准模型名，别在这里偷懒。

同样的排查逻辑也适用于 Base URL 配置错误。如果你改了模型服务地址，记得同步更新 Base URL，否则 Agent 会默认请求官网地址，导致认证失败或连接超时。

5.5 容器内时区与日志时间偏移

这个问题不致命但很影响排查。默认情况下，容器时区是 UTC，日志时间和本地时间差 8 小时。排查问题时看日志总感觉对不上时间线。

解决方式是启动时加环境变量 TZ=Asia/Shanghai。Compose 文件里同样在 environment 里加一行。改完重建容器，日志时间就正常了。

6. 进阶玩法：接钉钉/微信、多模型切换、长期记忆与二次开发

容器稳定跑通、模型对话正常之后，OpenClaw 才算真正开始发挥价值。最后这部分聊几个我自己验证过的进阶方向。

6.1 接入钉钉和微信

OpenClaw 支持接入消息平台。钉钉这方面相对省心，可以利用官方机器人接口来实现。基本流程是：在钉钉开放平台创建一个机器人，拿到 Webhook 地址和加签密钥，然后在 OpenClaw 的配置里添加对应的消息通道配置，让 Agent 把钉钉群里 @ 它的消息作为输入，处理完后把回复发回群聊。

微信的接入渠道比较敏感，市面上多数方案依赖非官方接口或中间件，封号风险很高。如果你确实需要一个稳定的个人助手入口，更稳妥的做法是优先接钉钉，或者用经过合规审查的官方接口。这部分我不展开具体工具，你自己判断风险。

6.2 多模型策略：便宜模型和强模型搭配

热词里有“OpenClaw 多模型”，这背后是一个很实际的诉求：每个任务都调用最强模型，成本太高；所有任务都用便宜模型，复杂任务效果又不够。

OpenClaw 支持按 Skill 或按对话上下文配置不同模型。我的做法是：

默认对话模型用性价比高的，比如 DeepSeek 系列。
需要深度推理的任务，比如代码生成、长文本分析，通过 Skill 指定调用更强模型。
本地 NIM 部署的模型作为内网数据处理的专用模型，不走外部 API。

这种多模型路由的配置不复杂，核心就是让不同任务类型落到不同的模型环境变量上。具体配置方式随框架版本迭代会变化，以官方文档为主。

6.3 Active Memory：让 Agent 拥有长期工作记忆

OpenClaw 的 Active Memory 功能值得单独讲。简单说，它解决的是“Agent 过一会儿就忘了之前聊过什么”的问题。默认情况下，Agent 的上下文窗口有限，关闭对话历史就丢了。Active Memory 会把重要的对话信息、用户偏好、任务状态写入持久化存储，下次对话时自动加载相关记忆。

在 Docker 部署中，这个功能天然和数据卷挂载结合得很好。记忆数据写入挂载的 ~/.openclaw 目录，即使容器删掉重建，记忆依然存在。前提是你配置了正确的数据目录挂载，并用 SQLite 或 PostgreSQL 这类持久化数据库做存储后端。

如果你想构建一个真正长期陪伴的 Agent，Active Memory 是优先级很高的配置项。

6.4 二次开发与容器内改动持久化

做二次开发时，最怕改完代码一重建容器，全部改动消失。解决方案有以下几种：

挂载源码目录：把 OpenClaw 的源码通过 volume 挂载到容器中，改宿主机上的代码即时生效。
使用 Dockerfile 构建自己的镜像：基于官方镜像，把自己的 Skill、配置、自定义代码打进去，这样部署到任何机器都是一样的效果。

示例 Dockerfile：

dockerfile复制FROM openclaw/openclaw:latest
COPY ./my-skills /root/.openclaw/skills
COPY ./my-config.yaml /root/.openclaw/config.yaml
ENV TZ=Asia/Shanghai

构建自己的镜像：

bash复制docker build -t my-openclaw:1.0 .

之后无论在哪台机器跑 docker run 或 docker compose up，拿到的都是你定制好的完整环境。我强烈建议，凡是做了配置改动，第一时间把改动沉淀到 Dockerfile 或 Compose 文件里，不要只在容器里手动改。否则下次升级镜像时，所有手工修改都会丢。

这一路折腾下来，我的真实体会是：OpenClaw 本身是个很有潜力的智能体框架，但它的安装和配置链路确实不算短。Docker 帮我把最痛苦的环境依赖问题一次性解决了，剩下的事情反而变得清晰——所有数据通过挂载管理，所有配置通过环境变量和 Compose 文件管理，升级容器不丢数据，换机器秒级迁移。如果你正准备部署 OpenClaw，我给的建议是：先别急着搞本机裸装，直接配好 Docker，镜像拉下来，把最基础的对话跑通，再逐步加 Skill、接平台、调多模型。把基础打牢之后，这个 Agent 能玩出多少花样，就完全取决于你的想象力了。