OpenClaw 安装配置指南 v3

by zhengshun
on 8 3 月, 2026

文档版本：v3.0
适用系统：Ubuntu 24.04 LTS
适用版本：OpenClaw 2026.3.2
基于：生产服务器的完整部署实践

⚠️ v3 版本关键变更说明

与 v2 版本相比，v3 版本有以下重要更新：

变更项v2 版本v3 版本（实际部署）
Web UI 访问方式本地访问SSH 隧道 + Token 认证
Gateway Token未明确说明必须配置，用于 Web UI 认证
访问地址http://服务器IP:18789http://localhost:18888（通过SSH隧道）
公网访问尝试配置 allowedOrigins确认不可行（mode仅支持local/remote）
端口绑定127.0.0.1仅本地监听，必须通过隧道访问

核心发现 1：OpenClaw 2026.3.2 的 gateway.mode 仅支持 "local" 或 "remote"，不支持 "lan" 模式，无法直接通过公网 IP 访问 Web UI。

核心发现 2：必须通过 SSH 隧道将服务器的 127.0.0.1:18789 映射到本地端口，然后在浏览器中输入 Gateway Token 进行认证。

目录

  1. 服务器环境信息
  2. 系统准备
  3. Node.js 安装
  4. OpenClaw 安装
  5. 模型配置（阿里云百炼）
  6. 用户级 systemd 服务配置（关键）
  7. SSH 隧道访问配置（v3 新增）
  8. Gateway Token 配置（v3 新增）
  9. 服务管理
  10. 配置文件参考
  11. 故障排查
  12. 常见问题

一、服务器环境信息

1.1 当前生产环境

环境项实际值
服务器 IP
SSH 端口22
SSH 密码（部署时使用）
操作系统Ubuntu 24.04.4 LTS (Noble Numbat)
OpenClaw 版本2026.3.2 (85377a2)
Node.js 版本v22.22.0
npm 安装路径/usr/lib
OpenClaw 执行路径/usr/bin/openclaw
配置目录/root/.openclaw/
用户级服务文件/root/.config/systemd/user/openclaw-gateway.service
内存3.8 GiB（使用约 400MB）
存储30GB SSD（已用约 8GB）

1.2 系统要求

配置项最低要求推荐配置
CPU2 核2 核及以上
内存2 GB4 GB 及以上（推荐）
存储20 GB SSD40 GB SSD 及以上
操作系统Ubuntu 20.04+Ubuntu 24.04 LTS
Node.jsv22.0.0+v22 LTS（已验证 v22.22.0）
网络稳定互联网连接推荐海外节点

二、系统准备

2.1 更新系统

apt update
apt upgrade -y

2.2 安装基础依赖

apt install -y curl git build-essential wget gnupg vim ca-certificates software-properties-common

三、Node.js 安装

3.1 使用 NodeSource 安装（推荐）

# 下载并执行 NodeSource 安装脚本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js 22
apt install -y nodejs

3.2 验证安装

node --version
# 预期输出：v22.22.0 或更高

npm --version
# 预期输出：10.x.x

四、OpenClaw 安装

4.1 npm 全局安装

npm install -g openclaw@latest

安装完成后，OpenClaw 会被安装到 /usr/lib/，可执行文件位于 /usr/bin/openclaw。

4.2 验证安装

openclaw --version
# 预期输出：2026.3.2

4.3 运行初始化向导

openclaw onboard

注意：不建议使用 --install-daemon 参数，该参数会安装系统级 systemd 服务，而在 2026.3.2 版本中存在 Bug，必须改用用户级服务。

五、模型配置（阿里云百炼）

5.1 API 接入信息

配置项值
baseUrlhttps://coding.dashscope.aliyuncs.com/v1
api 类型openai-completions
默认主模型bailian/qwen3.5-plus

5.2 已配置模型列表

模型 ID上下文窗口最大 Token支持输入
qwen3.5-plus1,000,00065,536文本 + 图片
qwen3-max-2026-01-23262,14465,536文本
qwen3-coder-plus1,000,00065,536文本

5.3 完整 openclaw.json 配置

vim ~/.openclaw/openclaw.json

写入以下内容（将 YOUR_API_KEY 替换为实际的 API Key）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "YOUR_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-max-2026-01-23",
            "name": "qwen3-max-2026-01-23",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 262144,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-plus",
            "name": "qwen3-coder-plus",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      },
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "YOUR_GENERATED_TOKEN"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    },
    "port": 18789
  },
  "meta": {
    "lastTouchedVersion": "2026.3.2",
    "lastTouchedAt": "2026-03-05T12:00:00.000Z"
  }
}

注意：YOUR_GENERATED_TOKEN 需要替换为自动生成的随机字符串，可以使用 openssl rand -hex 24 生成。

六、用户级 systemd 服务配置（关键）

6.1 创建用户级 systemd 服务

# 创建目录
mkdir -p /root/.config/systemd/user/

# 创建用户级服务文件（使用 gateway run，不是 gateway start）
cat > /root/.config/systemd/user/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway (v2026.3.2)
After=network.target

