OpenClaw Ubuntu 安装指南-171主机测评

OpenClaw Ubuntu 安装指南

📋 目录

简介
系统要求
安装步骤
配置向导
常用命令
故障排除
参考资源

🤖 简介

OpenClaw 是一个运行在本地设备上的个人 AI 助手。它可以在您已经使用的渠道上回复您（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），以及 BlueBubbles、Matrix、Zalo 和 Zalo Personal 等扩展渠道。它可以在 macOS/iOS/Android 上进行语音对话，并可以渲染您控制的实时 Canvas。Gateway 只是控制平面——产品本身才是助手。

OpenClaw 的核心特点：

🌐 多渠道支持 – 连接各种即时通讯平台
🔒 本地优先 – 数据存储在本地，保护隐私
🎨 实时 Canvas – 智能体驱动的可视化工作区
🗣️ 语音交互 – 支持语音唤醒和对话模式
🔧 丰富的工具集 – 浏览器控制、节点管理、自动化等

🖥️ 系统要求

最低系统要求

组件要求

操作系统	Ubuntu 20.04 LTS 或更高版本
Node.js	≥ 22.0.0（必需）
内存	至少 4GB RAM（建议 8GB）
存储	至少 2GB 可用空间
网络	稳定的互联网连接

Node.js 版本检查

在安装 OpenClaw 之前，请确保您的系统已安装 Node.js ≥ 22：

# 检查 Node.js 版本
node –version

# 如果版本低于 22，请先安装或升级 Node.js
# 使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

支持的包管理器

OpenClaw 支持以下包管理器：

npm (推荐)
pnpm (备用)
Bun (用于从源码运行 TypeScript)

⚡ 安装步骤

方法一：使用 npm 安装（推荐）

# 全局安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw –version

方法二：使用 pnpm 安装

# 全局安装 OpenClaw
pnpm add -g openclaw@latest

# 验证安装
openclaw –version

方法三：从源码安装（开发版本）

如果您需要最新开发版本或想要贡献代码：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（推荐使用 pnpm）
pnpm install

# 构建项目
pnpm build

# 运行 onboarding 向导
pnpm openclaw onboard –install-daemon

安装验证

安装完成后，运行以下命令验证安装：

# 查看 OpenClaw 版本
openclaw –version

# 查看帮助信息
openclaw –help

⚙️ 配置向导

启动配置向导

OpenClaw 提供了一个交互式的配置向导，帮助您完成初始设置：

# 启动配置向导并安装守护进程
openclaw onboard –install-daemon

配置向导流程

配置向导会引导您完成以下步骤：

🔧 OpenClaw Onboarding Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 配置模型 (anthropic/claude-opus-4-5)
2. 配置工作区 (~/.openclaw/workspace)
3. 配置通道 (WhatsApp/Telegram/Slack/Discord)
4. 安装 Gateway 守护进程
5. 完成

步骤 1：配置 AI 模型

OpenClaw 支持多种 AI 模型，官方推荐：

Anthropic Claude Pro/Max (推荐) + Opus 4.5
OpenAI ChatGPT/Codex

配置示例（~/.openclaw/openclaw.json）：

{
agent: {
model: "anthropic/claude-opus-4-5",
},
}

步骤 2：配置工作区

工作区是 OpenClaw 存储配置和文件的地方：

默认路径：~/.openclaw/workspace
配置文件：AGENTS.md, SOUL.md, TOOLS.md

步骤 3：配置消息通道

OpenClaw 支持多种消息平台：

平台配置方式

WhatsApp	pnpm openclaw channels login
Telegram	设置 TELEGRAM_BOT_TOKEN
Slack	设置 SLACK_BOT_TOKEN + SLACK_APP_TOKEN
Discord	设置 DISCORD_BOT_TOKEN
Signal	需要 signal-cli
iMessage	通过 BlueBubbles 推荐

步骤 4：安装 Gateway 守护进程

守护进程确保 Gateway 在后台持续运行：

# 安装守护进程
openclaw onboard –install-daemon

# 手动启动 Gateway
openclaw gateway –port 18789 –verbose

启动 Gateway

配置完成后，启动 Gateway：

# 前台运行
openclaw gateway –port 18789 –verbose

# 或使用后台模式
openclaw gateway –port 18789

Gateway 默认监听：ws://127.0.0.1:18789

📚 常用命令

Gateway 管理

# 启动 Gateway
openclaw gateway –port 18789 –verbose

# 停止 Gateway（按 Ctrl+C）
# 或使用守护进程管理
openclaw gateway stop

# 检查 Gateway 状态
openclaw doctor

消息发送

# 发送消息到指定联系人
openclaw message send –to +1234567890 –message "Hello from OpenClaw"

# 发送消息到群组
openclaw message send –channel telegram –message "Hello group!"

与 AI 助手对话

# 发送消息给助手
openclaw agent –message "Ship checklist" –thinking high

# 交互式对话模式
openclaw agent

通道管理

# 登录通道
pnpm openclaw channels login

# 查看已配置的通道
openclaw channels list

# 查看通道状态
openclaw doctor

系统诊断

# 运行系统诊断
openclaw doctor

# 检查配置
openclaw doctor –config

# 查看日志
openclaw doctor –logs

更新 OpenClaw

# 更新到最新版本
openclaw update

# 切换更新通道
openclaw update –channel stable|beta|dev

