玩转OpenClaw | 基于Linux系统OpenClaw本地部署实践指南

玩转OpenClaw | 基于Linux系统OpenClaw本地部署实践指南

• 1.1 OpenClaw项目简介

• 1.2 OpenClaw主要特点

• 2.1 本地环境规划

• 2.2 本次实践介绍

• 2.3 注意事项

• 3.1 检查本地环境

• 3.2 更新软件包列表

• 3.3 安装基础工具

• 4.1 一键安装

• 4.2 修改监听地址

• 4.3 访问OpenClaw页面

• 5.1 安装Ningx

• 5.2 生成自签名证书

• 5.3 修改配置文件

• 5.4 启用配置并测试

• 5.5 重启Nginx服务

• 5.6 启动OpenClaw服务

• 5.7 检查监听端口

• 5.8 访问OpenClaw

• 6.1 配置AI模型

• 6.2 AI对话测试

• 6.3 安装skills

• 6.4 查看概览页面

• 6.5 OpenClaw命令速查

• 7.1 登录QQ开放平台

• 7.2 创建机器人

• 7.3 查看QQ机器人

• 7.4 对话测试

• 8.1 一键部署失败

• 8.2 其余电脑访问控制面板失败

• 8.3 对话失败或报错

前言

在本地化部署大模型应用日益成为隐私保护核心需求的今天，OpenClaw 以其轻量级架构和强大的终端集成能力，为 Linux 用户提供了构建私有 AI 助手的理想方案。本文基于实际部署流程，详细阐述从环境准备、一键安装到配置 HTTPS 访问及接入 QQ 机器人的完整操作步骤。通过这套实践指南，旨在帮助读者快速搭建起功能完备的本地智能中枢，实现安全可控的个性化 AI 交互体验。

一、OpenClaw介绍

1.1 OpenClaw项目简介

OpenClaw 是一款可运行在用户自有设备上的个人AI助手。它核心理念是"本地部署、数据自主"，让用户能够在自己控制的设备上运行AI助手，而非依赖云端服务。OpenClaw通过网关（Gateway）作为控制平面，连接用户日常使用的各种通讯渠道，让AI助手能够在用户已有的沟通工具中响应和服务。

核心理念：Gateway只是控制平面，真正的产品是助手本身。

1.2 OpenClaw主要特点

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

本次实践基于 Ubuntu 24.04.2 LTS 个人测试环境，旨在提供一份详尽的 OpenClaw 本地部署指南。我们将逐步演示从环境规划到服务运行的完整流程，帮助用户快速掌握该工具在 Linux 系统下的安装与配置要点。

2.3 注意事项

OpenClaw Onboard 在安装过程中会自动注册 Gateway 守护进程（基于 launchd 或 systemd 用户服务），以确保核心服务在后台持续稳定运行。鉴于该架构涉及本地端口监听与自动化执行权限，出于安全隔离考虑，强烈建议在云服务器或独立的空白测试机上部署，避免直接在与日常办公混用的主环境中运行。此外，本文档所有操作均基于个人测试环境验证，若计划应用于生产场景，请务必结合实际网络拓扑进行严格的安全评估与访问控制策略调整。

三、环境准备工作

3.1 检查本地环境

检查本地系统环境，当前操作系统为Ubuntu 24.04.2 LTS。

root@ubuntu01:~# cat /etc/os-release PRETTY_NAME="Ubuntu 24.04.2 LTS" NAME="Ubuntu" VERSION_ID="24.04" VERSION="24.04.2 LTS (Noble Numbat)" VERSION_CODENAME=noble ID=ubuntu ID_LIKE=debian HOME_URL="https://www.ubuntu.com/" SUPPORT_URL="https://help.ubuntu.com/" BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/" PRIVACY_POLICY_URL="https://ubuntu.com/legal/terms-and-policies/privacy-policy" UBUNTU_CODENAME=noble LOGO=ubuntu-logo

检查内核和硬盘大小，执行以下命令，结果如下所示：

root@ubuntu01:~# free -h                total        used        free      shared  buff/cache   available Mem:           3.8Gi       470Mi       2.2Gi       744Ki       1.5Gi       3.4Gi Swap:          3.8Gi          0B       3.8Gi root@ubuntu01:~# lsblk NAME                      MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS sda                         8:0    0  120G  0 disk ├─sda1                      8:1    0    1M  0 part ├─sda2                      8:2    0    2G  0 part /boot └─sda3                      8:3    0  118G  0 part   └─ubuntu--vg-ubuntu--lv 252:0    0   59G  0 lvm  / sr0                        11:0    1    3G  0 rom

3.2 更新软件包列表

