智能体框架OpenClaw的Docker手工部署与故障排查指南-代码聚汇网

智能体框架OpenClaw的Docker手工部署与故障排查指南

德国人Leo乐柏说·2026-09-04·阅读 21 GEO检测（免费）

OpenClawDocker部署AI Agent

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

如果你最近一直在刷 AI Agent 相关的内容，估计已经被 OpenClaw 这个名字刷屏了。它是一款开源智能体框架，前身叫 Clawdbot，核心思路很直接：用自然语言让 AI 去完成实际任务，比如管理文件、调用 API、操作浏览器、读数据库、写代码跑测试，而不是只停留在对话框里陪聊。网上很多教程会让你用一键脚本部署，但我个人在几个环境里折腾下来，还是坚持用 Docker 手工部署。原因很简单：手工部署能让我清楚知道容器里到底跑了什么、配置落在哪个目录、日志去哪里看，出了问题不至于两眼一抹黑。这篇文章会把从 Docker 准备、镜像拉取、容器启动、模型接入到常见报错排查的完整过程写下来，适合那些想自己掌控部署过程、又不想被各种封装脚本坑到的人。

在动手之前，先说明一点：OpenClaw 的版本迭代非常快，尤其是 2.0 之后，配置项、目录结构甚至镜像名都发生过变化。你如果搜到一篇一两年前的文章，里面的命令大概率跑不通，不是你的问题，是项目改名和重构导致的。所以这篇文章会尽量抓住不容易过时的核心逻辑，再结合我实际踩过的坑来展开。

1. 先搞清楚部署思路：这是一个智能体框架，不是一个聊天壳

很多人在部署前没搞明白 OpenClaw 的定位，以为装完就是一个类似网页版 ChatGPT 的东西。实际上它是一个“智能体运行时”：框架本身不产生模型能力，而是负责把模型接到工具、渠道、文件系统和外部系统上。你可以把 OpenClaw 理解成一个“带手脚的大脑容器”，大脑是 Claude、GPT、DeepSeek 这类模型，手脚是文件读写、命令执行、网络请求、API 调用这些能力。

1.1 项目背景：从 Clawdbot 到 OpenClaw，为什么版本差异这么大

OpenClaw 前身的名字是 Clawdbot，所以你在老教程里会看到大量 clawdbot 字样，镜像仓库、配置目录、日志输错格式都不太一样。作者后来把项目改名为 OpenClaw，同时重做了不少底层逻辑，比如 Active Memory 的引入、执行审批机制的调整、消息渠道层的抽象。这个改名过程给部署带来一个很现实的问题：你搜到的教程和实际安装包可能根本不是同一个版本。判断版本最直接的办法是看日志和命令入口，不要只看标题。

我最早尝试部署时就踩过这个坑。按照一篇老文章拉了一个 clawdbot 镜像，结果容器起来了，但配置文件生成的结构和文档对不上，后来才发现那篇文章讲的是改名前的旧版本。所以你在拉镜像前，一定要先去项目官方仓库或者官方文档页确认当前推荐的镜像名和版本号，别凭习惯直接照抄命令。

1.2 为什么我推荐 Docker 手工部署而不是一键脚本

官网提供的一键脚本确实方便，理论上帮你把 Docker、容器、配置目录都处理好，但问题也出在这里：它帮你做了太多隐藏决策。万一部署完 AI 没有按预期工作，你根本不知道它是把配置写到了 /root/.openclaw 还是 /home/user/.openclaw，也不知道容器名是什么、日志怎么看，只能去翻官方 issue。手工部署虽然多敲几条命令，但整个过程是透明的，出错了你能一步步定位，这对后续维护和排错的价值非常高。

手工部署的另一个优势是容易“环境复制”。你在一台机器上手工跑通以后，可以把 docker compose 文件和配置目录一起备份，到新机器上直接复用。一键脚本在这方面的可重复性就差一些，因为它每次执行都会探测当前系统，做一堆判断，换个环境结果可能就不同。对于需要在多台机器上部署的人来说，写好 compose 文件才是真正一劳永逸的办法。

1.3 手工部署需要理解的核心目录结构

OpenClaw 在 Linux/macOS 容器里默认把配置放在用户根目录下的 .openclaw 文件夹里。如果以 root 用户运行，路径就是 /root/.openclaw；如果镜像内部有一个普通用户，路径就可能是 /home/user/.openclaw。这个目录下面一般放着主配置文件、工作目录、执行审批记录等。exec-approvals.json 记录的是你授权哪些命令可以被 AI 直接执行，workspace 是 AI 读写文件的默认工作区。

