## 一、前置准备
1.2 系统环境预处理
javascript
# 更新系统软件包列表（必做）
sudo apt update && sudo apt upgrade -y
# 安装基础依赖（编译工具、网络工具等，避免卡在 node-gyp rebuild）
sudo apt install -y curl wget git python3 build-essential libssl-dev ufw
1.3 安装 Node.js
javascript
# 导入 NodeSource 22.x 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装 Node.js 和 npm（npm 用于包管理）
sudo apt install -y nodejs
# 验证安装是否成功（显示版本号即正常）
node --version # 需显示 v22.x.x
npm --version # 需显示 10.x.x 及以上
1.4 国内环境优化（可选，解决下载卡顿）
国内用户直接下载 OpenClaw 依赖可能卡顿，建议配置 npm 国内镜像（阿里云源），加速下载速度：
javascript
# 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com
# 验证镜像配置是否生效
npm config get registry # 显示 https://registry.npmmirror.com 即成功
二、安装方式
方案一：一键安装（官方推荐，新手首选）
官方提供一键安装脚本，自动完成所有配置，无需手动操作，适合首次接触 OpenClaw 的新手：
- 执行一键安装命令，脚本会自动下载、安装 OpenClaw 及所有依赖（若提示“没有文件”“无法找到install.sh”，核心原因是OpenClaw 2025年末品牌升级后，官方一键脚本路径调整，按以下两种方式解决，优先选方式1）： 方式1：替换为国内可用的一键安装脚本（适配国内网络，解决文件缺失问题）：
curl -fsSL https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh | bash方式2：手动下载安装脚本后执行（彻底解决“没有文件”报错）：# 手动下载脚本文件（国内镜像，避免文件缺失）wget https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh# 给脚本添加执行权限chmod +x install.sh# 执行安装脚本sudo ./install.sh - 安装过程说明：
- 安装过程中会提示确认配置（如模型选择、Channel 配置），默认按 Enter 键即可，后续可在 UI 界面修改；
- 若出现“权限不足”报错，在命令前添加 sudo（sudo curl -fsSL ... | bash）；
- 安装耗时约 3-10 分钟，取决于网络速度，耐心等待，不要中途中断命令。
- 验证安装成功：安装完成后，终端会显示“OpenClaw installed successfully”，并给出 Control UI 登录地址（默认 http://127.0.0.1:18789/openclaw），即表示安装成功。
方案二：npm 全局安装（灵活可控，适合进阶用户）
通过 npm 全局安装，可手动控制版本、灵活配置参数，适合需要自定义安装路径或版本的用户：
- 执行 npm 安装命令，全局安装最新版 OpenClaw：
npm install -g openclaw@latest - 解决下载卡顿问题：
- 若命令执行后卡住（尤其是下载预编译二进制文件时），可中断命令（Ctrl+C），重新执行；
- 若仍卡顿，可使用浏览器下载离线安装包（参考国内镜像站），再手动安装。
- 验证安装成功：执行以下命令，显示版本号即正常：
openclaw --version
三、初始化配置
安装完成后，需完成简单初始化配置（模型选择、Channel 配置、端口放行），才能正常使用 OpenClaw 的所有功能，以下步骤适配所有安装方式。
3.1 端口放行（必做，解决无法访问 UI 问题）
OpenClaw Gateway 默认监听 18789 端口，Ubuntu 防火墙（ufw）默认会拦截该端口，需手动放行：
javascript
# 放行 18789 端口（TCP 协议）
sudo ufw allow 18789/tcp
# 重启防火墙，使配置生效
sudo ufw reload
# 验证端口是否放行成功
sudo ufw status | grep 18789 # 显示“ALLOW”即成功
3.2 启动 Gateway 服务
Gateway 是 OpenClaw 的核心服务，负责接收请求、调用工具，需确保其正常启动。
首先运行openclaw setup ，来到root/.openclaw 目录下，寻找配置文件openclaw.json 。打开并进行编辑，添加Gateway配置。
javascript
{
"agents": {
"defaults": {
"workspace": "/home/zhaodt/.openclaw/workspace"
}
},
"meta": {
"lastTouchedVersion": "2026.2.9",
"lastTouchedAt": "2026-02-12T13:06:24.900Z"
},
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
"controlUi": {
"enabled": true,
"basePath": "/openclaw",
"allowInsecureAuth": true,
"dangerouslyDisableDeviceAuth": false, // 建议关闭高危配置
"allowedOrigins": [ // 新增白名单
"http://47.77.183.124:18789", // 服务器公网IP+端口
"http://172.17.48.105:18789", // 服务器内网IP+端口
"http://localhost:18789", // 本机访问
"http://127.0.0.1:18789"
]
},
"auth": {
"mode": "token",
"token": "1c20ee2a91f3c4870d1"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"nodes": {
"allowCommands": [
"ls",
"pwd",
"cat"
]
}
}
}
javascript
# 方式 1：前台运行（适合测试，关闭终端即停止）
openclaw gateway --port 18789 --verbose
# 方式 2：后台运行（推荐，持久化启动）
# 安装 PM2 进程管理器（用于后台守护）
npm install -g pm2
# 注意：若已执行过此命令，不要重复执行，避免启动多个openclaw进程（导致端口冲突、UI无法访问）
pm2 start "openclaw gateway" --name openclaw # 仅启动1个进程
pm2 startup
pm2 save
# 验证服务状态（显示“online”且只有1个openclaw进程即正常）
pm2 status openclaw
# 若出现多个openclaw进程，执行以下命令清理（补充）
# pm2 stop openclaw && pm2 delete openclaw && pm2 start "openclaw gateway" --name openclaw
# 若服务一直重启，执行 pm2 logs openclaw 查看错误日志，定位重启原因
3.3 配置 Control UI 可远程访问（可选）
默认情况下，Control UI 仅允许本地（127.0.0.1）访问，若你的 Ubuntu 是 Server 版（无桌面），或想从其他设备访问，可以采用ssh连接的方式，打开本地终端工具（如OrcaTerm客户端版、Xterminal、Termius等），输入以下命令：
javascript
ssh -N -L 18789:127.0.0.1:18789 root@服务器公网IP地址
其中root@之后的内容为前面记录的服务器公网IP地址。
输入服务器登录密码后，按下回车，终端屏幕会停留在闪烁状态，此时不要关闭本地SSH终端。接下来，您可以在本地电脑上打开浏览器，输入以下网址：
javascript
http://localhost:18789/openclaw
此时即可在浏览器中访问OpenClaw WebUI。注意使用过程中需要保持本地终端的窗口不关闭，使用结束后再关闭本地终端。
您可以在WebUI的界面左侧导航栏中找到“Overview”，在Overview页面中输入OpenClaw的Gateway Token，即可正常开始使用WebUI。提示：您可以通过OrcaTerm终端登录服务器，在终端内输入并执行openclaw config get gateway.auth.token这条命令来获取Token。
3.4 初始化向导配置
运行向导并安装后台服务：openclaw onboard --install-daemon
javascript
步骤 1：Gateway 模式
? Gateway mode: (Use arrow keys)
❯ Local # 本地运行（推荐）
Remote # 连接到远程 Gateway
步骤 2：认证方式
? Auth provider: (Use arrow keys)
❯ Anthropic (API key) # 推荐
Anthropic (OAuth) # Claude Code 凭证复用
OpenAI (API key) # ChatGPT/Codex
OpenAI (OAuth)
...更多选项
步骤 3：选择模型
? Default model: (Use arrow keys)
❯ claude-sonnet-4-0 # 推荐，速度和智能平衡
claude-opus-4-5 # 更强智能，但更慢
claude-haiku-3-5 # 快速响应
步骤 4：频道配置
? Channels: (Select channels to configure)
❯⬡ WhatsApp # 需要 QR 登录
◉ Telegram # 需要 bot token
◯ Discord # 需要 bot token
◯ Mattermost # 需要 plugin token
◯ iMessage # macOS 本地
步骤 5：配对安全设置
默认：未知私聊会收到简短代码，需要批准后才能处理消息。
步骤 6：工作区设置
? Workspace directory: (Use arrow keys)
❯ ~/.openclaw/workspace # 默认工作区
自定义路径
步骤 7：技能选择
? Install recommended skills: (y/N)
y # 安装推荐技能
步骤 8：后台服务安装
? Install daemon: (y/N)
y # 安装后台服务（推荐）
