OpenClaw AI Agent在Ubuntu 22.04的部署指南：从Node.js配置到Web UI访问

OpenClaw 是一个可以接入 Telegram / Discord / 飞书 / Slack / WhatsApp 等聊天平台 的 AI Agent 框架，非常适合用来构建自己的跨平台AI助手。

本教程将手把手带你在 Ubuntu 系统上完成 OpenClaw 的完整部署，主要内容包括：

• 环境准备与系统更新
• Node.js 安装与配置
• OpenClaw 一键安装脚本执行
• 初始化配置流程详解
• Web UI 访问及远程连接方法
• 常见问题（如PATH配置）的解决方案

---

一、环境信息

测试环境：

项目	配置
系统	Ubuntu 22.04 LTS
CPU	4 Core
内存	8 GB
网络	100 Mbps
Node	v24 LTS

建议配置：

• 最低配置：2核4G
• 推荐配置：4核8G

---

二、安装依赖

1. 更新系统

首先，更新系统的软件包源列表，确保能获取到最新的软件信息。

sudo apt update

2. 安装 curl

curl 是后续下载安装脚本和 Node.js 所必需的工具。

sudo apt install -y curl

安装完成后，可以验证一下：

curl --version

3. 安装 Node.js（LTS版本）

OpenClaw 基于 Node.js 运行，因此需要先安装 Node.js 环境。推荐使用 NodeSource 官方仓库 来安装最新的 LTS（长期支持）版本，以获得更好的稳定性和兼容性。

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

安装完成后，使用以下命令验证 Node.js 和 npm（Node.js 的包管理器）的版本：

node -v
npm -v

预期会看到类似以下的输出，版本号可能因时间略有不同：

node v24.14.0
npm 11.9.0

4. 设置 npm 国内镜像（推荐）

如果你的服务器位于国内，直接从官方 npm 仓库下载包可能会非常缓慢。为此，建议将 npm 的源切换到国内镜像，例如 npmmirror.com。

npm config set registry https://registry.npmmirror.com

执行以下命令检查配置是否生效：

npm config get registry

如果返回 https://registry.npmmirror.com，说明镜像配置成功。

---

三、安装 OpenClaw

环境准备就绪后，就可以通过官方提供的一键安装脚本来安装 OpenClaw 了。这个脚本会自动处理大部分繁琐的配置工作。

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

整个安装流程通常是自动化的，包括：

1. 检测现有的 Node.js 环境。
2. 配置 npm 的全局安装目录。
3. 通过 npm 全局安装 OpenClaw 核心包。
4. 运行初始化配置向导。
5. 创建并启用 systemd 用户服务，以便 OpenClaw 可以随系统启动。

安装成功时，你会在终端看到类似 🦞 OpenClaw installed successfully 的提示。

---

四、初始化配置

安装脚本运行完毕后，会自动进入 OpenClaw onboarding（初始化）流程。你需要根据提示完成以下几项核心配置：

1. 选择运行模式

系统会询问你选择哪种启动模式。对于首次使用的用户，选择 QuickStart 即可。

QuickStart

2. Gateway（网关）配置

这里配置 OpenClaw 核心服务的访问方式。通常保持默认设置即可。

• Port（端口）: 18789 (后续通过这个端口访问Web UI)
• Bind（绑定地址）: 127.0.0.1 (默认只允许本地访问，远程访问需通过SSH转发)
• Auth（认证方式）: Token (使用令牌认证，更安全)

3. 选择并配置 AI 模型

OpenClaw 支持多种大模型提供商。你需要选择一个，并输入对应的 API Key。
例如，选择 Z.AI（智谱AI），然后粘贴你在其官网获取的 API Key。

Z.AI
xxx.xxxx (此处应替换为你的真实API Key)

4. 选择默认模型

在上一步选择的供应商下，通常有多个模型可用。选择一个作为默认对话模型，例如 zai/glm-4.7。

zai/glm-4.7

5. Channel（通道）配置

这是 OpenClaw 最强大的功能之一，允许你将 AI 助手接入到各种聊天平台。初始化时可以先跳过，后续在 Web UI 中详细配置。

平台	状态
Telegram	需要 token
Discord	需要 token
Slack	需要 token
WhatsApp	未配置
飞书	需要插件
LINE	需要插件

对于新手，建议先选择：

Skip for now

完成以上所有步骤后，OpenClaw 服务就会自动启动。

---

五、OpenClaw 控制面板与访问

安装配置完成后，OpenClaw 会提供一个 Web UI 控制台 用于管理和交互。

控制台的本地访问地址为：

http://127.0.0.1:18789/