[Service]
Type=simple
Environment=XDG_RUNTIME_DIR=/run/user/0
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus
ExecStart=/usr/bin/openclaw gateway run
Restart=on-failure
RestartSec=10
StartLimitInterval=60
StartLimitBurst=3

[Install]
WantedBy=default.target
EOF

# 设置权限
chmod 644 /root/.config/systemd/user/openclaw-gateway.service

6.2 启用并启动用户级服务

# 设置必要的环境变量
export XDG_RUNTIME_DIR=/run/user/0

# 重载用户级 systemd 配置
systemctl --user daemon-reload

# 启用服务（开机自启）
systemctl --user enable openclaw-gateway.service

# 启动服务
systemctl --user start openclaw-gateway.service

6.3 验证服务状态

# 检查服务状态（正常应显示 active (running)）
systemctl --user status openclaw-gateway.service

正常输出示例：

● openclaw-gateway.service - OpenClaw Gateway (v2026.3.2)
     Loaded: loaded (/root/.config/systemd/user/openclaw-gateway.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-03-05 09:44:29 UTC; 20s ago
   Main PID: 32870 (openclaw)
      Tasks: 18 (limit: 4601)
     Memory: 389.1M (peak: 410.2M)
        CPU: 5.252s
     CGroup: /user.slice/user-0.slice/user@0.service/app.slice/openclaw-gateway.service
             ├─32870 openclaw
             └─32877 openclaw-gateway

6.4 关键说明

⚠️ 重要：ExecStart 必须使用 openclaw gateway run，而不能使用 openclaw gateway start。

  • gateway run：直接在前台运行网关进程，适合作为 systemd 服务的 ExecStart
  • gateway start：尝试通过 systemd 启动服务，在服务内部调用会导致无限循环

七、SSH 隧道访问配置（v3 新增）

7.1 为什么需要 SSH 隧道

OpenClaw 2026.3.2 的 gateway.mode 仅支持两种模式：

  • "local" – 仅监听 127.0.0.1（本地）
  • "remote" – 远程模式（需要额外配置）

不支持 "lan" 模式，无法直接通过公网 IP 访问 Web UI。因此必须通过 SSH 隧道将服务器的本地端口映射到本地电脑。

7.2 建立 SSH 隧道

在本地电脑（Windows PowerShell 或 macOS/Linux 终端）执行：

# 将服务器的 127.0.0.1:18789 映射到本地的 18888 端口
ssh -L 18888:127.0.0.1:18789 root@154.**.***.68

输入服务器密码后，保持 SSH 连接窗口打开。

7.3 验证隧道建立

在本地新开一个终端窗口执行：

# Windows
netstat -an | findstr 18888

# macOS/Linux
netstat -an | grep 18888
# 或
lsof -i :18888

如果显示 LISTENING 或 LISTEN，说明隧道已建立。

7.4 浏览器访问

打开浏览器，访问：

http://localhost:18888

八、Gateway Token 配置（v3 新增）

8.1 什么是 Gateway Token

OpenClaw Web UI 需要 Token 认证才能访问。首次访问时会显示错误：

unauthorized: gateway token missing (open the dashboard URL and paste the token in Control UI settings)

8.2 获取 Gateway Token

在服务器上执行：

# 查看配置文件中的 token
cat ~/.openclaw/openclaw.json | grep -A 3 '"auth"'

或者使用 Python 提取：

python3 -c "import json; d=json.load(open('/root/.openclaw/openclaw.json')); print(d.get('gateway',{}).get('auth',{}).get('token','not found'))"

示例 Token（实际部署时生成）：

b5f91ba8ec7cb41469bb14ddc3c76a24342c15f942adebd3

8.3 在 Web UI 中输入 Token

  1. 打开浏览器访问 http://localhost:18888
  2. 在页面上找到 “Control UI settings” 或设置图标
  3. 在 Gateway Token 输入框中粘贴 Token
  4. 点击保存/应用

8.4 通过 URL 参数直接访问

也可以在 URL 中直接添加 token 参数：

http://localhost:18888?token=b5f91ba8ec7cb41469bb14ddc3c76a24342c15f942adebd3

九、服务管理

9.1 日常管理命令

# 必须先设置此环境变量
export XDG_RUNTIME_DIR=/run/user/0

# 查看服务状态
systemctl --user status openclaw-gateway.service

# 启动服务
systemctl --user start openclaw-gateway.service

# 停止服务
systemctl --user stop openclaw-gateway.service

# 重启服务
systemctl --user restart openclaw-gateway.service

# 查看实时日志
journalctl --user -u openclaw-gateway.service -f

# 查看最近 50 条日志
journalctl --user -u openclaw-gateway.service -n 50 --no-pager

9.2 端口检查

# 确认 Gateway 监听的端口
ss -tlnp | grep openclaw

# 预期输出：
# LISTEN 0 511 127.0.0.1:18789 ... openclaw-gateway

十、配置文件参考

10.1 最终 openclaw.json 配置

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-sp-e6*************************d03ce",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-max-2026-01-23",
            "name": "qwen3-max-2026-01-23",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 262144,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-plus",
            "name": "qwen3-coder-plus",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0 },
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      },
      "compaction": {
        "mode": "safeguard"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "b5f91ba8ec7cb41469bb14ddc3c76a24342c15f942adebd3"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    },
    "port": 18789
  },
  "meta": {
    "lastTouchedVersion": "2026.3.2",
    "lastTouchedAt": "2026-03-05T12:00:00.000Z"
  }
}

