OpenClaw双机部署实战：Ubuntu下Gateway+Node架构搭建与排错指南

说实话OpenClaw 这个项目我第一次接触是在它早期还叫别的名字的时候当时只是拿一台 Ubuntu 小主机跑跑单机觉得就是个能自动调工具、跑任务的玩具。后来需求变得复杂一台机器既要跑网关又要执行任务动不动就因为某个插件崩溃把整个调度链路带崩我这才下决心把架构拆成 Gateway Node 双机部署。这篇记录从系统准备、Gateway 端配置、Node 端接入到联调验证、常见报错排查全是我 2026 年初在 Ubuntu 24.04 LTS 上实际跑过的流程。如果你也准备在 Ubuntu 上把 OpenClaw 做成多机架构这篇文章可以直接拿来当操作手册少走不少弯路。1. 为什么我最终选择了 Gateway Node 双机部署1.1 OpenClaw 的 Gateway 和 Node 各自管什么OpenClaw 现在的架构说白了就是“大脑”和“手脚”分离。Gateway 是控制面负责接收用户指令、管理工作流、维护模型路由、把任务拆解后分发给各个执行节点Node 是执行面干活的地方跑具体命令、调本地工具、访问内网服务、执行各种自动化脚本然后把执行结果和日志回传给 Gateway。一开始我不理解为什么要分这么细后来实际用多了才明白这种设计最大的好处是“故障边界清晰”。单机部署时一个 Python 脚本把系统资源吃满Gateway 接收指令也跟着卡顿相当于指挥中心和施工现场在同一个房间里一着火全完蛋。拆成双机后Gateway 机器专心做调度Node 机器随便折腾即使 Node 端某个技能把系统搞挂了只要重启 Node 就行Gateway 不受影响新任务也不会被连带阻塞。1.2 双机架构适合什么场景以及我的环境规划如果你只是在本机跑几个玩具任务那单机部署完全够用没必要折腾双机。但如果你要把 OpenClaw 用起来比如定时巡检服务器、批量处理文件、接本地大模型做自动化工作流甚至让它在家里多台设备之间互调工具双机甚至多机就是刚需。我现在的使用场景就是Gateway 放在客厅的小主机上负责 7x24 小时接收指令Node 放在书房的工作站上承担所有重活比如跑模型推理、批量转码、定时备份。下面这是我实际用的环境给大家做参考节点硬件配置系统版本主要职责Gateway4核8G128G SSDUbuntu 24.04 LTS指令接收、工作流编排、模型路由、任务分发Node8核16G512G SSDRTX 3060Ubuntu 24.04 LTS任务执行、Ollama 模型调用、文件处理、定时脚本两个节点在同一个局域网内Gateway 的 IP 是 192.168.1.10Node 的 IP 是 192.168.1.20。这个规划很重要后面所有配置都要围绕 IP 和端口来写建议你在动手前先把两台机器的 IP 固定下来别用 DHCP 随机分配不然重启后地址一变Node 连不上 Gateway 会让你怀疑人生。2. 部署前的系统和网络准备先把地基打好2.1 Ubuntu 系统基础整理别急着装 OpenClaw先把系统收拾干净。我用的是 Ubuntu 24.04 LTS 最小化安装装完第一件事就是把 apt 源换成国内镜像。原因很简单默认源在国外拉依赖包慢到让人崩溃尤其是部署过程要装几十个依赖包的时候差距是十分钟和半小时以上的区别。换源的操作很简单把 /etc/apt/sources.list.d/ubuntu.sources 里的源地址替换成可用的国内镜像地址然后sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git unzip zip build-essential这里提醒一下build-essential 一定要装OpenClaw 在安装过程中会编译一些原生模块缺了编译工具链会报错而且报错信息隐藏得很深不仔细看都发现不了是缺 gcc。另外我建议在部署前给两台机器设置固定主机名。Gateway 机器叫 openclaw-gatewayNode 机器叫 openclaw-node改 /etc/hostname 和 /etc/hosts 后重启或者执行 hostnamectl set-hostname 生效。主机名理顺了后面看日志时一眼就能分辨是哪台机器出的问题不然全是 ubuntu 主机名排查故障时两头晕。2.2 Node.js 环境安装与版本管理OpenClaw 的运行时基于 Node.js这部分是整个部署流程里最容易出幺蛾子的环节。我在网上看过太多人直接用 apt install nodejs 装系统自带的版本结果版本太老导致 OpenClaw 启动直接报错。我的建议是使用 nvm 做版本管理灵活、干净、卸载也方便。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.bashrc然后安装 Node.js 22 LTS这个版本是我实测下来 OpenClaw 运行最稳的版本线如果你在 2026 年看到新的 LTS 也可以试但生产环境建议保守一点nvm install 22 nvm use 22 nvm alias default 22 node -v npm -v看到 v22.x.x 和 10.x.x 这样的输出就说明 OK 了。这里有个坑必须提醒nvm 安装完 Node 后新开的终端窗口可能找不到 node 命令这是因为 .bashrc 没生效执行 source ~/.bashrc 或者重开终端即可。如果你用的是 zsh记得看 .zshrc 里面是否也加载了 nvm。npm 的源我也建议顺手换成国内镜像不然装 OpenClaw 依赖时等得人想砸键盘npm config set registry https://registry.npmmirror.com换完之后执行 npm config get registry 验证一下输出 npmmirror 地址就代表生效了。2.3 SSH 与防火墙配置双机部署意味着你要在两台机器之间来回操作如果每次都跑去物理机前敲键盘效率太低。建议先把 SSH 配置好至少做到能从 Gateway 免密登录 Node方便联调。先在两台机器上都安装并启动 SSH 服务sudo apt install -y openssh-server sudo systemctl enable --now ssh然后生成密钥对并做免密登录ssh-keygen -t ed25519 ssh-copy-id user192.168.1.20这里我用的是 ed25519 密钥比传统的 RSA 更短更安全如果你有老系统兼容性要求再考虑 RSA。配置完测试一行 ssh user192.168.1.20 就能登上去说明成功了。防火墙方面Ubuntu 默认的 ufw 我建议开启只放行必要的端口。OpenClaw 默认的通信端口是 7100Gateway 的监听端口SSH 是 22。如果你还要用 Prometheus 监控后面还要放行 9100 和 9090。放行命令sudo ufw allow 22/tcp sudo ufw allow 7100/tcp sudo ufw enable不少新手在配置完防火墙后发现节点连不上 Gateway一查全是端口被挡了。这个坑很基础但特别常见放行完端口记得用 sudo ufw status 确认一下。3. Gateway 端部署 OpenClaw 全流程3.1 安装并初始化 OpenClaw GatewayGateway 端的安装流程很直白。OpenClaw 提供了官方安装脚本拉取最新稳定分支后会自动安装依赖并生成初始配置。执行curl -fsSL https://openclaw.example.com/install.sh | bash这里解释一下官网是 openclaw 官方域名安装脚本做的事情其实就是下载二进制包、创建数据目录、生成默认配置文件。执行完后 OpenClaw 的可执行文件会放在 ~/.openclaw/bin/ 下数据目录在 ~/.openclaw/。注意必须以普通用户身份安装OpenClaw 明确不支持 root 运行这个限制一开始我还没当回事结果以 root 装完启动直接报权限错误后来规规矩矩用普通用户重装了一遍。首次初始化openclaw init --role gateway初始化过程会问你几个问题主要是数据目录、监听端口、日志级别。我给出的配置建议是数据目录保持默认监听端口填 7100日志级别先选 debug等部署稳定后再改成 info。端口这里我强调一下不要用 7000 这类常见端口容易和其他服务冲突。我一开始用的就是 7000结果和局域网里另一台设备的服务撞了Node 端怎么都连不上排查了一个多小时才发现是端口占用。初始化完成后OpenClaw 会在 ~/.openclaw/config.yaml 生成配置文件。核心配置段大概长这样gateway: listen: 0.0.0.0:7100 hostname: openclaw-gateway data_dir: ~/.openclaw/data tls: enabled: false这里的 listen 字段必须监听 0.0.0.0而不是 127.0.0.1否则只有本机可以访问Node 端根本连不进来。这个问题在官方文档里写得不算显眼但在社区里问的人极多。3.2 二维码配对与节点注册机制Gateway 配置好后下一步就是让 Node 注册进来。OpenClaw 采用了一种比较现代的配对方式Gateway 生成一次性配对二维码Node 端扫码后自动完成节点注册和证书交换。这比手动拷贝 IP 和密钥要友好得多也避免了明文传输凭据的风险。首次启动 Gatewayopenclaw gateway start启动成功后OpenClaw 会在终端输出配对二维码同时会把二维码图片保存到 ~/.openclaw/data/pairing/qr_code.png。如果你是在无显示器的服务器上操作可以直接把这张图片复制到本地再扫。二维码的有效期默认是 15 分钟超时后需要重启 gateway 进程重新生成。这个机制的原理我简单说一下Gateway 在配对模式下会生成一个一次性随机 token这个 token 编码在二维码里Node 扫码后把 token 发回 GatewayGateway 验证通过后签发一个节点证书给 Node。之后 Node 和 Gateway 之间的通信就走证书加密了不再需要重复扫码。理解了这一点你就明白为什么二维码不能截图外传它本质上是一把临时的钥匙。3.3 用 systemd 让 Gateway 常驻后台终端直接跑 openclaw gateway start 只能在前台运行一旦你退出 SSH 会话进程就跟着挂了。要想让它 7x24 小时稳定运行必须用 systemd 守护。我写了一个 service 文件[Unit] DescriptionOpenClaw Gateway Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/.openclaw ExecStart/home/你的用户名/.openclaw/bin/openclaw gateway start Restarton-failure RestartSec10 EnvironmentPATH/home/你的用户名/.nvm/versions/node/v22.x.x/bin:/usr/local/bin:/usr/bin EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target注意 Environment 里的 PATH 一定要包含 Node.js 的实际路径因为 systemd 启动的环境是不加载 .bashrc 的很多部署教程没提这点导致服务启动后找不到 node 命令。写完后把这个文件放到 /etc/systemd/system/openclaw-gateway.service然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway sudo systemctl status openclaw-gateway看到 active (running) 就说明 Gateway 已经常驻了。日志查看用 journalctl -u openclaw-gateway -f后面排查问题全靠它。4. Node 端部署与双机组网联调4.1 Node 端安装与注册Node 端也需要安装 OpenClaw但初始化角色不同。执行curl -fsSL https://openclaw.example.com/install.sh | bash openclaw init --role nodeNode 初始化时同样会有几个交互问题其中最关键的一个是填写 Gateway 地址。这里一定要填 Gateway 机器在局域网内的实际 IP比如 http://192.168.1.10:7100不要填 127.0.0.1因为 Node 和 Gateway 是两台机器127.0.0.1 指向的是 Node 自己。填完地址后OpenClaw 会显示一个配对等待界面此时扫 Gateway 上的二维码即可完成注册。如果扫码后长时间没反应打开 Gateway 的 debug 日志看十有八九是防火墙挡了 7100 端口。注册成功后Node 的数据目录下会多出一个 certs 目录里面存放着和 Gateway 通信用的客户端证书。这个目录要保护好权限尽量设置成只有当前用户可读写chmod -R 700 ~/.openclaw/certs4.2 双机连通性验证和任务调度实测Node 接入后先别急着跑复杂任务做一次最小化的链路验证。第一步验证网络层连通性在 Node 机器上执行curl http://192.168.1.10:7100/health如果返回 JSON 格式的健康检查结果说明网络和端口都通。如果 curl 超时优先排查防火墙和安全组如果返回 502说明 Gateway 进程有问题往下看第 5 节。第二步验证业务链路。我在 Gateway 上创建了一个最简单的任务让 Node 执行 uname -a 并把结果回传。具体做法是在 Gateway 的管理界面或者命令行中新建任务选择目标节点为 openclaw-node命令填 uname -a然后触发执行。我实际执行这一步骤时第一次任务返回的状态是 failed日志里显示 Node 端执行超时。后来发现是 Node 端 OpenClaw 进程没有用 systemd 托管终端一关进程就没了Gateway 发过来的任务没人接收自然就超时了。给 Node 端也配上 systemd 服务问题就解决了。所以 Node 端同样建议用 systemd 守护service 内容和 Gateway 的类似只是 ExecStart 变成了 openclaw node start。4.3 跨机部署的几个注意点如果你的 Gateway 和 Node 在同一个局域网部署到这里基本就完事了。但我猜有不少人想把 Node 放在别的网络环境里比如家里一台、公司一台这种跨网段部署需要额外注意几件事。首先是端口暴露问题。不要在公网直接暴露 OpenClaw 的管理端口除非你有专业的防护手段。我见过有人图省事把 7100 端口直接映射到公网结果没几天就被人扫到并尝试爆破。安全做法是只在可信内网使用或者通过云平台的安全组把访问白名单限制到指定 IP。其次是网络延迟对任务超时的影响。跨网络环境下Node 执行任务的回传延迟会明显变高尤其是执行时间较长的脚本容易触发 Gateway 侧的任务超时阈值。这种情况可以在 Gateway 配置里调大 task_timeout 参数我的跨网测试环境里设的是 300 秒。最后强烈建议在 Node 端也做 systemd 守护和日志持久化不然 Node 进程挂了你都不知道Gateway 这边只会看到任务一直失败排查起来非常被动。5. 常见坑和排查实录我踩过的都在这5.1 系统层面的几个大坑先说一个最让人崩溃的在 WSL2 里跑 OpenClaw启动时报 “openclaw could not safely verify the wsl2 environment”。这个报错的意思是 OpenClaw 检测到当前运行在 WSL2 环境中但无法确认系统环境符合要求。实际上 OpenClaw 在 WSL2 里的兼容性一直不太理想主要问题集中在资源限制和网络转发上。我之前为了图方便在 Windows 的 WSL2 里试过部署写代码是没问题但做双机联调时到了扫码配对环节就莫名其妙失败。如果你想让 OpenClaw 跑得安心建议直接上原生 Ubuntu别说 WSL2虚拟机我都不推荐。我最终的 Gateway 和 Node 都是原生系统配对一次通过再也没出现环境校验问题。另一个系统层的坑是中文输入法导致配置文件编码出错。我在配 Node 时因为编辑配置文件时输入法切到了中文某个配置项的值里混入了一个中文引号结果 OpenClaw 启动时 yaml 解析失败报错信息极其抽象只说语法错误根本定位不到是哪个文件哪一行。后来把所有配置文件用 yamllint 检查了一遍才在配置的注解里发现中文标点。建议在部署阶段所有配置文件都用纯英文环境和英文标点编辑别给排错添乱。再有一个是 SSH 连接不上。我因为懒得改默认配置结果系统重启后 SSH 服务没起来外网怎么连都连不上。排查步骤就是先确认 openssh-server 装了没然后 sudo systemctl status ssh 看服务状态最后看 ufw status 确认 22 端口放行了没。这三个从大概率到小概率基本覆盖了常见原因。5.2 502 Bad Gateway 报错的系统性排查跑 OpenClaw 的过程中我遇到最多的报错就是 502 Bad Gateway。最典型的一个长这样“unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572”。这个报错看起来吓人其实拆开看就一句话Gateway 要把请求转发到本地的 1572 端口但那个端口上根本没有服务在监听或者服务已经挂了。1572 端口一般是 OpenClaw 的扩展服务端口比如本地模型网关或者某个插件子进程。我的排查顺序建议是第一确认目标端口有没有进程监听sudo lsof -i :1572 ss -tlnp | grep 1572如果没有任何输出说明对应的子服务根本没起来。第二如果端口有监听但依然 502用 curl 直接测一下这个端口curl http://127.0.0.1:1572/health能通就说明服务正常问题出在 OpenClaw 内部路由不通就说明服务假死需要重启子服务。第三检查 OpenClaw 自身日志journalctl -u openclaw-gateway -f日志里会明确指出是哪个插件或哪个转发规则出了问题。我还遇到过一种 502报错信息里带了 “cc switch local 转发失败” 的字样。这种一般是 OpenClaw 内部的动态路由切换出了问题某个技能在处理请求时试图把任务切到另一个内部转发通道但目标通道没有正确注册。遇到这种别急着重启整套服务先去管理界面看当前注册的节点列表确认 Node 是不是掉线了。因为内部转发通道依赖节点注册表节点掉线后网关尝试转发就会立刻 502。这里分享一个我很受益的实践给 Gateway 和 Node 各写一个健康检查脚本每分钟探测一次 /health 接口发现异常就自动重启服务并推送通知。有了这个502 类问题基本在用户感知之前就被处理掉了。5.3 模型路由配置错误doesn‘t look like an anthropic model另外一个高频报错是“doesn’t look like an anthropic model: expected a gateway model route reference”。我当时第一次看到这个报错直接懵了因为我配的明明不是 Anthropic 的模型后来才搞明白问题出在模型路由配置上。OpenClaw 的模型路由配置里每个模型都需要通过一个路由 ID 来引用。如果你在某个工作流里直接填了模型名称而没有先定义一个对应的路由 ID网关就会用默认规则去匹配匹配不上就抛出这个错误。正确的做法是在配置里先定义模型路由model_routes: local-llama: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 model: llama3.1 api_key: dummy然后在工作流或技能配置里引用的是路由 ID local-llama而不是模型名 llama3.1。这个命名习惯一开始不太适应但理解了“路由 ID 是网关内部寻址用的逻辑名模型名是上游服务真正识别的名称”之后就再也不会混淆了。如果你接的是 Anthropic 的模型原理也一样路由 ID 和实际的模型名称是两回事别混填。这大概是 OpenClaw 的配置里最值得花十分钟搞明白的一个概念。5.4 Node 版本相关的坑最后说一个安装层面的坑。如果你用系统自带的 Node.js 旧版本OpenClaw 安装依赖时可能会报 Node 版本不满足要求。我的处理方式是统一用 nvm 管理 Node 版本并且给 Gateway 和 Node 两台机器用同一个 Node 大版本避免两边运行时代码行为不一致。还有个小坑npm 安装依赖时如果网络抽风会出现依赖装了一半、目录锁没释放的情况。这时候不要反复 npm install执行rm -rf node_modules package-lock.json npm cache clean --force npm install干净重来往往比在原地挣扎更高效。6. 进阶接入本地模型、监控与日常维护6.1 给 Node 接入 Ollama 本地模型既然 Node 机器上有显卡不接本地大模型就太浪费了。OpenClaw 本身支持 OpenAI 兼容接口所以接入 Ollama 非常顺滑。先在 Node 机器上安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh ollama pull llama3.1 ollama serve默认情况下 Ollama 监听 127.0.0.1:11434但 OpenClaw 的 Node 进程是本地调用所以这个地址没问题。然后在 OpenClaw 配置里加一条模型路由model_routes: ollama-llama3: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 model: llama3.1 api_key: ollama配置完重启 OpenClaw 服务然后建一个任务让它调用 ollama-llama3 路由。我实测下来本地跑 llama3.1 的响应速度和调用外部 API 相比少了一层网络延迟而且数据完全不出内网隐私上也没负担。如果你有更大的模型需求DeepSeek 系列的开源版本也能用同样的方式接进来只要 base_url 指向对应的本地推理服务即可。6.2 用 Prometheus 监控双机健康状态部署完的开源项目如果不上监控就像买了车不装仪表盘。我用的监控方案是 Prometheus node_exporter。两台机器各装一个 node_exporter监听 9100 端口wget https://github.com/prometheus/node_exporter/releases/download/v1.8.2/node_exporter-1.8.2.linux-amd64.tar.gz tar xzf node_exporter-*.tar.gz sudo mv node_exporter-*/node_exporter /usr/local/bin/然后写一个简单的 systemd 服务托管再在 Prometheus 的配置文件里加上两个采集目标scrape_configs: - job_name: node static_configs: - targets: [192.168.1.10:9100, 192.168.1.20:9100]有了监控数据后我设置了两个告警规则CPU 使用率连续 5 分钟超过 90%内存使用率超过 85%。一旦 Node 机器因为跑模型负载过高我能在第一时间收到通知而不是等任务超时了才去翻日志。6.3 升级与卸载别把系统搞脏OpenClaw 迭代速度不慢升级是个常态操作。升级前先做配置备份cp -r ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)然后执行 openclaw upgrade升级完成后重启服务。我遇到过升级后某些插件不兼容的情况这时候直接用备份目录回滚rm -rf ~/.openclaw mv ~/.openclaw.bak.xxx ~/.openclaw sudo systemctl restart openclaw-gateway卸载则要干净彻底。光删目录是不够的systemd 服务还残留在系统里。完整卸载流程sudo systemctl stop openclaw-gateway sudo systemctl disable openclaw-gateway sudo rm /etc/systemd/system/openclaw-gateway.service sudo systemctl daemon-reload rm -rf ~/.openclaw这样操作之后系统基本恢复到安装前的状态不会有残留进程或者自启动项对后续部署其他服务也不会有干扰。7. 部署完之后我给自己定的运维习惯最后分享几点不是教程里会写、但实际用下来特别管用的经验。一是配置备份要勤快。OpenClaw 的配置改动频率比我预想的高每次加节点、改模型路由、调插件参数都会动配置文件。我现在每周用 cron 做一次配置目录自动备份保留最近 30 天的版本。一旦改配置把系统改崩了直接回滚到昨天的配置比现场排查快得多。二是日志必须有轮转。OpenClaw 的日志在 debug 模式下增长特别快如果不处理一块 20G 的硬盘可能一周就被日志写满。我在 systemd 的 service 文件里加了 logrotate 的配置每天切割一次日志最多保留 7 天。这个细节让我少处理了好几次“磁盘满了导致服务假死”的事故。三是搭好环境之后尽量少动基础组件。Node 版本、npm 源、系统依赖这些属于基石一旦跑通就别频繁升级。我吃过一次亏某次手贱把 Node 从 22 升到了 23结果 OpenClaw 有个原生模块编译不过去折腾了大半个晚上才回滚。如果新版本没有明确需要解决的问题就让它待在原处这是部署架构稳定的核心心得。