OpenClaw Ubuntu 24.04 安装指南

目标：在 Ubuntu 24.04 服务器上从零安装并跑通 OpenClaw Gateway（v2026.10.6），覆盖官方一键脚本、npm 全局包、官方 Docker 镜像三种安装方案，以及最小配置、systemd 服务托管、验证与卸载全流程。已在 Ubuntu 24.04.5 LTS（x86_64）环境完整实测，文中命令与回显均为实测原样记录。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64），内核 6.8.0-138-generic
OpenClaw 版本：2026.10.6（构建号 fe06181，2026-10-22 发布的当前最新稳定版）
Node.js：24.22.1（NodeSource 24 线，满足 2026.10 版要求的 24.22.1+）
npm：11.19.1
默认端口：Gateway 监听 ws://127.0.0.1:18789，Control UI 面板 http://127.0.0.1:18789/
状态目录：~/.openclaw/（配置文件 ~/.openclaw/openclaw.json，会话与状态 SQLite 库在 ~/.openclaw/state/、~/.openclaw/agents/）
实测时间：2026-10-23

二、前置条件

一台 Ubuntu 24.04 服务器（x86_64/aarch64 均可），具备 sudo 权限；建议 2 GB 以上内存（实测 Gateway 常驻内存约 1 GB，见 8.3 节 status 回显）。
可访问外网（下载 NodeSource 源、npm 包或 Docker 镜像）；内网环境需自备代理或离线包。
已安装 curl 与 ca-certificates（一键脚本与 NodeSource 源依赖）：

sudo apt-get update
sudo apt-get install -y curl ca-certificates

一个 LLM 访问凭据（任一）：云厂商 API Key（Anthropic/OpenAI/Gemini/DeepSeek 等），或本地推理端点（Ollama/vLLM/LM Studio 的 OpenAI 兼容地址）。没有模型凭据时 onboarding 无法完成模型验证，但安装、配置加载与 Gateway 启动不受影响。
（方案 C 专用）已安装 Docker Engine 与 Docker Compose v2。

三、版本选型说明

稳定版选择：npm 的 latest tag 对应当前最新稳定版。本次实测时为 2026.10.6（查询日期 2026-10-23，来源：GitHub Releases 与 npm registry）。
运行时要求：v2026.10.6 起要求打过 2026 年 10 月安全补丁的 Node 24.22.1+（24 线）或 26.12.1+（26 线）；官方安装器在 Linux 上自动安装 Node 24 LTS，Docker 镜像内置 Node 24.22.1。旧版本 Node 会被拒绝。
版本号格式：年.月.序号（如 2026.10.6）。发布节奏约每月 4 个稳定版，另有 beta 预发布（如 2026.10.10-beta.3）与 main 跟踪通道。
Docker 镜像 tag：ghcr.io/openclaw/openclaw:latest（主registry，与 openclaw/openclaw:latest Docker Hub 镜像同步）；版本 tag 如 2026.10.6；变体有 slim、-browser（内置 Chromium，供 Gateway 托管浏览器功能）等。生产建议锁定版本 tag。

通道	标识	适用场景
稳定版	npm `latest` / 镜像 `latest` 或版本号	日常生产使用
预发布	npm `next`、`x.y.z-beta.n`	提前验证新特性
开发通道	`openclaw update --channel dev` / 镜像 `main`	跟踪主线开发

关键差异解读：稳定版与预发布通道的配置 schema 可能存在差异（OpenClaw 对配置做严格校验），生产环境锁定稳定版本号，升级前先看 Release notes。

四、方案 A：官方一键安装脚本（推荐）

4.1 方案说明

官方推荐的安装方式：脚本自动检测操作系统与发行版，按需安装 Node.js 运行时，再安装 OpenClaw npm 包，最后自动启动 onboarding 引导。适合全新服务器上快速从零到一。脚本支持 macOS、Linux 与 WSL2。

4.2 下载与执行

直接管道执行（装完自动进入 onboarding 向导）：

curl -fsSL https://openclaw.ai/install.sh | bash

服务器无人值守场景建议跳过交互式引导，先只装软件：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

