跳到主要内容

安装 OpenClaw

OpenClaw 是一款强大的本地部署 AI 助手，支持接入多种大模型（如 GLM-5、DeepSeek、Kimi 等）并实现自动化工作流。以下是详细的安装与配置步骤。

一、 系统要求与前置准备​

在开始安装前，请确保你的系统满足以下最低要求：

  • 操作系统：
    • macOS：12 及以上版本（Intel 或 Apple Silicon 芯片均可）。
    • Linux：Ubuntu 20.04+、Debian 11+、Fedora 38+ 等主流发行版。
    • Windows：Windows 10/11，强烈建议开启 WSL2（Windows Subsystem for Linux）。原生 Windows 环境仅支持 PowerShell 脚本，功能有限。
  • 核心依赖：
    • Node.js：版本 v20 或更高（推荐 v22 LTS）。安装完成后，在终端输入 node -v 验证，应输出类似 v22.x.x 的版本号。
    • Git：用于源码安装或 Docker 部署。

二、 安装方式选择​

根据你的技术背景和使用场景，选择以下一种方式安装。

方式一：官方一键安装（新手首选）​

此方式会自动检测环境、安装依赖并启动配置向导，无需手动配置。

  • macOS / Linux / WSL2： 
    curl -fsSL https://openclaw.ai/install.sh | bash
  • Windows (PowerShell)：

    请使用管理员身份打开 PowerShell 并执行：

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

方式二：npm 手动安装（适合已安装 Node.js 的用户）​

如果你已安装 Node.js，可以直接通过包管理器安装。

  • 全局安装： 
    npm install -g openclaw@latest
    • macOS/Linux 权限问题：若遇权限错误，请添加 sudo。
    • 国内镜像加速：可尝试使用 npm 镜像加速： 
      npm config set registry https://registry.npmmirror.com
    • macOS sharp 依赖失败：若遇到 sharp 依赖安装失败，可使用： 
      SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
  • 验证安装： 
    openclaw --version

方式三：Docker 部署（适合服务器或隔离环境）​

适合在服务器或需要环境隔离的场景下部署。

  1. 安装并启动 Docker Desktop。
  2. 把 OpenClaw 的代码 Clone 到本地： 
    git clone https://github.com/openclaw/openclaw.git
  3. 进入项目根目录，执行以下命令： 
    ./docker-setup.sh
    之后会进入镜像构建流程，构建完成后自动进入配置流程。

方式四：源码安装（适合开发者）​

适合开发者或需要修改代码的场景。

  1. 克隆仓库： 
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
  2. 安装依赖并构建： 
    pnpm install
    pnpm ui:build
    pnpm build
  3. 创建全局链接并启动配置： 
    pnpm link --global
    openclaw onboard --install-daemon

三、 初始化配置（Onboarding）​

安装完成后，必须执行初始化向导。如果一键安装脚本未自动启动，请手动运行：

openclaw onboard --install-daemon

根据提示信息完成以下配置（参考建议）：

配置项建议选择说明
风险提示Yes确认了解 OpenClaw 的强大功能与潜在风险。
Onboarding modeQuickStart快速启动模式，省去复杂配置。
Model/auth providerSkip for now可先跳过，后续在 Web UI 中配置。
Filter models by providerAll providers查看所有支持的模型。
Default model使用默认配置或选择你常用的模型（如 DeepSeek、GLM-5）。
Select channelSkip for now可先跳过，后续配置飞书、Telegram 等通道。
Configure skills now?No可先跳过，后续再配置技能包。
Enable hooks?按空格选中建议启用，用于内容引导、日志和会话记录。
Hatch your botHatch in TUI在终端界面中启动。

四、 启动与验证​

1. 启动服务​

  • 启动服务： 
    openclaw gateway start
  • 开机自启（推荐）： 
    openclaw gateway enable

2. 验证运行​

  • 检查状态： 
    openclaw status
    # 或
    openclaw health
    看到 Gateway reachable 或 running 说明一切正常。
  • 打开控制面板： 
    openclaw dashboard
    此命令会自动打开浏览器，访问 Web 聊天界面（默认地址：http://127.0.0.1:18789）。

五、 配置文件路径​

所有核心配置和日志都保存在以下目录，你可以手动编辑配置文件（如 openclaw.json）进行高级设置：

  • Linux/macOS/WSL2：~/.openclaw/
  • Windows：C:\Users\你的用户名\.openclaw\

六、 常见问题排查​

  • Q1: 安装时提示权限不足？
    • macOS/Linux：在命令前添加 sudo。
    • Windows：请使用管理员身份运行 PowerShell。
  • Q2: macOS 上 sharp 依赖安装失败？
    • 尝试设置环境变量：SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest。
  • Q3: 配置修改后不生效？
    • 重启服务：openclaw gateway restart。
  • Q4: 遇到 "CMake找不到CUDA Toolkit" 错误？
    • 通常不影响安装，可以忽略或尝试安装 CUDA Toolkit。