1. 项目概述：打造你的专属AI助手管家

最近在折腾一个挺有意思的项目，叫OpenClaw。简单来说，它是一个功能强大的个人AI助手，能帮你处理各种任务，比如自动浏览网页、执行命令、管理文件，还能通过Telegram、Discord这些你常用的聊天软件和你对话。听起来是不是有点像把ChatGPT的能力，加上自动化脚本，再塞进一个随时待命的机器人里？没错，差不多就是这个感觉。

但今天聊的重点不是OpenClaw本身，而是如何用Docker这个“集装箱”技术，把它封装成一个开箱即用、部署简单的服务。我用的这个Docker镜像来自 zot24/openclaw-docker ，它最大的好处就是帮你把所有复杂的依赖和环境配置都打包好了。你不需要去操心怎么安装Node.js、Python、Chromium浏览器这些乱七八糟的东西，也不用担心不同系统下的兼容性问题。对于喜欢在NAS（比如群晖）、树莓派或者Umbrel这类自托管平台上玩服务的爱好者来说，这种“一键部署”的体验实在是太友好了。

这个镜像就像一个预装好所有软件和驱动的“AI助手一体机”。你只需要提供几个关键的API密钥（比如给AI大脑用的Anthropic或OpenAI的密钥，还有给聊天机器人用的Telegram Bot Token），然后一条命令，它就能在你的服务器上跑起来。之后，无论是在公司电脑前，还是躺在床上用手机，你都能通过熟悉的聊天界面，让这个助手帮你查资料、写总结、甚至控制你服务器上的其他服务。接下来，我就带你从头到尾走一遍部署和配置的完整流程，并分享一些我踩过坑才总结出来的实战经验。

2. 核心设计思路与方案选型

2.1 为什么选择Docker化部署？

在深入配置之前，我们先聊聊为什么这种AI助手项目特别适合用Docker来部署。这不仅仅是跟风，而是由这类项目本身的技术特性决定的。

首先， 依赖复杂且庞杂 。OpenClaw作为一个全功能AI代理，其能力边界很广，这直接反映在它的依赖上。它需要一个Node.js环境来运行主程序，需要Go来编译某些组件（比如TTS工具 sag ），需要Python环境来运行一些基于MCP（Model Context Protocol）的工具，需要一个完整的Chromium浏览器来做网页自动化，还需要FFmpeg和ImageMagick来处理多媒体。手动在裸机或虚拟机上配置这一套环境，光是处理不同编程语言包管理器之间的冲突、解决浏览器在无头模式下的依赖，就足以让人头疼半天。Docker镜像把这些依赖全部封装在一个隔离的、标准化的环境里，保证了“在任何地方运行”的一致性。

其次， 安全性隔离 。AI助手拥有执行Shell命令、访问网络和文件系统的能力。虽然很强大，但也意味着潜在的风险。Docker容器提供了天然的隔离层，可以将助手的运行环境与宿主机系统隔离开。这个镜像还特意采用了非root用户（UID 1000）运行，进一步践行了最小权限原则。即使程序本身出现漏洞，攻击者也被限制在容器内部，难以影响到宿主机的其他服务或数据。

最后， 维护和升级的便捷性 。AI领域模型和工具迭代飞快。Docker镜像通过标签（Tag）管理版本，你可以轻松地在 latest （最新版）和某个固定的日历版本（如 v2026.1.30 ）之间切换。回滚到上一个稳定版本也只是一条命令的事。这对于追求稳定性的家庭服务器环境尤为重要。

2.2 镜像的架构与工具链解析

zot24/openclaw-docker 镜像采用了一个典型的多阶段构建（Multi-stage Build）策略，这能有效减小最终镜像的体积。我们来拆解一下它的层次：

1. 基础层（deps） ：这一层安装了所有系统级的依赖，比如操作系统包、Node.js、Go、Python、Chromium等。因为工具链相对稳定，这一层可以被很好地缓存，加速后续构建。
2. 构建层（builder） ：在这一层，它会从OpenClaw的官方GitHub仓库拉取指定版本的源代码，然后执行 npm install 和 npm run build 。这样，应用本身的构建过程被独立出来，只有当OpenClaw有新版本发布时，这一层才需要重新构建。
3. 运行层（runtime） ：这是最终我们下载和运行的镜像。它只包含运行OpenClaw所必需的文件：构建好的Node.js应用、编译好的Go二进制文件（如 sag ）、以及精简后的运行时依赖。通过这种分离，最终镜像在保持功能完整的前提下，体积得到了优化（约1.5-2GB）。