实测输出（--no-onboard 方式，输出节选，实测于 Ubuntu 24.04.5）：

· Installing Node.js
✓ Node.js v24.22.1 installed
· Active Node.js: v24.22.1 (/usr/bin/node)
· Active npm: 11.19.1 (/usr/bin/npm)

[2/3] Installing OpenClaw
· Git not found, installing it now
· Updating package index
· Installing Git
✓ Git installed
· Installing OpenClaw v2026.10.6
· Installing OpenClaw package
✓ OpenClaw npm package installed
· Published openclaw bin link at /usr/bin/openclaw
✓ OpenClaw installed

[3/3] Finalizing setup

🦞 OpenClaw installed successfully (2026.10.6)!
cracks claws Alright, what are we building?

· Skipping onboard (requested); run openclaw onboard later

FAQ: https://docs.openclaw.ai/start/faq
Support: https://community.openclaw.ai/

⚠️ 注意：脚本检测到系统无 Git 时会自动安装 Git（build-essential 等编译工具链在需要源码安装时也会自动准备），因此首次运行耗时主要在 apt 下载，国内网络环境建议提前配好 apt 镜像或代理。

4.3 验证安装

openclaw --version

实测输出：

OpenClaw 2026.10.6 (fe06181)

openclaw doctor

无配置时的实测输出（doctor 会列出当前缺口与修复命令，节选）：

◇  Gateway ──────────────────────────────────────────────────────╮
│                                                                │
│  gateway.mode is unset; gateway start will be blocked.         │
│  Fix: run openclaw configure and set Gateway mode (local/remote). │
│  Or set directly: openclaw config set gateway.mode local       │
│  Missing config: run openclaw setup first.                     │
│                                                                │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  Gateway auth is off or missing a token.                       │
│  Run `openclaw doctor --fix --generate-gateway-token` to generate a │
│  token, then restart the Gateway.                              │
│                                                                │
└────────────────────────────────────────────────────────────────┘

该回显说明安装本身已成功，剩下的缺口（gateway.mode、auth token）在第八章「配置说明」中逐一补齐。

4.4 后续引导

正式启用时执行交互式 onboarding（模型凭据验证 → 工作区创建 → Gateway 配置 → 安装守护服务）：

openclaw onboard --install-daemon

五、方案 B：npm 全局包安装（自管 Node.js）

5.1 方案说明

适合已经用 NodeSource/nvm 等方式自管 Node.js 的服务器：直接从 npm 安装全局包，不引入官方安装器的运行时管理。OpenClaw 官方发布 npm 包 openclaw，Node 24.22.1+ 或 26.12.1+ 即可。

5.2 安装 Node.js 24（NodeSource 源）

系统无 Node 或版本低于 24.22.1 时，先装 Node 24 线：

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -

实测输出（尾部）：

2026-10-22 21:28:11 - To install Node.js, run: apt install nodejs -y
2026-10-22 21:28:11 - You can use N|solid Runtime as a node.js alternative
2026-10-22 21:28:11 - To install N|solid Runtime, run: apt install nsolid -y

apt-get install -y nodejs

实测输出（尾部）：

Setting up nodejs (24.22.1-1nodesource1) ...

node -v && npm -v

实测输出：

v24.22.1
11.19.1

5.3 安装 OpenClaw 全局包

npm 12 起默认拦截未批准的包生命周期脚本，全局安装需显式放行 openclaw 的 preinstall/postinstall（npm 11.16 接受该参数并仅告警；npm 11.15 及更早版本去掉该参数）：

npm install -g openclaw@latest --allow-scripts=openclaw

实测输出（尾部）：

111 packages are looking for funding
  run `npm fund` for details
npm warn install-scripts 4 packages have install scripts not yet covered by allowScripts:
npm warn install-scripts   @google/genai@2.27.0 (preinstall: echo 'preinstall: no-op')
npm warn install-scripts   esbuild@0.28.2 (postinstall: node install.js)
npm warn install-scripts   koffi@3.3.2 (install: node ./cnoke.cjs -P . -D src/koffi --prebuild --release)
npm warn install-scripts   protobufjs@7.6.6 (postinstall: node scripts/postinstall)

