主流家用Linux发行版

• Ubuntu (推荐) - 用户友好，社区支持强大
• Debian - 稳定可靠，适合长期运行
• Fedora - 较新软件包，适合技术爱好者
• CentOS Stream - 企业级稳定性
• Arch Linux - 高度可定制，适合高级用户

系统要求

最低硬件要求

• CPU: 2核以上
• 内存: 2GB RAM
• 存储: 10GB可用空间
• 网络: 稳定的互联网连接

软件依赖

• Node.js: v18.x 或更高版本
• npm: v8.x 或更高版本
• Git: 用于版本控制和更新
• System packages:
  • build-essential (Debian/Ubuntu)
  • gcc-c++ (RHEL/CentOS/Fedora)
  • python3 (某些npm包需要)

安装前检查清单

[ ] 系统信息确认

• 操作系统版本: lsb_release -a 或 cat /etc/os-release
• 架构确认: uname -m (应为x86_64或arm64)
• 可用磁盘空间: df -h
• 可用内存: free -h

[ ] 网络配置

• 网络连接测试: ping 8.8.8.8
• DNS解析测试: nslookup google.com
• 防火墙状态: sudo ufw status (Ubuntu) 或 sudo firewall-cmd --state (Fedora/CentOS)

[ ] 用户权限

• 当前用户是否在sudo组: groups
• 是否可以执行sudo命令: sudo whoami

[ ] 现有环境检查

• Node.js版本: node --version
• npm版本: npm --version
• Git版本: git --version

准备工作

1. 系统更新

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# Fedora
sudo dnf update -y

# CentOS/RHEL
sudo yum update -y

2. 安装基础开发工具

# Ubuntu/Debian
sudo apt install -y build-essential git curl

# Fedora
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y git curl

# CentOS/RHEL
sudo yum groupinstall -y "Development Tools"
sudo yum install -y git curl

3. 创建专用用户（可选但推荐）

sudo adduser openclaw
sudo usermod -aG sudo openclaw  # Ubuntu/Debian
# 或
sudo usermod -aG wheel openclaw  # RHEL/CentOS/Fedora

Node.js环境配置

方法1: 使用NodeSource官方仓库（推荐）

Ubuntu/Debian

# 1. 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

# 2. 安装Node.js和npm
sudo apt-get install -y nodejs

# 3. 验证安装
node --version
npm --version

RHEL/CentOS/Fedora

# 1. 添加NodeSource仓库
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -

# 2. 安装Node.js和npm
sudo yum install -y nodejs
# 或者在Fedora上使用
sudo dnf install -y nodejs

# 3. 验证安装
node --version
npm --version

方法2: 使用nvm（Node Version Manager）

# 1. 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. 重新加载shell配置
source ~/.bashrc
# 或者
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 3. 安装Node.js 18.x
nvm install 18
nvm use 18
nvm alias default 18

# 4. 验证安装
node --version
npm --version

方法3: 手动下载安装（适用于离线环境）

# 1. 下载Node.js二进制包
wget https://nodejs.org/dist/v18.19.0/node-v18.19.0-linux-x64.tar.xz

# 2. 解压到/opt目录
sudo tar -xf node-v18.19.0-linux-x64.tar.xz -C /opt/
sudo mv /opt/node-v18.19.0-linux-x64 /opt/nodejs

# 3. 创建符号链接
sudo ln -s /opt/nodejs/bin/node /usr/local/bin/node
sudo ln -s /opt/nodejs/bin/npm /usr/local/bin/npm

# 4. 验证安装
node --version
npm --version

OpenClaw核心组件安装

1. 全局安装OpenClaw CLI

# 安装OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

2. 配置npm全局目录（可选但推荐）

# 创建全局npm目录
mkdir ~/.npm-global

# 配置npm使用新目录
npm config set prefix '~/.npm-global'

# 添加到PATH（添加到~/.bashrc或~/.profile）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证PATH配置
which openclaw

3. 安装系统依赖

Ubuntu/Debian

# 安装必要的系统包
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    python3 \
    git \
    curl \
    wget \
    unzip \
    libx11-dev \
    libx11-xcb-dev \
    libsecret-1-dev \
    libgtk-3-dev \
    libnotify-dev \
    libglib2.0-dev \
    libnss3-dev \
    libasound2-dev \
    libxtst-dev \
    xauth \
    xvfb

# 安装音视频支持（可选）
sudo apt-get install -y \
    pulseaudio \
    alsa-utils \
    ffmpeg