如果初始化时设置了 Token 认证，则需要携带 Token 访问：

http://127.0.0.1:18789/#token=xxxxxxx

---

六、远程访问 Web UI

如果你的 OpenClaw 部署在云服务器上，默认绑定地址 127.0.0.1 意味着无法直接从外部浏览器访问。这时，可以使用 SSH 本地端口转发 来实现安全访问。

在你的本地电脑（如Windows上的WSL或Mac的终端）上执行以下命令：

ssh -N -L 18789:127.0.0.1:18789 ubuntu@你的服务器IP地址

• -N 表示不执行远程命令，只做端口转发。
• -L 18789:127.0.0.1:18789 表示将本地的 18789 端口映射到服务器本地的 18789 端口。
• ubuntu@服务器IP 替换为你的服务器用户名和IP。

执行后，该终端会处于挂起状态（不要关闭）。此时，在你的本地浏览器中访问：

http://localhost:18789

或（如果设置了Token）

http://localhost:18789/#token=你的token

即可打开部署在远程服务器上的 OpenClaw 控制界面。

---

七、解决 command not found (PATH问题)

安装后，在终端直接输入 openclaw 命令可能会提示 command not found。这是因为通过 npm 全局安装的包，其所在路径没有被添加到系统的 PATH 环境变量中。

1. 检查命令位置

which openclaw

如果没有任何输出，说明系统在 PATH 中找不到该命令。

2. 查看 npm 全局安装目录

我们需要找出 Node.js 全局包的安装路径。

npm prefix -g

该命令会输出一个路径，例如 /home/ubuntu/.npm-global。

3. 将路径添加到 PATH

将上述路径下的 bin 目录添加到当前用户的 PATH 中。编辑 Shell 的配置文件（如 ~/.bashrc）。

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc

4. 使配置生效

source ~/.bashrc

5. 验证

再次检查 openclaw 命令：

which openclaw

现在应该能正确输出路径了，例如 /home/ubuntu/.npm-global/bin/openclaw。

---

八、OpenClaw 常用命令

配置好PATH后，你就可以在终端使用 openclaw 命令行工具了。

• 查看系统状态：

  openclaw doctor

• 列出当前配置：

  openclaw config list

• 打开 Web 控制台 (如果服务已运行)：

  openclaw dashboard

• 安全扫描：

  openclaw security audit --deep

• 自动修复安全问题：

  openclaw security audit --fix

---

九、系统服务管理

OpenClaw 安装后默认注册为 systemd user service，这意味着它以后台服务的形式运行，并且支持开机自启。这对于生产环境下的稳定运行至关重要，也是 运维 的常见操作。

• 查看服务状态：

  systemctl --user status openclaw-gateway

• 启动服务：

  systemctl --user start openclaw-gateway

• 停止服务：

  systemctl --user stop openclaw-gateway

• 重启服务 (修改配置后常用)：

  systemctl --user restart openclaw-gateway

---

十、目录结构

了解 OpenClaw 的主要文件和目录位置，有助于后续的配置管理和问题排查。所有数据默认位于用户主目录下的 .openclaw 文件夹中。

~/.openclaw

典型的目录结构如下：

.openclaw
├── openclaw.json       # 主配置文件
├── workspace           # 工作空间目录
├── agents              # Agent数据目录
│   └── main
│       └── sessions    # 会话记录存储位置

目录/文件	作用
openclaw.json	核心配置文件，包含模型、网关、通道等所有设置。
workspace	AI Agent 执行任务时可以使用的工作区。
agents	存放不同AI助手（Agent）的配置和数据。
sessions	存储与AI的历史对话记录。

---

十一、测试与后续操作

完成部署后，最重要的就是测试AI是否能正常工作。

1. 通过本地或SSH转发的方式打开 Web UI (http://localhost:18789)。
2. 在聊天界面输入一个问题，例如：“你是谁？”。
3. 如果AI能够正常回复，例如：“我是基于 glm-4.7 的 AI Agent”，则说明整个部署流程成功。

至此，一个基础的 OpenClaw AI 助手已经部署完毕。你可以在 Web UI 中进一步探索，例如：

• 个性化AI：给AI设置名字、修改系统提示词（Prompt）。
• 扩展能力：为AI添加各种工具（Tools），使其能够执行搜索、计算等任务。
• 连接平台：在 “Channels” 页面配置 Telegram、Discord 等聊天平台，让你的AI助手真正“活”在各个社交软件中。

希望这篇在 云栈社区 分享的教程能帮助你顺利开启 AI Agent 的构建之旅。如果在实践中遇到其他问题，欢迎在技术社区中进行交流探讨。