💡 说明：npm warn install-scripts 是 npm 11.16+ 的策略提示——这 4 个依赖包的 install 脚本未被 --allow-scripts=openclaw 覆盖，OpenClaw 主包自身的生命周期脚本已放行。实测安装与运行不受影响；如需完全消除告警，可按提示追加 --allow-scripts=@google/genai,esbuild,koffi,protobufjs。

5.4 验证安装

which openclaw && openclaw --version

实测输出：

/usr/bin/openclaw
OpenClaw 2026.10.6 (fe06181)

npm prefix -g

实测输出（全局包前缀，openclaw 可执行文件即在其 bin 目录下）：

/usr

六、方案 C：官方 Docker 镜像部署

6.1 方案说明

官方在 GitHub Container Registry（ghcr.io）发布预构建镜像（Docker Hub 同步镜像 openclaw/openclaw），内置 Node 24.22.1 运行时，适合无本地安装诉求的隔离部署与滚动升级。镜像入口为 node /app/docker-entrypoint.mjs，默认命令即启动 Gateway（node openclaw.mjs gateway）。基础镜像为 node:24.22.1-bookworm-slim。

6.2 拉取镜像

docker pull ghcr.io/openclaw/openclaw:latest

实测输出（尾部）：

Digest: sha256:7dbff0fe5f5359b1badefe90a23efa9f203cd0d3c36bee095f4896c7a1d3864b
Status: Downloaded newer image for ghcr.io/openclaw/openclaw:latest
ghcr.io/openclaw/openclaw:latest

版本核对（容器内 CLI 打印版本号）：

docker run --rm --entrypoint node ghcr.io/openclaw/openclaw:latest openclaw.mjs --version

实测输出：

OpenClaw 2026.10.6 (fe06181)

6.3 准备状态目录并启动 Gateway

Gateway 的配置与会话状态都落在容器内 /home/node/.openclaw，用宿主目录持久化（容器内进程以 node 用户 uid=1000 运行，目录属主需与之匹配）：

mkdir -p /opt/openclaw/state
chown -R 1000:1000 /opt/openclaw/state

⚠️ 排障实录：若省略 chown，让容器以 root 属主的目录挂载启动，Gateway 进入维护流程时会报权限错误（实测回显）：
Doctor could not enter maintenance. failed to acquire gateway state ownership | EACCES: permission denied, mkdir '/home/node/.openclaw/tmp/openclaw-1000' | EACCES (code=EACCES). Check ownership and write permissions for the reported lock path under the OpenClaw user; containers need a writable state mount.
处理：在宿主机执行 chown -R 1000:1000 /opt/openclaw/state 后重启容器即可。

启动 Gateway 容器（OPENCLAW_GATEWAY_TOKEN 为控制面访问令牌，浏览器接入 Control UI 时使用）：

docker run -d \
  --name openclaw-gateway \
  --restart unless-stopped \
  -p 18789:18789 \
  -e OPENCLAW_GATEWAY_TOKEN="oc_docker_q1w2e3r4" \
  -v /opt/openclaw/state:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest

6.4 首次启动的配置引导

空状态目录首次启动时，镜像入口会先做初始化检查。实测日志显示启动被保守拦截（该设计防止把被清空/损坏的配置当作正常状态）：

Gateway start blocked: existing config is missing gateway.mode. Treat this as suspicious or clobbered config. Re-run `openclaw onboard --mode local` or `openclaw setup`, set gateway.mode=local manually, or pass --allow-unconfigured.

处理方法（二选一）：

方法一：用一次性容器向同一状态目录写入最小配置，再重启 Gateway 容器：

docker run --rm \
  -v /opt/openclaw/state:/home/node/.openclaw \
  --entrypoint node \
  ghcr.io/openclaw/openclaw:latest \
  openclaw.mjs config set gateway.mode local

实测输出：

Updated gateway.mode. Restart the gateway to apply.

方法二：启动命令追加 --allow-unconfigured 参数放行未配置启动（仅建议调试场景使用）。

