OpenClaw 部署(下)：系统级原生部署与调试

📘 文档目的与功能

　　本文档记录了在 Ubuntu 24.04 系统上通过 Systemd 用户级服务 的方式部署 OpenClaw。从Node.js 安装、npm 全局配置到初始化的完整过程。重点解决 root 用户运行失败、跨域访问被拦截（origin not allowed）、设备配对（pairing required） 等常见问题，并提供 Nginx 反向代理与 HTTPS 配置方案，最终通过 Systemd 服务实现开机自启与后台稳定运行。

　　如需Docker下极简部署，见《OpenClaw 部署(上)：基于 Docker 快速搭建与调试》。

一、环境准备
1、系统要求
  • 操作系统: Ubuntu 24.04 LTS
  • 网络: 建议配置代理（如 OpenWrt）以解决网络受限问题
  • AI Key: 准备好大模型 API Key（如百度千帆、GPT 等）
2. 基础工具安装
sudo apt update
sudo apt install -y curl wget git build-essential python3 net-tools
二、Node.js 安装
1. 添加 NodeSource 官方仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
2. 安装 Node.js
sudo apt install -y nodejs
# 验证安装（应为v22.x.x）
node -v && npm -v
三、OpenClaw 安装（用户级）
重要提示：不应使用 root 用户运行 OpenClaw，因为 root 用户下的 systemctl --user 服务模式会运行失败。
1. 创建专用用户
sudo useradd -m -s /bin/bash openclaw
sudo passwd openclaw
2. 切换到新用户并配置 npm 用户环境
su - openclaw
后续操作均在 openclaw 用户下执行：
# 1. 创建用户级别的 npm 全局安装目录
mkdir -p ~/.local/npm-global

# 2. 配置 npm 使用该目录
npm config set prefix '~/.local/npm-global'

# 3. 将该目录的 bin 子目录添加到当前用户的 PATH 环境变量中
echo 'export PATH="$HOME/.local/npm-global/bin:$PATH"' >> ~/.bashrc

# 4. 使配置立即生效
source ~/.bashrc

# 5. 设置 npm 国内镜像源以加速下载
npm config set registry https://registry.npmmirror.com
3. 安装 OpenClaw
npm i -g openclaw
4. 验证安装
which openclaw              # 应指向 ~/.local/npm-global/bin/openclaw
openclaw --version          # 查看版本
whoami                      # 确认当前为 openclaw 用户
四、初始化配置与 Dashboard 访问
1. 启动交互式配置向导
OpenClaw 提供了 onboard 命令进行一键初始化。
openclaw onboard
按提示依次完成以下配置：
步骤 操作说明
安全提示 选择 YES 继续，启用 QuickStart 模式
模型配置 选择所需 AI 模型（如GPT），输入对应 API Key
Skill 配置 可暂时跳过，后续在 Dashboard 中配置
自动补全 推荐选择 Yes 启用命令行自动补全

 

2. 记录关键信息
配置向导完成后，终端会输出重要信息，要记录下来：
📌 需要保存：
  • 配置文件路径：~/.openclaw/config.json
  • Dashboard 访问地址（含 token）
  • SSH 隧道命令（用于远程访问）
五、启动 Gateway 服务
1、前台运行（测试用）
# 在前台运行 gateway，会占用当前终端
openclaw gateway run

2、访问 Dashboard
  • 本机访问：浏览器打开 http://localhost:18789
  • 远程访问：需通过 SSH 隧道
六、远程访问与端口映射
1. 本地 SSH 隧道（推荐）
在本地电脑执行（如 Windows PowerShell）：
ssh -N -L 18789:127.0.0.1:18789 -L 18791:127.0.0.1:18791 openclaw@192.168.20.169
然后浏览器访问：
http://localhost:18789/#token=d687662349dcd4820ff26cf8b2a0451527f262926600f208
七、高级功能启用
启用 exec 执行工具（允许执行 shell 命令）， 谨慎启用，存在安全风险！
openclaw config set tools.profile full
八、Nginx 反向代理与 HTTPS（可忽略）
为实现局域网 HTTPS 访问，推荐配置反向代理，但要解决2个报错，见第八部分，如果打算使用SSH 隧道，可忽略。
1. 安装、配置Nginx

具体见上一篇文档
2. 访问地址
浏览器打开：https://192.168.20.169/#token=你的token
九、报错问题解决
 问题 1：浏览器提示 origin not allowed
原因：跨域请求被拦截。
解决方案：
1. 编辑配置文件：
nano ~/.openclaw/openclaw.json
2. 增加 controlUi 模块：
"controlUi": {
  "allowedOrigins": [
    "http://localhost:18789",
    "https://192.168.20.169"
  ]
}
添加前、后对比



2. 重启 Gateway：
pkill -f "openclaw-gateway"
openclaw gateway run

问题 2：浏览器提示 pairing required
1. 查看及审批设备
#查看待批准的设备列表:
openclaw devices list
# 批准设备（用实际看到的设备ID）
openclaw devices approve 10524b60-6263-4190-9ae3-0c6422012163
2. 重新访问
https://192.168.20.169/#token=d687662349dcd4820ff26cf8b2a0451527f262926600f208
十、系统级服务配置（Systemd）

为实现开机自启和后台稳定运行，配置 systemd 服务。

1. 创建服务文件（以 root 身份执行）
sudo cat > /etc/systemd/system/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
ExecStart=/home/openclaw/.local/npm-global/bin/openclaw gateway run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
2. 重载并启动服务
systemctl daemon-reload
systemctl start openclaw-gateway
systemctl enable openclaw-gateway
systemctl status openclaw-gateway
journalctl -u openclaw-gateway -f
十一、OpenClaw接入企业微信
需要公网IP及安装插件，可在云主机上部署，见：https://cloud.baidu.com/doc/LS/s/6ml9f3cvl