1. 项目概述：一个开箱即用的 OpenClaw Docker 部署方案

如果你和我一样，对 AI 助手既爱又恨，爱它的效率，恨它的隐私和不可控，那么 OpenClaw 的出现绝对是个福音。简单来说，OpenClaw 是一个让你能完全掌控在自己硬件上运行的 AI 助手的开源项目。它不是一个具体的 AI 模型，而是一个“网关”或者说“平台”，你可以把它想象成一个高度可定制的智能家居中枢，只不过它连接和管理的是各种 AI 能力。你可以通过插件接入 Claude、GPT、本地大模型，甚至是自定义的工具，然后通过统一的界面（比如 Slack、Discord、网页）与它们交互，所有数据流都经过你自己的服务器。

听起来很酷，但部署起来，尤其是要整合各种插件、管理依赖，对于非资深 DevOps 玩家来说，门槛不低。这就是 Fanccy315/openclaw-docker 这个项目存在的意义。它提供了一个 Docker 化的 OpenClaw 模板，把繁琐的环境搭建、插件预装、配置优化都打包好了。你拿到手的不再是一堆需要自己拼装的零件，而是一个已经组装了七七八八的半成品机器人，只需要接上电源（配置密钥）和下达指令（初始化），它就能跑起来。

这个模板的核心价值在于“开箱即用”和“可定制化”的平衡。它基于 Node.js 22 构建，预装了像 Matrix（一个开源的消息协议插件）这样的常用组件，还集成了 Homebrew 以便于在容器内灵活安装其他软件。更重要的是，它提供了一套清晰的 Docker Compose 架构和详实的操作指南，即便是 Docker 新手，按照步骤也能把自己的私有 AI 助理搭建起来。接下来，我会带你深入这个模板的每一个细节，从设计思路到每一步实操，再到我踩过的坑和总结的技巧，让你不仅能部署成功，更能理解背后的原理，真正地“拥有你的数据”。

2. 核心设计思路与架构解析

2.1 为什么选择 Docker 化部署？

在深入代码之前，我们得先聊聊为什么这种 AI 助手项目特别适合用 Docker 来部署。OpenClaw 本身是一个 Node.js 应用，它会有复杂的依赖（各种 AI 服务的 SDK、数据库驱动、网络库），还需要一个稳定的运行时环境。如果你直接在物理机或虚拟机上安装，首先会遇到“它在我机器上跑得好好的，为什么到你那就挂了”的经典问题。不同系统（Ubuntu, macOS, Windows）的库版本、路径结构都可能成为拦路虎。

Docker 通过容器化技术，将应用及其所有依赖打包成一个独立的、可移植的“镜像”。这意味着，只要你的主机能运行 Docker，那么这个镜像在任何地方的行为都是一致的。对于 OpenClaw 这种需要长期运行、可能频繁更新插件和配置的服务，Docker 提供了绝佳的隔离性和可重现性。你可以轻松地回滚到上一个版本的镜像，可以毫不费力地在另一台服务器上克隆整个环境，这对于个人数据服务的高可用性维护来说，至关重要。

这个模板项目正是抓住了这个痛点。它没有让你从零开始 npm install ，而是提供了一个已经构建好的环境蓝图（Dockerfile）。你只需要执行 docker build 和 docker-compose up ，一个包含 OpenClaw 核心、预装插件、以及优化后系统配置的完整服务就启动了。这大大降低了技术门槛，让关注点从“如何搭建环境”回归到“如何使用和定制我的 AI 助手”本身。

2.2 容器架构设计：Gateway 与 CLI 的分离

仔细看项目提供的 docker-compose.yml ，你会发现它定义了两个服务： gateway 和 cli 。这是一种非常巧妙且符合最佳实践的设计，值得我们细细品味。

gateway 服务 是主力军，也是常驻士兵。它以后台守护进程（daemon）的形式运行 OpenClaw 的核心网关。它的职责是：

• 持续监听来自配置好的客户端（如 Discord Bot、Matrix 客户端）的请求。
• 加载并管理所有已安装的插件。
• 处理 AI 模型的调用逻辑和路由。
• 维护运行状态和日志。

为了让它的数据持久化，不被容器销毁而丢失，模板将主机上的一个目录（比如 ./data ）映射到了容器内的 /home/node/.openclaw 。这里存放着 OpenClaw 的核心配置文件 openclaw.json 、数据库文件以及日志。这样，无论容器如何重启、重建，你的配置和聊天历史都能得以保留。