镜像内集成的工具链是其强大能力的基石：

• Playwright + Chromium ：这是实现“让AI上网”的关键。Playwright是一个强大的浏览器自动化库，Chromium是一个开源的浏览器内核。它们组合起来，使得OpenClaw可以像真人一样操作浏览器，点击、输入、滚动、截图，从而完成信息查询、数据抓取等任务。
• FFmpeg + whisper ：这对组合处理音频。FFmpeg负责音频格式的转换和剪辑，而whisper（OpenAI的开源语音识别模型）负责将语音消息转写成文字。这意味着你可以直接给助手发送语音指令。
• ImageMagick ：用于处理图片，比如调整大小、格式转换、简单的图像分析等。
• sag ：一个调用ElevenLabs文本转语音（TTS）API的命令行工具，可以让助手“开口说话”，将回复转换成语音消息。
• mcporter + uv/uvx ：这是对接MCP生态的工具。MCP允许外部工具（如数据库、日历、邮件客户端）以标准协议向AI模型提供上下文和操作接口。 mcporter 用于管理MCP服务器， uv 是一个快速的Python包管理器和运行器，用于执行那些用Python编写的MCP工具脚本。

这种“全家桶”式的打包，确保了OpenClaw所有预设功能在容器内都能直接运行，用户无需进行额外的、容易出错的安装步骤。

3. 从零开始的部署与配置实战

理论说得再多，不如动手跑起来。下面我将以最常用的 docker-compose 方式为例，带你完成一次完整的部署。我假设你已经在服务器上安装好了Docker和Docker Compose。

3.1 环境准备与快速启动

第一步，获取部署文件。通常我们需要克隆包含 docker-compose.yml 的仓库。

git clone https://github.com/zot24/openclaw-docker.git
cd openclaw-docker

不过，更常见的做法是，我们可能只想快速启动，不想克隆整个仓库。这时可以自己创建一个 docker-compose.yml 文件。这里我给出一个功能齐全的模板，你可以直接复制使用。

version: '3.8'

services:
  openclaw:
    image: ghcr.io/zot24/openclaw-docker:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789" # 网关Web界面和API端口
    environment:
      # --- 核心AI模型配置（至少配置一个）---
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-} # 例如：sk-ant-xxx
      # OPENAI_API_KEY: ${OPENAI_API_KEY:-} # 如果使用OpenAI，取消注释
      # OPENCODE_BASE_URL: http://host.docker.internal:11434/v1 # 如果使用本地Ollama，取消注释
      # OPENCODE_MODEL: llama3.1 # 本地模型名称

      # --- 通信渠道配置（按需启用）---
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-} # 强烈推荐从Telegram开始
      # DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN:-}

      # --- 网关与安全配置 ---
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-} # 建议设置一个强密码
      GATEWAY_BIND: lan # 如果仅本机访问，可改为 loopback

      # --- 代理运行时配置 ---
      AGENT_TIMEOUT: "600"
      ENABLE_BROWSER: "true"
      ENABLE_EXEC: "true" # 允许执行Shell命令，请谨慎评估风险
      EXEC_TIMEOUT: "30000"
    volumes:
      - ./data/openclaw:/home/openclaw/.openclaw # 配置和凭证持久化
      - ./data/workspace:/home/openclaw/clawd # 工作空间和记忆持久化
    # 如果使用本地Ollama且遇到连接问题，可能需要添加网络配置
    # networks:
    #   - default
    #   - ollama_network # 假设Ollama在另一个自定义网络中

同时，创建一个 .env 文件来存放你的敏感信息（ 务必将此文件加入 .gitignore ）：

# .env 文件示例
# AI模型密钥 (选一个即可)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 通信渠道令牌
TELEGRAM_BOT_TOKEN=1234567890:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# 网关令牌（用于访问Web界面API）
OPENCLAW_GATEWAY_TOKEN=my_strong_gateway_password_here

重要提示 ： ENABLE_EXEC: “true” 赋予了AI助手在容器内执行Shell命令的能力，这非常强大但也存在风险。请确保你完全信任所连接的AI模型，并且理解其可能执行的操作。在生产环境或对安全性要求高的场景中，可以考虑将其设置为 false 。

准备工作完成后，启动服务就一行命令：

docker-compose up -d

