OpenClaw 安装部署完全指南- 从零配置AI助手

2小时前 0

教程

OpenClaw 安装部署完全指南

前言

OpenClaw 是一个开源的 AI Agent 网关框架，支持连接 Discord、飞书、Telegram、微信等多个平台，让你轻松拥有一个 24x7 在线的人工智能助手。本文详细介绍 OpenClaw 在各操作系统上的安装部署步骤、完整命令参考以及常见问题的解决方案。

阅读收益：

✅ 掌握 Windows / macOS / Linux / Docker 四种安装方式
✅ 了解 OpenClaw 所有常用命令
✅ 解决 15+ 个安装和运行中的常见报错
✅ 学会配置模型和渠道连接

一、快速安装（5分钟上手）

前置要求

Node.js >= 18.0.0（推荐使用 nvm 管理）
npm >= 9.0.0 或 pnpm >= 8.0.0（推荐 pnpm）
系统内存：至少 2GB 可用内存

通用安装命令

macOS / Linux：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)：

iwr -useb https://openclaw.ai/install.ps1 | iex

npm 全局安装：

npm install -g openclaw@latest
# 或使用 pnpm
pnpm add -g openclaw@latest

二、Windows 系统安装

方法一：PowerShell 安装（推荐）

打开 PowerShell（以管理员身份运行）
设置执行策略（如果遇到脚本被阻止）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

安装 OpenClaw：

iwr -useb https://openclaw.ai/install.ps1 | iex

验证安装：

openclaw --version

方法二：使用 WSL2（推荐完整体验）

Windows 用户推荐使用 WSL2，可获得最佳体验：

启用 WSL2：

wsl --install

在 WSL2 中安装：

curl -fsSL https://openclaw.ai/install.sh | bash

启动 OpenClaw：

openclaw onboard --install-daemon

方法三：npm 手动安装

# 使用 npm
npm install -g openclaw@latest

# 或使用 yarn
yarn global add openclaw@latest

# 验证
openclaw --version

Windows 常见问题

问题：安装后命令找不到

# 检查 PATH 是否包含 npm 全局路径
$env:PATH += ";$(npm root -g)"
# 或重新打开终端

问题：Sharp 安装失败

# 设置忽略全局 libvips
$env:SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw@latest

三、macOS 系统安装

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

curl -fsSL https://openclaw.ai/install.sh | bash

方法二：Homebrew 安装

# 如果有 Homebrew
brew install openclaw

# 或
brew install --cask openclaw

方法三：npm 安装

# 使用 npm
npm install -g openclaw@latest

# 使用 pnpm（推荐）
pnpm add -g openclaw@latest

方法四：手动下载安装

从 GitHub Releases 下载最新版本
解压并配置 PATH

tar -xzf openclaw-macos-*.tar.gz
sudo mv openclaw /usr/local/bin/

验证安装

openclaw --version
openclaw doctor

四、Linux 系统安装

Ubuntu / Debian

# 安装依赖
sudo apt update
sudo apt install -y curl git

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

# 安装 Node.js（如果未安装）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

CentOS / RHEL / Fedora

# 安装依赖
sudo yum install -y curl

# 安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

Arch Linux

# 使用 yay 或其他 AUR 工具
yay -S openclaw

# 或手动安装
git clone https://aur.archlinux.org/openclaw.git
cd openclaw
makepkg -si

Alpine Linux

# 安装依赖
apk add --no-cache curl nodejs npm

# 安装 OpenClaw
npm install -g openclaw@latest

验证安装

openclaw --version
openclaw doctor

五、Docker 部署

快速启动

# 使用官方镜像
docker run -d \n  --name openclaw \n  -p 18789:18789 \n  -v ~/.openclaw:/root/.openclaw \n  openclaw/openclaw:latest

# 查看状态
docker logs -f openclaw

使用 docker-compose

创建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
      - "3000:3000"
    volumes:
      - ~/.openclaw:/root/.openclaw
    environment:
      - OPENCLAW_GATEWAY_PORT=18789
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3