cli 服务 则是一个特种兵，执行完特定任务就撤退。它是一个按需启动的临时容器，用途是执行 OpenClaw 的管理命令。为什么需要它？因为有些管理操作（比如最关键的初始化 onboard ）会频繁地读写和修改 openclaw.json 配置文件。如果让正在运行的 gateway 服务来执行这些命令，会导致配置文件被改动，进而触发网关服务的重启，可能使初始化过程中断或进入不可预知的状态。

因此， cli 服务通过 docker-compose run --rm cli <command> 的方式启动一个全新的、临时的容器，它共享同一个配置卷（ /home/node/.openclaw ），但独立于 gateway 运行。它执行命令修改配置，任务完成后容器自动删除，而 gateway 服务完全不受干扰。这种职责分离的设计，保证了服务核心的稳定性和管理操作的灵活性。

2.3 预装插件与扩展性考量

模板在 Dockerfile 中预装了 @openclaw/matrix 插件。这是一个深思熟虑的选择。Matrix 是一个开放、去中心化的实时通信协议，类似于一个开源的 Slack 或 Discord。选择它作为首个预装插件，有几点考虑：

1. 隐私友好 ：你可以搭建自己的 Matrix 服务器（如 Synapse 或 Dendrite），实现从 AI 模型到通信渠道的完全自托管，契合“Own Your Data”的精神。
2. 协议开放 ：不同于 Discord 或 Slack 的封闭 API，Matrix 协议允许更深度和灵活的集成。
3. 示范作用 ：它作为一个范例，展示了如何将 OpenClaw 与一个消息平台连接。理解了它的配置方式，你就能举一反三地配置其他插件（如 Discord、Telegram）。

注意 ：预装插件被安装在容器内的一个固定路径。模板通过 Docker 的“匿名卷”机制，将 /home/node/.openclaw/extensions 目录挂载为一个卷。这样做的目的是，即使你重建镜像，已经下载并放置在此目录下的插件也不会丢失。但这也意味着，如果你通过修改 Dockerfile 来增删预装插件，并重建了镜像，你需要手动处理这个卷中的数据与新镜像的兼容性问题。一个稳妥的做法是在重建前，备份或清空这个卷。

扩展性方面，模板通过集成 Homebrew 留下了后门。Homebrew 是 macOS 上著名的包管理器，在 Linux 容器内使用它，可以方便地安装一些 OpenClaw 可能依赖但未直接包含的系统级工具或库（比如某些语音处理库需要的音频工具）。Dockerfile 中配置了国内镜像源以加速安装，如果你不在国内，移除这些环境变量即可。这种设计给了高级用户一个“逃生舱”，可以在不修改 Dockerfile 主体的情况下，快速安装临时需要的软件包。

3. 从零开始的完整部署实操指南

理论讲得再多，不如动手做一遍。下面我将结合项目文档和我自己的实践，给出一个从零开始、包含所有细节的部署流程。假设你在一台干净的 Linux 服务器（如 Ubuntu 22.04）或本地开发机（macOS/Linux）上操作。

3.1 前期准备与环境检查

首先，确保你的系统已经安装了必要的软件：

1. Docker 与 Docker Compose ：这是基础中的基础。可以通过官方脚本安装 Docker，Docker Compose 通常作为插件包含在现代 Docker 安装中。

   # 在Ubuntu上，一个快速的安装方式（生产环境请参考官方文档）
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次用sudo
   # 注销并重新登录，使组权限生效
   

   安装后，运行 docker --version 和 docker compose version 确认安装成功。
2. Git ：用于克隆仓库。

   sudo apt update && sudo apt install git -y # Ubuntu/Debian
   

3.2 获取与自定义模板

接下来，获取项目代码并进行初步定制。

# 1. 克隆仓库到本地
git clone https://github.com/Fanccy315/openclaw-docker.git
cd openclaw-docker

# 2. （可选但推荐）查看并理解 Dockerfile
cat Dockerfile

关键的 Dockerfile 内容解读：

• FROM node:22-bookworm-slim ：使用官方的 Node.js 22 精简版镜像作为基础，体积小且安全。
• 一系列 RUN 命令：设置非 root 用户 node ，安装 Homebrew 并配置镜像源，清理缓存。这些是构建稳定环境的基础操作。
• USER node ：切换为 node 用户运行后续命令，遵循最小权限原则。
• RUN npm install -g @openclaw/cli @openclaw/matrix ：核心步骤，全局安装 OpenClaw CLI 和 Matrix 插件。 这里就是你可以自定义的地方 。如果你想预装其他官方或第三方插件（例如 @openclaw/discord ），就在这一行添加，如 npm install -g @openclaw/cli @openclaw/matrix @openclaw/discord 。
• 最后的 CMD 指令定义了容器默认启动的命令，即 openclaw gateway ，这正好对应 docker-compose.yml 中 gateway 服务的启动命令。