使用 docker-compose logs -f openclaw 可以查看实时日志。如果一切正常，你应该能看到服务启动成功的消息。现在，打开浏览器，访问 http://你的服务器IP:18789/chat ，就能看到OpenClaw的Web聊天界面了。首次访问可能需要输入你在 .env 文件中设置的 OPENCLAW_GATEWAY_TOKEN 。

3.2 核心通道配置详解：以Telegram为例

Web界面不错，但通过聊天软件与助手交互才是更自然的方式。Telegram因其强大的Bot API和广泛的用户基础，成为首选的集成渠道。下面详细说说配置步骤和背后的原理。

第一步：创建Telegram Bot

1. 在Telegram中搜索并联系 @BotFather 。
2. 发送 /newbot 指令，按提示操作。
3. 为你的Bot起一个名字（如 My OpenClaw Assistant ）和一个唯一的用户名（必须以 bot 结尾，如 my_openclaw_bot ）。
4. 创建成功后， @BotFather 会给你一串像 1234567890:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 的令牌。这就是 TELEGRAM_BOT_TOKEN 。

第二步：理解配置策略 在 .env 或 docker-compose.yml 中，除了令牌，还有几个重要的策略变量：

• OPENCLAW_DM_POLICY ：控制谁可以直接私聊（DM）你的Bot。默认为 pairing ，这是一种安全且灵活的模式。在此模式下，用户需要先在群组中 @ 提及Bot并成功交互一次后，才能获得私聊权限。这防止了陌生人随意私聊Bot。其他选项包括 allowlist （仅允许列表中的用户ID）和 open （允许任何人私聊）。
• TELEGRAM_ALLOWED_USERS ：当DM策略设为 allowlist 时，在此填写允许私聊的Telegram用户ID，用逗号分隔。你可以通过像 @userinfobot 这样的Bot来获取自己的用户ID。

第三步：配置与测试 将获取到的令牌填入 .env 文件，然后重启容器： docker-compose restart openclaw 。 查看日志，你应该能看到Bot已成功连接到Telegram API。现在，在Telegram里找到你的Bot，发送 /start 。如果配置了 pairing 策略，你需要先在一个有Bot的群组里 @ 它并说句话（比如“你好”），然后才能回到私聊窗口正常使用。

实操心得 ：强烈建议从 pairing 策略开始。 open 策略虽然方便，但可能引来垃圾消息或滥用。另外，记得将Bot添加到群组后，在群组设置里为Bot开启“封禁用户”、“删除消息”等管理员权限（如果需要它管理群聊），并关闭“隐私模式”，否则Bot无法看到群组内的普通消息。

3.3 集成本地大语言模型（Ollama）

使用云端API（如Claude、GPT）虽然方便，但存在延迟、费用和隐私顾虑。在本地部署像Ollama这样的工具来运行开源大模型（如Llama 3.1、Qwen等），是一个很好的替代方案。这里的关键在于让OpenClaw容器能够访问到Ollama服务。

场景一：Ollama与OpenClaw在同一台宿主机上 这是最简单的情况。Ollama默认在宿主的 11434 端口提供服务。Docker为容器提供了一个特殊的DNS名称 host.docker.internal 来指向宿主机的内部IP。 你只需要在OpenClaw的环境变量中配置：

OPENCODE_BASE_URL=http://host.docker.internal:11434/v1
OPENCODE_MODEL=llama3.1 # 替换成你在Ollama中拉取并运行的模型名

重启OpenClaw容器即可。OpenClaw会自动将 OPENCODE_BASE_URL 识别为一个本地模型提供商。

场景二：Ollama与OpenClaw都在Docker中（例如在Umbrel上） 在Umbrel或Portainer这类平台，每个应用通常运行在独立的容器中。它们之间需要通过Docker网络通信。

1. 确保网络互通 ：最简单的方法是让两个容器都连接到同一个自定义Docker网络。例如，先创建一个网络： docker network create ai-net 。然后在运行Ollama和OpenClaw时，都通过 --network ai-net 参数指定。
2. 使用容器名访问 ：在Docker网络中，容器可以通过其名称直接相互解析。假设你的Ollama容器名叫 ollama ，那么OpenClaw的配置应为：

   OPENCODE_BASE_URL=http://ollama:11434/v1
   OPENCODE_MODEL=llama3.1
   

3. 查找现有容器的网络 ：如果容器已经存在，你可以用 docker inspect <container_name> | grep -A 10 “Networks” 来查看它所在的网络，然后用 docker network connect <network_name> <openclaw_container> 将OpenClaw容器也加入那个网络。