RHEL/CentOS/Fedora

# 安装必要的系统包
sudo yum groupinstall -y "Development Tools"
sudo yum install -y \
    python3 \
    git \
    curl \
    wget \
    unzip \
    libX11-devel \
    libX11-xcb-devel \
    libsecret-devel \
    gtk3-devel \
    libnotify-devel \
    glib2-devel \
    nss-devel \
    alsa-lib-devel \
    libXtst-devel \
    xorg-x11-server-Xvfb

# Fedora用户使用dnf
# sudo dnf groupinstall -y "Development Tools"
# sudo dnf install -y [same packages as above]

# 安装音视频支持（可选）
sudo yum install -y \
    pulseaudio \
    alsa-utils \
    ffmpeg

权限和安全配置

1. 创建专用用户（推荐）

# 创建openclaw用户
sudo adduser --system --group --no-create-home openclaw

# 或创建普通用户（如果需要交互式登录）
sudo adduser openclaw
sudo usermod -aG sudo openclaw  # Ubuntu/Debian
# sudo usermod -aG wheel openclaw  # RHEL/CentOS/Fedora

2. 配置sudo权限（如果需要）

# 编辑sudoers文件
sudo visudo

# 添加以下行（替换username为实际用户名）
username ALL=(ALL) NOPASSWD: /usr/bin/openclaw, /usr/local/bin/openclaw

3. 防火墙配置

Ubuntu/Debian (UFW)

# 允许HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 允许OpenClaw默认端口（如果使用Web界面）
sudo ufw allow 3000/tcp

# 启用防火墙
sudo ufw enable

RHEL/CentOS/Fedora (firewalld)

# 允许HTTP/HTTPS
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# 允许OpenClaw默认端口
sudo firewall-cmd --permanent --add-port=3000/tcp

# 重载防火墙规则
sudo firewall-cmd --reload

验证安装

1. 基本功能测试

# 检查OpenClaw版本
openclaw --version

# 检查可用命令
openclaw help

# 初始化工作区
openclaw init

2. 依赖检查

# 检查Node.js版本
node --version

# 检查npm版本
npm --version

# 检查全局安装的包
npm list -g --depth=0

3. 系统信息验证

# 检查系统架构
uname -m

# 检查可用内存
free -h

# 检查磁盘空间
df -h

故障排除

常见安装问题

1. npm权限错误

症状: Error: EACCES: permission denied 解决方案: - 使用方法2（nvm）安装Node.js - 或配置npm全局目录（见上文）

2. 缺少编译依赖

症状: gyp ERR! build error 解决方案: - 确保已安装build-essential（Ubuntu/Debian）或Development Tools（RHEL/CentOS/Fedora）

3. 网络连接问题

症状: npm ERR! network timeout 解决方案: - 配置npm镜像源： bash npm config set registry https://registry.npmmirror.com

4. 版本冲突

症状: Unsupported Node.js version 解决方案: - 确保使用Node.js 18.x版本 - 使用nvm管理多个Node.js版本

OpenClaw基础配置

1. 配置文件位置

OpenClaw的配置文件通常位于以下位置： - 全局配置: ~/.openclaw/config.json - 工作区配置: /home/admin/openclaw/workspace-agents/lobster-master/config.json - 插件配置: ~/.openclaw/extensions/

2. 基础配置项说明

核心配置 (config.json)

{
  "model": "generic/qwen3-max-2026-01-23",
  "workspace": "/home/admin/openclaw/workspace-agents/lobster-master",
  "timezone": "Asia/Shanghai",
  "channels": {
    "webchat": {
      "enabled": true
    },
    "telegram": {
      "enabled": false,
      "token": "your-telegram-bot-token"
    },
    "discord": {
      "enabled": false,
      "token": "your-discord-bot-token"
    }
  },
  "security": {
    "allowDangerousCommands": false,
    "requireConfirmation": true
  },
  "memory": {
    "enabled": true,
    "path": "/home/admin/openclaw/workspace-agents/lobster-master/memory"
  }
}

3. 配置步骤

步骤1: 初始化配置文件

# 创建配置目录
mkdir -p ~/.openclaw

# 生成默认配置
openclaw config init

步骤2: 编辑基础配置

nano ~/.openclaw/config.json

根据需要修改以下关键配置项： - model: 选择合适的AI模型 - workspace: 设置工作目录路径 - timezone: 设置时区（推荐使用Asia/Shanghai） - channels: 启用需要的通信渠道