3.3 构建 Docker 镜像

你可以选择在本地构建，也可以利用项目提供的 GitHub Actions 在云端构建。对于首次部署，建议先在本地构建以快速验证。

# 在项目根目录执行
docker build -t my-openclaw:latest .

这个命令会根据当前目录的 Dockerfile 构建一个名为 my-openclaw ，标签为 latest 的镜像。构建过程会下载基础镜像、安装 Node.js 依赖，可能需要几分钟时间，取决于你的网络速度。

实操心得 ：第一次构建时，可能会因为网络问题导致 npm install 或 Homebrew 安装失败。如果遇到这种情况，可以尝试在 Dockerfile 中为 npm 也配置国内镜像源（如 RUN npm config set registry https://registry.npmmirror.com ），或者使用构建缓存 docker build --no-cache -t ... 重新构建。构建成功后，使用 docker images 命令应该能看到你的 my-openclaw 镜像。

3.4 配置与运行：关键步骤详解

镜像构建好后，真正的配置才开始。项目根目录下的 docker-compose.yml 是编排文件，定义了服务如何运行。

第一步：调整 docker-compose.yml（可选但重要） 打开 docker-compose.yml ，重点关注以下几点：

• 端口映射 ： gateway 服务默认没有映射任何端口到主机。因为 OpenClaw 主要通过插件与外部服务（如 Matrix）通信，网关本身不直接提供 HTTP 服务。如果你需要启用某些插件的管理界面或调试端口，可以在这里添加 ports 映射。
• 环境变量 ：如前所述， HOMEBREW_* 环境变量配置了国内镜像源。如果你不需要，或者不在国内，可以删除或注释掉这三行。
• 卷映射 ： - ./data:/home/node/.openclaw 这一行将当前目录下的 data 文件夹映射为配置存储位置。确保这个路径对你来说是合适的。你可以将其改为绝对路径，如 /path/to/your/openclaw/data:/home/node/.openclaw ，这样更清晰。

第二步：执行初始化配置（最关键的一步） 这是让 OpenClaw 从“一个空壳”变成“可配置实例”的过程。

# 使用临时的 cli 容器执行初始化命令
docker compose run --rm cli onboard --no-install-daemon

执行这个命令后，CLI 会启动一个交互式向导：

1. 它会提示你输入 OpenClaw 实例的名称。
2. 接着会问你是否要安装并运行 OpenClaw 守护进程。 这里一定要选择 n (否) ，因为我们已经用 Docker Compose 来管理服务了，不需要它再安装一个系统服务。
3. 然后会提示选择绑定模式（bind mode）。 这里必须选择 lan 。这个模式会将服务绑定到容器内的所有网络接口（ 0.0.0.0 ），这对于 Docker 容器间的网络通信至关重要。如果错误地选择了 local （只绑定到 127.0.0.1 ），那么 gateway 服务将无法被同一 Docker 网络内的其他容器（比如未来的其他服务）访问。
4. 初始化完成后，CLI 容器会自动退出并删除。此时，你本地的 ./data 目录下应该生成了初始的 openclaw.json 配置文件。

第三步：启动核心网关服务 初始化配置完成后，就可以拉起常驻的网关服务了。

# 启动 gateway 服务并在后台运行
docker compose up -d gateway

# 查看服务日志，确认启动是否成功
docker compose logs -f gateway

如果一切顺利，日志最后会显示网关已启动，并开始加载插件（如预装的 Matrix 插件）。你可以用 docker compose ps 查看服务状态，应该看到 gateway 服务是 Up 状态。

4. 插件配置与设备配对实战

服务跑起来了，但它现在还是个“光杆司令”，没有连接任何 AI 能力，也没有连接任何聊天界面。接下来我们需要给它注入灵魂。

4.1 配置 Matrix 插件连接

OpenClaw 通过插件与外界通信。我们已经预装了 Matrix 插件，现在需要配置它。配置是通过修改 ./data/openclaw.json 文件完成的。

首先，你需要一个 Matrix 账户和可以访问的 Matrix 服务器（Homeserver）。你可以使用公共服务器（如 matrix.org ），但为了完全自托管，我强烈建议自己搭建一个（例如使用 Synapse）。假设你已经有了一个 Matrix 账户 @yourbot:your-server.com 。

