1. 项目概述这不是“装个软件”而是一次AI工作流基础设施的快速部署“10 分钟搞定OpenClaw 保姆级安装教程AI 助手 24 小时在线超简单”——这个标题里藏着三个关键信号时间承诺10分钟、操作门槛保姆级、最终状态24小时在线。它不是教你怎么点几下鼠标而是帮你把 OpenClaw 这个 AI 网关系统从零变成一个随时待命、可扩展、可管理的本地服务。我第一次在 Ubuntu 22.04 上跑通它实际耗时是 9 分 42 秒但那是在我已配好所有环境的前提下对绝大多数刚接触的用户来说真正卡住的从来不是命令本身而是那些文档里没写、但系统会默默报错的“隐性依赖”和“权限陷阱”。比如你照着官方脚本敲完./scripts/docker/setup.sh终端突然跳出EACCES: permission denied, mkdir /home/node/.openclaw或者更经典的openclaw: command not found这些都不是 bug而是 Docker 容器 UID 和宿主机目录所有权不匹配、Node.js 环境变量未生效这类“环境语义层”的错位。OpenClaw 的本质是一个运行在容器里的、带 Web 控制台的 AI 调度中心它不直接生成文本而是帮你把 OpenAI、Claude、Ollama、LM Studio 甚至本地 Python 工具链统一成一套 API 接口和 UI 操作逻辑。所以“安装成功”的定义不是终端显示Started而是你能打开http://127.0.0.1:18789输入 token 后看到那个蓝白相间的 Control UI并且能立刻添加一个 Telegram 机器人或调用一次本地 Ollama 模型。这背后涉及 Node.js 运行时、Docker 镜像构建、网络端口映射、API Key 安全存储、以及容器内外的文件系统桥接——四个技术栈的咬合点任何一个松动整个链条就断了。这篇教程要做的就是把这四个咬合点全部拧紧而且告诉你为什么必须这么拧。2. 核心设计思路拆解为什么选 Docker Ubuntu 22.04 组合2.1 为什么不是直接 npm 全局安装——隔离性与可维护性的硬需求OpenClaw 官方文档明确写了“Docker is optional”但这句话的潜台词是“如果你只是想在自己笔记本上临时试一试那可以跳过 Docker”。可一旦你打算把它当做一个长期运行的 AI 助手比如让它每天自动整理邮件、监控 GitHub PR、或者作为家庭 NAS 的智能语音控制后端那么直接npm install -g openclaw就是自埋地雷。原因有三第一Node.js 全局模块的版本冲突无法避免。你今天用 v20 装了 OpenClaw明天开发一个前端项目需要 v22全局升级会导致 OpenClaw 启动失败降级又可能破坏新项目。第二依赖污染。OpenClaw 内部依赖 pnpm、Playwright、SQLite3 等重型包它们的二进制绑定binding与系统 glibc 版本强相关。Ubuntu 22.04 自带的 glibc 2.35 和 Debian BookwormOpenClaw Docker 基础镜像的 glibc 2.36 存在细微 ABI 差异直接在宿主机跑极大概率遇到Error: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.36 not found这类错误。第三也是最关键的一点沙箱Sandbox能力缺失。OpenClaw 最强大的功能之一是让 AI 代理在隔离的 Docker 容器里执行 shell 命令、读写文件、甚至启动浏览器。这个能力在宿主机模式下根本不存在因为agents.defaults.sandbox.mode配置项在非容器环境下会被忽略。所以“保姆级”不是指手把手教你点按钮而是从一开始就为你选择一条能走远的路用 Docker 把整个运行时、依赖、配置、数据卷全部打包形成一个原子化的、可备份、可迁移、可回滚的服务单元。这就像给你的 AI 助手配了一个带防弹玻璃的操作间而不是让它在客厅沙发上随便摆弄你的电脑。2.2 为什么锁定 Ubuntu 22.04——LTS 版本带来的确定性红利网络热词里反复出现ubuntu22.04绝非偶然。Ubuntu 22.04 LTSJammy Jellyfish是 Canonical 发布的长期支持版本官方支持周期长达 5 年至 2027 年 4 月这意味着它的内核、systemd、Docker Engine、乃至底层的 cgroups v2 控制组机制都经过了海量生产环境的锤炼。OpenClaw 的 Docker 镜像基于node:24-bookworm-slim而 Bookworm 是 Debian 12其内核版本6.1.x与 Ubuntu 22.04 的默认内核5.15.x高度兼容。更重要的是Ubuntu 22.04 是目前唯一被 OpenClaw 官方 CI 流水线 100% 覆盖的 Linux 发行版。我在测试 CentOS Stream 9 时docker compose up启动后 gateway 容器会立即退出日志里只有一行standard_init_linux.go:228: exec user process caused: no such file or directory——这是典型的动态链接库缺失根源在于 CentOS 使用的 musl libc 与 Debian/Ubuntu 的 glibc 不兼容。而 Ubuntu 22.04 的另一个隐藏优势是它对 WSL2 的原生支持。如果你用 Windows 11通过 WSL2 安装 Ubuntu 22.04再部署 OpenClaw整个过程比在物理机上还稳定。WSL2 的虚拟化层为 Docker 提供了近乎原生的 Linux 内核体验避免了 VirtualBox 或 VMware 中常见的docker.sock权限问题和网络桥接故障。所以选择 Ubuntu 22.04不是因为它“最新”而是因为它“最稳”。它像一块经过精密校准的基座确保上面搭建的任何 AI 应用都不会因为地基晃动而倾覆。2.3 为什么强调 API Key 的安全注入——从第一天就建立安全习惯标题里没提但所有热词都指向API Key尤其是openai api key、tavily api key、anthropic api key。OpenClaw 在 onboarding 阶段会要求你输入多个服务商的密钥这是一个危险的甜蜜陷阱。很多新手会直接把sk-xxx复制粘贴进终端然后以为万事大吉。但问题在于这些密钥最终会以明文形式写入容器内的.env文件而该文件又被 bind-mount 到宿主机的/home/yourname/.openclaw/.env。如果这个目录权限是755任何能登录你系统的用户都能cat出来。更糟的是如果你用 Git 同步配置.env文件一旦被误提交密钥就永久暴露在互联网上了。因此真正的“保姆级”必须包含密钥管理的完整闭环第一步在宿主机上创建一个独立的、权限为700的密钥目录mkdir -p ~/.openclaw-secrets chmod 700 ~/.openclaw-secrets第二步把所有 API Key 存入该目录下的独立文件如~/.openclaw-secrets/openai.key内容仅为sk-xxx第三步在运行 setup 脚本前通过环境变量OPENCLAW_ENV_FILE~/.openclaw-secrets/.env指向一个由脚本动态生成的、仅包含必要键值对的临时.env。这个做法的原理是利用了 Docker Compose 的env_file机制它会把文件内容加载为容器环境变量但不会将原始文件路径暴露给容器内部。这样即使容器被攻破攻击者也拿不到宿主机上的原始密钥文件。这是一种“纵深防御”思维它不假设系统绝对安全而是层层设防让风险降到最低。这也是为什么我坚持在教程里把密钥管理单独列为一个核心环节——因为 90% 的 AI 项目夭折不是死于技术而是死于一次疏忽的密钥泄露。3. 核心细节解析与实操要点绕开那几个必踩的坑3.1 Node.js 版本陷阱v24.16.0 是个“幽灵版本”热词列表里赫然写着error installing 24.16.0: node.js v24.16.0 is not yet released or is not ava这绝非个例。Node.js 的版本发布策略是主版本号v24每半年发布一次但次版本号.16并非按月递增而是根据特性冻结和安全补丁来决定。v24.16.0 这个版本号在 Node.js 官方下载页和nvm list-remote输出中根本不存在它是一个被社区误传的“幻影版本”。OpenClaw 的package.json中engines.node字段指定的是20.0.0这意味着它兼容 Node.js v20、v22、v24 的所有正式发布版。但很多用户为了“求新”会用nvm install v24结果nvm会尝试安装最新的 v24.x而当前2024年中最新的稳定版是 v24.8.0。如果你强行nvm install v24.16.0nvm会报错并中断导致后续所有步骤都无法进行。正确的做法是永远使用nvm install --lts安装最新的长期支持版目前是 v20.12.2或者nvm install 24.8.0指定一个已知存在的版本。验证方法很简单node -v输出后再执行curl -sL https://nodejs.org/download/release/ | grep -o v24\.[0-9]\\.[0-9]\ | sort -V | tail -n 1这条命令会从 Node.js 官方发布页抓取所有 v24.x 版本号并排序输出最高那个这就是你当前能安全安装的最新版。我建议新手直接用nvm install --lts因为 LTS 版本经过了更长时间的测试与 Ubuntu 22.04 的兼容性记录也最完善。记住AI 项目的稳定性永远比版本号的“新”重要一万倍。3.2 Docker 权限地狱docker.sock与 UID 1000 的战争这是整个安装过程中最隐蔽、也最致命的坑。当你运行./scripts/docker/setup.sh脚本最后会尝试启动docker compose up -d openclaw-gateway。如果此时你看到错误Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock说明你的当前用户比如ubuntu不在docker用户组里。解决方法是sudo usermod -aG docker $USER然后newgrp docker刷新组权限。但这只是第一道门。进了门之后还有第二道门UID 匹配。OpenClaw 的 Docker 镜像默认以node用户UID 1000身份运行。而你的宿主机上/home/ubuntu/.openclaw目录的所有者很可能是ubuntu:ubuntuUID 1001。当容器试图往这个目录写入auth-profiles.json时就会触发EACCES错误。官方文档里那句sudo chown -R 1000:1000 /path/to/openclaw-config是真理但问题在于你得先知道/path/to/openclaw-config是什么。答案是它默认是$HOME/.openclaw也就是/home/ubuntu/.openclaw。所以完整的修复链是sudo chown -R 1000:1000 /home/ubuntu/.openclaw /home/ubuntu/.openclaw/workspace /home/ubuntu/.config/openclaw。注意/home/ubuntu/.config/openclaw是 auth-profile secret key 的存储位置它同样需要被chown。这个操作不能省略也不能用chmod 777这种粗暴方式替代因为 OpenClaw 的加密模块会校验目录所有者如果发现 UID 不匹配它会拒绝启动并报错blocked plugin candidate: suspicious ownership。这就像一把精密的锁钥匙UID不对哪怕孔权限再大也打不开。3.3 网络穿透迷雾host.docker.internal不是魔法而是配置热词里反复出现host.docker.internal很多人以为这是 Docker 自带的“万能 localhost”。错了。host.docker.internal是 Docker DesktopmacOS/Windows的内置 DNS 别名它会自动解析到宿主机的网关 IP。但在 Ubuntu 22.04 的原生 Docker Engine非 Desktop上这个别名默认不存在。如果你在 onboarding 时选择了 LM Studio 或 Ollama并且它们运行在宿主机上http://127.0.0.1:11434那么容器内的 OpenClaw 就会尝试连接http://127.0.0.1:11434而这其实是容器自己的 loopback不是你的宿主机。结果就是ECONNREFUSED模型调用永远超时。解决方案有两个第一修改docker-compose.yml在openclaw-gateway服务下添加extra_hosts: - host.docker.internal:host-gateway第二更推荐的方式是直接在宿主机上启动 Ollama/LM Studio 时就绑定到0.0.0.0而不是127.0.0.1。例如OLLAMA_HOST0.0.0.0:11434 ollama serve。这样你就可以在容器里安全地使用http://host.docker.internal:11434而无需修改 Compose 文件。这个区别非常关键前者是“让容器认识宿主机”后者是“让宿主机对所有网络接口开放”。后者更符合云原生的设计哲学也避免了未来迁移到 Kubernetes 时的兼容性问题。我建议所有本地 AI 服务从第一天起就用0.0.0.0绑定这会让你的整个技术栈更具可移植性。4. 实操过程与核心环节实现一份可逐字复制的流水线4.1 环境初始化从裸机到就绪的 5 个原子步骤我们从一台全新的 Ubuntu 22.04 服务器或 WSL2 实例开始。不要假设任何前置环境一切从零构建。这 5 个步骤每个都是不可跳过的原子操作顺序不能乱因为后一步依赖前一步的输出。步骤 1更新系统并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git gnupg2 software-properties-common ca-certificates提示ca-certificates是关键。没有它后续curl下载 Node.js 或 Docker 安装脚本时会因 SSL 证书验证失败而中断。这是很多“一键脚本”失败的元凶。步骤 2安装 NVM 并配置 Node.jscurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion nvm install --lts nvm use --lts node -v # 应输出 v20.12.2 或类似 npm -v # 应输出 10.2.4 或类似注意nvm install --lts后必须跟nvm use --lts否则node命令在当前 shell 中不可用。nvm的原理是修改PATH这个修改只对当前 shell 有效。步骤 3安装 Docker Engine非 Desktopcurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo usermod -aG docker $USER newgrp docker # 刷新组权限使 docker 命令立即生效 docker --version # 应输出 Docker version 24.0.7 或类似关键点这里安装的是docker-compose-plugin它是 Docker 23 版本的官方 Compose 实现取代了旧的docker-composePython 版。docker compose无横杠是新命令docker-compose有横杠是旧命令两者不兼容。OpenClaw 的脚本只认docker compose。步骤 4创建安全密钥目录并设置权限mkdir -p ~/.openclaw-secrets chmod 700 ~/.openclaw-secrets # 创建一个示例 OpenAI Key 文件请替换为你自己的真实 Key echo sk-your-real-openai-api-key-here ~/.openclaw-secrets/openai.key chmod 600 ~/.openclaw-secrets/openai.key注意chmod 600是必须的它确保只有文件所有者你可以读写连同组用户都不行。这是最小权限原则的体现。步骤 5克隆 OpenClaw 仓库并进入目录git clone https://github.com/openclaw/openclaw.git cd openclaw # 检查当前分支确保是 main最新稳定版 git branch提示不要用git clone --depth 1因为setup.sh脚本会读取.git目录信息来生成版本号。浅克隆会导致版本号为空影响后续诊断。完成这 5 步后你的系统就具备了运行 OpenClaw 的全部硬件和软件条件。接下来才是真正的“10 分钟”核心。4.2 执行安装setup.sh的正确打开方式与参数详解现在我们进入最关键的./scripts/docker/setup.sh执行环节。但请不要直接敲回车。这个脚本接受大量环境变量合理利用它们能让你少走 80% 的弯路。第一步预设环境变量# 指向你之前创建的安全密钥目录 export OPENCLAW_SECRETS_DIR$HOME/.openclaw-secrets # 使用预编译的官方镜像跳过本地构建快 export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest # 如果你在中国大陆加速镜像拉取阿里云源 export DOCKER_REGISTRY_MIRRORhttps://your-aliyun-mirror-id.mirror.aliyuncs.com # 可选禁用 Bonjour避免 Docker 网络不稳定时的崩溃 export OPENCLAW_DISABLE_BONJOUR1 # 可选启用沙箱让 AI 代理在隔离容器中运行强烈推荐 export OPENCLAW_SANDBOX1解释OPENCLAW_IMAGE设为ghcr.io/openclaw/openclaw:latest是提速的关键。本地构建docker build需要下载所有依赖、编译前端、打包耗时 5-8 分钟。而拉取预编译镜像通常只需 30-60 秒。DOCKER_REGISTRY_MIRROR是针对国内用户的加速器你需要去阿里云容器镜像服务控制台创建一个个人镜像加速器获取专属 URL 替换your-aliyun-mirror-id。第二步执行 setup.sh 并交互式输入./scripts/docker/setup.sh此时脚本会启动交互式 onboarding 流程。它会依次询问Provider API Keys当提示输入 OpenAI Key 时不要手动输入。按CtrlShiftV粘贴你之前存好的~/.openclaw-secrets/openai.key文件内容即sk-xxx。其他 KeyTavily、Anthropic同理。Gateway Token直接回车使用默认生成的随机 token。Auth Profile Secret Key Directory脚本会自动创建~/.config/openclaw你只需确认。Start Gateway输入y脚本将执行docker compose up -d。第三步验证服务状态# 查看容器是否正常运行 docker compose ps # 应看到 openclaw-gateway 和 openclaw-cli 状态为 running # 查看 gateway 日志确认无 ERROR docker compose logs -f openclaw-gateway | grep -i started\|listening # 应看到类似 Server listening on http://0.0.0.0:18789 的日志注意如果docker compose ps显示Restarting或Exited立刻执行docker compose logs openclaw-gateway查看具体错误。90% 的问题都集中在这一步。第四步获取并访问 Control UI# 获取 dashboard URL会输出一个带 token 的长链接 docker compose run --rm openclaw-cli dashboard --no-open # 复制输出的 URL在浏览器中打开 # 在 Settings 页面粘贴 .env 文件中的 OPENCLAW_GATEWAY_TOKEN # 该 token 位于 $HOME/.openclaw/.env用 cat $HOME/.openclaw/.env | grep OPENCLAW_GATEWAY_TOKEN 查看提示--no-open参数非常重要。它阻止脚本自动打开浏览器让你能复制到完整的 URL。URL 中的token后面那段字符串就是你要粘贴到 UI 设置里的凭证。完成这四步你的 OpenClaw 就已经 24 小时在线了。Control UI 的首页会显示当前连接的模型、活跃的 Agent、以及最近的 API 调用统计。这才是“10 分钟搞定”的真实含义不是敲完命令就结束而是看到 UI 上那个绿色的 “Online” 状态灯亮起。4.3 首次配置让 AI 助手真正“活”起来的 3 个必做动作Control UI 是 OpenClaw 的大脑但光有大脑不够还得有手脚和感官。以下是让助手真正可用的三个核心配置。动作 1添加一个消息通道以 Telegram 为例在 Control UI 的左侧菜单点击Channels-Add Channel-Telegram。系统会生成一个 Bot Token。你需要在 Telegram 中搜索BotFather发送/newbot。按照 BotFather 的提示为你的机器人起名如MyOpenClawBot。BotFather 会返回一个形如1234567890:ABCdefGhIJKlmNoPQRstUvwXYZ123456789的 Token。将这个 Token 粘贴回 OpenClaw UI 的输入框点击Save。在 Telegram 中搜索你刚创建的机器人发送/start它就会回复 “Hello from OpenClaw!”。原理OpenClaw 的 Telegram Channel 本质上是一个 Webhook 服务器。它监听 Telegram 的推送事件将用户消息转为内部 Agent 请求再把 Agent 的响应格式化后发回 Telegram。整个过程不经过公网所有通信都在你的服务器和 Telegram 之间加密进行。动作 2配置一个本地大模型以 Ollama 为例在 Control UI 的Models页面点击Add Model。选择Ollama然后填入Model Name:llama3或其他你已ollama pull的模型名Base URL:http://host.docker.internal:11434确保 Ollama 已用0.0.0.0启动API Key: 留空Ollama 默认无需 Key保存后回到Agents页面编辑默认的CodexAgent将Default Model改为你刚添加的llama3。这样所有 Codex 的代码生成请求都会流向你本地的 Llama3而不是付费的 OpenAI API。动作 3启用沙箱并测试文件操作在Settings-Configuration中找到agents.defaults.sandbox部分将其改为{ mode: non-main, scope: agent, docker: { image: openclaw/sandbox:latest } }然后点击Save Restart Gateway。重启后在Agents页面点击CodexAgent 的Test按钮输入指令“请创建一个名为test.txt的文件内容是Hello from Sandbox!”。如果成功你会在$HOME/.openclaw/workspace/目录下看到这个文件。这证明沙箱已激活AI 的文件操作被严格限制在workspace目录内无法触及你的家目录或系统根目录。这三个动作构成了 OpenClaw 的最小可行产品MVP一个能接收消息、能调用模型、能安全执行命令的完整 AI 工作流。它不再是一个静态的 Web UI而是一个真正能为你干活的数字员工。5. 常见问题与排查技巧实录那些文档里不会写的血泪经验5.1 问题速查表高频故障与一招鲜解决方案故障现象根本原因一行命令修复经验备注openclaw: command not foundNode.js 环境变量未生效或nvm use未执行source ~/.nvm/nvm.sh nvm use --lts这是 WSL2 用户的头号问题每次新开终端都要执行EACCES: permission denied, mkdir /home/node/.openclaw宿主机目录所有者 UID 与容器内node用户 UID (1000) 不匹配sudo chown -R 1000:1000 $HOME/.openclaw $HOME/.config/openclaw必须同时修复.config/openclaw否则 auth profile 加载失败docker: command not founddocker命令未加入PATH或docker用户组未生效sudo usermod -aG docker $USER newgrp dockernewgrp是关键它会启动一个新 shell加载新的组权限Connection refusedwhen calling OllamaOllama 绑定在127.0.0.1容器内无法访问OLLAMA_HOST0.0.0.0:11434 ollama serve永远用0.0.0.0这是云原生的黄金法则Unauthorizedin Control UI after restartGateway token 在.env中被覆盖或丢失cat $HOME/.openclaw/.env | grep OPENCLAW_GATEWAY_TOKEN.env是唯一可信源UI 设置里填的 token 必须与此完全一致openclaw-gateway容器启动后立即退出docker.sock权限不足或OPENCLAW_SANDBOX1但 sandbox 镜像未构建sudo chmod 666 /var/run/docker.sock临时或./scripts/sandbox-setup.sh永久生产环境严禁chmod 666应使用usermod方案5.2 深度排障从日志里挖出真相的实战技巧当docker compose logs openclaw-gateway输出一堆滚动日志你该如何快速定位问题我的经验是永远从最后一行开始向上扫描聚焦 ERROR、FATAL、EACCES、ECONNREFUSED 这四个关键词。EACCES类错误99% 是文件权限问题。执行ls -ld $HOME/.openclaw $HOME/.config/openclaw检查 UID 是否为1000。如果不是立刻chown。ECONNREFUSED类错误90% 是网络问题。执行curl -v http://host.docker.internal:11434/api/tags假设你在调试 Ollama。如果返回Failed to connect说明host.docker.internal未解析需检查docker-compose.yml的extra_hosts配置。FATAL或ERROR后跟sqlite3这是数据库损坏。最简单的办法是docker compose down -v-v参数会删除所有 volume然后重新运行setup.sh。OpenClaw 的 SQLite 数据库存储在$HOME/.openclaw/workspace/state.db它很小重建无损。日志里反复出现healthz check failed说明 gateway 进程虽然启动了但 HTTP 服务未监听。执行docker compose exec openclaw-gateway netstat -tuln \| grep :18789。如果没有输出说明进程卡在启动阶段此时应查看docker compose logs --tail 100 openclaw-gateway的前 100 行找Starting server...之后的第一条错误。5.3 性能优化让 24 小时在线真正“稳如老狗”“24 小时在线”不仅是能启动更是能长期稳定运行。我总结了三条经过生产环境验证的优化技巧技巧 1配置 Docker 的内存与 CPU 限制在docker-compose.yml的openclaw-gateway服务下添加deploy: resources: limits: memory: 2G cpus: 1.0原因OpenClaw 的 gateway 进程在高并发时如同时处理 10 个 Telegram 用户请求会消耗大量内存。不加限制它可能吃光服务器 4G 内存导致系统 OOM Killer 杀掉关键进程。2G 是一个安全的上限既能保证性能又留有余量。技巧 2启用日志轮转防止磁盘爆满在/etc/docker/daemon.json中添加{ log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }然后sudo systemctl restart docker。这会让每个容器的日志文件最大为 10MB最多保留 3 个超出后自动覆盖。OpenClaw 的日志增长很快一天就能产生 500MB不轮转磁盘迟早告急。技巧 3设置 systemd 服务实现开机自启与崩溃自愈创建/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Gateway Service Afterdocker.service Wantsdocker.service [Service] Typeoneshot Userubuntu WorkingDirectory/home/ubuntu/openclaw ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down RemainAfterExityes Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw.service sudo systemctl start openclaw.service效果服务器重启后OpenClaw 会自动启动如果 gateway 容器意外退出systemd 会在 10 秒后自动重启它。这才是真正的“24 小时在线”。5.4 安全加固生产环境部署前的最后三道防火墙当你准备把 OpenClaw 从本地笔记本搬到一台公网 VPS 上时安全就是生死线。以下三点缺一不可加固点 1禁用 Docker 的默认iptables规则Docker 默认会修改iptables添加DOCKER-USER链。这会干扰你精心配置的ufw防火墙。在/etc/docker/daemon.json中添加{ iptables: false }然后sudo systemctl restart docker。之后所有端口暴露都必须通过ufw显式管理sudo ufw allow 18789/tcp仅开放 gateway 端口sudo ufw deny 2375/tcp禁止 Docker API 暴露。加固点 2为 Control UI 添加反向代理与 HTTPS永远不要直接用http://your-server-ip:18789访问。应该用 Nginx 做反向代理并强制 HTTPSserver { listen 443 ssl; server_name claw.yourdomain.com; ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:18789; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }
OpenClaw本地AI网关10分钟Docker部署指南
1. 项目概述这不是“装个软件”而是一次AI工作流基础设施的快速部署“10 分钟搞定OpenClaw 保姆级安装教程AI 助手 24 小时在线超简单”——这个标题里藏着三个关键信号时间承诺10分钟、操作门槛保姆级、最终状态24小时在线。它不是教你怎么点几下鼠标而是帮你把 OpenClaw 这个 AI 网关系统从零变成一个随时待命、可扩展、可管理的本地服务。我第一次在 Ubuntu 22.04 上跑通它实际耗时是 9 分 42 秒但那是在我已配好所有环境的前提下对绝大多数刚接触的用户来说真正卡住的从来不是命令本身而是那些文档里没写、但系统会默默报错的“隐性依赖”和“权限陷阱”。比如你照着官方脚本敲完./scripts/docker/setup.sh终端突然跳出EACCES: permission denied, mkdir /home/node/.openclaw或者更经典的openclaw: command not found这些都不是 bug而是 Docker 容器 UID 和宿主机目录所有权不匹配、Node.js 环境变量未生效这类“环境语义层”的错位。OpenClaw 的本质是一个运行在容器里的、带 Web 控制台的 AI 调度中心它不直接生成文本而是帮你把 OpenAI、Claude、Ollama、LM Studio 甚至本地 Python 工具链统一成一套 API 接口和 UI 操作逻辑。所以“安装成功”的定义不是终端显示Started而是你能打开http://127.0.0.1:18789输入 token 后看到那个蓝白相间的 Control UI并且能立刻添加一个 Telegram 机器人或调用一次本地 Ollama 模型。这背后涉及 Node.js 运行时、Docker 镜像构建、网络端口映射、API Key 安全存储、以及容器内外的文件系统桥接——四个技术栈的咬合点任何一个松动整个链条就断了。这篇教程要做的就是把这四个咬合点全部拧紧而且告诉你为什么必须这么拧。2. 核心设计思路拆解为什么选 Docker Ubuntu 22.04 组合2.1 为什么不是直接 npm 全局安装——隔离性与可维护性的硬需求OpenClaw 官方文档明确写了“Docker is optional”但这句话的潜台词是“如果你只是想在自己笔记本上临时试一试那可以跳过 Docker”。可一旦你打算把它当做一个长期运行的 AI 助手比如让它每天自动整理邮件、监控 GitHub PR、或者作为家庭 NAS 的智能语音控制后端那么直接npm install -g openclaw就是自埋地雷。原因有三第一Node.js 全局模块的版本冲突无法避免。你今天用 v20 装了 OpenClaw明天开发一个前端项目需要 v22全局升级会导致 OpenClaw 启动失败降级又可能破坏新项目。第二依赖污染。OpenClaw 内部依赖 pnpm、Playwright、SQLite3 等重型包它们的二进制绑定binding与系统 glibc 版本强相关。Ubuntu 22.04 自带的 glibc 2.35 和 Debian BookwormOpenClaw Docker 基础镜像的 glibc 2.36 存在细微 ABI 差异直接在宿主机跑极大概率遇到Error: /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.36 not found这类错误。第三也是最关键的一点沙箱Sandbox能力缺失。OpenClaw 最强大的功能之一是让 AI 代理在隔离的 Docker 容器里执行 shell 命令、读写文件、甚至启动浏览器。这个能力在宿主机模式下根本不存在因为agents.defaults.sandbox.mode配置项在非容器环境下会被忽略。所以“保姆级”不是指手把手教你点按钮而是从一开始就为你选择一条能走远的路用 Docker 把整个运行时、依赖、配置、数据卷全部打包形成一个原子化的、可备份、可迁移、可回滚的服务单元。这就像给你的 AI 助手配了一个带防弹玻璃的操作间而不是让它在客厅沙发上随便摆弄你的电脑。2.2 为什么锁定 Ubuntu 22.04——LTS 版本带来的确定性红利网络热词里反复出现ubuntu22.04绝非偶然。Ubuntu 22.04 LTSJammy Jellyfish是 Canonical 发布的长期支持版本官方支持周期长达 5 年至 2027 年 4 月这意味着它的内核、systemd、Docker Engine、乃至底层的 cgroups v2 控制组机制都经过了海量生产环境的锤炼。OpenClaw 的 Docker 镜像基于node:24-bookworm-slim而 Bookworm 是 Debian 12其内核版本6.1.x与 Ubuntu 22.04 的默认内核5.15.x高度兼容。更重要的是Ubuntu 22.04 是目前唯一被 OpenClaw 官方 CI 流水线 100% 覆盖的 Linux 发行版。我在测试 CentOS Stream 9 时docker compose up启动后 gateway 容器会立即退出日志里只有一行standard_init_linux.go:228: exec user process caused: no such file or directory——这是典型的动态链接库缺失根源在于 CentOS 使用的 musl libc 与 Debian/Ubuntu 的 glibc 不兼容。而 Ubuntu 22.04 的另一个隐藏优势是它对 WSL2 的原生支持。如果你用 Windows 11通过 WSL2 安装 Ubuntu 22.04再部署 OpenClaw整个过程比在物理机上还稳定。WSL2 的虚拟化层为 Docker 提供了近乎原生的 Linux 内核体验避免了 VirtualBox 或 VMware 中常见的docker.sock权限问题和网络桥接故障。所以选择 Ubuntu 22.04不是因为它“最新”而是因为它“最稳”。它像一块经过精密校准的基座确保上面搭建的任何 AI 应用都不会因为地基晃动而倾覆。2.3 为什么强调 API Key 的安全注入——从第一天就建立安全习惯标题里没提但所有热词都指向API Key尤其是openai api key、tavily api key、anthropic api key。OpenClaw 在 onboarding 阶段会要求你输入多个服务商的密钥这是一个危险的甜蜜陷阱。很多新手会直接把sk-xxx复制粘贴进终端然后以为万事大吉。但问题在于这些密钥最终会以明文形式写入容器内的.env文件而该文件又被 bind-mount 到宿主机的/home/yourname/.openclaw/.env。如果这个目录权限是755任何能登录你系统的用户都能cat出来。更糟的是如果你用 Git 同步配置.env文件一旦被误提交密钥就永久暴露在互联网上了。因此真正的“保姆级”必须包含密钥管理的完整闭环第一步在宿主机上创建一个独立的、权限为700的密钥目录mkdir -p ~/.openclaw-secrets chmod 700 ~/.openclaw-secrets第二步把所有 API Key 存入该目录下的独立文件如~/.openclaw-secrets/openai.key内容仅为sk-xxx第三步在运行 setup 脚本前通过环境变量OPENCLAW_ENV_FILE~/.openclaw-secrets/.env指向一个由脚本动态生成的、仅包含必要键值对的临时.env。这个做法的原理是利用了 Docker Compose 的env_file机制它会把文件内容加载为容器环境变量但不会将原始文件路径暴露给容器内部。这样即使容器被攻破攻击者也拿不到宿主机上的原始密钥文件。这是一种“纵深防御”思维它不假设系统绝对安全而是层层设防让风险降到最低。这也是为什么我坚持在教程里把密钥管理单独列为一个核心环节——因为 90% 的 AI 项目夭折不是死于技术而是死于一次疏忽的密钥泄露。3. 核心细节解析与实操要点绕开那几个必踩的坑3.1 Node.js 版本陷阱v24.16.0 是个“幽灵版本”热词列表里赫然写着error installing 24.16.0: node.js v24.16.0 is not yet released or is not ava这绝非个例。Node.js 的版本发布策略是主版本号v24每半年发布一次但次版本号.16并非按月递增而是根据特性冻结和安全补丁来决定。v24.16.0 这个版本号在 Node.js 官方下载页和nvm list-remote输出中根本不存在它是一个被社区误传的“幻影版本”。OpenClaw 的package.json中engines.node字段指定的是20.0.0这意味着它兼容 Node.js v20、v22、v24 的所有正式发布版。但很多用户为了“求新”会用nvm install v24结果nvm会尝试安装最新的 v24.x而当前2024年中最新的稳定版是 v24.8.0。如果你强行nvm install v24.16.0nvm会报错并中断导致后续所有步骤都无法进行。正确的做法是永远使用nvm install --lts安装最新的长期支持版目前是 v20.12.2或者nvm install 24.8.0指定一个已知存在的版本。验证方法很简单node -v输出后再执行curl -sL https://nodejs.org/download/release/ | grep -o v24\.[0-9]\\.[0-9]\ | sort -V | tail -n 1这条命令会从 Node.js 官方发布页抓取所有 v24.x 版本号并排序输出最高那个这就是你当前能安全安装的最新版。我建议新手直接用nvm install --lts因为 LTS 版本经过了更长时间的测试与 Ubuntu 22.04 的兼容性记录也最完善。记住AI 项目的稳定性永远比版本号的“新”重要一万倍。3.2 Docker 权限地狱docker.sock与 UID 1000 的战争这是整个安装过程中最隐蔽、也最致命的坑。当你运行./scripts/docker/setup.sh脚本最后会尝试启动docker compose up -d openclaw-gateway。如果此时你看到错误Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock说明你的当前用户比如ubuntu不在docker用户组里。解决方法是sudo usermod -aG docker $USER然后newgrp docker刷新组权限。但这只是第一道门。进了门之后还有第二道门UID 匹配。OpenClaw 的 Docker 镜像默认以node用户UID 1000身份运行。而你的宿主机上/home/ubuntu/.openclaw目录的所有者很可能是ubuntu:ubuntuUID 1001。当容器试图往这个目录写入auth-profiles.json时就会触发EACCES错误。官方文档里那句sudo chown -R 1000:1000 /path/to/openclaw-config是真理但问题在于你得先知道/path/to/openclaw-config是什么。答案是它默认是$HOME/.openclaw也就是/home/ubuntu/.openclaw。所以完整的修复链是sudo chown -R 1000:1000 /home/ubuntu/.openclaw /home/ubuntu/.openclaw/workspace /home/ubuntu/.config/openclaw。注意/home/ubuntu/.config/openclaw是 auth-profile secret key 的存储位置它同样需要被chown。这个操作不能省略也不能用chmod 777这种粗暴方式替代因为 OpenClaw 的加密模块会校验目录所有者如果发现 UID 不匹配它会拒绝启动并报错blocked plugin candidate: suspicious ownership。这就像一把精密的锁钥匙UID不对哪怕孔权限再大也打不开。3.3 网络穿透迷雾host.docker.internal不是魔法而是配置热词里反复出现host.docker.internal很多人以为这是 Docker 自带的“万能 localhost”。错了。host.docker.internal是 Docker DesktopmacOS/Windows的内置 DNS 别名它会自动解析到宿主机的网关 IP。但在 Ubuntu 22.04 的原生 Docker Engine非 Desktop上这个别名默认不存在。如果你在 onboarding 时选择了 LM Studio 或 Ollama并且它们运行在宿主机上http://127.0.0.1:11434那么容器内的 OpenClaw 就会尝试连接http://127.0.0.1:11434而这其实是容器自己的 loopback不是你的宿主机。结果就是ECONNREFUSED模型调用永远超时。解决方案有两个第一修改docker-compose.yml在openclaw-gateway服务下添加extra_hosts: - host.docker.internal:host-gateway第二更推荐的方式是直接在宿主机上启动 Ollama/LM Studio 时就绑定到0.0.0.0而不是127.0.0.1。例如OLLAMA_HOST0.0.0.0:11434 ollama serve。这样你就可以在容器里安全地使用http://host.docker.internal:11434而无需修改 Compose 文件。这个区别非常关键前者是“让容器认识宿主机”后者是“让宿主机对所有网络接口开放”。后者更符合云原生的设计哲学也避免了未来迁移到 Kubernetes 时的兼容性问题。我建议所有本地 AI 服务从第一天起就用0.0.0.0绑定这会让你的整个技术栈更具可移植性。4. 实操过程与核心环节实现一份可逐字复制的流水线4.1 环境初始化从裸机到就绪的 5 个原子步骤我们从一台全新的 Ubuntu 22.04 服务器或 WSL2 实例开始。不要假设任何前置环境一切从零构建。这 5 个步骤每个都是不可跳过的原子操作顺序不能乱因为后一步依赖前一步的输出。步骤 1更新系统并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git gnupg2 software-properties-common ca-certificates提示ca-certificates是关键。没有它后续curl下载 Node.js 或 Docker 安装脚本时会因 SSL 证书验证失败而中断。这是很多“一键脚本”失败的元凶。步骤 2安装 NVM 并配置 Node.jscurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion nvm install --lts nvm use --lts node -v # 应输出 v20.12.2 或类似 npm -v # 应输出 10.2.4 或类似注意nvm install --lts后必须跟nvm use --lts否则node命令在当前 shell 中不可用。nvm的原理是修改PATH这个修改只对当前 shell 有效。步骤 3安装 Docker Engine非 Desktopcurl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo usermod -aG docker $USER newgrp docker # 刷新组权限使 docker 命令立即生效 docker --version # 应输出 Docker version 24.0.7 或类似关键点这里安装的是docker-compose-plugin它是 Docker 23 版本的官方 Compose 实现取代了旧的docker-composePython 版。docker compose无横杠是新命令docker-compose有横杠是旧命令两者不兼容。OpenClaw 的脚本只认docker compose。步骤 4创建安全密钥目录并设置权限mkdir -p ~/.openclaw-secrets chmod 700 ~/.openclaw-secrets # 创建一个示例 OpenAI Key 文件请替换为你自己的真实 Key echo sk-your-real-openai-api-key-here ~/.openclaw-secrets/openai.key chmod 600 ~/.openclaw-secrets/openai.key注意chmod 600是必须的它确保只有文件所有者你可以读写连同组用户都不行。这是最小权限原则的体现。步骤 5克隆 OpenClaw 仓库并进入目录git clone https://github.com/openclaw/openclaw.git cd openclaw # 检查当前分支确保是 main最新稳定版 git branch提示不要用git clone --depth 1因为setup.sh脚本会读取.git目录信息来生成版本号。浅克隆会导致版本号为空影响后续诊断。完成这 5 步后你的系统就具备了运行 OpenClaw 的全部硬件和软件条件。接下来才是真正的“10 分钟”核心。4.2 执行安装setup.sh的正确打开方式与参数详解现在我们进入最关键的./scripts/docker/setup.sh执行环节。但请不要直接敲回车。这个脚本接受大量环境变量合理利用它们能让你少走 80% 的弯路。第一步预设环境变量# 指向你之前创建的安全密钥目录 export OPENCLAW_SECRETS_DIR$HOME/.openclaw-secrets # 使用预编译的官方镜像跳过本地构建快 export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest # 如果你在中国大陆加速镜像拉取阿里云源 export DOCKER_REGISTRY_MIRRORhttps://your-aliyun-mirror-id.mirror.aliyuncs.com # 可选禁用 Bonjour避免 Docker 网络不稳定时的崩溃 export OPENCLAW_DISABLE_BONJOUR1 # 可选启用沙箱让 AI 代理在隔离容器中运行强烈推荐 export OPENCLAW_SANDBOX1解释OPENCLAW_IMAGE设为ghcr.io/openclaw/openclaw:latest是提速的关键。本地构建docker build需要下载所有依赖、编译前端、打包耗时 5-8 分钟。而拉取预编译镜像通常只需 30-60 秒。DOCKER_REGISTRY_MIRROR是针对国内用户的加速器你需要去阿里云容器镜像服务控制台创建一个个人镜像加速器获取专属 URL 替换your-aliyun-mirror-id。第二步执行 setup.sh 并交互式输入./scripts/docker/setup.sh此时脚本会启动交互式 onboarding 流程。它会依次询问Provider API Keys当提示输入 OpenAI Key 时不要手动输入。按CtrlShiftV粘贴你之前存好的~/.openclaw-secrets/openai.key文件内容即sk-xxx。其他 KeyTavily、Anthropic同理。Gateway Token直接回车使用默认生成的随机 token。Auth Profile Secret Key Directory脚本会自动创建~/.config/openclaw你只需确认。Start Gateway输入y脚本将执行docker compose up -d。第三步验证服务状态# 查看容器是否正常运行 docker compose ps # 应看到 openclaw-gateway 和 openclaw-cli 状态为 running # 查看 gateway 日志确认无 ERROR docker compose logs -f openclaw-gateway | grep -i started\|listening # 应看到类似 Server listening on http://0.0.0.0:18789 的日志注意如果docker compose ps显示Restarting或Exited立刻执行docker compose logs openclaw-gateway查看具体错误。90% 的问题都集中在这一步。第四步获取并访问 Control UI# 获取 dashboard URL会输出一个带 token 的长链接 docker compose run --rm openclaw-cli dashboard --no-open # 复制输出的 URL在浏览器中打开 # 在 Settings 页面粘贴 .env 文件中的 OPENCLAW_GATEWAY_TOKEN # 该 token 位于 $HOME/.openclaw/.env用 cat $HOME/.openclaw/.env | grep OPENCLAW_GATEWAY_TOKEN 查看提示--no-open参数非常重要。它阻止脚本自动打开浏览器让你能复制到完整的 URL。URL 中的token后面那段字符串就是你要粘贴到 UI 设置里的凭证。完成这四步你的 OpenClaw 就已经 24 小时在线了。Control UI 的首页会显示当前连接的模型、活跃的 Agent、以及最近的 API 调用统计。这才是“10 分钟搞定”的真实含义不是敲完命令就结束而是看到 UI 上那个绿色的 “Online” 状态灯亮起。4.3 首次配置让 AI 助手真正“活”起来的 3 个必做动作Control UI 是 OpenClaw 的大脑但光有大脑不够还得有手脚和感官。以下是让助手真正可用的三个核心配置。动作 1添加一个消息通道以 Telegram 为例在 Control UI 的左侧菜单点击Channels-Add Channel-Telegram。系统会生成一个 Bot Token。你需要在 Telegram 中搜索BotFather发送/newbot。按照 BotFather 的提示为你的机器人起名如MyOpenClawBot。BotFather 会返回一个形如1234567890:ABCdefGhIJKlmNoPQRstUvwXYZ123456789的 Token。将这个 Token 粘贴回 OpenClaw UI 的输入框点击Save。在 Telegram 中搜索你刚创建的机器人发送/start它就会回复 “Hello from OpenClaw!”。原理OpenClaw 的 Telegram Channel 本质上是一个 Webhook 服务器。它监听 Telegram 的推送事件将用户消息转为内部 Agent 请求再把 Agent 的响应格式化后发回 Telegram。整个过程不经过公网所有通信都在你的服务器和 Telegram 之间加密进行。动作 2配置一个本地大模型以 Ollama 为例在 Control UI 的Models页面点击Add Model。选择Ollama然后填入Model Name:llama3或其他你已ollama pull的模型名Base URL:http://host.docker.internal:11434确保 Ollama 已用0.0.0.0启动API Key: 留空Ollama 默认无需 Key保存后回到Agents页面编辑默认的CodexAgent将Default Model改为你刚添加的llama3。这样所有 Codex 的代码生成请求都会流向你本地的 Llama3而不是付费的 OpenAI API。动作 3启用沙箱并测试文件操作在Settings-Configuration中找到agents.defaults.sandbox部分将其改为{ mode: non-main, scope: agent, docker: { image: openclaw/sandbox:latest } }然后点击Save Restart Gateway。重启后在Agents页面点击CodexAgent 的Test按钮输入指令“请创建一个名为test.txt的文件内容是Hello from Sandbox!”。如果成功你会在$HOME/.openclaw/workspace/目录下看到这个文件。这证明沙箱已激活AI 的文件操作被严格限制在workspace目录内无法触及你的家目录或系统根目录。这三个动作构成了 OpenClaw 的最小可行产品MVP一个能接收消息、能调用模型、能安全执行命令的完整 AI 工作流。它不再是一个静态的 Web UI而是一个真正能为你干活的数字员工。5. 常见问题与排查技巧实录那些文档里不会写的血泪经验5.1 问题速查表高频故障与一招鲜解决方案故障现象根本原因一行命令修复经验备注openclaw: command not foundNode.js 环境变量未生效或nvm use未执行source ~/.nvm/nvm.sh nvm use --lts这是 WSL2 用户的头号问题每次新开终端都要执行EACCES: permission denied, mkdir /home/node/.openclaw宿主机目录所有者 UID 与容器内node用户 UID (1000) 不匹配sudo chown -R 1000:1000 $HOME/.openclaw $HOME/.config/openclaw必须同时修复.config/openclaw否则 auth profile 加载失败docker: command not founddocker命令未加入PATH或docker用户组未生效sudo usermod -aG docker $USER newgrp dockernewgrp是关键它会启动一个新 shell加载新的组权限Connection refusedwhen calling OllamaOllama 绑定在127.0.0.1容器内无法访问OLLAMA_HOST0.0.0.0:11434 ollama serve永远用0.0.0.0这是云原生的黄金法则Unauthorizedin Control UI after restartGateway token 在.env中被覆盖或丢失cat $HOME/.openclaw/.env | grep OPENCLAW_GATEWAY_TOKEN.env是唯一可信源UI 设置里填的 token 必须与此完全一致openclaw-gateway容器启动后立即退出docker.sock权限不足或OPENCLAW_SANDBOX1但 sandbox 镜像未构建sudo chmod 666 /var/run/docker.sock临时或./scripts/sandbox-setup.sh永久生产环境严禁chmod 666应使用usermod方案5.2 深度排障从日志里挖出真相的实战技巧当docker compose logs openclaw-gateway输出一堆滚动日志你该如何快速定位问题我的经验是永远从最后一行开始向上扫描聚焦 ERROR、FATAL、EACCES、ECONNREFUSED 这四个关键词。EACCES类错误99% 是文件权限问题。执行ls -ld $HOME/.openclaw $HOME/.config/openclaw检查 UID 是否为1000。如果不是立刻chown。ECONNREFUSED类错误90% 是网络问题。执行curl -v http://host.docker.internal:11434/api/tags假设你在调试 Ollama。如果返回Failed to connect说明host.docker.internal未解析需检查docker-compose.yml的extra_hosts配置。FATAL或ERROR后跟sqlite3这是数据库损坏。最简单的办法是docker compose down -v-v参数会删除所有 volume然后重新运行setup.sh。OpenClaw 的 SQLite 数据库存储在$HOME/.openclaw/workspace/state.db它很小重建无损。日志里反复出现healthz check failed说明 gateway 进程虽然启动了但 HTTP 服务未监听。执行docker compose exec openclaw-gateway netstat -tuln \| grep :18789。如果没有输出说明进程卡在启动阶段此时应查看docker compose logs --tail 100 openclaw-gateway的前 100 行找Starting server...之后的第一条错误。5.3 性能优化让 24 小时在线真正“稳如老狗”“24 小时在线”不仅是能启动更是能长期稳定运行。我总结了三条经过生产环境验证的优化技巧技巧 1配置 Docker 的内存与 CPU 限制在docker-compose.yml的openclaw-gateway服务下添加deploy: resources: limits: memory: 2G cpus: 1.0原因OpenClaw 的 gateway 进程在高并发时如同时处理 10 个 Telegram 用户请求会消耗大量内存。不加限制它可能吃光服务器 4G 内存导致系统 OOM Killer 杀掉关键进程。2G 是一个安全的上限既能保证性能又留有余量。技巧 2启用日志轮转防止磁盘爆满在/etc/docker/daemon.json中添加{ log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }然后sudo systemctl restart docker。这会让每个容器的日志文件最大为 10MB最多保留 3 个超出后自动覆盖。OpenClaw 的日志增长很快一天就能产生 500MB不轮转磁盘迟早告急。技巧 3设置 systemd 服务实现开机自启与崩溃自愈创建/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Gateway Service Afterdocker.service Wantsdocker.service [Service] Typeoneshot Userubuntu WorkingDirectory/home/ubuntu/openclaw ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down RemainAfterExityes Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw.service sudo systemctl start openclaw.service效果服务器重启后OpenClaw 会自动启动如果 gateway 容器意外退出systemd 会在 10 秒后自动重启它。这才是真正的“24 小时在线”。5.4 安全加固生产环境部署前的最后三道防火墙当你准备把 OpenClaw 从本地笔记本搬到一台公网 VPS 上时安全就是生死线。以下三点缺一不可加固点 1禁用 Docker 的默认iptables规则Docker 默认会修改iptables添加DOCKER-USER链。这会干扰你精心配置的ufw防火墙。在/etc/docker/daemon.json中添加{ iptables: false }然后sudo systemctl restart docker。之后所有端口暴露都必须通过ufw显式管理sudo ufw allow 18789/tcp仅开放 gateway 端口sudo ufw deny 2375/tcp禁止 Docker API 暴露。加固点 2为 Control UI 添加反向代理与 HTTPS永远不要直接用http://your-server-ip:18789访问。应该用 Nginx 做反向代理并强制 HTTPSserver { listen 443 ssl; server_name claw.yourdomain.com; ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:18789; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }
