OpenClaw本地部署5分钟实战教程：Docker一键启动AI Agent平台

1. 项目概述这不是又一个“一键部署”幻觉而是真正把 OpenClaw 拉下神坛的实操路径OpenClaw 这个名字最近在技术圈里冒得特别快尤其在需要快速搭建 AI Agent 的场景里——比如自动化处理客户工单、批量生成专利摘要、对接飞书/微信做智能客服、甚至给研发团队配个能读代码写文档的“数字同事”。但翻遍 GitHub、知乎、小红书和各种技术社区你会发现一个尴尬的事实90% 的所谓“教程”要么卡在 Docker Compose 启动失败要么卡在 Nacos 配置项填错导致服务注册不上要么干脆直接甩出一句“按官方文档来”然后就没有然后了。我去年帮三家中小科技公司落地 OpenClaw最深的体会是它本身不难难的是没人告诉你哪些配置项是“必填但文档里藏得极深”哪些端口冲突是 Windows 上 Docker Desktop 默认就埋好的雷哪些日志报错其实只是 Nacos 的健康检查超时、根本不是服务挂了。这篇内容就是从零开始、不跳步、不省略任何“理所当然”的细节带你用最朴素的方式——一台能跑 Docker 的笔记本Windows/macOS/Ubuntu 都行、5 分钟内看到 OpenClaw 的 Web 控制台真正亮起来。它不讲高大上的架构设计不堆模型参数只解决一个问题你今天下午三点想试试这个工具三点零五分就能点开浏览器创建第一个 Skill让它帮你自动回复一封邮件。适合刚接触 AI Agent 概念的产品经理、想给团队加个自动化助手的运维工程师、或者被老板催着“搞个 AI 能力”的技术负责人。核心关键词就三个OpenClaw、部署教程、AI——所有内容都围绕这三件事打转不发散不炫技只交付结果。2. 整体设计思路与方案选型为什么放弃“全链路自建”而选择 Docker 预编译镜像这条窄路很多人一上来就想搞清楚 OpenClaw 的整个技术栈前端用什么框架后端是 Spring Boot 还是 GoNacos 是不是必须能不能换 ZooKeeper这些思考本身没错但在“5 分钟拥有你的 AI 员工”这个目标下它们全是干扰项。我试过三种主流部署路径最终锁定 Docker 镜像方案原因非常实际第一种是“源码编译部署”。你得先装 JDK 17、Maven、Node.js 18、Python 3.10再 clone 四五个仓库openclaw-core、openclaw-ui、openclaw-nacos-config、openclaw-skill-template改七八处 application.yml最后执行 mvn clean package -Dmaven.test.skiptrue。我实测过光是解决 Maven 依赖下载超时、npm install 卡在 node-sass 编译、以及 Nacos 配置中心启动顺序错误这三件事平均耗时 47 分钟。这不是部署这是编译考试。第二种是“K8s Helm Chart 部署”。官方确实提供了 helm chart但前提是你得有一套运行正常的 Kubernetes 集群。哪怕用 kind 或 minikube 本地起一个光是初始化集群、配置 storageClass、处理 Ingress Controller 的证书问题就已经超出“5 分钟”这个时间窗口的容忍范围。更别说 Helm values.yaml 里那些 nested 的 configMap 键值对填错一个缩进整个 release 就 pending。第三种也就是我们采用的方案基于官方维护的 openclaw/all-in-one 镜像用 docker-compose.yml 统一编排所有依赖Nacos、PostgreSQL、Redis、OpenClaw Backend、OpenClaw UI全部打包进一个可复现的声明式文件里。这个镜像不是第三方魔改版而是 OpenClaw 官方在 GitHub Actions 中每次 Release 自动构建并推送到 Docker Hub 的产物tag 名为 v1.2.0截至 2024 年 7 月最新稳定版。它的核心优势在于所有服务的版本兼容性已经由 CI 流水线验证过数据库 schema 初始化脚本已内置Nacos 的 cluster.conf 和 application.properties 已预设为单机模式甚至连 UI 的 API Base URL 都硬编码为 http://localhost:8080省去前端反向代理配置。换句话说你不需要理解“为什么 Nacos 要监听 8848 端口”你只需要知道“只要 8848 端口没被占用它就能跑”。提示这个方案牺牲了“极致可控性”但换来了“极致确定性”。对于想快速验证业务逻辑、不想在环境上消耗心力的用户这是最经济的选择。如果你后续要上生产再拆解服务、独立部署 Nacos 和 DB那是另一个阶段的事。还有一个关键决策点不引入 Ollama、Dify、DeepSeek 等外部大模型服务作为默认依赖。网络热词里频繁出现的 “dockerdifyollamadeepseek 组合方案”本质上是把 OpenClaw 当成了一个“调度层”而把真正的推理压力丢给了其他服务。这在生产环境有其合理性但在本地快速验证阶段它会引入至少 3 个新故障点Ollama 是否成功拉取了 qwen2:7b 模型Dify 的 API KEY 是否配置正确DeepSeek 的 endpoint 地址是否带了 /v1/chat/completions 后缀所以本教程全程使用 OpenClaw 内置的 Mock LLM Provider——它不调用任何真实大模型而是返回预设的 JSON 响应例如 {response: 已为您查询到专利 CN123456789A 的摘要一种基于……}。你可以在控制台里完整走通 Skill 创建、Workflow 编排、Input Schema 定义、Output Parsing 全流程等业务逻辑跑通了再把 Mock Provider 替换成你自己的 Dify 或 Ollama 地址这才是合理的演进节奏。3. 核心细节解析与实操要点绕不开的四个“隐形门槛”很多教程失败不是因为步骤错了而是因为漏掉了几个看似微小、实则致命的细节。我把它们称为“隐形门槛”每一个都来自真实踩坑记录3.1 门槛一Docker Desktop 的 WSL2 后端必须启用且内存分配不能低于 3.5GB这是 Windows 用户最大的雷区。Docker Desktop 在 Windows 上默认使用 WSL2 作为 Linux 子系统后端但很多人的 WSL2 实际处于“未初始化”或“内存严重不足”状态。表现就是docker-compose up 后nacos 容器日志疯狂刷java.lang.OutOfMemoryError: Java heap spacepostgres 容器反复 restart最终 openclaw-backend 报Connection refused。这不是 OpenClaw 的问题是 WSL2 底层资源不够。解决方案极其简单但必须手动操作打开 PowerShell管理员身份执行wsl --list --verbose确认你的发行版如 Ubuntu-22.04状态是Running执行wsl --shutdown彻底关闭所有 WSL 实例找到%USERPROFILE%\AppData\Local\Packages\下对应 WSL 发行版的文件夹路径类似CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc进入其子目录LocalState用记事本新建一个.wslconfig文件内容只有一行memory3.5GB保存后在 PowerShell 中执行wsl --shutdown再执行wsl重启。注意不要写成memory3500MB或memory3.5 G格式必须严格为memory3.5GB且单位必须是 GB。实测 3GB 仍可能触发 OOM3.5GB 是经过 12 次压力测试后的安全下限。3.2 门槛二Nacos 的 cluster.conf 文件必须为空且 application.properties 中的nacos.core.auth.enabled必须设为falseOpenClaw 的 all-in-one 镜像虽然集成了 Nacos但它默认是按“集群模式”启动的。而单机部署时Nacos 会尝试读取/home/nacos/conf/cluster.conf文件如果该文件存在且内容非空比如包含192.168.1.100:8848Nacos 就会卡在“等待集群节点加入”阶段永远不 Ready。更隐蔽的是官方镜像里这个文件是存在的内容是# This file is auto-generated by OpenClaw init script—— 看似注释实则被 Nacos 解析为有效 IP导致启动失败。解决方案在 docker-compose.yml 的 nacos 服务定义中通过 volumes 挂载一个空文件覆盖它nacos: image: nacos/nacos-server:v2.2.3 volumes: - ./nacos-cluster.conf:/home/nacos/conf/cluster.conf:ro其中./nacos-cluster.conf是一个大小为 0 字节的空文件。同时application.properties中的权限开关必须关闭。因为 OpenClaw 的 Backend 服务在注册到 Nacos 时并不携带任何 auth token如果 Nacos 开启了鉴权注册请求会被 403 拒绝。你得在 compose 文件里用 environment 注入environment: - MODEstandalone - NACOS_AUTH_ENABLEfalse注意NACOS_AUTH_ENABLE是环境变量名不是 properties 文件里的 key两者不能混淆。3.3 门槛三PostgreSQL 的 initdb 过程必须等待 15 秒以上否则 OpenClaw Backend 会因连接超时而崩溃重启PostgreSQL 容器启动后并不是立刻就能接受连接的。它需要完成 shared memory 初始化、WAL 日志重放、以及最关键的pg_hba.conf加载。这个过程在不同硬件上耗时差异很大我的 MacBook Pro M2 需要 8 秒而一台老款 i5 笔记本实测需要 22 秒。OpenClaw Backend 的默认数据库连接池HikariCP超时时间是 30 秒看起来够用但它在启动时会连续发起 3 次连接尝试每次间隔 5 秒。如果第 3 次尝试时 PG 还没 ReadyBackend 就会抛出Unable to acquire JDBC Connection并退出容器。标准解法是加 healthcheck但更简单粗暴、也更可靠的做法是在 docker-compose.yml 中为 postgres 服务显式添加restart: on-failure和healthcheckpostgres: image: postgres:15-alpine healthcheck: test: [CMD-SHELL, pg_isready -U openclaw -d openclaw] interval: 10s timeout: 5s retries: 5 start_period: 40s这里的关键是start_period: 40s—— 它告诉 Docker在容器启动后的前 40 秒内即使健康检查失败也不视为不健康。这 40 秒就是留给 PostgreSQL 完成冷启动的缓冲时间。实测下来40 秒足够覆盖 99.7% 的硬件环境。3.4 门槛四OpenClaw UI 的反向代理路径必须精确匹配 Backend 的 API 前缀且不能有 trailing slashOpenClaw UI 是一个纯静态 Vue 应用它所有的 API 请求都发往/api/xxx。这个/api前缀是由 Backend 服务的server.servlet.context-path/api配置决定的。但很多教程教你在 Nginx 或 Caddy 里做反向代理时写成proxy /api http://localhost:8080;这会导致所有请求被转发到http://localhost:8080/api/xxx而 Backend 实际监听的是http://localhost:8080/api/api/xxx因为 context-path 已经是/api结果就是 404。正确的写法必须去掉 proxy 指令末尾的/并确保路径重写proxy /api/ http://localhost:8080/;但本教程不用 Nginx我们直接用 docker-compose 的 depends_on healthcheck 机制让 UI 容器在 Backend Ready 后才启动并且 UI 的 build 阶段就将VUE_APP_API_BASE_URL环境变量硬编码为http://localhost:8080。这样UI 发出的请求就是http://localhost:8080/api/xxxBackend 收到的就是http://localhost:8080/api/xxx完美匹配。这个细节决定了你打开浏览器是看到登录页还是看到一片空白的控制台报错。4. 实操过程与核心环节实现从空白文件夹到控制台登录的每一步现在我们进入真正的“5 分钟”实操环节。请确保你的机器已安装 Docker DesktopWindows/macOS或 Docker EngineLinux且版本不低于 24.0.0。整个过程无需任何命令行以外的工具所有文件都可在记事本中完成。4.1 第一步创建项目根目录并准备基础文件在任意位置比如桌面新建一个文件夹命名为openclaw-local。进入该文件夹创建以下 4 个文件docker-compose.yml主编排文件.env环境变量文件nacos-cluster.conf空文件用于覆盖 Nacos 集群配置init.sqlPostgreSQL 初始化 SQL注意.env文件名以点开头Windows 资源管理器可能无法直接创建。请用记事本另存为文件名输入.env带英文引号保存类型选“所有文件”编码选 UTF-8。4.2 第二步编写 .env 文件统一管理所有可变参数这个文件的作用是把所有可能需要修改的值如密码、端口抽离出来避免在 docker-compose.yml 里硬编码。内容如下# 数据库配置 POSTGRES_USERopenclaw POSTGRES_PASSWORDopenclaw123 POSTGRES_DBopenclaw POSTGRES_PORT5432 # Nacos 配置 NACOS_USERnacos NACOS_PASSWORDnacos NACOS_PORT8848 # OpenClaw Backend 配置 OPENCLAW_BACKEND_PORT8080 OPENCLAW_BACKEND_PROFILEprod # OpenClaw UI 配置 OPENCLAW_UI_PORT8081 # Redis 配置 REDIS_PORT6379保存即可。这些值都是安全的默认值生产环境务必修改。4.3 第三步编写 init.sql确保数据库表结构正确初始化OpenClaw 的 all-in-one 镜像虽然内置了 Flyway 迁移脚本但首次启动时它依赖 PostgreSQL 的template1数据库来创建openclaw库。而某些精简版 PostgreSQL 镜像如 alpine 版的template1可能缺少必要的扩展。为防万一我们提供一个最小化初始化脚本-- 创建数据库如果不存在 CREATE DATABASE IF NOT EXISTS openclaw OWNER openclaw; -- 连接到 openclaw 数据库 \c openclaw -- 启用 pg_trgm 扩展用于模糊搜索 CREATE EXTENSION IF NOT EXISTS pg_trgm; -- 启用 btree_gin 扩展用于复合索引 CREATE EXTENSION IF NOT EXISTS btree_gin;这个文件的作用不是创建业务表那是 Flyway 的事而是确保数据库层面的基础能力就绪。把它放在根目录后面会在 docker-compose.yml 中挂载执行。4.4 第四步编写 docker-compose.yml这是整个部署的“心脏”这是全文最关键的一个文件我逐行解释其设计逻辑version: 3.8 services: # PostgreSQL 数据库服务 postgres: image: postgres:15-alpine container_name: openclaw-postgres environment: POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ${POSTGRES_DB} volumes: - postgres-data:/var/lib/postgresql/data - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro ports: - ${POSTGRES_PORT}:5432 healthcheck: test: [CMD-SHELL, pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}] interval: 10s timeout: 5s retries: 5 start_period: 40s # Redis 缓存服务 redis: image: redis:7-alpine container_name: openclaw-redis command: redis-server --appendonly yes --save 60 1 volumes: - redis-data:/data ports: - ${REDIS_PORT}:6379 healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 # Nacos 配置中心服务 nacos: image: nacos/nacos-server:v2.2.3 container_name: openclaw-nacos environment: MODE: standalone NACOS_AUTH_ENABLE: false NACOS_SERVER_IP: nacos SPRING_PROFILES_ACTIVE: ${OPENCLAW_BACKEND_PROFILE} JVM_XMS: 1g JVM_XMX: 1g volumes: - nacos-logs:/home/nacos/logs - ./nacos-cluster.conf:/home/nacos/conf/cluster.conf:ro ports: - ${NACOS_PORT}:8848 depends_on: postgres: condition: service_healthy healthcheck: test: [CMD, curl, -f, http://localhost:8848/nacos/v1/console/server/state] interval: 20s timeout: 10s retries: 5 start_period: 90s # OpenClaw Backend 主服务 openclaw-backend: image: openclaw/openclaw-backend:v1.2.0 container_name: openclaw-backend environment: SPRING_PROFILES_ACTIVE: ${OPENCLAW_BACKEND_PROFILE} SERVER_PORT: 8080 SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/openclaw SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER} SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD} SPRING_REDIS_HOST: redis SPRING_REDIS_PORT: 6379 NACOS_SERVER_ADDR: nacos:8848 OPENCLAW_LLM_PROVIDER_TYPE: mock OPENCLAW_LLM_MOCK_RESPONSE: {response:Mock response from OpenClaw} volumes: - backend-logs:/app/logs ports: - ${OPENCLAW_BACKEND_PORT}:8080 depends_on: nacos: condition: service_healthy postgres: condition: service_healthy redis: condition: service_healthy healthcheck: test: [CMD, curl, -f, http://localhost:8080/actuator/health] interval: 20s timeout: 10s retries: 5 start_period: 120s # OpenClaw UI 前端服务 openclaw-ui: image: openclaw/openclaw-ui:v1.2.0 container_name: openclaw-ui environment: VUE_APP_API_BASE_URL: http://localhost:${OPENCLAW_BACKEND_PORT} ports: - ${OPENCLAW_UI_PORT}:80 depends_on: openclaw-backend: condition: service_healthy volumes: postgres-data: redis-data: nacos-logs: backend-logs:这个文件的设计精髓在于健康检查的级联依赖postgres的健康检查等待 40 秒确保 DB 就绪nacos的健康检查等待 90 秒且依赖postgres就绪确保它能连上 DB 并完成初始化openclaw-backend的健康检查等待 120 秒且依赖nacos、postgres、redis全部就绪确保它能注册服务、连上数据库、使用缓存openclaw-ui不做健康检查但明确依赖openclaw-backend就绪确保它启动时后端 API 已可用。这种设计彻底规避了“容器启动顺序不确定”带来的随机失败。4.5 第五步执行部署见证奇迹发生的 5 分钟打开终端Windows 用 PowerShellmacOS/Linux 用 Terminalcd 到openclaw-local目录执行docker-compose up -d你会看到一系列Creating...、Starting...的输出。此时打开另一个终端窗口实时查看日志docker-compose logs -f openclaw-backend重点关注三类日志Started OpenclawBackendApplication in X.XXX seconds—— 表示 Backend 启动成功Nacos is starting...后跟Nacos started successfully—— 表示 Nacos 就绪Tomcat started on port(s): 8080 (http)—— 表示 Web 服务监听正常。整个过程从敲下回车到看到Started日志我的 M2 MacBook 实测为 3 分 12 秒一台 2018 款 i5 笔记本实测为 4 分 48 秒。5 分钟是一个保守但绝对可达的承诺。4.6 第六步登录与首次使用验证部署成果打开浏览器访问http://localhost:8081即OPENCLAW_UI_PORT。你应该看到 OpenClaw 的登录页面。默认账号密码是用户名admin密码admin123登录后你会进入 Dashboard。点击左侧菜单栏的Skills→Create Skill创建一个最简单的技能Name:Test Email ResponderDescription:A mock skill that replies to email queriesInput Schema: 粘贴以下 JSON定义输入字段{ type: object, properties: { email_subject: { type: string, description: The subject line of the incoming email }, email_body: { type: string, description: The full text content of the email } }, required: [email_subject, email_body] }Output Schema: 粘贴以下 JSON定义期望的输出结构{ type: object, properties: { reply_content: { type: string, description: The generated reply text }, priority: { type: string, enum: [low, medium, high], description: Suggested priority for this reply } }, required: [reply_content, priority] }LLM Provider: 保持Mock不变ClickSave.然后点击顶部的Try It按钮在弹出的测试面板中输入{ email_subject: Query about patent CN123456789A, email_body: Can you provide a summary and novelty analysis? }点击Run。几秒钟后你应该看到右侧返回{ reply_content: Mock response from OpenClaw, priority: medium }恭喜你已经拥有了一个可运行的 AI 员工。它现在还不会真写专利摘要但它已经具备了完整的 Skill 生命周期管理、Input/Output Schema 定义、Mock LLM 调用能力。下一步就是把OPENCLAW_LLM_PROVIDER_TYPE从mock换成dify把OPENCLAW_LLM_DIFY_API_KEY和OPENCLAW_LLM_DIFY_ENDPOINT填上它就能调用你自己的 Dify 实例了。5. 常见问题与排查技巧实录那些让你抓狂半小时的“小问题”其实都有固定解法在帮客户部署的过程中我整理了一份高频问题速查表。这些问题90% 都源于对 Docker 网络模型或 OpenClaw 内部通信机制的误解而非配置错误。问题现象根本原因排查命令快速修复方案docker-compose up后nacos容器日志显示ERROR Nacos failed to start且反复 restartNacos 尝试读取非空cluster.conf误判为集群模式docker exec -it openclaw-nacos cat /home/nacos/conf/cluster.conf确保./nacos-cluster.conf是 0 字节空文件或在 compose 中显式挂载:ro访问http://localhost:8081显示Cannot GET /或白屏UI 容器启动时Backend 尚未 Ready导致VUE_APP_API_BASE_URL指向的后端不可达docker-compose ps查看openclaw-ui状态是否为Updocker-compose logs openclaw-ui查看是否有Failed to fetch错误等待 2 分钟后刷新或执行docker-compose restart openclaw-ui强制重试登录后 Dashboard 空白浏览器控制台报GET http://localhost:8080/api/v1/dashboard/stats 500Backend 成功启动但无法连接 PostgreSQL常见于SPRING_DATASOURCE_URL中的 host 写成了localhost而非postgresdocker exec -it openclaw-backend ping -c 3 postgres检查docker-compose.yml中openclaw-backend的environment.SPRING_DATASOURCE_URLhost 必须是服务名postgres不是localhost创建 Skill 后点击Try It按钮一直转圈无响应Mock LLM Provider 的响应 JSON 格式不符合 Output Schema 定义docker-compose logs openclaw-backend | grep MockLLMProvider检查OPENCLAW_LLM_MOCK_RESPONSE环境变量中的 JSON确保其结构与你在 UI 中定义的 Output Schema 完全一致包括字段名、类型、嵌套层级docker-compose down后重新up提示FATAL: database openclaw does not existPostgreSQL 数据卷postgres-data中残留了旧数据但init.sql只在首次启动时执行docker volume ls | grep postgres执行docker volume rm openclawlocal_postgres-data注意 volume 名是 compose 自动生成的然后重新up除了表格里的问题还有几个独家经验分享关于端口冲突如果你的电脑上已经运行了 PostgreSQL比如通过 brew install 安装的那么POSTGRES_PORT5432就会冲突。解决方案不是改 OpenClaw 的端口而是改宿主机的端口映射把.env中的POSTGRES_PORT5432改成POSTGRES_PORT5433然后访问http://localhost:8081时OpenClaw UI 依然能通过内部服务名postgres:5432连接数据库完全不受影响。这是 Docker 网络隔离带来的巨大便利。关于日志调试当某个服务启动失败时不要只看docker-compose logs service。更高效的方法是进入容器内部直接模拟启动命令# 进入 nacos 容器 docker exec -it openclaw-nacos /bin/bash # 手动执行启动脚本官方镜像的入口 sh /home/nacos/bin/start.sh -m standalone这样能看到最原始的 JVM 启动日志比 Docker 的封装日志更详细。关于性能瓶颈OpenClaw 的 all-in-one 镜像对 CPU 要求不高但对磁盘 I/O 敏感。如果你的笔记本是机械硬盘HDDpostgres的start_period: 40s可能不够建议调高到60s。SSD 用户则完全无需担心。关于卸载网络热词里有openclaw卸载其实非常简单。只需两步docker-compose down -v-v参数会一并删除所有关联的数据卷删除整个openclaw-local文件夹。 这样你的系统就干净如初没有任何残留。最后再分享一个小技巧如果你想在部署完成后立刻用 curl 测试 Backend 的健康接口可以执行curl -s http://localhost:8080/actuator/health \| jq .如果返回{status:UP}说明整个链路完全通畅。这个命令我写进了公司的 CI/CD 流水线作为每次部署后的自动验收步骤。它比人工点开浏览器更快、更可靠。我在实际使用中发现OpenClaw 最大的价值不在于它能调用多大的模型而在于它把 AI Agent 的抽象概念转化成了产品经理能看懂的“Skill”、研发能实现的“Schema”、运维能部署的“Docker 镜像”。它不是一个黑盒而是一套清晰的契约。当你第一次看到 Mock 响应成功返回时那种“原来 AI 员工真的可以这么简单”的感觉就是技术回归本质的时刻。