步骤3: 配置安全设置

{
  "security": {
    "allowDangerousCommands": false,
    "requireConfirmation": true,
    "allowedHosts": ["localhost", "127.0.0.1"],
    "maxExecutionTime": 300
  }
}

4. 插件和技能配置

安装常用插件

# 安装Feishu插件（如果需要）
npm install -g @openclaw/feishu

# 安装语音插件（如果需要）
npm install -g @openclaw/voice

配置插件

创建插件配置文件 ~/.openclaw/extensions/feishu/config.json:

{
  "appId": "your-feishu-app-id",
  "appSecret": "your-feishu-app-secret",
  "verificationToken": "your-verification-token"
}

5. 首次运行验证

启动OpenClaw服务

# 启动Gateway服务
openclaw gateway start

# 检查服务状态
openclaw gateway status

验证基本功能

# 测试基本命令
openclaw help

# 测试配置加载
openclaw config get

Web界面访问（如果启用）

• 访问 http://localhost:3000（默认端口）
• 确认界面正常加载
• 测试基本交互功能

6. 日志和监控配置

日志配置

{
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log",
    "maxSize": "100MB",
    "maxFiles": 10
  }
}

创建日志目录

mkdir -p ~/.openclaw/logs

7. 自动启动配置（可选）

systemd服务配置（Ubuntu/Debian/CentOS 7+）

创建服务文件 /etc/systemd/system/openclaw.service:

[Unit]
Description=OpenClaw AI Assistant
After=network.target

[Service]
Type=simple
User=admin
WorkingDirectory=/home/admin
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

8. 备份和恢复

配置备份

# 备份整个配置目录
tar -czf openclaw-config-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

配置恢复

# 恢复配置
tar -xzf openclaw-config-backup-20260309.tar.gz -C ~/

常见配置问题排查

1. 配置文件权限问题

# 确保配置文件权限正确
chmod 600 ~/.openclaw/config.json
chmod 700 ~/.openclaw

2. 路径配置错误

• 确认所有路径使用绝对路径
• 检查工作目录是否存在且有写权限
• 验证插件路径是否正确

3. 端口冲突

• 检查默认端口（3000）是否被占用
• 修改配置中的端口设置
• 使用 netstat -tlnp | grep :3000 检查端口占用

4. 模型配置问题

• 确认指定的模型名称正确
• 检查API密钥是否有效（如果使用外部API）
• 验证网络连接是否正常

5个预设智能体配置

1. art-designer (美术设计师)

用途: 处理图像生成、设计相关任务 配置文件: ~/.openclaw/agents/art-designer/SOUL.md

name: "art-designer"
role: "专业美术设计师"
capabilities: ["image-generation", "design-analysis", "creative-direction"]

2. marketing-writer (营销文案专家)

用途: 创建营销内容、文案撰写 配置文件: ~/.openclaw/agents/marketing-writer/SOUL.md

name: "marketing-writer"
role: "专业营销文案专家"
capabilities: ["copywriting", "content-strategy", "brand-voice"]

3. sys-ops (系统运维工程师)

用途: 系统管理、故障排除、性能优化 配置文件: ~/.openclaw/agents/sys-ops/SOUL.md

name: "sys-ops"
role: "专业系统运维工程师"
capabilities: ["system-administration", "troubleshooting", "performance-tuning"]

4. data-researcher (资料搜集研究员)

用途: 信息搜集、数据分析、研究任务 配置文件: ~/.openclaw/agents/data-researcher/SOUL.md

name: "data-researcher"
role: "专业资料搜集研究员"
capabilities: ["web-research", "data-analysis", "information-synthesis"]

5. shrimp-t800 (代码开发专家)

用途: 编程、代码审查、技术实现 配置文件: ~/.openclaw/agents/shrimp-t800/SOUL.md

name: "shrimp-t800"
role: "专业代码开发专家"
capabilities: ["coding", "code-review", "technical-implementation"]

配置步骤

1. 创建智能体目录

mkdir -p ~/.openclaw/agents/{art-designer,marketing-writer,sys-ops,data-researcher,shrimp-t800}

2. 配置每个智能体的SOUL.md

为每个智能体创建对应的SOUL.md文件，定义其角色、能力和行为准则。

3. 配置AGENT.md

在每个智能体目录下创建AGENT.md文件：