10.2 用户级服务文件

[Unit]
Description=OpenClaw Gateway (v2026.3.2)
After=network.target

[Service]
Type=simple
Environment=XDG_RUNTIME_DIR=/run/user/0
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus
ExecStart=/usr/bin/openclaw gateway run
Restart=on-failure
RestartSec=10
StartLimitInterval=60
StartLimitBurst=3

[Install]
WantedBy=default.target

十一、故障排查

11.1 问题：服务启动失败，显示 “Config invalid”

现象：日志中出现 Config invalid，提示 gateway.mode: Invalid input (allowed: "local", "remote")

原因：尝试使用 "lan" 或其他不支持的 mode 值。

解决：确保 gateway.mode 只能是 "local" 或 "remote"：

{
  "gateway": {
    "mode": "local"
  }
}

11.2 问题：无法通过公网 IP 访问 Web UI

现象：浏览器访问 http://154.**.***.68:18789 失败

原因：OpenClaw 2026.3.2 仅支持 local 模式，只监听 127.0.0.1。

解决：必须使用 SSH 隧道访问，详见第七节。

11.3 问题：Web UI 显示 “gateway token missing”

现象：页面加载后显示未授权错误

原因：需要在 Web UI 中输入 Gateway Token 进行认证。

解决：获取 Token 并在页面设置中输入，详见第八节。

11.4 问题：SSH 隧道端口被占用

现象：bind [127.0.0.1]:18888: Address already in use

原因：本地端口 18888 已被其他程序占用。

解决：更换本地端口：

ssh -L 18889:127.0.0.1:18789 root@154.**.***.68

然后访问 http://localhost:18889

11.5 问题：SSH 连接警告 “REMOTE HOST IDENTIFICATION HAS CHANGED”

现象：SSH 连接时显示主机密钥变更警告

原因：服务器重置后 SSH 密钥已变更。

解决：清理本地 known_hosts：

# Windows PowerShell
ssh-keygen -R 154.**.***.68

# 然后重新连接
ssh -L 18888:127.0.0.1:18789 root@154.**.***.68

十二、常见问题

Q1: 如何生成 Gateway Token？

# 使用 openssl 生成随机 token
openssl rand -hex 24

# 或使用 Python
python3 -c "import secrets; print(secrets.token_hex(24))"

Q2: 是否可以配置公网直接访问？

不可以。OpenClaw 2026.3.2 的 gateway.mode 仅支持 "local" 和 "remote"，不支持 "lan" 模式。即使配置 allowedOrigins 为公网 IP，也无法绕过此限制。

Q3: 如何查看当前 Token？

python3 -c "import json; d=json.load(open('/root/.openclaw/openclaw.json')); print(d.get('gateway',{}).get('auth',{}).get('token','not found'))"

Q4: SSH 隧道断开后如何重新连接？

直接重新执行 SSH 命令即可：

ssh -L 18888:127.0.0.1:18789 root@154.**.***.68

Q5: 如何更新 OpenClaw？

# 停止服务
export XDG_RUNTIME_DIR=/run/user/0
systemctl --user stop openclaw-gateway.service

# 更新
npm install -g openclaw@latest

# 重启服务
systemctl --user start openclaw-gateway.service

# 确认版本
openclaw --version

附录

A. 与 v2 版本的完整差异对照

章节v2 版本v3 版本
Web UI 访问尝试公网访问SSH 隧道 + Token 认证
Gateway mode尝试 "lan" 模式仅支持 "local" 模式
端口绑定尝试 0.0.0.0仅 127.0.0.1
访问地址http://服务器IP:18789http://localhost:18888
认证方式未明确必须输入 Gateway Token
SSH 隧道未提及新增完整配置指南

B. 快速部署检查清单

部署完成后，按以下顺序验证：

# 1. 确认服务运行
export XDG_RUNTIME_DIR=/run/user/0
systemctl --user status openclaw-gateway.service

# 2. 确认端口监听
ss -tlnp | grep 18789

# 3. 本地 curl 测试
curl -s http://127.0.0.1:18789 | head -5

# 4. 获取 Gateway Token
python3 -c "import json; d=json.load(open('/root/.openclaw/openclaw.json')); print(d.get('gateway',{}).get('auth',{}).get('token','not found'))"

本地电脑：

# 5. 建立 SSH 隧道
ssh -L 18888:127.0.0.1:18789 root@154.**.***.68

# 6. 浏览器访问
http://localhost:18888

# 7. 输入 Gateway Token

C. 资源链接

文档结束

Categories:

AI

Tags:

AI

No responses yet

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

🛡️ 闽ICP备2024065179号-3