为避免依赖冲突并确保安装顺利，首先需更新软件包列表以同步最新版本的依赖库。在当前测试环境中，我们将直接使用 root 权限执行以下命令完成更新：

apt update 

3.3 安装基础工具

安装以下相关依赖，在后续部署过程我们会用到。

apt install -y build-essential g++ make python3 curl git vim tree 

四、安装OpenClaw

4.1 一键安装

• Windows安装（可选）

在 Windows 环境下，可直接通过 PowerShell 执行以下脚本部署 OpenClaw。鉴于本次测试基于 Linux 系统，故不再演示 Windows 端的安装流程。

iwr -useb https://openclaw.ai/install.ps1 | iex

• Linux系统安装

官方提供了自动安装脚本，它会自动处理 Node.js 环境的检测（OpenClaw 依赖 Node.js 22 或更高版本），是最适合新手的安装方式。我们在Linux系统下，执行以下一键安装脚本。

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

第一次执行，可能由于网络原因会安装失败，如下所示报错：

当出现以上报错时候，我们需要更换npm镜像源，尝试临时更换为国内的淘宝镜像源来加速和稳定下载。

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

重新重新运行一键安装脚本进行安装，当出现以下提示时，表明安装程序在最终完成前，强制要求用户确认已充分知悉相关安全风险。此时，我们使用键盘方向键和回车键选择 “Yes” 以继续。

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

OpenClaw 的“入门模式”（Onboarding mode）选择界面： 建议直接按回车键（Enter）保持默认选择QuickStart。

🔍 选项含义

当出现以下界面，我们选择“Skip for now”跳过选择模型提供商步骤，在后续再行配置。

选择默认的“All providers”，回车键确认。

选择默认的“Keep current (default: anthropic/claude-opus-4-6)”，回车键确认。

我们选择“Skip for now”，现在先不绑定任何聊天软件，跳过此步骤。

我们继续选择“Skip for now”，回车键确认。

我们选择“No”，跳过安装Skills，后续再进行安装。

通过空白键进行选择，保持默认选择 “Skip for now”，直接按 回车键即可。

我们选择“Hatch in TUI (recommended)”（直接在当前终端窗口启动）：

出现以下提示，则表明OpenClaw服务启动成功。

4.2 修改监听地址

由于是本地内网测试部署，需将监听地址修改为 0.0.0.0，从而使内网其他机器能够访问。如果是云服务器或生产环境，请记得配置相应的防火墙规则，确保网络安全。修改配置文件：找到 gateway -> bind 字段，将刚才改的 "all" 改为 "lan"。allowedOrigins为“*”，允许所有内网访问，生产环境建议指定具体 IP。

vim /root/.openclaw/openclaw.json