避坑指南 ：最常见的问题是“连接被拒绝”。首先用 curl http://ollama:11434/api/tags 在OpenClaw容器内测试（通过 docker exec -it openclaw curl … ），看是否能获取Ollama的模型列表。如果失败，检查：1) Ollama容器是否正在运行；2) 两个容器是否在同一网络；3) Ollama是否绑定了 0.0.0.0 而不仅仅是 127.0.0.1 （Ollama默认是 0.0.0.0 ，所以通常没问题）。

4. 高级功能配置与优化技巧

基础功能跑通后，我们可以探索一些更高级的特性，让助手变得更智能、更贴心。

4.1 启用记忆搜索与工作空间管理

OpenClaw可以将对话历史存储到向量数据库中，从而实现基于语义的记忆搜索。这意味着助手能“记住”很久以前的对话内容，并在你问到相关问题时，从记忆中提取上下文。要启用这个功能，需要设置环境变量：

ENABLE_MEMORY_SEARCH=true

重启后，助手就会开始将对话内容向量化并存储。你可以在Web聊天界面或通过聊天渠道询问它“我们之前聊过关于XXX的事情吗？”，它会尝试从记忆中寻找相关信息。

工作空间目录（ /home/openclaw/clawd ）是助手的“硬盘”，它在这里存储记忆向量数据库、技能（Skills）定义文件、以及执行任务时产生的临时文件或下载的内容。通过Docker卷将其映射到宿主机（如 ./data/workspace:/home/openclaw/clawd ），可以持久化这些数据，即使容器重建也不会丢失记忆和技能。

技能（Skills） 是扩展助手能力的关键。你可以编写JavaScript/TypeScript文件放在工作空间的特定目录下，定义新的工具（Tools）供AI调用。例如，你可以写一个技能来查询你家庭智能家居的状态，或者控制你的媒体服务器。这需要一定的编程知识，但为助手赋予了无限的可能。

4.2 配置文本转语音（TTS）与语音消息处理

让助手“会说话”能极大提升交互体验，特别是在车载或智能家居场景中。OpenClaw通过集成 sag 工具来调用ElevenLabs的TTS服务。

1. 获取ElevenLabs API Key ：前往ElevenLabs官网注册，在个人资料页面可以找到API密钥。
2. 配置环境变量 ：

   ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
   SAG_VOICE_ID=一个特定的语音ID # 可选，如果不设置，sag会使用默认或第一个可用语音
   

3. 如何使用 ：配置完成后，当你在支持语音的渠道（如Telegram）中与助手交互时，在某些上下文中（例如你明确要求，或者助手认为语音回复更合适），它可能会尝试发送语音消息。需要注意的是，语音生成和传输需要时间，回复可能会比纯文本慢。

另一方面， 语音转文字（STT） 功能是自动启用的（依赖 whisper ）。当你向助手发送一条语音消息时，它会自动调用 whisper 模型（已内置在镜像中）将语音转录为文本，然后再进行处理。这要求你的服务器有一定的CPU/GPU算力，因为Whisper模型推理是计算密集型的。如果发现语音处理特别慢，可以考虑在OpenClaw的配置中调整Whisper的模型大小（如果支持），或者关闭此功能。

4.3 安全加固与网络调优

将一个人AI助手暴露在网络上，安全是重中之重。除了使用非root用户运行，这里还有几个加固点：

1. 网关令牌（Gateway Token） ： OPENCLAW_GATEWAY_TOKEN 是访问Web界面和API的密码。 务必 设置一个强密码，不要使用默认值或空值。这能防止未经授权的人访问你的助手Web界面。
2. 绑定模式（GATEWAY_BIND） ：
   • lan ：绑定到所有网络接口（ 0.0.0.0 ），局域网内其他设备可访问。适用于内网使用。
   • loopback ：仅绑定到本地回环地址（ 127.0.0.1 ），只有宿主机本身能访问。最安全，但意味着你无法从其他设备访问Web界面。
   • tailnet ：为Tailscale等虚拟组网软件设计。 如果只在部署的机器上使用Web界面，强烈建议设置为 loopback 。如果需要远程访问，应结合反向代理（如Nginx）和HTTPS、基础认证来增加安全层。
3. 防火墙规则 ：在宿主机防火墙或路由器上，只开放必要的端口（如 18789 ），并且可以考虑限制只允许特定IP段（如你的家庭IP）访问。
4. 定期更新 ：关注 zot24/openclaw-docker 仓库的更新，定期拉取新镜像并重建容器，以获取安全补丁和功能更新。可以使用 watchtower 等工具自动化此过程。