写入配置后重启并验证：

docker restart openclaw-gateway
docker logs openclaw-gateway

实测日志（节选）：

2026-10-22T21:53:08.641+00:00 [gateway] ready

6.5 验证 Control UI

宿主机访问映射端口：

curl -si http://127.0.0.1:18789/ | head -3

实测输出：

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer

HTTP 200 即 Control UI 就绪；浏览器打开 http://<服务器IP>:18789/，在 Settings 中粘贴 OPENCLAW_GATEWAY_TOKEN 完成接入。

七、方案对比与选择建议

维度	方案 A：一键脚本	方案 B：npm 全局包	方案 C：Docker 镜像
运行时	脚本自动装 Node 24 LTS	自管 Node（≥24.22.1）	镜像内置 Node 24.22.1
需要联网	是（下载脚本/Node/npm 包）	是（npm 包）	是（拉镜像，可离线导入）
安装耗时（实测）	约 5–8 分钟（含 Git/apt）	约 2–3 分钟	拉镜像后秒级启动
服务托管	配合 `openclaw onboard --install-daemon`	`openclaw gateway install`（systemd）	`--restart unless-stopped`
升级方式	`openclaw update` 或重跑脚本	`npm install -g openclaw@latest`	换镜像 tag 重建容器
状态位置	`~/.openclaw/`	`~/.openclaw/`	挂载卷 `/home/node/.openclaw`
适用场景	新服务器快速起步	已有 Node 技术栈	隔离部署/无本地安装诉求

关键差异解读：能联网的新服务器首选方案 A（全自动、含 onboarding）；运维上要求环境隔离、用统一容器平台管理的选方案 C；对 Node 版本有统一管控的团队用方案 B。三者状态目录结构一致，迁移只需搬 ~/.openclaw/（或挂载卷）。

八、配置说明与 systemd 服务托管

8.1 最小可运行配置

方案 A/B 安装后，用 config 子命令写入三处最小配置（交互式向导为 openclaw onboard / openclaw configure）：

openclaw config set gateway.mode local
openclaw config set gateway.auth.token "oc_test_2026_q1w2e3r4"
openclaw config set agents.defaults.workspace "/root/.openclaw/workspace"

实测输出（逐条）：

Updated gateway.mode. Restart the gateway to apply.

Updated gateway.auth.token. Restart the gateway to apply.

Updated agents.defaults.workspace. Change will apply without restarting the gateway.

配置文件位置与内容确认：

openclaw config file
cat ~/.openclaw/openclaw.json

实测输出：

/root/.openclaw/openclaw.json

{
  "gateway": {
    "mode": "local",
    "auth": {
      "token": "oc_test_2026_q1w2e3r4"
    }
  },
  "plugins": {
    "entries": {
      "anthropic": {
        "config": {
          "sessionCatalog": {
            "enabled": false
          }
        }
      },
      "codex": {
        "config": {
          "sessionCatalog": {
            "enabled": false
          }
        }
      }
    }
  },
  "meta": {
    "migrations": {
      "modelPolicyAllowlist": true,
      "utilityModelSeparation": true
    },
    "lastTouchedVersion": "2026.10.6"
  },
  "agents": {
    "defaults": {
      "workspace": "/root/.openclaw/workspace"
    }
  }
}

逐项说明：gateway.mode=local 表示本机自用模式（Gateway 只绑本机回环）；gateway.auth.token 是控制面访问令牌（Control UI 与 CLI 连接 Gateway 时鉴权用，示例为测试值，生产请用 openclaw doctor --fix --generate-gateway-token 生成随机强令牌）；agents.defaults.workspace 指定主 Agent 工作区；plugins.entries 与 meta 由 OpenClaw 自动写入（内置插件声明与迁移标记），无需手改。

8.2 前台启动与验证

先以前台方式验证 Gateway 能正常拉起：

openclaw gateway run

实测日志（节选，启动约 8 秒后就绪）：

2026-10-22T21:30:13.839+00:00 [gateway] ready
2026-10-22T21:30:15.374+00:00 [gateway] remote model catalog applied