启动服务：

docker-compose up -d
docker-compose logs -f

带 GPU 支持的 Docker 配置

docker run -d \n  --name openclaw-gpu \n  --gpus all \n  -p 18789:18789 \n  -v ~/.openclaw:/root/.openclaw \n  openclaw/openclaw:latest

六、初始化配置

运行引导向导

openclaw onboard --install-daemon

向导会引导你完成：

选择模型提供商（OpenAI / Claude / DeepSeek / 本地模型）
输入 API Key
配置网关设置
可选：安装 Telegram Bot 等渠道

手动配置

# 查看当前配置
openclaw config get

# 设置 API Key
openclaw config set models.providers.openai.apiKey YOUR_API_KEY

# 设置默认模型
openclaw config set agents.defaults.model gpt-4o

# 启动网关
openclaw gateway start

# 查看状态
openclaw gateway status

七、OpenClaw 完整命令参考

🚀 网关管理（Gateway）

命令	说明
`openclaw gateway start`	启动网关服务
`openclaw gateway stop`	停止网关服务
`openclaw gateway restart`	重启网关服务
`openclaw gateway status`	查看网关状态
`openclaw gateway logs`	查看网关日志

# 常用示例
openclaw gateway start
openclaw gateway status
openclaw gateway restart

⚙️ 配置管理（Config）

命令	说明
`openclaw config get [路径]`	获取配置项
`openclaw config set <路径> <值>`	设置配置项
`openclaw config reset`	重置为默认配置
`openclaw configure`	交互式配置

# 示例
openclaw config get gateway.port
openclaw config set gateway.port 18790
openclaw config get agents.defaults.model
openclaw config set agents.defaults.model deepseek/deepseek-chat

🩺 诊断命令（Doctor）

命令	说明
`openclaw doctor`	运行完整健康检查诊断
`openclaw doctor --fix`	自动修复检测到的问题
`openclaw doctor --verbose`	显示详细诊断信息

🔌 渠道管理（Channels）

命令	说明
`openclaw channels list`	列出已连接的渠道
`openclaw channels add <类型>`	添加新渠道
`openclaw channels remove <名称>`	移除渠道
`openclaw channels status`	查看渠道状态

# 添加 Telegram Bot
openclaw channels add telegram --bot-token YOUR_BOT_TOKEN

# 添加 Discord
openclaw channels add discord --bot-token YOUR_DISCORD_TOKEN

# 添加飞书
openclaw channels add feishu --app-id XXX --app-secret XXX

# 查看所有渠道
openclaw channels list

🧠 模型管理（Models）

命令	说明
`openclaw models list`	列出可用模型
`openclaw models status`	查看模型状态
`openclaw models auth`	配置模型认证
`openclaw infer`	测试推理

# 配置 API Key
openclaw models auth paste-token --provider openai
openclaw models auth paste-token --provider deepseek

# 设置默认模型
openclaw config set agents.defaults.model gpt-4o

# 测试模型
openclaw infer "Hello, how are you?"

⏰ 定时任务（Cron）

命令	说明
`openclaw cron list`	列出所有定时任务
`openclaw cron add`	添加新定时任务
`openclaw cron rm <id>`	删除定时任务
`openclaw cron enable <id>`	启用任务
`openclaw cron disable <id>`	禁用任务
`openclaw cron runs <id>`	查看任务执行记录

# 添加定时任务
openclaw cron add --name "daily-report" --every 24h --message "发送日报"

# 查看任务
openclaw cron list --all

# 删除任务
openclaw cron rm task-id-123

🔧 技能管理（Skills）

命令	说明
`openclaw skills list`	列出已安装技能
`openclaw skills add <名称>`	安装技能
`openclaw skills remove <名称>`	卸载技能
`openclaw skills search`	搜索技能市场

# 搜索技能
openclaw skills search "web search"

# 安装技能
openclaw skills add web-search

# 查看已安装
openclaw skills list

🔌 插件管理（Plugins）