"gateway": {     "port": 18789,     "mode": "local",     "bind": "lan",     "controlUi": {       "allowedOrigins": ["*"]     },     "auth": {       "mode": "token",       "token": "e7b6fa8770dc028c9518923adedbd9f9822fa880af863e4d"     },       ...

• 启动OpenClaw 的文本用户界面来重新配置服务

openclaw tui

4.3 访问OpenClaw页面

本地浏览器访问：http://《IP地址》:18789，将IP替换为自己服务器IP地址。如果无法访问到以下页面，则检查宿主机的防火墙是否关闭或者放行相关端口，云服务器则还需要设置安全组规则。

五、配置https访问

5.1 安装Ningx

使用以下命令，快速安装Nginx。

apt install nginx -y

5.2 生成自签名证书

内网环境下，我们直接以http方式访问会报错，其他客户端需通过 HTTPS 协议访问 OpenClaw 服务，因此需要配置自签名证书。

• 创建自签名证书目录

mkdir -p /etc/nginx/ssl

• 生成证书：生成证书时设置有效期为365 天，-subj参数中的IP请填写本机服务器IP地址。

openssl req -x509 -nodes -days 365 -newkey rsa:2048    -keyout /etc/nginx/ssl/openclaw.key    -out /etc/nginx/ssl/openclaw.crt    -subj "/C=CN/ST=State/L=City/O=Organization/CN=192.168.20.109"

5.3 修改配置文件

我们修改Nginx配置文件，内容如下所示：

vim /etc/nginx/sites-available/openclaw

server {     listen 15666 ssl;     server_name 192.168.20.109; # 或者你的域名     # SSL 证书路径     ssl_certificate /etc/nginx/ssl/openclaw.crt;     ssl_certificate_key /etc/nginx/ssl/openclaw.key;     # SSL 优化配置 (推荐)     ssl_protocols TLSv1.2 TLSv1.3;     ssl_ciphers HIGH:!aNULL:!MD5;     ssl_prefer_server_ciphers on;     location / {         # 反向代理到 OpenClaw 的本机 HTTP 端口 (18789)         proxy_pass http://127.0.0.1:18789;         # 关键：传递 WebSocket 支持         proxy_http_version 1.1;         proxy_set_header Upgrade $http_upgrade;         proxy_set_header Connection "upgrade";         # 关键：传递真实 Host 和协议，让 OpenClaw 知道它是通过 HTTPS 访问的         proxy_set_header Host $host;         proxy_set_header X-Real-IP $remote_addr;         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;         proxy_set_header X-Forwarded-Proto $scheme;         # 增加超时时间，防止长连接断开         proxy_read_timeout 86400s;         proxy_send_timeout 86400s;     } }

5.4 启用配置并测试

• 创建软链接启用站点

ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/

• 移除默认的 default 配置 (可选，避免端口冲突，如果默认配置没占15666可跳过)

rm /etc/nginx/sites-enabled/default

• 测试 Nginx 配置语法

nginx -t

5.5 重启Nginx服务

• 设置Nginx开机自启，重启Nginx服务。

systemctl daemon-reload systemctl enable nginx systemctl restart nginx

5.6 启动OpenClaw服务

• 我们启动OpenClaw网关服务：

openclaw gateway start

• 检查OpenClaw网关服务状态

systemctl --user status openclaw-gateway

• 检查OpenClaw 网关服务的当前运行状态

openclaw gateway status

5.7 检查监听端口

我们检查Nginx反向代理端口15666和OpenClaw服务端口，确保相关服务正向运行。

root@ubuntu01:~# ss -tunlp |grep 15666 tcp   LISTEN 0      511                            0.0.0.0:15666      0.0.0.0:*    users:(("nginx",pid=1640,fd=7),("nginx",pid=1639,fd=7),("nginx",pid=1638,fd=7),("nginx",pid=1637,fd=7),("nginx",pid=1636,fd=7)) root@ubuntu01:~# ss -tunlp |grep 18789 tcp   LISTEN 0      511                            0.0.0.0:18789      0.0.0.0:*    users:(("openclaw-gatewa",pid=1816,fd=22)) root@ubuntu01:~#

5.8 访问OpenClaw

查看网关令牌，可以在openclaw.json文件下进行查询。

root@ubuntu01:~# grep "token" /root/.openclaw/openclaw.json       "mode": "token",       "token": "e7b6fa8770dc028c9518923adedbd9f9822fa880af863e4d"

我们也可以使用以下方式查询并显示 OpenClaw 网关的连接信息（含令牌），同时阻止自动打开浏览器。

root@ubuntu01:~# openclaw dashboard --no-open 🦞 OpenClaw 2026.3.13 (61d171a) — I can run local, remote, or purely on vibes—results may vary with DNS. Dashboard URL: http://127.0.0.1:18789/#token=e7b6fa8770dc028c9518923adedbd9f9822fa880af863e4d Copy to clipboard unavailable. Browser launch disabled (--no-open). Use the URL above.

我们以https方式访问OpenClaw，https://《IP地址》:15666，将IP替换为自己服务器IP地址，复制粘贴刚才查询的Token。

在浏览器点击连接后，我们迅速回到服务器上进行配置操作。

• 查看待配对设备请求（获取 Request ID）

root@ubuntu01:~# openclaw devices list 🦞 OpenClaw 2026.3.13 (61d171a) — Powered by open source, sustained by spite and good documentation. │ ◇ Pending (1) ┌──────────────────────────────────────┬───────────────────────────────────────────────────────────┬──────────┬────────────┬──────────┬────────┐ │ Request                              │ Device                                                    │ Role     │ IP         │ Age      │ Flags  │ ├──────────────────────────────────────┼───────────────────────────────────────────────────────────┼──────────┼────────────┼──────────┼────────┤ │ 846877c2-1066-4229-9d23-0a3f5fce9e20 │ 52f0e7718fcc93aaa478135bfd49fd420293a7bf68a341e18cf95bc98 │ operator │            │ just now │        │ │                                      │ e76b9f0                                                   │          │            │          │        │ └──────────────────────────────────────┴───────────────────────────────────────────────────────────┴──────────┴────────────┴──────────┴────────┘ Paired (1) ┌──────────────────────────────────────────┬────────────┬────────────────────────────────────────────────────────────┬────────────┬────────────┐ │ Device                                   │ Roles      │ Scopes                                                     │ Tokens     │ IP         │ ├──────────────────────────────────────────┼────────────┼────────────────────────────────────────────────────────────┼────────────┼────────────┤ │ c9275774b83830aac12c324b885afd1ea7c070e0 │ operator   │ operator.read, operator.admin, operator.write, operator.   │ operator   │            │ │ bea6c4ea26e2271f90f338a5                 │            │ approvals, operator.pairing                                │            │            │ └──────────────────────────────────────────┴────────────┴────────────────────────────────────────────────────────────┴────────────┴───────

• 快速批准最新请求

openclaw devices approve --latest

此时，我们马上回到浏览器点击连接，即可正常连接成功。

六、OpenClaw基本配置

6.1 配置AI模型

• 我们在服务器终端，在交互式界面上，选择Local (this machine)。

openclaw configure

• 选择Model 模型配置

• 选择Qwen（通义千问）

• 由于我们非Windows本地登录，使用xshell连接的Linux服务器，我们需要复制授权地址到浏览器打开。

• 在浏览器中，我们登录千问账号，进行确认验证。

• 回到服务器端，我们选择默认的模型，回车键确认即可。

• 我们选择continue，结速AI模型配置。

• 我们重启OpenClaw 网关服务：

openclaw gateway restart

6.2 AI对话测试

我们回到OpenClaw的控制面板，进入聊天页面，进行简单询问，正常回答即可表示AI模型配置成功。

6.3 安装skills

我们执行以下配置命令后，依次选择Local (this machine)—Skills—Yes—clawhub，回车键确认。

openclaw configure

• 安装方式选择npm

• 此时会提示是否配置一些额外的服务，我们全部都选择No，最后确认完成即可。

• 每次配置修改完毕后，我们重启OpenClaw 网关服务：

openclaw gateway restart

6.4 查看概览页面

在 OpenClaw 控制面板的概览页面中，我们可以查看网关运行状态及其他核心系统信息。

6.5 OpenClaw命令速查

我们可以通过OpenClaw的help帮助选项，查询openclaw命令详细用法。

openclaw --help

核心命令按功能介绍：

七、接入QQ机器人

7.1 登录QQ开放平台

• 使用自己的手机QQ扫码登录QQ开放平台

• QQ开放平台官方地址：https://q.qq.com/qqbot/openclaw/index.html

7.2 创建机器人

我们在QQ开放平台的主页面，直接点击【创建机器人】选项。

创建机器人完毕后，系统会自动显示机器人相关信息以及在openclaw上部署指引。

我们依次复制机器人指引中的3条命令到我们的服务器终端：

• 安装OpenClaw开源社区QQBot插件

openclaw plugins install @tencent-connect/openclaw-qqbot@latest

• 配置绑定当前QQ机器人，修改为自己的token。

openclaw channels add --channel qqbot --token "xxxxxxx"

• 重启本地OpenClaw服务

openclaw gateway restart

7.3 查看QQ机器人

我们返回到OpenClaw控制面板上，在频道页面，可以看到已经接入QQ机器人。

7.4 对话测试

我们在手机版 QQ 中向 OpenClaw（小龙虾）发送“查询操作系统信息”的指令，若收到成功回复，即标志着 OpenClaw 基础配置完成。

八、踩坑记录

8.1 一键部署失败

第一次执行一键部署脚本，可能由于网络原因会安装失败，如下所示报错：

• 解决方法：设置国内NPM镜像源

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

8.2 其余电脑访问控制面板失败

在内网其余电脑访问OpenClaw服务器，会有2个问题：

• 问题1：若未启用 HTTPS 访问，系统将因安全策略限制而连接报错。解决该问题需配置 Nginx 反向代理并部署 SSL 证书，以强制开启安全的 HTTPS 通信。

• 问题2：若连接时提示“pairing required”，表明设备尚未经过授权。我们可以在服务器终端执行 openclaw devices approve --latest 命令快速批准最新配对请求，随后重新连接即可成功建立会话。

8.3 对话失败或报错

• 报错表现：在 Web 聊天界面发送消息，没有回复或报错。

• 解决方法: 检查AI模型是否配置，可重新进入配置向导进行操作。

openclaw configure

九、总结

本次实践成功在 Linux 环境中完成了 OpenClaw 的本地部署，通过一键安装脚本与 Nginx 配置实现了服务的快速搭建与 HTTPS 安全访问。在功能验证环节，完成了 AI 模型配置、对话测试以及 QQ 机器人接入，验证了系统在多平台协同方面的兼容性。针对部署过程中出现的一键部署失败、远程访问异常及对话报错等问题，通过日志排查与配置调整找到了有效解决方案。OpenClaw 凭借简洁的命令行交互与灵活的扩展能力，为私有化 AI 助手的落地应用提供了可靠的技术路径。

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～