OpenClaw 安装完整指南：从零到部署个人 AI 助手

为什么需要 OpenClaw 安装指南？

OpenClaw 是一个强大的开源个人 AI 助手框架，可以部署在你自己的服务器上。与 ChatGPT、Claude 等云端 AI 服务不同，OpenClaw 强调数据隐私、完全控制和多渠道集成。

本文将手把手教你完成 OpenClaw 的完整安装过程，无论你是使用 Linux 服务器、Mac 电脑还是 Windows 系统，都能找到对应的安装方案。

安装前准备

系统要求

最低配置：

CPU：1 核心
内存：1GB RAM
存储：10GB 可用空间
系统：Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)、macOS 11+、Windows 10+

推荐配置（生产环境）：

CPU：2 核心
内存：2GB RAM
存储：20GB SSD
网络：稳定的互联网连接

必需软件：

Node.js 22 或更高版本（这是硬性要求）

检查版本：node --version

升级 Node.js：

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS
brew install node@22

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

npm 包管理器（随 Node.js 自动安装）
Git（可选，用于从源码安装）

API 密钥准备

OpenClaw 需要一个大语言模型 API 才能工作。推荐使用以下服务之一：

Anthropic Claude（推荐）
- 注册地址：https://console.anthropic.com
- 创建 API Key
- 模型推荐：claude-sonnet-4.5 或 claude-opus-4.6
OpenAI GPT
- 注册地址：https://platform.openai.com
- 创建 API Key
- 模型推荐：gpt-5.3-codex 或 gpt-4o
其他兼容 OpenAI API 的服务
- 国内中转站（如 AnyRouter、KFC API）
- 自建模型网关

保存好你的 API Key，安装过程中会用到。

方法一：快速安装脚本（推荐）

这是最简单的安装方式，适合大多数用户。

Linux / macOS

# 下载并运行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 安装完成后，运行向导
openclaw onboard --install-daemon

安装脚本会自动：

下载最新版本的 OpenClaw
安装到全局路径（/usr/local/lib/openclaw）
创建命令行工具（openclaw）
配置系统服务（systemd 或 launchd）

Windows (PowerShell)

# 以管理员身份运行 PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

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

方法二：npm 安装

如果你更喜欢使用 npm 包管理器，可以直接安装：

# 全局安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw --version

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

配置向导详解

运行 openclaw onboard 后，向导会引导你完成以下步骤：

1. API 密钥配置

? 选择你的 LLM 提供商：
  ▸ Anthropic (Claude)
    OpenAI (GPT)
    自定义 OpenAI 兼容 API

? 输入你的 API Key：
  (粘贴你的密钥，输入时不会显示)

2. Gateway 设置

? Gateway 监听端口：
  (默认 18789，直接回车即可)

? 允许的访问地址：
  (默认 127.0.0.1，如需远程访问可设置为 0.0.0.0)

3. 渠道配置（可选）

向导会询问是否配置消息渠道：

? 是否现在配置消息渠道？ (Y/n)

建议先跳过，等 Gateway 运行后再单独配置。你可以选择：

Telegram：最简单，只需 Bot Token
WhatsApp：需要 WhatsApp Business API
Discord：需要 Bot Token
其他：iMessage、Signal、Google Chat 等

4. 服务安装

? 是否安装为系统服务？ (Y/n)

强烈推荐选择 Y，这样 OpenClaw 会在系统启动时自动运行，并在崩溃后自动重启。

启动和验证

检查服务状态

# 检查 Gateway 是否运行
openclaw gateway status

# 查看日志
openclaw gateway logs

启动 Control UI

# 打开浏览器控制面板
openclaw dashboard

# 或者手动访问
# http://127.0.0.1:18789/

如果看到控制面板加载成功，说明安装完成！

发送测试消息（需要配置渠道）

# Telegram 示例
openclaw message send \
  --channel telegram \
  --target @your_username \
  --message "Hello from OpenClaw!"

方法三：Docker 部署

适合容器化部署和快速测试。

创建 Docker Compose 配置

# 创建工作目录
mkdir ~/openclaw-docker && cd ~/openclaw-docker

# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - NODE_ENV=production
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # 或使用 OpenAI
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/root/.openclaw
      - ./workspace:/workspace
    command: >
      sh -c "
        openclaw gateway start &&
        tail -f /dev/null
      "
EOF

# 创建 .env 文件
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
# OPENAI_API_KEY=sk-xxxxxxxxxxxx
EOF

启动容器

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f openclaw

# 访问控制面板
# http://your-server-ip:18789/

方法四：从源码编译

适合开发者或需要自定义功能的场景。

克隆仓库

# 克隆源码
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

构建和运行

# 构建
npm run build

# 链接到全局
npm link

# 验证
openclaw --version

# 运行向导
openclaw onboard

配置文件详解

配置文件位于 ~/.openclaw/openclaw.json（Linux/macOS）或 %USERPROFILE%\.openclaw\openclaw.json（Windows）。