这个目录结构理解不透彻，后面会有很多连锁问题。比如你想挂载宿主机目录，把配置持久化到本地，如果搞错了容器内路径，挂载就是无效的，容器一删数据全丢。因此我建议首次启动容器后，第一件事是进入容器确认当前用户的 HOME 和 .openclaw 的实际位置，再考虑卷挂载。

bash复制docker exec -it openclaw sh
echo $HOME
ls -la $HOME/.openclaw/

看到实际路径后再去配置 compose 文件，这才是稳妥的顺序。

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

2. 部署前准备：先把 Docker 环境这张多米诺骨牌扶稳

OpenClaw 本身依赖 Docker 运行，所以 Docker 环境是否健康，直接决定后面每一步是否顺利。很多人在这一步就被卡住了，常见表现是 Docker Desktop 装完启动不了，或者镜像拉取慢到怀疑人生。这些都属于环境问题，但解决起来并不难，只是排查顺序要正确。

2.1 Docker 安装的常见方案选择

如果你是 Windows 用户，优先用 Docker Desktop，它自带图形界面和 WSL2 集成，对新手最友好。安装时记得在设置里勾选 WSL2 后端，因为新版 Docker Desktop 已经默认使用 WSL2。装完后不要急着拉镜像，先打开命令行跑一下 docker version，确认客户端和服务端都在运行。

macOS 用户同样用 Docker Desktop，Apple Silicon 芯片注意优先选 arm64 版本，不要手动指定 x86 镜像，否则性能会很差。Linux 用户则没有 Docker Desktop 这个概念，直接安装 Docker Engine 就行，Ubuntu 这类发行版可以用官方 apt 源安装，也可以用发行版自带的包管理器。我一直强调先确认基础环境，因为后面很多 OpenClaw 的异常现象，追根溯源其实都是 Docker 服务本身没起来。

检查 Docker 是否正常的办法：

bash复制docker version
docker info

如果 docker info 能正常输出，说明服务端可用。如果提示权限不足，说明当前用户不在 docker 用户组里，需要 sudo usermod -aG docker $USER 然后重新登录。

2.2 Docker Desktop 启动失败和虚拟化支持检测不到

Windows 上最典型的问题就是 Docker Desktop 提示 virtualisation support wasn't detected。这个提示表面上说的是“没检测到虚拟化支持”，但实际上你的 CPU 很可能支持虚拟化，只是 BIOS 里的开关没打开，或者 Windows 的虚拟机平台功能没启用。

排查顺序建议如下：

打开任务管理器，切到“性能”标签，看 CPU 一栏有没有“虚拟化：已启用”。如果显示“已禁用”，需要重启进 BIOS，找到 SVM（AMD）或 VT-x（Intel）选项并打开。
在 Windows 的“启用或关闭 Windows 功能”里，把“虚拟机平台”和“适用于 Linux 的 Windows 子系统”勾上。
以管理员身份打开 PowerShell，执行 bcdedit /set hypervisorlaunchtype auto，然后重启电脑。
重启后再打开 PowerShell 执行 wsl --status，确认 WSL 内核正常。如果提示没有内核，执行 wsl --update。

按这个顺序排查下来，大部分 Docker Desktop 无法启动的问题都能解决。我不建议一上来就重装 Docker，因为根因往往是系统层的虚拟化配置，重装解决不了。

2.3 镜像拉取慢的加速方案

Docker 镜像默认从公共仓库拉取，在部分网络环境下速度确实不理想。解决办法是给 Docker 配置镜像加速地址。Linux 上修改 /etc/docker/daemon.json，Windows 和 macOS 在 Docker Desktop 的 Settings -> Docker Engine 里修改同样的 JSON 结构。一个有效的配置格式如下：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

不同加速地址的稳定性和速度差异很大，如果你所在环境有云服务商提供的专属加速地址，优先用专属地址，因为它们通常只对你的账号开放，基本不会失效。改完配置后必须重启 Docker 服务才能生效。如果重启后拉镜像还是慢，可以换几个公共地址试试，但不要在同一时间配置太多，否则 Docker 会逐个尝试，反而拖慢速度。

我还想提醒一句：在配置镜像加速时，不要混淆“镜像加速”和网络访问工具。镜像加速只是优化镜像下载链路，不会改变容器内部的网络出口。OpenClaw 运行时要访问模型 API，依赖的是宿主机本身的网络环境，不要在容器网络层面做多余的文章。

2.4 拉取镜像前先确认版本和架构