另开一个终端做三连验证：

openclaw gateway status

实测输出（节选）：

Config (cli): ~/.openclaw/openclaw.json
Gateway: bind=loopback (127.0.0.1), port=18789 (env/config)
Check target: ws://127.0.0.1:18789
Dashboard: http://127.0.0.1:18789/
CLI version: 2026.10.6 (/usr/bin/openclaw)
Gateway version: 2026.10.6
Connectivity check: ok
Capability: connected-no-operator-scope

openclaw health

实测输出：

Gateway event loop: ok max=21ms p99=21ms util=0.018 cpu=0.023
Gateway check duration: 11ms
Agents: main (default)
Heartbeat interval: 30m (main)
Session store (main): /root/.openclaw/agents/main/agent/openclaw-agent.sqlite (0 entries)

curl -si http://127.0.0.1:18789/ | head -1

实测输出：

HTTP/1.1 200 OK

8.3 systemd 用户服务托管（长期运行）

OpenClaw 官方把 Gateway 托管为 systemd 用户服务（user service），一条命令完成安装：

openclaw gateway install

实测输出：

Installed systemd service: /root/.config/systemd/user/openclaw-gateway.service
Gateway service installed. Runtime readiness has not been checked; startup may still be in progress. Check with openclaw gateway status and openclaw health.

服务单元文件内容（/root/.config/systemd/user/openclaw-gateway.service，实测原样）：

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target
StartLimitBurst=10
StartLimitIntervalSec=300

[Service]
ExecStart=/usr/bin/node --max-old-space-size=8192 /usr/lib/node_modules/openclaw/dist/index.js gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=330
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=mixed
Environment=HOME=/root
Environment=TMPDIR=/tmp
Environment=PATH=/usr/bin:/bin:/usr/local/bin:/root/.local/bin:/root/.npm-global/bin:/root/bin:/root/.nix-profile/bin
Environment=NODE_OPTIONS=
Environment=OPENCLAW_GATEWAY_PORT=18789
Environment=OPENCLAW_SYSTEMD_UNIT=openclaw-gateway.service
Environment="OPENCLAW_WINDOWS_TASK_NAME=OpenClaw Gateway"
Environment=OPENCLAW_WINDOWS_TASK_HIDDEN_LAUNCHER=1
Environment=OPENCLAW_SERVICE_MARKER=openclaw
Environment=OPENCLAW_SERVICE_KIND=gateway

[Install]
WantedBy=default.target

要点说明：ExecStart 带 --max-old-space-size=8192（V8 老生代上限 8 GB，按需调小）；Restart=always + RestartSec=5 崩溃自动拉起；TimeoutStopSec=330 给会话收尾留足时间。

服务器上以 root/专用用户运行用户服务时，需开启 lingering 让服务在无登录会话时也保持运行，然后启动服务：

loginctl enable-linger root
systemctl --user daemon-reload
systemctl --user start openclaw-gateway.service

验证服务状态：

systemctl --user status openclaw-gateway.service --no-pager

实测输出（节选）：

