戈玄白今天要做题我先把话说在前面：如果要在自己电脑上把 OpenClaw 跑起来，Docker 是我目前用过最省心的一条路。原因很简单，OpenClaw 这个项目迭代太快，依赖链路又长，今天装好明天可能就少个系统库，直接裸机装很容易把时间耗在环境问题上。用 Docker 之后，镜像一拉、容器一启，整个运行环境就被隔离封装好，本机干净，卸载也干净。这篇内容不是照搬官方文档，而是我把从零到能跑通、再到正常接入模型和消息渠道的过程整理了一遍，重点讲思路和踩坑点，适合第一次接触 OpenClaw、准备用 Docker 做本地部署的人参考。
这篇东西适合两类人：一类是想在本地快速验证 OpenClaw 玩法、不想折腾底层环境的普通用户；另一类是准备把 OpenClaw 放到服务器上长期跑、需要认真做数据持久化和升级规划的人。无论你是 Windows 还是 Linux，都可以按下面的思路操作，具体差异我会单独标出来。
1. 安装前，先把 OpenClaw 和 Docker 这件事想明白
1.1 OpenClaw 到底是什么
OpenClaw 从关键字和实际体验上看，不是那种装完就跑个 demo 的小玩具，而是一个具备工作区的智能体运行框架。它的核心逻辑是给 AI 模型配上一套可执行的运行环境：模型可以调用工具、读写文件、操作 workspace 里的项目、按审批机制执行敏感命令，还能通过 skill 体系扩展新能力。
你可以把它理解成一个"会给模型配手脚的运行时"——大模型负责思考，OpenClaw 负责动手，两者之间通过指令和数据打通。正因为它能干实际的活，而不是只聊天，它才需要一套可靠、可隔离、可恢复的运行机制。Docker 恰好满足这些要求。
1.2 用 Docker 安装和原生安装的差别在哪
原生安装 OpenClaw 理论上也不复杂，要么下载便携包，要么用包管理器装，但实操下来你会遇到几个绕不开的问题：系统 Python 或 Node 版本冲突、依赖库和本机环境互相污染、换一台机器就要重新编译配置、升级 OpenClaw 时旧版本残留文件影响新版本运行。
用 Docker 之后这些问题会被大幅弱化。镜像里已经把运行所需的基础环境、依赖、目录结构固化好了，你只需要关心两件事：数据目录挂载方式对不对、模型配置写没写对。升级时也不需要先卸载再装，先拉新镜像再重建容器即可，老容器留着还能做备份。
还有一个隐藏好处是安全隔离。OpenClaw 运行时会执行很多命令，仓库里也要求配置 exec-approvals，也就是说 AI 要执行敏感命令前需要经过审批。放在容器里跑，即使审批规则配得比较宽松，最坏情况下也只是容器内文件受影响，不会立刻波及宿主机系统，这对想尝试自动化和 Agent 行为的人来说多了一层保障。
提示：Docker 不是万能的。如果你的使用场景是给 OpenClaw 开发自定义 skill，并且需要频繁调试本机硬件、USB 设备或特定系统 API，容器化反而会多一道设备映射的麻烦。本地学习用 Docker，搞深度系统集成时再考虑原生安装，这是比较合理的分工。
1.3 安装前的准备工作清单
安装前建议先把这几样东西备好，避免装到一半到处找资料：
- 一台能正常联网的机器，建议内存不低于 8GB，因为 OpenClaw 容器加上模型推理进程会比较吃内存；
- Docker 运行环境。Windows 用 Docker Desktop，Linux 可以用 Docker Engine，macOS 同样装 Docker Desktop；
- 一个文本编辑工具，后面改配置会用到；
- 模型 API Key，比如接入 DeepSeek 或 OpenAI 兼容接口时需要一个可用 Key；
- 了解自己的网络情况。如果拉取镜像慢，提前准备镜像加速配置。
准备工作不需要一步到位，可以先装 Docker 再准备 Key，但网络、内存这两项最好提前确认，否则后面排查起来很容易误判方向。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本机 Docker 环境准备：Windows 与 Linux 双平台实操
2.1 Windows 下安装 Docker Desktop 的完整流程
Windows 上装 Docker，核心是一个叫 Docker Desktop 的桌面程序。安装包从官网下载即可，但我建议在安装前先把系统设置确认一遍，因为很多安装失败并不是 Docker 的问题，而是 Windows 自己没开虚拟化。
第一步，检查 CPU 虚拟化是否开启。打开任务管理器，切到"性能"标签页，看右下角"虚拟化"是否显示"已启用"。如果显示未启用，需要进 BIOS 开启 Intel VT-x 或 AMD-V，这一步不在系统里操作，而是在开机时按 Del 或 F2 进入 BIOS 设置。
第二步，开启 Windows 相关功能。在"控制面板—程序—启用或关闭 Windows 功能"里，把"适用于 Linux 的 Windows 子系统"和"虚拟机平台"两项勾上。如果这里没勾，Docker Desktop 启动时大概率会报错，典型提示就是"Docker Desktop failed to start because virtualisation support wasn't detected"。很多人以为这个报错是电脑太老或 Docker 坏了，实际上多半是系统功能没开全。
第三步，重启系统后安装 Docker Desktop。安装过程基本一路 Next，但安装类型建议保留默认的 WSL 2 backend，因为 WSL 2 后端比 Hyper-V 后端更省资源，和 OpenClaw 这种需要大量 I/O 的容器也更搭配。
第四步，启动 Docker Desktop，等右下角鲸鱼图标变成稳定的运行状态。如果一切顺利，打开终端执行 docker version 可以看到 Client 和 Server 两段信息，说明 Docker 已经正常工作。
经验之谈：Windows 下如果
docker version只有 Client 没有 Server，或者提示无法连接到 Docker daemon，先别急着重装，去设置里确认 WSL 2 backend 是否启用，然后在 PowerShell 执行wsl --update更新一下 WSL 内核，八成就能解决。
2.2 Linux 服务器上用 Docker Engine 部署
如果你的 OpenClaw 不是跑在桌面电脑上，而是放在云服务器或 NAS 上长期运行，那不需要装 Docker Desktop，只需要装 Docker Engine。Linux 发行版不同，安装命令会略有差异，但思路一致：配置 Docker 官方源，安装 docker-ce，然后启动服务并设置开机自启。
安装完成后，随手把当前用户加入 docker 组，否则每次执行 docker 命令都要加 sudo。命令是 sudo usermod -aG docker $USER，执行完要重新登录一次才生效。这个细节很多人会漏掉，结果后续脚本里执行 docker 命令全部提示权限不足。
Linux 上还有一个建议：如果你的机器内存不大，可以给 Docker 配置一个 swap 限制，避免某个容器内存失控把整台服务器拖死。修改 /etc/docker/daemon.json，在里面加上内存相关配置，保存后重启 Docker 服务即可。
2.3 镜像拉取慢的解决思路：配置镜像加速源
不管是 Windows 还是 Linux，国内网络环境下拉 Docker Hub 镜像都可能遇到速度极慢甚至超时的情况。OpenClaw 镜像通常好几个 GB，如果每秒走几十 KB，基本等于没法用。
最快的解决方式是给 Docker 配置 registry mirror。Windows 下在 Docker Desktop 的 Settings—Docker Engine 里编辑 JSON 配置，Linux 下编辑 /etc/docker/daemon.json，写入镜像加速地址后重启 Docker。如果你使用阿里云容器镜像服务，可以登录控制台拿到个人专属加速地址，效果比较稳定。
配置完成后，可以用 docker info 查看 Registry Mirrors 字段是否生效。镜像源不是万能的，有时个别镜像仍会拉取失败，这时可以多试几个源，或者换个时间再拉。千万别局域网里看到谁分享加速地址就无脑填，很多第三方加速源稳定性没有保障，反而会拖慢速度。
3. 用 Docker 把 OpenClaw 第一次跑起来
3.1 拉取镜像与选择版本
先把官方发布的镜像拉下来。我用的是命令行方式，执行 docker pull openclaw/openclaw:latest 这类命令时，注意留意镜像仓库的准确名称。OpenClaw 迭代很快，latest 标签只适合尝鲜，如果你希望长期稳定运行，更建议拉取带具体版本号的镜像。
拉镜像时如果进度条长时间不动，先确认镜像加速是否配置成功，再确认本地磁盘空间是否充足。Docker 镜像在下载过程中会占用大量临时空间，磁盘写满时不会立刻报错，而是表现为下载卡在某个百分比。
镜像拉下来后执行 docker images 能看到本地镜像列表，确认 IMAGE ID 和大小正常，再进入下一步。
3.2 启动容器：目录挂载与端口映射
启动 OpenClaw 容器时，我最看重的有两个参数：一个是数据卷挂载，另一个是端口映射。
先看端口映射。OpenClaw 一般会提供一个 Web 管理界面或 API 端口，需要把容器内端口映射到宿主机。比如容器内监听 3000 端口，启动时用 -p 3000:3000 映射，之后就能通过浏览器访问本机 3000 端口进行操作。
再看数据目录。OpenClaw 默认会把配置、workspace、审批记录等数据放在 /root/.openclaw 目录下。如果不做挂载，每次删除容器重建，所有配置和数据都会丢失，前面配置的模型、技能、工作区文件全部清零，这个坑我踩过一次。
所以启动容器时，至少要把这个目录挂载出来。比如 Windows 下在 PowerShell 执行：
powershell复制docker run -d --name openclaw -p 3000:3000 -v "$HOME\.openclaw:/root/.openclaw" --restart=unless-stopped openclaw/openclaw:latest
Linux 下把路径改成：
bash复制docker run -d --name openclaw -p 3000:3000 -v "$HOME/.openclaw:/root/.openclaw" --restart=unless-stopped openclaw/openclaw:latest
--restart=unless-stopped 的意思是容器异常退出或机器重启后会自动拉起容器，这对服务器上长期运行的场景几乎是必加的。如果你只是本地临时测试，不加也没问题，手动启停更灵活。
3.3 用 docker logs 判断容器是否真正启动成功
启动容器后，执行 docker ps 查看容器状态。如果看到 STATUS 是 Up，说明容器进程还活着，但不能说明 OpenClaw 已经完全就绪，要再看日志确认。
docker logs openclaw 会输出容器的运行日志。如果出现类似初始化配置完成、开始监听端口的信息，说明服务已正常启动。如果日志里有报错堆栈，先不要慌，把报错信息和容器启动命令截图保存，然后再逐行排查。
有个小技巧：用 docker logs -f openclaw 可以实时跟踪日志输出，适合观察启动过程中的状态变化。启动失败时，日志往往能直接告诉你前因后果，比如缺少模型 Key、配置目录不存在、端口被占用等。养成先看日志再动手的习惯，能少走很多弯路。
4. 模型接入与核心配置：从"能跑"到"好用"
4.1 首次启动后的配置目录结构
容器跑起来后，OpenClaw 会在挂载的目录里自动生成一批文件。以 ~/.openclaw 为例，你会看到 workspace、config 文件、exec-approvals.json、记忆数据等几个部分。
workspace 是 OpenClaw 的工作区，模型读写文件、执行项目任务都在这个目录里进行。exec-approvals.json 是命令审批记录文件，里面记录了哪些命令被允许直接执行、哪些命令需要每次确认。如果你是初次启动，打开这个文件时看到内容很少或格式很新，说明审批机制还没有积累操作记录，需要在后续使用中慢慢沉淀。
有一个常见提示值得注意：启动时如果看到"legacy exec approvals exist at /root/.openclaw/exec-approvals.json，run ..."这类信息，意思是你目录里存在旧版本格式的审批文件，新版启动时希望你把旧格式迁移成新格式，或者清理掉这份旧的审批记录。处理方法很简单：先别急着删，备份一份到别处，然后运行日志里提示的命令做迁移或重置。如果删掉后一切正常，说明旧文件确实不再兼容；如果删完又出现新的报错，再用备份恢复。
4.2 模型配置：接入 DeepSeek 与 OpenAI 兼容接口
OpenClaw 本身不生产模型，它需要外接一个模型后端。配置时要在 config 里写明模型服务地址、API Key 和模型名称。
我测试时最常见的一个报错是"agent failed before reply: unknown model: deepseek"。这个报错看起来像是不支持某个模型，但实际原因往往是模型 ID 写错了，或者该模型服务并没有把自己注册成这个名字。
比如你用的是 DeepSeek，但 DeepSeek 的模型 ID 通常是 deepseek-chat 或 deepseek-reasoner，不是简单的 deepseek。如果你在配置文件里写了一个后端不认识的模型名，模型服务端会直接拒绝请求。
正确的排查路径是：先确认你用的模型服务商具体提供了哪些模型 ID，再把 config 里的 model 字段改成准确的 ID，然后重启容器。如果仍然报 unknown model，那就要检查 config 里的 base_url 是否写对，API Key 是否真实有效。建议先用 curl 调用一次模型服务的 API，确认 Key 和模型名都能用，再回头改 OpenClaw 配置。
有些用户会提到 OpenClaw 配置 NVIDIA NIM 的情况。NVIDIA NIM 提供的是自托管推理微服务，如果你本地有 NVIDIA GPU 并跑起了 NIM 容器，可以把 OpenClaw 的模型后端指向 NIM 的 API 地址。配置方式和 OpenAI 兼容接口类似，把 base_url 改成 NIM 服务地址即可，但要注意 NIM 容器和 OpenClaw 容器需要处于同一网络，或者通过宿主机 IP 访问。
4.3 多模型与运行时元数据
OpenClaw 支持多模型配置，意味着你可以给不同任务分配不同模型。比如简单文件整理用便宜快速的模型，复杂推理任务用更强更慢的模型。
多模型不是简单地在配置里写多个名字，而是要理解模型的调用场景。OpenClaw 内部有角色分工，比如处理对话的主模型、执行轻量事务的辅助模型等，不同角色对应不同配置项。如果你把同一个 Key 填到所有配置项里，虽然能跑，但成本控制和效果优化就无从谈起。
还有一层运行时元数据的概念。OpenClaw 在运行过程中会产生大量元数据，反映当前状态、已加载技能、Agent 的执行进度等。排查问题时，查看这些运行时元数据能帮你定位是模型环节卡住，还是 skill 执行环节出了问题。说白了，当你的 Agent 不按预期工作时，先看元数据再猜原因，这是一种专业的工作习惯。
5. 数据持久化、Skill 扩展与消息渠道打通
5.1 Active Memory 与长期工作记忆
OpenClaw 有一个比较有特色的设计，是 Active Memory 机制，也就是让 Agent 在多次任务之间保留长期工作记忆。常规聊天式 AI 在关闭会话后什么都不记得，而 OpenClaw 会把重要信息、项目上下文、历史决策写入记忆文件，下次启动后还能读取。
这个机制用 Docker 部署时要特别注意文件挂载。记忆本质上是磁盘上的数据，如果容器没有挂载数据卷，重启容器后记忆就会丢。我见过不少用户说"为什么我的 Agent 没有长期记忆"，排查到最后发现是启动命令里没有挂载 ~/.openclaw。
如果你希望 Active Memory 发挥价值，建议在使用过程中定期查看记忆文件的内容，你会发现它不只是原始的日志堆积，而是有结构地记录要点。当 Agent 的行为变得不正常时，检查记忆文件里是否积累了错误结论，必要时要手动清理或修正记忆片段。这和给人做"记忆矫正"是类似的概念。
5.2 Skill 技能扩展：从内置功能到自定义能力
OpenClaw 的能力扩展主要靠 Skill。Skill 本质上是一套遵循特定格式的指令和脚本集合，它告诉模型在某类场景下应该怎么调用工具、按什么步骤执行任务。
通过 Docker 安装的 OpenClaw，Skill 目录同样位于挂载的数据卷内。添加新 Skill 时，不需要进容器内部操作，直接在宿主机上把 Skill 文件夹放到对应目录，重启容器就能识别。这个设计特别适合和 Obsidian、项目管理工具结合使用，比如有人会把 OpenClaw 和 Obsidian 联动，让 Agent 管理项目笔记和任务清单，本质上是写一个能读写 Obsidian 库的 Skill。
但这里有一个效率陷阱：Skill 数量越多，模型在每一步决策时需要扫描的指令就越庞大，既增加 Token 消耗，也可能降低响应速度。建议只保留当前任务必需的 Skill，暂时用不到的可以先移出目录。
5.3 接入微信和飞书：让 Agent 走进消息流
把 OpenClaw 接到微信或飞书，是很多人真正开始高频使用它的转折点。接入后，你不必再盯着终端或网页界面，直接在聊天窗口里给 Agent 发消息，它就能干活并汇报结果。
接入消息平台通常需要配置 webhook 地址和机器人凭证。以飞书为例，你需要在飞书开放平台创建机器人应用，拿到 App ID 和 App Secret，然后把这些信息填到 OpenClaw 的渠道配置里。微信的接入方式则要区分个人号和公众号，限制和操作路径都不同，需要按官方指引处理。
Docker 部署下，消息平台回调到 OpenClaw 容器的核心是端口可达性。本地测试时，平台服务器需要能访问到你的 OpenClaw 服务，这在局域网和公网环境下的配置差异很大。本地开发可以先借助内网穿透类工具做临时回调测试，但若用于正式环境，建议还是把 OpenClaw 部署到有公网 IP 的云服务器上。这里不展开说具体工具，方向明确即可。
5.4 用 Docker Compose 固化你的部署方案
当你把模型配置、数据目录、端口映射、额外容器（比如 Redis 或 NIM）都理顺后，强烈建议把启动过程改写成 Docker Compose 文件。Compose 文件的好处是可以把 OpenClaw 和它依赖的服务一起定义，一条 docker compose up -d 就能拉起整套环境。
一个典型的 compose 文件会包含 openclaw 服务定义、volume 声明、环境变量、端口映射。如果 OpenClaw 需要连接 Redis 或其他中间件，可以在 compose 里定义这些服务，让它们走内部网络互访。这样无论换机器还是给同事分享部署方式，只需要拷贝一份 compose 文件，省掉大量重复沟通成本。
写 compose 文件时，注意把环境变量和密钥单独放在 .env 文件里，不要把 API Key 直接硬编码到 compose 文件中。.env 文件要记得加入 .gitignore，避免不小心提交到公开仓库导致 Key 泄露。
6. 高频问题排查实录：从报错信息到解决思路
6.1 exec-approvals 提示旧文件已存在
这个提示我在前面简单提过，但因为它太常见，值得单独拿出来说一下。报错信息大致意思是 /root/.openclaw/exec-approvals.json 存在旧版审批记录，需要运行指定命令处理。
出现这个提示的场景通常是从旧版本容器升级到新版本，或者之前用原生安装方式使用过 OpenClaw，现在改用 Docker 挂载了原来的目录。处理时先备份，再执行提示中的迁移或清理命令。如果提示说需要运行 openclaw 相关命令，而这些命令只能在容器内部执行，可以使用 docker exec -it openclaw openclaw ... 这样的方式进入容器执行。
平时使用中，exec-approvals.json 文件会越积越多，因为每次批准命令都会追加记录。建议每隔一段时间清理一次过期记录，避免文件过大拖慢启动解析速度。
6.2 "无法将 openclaw 项识别为 cmdlet、函数、脚本文件"问题
这个报错主要出现在 Windows PowerShell 中，原因是用户试图直接运行 openclaw 命令，但系统没有找到这个可执行文件。如果你是通过 Docker 方式安装的 OpenClaw，宿主机本来就没有 openclaw 可执行程序，出现这个提示是正常的。
解决方案是不要直接在 PowerShell 里运行 openclaw，而是通过 docker exec 在容器内执行。比如：
powershell复制docker exec -it openclaw openclaw --version
如果你确实希望在宿主机直接使用 openclaw 命令行，那就需要单独安装 CL I 工具，但这与 Docker 部署方式是两套体系，容易造成混淆。我建议遵循"容器化部署就用容器命令"的原则，不要混用。
6.3 模型启动失败：unknown model 的完整排查
"agent failed before reply: unknown model: deepseek" 这个报错我在模型配置章节提过，排查思路再说完整一点。
首先检查配置文件里 model 字段是否和模型服务商提供的模型 ID 完全一致。DeepSeek 的模型 ID 是带后缀的，不能只写厂商名。其次检查 base_url，有些兼容接口的路径结尾需要加 /v1，缺少路径会导致请求到错误地址。再次，用 curl 直接测试模型 API，排除 Key 失效或欠费的情况。最后，确认 OpenClaw 版本是否太旧、是否支持你要接入的模型服务。按照这个顺序排查，绝大多数 unknown model 都能在十分钟内定位。
6.4 Docker Desktop 启动失败：虚拟化支持未开启
Docker Desktop 报 "because virtualisation support wasn't detected" 是很经典的 Windows 问题。这并不一定表示 CPU 不支持虚拟化，更常见的原因是 Windows 的虚拟机平台功能没有开启，或者 BIOS 中的硬件虚拟化被禁用。
检查路径按顺序来：先到任务管理器确认虚拟化是否是"已启用"，如果没启用去 BIOS 打开 VT-x/AMD-V；确认 BIOS 设置没问题后，在 Windows 功能里勾选"虚拟机平台"和"适用于 Linux 的 Windows 子系统"，重启后再启动 Docker Desktop。如果还是不行，在 PowerShell 执行 bcdedit /set hypervisorlaunchtype auto 然后重启。
注意：修改 bcdedit 属于系统级操作，不适合对引导配置不熟悉的用户盲目执行。建议先完成前两步检查，确有需要再搜一下该命令的详细说明，确认风险后操作。
6.5 容器能启动但 Agent 不回复
容器状态是 Up，但给 Agent 发消息后迟迟没有回复，这种问题最难排查，因为表面看一切正常。我的排查顺序是：先看 docker logs 有没有新输出，如果完全没有，说明请求根本没到达 OpenClaw，问题出在消息渠道或网络链路；如果有日志但卡在调用模型的步骤，再去检查模型 API 连通性；如果模型返回正常但 Agent 没继续执行后续动作，那大概率是 Skill 或审批机制拦截了命令，检查 exec-approvals 是否需要手动批准。
这种"软故障"比直接报错更耗时间，所以平时合理的使用习惯很重要：给容器加合适的日志级别，配置好持久化存储，遇到问题能从日志和数据文件两个维度回溯现场，而不是一拍脑袋乱改配置。
用 Docker 跑 OpenClaw，我的最终建议
如果你现在准备开始，我建议的操作路径很直接：先确认机器虚拟化环境，装好 Docker，拉镜像，用一条带数据卷挂载的命令把 OpenClaw 跑起来，然后花一小时配置模型并测试一次完整对话。这里不需要一步到位接入微信或飞书，也不用急着写 Skill，先让容器"活"起来，能对话、能在 workspace 里做简单文件操作，再逐步扩展。
我个人在实际操作中体会最深的一点是：Docker 方式下 OpenClaw 的真正复杂度不在安装本身，而在于你是否理解"容器内的程序和容器外的数据"之间的边界。模型 Key、workspace 文件、审批记录、记忆数据，这些真正有价值的东西都在挂载目录里，容器本身反而随时可以推倒重建。理解了这一层，OpenClaw 无论是升级、迁移还是备份，都会变得非常清爽。
最后再分享一个小技巧：每次准备升级 OpenClaw 前，先执行 docker commit 或直接备份整个 ~/.openclaw 目录。这个习惯在项目高速迭代期特别有用，因为它能让你在升级出错后秒级回滚到可用状态。部署工具这件事，稳定压倒一切，能让自己安心折腾的方案，才是好方案。