命令	说明
`openclaw plugins list`	列出已安装插件
`openclaw plugins add <路径>`	安装插件
`openclaw plugins remove <名称>`	卸载插件
`openclaw plugins reload <名称>`	重载插件

🔒 安全与认证（Security）

命令	说明
`openclaw security audit`	运行安全审计
`openclaw pairing list`	列出配对设备
`openclaw pairing approve <id>`	批准配对请求
`openclaw pairing revoke <id>`	撤销配对
`openclaw secrets list`	列出密钥

📊 系统状态

命令	说明
`openclaw status`	查看完整状态
`openclaw health`	健康检查
`openclaw logs`	查看日志
`openclaw system info`	系统信息

💾 备份与更新

命令	说明
`openclaw backup`	创建备份
`openclaw backup list`	列出备份
`openclaw update`	更新 OpenClaw
`openclaw reset`	重置配置
`openclaw uninstall`	卸载 OpenClaw

# 创建备份
openclaw backup

# 列出备份
openclaw backup list

# 更新到最新版本
openclaw update

# 更新到指定版本
openclaw update --version 1.5.0

🌐 其他命令

命令	说明
`openclaw dashboard`	打开控制面板
`openclaw browser`	启动浏览器控制
`openclaw memory`	内存管理
`openclaw message`	发送测试消息
`openclaw tui`	启动终端界面
`openclaw docs`	查看文档

八、常见问题与解决方案（15个报错全解）

💡 提示：遇到问题时，首先运行 openclaw doctor 进行诊断，大部分问题可以被自动检测和修复。

问题 1：EBADENGINE — Node.js 版本不兼容

症状：安装时报错 Unsupported engine, current version: 16.x, required: >=18.0.0

解决方案：

# 使用 nvm 安装 Node.js 20
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20

# 重新安装 OpenClaw
npm install -g openclaw@latest

问题 2：command not found — PATH 未配置

症状：安装成功但命令找不到

解决方案：

# 添加到 PATH（Linux/macOS）
echo 'export PATH="$(npm global bin):$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows 用户在 PowerShell 中执行
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";" + (npm root -g),
    "User"
)

问题 3：Sharp 安装失败

症状：sharp: Installation error 或编译错误

解决方案：

# Linux/macOS
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

问题 4：Gateway start blocked

症状：Gateway start blocked: set gateway.mode=local

解决方案：

# 交互式修复
openclaw doctor --fix

# 或手动修改配置
openclaw config set gateway.mode local

# 或编辑配置文件
nano ~/.openclaw/openclaw.json
# 添加: { "gateway": { "mode": "local" } }

问题 5：EADDRINUSE — 端口被占用

症状：Error: listen EADDRINUSE :::18789

解决方案：

# 查找占用端口的进程
lsof -i :18789    # macOS
netstat -tulnp | grep 18789    # Linux
netstat -ano | findstr 18789   # Windows

# 关闭占用进程
kill -9 <PID>

# 或更改 OpenClaw 端口
openclaw config set gateway.port 18790
openclaw gateway restart

问题 6：Gateway 启动后立即退出

症状：进程消失，openclaw status 显示网关不可达

解决方案：

# 查看详细日志
openclaw gateway logs

# 检查配置文件语法
openclaw config get

# 重新初始化
openclaw reset
openclaw onboard --install-daemon

问题 7：HTTP 429 — 速率限制

症状：API 返回 429 错误，长上下文请求被限制

解决方案：

// 在 openclaw.json 中禁用长上下文
{
  "models": {
    "providers": {
      "openai": {
        "options": {
          "context1m": false
        }
      }
    }
  }
}

问题 8：AUTH_TOKEN_MISMATCH — 令牌不匹配

症状：连接控制面板时认证失败

解决方案：

# 重新设置 gateway token
openclaw configure

# 或手动重置
openclaw config set gateway.auth.token YOUR_NEW_TOKEN

# 确认环境变量与配置文件一致
echo $OPENCLAW_GATEWAY_TOKEN

问题 9：插件安装失败 — package.json missing

