Ubuntu 安装部署 OpenClaw 详细教程

玛卡叭咔

421人浏览 · 2026-09-05 11:18:04

玛卡叭咔 · 2026-09-05 11:18:04 发布

🦞 Ubuntu 安装部署 OpenClaw AI 详细教程

自托管 AI 智能体 Gateway 网关 — 多渠道、开源、本地优先的智能助手平台

Ubuntu 20.04 / 22.04 / 24.04Node.js 24+10+ 聊天渠道MIT 开源

📋 教程目录

OpenClaw AI 简介
架构与工作原理
系统要求
安装 Node.js
安装 OpenClaw（三种方式）
新手引导配置
验证安装
使用 Control UI 仪表板
连接聊天渠道
Docker 部署方式
服务器部署与运维
常用配置说明
常见问题排查
部署检查清单

1OpenClaw AI 简介

OpenClaw（俗称"小龙虾"）是一款本地优先、开源、跨平台的 AI 智能体 Gateway 网关。它不是云端 SaaS，而是直接运行在你自己的电脑或服务器上，通过赋予模型"手脚"，让 AI 从"被动回答问题"升级为"主动完成任务"。

核心特性

自托管：在你的硬件上按你的规则运行，数据完全可控
多渠道 Gateway 网关：单个 Gateway 支持 Discord、Telegram、WhatsApp、Signal、Slack、飞书、微信等 10+ 聊天渠道
智能体原生：支持工具使用、会话、记忆、多智能体路由
插件市场：ClawHub 插件生态，可扩展渠道和能力
媒体支持：发送和接收图像、音频及文档
Web Control UI：浏览器仪表板，用于聊天、配置和会话管理
移动节点：支持 iOS / Android 节点配对，Canvas、相机和语音工作流
开源：MIT 许可证，由 OpenClaw 基金会社区驱动

支持的聊天渠道

主流渠道

Telegram
Discord
WhatsApp
Signal
Slack
Microsoft Teams

其他渠道

飞书 / Google Chat
iMessage
Matrix
Zalo
WebChat（网页聊天）
更多可通过插件扩展

和其他 AI 助手的区别：OpenClaw 不是又一个聊天机器人，而是一个 Gateway 网关。你把它部署在服务器上，连接各种聊天应用，然后在任何地方都能和你的 AI 助手对话——就像跟朋友发消息一样自然。

2架构与工作原理

聊天应用
Discord/Telegram/WhatsApp... ↔ OpenClaw Gateway
会话·路由·渠道连接 ↔ AI 智能体
工具·记忆·多模型 ↔ 模型提供商
Anthropic/OpenAI/Google...

核心组件

组件	作用
Gateway 网关	会话、路由和渠道连接的唯一事实来源，管理所有消息流
渠道插件	连接各个聊天平台的适配器，一个 Gateway 可同时接多个渠道
智能体运行时	处理 AI 对话、工具调用、记忆管理
Control UI	浏览器仪表板，用于聊天、配置和会话管理
节点（Node）	iOS/Android/本地设备端，提供屏幕、相机、Canvas 能力
ClawHub	插件市场，可扩展渠道和技能

配置与数据位置

配置文件：~/.openclaw/openclaw.json
状态目录：~/.openclaw/
默认端口：18789（Control UI 和 Gateway API）

3系统要求

3.1 最低要求

项目	最低要求	推荐配置
Ubuntu 版本	20.04+	22.04 LTS / 24.04 LTS
Node.js	22.22.3+ 或 24.15+	Node 24.x（默认目标版本）
CPU	1 核	2 核及以上
内存	1 GB	2 GB+（运行沙箱时建议 4GB+）
硬盘空间	1 GB	5 GB+
网络	能访问模型 API	稳定的互联网连接

3.2 准备 API Key

你需要至少一个 AI 模型提供商的 API Key。支持的主要提供商：

提供商	说明
Anthropic (Claude)	推荐，质量最佳
OpenAI	GPT 系列模型
Google (Gemini)	Gemini 系列
本地模型	支持 Ollama 等本地模型服务

新手建议：先准备好一个 API Key（比如 Anthropic 或 OpenAI 的），新手引导时会用到。之后可以随时添加更多提供商。

4安装 Node.js

OpenClaw 需要 Node.js 22.22.3+、24.15+ 或 25.9+，推荐使用 Node 24。

4.1 方式一：使用 NodeSource 仓库（推荐）

# 添加 NodeSource Node.js 24.x 仓库
$ curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装 Node.js
$ sudo apt install -y nodejs

# 验证
$ node --version
# v24.x.x

$ npm --version
# 10.x.x

4.2 方式二：使用 nvm（多版本管理）

# 安装 nvm
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell
$ source ~/.bashrc

# 安装 Node 24
$ nvm install 24
$ nvm use 24

