Ubuntu 24.04 部署 OpenClaw 完整教程-下雪啦资源网

安装准备

在开始之前，请确保您的 Ubuntu 24.04 系统满足以下要求：

Node.js 22.14 或更高版本（推荐 Node 24）
管理员权限（sudo）
稳定的网络连接（用于下载 npm 包）

1. 安装 Node.js

OpenClaw 需要 Node.js 来运行。Ubuntu 24.04 默认的 Node.js 版本可能较旧，建议使用 NodeSource 仓库安装最新版本：

# 安装必要依赖
sudo apt update
sudo apt install -y curl build-essential

# 添加 NodeSource 仓库（安装 Node 24 LTS）
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

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

2. 全局安装 OpenClaw

使用 npm 全局安装 OpenClaw（这是官方推荐的方式，不需要 Docker 和源码编译）：

# 安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
code openclaw --version

3. 初始化配置向导

运行 onboarding 向导来配置 OpenClaw：

# 运行配置向导
openclaw onboard --install-daemon

# 按照提示操作：
# 1. 选择模型提供商（如 Anthropic、OpenAI、Google 等）
# 2. 输入 API Key
# 3. 配置 Gateway 设置
# 4. 选择安装守护进程（systemd）

# 向导大约需要 2-3 分钟完成

4. 验证 Gateway 运行状态

检查 Gateway 是否正常运行：

# 检查 Gateway 状态
code openclaw gateway status

# 您应该看到 Gateway 在 18789 端口监听

5. 启动 Web 控制界面

打开浏览器控制界面：

# 启动控制界面（自动打开浏览器）
code openclaw dashboard

# 如果没有自动打开，手动访问：
# http://localhost:18789/

# 或者使用 Tailscale 远程访问（如果配置了）
# https://your-tailnet-name.openclaw.gateway

6. 首次聊天测试

在 Web 控制界面中发送第一条消息，测试 AI 助手是否正常工作：

# 在控制界面输入：
你好，请介绍一下你自己

# 您应该收到 AI 助手的回复

7. 配置系统服务（开机自启）

如果选择了安装守护进程，OpenClaw 会自动配置为系统服务。您可以手动管理服务：

# 查看服务状态
sudo systemctl status openclaw

# 启动服务
sudo systemctl start openclaw

# 停止服务
sudo systemctl stop openclaw

# 重启服务
sudo systemctl restart openclaw

# 设置开机自启
sudo systemctl enable openclaw

# 禁用开机自启
sudo systemctl disable openclaw

8. 常用命令

OpenClaw 提供了以下常用命令：

openclaw gateway status – 查看 Gateway 状态
openclaw gateway restart – 重启 Gateway
openclaw dashboard – 打开 Web 控制界面
openclaw tui – 启动终端交互界面
openclaw onboard – 运行配置向导
openclaw channel list – 列出已配置的频道

9. 配置文件位置

OpenClaw 的配置文件位于：

配置文件：~/.openclaw/openclaw.json
状态目录：~/.openclaw/state/
数据目录：~/.openclaw/data/
日志目录：~/.openclaw/logs/

10. 更新 OpenClaw

定期更新到最新版本：

# 更新 OpenClaw
npm update -g openclaw

# 或者指定版本
npm install -g openclaw@latest

# 卸载 OpenClaw
npm uninstall -g openclaw

11. 故障排查

问题：Gateway 未运行

# 检查服务状态
sudo systemctl status openclaw

# 查看日志
sudo journalctl -u openclaw -f

# 手动启动测试
code openclaw gateway start

问题：无法访问 Web 界面

# 检查端口是否监听
sudo netstat -tlnp | grep 18789

# 检查防火墙设置
sudo ufw status
sudo ufw allow 18789/tcp

# 检查配置文件中的端口设置
cat ~/.openclaw/openclaw.json | grep controlUi

问题：API Key 无效

# 重新运行 onboard 向导
openclaw onboard

# 或手动编辑配置文件
cat ~/.openclaw/openclaw.json

12. 高级配置

配置多个模型提供商

在 openclaw.json 中配置多个模型提供商：

{
  "gateway": {
    "models": {
      "default": {
        "provider": "anthropic",
        "apiKey": "your-api-key"
      },
      "alternative": {
        "provider": "openai",
        "apiKey": "your-openai-key"
      }
    }
  }
}

配置系统环境变量

# 在 /etc/environment 或 ~/.bashrc 中添加
export OPENCLAW_HOME=/path/to/openclaw
export OPENCLAW_STATE_DIR=/path/to/state
export OPENCLAW_CONFIG_PATH=/path/to/config.json

# 重新加载配置
source ~/.bashrc