OpenClaw 官方推荐镜像在不同时期有过变化。如果你看的是全新文档，镜像名一般对应新仓库；如果你看的是早期 Clawdbot 教程，拉的是旧镜像。我建议以当前官方文档中实际给出的 Pull 命令为准，不要自己想当然。拉取时也可以指定平台参数：

bash复制docker pull pawder/openclaw:latest

如果你的宿主机是 Apple Silicon 或者 ARM 架构的服务器，而镜像只提供了 amd64 版本，可以在拉取或运行时加 --platform linux/amd64 参数，但这会引入模拟层，性能打折。最好先去镜像仓库页确认是否提供 arm64 版本。

3. 一步步手工部署：从 docker run 到 docker compose

环境准备好之后，就可以进入正题了。先说一个核心原则：不要裸奔式地起容器，至少要做到数据卷挂载、端口映射、重启策略三件事齐全。否则容器一旦删除或崩溃，配置数据就全没了，那种崩溃感我体验过一次，不想让你再体验。

3.1 用 docker run 快速拉起第一个容器

如果只是临时体验，最简单的启动命令如下：

bash复制docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -e TZ=Asia/Shanghai \
  -v openclaw_data:/home/user/.openclaw \
  pawder/openclaw:latest

解释一下每个参数的作用：-d 让容器在后台运行，不然窗口一关就停了；--name 指定容器名，方便后续用 docker logs openclaw 查看日志；--restart unless-stopped 让 Docker 在容器异常退出时自动拉起，服务器重启后也会自动启动；-p 把容器内 18789 端口映射到宿主机，方便通过浏览器访问；-e TZ=Asia/Shanghai 设置时区，避免日志时间差 8 个小时；-v openclaw_data:/home/user/.openclaw 是数据卷挂载，让配置数据持久化。

这里最需要注意的是 /home/user/.openclaw 这个容器内路径。不同版本的镜像基础用户不一样，有的容器默认是 user 用户，有的是 root。保险做法是第一次启动时先不要挂载卷，用上面命令启动后，通过 docker exec 进去看实际路径，再重建容器。

3.2 用 docker compose 固化部署配置

容器跑通之后，我强烈建议立刻把部署方式切换成 docker compose，因为 compose 文件就是你的部署文档。下次换机器，只需要把 compose 文件和配置目录拷过去，一条 docker compose up -d 就能恢复整个环境。创建一个目录，比如 openclaw-deploy，在里面新建 docker-compose.yml：

yaml复制services:
  openclaw:
    image: pawder/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./openclaw_data:/home/user/.openclaw

如果你是 Linux 服务器，想把工作区目录直接暴露出来，方便宿主机查看 AI 生成的文件，可以再加一个挂载点：

yaml复制    volumes:
      - ./openclaw_data:/home/user/.openclaw
      - ./workspace:/home/user/.openclaw/workspace

但注意：workspace 目录是容器内用户的工作目录，宿主机上对应的目录权限如果不对，OpenClaw 可能无法写入。如果你遇到“文件无法写入”之类的报错，先检查宿主机目录所有者与容器内用户 ID 是否一致。最简单的办法是 chmod -R 777 ./workspace，虽然粗暴，但在本地测试环境里最省心。

3.3 启动后如何验证部署成功

启动容器后，先看日志，不要立刻打开浏览器。日志是判断容器是否正常运行的第一手信息：

bash复制docker logs -f openclaw

正常情况下，日志会输出 OpenClaw 启动的一些元数据，包括监听端口、加载的配置路径等。看到监听 18789 端口之类的信息后，再打开浏览器访问 http://localhost:18789，一般能看到一个 Web 界面或者 Onboarding 引导页，指引你完成初始配置。如果你是通过远程服务器访问，记得把 localhost 换成服务器 IP，并检查防火墙和安全组是否放行 18789 端口。

配置过程中需要填写模型相关的 API Key。OpenClaw 本身没有内建模型，它需要你把模型 API 的密钥填进去。主流的 Anthropic、OpenAI、OpenRouter 等都能配置。如果暂时没有 API Key，界面会一直卡在某一步，这是正常的，不是系统坏了。

3.4 常用维护命令实录

部署完成之后，日常用到最多的命令就那么几条：

bash复制# 查看最近日志
docker logs --tail 200 openclaw

# 进入容器交互
docker exec -it openclaw sh

# 重启容器
docker restart openclaw

# 关闭并删除容器（不会删除数据卷）
docker stop openclaw && docker rm openclaw