1. 停止网关服务，避免配置时服务重启： docker compose stop gateway 。
2. 编辑 ./data/openclaw.json 。在 "plugins" 部分，你会找到 "@openclaw/matrix" 的配置项。你需要填写以下关键信息：

   {
     "plugins": {
       "@openclaw/matrix": {
         "enabled": true,
         "config": {
           "homeserver": "https://your-server.com", // 你的 Matrix 服务器地址
           "userId": "@yourbot:your-server.com", // 机器人的 Matrix ID
           "accessToken": "YOUR_MATRIX_ACCESS_TOKEN", // 机器人的访问令牌
           "autoJoin": true, // 是否自动加入被邀请的房间
           "encryption": true // 是否启用端到端加密（推荐）
         }
       }
     }
   }
   

   如何获取 accessToken ？这通常需要在你的 Matrix 客户端（如 Element）中，为机器人账户创建一个新的访问令牌。具体步骤因服务器和客户端而异，一般可以在客户端的设置 -> 帮助与关于 -> 访问令牌中找到创建和管理令牌的地方。
3. 保存配置文件，然后重新启动网关服务： docker compose start gateway 。
4. 查看网关日志 docker compose logs -f gateway ，应该能看到 Matrix 插件正在尝试登录并连接。登录成功后，你就可以在 Matrix 客户端中搜索这个机器人用户并与之私聊，或者将它拉入群组。

4.2 设备配对：连接 AI 服务

OpenClaw 将每一个 AI 服务（如 OpenAI 的 ChatGPT、Anthropic 的 Claude）或工具抽象为一个“设备”（Device）。在使用这些设备前，需要进行“配对”（Approve），这实际上是一个授权和配置的过程。

根据项目文档的提示， 设备配对必须在运行 gateway 服务的容器内执行 ，而不是在临时的 cli 容器里。这是因为配对操作需要与正在运行的网关进程进行交互。

具体操作步骤：

1. 首先，确保你的 gateway 服务正在运行 ( docker compose ps )。
2. 进入 gateway 容器的交互式 Shell：

   docker exec -u node -it openclaw-docker-gateway-1 /bin/bash
   

   注意 ：容器名称可能因你的项目目录名而异，可以用 docker ps 查看准确的容器名。 -u node 指定以 node 用户身份进入，避免权限问题。

3. 在容器内部，首先列出当前待处理的设备配对请求：

   openclaw devices list
   

   初始状态下，这个列表可能是空的。你需要先触发一个配对请求。如何触发？通常是通过与已配置的插件（如 Matrix 机器人）交互，尝试使用某个尚未配置的 AI 服务。例如，在 Matrix 里对机器人说“/use claude”，如果 Claude 设备未配对，网关会生成一个配对请求。
4. 再次执行 openclaw devices list ，你现在应该能看到一个待批准的请求，其中包含一个 Request ID 和设备类型（如 claude ）。
5. 批准该设备配对：

   openclaw devices approve <Request ID>
   

   执行此命令会启动一个交互式配置向导。以 Claude 为例，它会引导你：
   • 输入该设备的显示名称（如 “My Claude”）。
   • 输入对应的 API 密钥（你需要提前在 Anthropic 官网获取）。
   • 选择模型版本（如 claude-3-5-sonnet-20241022 ）。
   • 配置其他参数（如请求超时时间、最大 token 数等）。
6. 配置完成后，退出容器的 Shell： exit 。

现在，你的 OpenClaw 实例已经成功连接了一个 AI 服务。你可以在 Matrix 中与机器人对话，并指定使用这个新配对的设备（例如：“@bot: /use claude” 然后正常聊天）。你可以重复此过程，添加多个不同的 AI 设备（如 GPT、Gemini 等），并在聊天中根据需要切换使用。

5. 进阶运维与问题排查实录

将服务稳定跑起来只是第一步，长期的维护和问题解决能力更重要。下面分享一些我在使用这个模板过程中遇到的典型问题及解决方法。

5.1 常见问题与解决方案速查表

