OpenClaw Ubuntu 安装指南

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

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

# 克隆仓库
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 支持多种消息平台：

步骤 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

获取帮助

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

1. 查看官方文档：https://docs.openclaw.ai
2. 查看故障排除指南：https://docs.openclaw.ai/channels/troubleshooting
3. 提交 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

快速入门

• 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. ✅ 查看文档了解高级功能