我尤其建议你养成“进容器确认状态”的习惯。比如想查看当前哪个模型生效、配置到底在哪个目录，直接进容器敲 openclaw 相关命令比在宿主机猜要靠谱得多。容器内部如果提示没有 find 或者 vim 这类基础工具，不要慌，很多精简镜像不带这些，你可以通过挂载出来的配置目录在宿主机上用编辑器改文件，改完重启容器即可。

4. 配置模型与外部能力，让 Agent 真正开始干活

容器起来了只是地基，真正决定 OpenClaw 好不好用的，是模型配置和渠道接入。这一节我把最关键的地方梳理一遍。很多时候 Agent 回复奇怪或者干脆不回复，问题都出在模型配置上，而不是框架本身。

4.1 理解模型配置的“三元组”

无论你用的是哪个模型供应商，OpenClaw 在识别模型时一般需要知道三个层面的信息：模型家族、供应商、模型名称。比如你要用 Anthropic 的 Claude，模型家族是 Claude，供应商是 Anthropic，模型名称是具体的某个版本编号。如果只填一个“claude”或者“deepseek”这种短名字，框架很可能不知道你想干嘛，轻则模型列表加载失败，重则直接报 unknown model。

很多初次使用的朋友会直接修改配置文件里的 model 字段。我的建议是，不要一上来就手改 JSON 文件，先通过 OpenClaw 自身提供的配置入口选择模型。它会自动生成符合规范的配置字段，你只需要把 API Key 填进去。如果你确实想手写配置，至少先让系统生成一个模板，再在模板基础上改动，不要凭空创造一个和系统字段对不上的配置。

4.2 多模型与本地模型接入思路

OpenClaw 支持配置多个模型，一般会有一个主模型负责思考策略，另一个更轻量的模型负责简单任务。这种设计非常实用，因为复杂任务如果全走贵模型，成本会很快上去，而轻量任务用快速模型不但省钱，响应速度也更快。配置多模型时需要注意各个模型是否都能被当前供应商正常访问，不要只检查主模型没检查备用模型。

如果你想接入 NVIDIA NIM 这类本地模型服务，思路也类似。NIM 本质上是把模型封装成标准化推理服务，对外提供兼容接口。你把 OpenClaw 的模型供应商指向 NIM 的地址，再把模型名称改成 NIM 里实际部署的模型 ID 就行。好处很明显：数据不用出内网，隐私性更强，适合对数据安全要求高的场景。

4.3 把 OpenClaw 接入微信、飞书等 IM 渠道

OpenClaw 比较吸引人的一点是可以通过 IM 聊天直接指挥 AI。飞书这类开放平台的接入相对正规，你在飞书开放平台创建一个应用，拿到 App ID 和 App Secret，然后把消息回调地址指向 OpenClaw 的 Webhook 即可。需要暴露到公网，所以要确保域名能访问到服务器端口。

至于个人微信，我不建议你把主要精力放在这上面。个人微信的自动化本身属于边缘场景，一方面稳定性差，另一方面容易触发平台风控。如果你真的只是自己测试，可以先跑通飞书，因为飞书有官方接口，安全性和稳定性都有保障。等你在飞书渠道上验证了 Agent 的指挥流程，再决定要不要折腾其他渠道。

4.4 工作区、执行审批和 Active Memory 三件套

OpenClaw 体现“智能体”属性的三个关键能力是工作区、执行审批和记忆。工作区是 AI 读写文件的地方，相当于它的工位；执行审批是 AI 在运行命令前向你确认的机制，相当于门禁；记忆则是让 AI 跨会话记得你是谁、在做什么。

执行审批这个功能很重要，尤其当 AI 要执行删除文件、安装依赖这类危险操作时，一定要保持审批开启。它的状态记录在 exec-approvals.json 里，你可以理解成一张“通行证清单”。同一个操作你批准过一次，之后它会直接放行。所以我建议工作区文件不要挂载到系统关键目录，只把专门的目录当作工作区即可。

关于 Active Memory，我强烈建议从第一天就养成使用习惯。普通对话是“失忆”的，而 Active Memory 能让 AI 在长期任务中保留关键上下文。实操中，我会在任务开始时让 AI“先读取 Active Memory，再执行”，任务收尾时让它“把关键进展更新到 Active Memory”。这样，即使几天后再继续同一个项目，它依然能想起来做了什么、下一步该干什么。

5. 高频报错与排查经验实录

这一部分是我最想写的内容。OpenClaw 部署过程中的报错，80% 以上都集中在环境问题、路径问题和模型配置问题上。你把这些坑提前避开，至少能省出一个下午。