● openclaw-gateway.service - OpenClaw Gateway
     Loaded: loaded (/root/.config/systemd/user/openclaw-gateway.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-10-22 21:34:03 UTC; 20s ago
   Main PID: 5456 (MainThread)
      Tasks: 46 (limit: 94371)
     Memory: 1020.7M (peak: 1.2G)
        CPU: 15.409s
        ├─5456 /usr/bin/node --max-old-space-size=8192 /usr/lib/node_modules/openclaw/dist/index.js gateway --port 18789

再从 OpenClaw 侧确认服务已被识别（Service: systemd user (enabled)）：

openclaw gateway status

实测输出（节选）：

Service: systemd user (enabled)
Gateway: bind=loopback (127.0.0.1), port=18789 (service args)
Gateway version: 2026.10.6
Connectivity check: ok

💡 说明：实测 Gateway 稳定运行时内存约 1 GB（峰值 1.2 GB），生产服务器建议预留 2 GB 内存给 Gateway 进程。日常运维命令：systemctl --user stop|restart|status openclaw-gateway；查看日志用 journalctl --user -u openclaw-gateway -f 或 openclaw logs --follow。

8.4 升级与版本管理

openclaw update --channel stable

或按安装方式手动升级：npm 方案重跑 npm install -g openclaw@latest --allow-scripts=openclaw；Docker 方案改用新版本 tag 重建容器（挂载同一状态卷，入口会自动执行 openclaw doctor --fix 迁移检查）。升级前建议备份状态目录：

tar czf /root/openclaw-backup-$(date +%F).tgz -C /root .openclaw

九、常见问题（FAQ）

Q1：openclaw gateway status 显示 Config (cli): ... (invalid)，提示 agents.entries must contain at least one configured agent？ 这是配置校验器认为没有显式配置任何 agent 条目（默认 agent main 由系统隐式创建，不影响启动）。按官方修复流处理：

openclaw doctor --fix --non-interactive

实测修复后回显：

└  Doctor complete.

再次 openclaw gateway status，Config (cli) 后的 (invalid) 标记消失。

Q2：openclaw doctor --fix 报 GatewayStateOwnerContentionError？ 实测回显：

Doctor could not enter maintenance. GatewayStateOwnerContentionError: OpenClaw state database is busy at /root/.openclaw/state/openclaw.sqlite. holder 4019 at openclaw-server/pid-ns 4026533093, last renewed 3 s ago. The holder 4019 is alive on this host, stop it first.

原因：Gateway 正在运行并持有状态库的维护锁。doctor 的写修复需要独占维护权。处理顺序：先停 Gateway（systemctl --user stop openclaw-gateway 或停掉手工启动的 openclaw gateway run 进程），再执行 openclaw doctor --fix，完成后重新启动服务。

Q3：openclaw: command not found？ npm 全局 bin 目录不在 PATH。定位方法（官方文档同款排查命令）：

node -v
npm prefix -g
echo "$PATH"

把 $(npm prefix -g)/bin 加入 PATH，或重开 shell。实测 NodeSource 安装路径下 openclaw 落在 /usr/bin/openclaw，通常无需手工调整。

Q4：Gateway 启动日志报 Gateway start blocked: existing config is missing gateway.mode？ 配置缺 gateway.mode 时启动被保守拦截（防误用被清空的配置）。补齐配置即可：openclaw config set gateway.mode local（Docker 方案见 6.4 节的一次性容器写法），然后重启 Gateway。

Q5：gateway.mode is unset; gateway start will be blocked（doctor 提示）？ 同 Q4 根因。首次配置三部曲见 8.1 节；令牌缺失时可用 openclaw doctor --fix --generate-gateway-token 自动生成并写入。

Q6：npm 安装时报 npm warn install-scripts ...？ npm 11.16+/12 的供应链安全策略提示，非错误。--allow-scripts=openclaw 已放行主包脚本，其余告警包见 5.3 节说明，可按需追加放行。

Q7：Gateway 端口 18789 被占用？ 修改配置里的端口并重启：openclaw config set gateway.port 19001 --strict-json，Docker 方案改 -p <宿主端口>:18789 映射即可，容器内端口不必改。

十、卸载与清理

按安装方式卸载软件本体，再清理状态目录。

方案 A/B（npm 安装）：

openclaw gateway uninstall   # 移除 systemd 用户服务（如已安装）
npm uninstall -g openclaw

方案 C（Docker）：

docker rm -f openclaw-gateway

清理状态与配置（所有方案通用，执行前确认备份）：

rm -rf ~/.openclaw

Docker 方案另需删除宿主状态目录：

rm -rf /opt/openclaw/state

十一、参考链接

官方安装文档：https://docs.openclaw.ai/install
Docker 部署文档：https://docs.openclaw.ai/install/docker
onboarding/CLI 参考：https://docs.openclaw.ai/cli
配置文档：https://docs.openclaw.ai/gateway/configuration
GitHub 仓库：https://github.com/openclaw/openclaw
npm 包页：https://www.npmjs.com/package/openclaw
本站认知篇：《OpenClaw 介绍与选型指南》