# 更新通道说明
# – stable: 稳定版（推荐）
# – beta: 测试版
# – dev: 开发版

其他实用命令

# 查看帮助
openclaw –help

# 查看特定命令帮助
openclaw gateway –help
openclaw agent –help
openclaw message –help

# 配对管理
openclaw pairing approve <channel> <code>

🔧 故障排除

常见问题

1. Node.js 版本问题

问题：Node.js version must be >= 22

解决方案：

# 检查当前版本
node –version

# 使用 nvm 安装 Node.js 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

2. Gateway 无法启动

问题：Port 18789 already in use 或 Gateway 连接失败

解决方案：

# 检查端口占用
lsof -i :18789

# 停止占用端口的进程
kill <PID>

# 或使用其他端口
openclaw gateway –port 18790

3. npm 安装权限错误

问题：EACCES: permission denied

解决方案：

# 方法 1：使用 sudo（不推荐）
sudo npm install -g openclaw@latest

# 方法 2：配置 npm 使用用户目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest

4. 通道登录失败

问题：WhatsApp/Telegram 等通道无法登录

解决方案：

# 检查凭证配置
cat ~/.openclaw/openclaw.json

# 检查通道日志
openclaw doctor –logs

# 重新登录通道
pnpm openclaw channels login

5. 守护进程问题

问题：Gateway 守护进程无法启动或停止工作

解决方案：

# 检查守护进程状态
systemctl –user status openclaw

# 重新安装守护进程
openclaw onboard –install-daemon

# 手动启动守护进程
systemctl –user start openclaw

# 查看守护进程日志
journalctl –user -u openclaw -f

6. 内存不足

问题：Gateway 运行一段时间后崩溃

解决方案：

# 检查内存使用
free -h

# 清理 Gateway 进程
openclaw gateway stop
pkill -f openclaw

# 重启 Gateway
openclaw gateway –port 18789

诊断命令

当遇到问题时，运行以下命令获取诊断信息：

# 完整系统检查
openclaw doctor

# 检查配置
openclaw doctor –config

# 检查通道状态
openclaw doctor –channels

# 检查日志
openclaw doctor –logs

# 检查网络连接
openclaw doctor –network

日志查看

OpenClaw 的日志文件位置：

# Gateway 日志
cat ~/.openclaw/logs/gateway.log

# 通道日志
cat ~/.openclaw/logs/channels.log

# 实时查看日志
tail -f ~/.openclaw/logs/gateway.log

获取帮助

如果以上方法都无法解决您的问题：

查看官方文档：https://docs.openclaw.ai

查看故障排除指南：https://docs.openclaw.ai/channels/troubleshooting

加入 Discord 社区：https://discord.gg/clawd

提交 Issue：https://github.com/openclaw/openclaw/issues

🏗️ OpenClaw 架构概览

┌─────────────────────────────────────────────────────────────────┐
│ OpenClaw 架构图 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ WhatsApp / Telegram / Slack / Discord / Google Chat / Signal │
│ iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Gateway (控制平面) │ │
│ │ ws://127.0.0.1:18789 │ │
│ │ • 会话管理 • 通道连接 • 工具执行 • 事件处理 │ │
│ └────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Pi Agent │ │ CLI │ │ Web UI │ │
│ │ (RPC) │ │ openclaw.. │ │ Dashboard │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ macOS App │ │ iOS Node │ │ Android Node│ │
│ │ Menu Bar │ │ Canvas │ │ Canvas │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘

架构说明

消息渠道层 – 接收来自各平台的消息

Gateway 控制平面 – 核心控制单元，管理会话和工具

Agent 运行时 – AI 智能体，处理消息和执行任务

客户端层 – CLI、Web UI、桌面/移动应用

📖 参考资源

官方资源

官网：https://openclaw.ai
文档：https://docs.openclaw.ai
GitHub：https://github.com/OpenClaw/OpenClaw
Discord：https://discord.gg/clawd

快速入门

Getting Started
Onboarding Wizard
Showcase
FAQ

安装与更新

Installation Guide
Updating
Docker Installation
Nix Installation

配置与使用

Gateway Configuration
Models
Channel Setup
Security Guide

📝 终端命令示例

$ openclaw onboard –install-daemon
🔧 OpenClaw Onboarding Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 配置模型 (anthropic/claude-opus-4-5)
2. 配置工作区 (~/.openclaw/workspace)
3. 配置通道 (WhatsApp/Telegram/Slack/Discord)
4. 安装 Gateway 守护进程
5. 完成

> 选择操作: 4
✅ 正在安装 Gateway 守护进程…
✅ 守护进程安装成功！

$ openclaw gateway –port 18789 –verbose
🔌 Gateway 启动在 ws://127.0.0.1:18789
✅ Gateway 已就绪

$ openclaw message send –to +1234567890 –message "Hello from OpenClaw"
✅ 消息已发送

$ openclaw agent –message "Ship checklist" –thinking high
🤖 正在思考…
✅ 响应已生成

🎯 下一步

完成安装后，建议您：

✅ 运行 openclaw onboard 完成初始配置

✅ 启动 Gateway：openclaw gateway –port 18789 –verbose

✅ 配置至少一个消息渠道

✅ 尝试发送第一条消息测试

✅ 查看文档了解高级功能

Happy Exfoliating! 🦞

OpenClaw 由 Peter Steinberger 和社区开发维护