OpenClaw Ubuntu 安装指南OpenClaw Ubuntu 安装指南 📋 目录简介系统要求安装步骤

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

获取帮助

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

查看官方文档：docs.openclaw.ai
查看故障排除指南：docs.openclaw.ai/channels/tr…
加入 Discord 社区：discord.gg/clawd
提交 Issue：github.com/openclaw/op…

🏗️ 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、桌面/移动应用

📖 参考资源

官方资源

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

快速入门

安装与更新

配置与使用

📝 终端命令示例

$ 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 和社区开发维护