# 验证
$ node --version

4.3 方式三：让安装脚本自动安装

如果你使用官方安装脚本（下一节），它会自动检测并安装所需版本的 Node.js，可以跳过这一步。

注意：Ubuntu 22.04 默认仓库的 Node.js 版本是 12.x，24.04 默认是 18.x，都低于要求。请务必使用上面的方式安装 Node 24。

5安装 OpenClaw（三种方式）

方式一：一键安装脚本推荐

最简单最快的方式，自动检测系统、安装 Node、安装 OpenClaw 并启动新手引导。

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

如果不想运行新手引导：

$ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

方式二：npm 全局安装

如果你已经自行安装了 Node.js，可以直接用 npm 安装：

$ npm install -g openclaw@latest

# 然后运行新手引导并安装守护进程
$ openclaw onboard --install-daemon

pnpm 用户：需要先批准构建脚本：
pnpm add -g openclaw@latest && pnpm approve-builds -g && openclaw onboard --install-daemon

方式三：本地前缀安装（隔离安装）高级

将 OpenClaw 和 Node 都保存在本地前缀 ~/.openclaw 下，不依赖系统级 Node 安装：

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

从 GitHub 源码安装（开发者）

$ git clone https://github.com/openclaw/openclaw.git
$ cd openclaw
$ pnpm install && pnpm build && pnpm ui:build
$ pnpm link --global
$ openclaw onboard --install-daemon

从源码安装需要 pnpm：如果没有 pnpm，先执行 npm install -g pnpm

6新手引导配置

安装完成后，运行新手引导完成初始配置：

$ openclaw onboard --install-daemon

新手引导会引导你完成以下设置：

选择模型提供商 — 选择你想用的 AI 模型（Anthropic、OpenAI、Google 等）
输入 API Key — 输入对应的 API 密钥
Gateway 配置 — 设置网关监听地址和端口
安装守护进程 — --install-daemon 参数会自动安装 systemd 用户服务，开机自启
渠道配对（可选） — 可以先跳过，之后再配置

引导完成标志：提示 Gateway 网关已启动并正在运行，显示访问地址和端口（默认 18789）。

跳过某些步骤

如果想先快速跑起来，渠道配对、Skills 安装等都可以跳过，之后用以下命令继续配置：

$ openclaw configure       # 修改配置
$ openclaw channels add   # 添加新渠道

7验证安装

7.1 检查 CLI 是否可用

$ openclaw --version
# 输出类似：openclaw/0.x.x linux-x64 node-v24.x.x

7.2 运行健康检查

$ openclaw doctor
# 检查配置问题、环境状态等

7.3 检查 Gateway 状态

$ openclaw gateway status

正常输出应包含：

Gateway is running
PID: 12345
Port: 18789
Uptime: 2m 30s

7.4 常用管理命令

命令	作用
`openclaw gateway start`	启动 Gateway
`openclaw gateway stop`	停止 Gateway
`openclaw gateway restart`	重启 Gateway
`openclaw gateway status`	查看状态
`openclaw gateway logs`	查看日志
`openclaw dashboard`	打开 Control UI

8使用 Control UI 仪表板

8.1 打开仪表板

$ openclaw dashboard

这会在默认浏览器中打开 Control UI。

8.2 手动访问

如果浏览器没有自动打开，手动访问：

本地地址：http://127.0.0.1:18789/

8.3 仪表板功能

聊天界面

和 AI 助手对话
多会话管理
文件上传下载
代码块渲染

配置管理

模型提供商设置
渠道管理
插件安装
安全设置

8.4 测试第一条消息

在 Control UI 聊天框中输入一条消息（比如"你好"），如果收到 AI 回复，说明一切运行正常。

9连接聊天渠道

OpenClaw 最强大的功能之一是多渠道支持。下面以最容易配置的 Telegram 为例：

9.1 快速连接 Telegram

第 1 步：创建 Telegram Bot

在 Telegram 中搜索 @BotFather
发送 /newbot 命令
按提示设置 bot 名称和用户名
BotFather 会给你一个 Bot Token，保存下来

第 2 步：在 OpenClaw 中添加 Telegram 渠道

$ openclaw channels add telegram

按提示输入 Bot Token 即可。

第 3 步：开始聊天

在 Telegram 中找到你刚创建的 bot，发送一条消息，AI 就会回复。

9.2 其他渠道

渠道	难度	说明
Telegram	⭐ 最简单	只需 Bot Token
Discord	⭐⭐	创建 Discord 应用和 Bot
WhatsApp	⭐⭐⭐	需要 WhatsApp Business API 或网页版
Signal	⭐⭐⭐	需要 Signal 账号
飞书	⭐⭐	创建飞书应用
Slack	⭐⭐	创建 Slack App

9.3 控制谁可以访问

