Ubuntu 系统 OpenClaw AI 框架完整安装与部署指南

OpenClaw（原Clawdbot）是一款开源全平台个人AI助手框架，支持多模型接入、多渠道消息互通、自定义技能扩展与自动化工作流，可部署在Ubuntu桌面/服务器实现7×24小时运行。本指南基于官方最新规范编写，全程可落地、步骤可复现，适配Ubuntu 22.04 LTS及以上版本。

1. Node.js 22.x及以上：框架核心运行环境，Ubuntu默认apt源版本不满足要求，需通过官方源安装
2. 包管理器：npm（Node自带）、pnpm（推荐，性能更优）
3. Git：用于源码克隆与版本管理
4. 网络要求：国内用户需配置可正常访问海外API的网络环境，否则会出现网关启动失败、模型调用异常等问题

执行以下命令更新系统并安装基础依赖，全程可直接复制执行：

# 更新系统软件源 sudo apt update && sudo apt upgrade -y # 安装基础依赖包 sudo apt install -y curl git build-essential ca-certificates

官方一键脚本会自动完成环境检测、Node.js安装、OpenClaw部署与权限配置，全程无需手动干预，是最省心的安装方式。

# 执行官方一键安装脚本 curl -fsSL https://openclaw.ai/install.sh | bash

脚本执行完成后，会自动进入初始化配置向导，直接跳转到本文第三章操作即可。

适合需要自主管理Node环境、自定义安装路径的用户，分为npm和pnpm两种方式。

# 导入NodeSource官方GPG密钥 curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/nodesource.gpg # 添加Node.js 22.x软件源 echo "deb [signed-by=/etc/apt/trusted.gpg.d/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list # 安装Node.js sudo apt update && sudo apt install -y nodejs # 验证安装（输出版本号≥22.x即为正常） node -v npm -v

# 方式1：npm安装（通用） npm install -g openclaw@latest # 方式2：pnpm安装（推荐，性能更优） # 先安装pnpm npm install -g pnpm # 再安装OpenClaw pnpm add -g openclaw@latest

若出现权限报错，执行以下命令配置用户级全局路径，避免使用sudo：

# 配置npm全局路径到用户目录 mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' # 将路径写入环境变量 echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

适合需要二次开发、修改源码、使用开发版功能的用户。

# 克隆官方GitHub仓库 git clone https://github.com/openclaw/openclaw.git cd openclaw  # 安装项目依赖（推荐使用pnpm） pnpm install  # 构建前端UI与核心项目 pnpm ui:build pnpm build  # 本地运行初始化向导 pnpm openclaw onboard --install-daemon

安装完成后，核心步骤是通过交互式向导完成基础配置，这是框架正常运行的关键。

OpenClaw本身不内置大模型，需接入第三方模型服务，提前准备好以下任一平台的API密钥：

• 官方推荐：Anthropic Claude（Sonnet/Opus），长上下文与工具调用能力最优
• 通用选择：OpenAI GPT系列
• 国内适配：MiniMax、通义千问、文心一言等兼容OpenAI格式的模型

执行以下命令启动交互式配置向导，–install-daemon参数会自动配置systemd用户服务，实现开机自启动：

openclaw onboard --install-daemon

向导会按以下流程引导配置，全程按提示操作即可：

1. 模型配置：选择你要使用的AI模型厂商，输入对应的API密钥，向导会自动验证密钥有效性
2. 工作区配置：设置框架数据存储目录，默认路径为~/openclaw，包含代理配置、技能文件、日志等核心数据
3. 消息通道配置：可选配置WhatsApp、Telegram、Slack、Discord等渠道，实现多平台消息互通
4. 网关守护进程安装：确认安装systemd服务，实现后台常驻运行、开机自启动
5. 配置完成：向导会自动生成配置文件，启动网关服务，输出访问地址与管理凭证

执行以下命令，确认框架安装正常：

# 查看版本号，输出版本信息即为安装成功 openclaw --version  # 执行环境自检，自动排查配置问题与依赖缺失 openclaw doctor

1. 启动网关服务

# 后台启动网关（推荐，常驻运行） openclaw gateway start  # 前台运行（仅用于调试，关闭终端即停止） openclaw gateway run --verbose

2. 访问管理控制台
   执行以下命令自动打开控制台，或手动在浏览器访问 http://localhost:18789
   

openclaw dashboard

注意：远程服务器访问时，不可直接通过公网IP+HTTP访问，浏览器会限制功能，需配置HTTPS反向代理，详见第六章进阶部署。

解决方案：

1. 不要使用sudo执行npm全局安装，按本文2.2章节配置用户级npm全局路径
2. 执行sudo chown -R $USER:$USER ~/.npm修复npm缓存权限

解决方案：

1. 确认网络环境可正常访问你配置的模型API服务，国内用户需配置代理
2. 为终端配置代理环境变量：

export HTTP_PROXY=http://你的代理地址:端口 export HTTPS_PROXY=http://你的代理地址:端口 # 重启网关服务 openclaw gateway restart

解决方案：

1. 卸载系统自带的旧版本Node.js：sudo apt remove –purge nodejs npm
2. 按本文2.2章节步骤，通过NodeSource官方源安装Node.js 22.x及以上版本

openclaw 安装

解决方案：

1. 执行openclaw doctor检查密钥配置是否正确
2. 确认API密钥有足够的余额与调用权限，未被平台限制
3. 查看网关日志排查具体报错：openclaw gateway logs

解决方案：

1. 重新执行初始化向导，确保开启守护进程安装：openclaw onboard –install-daemon
2. 手动启用systemd用户服务：

systemctl --user enable --now openclaw-gateway systemctl --user status openclaw-gateway

适合服务器环境隔离部署，避免环境依赖冲突，创建docker-compose.yml文件：

version: '3.8' services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: always ports: - "18789:18789" environment: - OPENCLAW_GATEWAY_TOKEN=自定义安全令牌 - ANTHROPIC_API_KEY=你的Claude API密钥 # 可选：OPENAI_API_KEY=你的OpenAI API密钥 volumes: - ./openclaw-data:/root/openclaw networks: - openclaw-net networks: openclaw-net: driver: bridge

执行以下命令启动容器：

docker compose up -d

远程访问控制台必须使用HTTPS，推荐使用Caddy自动配置SSL证书，步骤如下：

1. 安装Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update && sudo apt install caddy

2. 配置Caddy反向代理，编辑/etc/caddy/Caddyfile：

你的域名.com { reverse_proxy localhost:18789 }

3. 重启Caddy服务，自动申请SSL证书并启用HTTPS：

sudo systemctl restart caddy

配置完成后，即可通过https://你的域名.com安全访问控制台。

1. 配置防火墙，仅开放必要端口：

sudo ufw allow ssh sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable

2. 禁止公网直接访问18789端口，仅通过本地回环或HTTPS反向代理访问
3. 定期更新框架版本：npm update -g openclaw@latest
4. 配置网关访问令牌，禁止无授权访问控制台

OpenClaw支持接入本地部署的兼容OpenAI格式的大模型（如Ollama、Llama.cpp），只需在配置中修改模型API地址为本地服务地址，即可实现完全本地化的AI助手，无需依赖第三方API服务。