问题现象	可能原因	排查步骤与解决方案
docker compose up 失败，提示 build 错误	1. Dockerfile 语法错误。 2. 网络问题导致依赖下载失败。 3. 基础镜像拉取失败。	1. 运行 docker build -t test . 单独构建，查看更详细的错误输出。 2. 检查 Docker 守护进程状态 systemctl status docker 。 3. 尝试更换 Docker 镜像源或使用代理。
服务状态为 Restarting	1. 应用启动后立即崩溃。 2. 配置错误（如 openclaw.json 格式错误）。 3. 端口冲突（如果映射了端口）。	1. 查看详细日志 docker compose logs --tail=50 gateway 。 2. 检查 ./data/openclaw.json 的 JSON 格式是否正确（可用在线工具校验）。 3. 检查 docker-compose.yml 中映射的端口是否被主机其他程序占用。
Matrix 插件连接失败，日志显示 Invalid access token	1. Matrix 访问令牌错误或已失效。 2. userId 或 homeserver 地址填写错误。	1. 在 Matrix 客户端中为机器人重新生成访问令牌并更新配置。 2. 确认 userId 格式为 @username:server.com ， homeserver 地址包含 https:// 前缀。
在 Matrix 中与机器人说话无反应	1. Matrix 插件未成功登录。 2. 机器人未加入当前房间。 3. 网关服务未正常运行。	1. 查看网关日志，确认 Matrix 插件是否显示登录成功。 2. 在 Matrix 客户端中，确保已邀请机器人账户加入聊天房间。 3. 检查 docker compose ps ，确认 gateway 服务为 Up 状态。
执行 openclaw devices approve 时无反应或报错	1. 未在 gateway 容器内执行命令。 2. 没有待处理的设备请求。	1. 确保使用 docker exec 进入 gateway 容器执行 ，而非 cli 容器。 2. 先与机器人交互触发请求（如发送 /use gpt ），再用 openclaw devices list 查看。
容器内 Homebrew 安装软件慢	Dockerfile 中配置的镜像源不适合你的网络环境。	进入容器 ( docker exec -it ... bash )，编辑 /home/node/.bashrc ，注释或修改 HOMEBREW_* 环境变量，然后 source ~/.bashrc 。或者，在 docker-compose.yml 的 gateway 服务环境变量中覆盖它们。

5.2 数据备份与迁移策略

你的所有核心数据（配置、聊天记录、插件数据）都保存在主机映射的 ./data 目录（具体路径取决于你的 docker-compose.yml 设置）。因此，备份和迁移变得非常简单。

备份：

# 假设你的数据卷在 /path/to/openclaw/data
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz -C /path/to/openclaw data/

这个命令会将整个 data 目录打包压缩。定期执行此操作，并将备份文件存储到安全的地方（如另一台服务器、云存储）。

迁移到新服务器：

1. 在新服务器上安装 Docker 和 Docker Compose。
2. 将整个项目目录（包括 docker-compose.yml , Dockerfile 等）和备份的 data 目录压缩包拷贝过去。
3. 解压备份数据到项目目录下，确保目录结构与原环境一致。
4. 运行 docker compose up -d gateway 。 由于 Docker 镜像可以通过网络拉取，而你的所有状态都在 data 目录里，所以服务会无缝地在新的服务器上以完全相同的状态运行起来。

5.3 使用 GitHub Actions 实现自动化构建与部署

对于追求自动化的用户，项目模板提供了 GitHub Actions 工作流（在 .github/workflows/ 目录下）。它的作用非常棒：当你修改 Dockerfile 或更新版本号后，自动构建新的 Docker 镜像，并可以推送到 Docker Hub 或 GitHub Container Registry，甚至自动部署到你的服务器。

如何使用：

1. Fork 仓库 ：首先，你需要 Fork 这个项目到你自己的 GitHub 账户下。
2. 配置 Secrets ：在你的 Fork 仓库的 Settings -> Secrets and variables -> Actions 页面，添加文档中提到的那些 Secrets（ SSH_HOST , SSH_USERNAME , SSH_PRIVATE_KEY 等）。这相当于给了 GitHub Actions 一把安全访问你服务器的钥匙。
3. 触发构建 ：修改 version.txt 文件中的版本号，然后提交并推送到你的仓库。这会自动触发工作流，执行构建。
4. 查看结果 ：在仓库的 Actions 标签页下，你可以看到工作流的运行状态和日志。

重要安全提示 ： SSH_PRIVATE_KEY 是你服务器的 SSH 私钥。务必使用一个具有最小必要权限的专用密钥对（比如，仅能访问特定目录进行文件上传），并 绝对不要 将私钥内容直接提交到代码仓库中。GitHub Secrets 是存储这类敏感信息的安全方式。

通过这套组合拳，你就拥有了一个从代码变更到服务更新的完整 CI/CD 流水线。开发测试时在本地快速迭代，稳定后通过 GitHub Actions 自动更新生产环境，这对于个人项目的维护来说，效率和可靠性都提升了一大截。

这个 OpenClaw Docker 模板，就像一位贴心的向导，为你扫清了自托管 AI 助手路上的一大片技术荆棘。它未必能满足所有极端定制化的需求，但它提供了一个极其坚实和优雅的起点。剩下的，就是发挥你的想象力，去配置更多的插件，连接更多的 AI 模型，打造一个真正属于你、懂你、且隐私无忧的数字伙伴。