可以配置白名单，只允许特定用户使用：

# 编辑配置文件
$ nano ~/.openclaw/openclaw.json

添加允许列表：

{
  "channels": {
    "telegram": {
      "allowFrom": ["+15555550123", "@your_username"]
    }
  }
}

安全提醒：在公共渠道（群聊）中使用时，建议设置 requireMention: true，只有 @ 机器人时才会回复，避免误触发。

10Docker 部署方式

10.1 前置条件

$ sudo apt install -y docker.io docker-compose-v2
$ sudo usermod -aG docker $USER
$ newgrp docker    # 使组权限立即生效

$ docker --version
$ docker compose version

10.2 使用预构建镜像

# 创建数据目录
$ mkdir -p ~/.openclaw

# 运行容器
$ docker run -d \
    --name openclaw \
    -p 18789:18789 \
    -v ~/.openclaw:/root/.openclaw \
    --restart unless-stopped \
    ghcr.io/openclaw/openclaw:latest

10.3 使用 Docker Compose

$ mkdir -p ~/openclaw-docker && cd ~/openclaw-docker
$ cat > docker-compose.yml << 'EOF'
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped
EOF

$ docker compose up -d

10.4 从源码构建镜像

$ git clone https://github.com/openclaw/openclaw.git
$ cd openclaw
$ ./scripts/docker/setup.sh

Docker 镜像来源：官方镜像发布在 GitHub Container Registry（ghcr.io/openclaw/openclaw）和 Docker Hub（openclaw/openclaw）。请使用官方镜像，避免使用非官方来源。

11服务器部署与运维

11.1 在 VPS 上部署

在云服务器上部署 OpenClaw 的流程和本地基本一致，但需要注意安全配置。

安全最佳实践

不要把 Gateway 暴露到公网：默认绑定 127.0.0.1，通过 SSH 隧道或 Tailscale 访问
配置访问令牌：设置 gateway.auth.token 或 gateway.auth.password
使用 HTTPS：对外暴露时必须使用反向代理 + SSL
限制渠道访问：配置 allowFrom 白名单
定期备份：备份 ~/.openclaw/ 目录

11.2 通过 SSH 隧道远程访问

# 在你的本地电脑上执行，建立 SSH 端口转发
$ ssh -L 18789:localhost:18789 user@your-server-ip

# 然后本地浏览器访问
# http://localhost:18789

11.3 配置 Nginx 反向代理（可选）

$ sudo apt install -y nginx

$ sudo tee /etc/nginx/sites-available/openclaw << 'EOF'
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

$ sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
$ sudo nginx -t
$ sudo systemctl restart nginx

11.4 systemd 服务管理

使用 --install-daemon 安装后，OpenClaw 会作为 systemd 用户服务运行：

# 查看服务状态
$ systemctl --user status openclaw-gateway

# 查看日志
$ journalctl --user -u openclaw-gateway -f

$ openclaw gateway logs   # 更简单的方式

11.5 性能调优（低配机器）

如果在小内存 VPS 或 ARM 主机上运行缓慢，可以启用 Node 模块编译缓存：

$ grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF'
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
$ source ~/.bashrc

11.6 更新 OpenClaw

# 更新到最新稳定版
$ openclaw update

# 切换到开发版
$ openclaw update --channel dev

# 切换回稳定版
$ openclaw update --channel stable

12常用配置说明

12.1 配置文件位置

~/.openclaw/openclaw.json

12.2 多模型提供商配置

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "claude-3-5-sonnet-20240620"
    }
  }
}

12.3 渠道白名单配置

