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 - 智能体驱动的可视化工作区
• 🗣️ 语音交互 - 支持语音唤醒和对话模式
• 🔧 丰富的工具集 - 浏览器控制、节点管理、自动化等

🖥️ 系统要求

最低系统要求

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 |bashsource ~/.bashrc nvm install22 nvm use 22

支持的包管理器

OpenClaw 支持以下包管理器：

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

⚡ 安装步骤

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

# 全局安装 OpenClawnpminstall -g openclaw@latest # 验证安装 openclaw --version 

方法二：使用 pnpm 安装

# 全局安装 OpenClawpnpmadd -g openclaw@latest # 验证安装 openclaw --version 

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

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

# 克隆仓库git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖（推荐使用 pnpm）pnpminstall# 构建项目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 支持多种消息平台：

步骤 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 22curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh |bashsource ~/.bashrc nvm install22 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（不推荐）sudonpminstall -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 npminstall -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 

获取帮助

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

1. 查看官方文档：https://docs.openclaw.ai
2. 查看故障排除指南：https://docs.openclaw.ai/channels/troubleshooting
3. 加入 Discord 社区：https://discord.gg/clawd
4. 提交 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 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ 

架构说明

1. 消息渠道层 - 接收来自各平台的消息
2. Gateway 控制平面 - 核心控制单元，管理会话和工具
3. Agent 运行时 - AI 智能体，处理消息和执行任务
4. 客户端层 - 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 🤖 正在思考... ✅ 响应已生成 

🎯 下一步

完成安装后，建议您：

1. ✅ 运行 openclaw onboard 完成初始配置
2. ✅ 启动 Gateway：openclaw gateway --port 18789 --verbose
3. ✅ 配置至少一个消息渠道
4. ✅ 尝试发送第一条消息测试
5. ✅ 查看文档了解高级功能

Happy Exfoliating! 🦞

OpenClaw 由 Peter Steinberger 和社区开发维护