Ubuntu 下安装 OpenClaw 并配置安全访问

环境准备

操作系统：Ubuntu 20.04 / 22.04 / 24.04（本文以 24.04 为例）
权限：需要使用 root 或拥有 sudo 权限的用户
网络：能够访问 GitHub 及 npm 源（建议使用国内镜像加速）

一、升级 Node.js 至 v22+

OpenClaw 要求 Node.js 版本≥22.0.0，低版本会导致 npm 安装失败。若系统已安装其他版本，请务必升级。

方法一：使用 nvm（推荐，便于多版本管理）

1. 安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重新加载环境变量：

source ~/.bashrc # 若使用 bash
# source ~/.zshrc # 若使用 zsh

2. 安装 Node.js v22 并设为默认

nvm install 22
nvm alias default 22
nvm use 22

3. 验证版本

node -v # 应显示 v22.x.x
npm -v # 检查 npm 版本

方法二：使用 NodeSource 官方仓库（系统级安装）

如果你希望直接覆盖系统 Node 版本，可以使用以下命令（以 Ubuntu/Debian 为例）：

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

CentOS/RHEL 用户请使用：

curl -fsSL https://rpm.nodesource.com/setup_22.x | bash -
yum install -y nodejs

方法三：手动下载二进制包

从 Node.js 官网下载 Linux 二进制包，解压后配置 PATH 即可。

二、安装 OpenClaw

1. 一键安装（官方推荐）

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

若网络不稳定，也可以直接使用 npm 全局安装（避免脚本问题）：

npm install -g openclaw@latest

2. 验证安装

openclaw --version

出现版本号即表示安装成功。

3. 初始化配置

openclaw onboard

此命令将引导你完成基础配置，包括：

选择 AI 模型（可跳过，后续添加）
配置聊天渠道（如 Telegram、飞书等，可跳过）
安装基础技能（建议全选）

跳过模型配置： 若暂时没有 API Key，可以选择跳过，后续随时补充。

在这里插入图片描述

选择 Open the Web UI：

在这里插入图片描述

4. 修改配置文件以实现外部访问

OpenClaw 默认只监听本地（127.0.0.1），如需从局域网其他设备访问 Web 控制台，需修改配置文件。

配置文件位于 ~/.openclaw/openclaw.json，编辑该文件：

nano ~/.openclaw/openclaw.json

找到 gateway 部分，将 bind 的值改为 "lan"（监听所有网络接口），并确保端口为 18789。

在这里插入图片描述

修改后重启 Gateway 服务：

openclaw gateway restart

5. 防火墙放行端口

根据你的防火墙工具，开放 18789 端口（注意：生产环境建议限制来源 IP）：

# ufw
ufw allow 18789/tcp

# firewalld
firewall-cmd --add-port=18789/tcp --permanent && firewall-cmd --reload

# iptables
iptables -A INPUT -p tcp --dport 18789 -j ACCEPT

验证监听状态：

ss -untlp | grep 18789

应显示类似 0.0.0.0:18789 的监听记录。

在这里插入图片描述

6. 安全访问：使用 SSH 隧道（推荐）

由于 Web 控制台基于 HTTP 且未配置 HTTPS，直接暴露可能带来安全风险。最安全的方式是通过 SSH 隧道将远程端口映射到本地。

在宿主机（你的物理机）上执行：

ssh -L 8888:localhost:18789 root@<虚拟机 IP>

在这里插入图片描述

8888：本地监听端口，可自定义
<虚拟机 IP>：Ubuntu 虚拟机的实际 IP 地址

保持此终端窗口打开，然后打开宿主机浏览器，访问 http://localhost:8888。此时相当于本地访问，完美满足浏览器的'安全上下文'要求，且所有流量均通过 SSH 加密。

在这里插入图片描述

优点：无需修改 OpenClaw 配置、无需开放防火墙、流量加密。缺点：每次访问需保持 SSH 连接。

三、常见问题与解决

Q1：安装时 npm 报错'node-domexception'等警告

这是正常现象，不影响使用，可忽略。

Q2：无法从外部访问 Web 控制台

检查 bind 是否设置为 "lan" 或 "0.0.0.0"（注意新版需用 lan 模式）。
确认防火墙已放行 18789 端口。
尝试使用 SSH 隧道方式。

Q3：浏览器报'origin not allowed'

在配置文件中添加 controlUi.allowedOrigins，例如：

"controlUi": {"allowedOrigins": ["http://你的宿主机 IP:18789"]}

然后重启 Gateway。

Q4：浏览器提示'需要安全上下文'

这是因为通过 HTTP 访问非本地地址。解决方案：

使用 SSH 隧道（推荐）
或配置 HTTPS（如使用 Tailscale Serve）
或在配置中设置 allowInsecureAuth: true（仅限测试环境）

四、进阶：配置模型与技能

1. 添加 AI 模型密钥

通过 Web 控制台或命令行添加：

openclaw config set models.providers.openai.apiKey sk-xxxxxx
openclaw models set openai/gpt-4

2. 安装新技能

使用官方工具 clawhub：

npm install -g clawhub
clawhub install tavily-search # 安装联网搜索技能

3. 使用本地模型

如果你有本地部署的模型（如 Ollama、vLLM），可通过自定义模型提供商接入，参考官方文档。

五、总结

通过本文，你已经在 Ubuntu 上成功搭建了 OpenClaw AI 助理，并掌握了通过 SSH 隧道安全访问 Web 控制台的方法。OpenClaw 的强大之处在于其可扩展性——你可以随时添加新技能、接入不同模型，甚至开发自己的插件。

友情提示：建议创建普通用户运行 OpenClaw，避免使用 root 带来安全风险。

Ubuntu 下安装 OpenClaw 并配置安全访问