{
  "channels": {
    "telegram": {
      "allowFrom": ["@your_username"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"]
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

12.4 Gateway 安全配置

{
  "gateway": {
    "bind": "127.0.0.1",
    "port": 18789,
    "auth": {
      "password": "your-secure-password"
    }
  }
}

修改配置后重启 Gateway：
openclaw gateway restart

12.5 环境变量

变量	作用
`OPENCLAW_HOME`	主目录路径
`OPENCLAW_STATE_DIR`	覆盖状态目录
`OPENCLAW_CONFIG_PATH`	覆盖配置文件路径
`OPENCLAW_NO_RESPAWN`	禁用进程重生（小内存机器有用）
`NODE_COMPILE_CACHE`	Node 模块编译缓存路径

13常见问题排查

13.1 命令找不到：openclaw: command not found

几乎都是 PATH 问题，npm 的全局二进制目录不在 shell 的 PATH 中。

# 检查 Node 是否安装
$ node -v

# 查找全局包位置
$ npm prefix -g

# 检查 PATH
$ echo "$PATH"

# 如果不在 PATH 中，添加到 .bashrc
$ echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

13.2 Gateway 启动失败

# 查看详细日志
$ openclaw gateway logs

# 运行健康检查
$ openclaw doctor

# 检查端口是否被占用
$ sudo lsof -i :18789

13.3 端口 18789 被占用

# 修改配置文件中的端口
$ nano ~/.openclaw/openclaw.json

# 修改 gateway.port 为其他端口，例如 18790

$ openclaw gateway restart

13.4 API Key 无效 / 模型调用失败

# 重新配置提供商
$ openclaw configure

# 检查网络连接
$ curl -I https://api.anthropic.com

13.5 升级后出问题

# 回退到上一个版本
$ openclaw update --version 0.x.x

# 或者运行 doctor 诊断
$ openclaw doctor

13.6 卸载 OpenClaw

$ openclaw gateway stop
$ openclaw gateway uninstall
$ npm uninstall -g openclaw

# 彻底删除数据（谨慎操作！）
$ rm -rf ~/.openclaw

14部署检查清单

基础环境

Ubuntu 20.04 / 22.04 / 24.04 系统
Node.js 24.x 已安装
npm / pnpm 可用
网络能访问模型 API

安装与配置

OpenClaw CLI 可正常运行（openclaw --version）
新手引导完成
API Key 已配置
Gateway 守护进程已安装并运行

功能验证

Control UI 可以访问（http://127.0.0.1:18789）
能正常和 AI 聊天对话
至少一个渠道已连接（可选）
openclaw doctor 无严重错误

服务器部署安全检查

Gateway 绑定 127.0.0.1（不直接暴露公网）
配置了访问密码或令牌
渠道设置了白名单
有定期备份策略
防火墙配置正确

🎉 部署完成！你现在拥有了一个完全自托管的 AI 智能体 Gateway 网关。可以通过 Control UI 在浏览器中聊天，或者连接 Telegram、Discord 等渠道在手机上随时使用。接下来可以探索：安装插件、添加更多渠道、配置多智能体、连接本地模型等。

官方网站：openclaw.ai | 文档：docs.openclaw.ai | GitHub：openclaw/openclaw

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

龙虾开发者社区

周榜换血九成，Agent Skills 星数翻倍

龙虾开发者社区

智能体从入门到精通：6个必学GitHub开源项目

龙虾开发者社区

所有评论(0)

查看更多评论

玛卡叭咔

@qq_43291026

已为社区贡献2条内容

Ubuntu 安装部署 OpenClaw 详细教程

玛卡叭咔

🦞 Ubuntu 安装部署 OpenClaw AI 详细教程

📋 教程目录

1OpenClaw AI 简介

核心特性

支持的聊天渠道

2架构与工作原理

核心组件

配置与数据位置

3系统要求

3.1 最低要求

3.2 准备 API Key

4安装 Node.js

4.1 方式一：使用 NodeSource 仓库（推荐）

4.2 方式二：使用 nvm（多版本管理）

4.3 方式三：让安装脚本自动安装

5安装 OpenClaw（三种方式）

方式一：一键安装脚本 推荐

方式二：npm 全局安装

方式三：本地前缀安装（隔离安装）高级

从 GitHub 源码安装（开发者）

6新手引导配置

新手引导会引导你完成以下设置：

跳过某些步骤

7验证安装

7.1 检查 CLI 是否可用

7.2 运行健康检查

7.3 检查 Gateway 状态

7.4 常用管理命令

8使用 Control UI 仪表板

8.1 打开仪表板

8.2 手动访问

8.3 仪表板功能

8.4 测试第一条消息

9连接聊天渠道

9.1 快速连接 Telegram

第 1 步：创建 Telegram Bot

第 2 步：在 OpenClaw 中添加 Telegram 渠道

第 3 步：开始聊天

9.2 其他渠道

9.3 控制谁可以访问

10Docker 部署方式

10.1 前置条件

10.2 使用预构建镜像

10.3 使用 Docker Compose

10.4 从源码构建镜像

11服务器部署与运维

11.1 在 VPS 上部署

安全最佳实践

11.2 通过 SSH 隧道远程访问

11.3 配置 Nginx 反向代理（可选）

11.4 systemd 服务管理

11.5 性能调优（低配机器）

11.6 更新 OpenClaw

12常用配置说明

12.1 配置文件位置

12.2 多模型提供商配置

12.3 渠道白名单配置

12.4 Gateway 安全配置

12.5 环境变量

13常见问题排查

13.1 命令找不到：openclaw: command not found

13.2 Gateway 启动失败

13.3 端口 18789 被占用

13.4 API Key 无效 / 模型调用失败

13.5 升级后出问题

13.6 卸载 OpenClaw

14部署检查清单

基础环境

安装与配置

功能验证

服务器部署安全检查

所有评论(0)

温馨提示：您尚未绑定手机号

玛卡叭咔

方式一：一键安装脚本推荐