基础配置示例

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "logLevel": "info"
  },
  "models": {
    "default": "anthropic/claude-sonnet-4.5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxxxx"
      }
    }
  },
  "channels": {
    "telegram": {
      "allowFrom": ["+861xxxxxxxxx"],
      "botToken": "your_bot_token_here"
    },
    "whatsapp": {
      "allowFrom": ["+861xxxxxxxxx"]
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

安全配置建议

限制访问来源：

{
  "channels": {
    "telegram": {
      "allowFrom": ["+861xxxxxxxxx"],  // 只允许你的号码
      "groups": {
        "*": {
          "requireMention": true  // 群聊需要 @ 才响应
        }
      }
    }
  }
}

设置每日预算：

{
  "spending": {
    "dailyLimit": 5.00,
    "alertThreshold": 4.00,
    "currency": "USD"
  }
}

常见问题解决

问题 1：Node.js 版本过低

错误信息：

Error: OpenClaw requires Node.js 22 or higher

解决方法：

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version  # 应该显示 v22.x.x

问题 2：API Key 无效

错误信息：

Error: Invalid API key

解决方法：

检查 API Key 是否正确复制
确认 API Key 有足够的配额
检查是否选择了正确的提供商（Anthropic vs OpenAI）

问题 3：端口被占用

错误信息：

Error: Port 18789 is already in use

解决方法：

# 查找占用进程
lsof -i :18789

# 或者修改配置使用其他端口
openclaw gateway start --port 18790

问题 4：Gateway 无法启动

检查日志：

openclaw gateway logs

# 或查看系统日志
journalctl -u openclaw-gateway -f

常见原因：

API Key 未配置
配置文件语法错误
端口被占用
系统资源不足

问题 5：消息发送失败

检查清单：

渠道是否正确配置（Telegram Bot Token、WhatsApp 等）
allowFrom 是否包含你的号码
网络连接是否正常
API 配额是否充足

生产环境部署建议

使用 systemd 管理（Linux）

OpenClaw 安装脚本会自动创建 systemd 服务，手动配置参考：

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw Gateway
After=network.target

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

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl enable openclaw
sudo systemctl start openclaw

反向代理配置（Nginx）

如果需要通过域名访问：

server {
    listen 80;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

SSL 配置（Let’s Encrypt）

# 安装 certbot
sudo apt-get install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d openclaw.yourdomain.com

# 自动续期
sudo certbot renew --dry-run

监控和日志

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

# 查看最近 100 行
sudo journalctl -u openclaw -n 100

# 设置日志轮转
sudo nano /etc/logrotate.d/openclaw

/home/openclaw/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

更新和升级

更新到最新版本

# 使用安装脚本更新
curl -fsSL https://openclaw.ai/install.sh | bash

# 或使用 npm
npm update -g openclaw@latest

# 重启服务
openclaw gateway restart

从源码更新

cd ~/openclaw
git pull origin main
npm install
npm run build
npm link
openclaw gateway restart

卸载

完全卸载 OpenClaw

# 停止服务
openclaw gateway stop

# 卸载服务
openclaw onboard --uninstall-daemon

# 删除全局包
npm uninstall -g openclaw

# 删除配置和数据（谨慎！）
rm -rf ~/.openclaw
rm -rf /usr/local/lib/openclaw

注意： 删除配置目录会丢失所有会话历史和配置，建议先备份。

下一步

安装完成后，你可以：

总结

OpenClaw 的安装过程已经非常简化了：

准备环境：Node.js 22+、API Key
运行安装：curl -fsSL https://openclaw.ai/install.sh | bash
配置向导：openclaw onboard
启动服务：openclaw gateway start
打开控制面板：openclaw dashboard

整个过程不超过 5 分钟。

如果你在安装过程中遇到问题，可以查看：

相关文章：

为什么需要 OpenClaw 安装指南？

安装前准备

系统要求

API 密钥准备

方法一：快速安装脚本（推荐）

Linux / macOS

Windows (PowerShell)

方法二：npm 安装

配置向导详解

1. API 密钥配置

2. Gateway 设置

3. 渠道配置（可选）

4. 服务安装

启动和验证

检查服务状态

启动 Control UI

发送测试消息（需要配置渠道）

方法三：Docker 部署

创建 Docker Compose 配置

启动容器

方法四：从源码编译

克隆仓库

构建和运行

配置文件详解

基础配置示例

安全配置建议

常见问题解决

问题 1：Node.js 版本过低

问题 2：API Key 无效

问题 3：端口被占用

问题 4：Gateway 无法启动

问题 5：消息发送失败

生产环境部署建议

使用 systemd 管理（Linux）

反向代理配置（Nginx）

SSL 配置（Let’s Encrypt）

监控和日志

更新和升级

更新到最新版本

从源码更新

卸载

完全卸载 OpenClaw

下一步

总结

阿里云 ECS

相关推荐

Gemini + OpenClaw 网络搜索完整指南：配置、实战与最佳实践

OpenClaw 联网搜索完全指南：从基础到高级实战

OpenClaw 真正的价值：22 个真实用例背后的 3 种增长飞轮

OpenClaw 教程：5 分钟搭建你的第一个 AI Agent