Docker部署openclaw AI助手：从零到一的完整实践指南

1. 项目概述快速启动你的AI助手最近在折腾一个叫 openclaw 的开源AI助手项目它本质上是一个可以部署在本地或服务器上的智能体Agent平台。简单来说你可以把它理解为一个“大脑”通过连接各种大语言模型比如 OpenAI 的 GPT、Anthropic 的 Claude、国内的 Qwen 等和消息渠道比如 Telegram、Discord、飞书让它帮你处理信息、回答问题甚至执行一些自动化任务。我之所以对它感兴趣是因为它提供了一个高度可定制、且能完全私有化部署的AI交互方案这对于注重数据隐私或者想深度集成到自有工作流的开发者来说非常有吸引力。这个项目本身功能强大但初始的部署和配置对于不熟悉 Docker 和命令行操作的朋友来说可能有点门槛。好在社区里已经有了一个名为start-openclaw的配套项目它的目标非常明确用最简单、最标准化的 Docker 方式帮你一键拉起 openclaw 服务。它把环境依赖、服务编排都打包好了你只需要几条命令就能获得一个可运行的 openclaw 实例极大地降低了上手难度。无论你是想快速体验 openclaw 的核心功能还是打算将其作为长期服务的基础这个 Docker 化的启动方案都是极佳的起点。接下来我将结合我自己的部署经验为你详细拆解从零开始使用start-openclaw的完整流程。我会重点解释每个步骤背后的“为什么”分享我在配置过程中踩过的坑和总结的技巧目标是让你不仅能成功跑起来还能理解其中的关键配置以便后续根据自身需求进行灵活调整。2. 环境准备与核心概念解析在动手之前我们需要确保基础环境就绪并理解几个核心概念这能帮助你在后续配置时做出更明智的选择。2.1 系统与Docker环境检查start-openclaw的核心依赖是 Docker。Docker 是一个容器化平台它可以把应用程序及其所有依赖库、环境变量、配置文件打包成一个独立的“容器”。这样做的好处是你无需在宿主机上复杂地配置 Python、Node.js 等运行环境避免了“在我机器上能跑”的经典问题。宿主机要求操作系统主流的 Linux 发行版如 Ubuntu 22.04 LTS、Debian 11/12、CentOS Stream 9、macOS 或 Windows需使用 WSL 2。我个人推荐在 Linux 服务器或 WSL 2 环境下进行最为稳定。Docker 引擎需要安装 Docker CE社区版或 Docker Desktop。你可以通过运行docker --version和docker-compose --version或docker compose version来检查是否已安装及版本。网络由于需要从 GitHub 的容器注册表ghcr.io拉取镜像你的宿主机必须能够访问ghcr.io和github.com。对于国内用户如果拉取镜像缓慢或失败可能需要配置 Docker 镜像加速器。安装与加速针对Linux如果你还没有安装 Docker可以参照以下步骤以 Ubuntu 为例# 1. 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 2. 安装依赖包 sudo apt-get update sudo apt-get install ca-certificates curl gnupg lsb-release # 3. 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 4. 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 5. 安装 Docker 引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 6. 验证安装 sudo docker run hello-world对于网络加速可以编辑或创建/etc/docker/daemon.json文件加入国内镜像源例如{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }然后重启 Docker 服务sudo systemctl restart docker。2.2 理解 openclaw 的容器化部署架构当我们使用start-openclaw时我们实际上在运行一个包含了完整 openclaw 应用及其运行时的 Docker 容器。这个架构有几个关键点需要理解镜像Image与容器Containerghcr.io/iamliuxiaozhen/start-openclaw:latest是一个 Docker 镜像它是应用的静态模板。当我们执行docker run或docker-compose up时Docker 会根据这个镜像创建并启动一个容器容器是镜像的运行实例。端口映射Port Mapping在配置中你会看到-p 127.0.0.1:18789:18789。这表示将容器内部的 18789 端口映射到宿主机的 18789 端口并且只绑定在宿主机的本地回环地址127.0.0.1上。这意味着最初只有宿主机本身能通过http://127.0.0.1:18789访问 openclaw 的 Web 界面。数据卷挂载Volume Mount这是至关重要的一环。容器本身是无状态的当容器被删除时其中的所有更改如下载的模型、创建的配置、聊天记录都会丢失。通过-v /host/path:/container/path将宿主机的目录挂载到容器内我们就能将 openclaw 产生的持久化数据如配置文件、工作空间文件保存在宿主机上。即使容器重建只要重新挂载相同的目录数据就能恢复。初始化Onboarding第一次运行容器后你需要进入容器执行openclaw onboard命令。这个过程会引导你完成核心配置如选择 AI 模型提供商、消息渠道、网络搜索工具等。这些配置信息会被保存在挂载的数据卷中。注意务必重视数据卷的配置。我曾因为忘记挂载卷在重启容器后丢失了所有配置和对话上下文不得不从头再来。官方也强烈建议配置卷挂载以避免 AI 助手“失忆”。3. 详细部署与初始化实操理解了基础概念后我们进入实战环节。我将以docker-compose方式为例进行详解因为这是管理容器生命周期启动、停止、重启更优雅的方式。3.1 获取并配置 docker-compose.yml 文件首先你需要获取项目的docker-compose.yml.example文件。通常你可以直接克隆start-openclaw的仓库或者直接下载这个文件。# 假设你在一个工作目录下例如 ~/projects cd ~/projects # 克隆仓库如果网络允许 git clone https://github.com/iamliuxiaozhen/start-openclaw.git cd start-openclaw如果网络不畅你也可以直接在 GitHub 页面上找到docker-compose.yml.example文件点击“Raw”按钮复制其内容然后在本地创建一个同名文件。接下来将其重命名为docker-compose.ymlcp docker-compose.yml.example docker-compose.yml现在用你喜欢的文本编辑器如nano,vim,VSCode打开docker-compose.yml文件。你会看到类似以下的内容services: openclaw: build: . container_name: openclaw-bot restart: unless-stopped privileged: true ports: - 127.0.0.1:18789:18789 volumes: # Mount volumes here # -/home/username/ai-workspace:/workspace # /home/username/.openclaw:/root/.openclaw environment: - NODE_ENVproduction stdin_open: true tty: true关键配置修改与解释build: .这行指示 Docker Compose 根据当前目录的 Dockerfile 构建镜像。但start-openclaw项目更推荐直接使用预构建的镜像。因此我建议将这行替换为image: ghcr.io/iamliuxiaozhen/start-openclaw:latest。这样会直接从仓库拉取镜像更快更稳定。services: openclaw: image: ghcr.io/iamliuxiaozhen/start-openclaw:latest # ... 其他配置保持不变volumes数据卷挂载这是你必须取消注释并修改的部分。它定义了哪些宿主机目录要映射到容器内。- /home/username/ai-workspace:/workspace将宿主机的/home/username/ai-workspace目录挂载到容器的/workspace。这是 openclaw 的工作空间AI 读写文件、执行代码都在这里。请将/home/username替换为你自己宿主机上的真实用户目录例如/home/ubuntu或/home/yourname。- /home/username/.openclaw:/root/.openclaw将宿主机的/home/username/.openclaw目录挂载到容器的/root/.openclaw。这是 openclaw 的核心配置目录onboard流程生成的配置文件、凭证、对话缓存等都存储在这里。同样需要替换路径。实操建议在宿主机上提前创建好这两个目录并确保当前用户有读写权限。mkdir -p ~/ai-workspace ~/.openclaw修改后的volumes部分应类似volumes: - /home/your_username/ai-workspace:/workspace - /home/your_username/.openclaw:/root/.openclawports端口映射默认127.0.0.1:18789:18789意味着服务只在宿主机本地可访问。如果你需要通过局域网其他设备访问 Web 界面暂时保持不动我们后面在高级配置里再调整。privileged: true给予容器特权模式。这通常是必要的因为 openclaw 可能需要访问宿主机的某些资源如 Docker 守护进程如果要在容器内运行代码或操作其他容器。这是一个安全权衡在可信环境下使用问题不大。修改并保存好docker-compose.yml文件。3.2 启动 openclaw 服务在包含docker-compose.yml文件的目录下执行以下命令启动服务# 默认在前台启动可以看到日志输出按 CtrlC 停止 docker-compose up # 或者使用守护进程模式在后台启动 docker-compose up -d我推荐先使用docker-compose up在前台运行观察启动日志是否有错误。如果看到服务正常启动并监听端口的日志说明容器已成功运行。之后可以按CtrlC停止再用docker-compose up -d在后台运行。使用docker-compose ps可以查看服务状态docker-compose logs -f openclaw可以实时查看日志。3.3 首次初始化配置 (Onboarding)容器运行起来后openclaw 服务本身还处于“未配置”状态。我们需要进入容器内部进行初始化。进入容器docker exec -it openclaw-bot bash这个命令会打开一个交互式的 bash 终端你就像登录到了这个容器内部。执行初始化向导openclaw onboard这会启动一个交互式的命令行向导。下面我带你一步步走完关键选择并解释每个选项的意义。第一步风险确认与模式选择你会看到一个安全提示页需要阅读并确认。然后选择模式◆ Onboarding mode │ ● QuickStart (Configure details later via openclaw configure.) │ ○ ManualQuickStart快速开始推荐新手选择。它会引导你完成最核心的几项配置模型、渠道其他高级设置可以后续通过openclaw configure命令再调整。Manual手动模式提供所有可配置项的完整列表适合有经验的用户进行精细化配置。选择QuickStart按回车。第二步选择 AI 模型/认证提供商这是一个很长的列表包含了 openclaw 支持的各种大模型 API。◆ Model/auth provider │ ● OpenAI (Codex OAuth API key) │ ○ Anthropic │ ○ Chutes ... (众多选项) │ ○ Skip for nowOpenAI如果你有 OpenAI 的 API Key这是最通用和强大的选择。AnthropicClaude 系列模型。Qwen阿里通义千问。Ollama如果你在本地运行了 Ollama 来部署开源模型如 Llama 3, Qwen2.5选这个。Skip for now暂时跳过后续再配置。但这样 AI 助手将无法工作。根据你的实际情况选择。例如选择OpenAI接下来会提示你输入 API Key。请提前准备好。第三步选择默认模型在选择完提供商后可能会让你选择该提供商下的具体模型。◆ Default model │ ● Keep current (qwen-portal/coder-model) │ ○ Enter model manually │ ○ qwen-portal/coder-model │ ○ qwen-portal/vision-model例如如果你选了 Qwen这里会列出可用的模型。选择你想要的比如qwen-portal/coder-model代码能力较强的模型。第四步选择消息渠道这是决定你如何与 AI 助手交互的关键。◆ Select channel (QuickStart) │ ● Telegram (Bot API) (recommended · newcomer-friendly) │ ○ WhatsApp (QR link) │ ○ Discord (Bot API) ... (众多选项) │ ○ Skip for nowTelegram非常推荐对新手友好。你需要先通过 BotFather 创建一个 Telegram Bot并获取它的 Token。Discord同样需要先在 Discord 开发者门户创建应用和 Bot获取 Token。飞书/Lark适合国内团队协作。Skip for now跳过后续通过 Web 界面配置。但初期你就只能通过本地 Web 界面http://127.0.0.1:18789来交互了。选择一个你常用的渠道。以 Telegram 为例选择后需要输入 Bot Token。第五步配置网络搜索◆ Search provider │ ● Brave Search (Structured results · country/language/time filters) │ ○ Gemini (Google Search) │ ○ Grok (xAI) ... (其他选项) │ ○ Skip for now这赋予了 AI 助手实时搜索网络信息的能力。例如选择Brave Search你需要去 Brave Search 官网申请一个免费的 API Key 并填入。如果暂时不需要可以选择Skip for now。后续可能还会有一些其他工具如代码解释器、文件读写的配置提示你可以根据向导一步步完成或者暂时跳过。完成与退出配置完成后向导会结束。你可以输入exit退出容器终端。3.4 验证与访问初始化完成后openclaw 服务应该已经就绪。访问本地 Web 界面在你的宿主机上打开浏览器访问http://127.0.0.1:18789。你应该能看到 openclaw 的 Web 用户界面。这是一个功能丰富的控制台你可以在这里直接与 AI 对话、管理配置、查看日志等。测试消息渠道如果你配置了 Telegram 等渠道现在可以去对应的 App 里给你的 Bot 发送消息看看它是否能正常回复。至此一个最基本的 openclaw 服务就已经部署并配置完成了。4. 高级配置、优化与问题排查基础服务跑通后我们可能会遇到一些需求或问题比如如何从外部网络访问、如何修改配置、服务挂了怎么办。这部分就是为你准备的“进阶手册”。4.1 调整网络访问范围默认配置下Web 界面只能在本机访问。如果你想让同一局域网下的其他设备比如你的手机、另一台电脑也能访问有两种方法。方法一修改 Docker 端口绑定简单但需注意防火墙这是最直接的方法修改docker-compose.yml中的ports部分ports: # 从 127.0.0.1:18789:18789 改为 - 0.0.0.0:18789:187890.0.0.0表示绑定到宿主机的所有网络接口。修改后重启服务docker-compose down docker-compose up -d现在同一局域网内的设备可以通过http://宿主机IP:18789来访问了。警告这样做意味着你宿主机的 18789 端口对局域网开放了。请确保你的宿主机防火墙如ufw、firewalld允许该端口的入站连接并且你信任你的局域网环境。在公网服务器上切勿直接这样暴露务必使用下面的反向代理或 VPN 方式。方法二修改 openclaw 内部绑定配置更灵活openclaw 服务本身有一个bind配置项控制其监听范围。默认是loopback仅容器内。我们可以进入容器修改它。# 1. 进入容器 docker exec -it openclaw-bot bash # 2. 进入配置目录 cd /root/.openclaw # 3. 编辑配置文件如果使用 nano nano openclaw.json # 如果使用 vim # vim openclaw.json在配置文件中找到bind字段可能在server或web部分将其值从loopback改为lan。{ // ... 其他配置 server: { bind: lan, // 修改这里 // ... } }lan模式会让服务监听在容器内的所有网络接口上结合 Docker 的端口映射-p 0.0.0.0:18789:18789就能实现局域网访问。 保存文件并退出编辑器。然后需要重启 openclaw 容器以使配置生效# 退出容器 exit # 重启容器 docker-compose restart不同bind模式的区别如下表所示模式监听范围适用场景loopback仅容器内部127.0.0.1仅通过宿主机本地访问最安全。lan容器内所有网络接口0.0.0.0配合 Docker 端口映射允许局域网访问。auto自动检测通常不推荐行为可能不明确。tailnet仅 Tailscale 网络用于 Tailscale 等虚拟组网环境。custom自定义 IP 地址高级用户指定特定 IP。4.2 配置反向代理生产环境推荐如果你希望在公网安全地访问 openclaw或者想使用域名和 HTTPS那么配置一个反向代理如 Nginx、Caddy是最佳实践。为什么需要反向代理安全Nginx/Caddy 可以处理 SSL/TLS 终止为你的服务提供 HTTPS 加密。便捷可以使用域名访问而非 IP 和端口。负载均衡与缓存为未来扩展预留可能性。统一入口如果你有多个服务可以通过不同路径如example.com/openclaw或子域名如claw.yourdomain.com来统一暴露。使用 Nginx 的基本配置示例假设你的 openclaw 容器运行在宿主机本地 18789 端口你想通过https://claw.yourdomain.com访问。在宿主机上安装 Nginx。创建一个新的 Nginx 配置文件例如/etc/nginx/sites-available/openclawserver { listen 80; server_name claw.yourdomain.com; # 替换为你的域名 # 强制重定向到 HTTPS可选但推荐 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name claw.yourdomain.com; # 替换为你的域名 # SSL 证书路径通过 Certbot 或其他方式获取 ssl_certificate /etc/letsencrypt/live/claw.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/claw.yourdomain.com/privkey.pem; # 其他 SSL 优化配置... location / { proxy_pass http://127.0.0.1:18789; # 指向本地 openclaw 服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下两行对于 WebSocket 连接很重要如果 openclaw Web 界面用到 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }创建软链接启用该配置并测试、重载 Nginxsudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置语法 sudo systemctl reload nginx # 重载配置确保你的docker-compose.yml中端口映射仍然是- 127.0.0.1:18789:18789只本地监听这样只有 Nginx 能访问它更安全。别忘了在域名 DNS 管理中将claw.yourdomain.com解析到你的服务器公网 IP。4.3 数据备份与迁移由于我们将数据卷挂载到了宿主机备份变得非常简单。你只需要定期备份宿主机上的这两个目录~/ai-workspace工作空间文件。~/.openclaw核心配置、缓存和凭证。备份示例# 创建一个备份压缩包 tar -czf openclaw-backup-$(date %Y%m%d).tar.gz ~/ai-workspace ~/.openclaw # 你可以将这个 tar.gz 文件转移到其他安全的地方迁移到新服务器在新服务器上安装 Docker 和 Docker Compose。将备份的tar.gz文件传到新服务器并解压到对应用户的 home 目录下。将修改好的docker-compose.yml文件也复制过去。在新服务器上运行docker-compose up -d。 只要挂载的宿主机路径一致openclaw 就会读取原有的所有数据和配置实现无缝迁移。4.4 常见问题与排查实录即使按照步骤操作也可能会遇到问题。这里记录了几个我遇到过的典型情况及其解决方法。问题一执行docker-compose up时拉取镜像失败或超时。现象长时间卡在Pulling image...或报错net/http: TLS handshake timeout。原因网络连接ghcr.io不稳定尤其是国内网络环境。解决配置 Docker 镜像加速器如前文所述。如果加速器对ghcr.io无效可以尝试通过第三方工具或换用其他网络环境拉取。检查宿主机的 DNS 设置可以尝试修改/etc/docker/daemon.json增加dns: [8.8.8.8, 114.114.114.114]然后重启 Docker。问题二成功启动后访问http://127.0.0.1:18789无法连接。现象浏览器显示“无法连接”或“连接被拒绝”。排查步骤检查容器状态docker-compose ps确认openclaw-bot容器的状态是Up。查看容器日志docker-compose logs -f openclaw查看是否有启动错误。常见错误包括配置文件格式错误、依赖的服务连接失败等。检查端口映射docker port openclaw-bot 18789查看容器端口 18789 实际映射到了宿主机的哪个地址和端口。确认是否是0.0.0.0:18789或127.0.0.1:18789。进入容器内部测试docker exec -it openclaw-bot bash curl http://localhost:18789如果容器内能访问说明服务本身是好的问题出在 Docker 端口映射或宿主机防火墙。如果容器内也不能访问说明 openclaw 进程可能没有正常启动需要仔细查看日志。问题三Onboarding 过程中输入 API Key 或 Token 后测试失败。现象在配置模型或渠道时提示“Authentication failed”或“Could not connect”。原因Key/Token 错误复制粘贴时可能多了空格或换行。网络问题容器无法访问对应的 API 端点如api.openai.com。特别是如果宿主机在特殊网络环境下。账户问题API Key 余额不足、被禁用或 Token 未正确配置 Bot 权限。解决仔细检查并重新输入 Key/Token可以在文本编辑器里粘贴查看是否有不可见字符。进入容器测试网络连通性docker exec -it openclaw-bot bash # 测试 OpenAI curl -v https://api.openai.com/v1/models # 测试 Telegram Bot API curl -v https://api.telegram.org/botYOUR_BOT_TOKEN/getMe如果无法连通可能需要为 Docker 容器配置代理如果宿主机使用代理或者检查宿主机的防火墙/安全组规则是否放行了出站连接。登录对应的云服务平台或 Bot 管理后台确认 Key/Token 有效且具有所需权限。问题四AI 助手回复缓慢或经常超时。现象发送消息后很久才有回复或直接超时。原因模型 API 延迟使用的云端大模型如 GPT-4本身响应慢或当前负载高。网络延迟到 API 服务器的网络不稳定。容器资源不足如果使用了本地模型如通过 Ollama可能是 CPU/内存不够。解决尝试换用响应更快的模型如 GPT-3.5-Turbo。在 openclaw 的 Web 界面或配置中调整 API 调用的超时时间。如果使用本地模型确保为 Docker 容器分配了足够的资源。可以在docker-compose.yml中设置资源限制services: openclaw: # ... 其他配置 deploy: resources: limits: cpus: 2.0 memory: 4G注意deploy部分通常用于docker stack在普通docker-compose中可以使用cpus和mem_limit等字段具体取决于版本。问题五如何更新 openclaw 到新版本start-openclaw项目会更新其 Docker 镜像。更新步骤如下# 1. 拉取最新的镜像 docker-compose pull # 2. 停止并重新启动容器使用新镜像 docker-compose down docker-compose up -d # 3. 清理旧的镜像以节省空间 docker image prune由于配置和数据都通过卷挂载在宿主机更新镜像不会影响你的设置和聊天记录。部署和运维这样一个 AI 助手服务就像打理一个数字花园。初期搭建需要一些耐心但一旦稳定运行它就能持续为你提供价值。我的体会是花时间理解 Docker 和数据卷的概念以及 openclaw 的配置结构远比死记硬背命令更有用。当遇到问题时学会查看日志docker-compose logs和进入容器排查docker exec -it是独立解决问题的关键能力。最后对于生产环境安全永远是第一位的务必通过反向代理和防火墙来保护你的服务。