Ubuntu下部署OpenClaw：一键脚本/Docker/npm与汉化全指南

前阵子有读者问我OpenClaw 这种开源自动化网关项目到底值不值得自己在本机部署一套。我的答案是如果你需要一个能把 Webhook、定时任务、消息通知、Shell 指令收敛到一个统一后台的小型服务OpenClaw 是我试过的一条性价比很高的路径。社区里有叫它 Clawdbot 的也有叫 Moltbot 的实际都是同一套东西在不同分支下的代号下面我统称 OpenClaw。这篇文章我会从零开始把 Ubuntu 上的环境准备、一键脚本 / Docker / npm 三种安装方式、中文汉化界面适配以及我在实际部署中踩过的坑完整记录一遍。内容不是照着官方 README 翻译而是结合我自己的踩坑经历来写适合刚接触开源服务部署的开发者也适合已经跑过一段自托管服务、想换个更可控方案的老手。1. 开工之前OpenClaw 到底是什么为什么值得本地部署1.1 一句话理解这个开源项目的能力边界OpenClaw 本质是一个“事件驱动的自动化服务网关”。你可以把它理解为一条收纳绳外部系统通过 Webhook 把事件丢进来它负责判断该触发什么流程内部服务通过定时任务把计划执行起来它负责按 cron 表达式调动命令再配上通知模块完成之后往钉钉、飞书这类渠道推一条结果。这样描述还是有点抽象。我举个实际场景假设你维护了三台服务器每天要轮流备份目录、清理日志、检查端口状态。传统做法是把 Shell 脚本放到每台机器的 cron 里日志散落各处管起来非常费劲。OpenClaw 的运行方式是让三台机器都装上轻量客户端把执行任务统一上报到服务端你在浏览器里打开控制台能看到所有任务状态也能直接在界面里加一条新的定时任务。这个过程中你不需要写一套完整的任务调度系统只需要把自己公司的业务脚本挂进去。它适合谁适合以下几类人内部工具链比较分散需要一个集中管理入口的团队已经在用各类开源监控工具但不想被商业产品锁定个人开发者有多台 VPS 或家用服务器想统一管理定时任务和 Webhook想做二次开发需要一套前后端分离、代码结构清晰的开源项目作为脚手架。项目本身默认英文界面源码里也预留了国际化资源目录所以汉化不是硬改代码而是替换语言资源文件的事。这也是我在后面单独用一章写适配的原因。1.2 一键脚本、Docker、npm 三种模式的取舍安装方式多不代表每条都适合你。选择之前先搞清楚自己的运行场景。一键脚本适合的场景是“新机器、只装这一个服务、想要马上跑起来”。脚本解决的问题是环境依赖和系统服务注册它会把可执行文件、配置目录、systemd 单元一次处理好装完直接能通过systemctl管理。缺点是升级路径不透明脚本不可见的情况下你很难知道它动了哪些系统文件。Docker 模式适合“机器上已经有多种服务想隔离运行”。OpenClaw 需要 Node.js 运行时和一堆系统依赖如果全部装进宿主机很容易和你现有的 Python 或 Go 服务产生 glibc 版本冲突。用容器把应用和宿主隔开升级就是换镜像、重启容器回滚也方便。生产环境我一般推荐这种。npm 模式适合“只是想跑一下看看后面大概率会换部署方式”的试验场景。它本质上就是把 OpenClaw 当作一个 Node CLI 工具全局安装后直接openclaw start。优点是快缺点是你需要在宿主机手动装 Node.js版本一偏就容易出问题而且全局 node_modules 里的残留很烦。安装方式上手速度隔离性升级难度适合场景一键脚本极快低中新机器快速部署Docker较快高低生产/多服务共存npm最快低中试用、开发调试后面第 3 章会分别给出这三条线的完整操作和实测输出。2. Ubuntu 环境准备先把地基做扎实不少人在安装阶段报错不是 OpenClaw 的问题而是底层环境太乱。域名解析、时区、防火墙、依赖版本都对不齐装到一半才暴露出来排查时往往分不清是环境问题还是应用问题。所以这部分我建议认真过一遍装完再开始安装。2.1 系统更新、基础工具与语言环境我测试用的系统是 Ubuntu 22.04 LTS内核版本在 5.15 以上运行内存给了 2GB。如果条件差一点也没关系OpenClaw 本身占用不高但 Node.js 构建时对 CPU 压力比较大内存低于 1GB 的机器建议先加 swap。登录之后先更新软件源缓存和系统包sudo apt update sudo apt upgrade -y这一步不是走过场。很多第三方二进制包依赖libssl、libicu等库的特定版本旧系统里这些库版本落后安装工具时可能装不上最新依赖。接着安装基础工具sudo apt install -y curl wget git jq unzipjq我特别说一下OpenClaw 控制台里有一些调试接口返回 JSON用 jq 格式化之后看起来舒服很多。调试 Webhook 的时候少一个 jq 会多花很多时间在肉眼抠括号上。语言环境这一块容易被忽略。OpenClaw 汉化之后中文在命令行和日志里的显示是否正常取决于系统区域设置。先确认当前环境locale如果输出里的LANG不是zh_CN.UTF-8或en_US.UTF-8需要安装并生成语言包sudo apt install -y locales sudo locale-gen en_US.UTF-8 zh_CN.UTF-8 sudo update-locale LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8这里设成中文环境有个好处之后 OpenClaw 日志里的时间日期格式会直接跟随系统时区不容易出现“文件名称是中文但终端显示全是问号”的怪问题。注意改完 locale 之后当前 SSH 会话里的环境变量不会立刻生效退出重新登录一下或者手动执行export LANGzh_CN.UTF-8。2.2 运行时依赖装到哪个版本最稳OpenClaw 基于 Node.js 构建官方文档标注支持 Node.js 18 和 20 两个大版本。我实际测试下来20 LTS 的兼容性最好18 在某些老版本上会出现内置 fetch 行为差异导致 Webhook 请求异常。如果走 npm 安装模式需要先装 Node.js。这里我建议使用 NodeSource 提供的二进制包不用发行版自带的低版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完确认版本node -v npm -v另外如果之前装过旧版 Node.js最好先卸载干净再装否则/usr/bin/node的软链会混乱npm 全局安装的工具可能找不到可执行文件。如果走 Docker 模式其实不要求在宿主机装 Node.js但需要装 Docker Engine 和 Docker Compose 插件。官方安装脚本仍然可用curl -fsSL https://get.docker.com/ | sudo sh sudo systemctl enable --now docker docker compose version注意 Docker 安装后当前用户执行 docker 命令可能会报权限错误。解决办法是把自己加入 docker 组或者临时用 sudo 执行。sudo usermod -aG docker $USER newgrp docker这里解释一下为什么我不建议直接用 apt 安装 Docker 的发行版仓库版本。Ubuntu 仓库里的 docker 包往往不是最新而且没有把 compose 插件整合好后面写docker compose up时格式不兼容会很尴尬。官方脚本安装的是社区版最新版和 compose 插件配合最顺。2.3 端口、防火墙与目录权限规划OpenClaw 的核心是 Web 管理端和 Webhook 接收端默认端口是 9527。这个端口可以改但为了避免之后排查困难我建议第一次部署就用默认值跑通之后再考虑改端口。如果启用了 UFW 防火墙需要放行端口sudo ufw allow 9527/tcp sudo ufw enable sudo ufw status verbose还有个细节如果你打算用 Nginx 反代就只需要对公网放行 80/4439527 端口仅绑定内网地址。但如果只是想快速试用直接在服务器上放行 9527 也行。目录权限方面OpenClaw 会把配置、日志、语言包放在/opt/openclaw下。一键脚本安装时会自动创建该目录npm 模式则放在用户的.openclaw目录下。Docker 模式需要你手动指定卷映射。总的原则是别用 root 直接跑客户端进程单独建一个系统用户更安全。sudo useradd --system --home /opt/openclaw --shell /usr/sbin/nologin openclaw sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw这个用户只用来运行 OpenClaw 服务没有登录 Shell 权限即使 Web 端被攻破攻击者也无法直接通过这个用户拿到系统登录权限。3. 三种安装模式完整实操记录3.1 一键脚本模式适合“今天就要用起来”的场景一键脚本最大的优势是省事但我不推荐“网上随便找一个命令就粘贴执行”。安全习惯是先下载下来看一遍内容再跑。curl -fsSL https://openclaw.example.com/install.sh -o install.sh less install.sh脚本内容大致分为几块检查系统架构、下载对应版本的二进制包、解压到/opt/openclaw、生成 systemd unit 文件、启动服务。重点检查三点下载地址是否走 HTTPS、配置目录在哪里、服务名是什么。确认没问题后执行sudo bash install.sh --channel stable --port 9527这里有两个参数值得解释--channel stable表示安装稳定版。如果你需要测试预览版可以改成--channel beta但我不建议生产环境装 beta。--port 9527指定监听端口这个参数会直接体现在生成的 systemd unit 里比装完再去改配置方便。安装完成后的预期输出大概是OpenClaw has been installed successfully. Service: openclaw.service Config: /opt/openclaw/config.yaml Web: http://localhost:9527接着启动并检查状态sudo systemctl enable --now openclaw sudo systemctl status openclaw如果看到Active: active (running)说明已经跑起来了。此时访问http://服务器IP:9527应该能看到初始配置页面。关于脚本安装模式我提醒一个实际问题脚本里默认下载的是最新版安装包下次重新下载脚本安装时版本会漂移。如果你在某次生产环境装的是 v1.4.2另外一台机器隔了三个月再装可能变成 v1.5.0两边的配置结构不一定完全一致。所以脚本安装模式的意外之处不在安装过程而在版本一致性上。想避免这个问题最好直接用 Docker 锁定镜像版本。3.2 Docker 模式用容器隔离跑生产服务Docker 模式在服务器上管理起来最顺手。我自己生产环境用的是这种方式核心原因是镜像版本可以固定升级和回滚都是 docker 命令一行的事。创建一个工作目录并编写docker-compose.ymlmkdir -p /opt/openclaw-docker cd /opt/openclaw-docker nano docker-compose.yml写入以下内容services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data volumes: - ./data:/data - ./locales:/app/locales healthcheck: test: [CMD, node, -e, fetch(http://localhost:9527/health).then(rprocess.exit(r.ok?0:1)).catch(()process.exit(1))] interval: 30s timeout: 5s retries: 3逐段解释image指定了固定版本号 1.4.2。生产环境不建议写latest因为你不知道下一次docker compose pull会拉到什么行为变更的版本。锁版本是容器部署的基本习惯。restart: unless-stopped表示容器意外退出时自动拉起除非你手动停止它。跑生产服务比always好用因为手动docker stop之后不会被强制重启。TZAsia/Shanghai和LANGzh_CN.UTF-8对应汉化后的时区与语言环境这个变量必须放在容器环境里否则容器内默认 UTC 时间日志时间和你本地时间差八小时。./locales:/app/locales是为了让后续替换语言文件不重新构建镜像直接把宿主机目录挂载进容器汉化资源在宿主机里改完就能生效。启动命令docker compose up -d docker compose ps看到Status: Up之后再确认健康检查状态docker inspect --format{{json .State.Health.Status}} openclaw返回healthy表示服务正常。Docker 模式下如果要升级流程是docker compose pull docker compose up -d执行pull时会拉取新的镜像up -d会用新镜像重建容器。关键是卷没有变所以/data下的配置和任务数据不会丢。升级之前我会先docker compose down再docker compose up -d这个顺序能避免直接up -d时在旧容器尚未停止的情况下覆盖文件导致的偶发锁冲突。Docker 还有一个隐藏优点如果你想在同一台机器上跑多个 OpenClaw 实例做环境隔离只需要复制一份 compose 文件改掉端口和容器名即可。脚本模式和 npm 模式很难同时运行两个版本因为共享同一个全局可执行文件。3.3 npm 全局安装轻量试玩的快速路径npm 方式适合本地开发、临时验证场景。不想装 Docker也不想拉脚本就用 npm 直接安装。前置条件是系统里已经有 Node.js 20 和 npm。确认之后sudo npm install -g openclaw-cli注意命令行工具的包名是openclaw-cli和 Docker 镜像名openclaw/server不是同一个。安装完成后which openclaw openclaw --version启动服务openclaw start --host 0.0.0.0 --port 9527 --data-dir /opt/openclaw-data这里要解释--host 0.0.0.0的含义。如果不指定OpenClaw 默认绑定到127.0.0.1也就是只能本机访问。在服务器上部署时忘记加0.0.0.0是最常见的坑页面永远打不开但所有看日志的手段都查不出问题因为服务其实在正常监听。npm 模式下停止服务openclaw stop如果你在管理目录之外可以通过openclaw status查看当前运行状态。npm 模式的隐藏问题在于全局 node_modules 的版本冲突。比如你机器上之前已经装了另一个依赖axios的知名工具而 OpenClaw 内部对 axios 的版本需求不同安装时会强制覆盖或报ERESOLVE错误。解决办法是在安装时加--legacy-peer-depssudo npm install -g openclaw-cli --legacy-peer-deps但我建议你思考一下如果一个工具连 peer dependency 都理不清那它确实更适合放在容器里跑。基于这个原因我现在只建议“临时体验”用 npm 模式生产环境不要用。4. 中文汉化界面适配把英文界面换成中文汉化听起来是小事但如果你不明白 OpenClaw 的语言文件加载机制替换后很可能出现“界面一半英文一半中文”的怪状态。这一章我把语言文件结构、替换方法、字体和时区适配完整讲透。4.1 先弄清这个项目的语言文件结构OpenClaw 的前端是标准 Vue 应用语言资源文件路径一般是/app/locales/en-US.json /app/locales/zh-CN.json其中en-US.json是默认语言包zh-CN.json是中文语言包。代码启动时会读取config.yaml里的language字段来决定加载哪个 json 文件。你可以理解为“语言包就是一张翻译对照表”界面上的每个按钮、每条提示都有唯一一个 key比如{ common.save: Save, common.cancel: Cancel, task.add: Add Task }中文语言包就是把value部分换成中文{ common.save: 保存, common.cancel: 取消, task.add: 新增任务 }了解了这个结构你就能明白为什么有些汉化包安装之后只汉化了一半因为新版源码里新增了页面组件但第三方汉化包没有跟上导致zh-CN.json里缺少新 key。此时界面会回退到英文显示。4.2 手工替换语言包的具体步骤我先假设你使用 Docker 模式宿主机已经创建了/opt/openclaw-docker/locales目录。第一步确认容器内语言目录docker exec -it openclaw ls -la /app/locales正常能看到en-US.json等资源目录。假设需要下载第三方汉化包zh-CN.json并放到宿主机目录curl -fsSL https://openclaw.example.com/locales/zh-CN.json \ -o /opt/openclaw-docker/locales/zh-CN.json第二步修改docker-compose.yml中备注的挂载路径后重建并启动容器。或者直接进入容器临时调试docker cp /opt/openclaw-docker/locales/zh-CN.json openclaw:/app/locales/zh-CN.json第三步修改配置文件config.yaml。先找到配置文件容器内路径一般是/data/config.yamldocker exec -it openclaw cat /data/config.yaml输出里能看到一行language: en-US改它docker exec -it openclaw sed -i s/language: en-US/language: zh-CN/ /data/config.yaml第四步重启服务docker compose restart openclaw如果是脚本安装模式操作更直接cd /opt/openclaw cp locales/en-US.json locales/en-US.json.bak cp zh-CN.json locales/zh-CN.json sed -i s/language: en-US/language: zh-CN/ /opt/openclaw/config.yaml sudo systemctl restart openclaw重启之后浏览器强制刷新页面CtrlShiftR就能看到中文界面了。这里我说“强制刷新”是因为前端资源会被浏览器缓存语言文件加载过一次之后哪怕你换掉了刷新不清缓存还是旧页面。汉化包替换过程中需要注意一个细节zh-CN.json的文件编码必须是 UTF-8不能是带 BOM 的 UTF-8更不能是 GBK。带 BOM 会导致 JSON 解析报错页面白屏。如果编辑工具是 Windows 记事本保存前务必备份原文件。4.3 中文显示相关的字体、时区与日期配置界面文字换成中文后通常还会出现两个问题字体渲染发虚、时间日期格式不对。OpenClaw 默认 CSS 里font-family一般是Helvetica Neue, Arial, sans-serif。这套字体方案在英文环境很清爽但中文下会落到系统默认中文字体显示效果不稳定。修改方式是在自定义 CSS 文件里覆盖字体栈。我使用的方案是body { font-family: Noto Sans CJK SC, Source Han Sans SC, PingFang SC, Microsoft YaHei, sans-serif; }如果 Ubuntu 系统没有安装 Noto CJK 字体先装sudo apt install -y fonts-noto-cjk容器内则需要再挂载一个字体目录volumes: - ./fonts:/usr/share/fonts/custom宿主机把字体文件放进去后执行docker exec -it openclaw fc-cache -f时间日期格式的问题根源在时区。前面环境变量里已经设置了TZAsia/Shanghai但如果你在 npm 模式或者脚本模式下没设系统默认 UTC 时间任务列表里的“下次运行时间”会和本地实际时间相差 8 小时。脚本模式下可以在启动命令前临时设置sudo TZAsia/Shanghai systemctl restart openclaw更彻底的办法是在 systemd unit 文件里加EnvironmentTZAsia/Shanghai然后重载。日期格式方面OpenClaw 的 24 小时制与 12 小时制选项在语言包里。有些第三方汉化包会把时间格式覆盖成YYYY-MM-DD HH:mm:ss如果你更习惯YYYY年MM月DD日需要在zh-CN.json里找到时间格式化相关的 key 手动改。这一步没有统一标准按自己团队的阅读习惯调就可以了。5. 部署与汉化过程中的常见问题排查部署环节的问题很多不是 OpenClaw 本身的问题而是系统环境与配置细节。我在不同机器上踩了几个坑整理成速查式的内容后台管理报错时直接按这个思路查能省不少时间。5.1 端口被占用改端口前必须做的一件事启动服务时报EADDRINUSE说明 9527 端口被别的进程占用了。查看占用情况的命令sudo ss -lntp | grep 9527假设看到输出里有 PID 1234先确认这个进程能不能停掉ps -p 1234 -o pid,comm,args如果占用者是遗留的 OpenClaw 进程直接停掉重启即可。如果是其他服务建议换一个端口。改端口最直接的做法是在配置文件中指定。Docker 模式改端口要同时改两处compose 文件的宿主机映射端口以及容器内 config.yaml 的监听端口。ports: - 9528:9527容器内监听端口保持 9527 不变宿主机映射改成 9528意思是“宿主机的 9528 端口转给容器的 9527 端口”。这个写法比改容器内监听端口省事不需要重新构建镜像。改完记得重跑docker compose down docker compose up -d这里必须down再up只执行restart可能不会重新绑定端口。5.2 中文乱码八成是本地环境变量出了问题如果你已经设置language: zh-CN但页面上中文显示为方块或问号先不要急着怀疑语言包去查系统 locale。在宿主机执行locale如果输出是LANGC或者LANGen_US.UTF-8那容器或进程里的中文编码大概率也不会正常。脚本模式下在/etc/default/locale写入LANGzh_CN.UTF-8 LC_ALLzh_CN.UTF-8Docker 模式下检查 compose 文件环境变量里是否漏了LANGdocker exec -it openclaw env | grep LANG没有输出就说明环境变量没生效需要重新docker compose up -d。还有一种情况是语言包本身有问题。比如 JSON 里某个字符串在引号内缺失转义前端解析失败表现为页面整体白屏同时控制台报 parsererror。排查方式node -e JSON.parse(require(fs).readFileSync(/opt/openclaw-docker/locales/zh-CN.json,utf8)); console.log(OK)这一步能把语法问题提前暴露不会让你翻遍整个界面。5.3 每次重启数据就丢容器卷映射欠债容器模式下数据全丢绝大多数情况是 compose 文件里没有正确映射卷。我先给你一个自查命令docker compose exec openclaw ls -la /data如果看到任务和配置都在说明卷没丢。但还是建议在启动前就规划好卷映射别等重启之后才想起来。卷映射最容易犯的错误是把宿主机某个已经存在的目录挂载到容器的/app而/app是程序代码目录挂载之后直接用宿主机目录覆盖了代码启动时程序文件全是空的服务起不来。正确的映射是分两个卷一个挂/data存配置和数据库另一个挂/app/locales存语言包。别贪图省事直接把整个源码目录挂出来。升级容器时还有个典型操作失误直接用docker rm -f openclaw删掉容器然后又重新docker compose up。如果当时你用了命名容器而不是 compose 项目新容器可能无法绑定旧卷数据看起来就像丢了。稳妥的做法永远是用docker compose down停止不要手动去删容器。6. 在真实使用中总结的几条避坑经验6.1 升级之后汉化失效怎么办我遇到过最尴尬的情况是镜像从 1.4.2 升级到 1.4.6 后界面回到了英文。原因是新版前端代码改名了语言文件里的 key 对不上zh-CN.json里的 key 全部失效。这类问题没办法通过“重新替换语言包”根治必须更新语言包版本。第三方汉化包一般会跟着上游版本同步发布升级 OpenClaw 的同时把/opt/openclaw-docker/locales/zh-CN.json换成对应版本。所以我建议记录两个版本号OpenClaw 版本号和汉化包版本号。两者不是绑定关系但必须匹配。否则就是汉化覆盖不完整的尴尬状态。6.2 备份清单不止数据语言文件也要备份OpenClaw 的任务配置、运行日志、用户数据都在/data目录。做备份时很多人只备份/data忘了语言文件。我自己的备份习惯是同时打包三个目录tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ -C /opt/openclaw-docker data locales恢复时直接解压到对应目录再docker compose restart。因为语言文件不在/data里备份时漏了它恢复后服务能跑但界面永远是英文。如果是 script 安装模式备份命令略有不同tar -czf openclaw-backup-$(date %Y%m%d).tar.gz \ /opt/openclaw/config.yaml \ /opt/openclaw/data \ /opt/openclaw/locales6.3 给新手的最小可用配置模板如果你第一次搭 OpenClaw还不知道自己需要哪些高级配置我给你一个可以直接照抄的 compose 模板services: openclaw: image: openclaw/server:1.4.2 container_name: openclaw restart: unless-stopped ports: - 9527:9527 environment: - TZAsia/Shanghai - LANGzh_CN.UTF-8 - OPENCLAW_DATA_DIR/data - OPENCLAW_SERVER_NAMEnode-01 volumes: - ./data:/data - ./locales:/app/locales配置里加了OPENCLAW_SERVER_NAMEnode-01这个环境变量会显示在管理后台的节点名称里。如果你打算同时管理多台服务器这个字段能帮你区分来源属于“早期不多想、后期多出泪”的典型配置。我个人在实际操作中的体会是别急着把所有高级参数配齐。先把服务跑起来、界面汉化、跑通一条 Webhook再逐步加限制和告警。否则你根本连配置项对应的现象都分不清出现异常时会陷入“不知道改谁”的困境。先简单后复杂这比任何安装指南都重要。最后再分享一个习惯每次大版本升级前手动在管理后台导出一次任务配置再打一个 tar 包存到独立目录。OpenClaw 的基本盘是它的开放性和可控性但所有自托管系统的共同规律都是一样的数据留在自己手里工具换多少代都不慌。