5.1 Windows 下 openclaw 命令不存在的真相

很多人习惯在宿主机上直接执行 openclaw 命令，然后收到 PowerShell 报错：无法将 openclaw 项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这大概率是因为你根本没有把 openclaw 的可执行文件加到系统 PATH 里。如果你使用的是便携包或者 npm 全局安装，安装位置不一定在系统默认搜索路径中。

排查方法是在 PowerShell 里执行 where.exe openclaw，看它是否能找到文件。找不到的话，就去安装目录里找 openclaw.exe 的实际位置，并把它所在目录加入到用户 PATH 环境变量。需要提醒的是，如果你通过 Docker 部署 OpenClaw，宿主机上根本没必要安装 openclaw 命令，所有命令都应该在容器内执行，所以先分清自己的部署方式再排查。

5.2 日志出现 legacy exec approvals，需要迁移

启动时如果看到类似这样的日志：

text复制Legacy exec approvals exist at /root/.openclaw/exec-approvals.json. Run `openclaw migrate` to upgrade them.

意思是检测到了旧格式的执行审批文件，需要迁移到新版本格式。这个提示出现并不代表系统坏了，但你最好照做，否则旧授权记录可能无法生效。由于你用的是 Docker 部署，在宿主机上直接执行 openclaw migrate 是无效的，必须先进容器里执行：

bash复制docker exec -it openclaw sh
openclaw migrate
exit
docker restart openclaw

执行完后再看日志，提示应该消失。顺带说一句，日志里如果路径是 /root/.openclaw，说明你的容器以 root 身份运行，这时候你在 compose 里挂载 /home/user/.openclaw 就挂错地方了。这是特别典型的坑，看到这个日志就说明容器内路径和挂载路径可能对不上。

5.3 Agent 回复前直接失败：unknown model

如果你的配置里直接写了某个模型短名称，比如把模型设置成 deepseek，启动后可能出现 agent failed before reply: unknown model 这类错误。原因很简单：供应商无法根据这个短名称找到对应模型。不同供应商对模型名称的格式要求很严，哪怕同一个公司的同一个模型，在不同聚合平台上也可能有不同前缀。

解决思路是到模型供应商的列表或者文档里确认准确的模型 ID。比如 DeepSeek 官方 API 的对话模型一般叫 deepseek-chat，如果你是通过 OpenRouter 这一类的聚合服务使用，模型名很可能需要写成带命名空间的完整形式。填完模型名后一定要把 API Key 对应填对，不同供应商的 Key 不能混用。检查完后重启容器再试。

5.4 容器内配置文件路径不对导致的挂载失效

很多教程直接让你挂载 /root/.openclaw，但官方镜像的默认用户不一定是 root。如果你挂载的路径和实际路径不一致，表面上看容器正常启动，实际上配置文件写到了容器可写层，数据卷是空的。容器一删，配置全丢。

判断方法很简单：

bash复制docker exec openclaw sh -c "echo \$HOME && ls -la \$HOME/.openclaw/"

看输出结果是否和你挂载的路径一致。如果不一致，需要调整 compose 里的容器内路径，或者通过 Dockerfile 指定用户。不要强行期望所有镜像的内部路径一样，这是版本差异最常导致的环境问题。

5.5 Docker Desktop 启动失败后的排查顺序

前面提过 virtualisation support 检测不到的问题，这里做一个小结。遇到 Docker Desktop 起不来的情况，按以下顺序检查：

BIOS 里 CPU 虚拟化开关是否打开。
Windows 功能中虚拟机平台、WSL 是否启用。
以管理员身份执行 bcdedit /set hypervisorlaunchtype auto 后重启。
执行 wsl --update 更新内核。
Docker Desktop 设置中检查 WSL2 后端是否启用。

如果你已经在用 Linux 服务器，Docker 服务起不来，先检查 /etc/docker/daemon.json 有没有语法错误。很多时候改完加速配置忘了校验 JSON，最后 Docker 服务直接无法启动。解决办法是先删掉或改名这个文件，再重启 Docker，确认能起来后再慢慢改配置。

5.6 一些容易忽略的小坑

容器时区不对是最常见但最不起眼的问题。如果你在容器里执行 date 发现时间是 UTC，那么日志时间会和你本地时间差 8 个小时。解决方法是启动时加上 -e TZ=Asia/Shanghai，或者在 compose 的 environment 里配置。

端口冲突也需要留意。如果你本机已经有服务占用了 18789 端口