症状：package.json missing openclaw.extensions

解决方案：

// 在你的插件 package.json 中添加
{
  "name": "my-openclaw-plugin",
  "openclaw": {
    "extensions": {
      "main": "dist/index.js"
    }
  }
}

问题 10：消息被过滤 — blocked/allowlist

症状：消息被拦截，用户无法正常使用

解决方案：

// 在 openclaw.json 中配置白名单
{
  "security": {
    "allowlist": {
      "enabled": true,
      "users": ["user-id-1", "user-id-2"]
    }
  }
}

问题 11：设备握手失败 — device nonce mismatch

症状：设备配对时报错 device nonce mismatch

解决方案：

# 重新启动配对流程
openclaw pairing revoke all
# 重新发起配对请求
openclaw pairing approve <pending-request-id>

问题 12：定时任务不触发

症状：Cron scheduler disabled 错误

解决方案：

// 在 openclaw.json 中启用调度器
{
  "gateway": {
    "scheduler": {
      "enabled": true
    }
  }
}

问题 13：Docker 部署内存不足

症状：容器被 OOM Kill

解决方案：

# 增加内存限制
docker run -d \
  --name openclaw \
  --memory=2g \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

问题 14：配置损坏

症状：启动失败，配置文件格式错误

解决方案：

# 备份并重置配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw reset
openclaw onboard --install-daemon

问题 15：云端部署无法访问命令行

症状：Railway/Fly.io 等平台无法运行 CLI

解决方案：

查看平台日志控制台
访问 https://<域名>/setup 状态页面
在 Bot 中添加状态查询指令：

// 添加 status 技能
openclaw skills add status

// 查看状态
openclaw status --json

九、配置示例

基础配置示例

{
  "meta": {
    "name": "My OpenClaw Agent",
    "version": "1.0.0"
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "auth": {
      "token": "your-gateway-token"
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-xxx",
        "model": "gpt-4o"
      },
      "deepseek": {
        "apiKey": "sk-xxx",
        "model": "deepseek-chat"
      }
    },
    "defaults": {
      "model": "openai/gpt-4o"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-telegram-bot-token"
    }
  }
}

十、进阶使用

部署到生产环境

使用 systemd 守护进程（Linux）：

openclaw onboard --install-daemon
sudo systemctl enable openclaw
sudo systemctl start openclaw

配置反向代理（Nginx）：

server {
    listen 443 ssl;
    server_name your-domain.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;
    }
}

配置 HTTPS：

# 使用 Let's Encrypt
sudo certbot --nginx -d your-domain.com

自定义控制面板

# 创建自定义 UI 目录
mkdir -p ~/.openclaw/control-ui-custom

# 放入你的构建文件
cp -r ./your-ui-build/* ~/.openclaw/control-ui-custom/

# 配置使用自定义 UI
openclaw config set gateway.controlUi.root ~/.openclaw/control-ui-custom
openclaw config set gateway.controlUi.enabled true

# 重启网关
openclaw gateway restart

十一、资源链接

资源	链接
官方网站	https://openclaw.ai
官方文档	https://docs.openclaw.ai
GitHub 仓库	https://github.com/openclaw/openclaw
技能市场	https://openclaw.ai/skills
问题反馈	https://github.com/openclaw/openclaw/issues
Discord 社区	https://discord.gg/openclaw

总结

本文详细介绍了 OpenClaw 在 Windows、macOS、Linux 和 Docker 环境下的安装部署方法，提供了完整的命令参考，并针对 15 个常见问题给出了详细的解决方案。

核心要点回顾：

✅ 使用官方安装脚本或 npm 可快速完成安装
✅ Windows 推荐使用 WSL2 获得最佳体验
✅ Docker 部署适合服务器环境
✅ openclaw doctor 是排查问题的首选工具
✅ 配置修改后记得重启网关

如果在使用过程中遇到其他问题，欢迎在评论区留言或访问官方社区寻求帮助！

本文更新于 2026 年 4 月 | OpenClaw 版本：最新稳定版