企业官网建设流程全解析

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

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

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

📋 教程目录

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

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...

核心组件

配置与数据位置

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

3系统要求

3.1 最低要求

3.2 准备 API Key

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

新手建议：先准备好一个 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

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

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

引导完成标志：提示 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 常用管理命令

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

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

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

$ openclaw channels add telegram

按提示输入 Bot Token 即可。

第 3 步：开始聊天

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

9.2 其他渠道

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 环境变量

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