# ~/.openclaw/agents/art-designer/AGENT.md
model: "generic/qwen3-max-2026-01-23"
tools: ["browser", "canvas", "qwen-image"]
workspace: "/home/admin/openclaw/workspace-agents/art-designer"

4. 初始化工作空间

# 为每个智能体创建工作空间
for agent in art-designer marketing-writer sys-ops data-researcher shrimp-t800; do
    mkdir -p "/home/admin/openclaw/workspace-agents/$agent"
done

5. 验证配置

# 检查所有智能体配置
ls -la ~/.openclaw/agents/

使用智能体

配置完成后，可以通过以下方式调用智能体： - 在主会话中使用 @agent-name 提及 - 通过 sessions_spawn 工具创建子会话 - 在任务分配时指定特定智能体处理

这些智能体将与龙虾场主（主Agent）协同工作，形成完整的多智能体系统。

常见安装问题

1. Node.js版本不兼容

症状: 安装过程中出现版本错误或依赖冲突 解决方案:

# 检查当前Node.js版本
node --version

# 如果版本过低，使用nvm管理Node.js版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

2. 权限问题

症状: EACCES 错误或无法写入全局目录 解决方案:

# 方案A: 使用sudo（不推荐）
sudo npm install -g openclaw

# 方案B: 配置npm全局目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3. 网络连接问题

症状: 安装过程中超时或无法下载依赖 解决方案:

# 使用国内镜像源
npm config set registry https://registry.npmmirror.com

# 或临时使用镜像
npm install -g openclaw --registry https://registry.npmmirror.com

4. 缺少系统依赖

症状: 编译错误或缺少头文件 解决方案:

# Ubuntu/Debian
sudo apt install -y build-essential python3-dev libssl-dev

# Fedora/RHEL/CentOS
sudo dnf install -y gcc-c++ python3-devel openssl-devel

运行时问题

1. OpenClaw无法启动

症状: 启动后立即退出或报错 诊断步骤:

# 查看详细日志
openclaw --verbose

# 检查配置文件
cat ~/.openclaw/config.json

# 验证依赖完整性
npm list -g --depth=0 | grep openclaw

2. 插件加载失败

症状: 特定功能不可用或报错 解决方案:

# 重新安装插件
openclaw plugin install <plugin-name>

# 检查插件状态
openclaw plugin list

# 更新所有插件
openclaw plugin update --all

3. 内存不足

症状: 系统变慢或OpenClaw进程被杀死 解决方案:

# 限制Node.js内存使用
export NODE_OPTIONS="--max-old-space-size=1024"
openclaw start

# 或在systemd服务中配置
# /etc/systemd/system/openclaw.service
# Environment=NODE_OPTIONS=--max-old-space-size=1024

日常维护

1. 系统更新

定期更新系统:

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# Fedora
sudo dnf upgrade -y

# CentOS/RHEL
sudo yum update -y

2. OpenClaw更新

更新OpenClaw核心:

# 全局更新
npm update -g openclaw

# 或重新安装最新版本
npm uninstall -g openclaw
npm install -g openclaw@latest

3. 备份配置

重要配置备份:

# 备份配置文件
cp -r ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)

# 备份项目数据
tar -czf openclaw-projects-$(date +%Y%m%d).tar.gz ~/openclaw/workspace-agents/

4. 日志管理

清理旧日志:

# 查看日志大小
du -sh ~/.openclaw/logs/

# 清理30天前的日志
find ~/.openclaw/logs/ -name "*.log" -mtime +30 -delete

性能优化

1. 系统级优化

# 增加文件描述符限制
echo "fs.file-max = 100000" | sudo tee -a /etc/sysctl.conf
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

2. Node.js优化

# 启用V8优化
export NODE_OPTIONS="--max-old-space-size=2048 --optimize_for_size --max_executable_size=2048"

# 在生产环境中禁用调试
export NODE_ENV=production

3. 监控资源使用

# 安装系统监控工具
sudo apt install htop iotop

# 监控OpenClaw进程
htop -p $(pgrep -f openclaw)

紧急恢复

1. 完全重置

# 停止OpenClaw
openclaw stop

# 备份并删除配置
mv ~/.openclaw ~/.openclaw-corrupted
mkdir ~/.openclaw

# 重新初始化
openclaw init

2. 数据恢复

# 从备份恢复配置
cp -r ~/.openclaw-backup-20260309/* ~/.openclaw/

# 重启服务
openclaw restart

支持资源

官方文档

• OpenClaw官方文档
• GitHub Issues
• Discord社区