5. 故障排查与日常维护指南

即使按照教程一步步来，也难免会遇到问题。下面是一些常见问题的排查思路和解决方法。

5.1 容器启动失败与日志分析

容器启动失败，第一步永远是查看日志。

docker-compose logs openclaw # 查看最近日志
docker-compose logs -f openclaw # 实时跟踪日志
docker logs <container_id> # 如果没用compose，直接用容器ID或名

常见错误1：端口冲突

Error: listen EADDRINUSE: address already in use :::18789

这说明宿主机的18789端口已被其他程序占用。解决方法：要么停止占用端口的程序，要么在 docker-compose.yml 中修改端口映射，例如 - “18790:18789” ，然后通过 http://localhost:18790/chat 访问。

常见错误2：环境变量或卷权限问题

Error: Cannot write to /home/openclaw/.openclaw/config.json

这通常是宿主机上映射的目录权限不对。容器内以UID 1000的用户运行，需要确保宿主机上的对应目录（如 ./data/openclaw ）对该用户可写。可以尝试在宿主机上执行： sudo chown -R 1000:1000 ./data （假设你的数据目录是 ./data ）。

常见错误3：模型API连接失败 在日志中看到大量关于Anthropic或OpenAI API连接超时或认证失败的报错。

• 检查密钥 ：确认 .env 文件中的API_KEY是否正确，前后有无多余空格。
• 检查网络 ：如果服务器在国内，访问某些国际API可能不稳定。尝试在容器内用 curl 测试连通性： docker exec openclaw curl -v https://api.anthropic.com 。
• 代理配置 ：如果服务器需要通过代理访问外网，需要在Docker容器内设置代理环境变量（ HTTP_PROXY , HTTPS_PROXY ）。这可以在 docker-compose.yml 的 environment 部分添加。

5.2 渠道连接异常处理

Telegram Bot无响应

• 检查令牌 ：确认 TELEGRAM_BOT_TOKEN 完全正确。
• 检查网络 ：确保容器所在服务器能正常访问Telegram的API（ api.telegram.org ）。某些网络环境可能需要配置代理。
• 查看Bot状态 ：在Telegram中给Bot发送 /start ，并查看OpenClaw容器日志，看是否有收到消息的日志。如果没有，说明连接有问题。

WebSocket连接错误（Web界面） 访问Web聊天界面时，控制台报WebSocket连接错误。

• 检查网关令牌 ：确认在Web界面弹出的密码框中输入了正确的 OPENCLAW_GATEWAY_TOKEN 。
• 检查反向代理配置 ：如果你使用了Nginx等反向代理，需要确保其正确配置了WebSocket代理。通常需要添加以下配置：

  location / {
      proxy_pass http://localhost:18789;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header Host $host;
  }
  

5.3 性能优化与资源监控

OpenClaw容器在空闲时内存占用不高（几百MB），但在执行任务时（尤其是浏览器自动化或语音转录），资源消耗会飙升。

• 内存不足 ：如果服务器内存较小（如1-2GB的VPS），可能会在启动Chromium时遇到问题。可以考虑在环境变量中限制Node.js内存： NODE_OPTIONS=--max-old-space-size=1024 （单位MB）。或者，如果不需要浏览器功能，可以设置 ENABLE_BROWSER=false 来禁用Playwright。
• CPU占用高 ：语音转录（Whisper）是CPU密集型任务。如果不需要此功能，可以在未来OpenClaw支持配置时关闭它。目前，如果遇到性能问题，可以暂时避免发送语音消息。
• 磁盘空间 ：工作空间和记忆数据会随时间增长。定期检查 ./data/workspace 目录的大小。可以编写一个简单的清理脚本，定期删除 clawd 目录下的临时文件（如 tmp/ 目录内的内容），但注意不要误删记忆数据库文件。
• 监控 ：使用 docker stats openclaw 可以实时查看容器的CPU、内存和网络使用情况。对于长期运行的服务，建议将其集成到Grafana、Prometheus等监控系统中。

维护一个健康的OpenClaw实例，关键在于“按需配置”。不需要的功能（如某个聊天渠道、TTS）就关闭它，能有效减少资源消耗和安全风险。定期查看日志，了解助手的工作状态，及时更新镜像和基础模型，你就能获得一个稳定、可靠且强大的个人AI伙伴。