OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

安装概览

安装程序内部机制

OpenClaw 提供三个安装脚本，托管于 openclaw.ai。

脚本 平台 功能
install.sh macOS / Linux / WSL 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。
install-cli.sh macOS / Linux / WSL 通过 npm 或 git 将 Node + OpenClaw 安装到本地前缀（~/.openclaw）。无需 root 权限。
install.ps1 Windows (PowerShell) 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。

三个脚本均支持 Node 22.22.3+、24.15+ 或 25.9+；全新安装默认以 Node 24 为目标版本。

快速命令

install.sh

bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

install-cli.sh

bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help

install.ps1

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

install.sh

流程（install.sh）

  • 检测操作系统

    支持 macOS 和 Linux（包括 WSL）。

  • 默认确保安装 Node.js 24

    检查 Node 版本，并在需要时安装 Node 24（macOS 使用 Homebrew，Linux 使用 NodeSource 的 apt/dnf/yum 设置脚本）。在 macOS 上，仅当安装程序需要用它安装 Node 或 Git 时，才会安装 Homebrew。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。 在 Alpine/musl Linux 上，安装程序使用 apk 软件包而不是 NodeSource，并验证实际链接的 SQLite 版本。当前稳定版 Alpine 软件包源可能提供版本足够新的 Node，但其系统 SQLite 存在漏洞；发生这种情况时，请改用官方 node:24-alpine 容器或基于 glibc 的主机。

  • 确保安装 Git

    如果缺少 Git，则使用检测到的软件包管理器进行安装，包括 macOS 上的 Homebrew 和 Alpine 上的 apk。

  • 安装 OpenClaw

    • npm 方式（默认）：通过 npm 全局安装
    • git 方式：克隆/更新仓库，使用 pnpm 安装依赖并构建，然后在 ~/.local/bin/openclaw 安装包装器

  • 安装后任务

    • 解析刚安装的 openclaw 二进制文件，以供后续命令使用
    • 对于尚未配置的安装，在执行 Doctor 或 Gateway 网关探测之前启动新手引导。使用 --no-onboard 或没有 TTY 时，会输出稍后完成设置所需的命令。
    • 对于已配置的安装，以尽力而为方式刷新并重启已加载的 Gateway 网关服务，然后运行 Doctor。升级时会尽可能更新插件；在启用提示的无界面运行中，则会输出手动命令。
    • 运行 --verify 时，它会检查已安装版本，并且仅在配置存在后检查 Gateway 健康。

    • 源代码检出检测

    如果在 OpenClaw 检出目录（package.json + pnpm-workspace.yaml）内运行，脚本会提供以下选项：

    • 使用检出目录（git），或
    • 使用全局安装（npm）

    如果没有可用的 TTY 且未设置安装方式，则默认使用 npm 并发出警告。

    如果安装方式选择无效或 --install-method 值无效，脚本会以代码 2 退出。

    示例（install.sh）

    默认

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

    跳过新手引导

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

    Git 安装

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

    GitHub main 检出

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main

    试运行

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

    安装后验证

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard --verify
    标志参考
    标志 描述
    --install-method | --method npm|git 选择安装方式（默认：npm）
    --npm npm 方式的快捷选项
    --git | --github git 方式的快捷选项
    --version <version|dist-tag|spec> npm 版本、dist-tag 或软件包规范（默认：latest）
    --beta 使用 beta dist-tag（如果可用），否则回退到 latest
    --git-dir | --dir <path> 检出目录（默认：~/openclaw）
    --no-git-update 对现有检出目录跳过 git pull
    --no-prompt 禁用提示
    --no-onboard 跳过新手引导
    --onboard 启用新手引导
    --verify 运行安装后冒烟验证（--version，如果已加载则检查 Gateway 健康）
    --dry-run 输出将执行的操作，但不应用更改
    --verbose 启用调试输出（set -x、npm notice 级别日志）
    --help | -h 显示用法
    环境变量参考
    变量 描述
    OPENCLAW_INSTALL_METHOD=git|npm 安装方式
    OPENCLAW_VERSION=latest|next|<semver>|<spec> npm 版本、dist-tag 或软件包规范
    OPENCLAW_BETA=0|1 如果可用则使用 beta
    OPENCLAW_HOME=<path> OpenClaw 状态以及默认 git/新手引导路径的基础目录
    OPENCLAW_GIT_DIR=<path> 检出目录
    OPENCLAW_GIT_UPDATE=0|1 切换 git 更新
    OPENCLAW_NO_PROMPT=1 禁用提示
    OPENCLAW_VERIFY_INSTALL=1 运行安装后冒烟验证
    OPENCLAW_NO_ONBOARD=1 跳过新手引导
    OPENCLAW_DRY_RUN=1 试运行模式
    OPENCLAW_VERBOSE=1 调试模式
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 日志级别（默认：error，隐藏 npm 弃用噪声）

    install-cli.sh

    流程（install-cli.sh）

  • 安装本地 Node 运行时

    将固定版本且受支持的 Node LTS tarball（该版本嵌入脚本中并独立更新，默认 24.15.0）下载到 <prefix>/tools/node-v<version>，并验证 SHA-256。 Linux ARMv7 使用 Node 22.22.3，因为官方未提供 Node 24+ ARMv7 二进制文件。 在 Alpine/musl Linux 上，由于 Node 不为固定运行时发布兼容的 tarball，因此使用 apk 安装 nodejs 和 npm，然后验证 Node 和实际链接的 SQLite 库。即使 Node 版本足够新，当前稳定版 Alpine 软件包源仍可能链接存在漏洞的 SQLite；当安全检查拒绝该软件包时，请使用官方 node:24-alpine 容器或基于 glibc 的主机。

  • 确保安装 Git

    如果缺少 Git，则尝试在 Linux 上通过 apt/dnf/yum/apk 安装，或在 macOS 上通过 Homebrew 安装。

  • 在前缀下安装 OpenClaw

    • npm 方式（默认）：使用 npm 安装到前缀下，然后将包装器写入 <prefix>/bin/openclaw
    • git 方式：克隆/更新检出目录（默认 ~/openclaw），并仍将包装器写入 <prefix>/bin/openclaw

  • 刷新已加载的 Gateway 网关服务

    如果已从同一前缀加载 Gateway 网关服务，脚本会运行 openclaw gateway install --force，然后运行 openclaw gateway restart，并 以尽力而为方式探测 Gateway 健康。

    • 示例（install-cli.sh）

    默认

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

    自定义前缀 + 版本

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

    Git 安装

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw

    自动化 JSON 输出

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

    运行新手引导

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    标志参考
    标志 说明
    --prefix <path> 安装前缀（默认：~/.openclaw）
    --install-method | --method npm|git 选择安装方式（默认：npm）
    --npm npm 方式的快捷选项
    --git | --github git 方式的快捷选项
    --git-dir | --dir <path> Git 检出目录（默认：~/openclaw）
    --version <ver> OpenClaw 版本或 dist-tag（默认：latest）
    --node-version <ver> Node 版本（默认：24.15.0；Linux ARMv7 上为 22.22.3）
    --json 输出 NDJSON 事件
    --onboard 安装后运行 openclaw onboard
    --no-onboard 跳过新手引导（默认）
    --set-npm-prefix 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 ~/.npm-global
    --help | -h 显示用法
    环境变量参考
    变量 说明
    OPENCLAW_PREFIX=<path> 安装前缀
    OPENCLAW_INSTALL_METHOD=git|npm 安装方式
    OPENCLAW_VERSION=<ver> OpenClaw 版本或 dist-tag
    OPENCLAW_NODE_VERSION=<ver> Node 版本
    OPENCLAW_HOME=<path> OpenClaw 状态及默认 git/新手引导路径的基础目录
    OPENCLAW_GIT_DIR=<path> git 安装的 Git 检出目录
    OPENCLAW_GIT_UPDATE=0|1 切换现有检出目录的 git 更新
    OPENCLAW_NO_ONBOARD=1 跳过新手引导
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 日志级别（默认：error）

    install.ps1

    流程（install.ps1）

  • 确保 PowerShell + Windows 环境

    需要 PowerShell 5+。

  • 默认确保安装 Node.js 24

    如果缺失，将依次尝试通过 winget、Chocolatey 和 Scoop 安装。如果没有可用的包管理器，脚本会将官方 Node.js 24 Windows zip 下载到 %LOCALAPPDATA%\OpenClaw\deps\portable-node，并将其添加到当前进程和用户 PATH。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。

  • 安装 OpenClaw

    • npm 方式（默认）：使用所选 -Tag 进行全局 npm 安装，并从可写的安装程序临时目录启动，因此即使 shell 在 C:\ 等受保护文件夹中打开也能正常工作
    • git 方式：克隆/更新仓库，使用 pnpm 安装/构建，并在 %USERPROFILE%\.local\bin\openclaw.cmd 安装封装程序。如果缺少 Git，脚本会在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下引导安装用户本地的 MinGit，并将其添加到当前进程和用户 PATH。

  • 安装后任务

    • 尽可能将所需的 bin 目录添加到用户 PATH
    • 尽力刷新已加载的 Gateway 网关服务（openclaw gateway install --force，然后重启）
    • 在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）

  • 处理失败

    iwr ... | iex 和脚本块安装会报告终止错误，但不会关闭当前 PowerShell 会话。直接使用 powershell -File / pwsh -File 安装时，仍会以非零状态退出，以便用于自动化。

    • 示例（install.ps1）

    默认

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

    Git 安装

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

    GitHub main 检出

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -Tag main

    自定义 git 目录

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

    试运行

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
    标志参考
    标志 说明
    -InstallMethod npm|git 安装方式（默认：npm）
    -Tag <tag|version|spec> npm dist-tag、版本或包规范（默认：latest）
    -GitDir <path> 检出目录（默认：%USERPROFILE%\openclaw）
    -NoOnboard 跳过新手引导
    -NoGitUpdate 跳过 git pull
    -DryRun 仅打印操作
    环境变量参考
    变量 说明
    OPENCLAW_INSTALL_METHOD=git|npm 安装方式
    OPENCLAW_GIT_DIR=<path> 检出目录
    OPENCLAW_NO_ONBOARD=1 跳过新手引导
    OPENCLAW_GIT_UPDATE=0 禁用 git pull
    OPENCLAW_DRY_RUN=1 试运行模式

    CI 和自动化

    使用非交互式标志/环境变量以获得可预测的运行结果。

    install.sh（非交互式 npm）

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

    install.sh（非交互式 git）

    bash
    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

    install-cli.sh（JSON）

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

    install.ps1（跳过新手引导）

    powershell
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

    故障排查

    为什么需要 Git？

    git 安装方式需要 Git。对于 npm 安装，仍会检查/安装 Git，以避免依赖项使用 git URL 时出现 spawn git ENOENT 故障。

    为什么 npm 在 Linux 上遇到 EACCES？

    某些 Linux 设置会将 npm 的全局前缀指向 root 所有的路径。install.sh 可以将前缀切换到 ~/.npm-global，并将 PATH 导出语句追加到 shell rc 文件（如果这些文件存在）。

    Windows：“npm error spawn git / ENOENT”

    重新运行安装程序，使其能够引导安装用户本地的 MinGit；或者安装 Git for Windows，然后重新打开 PowerShell。

    Windows：“openclaw is not recognized”

    运行 npm config get prefix，并将该目录添加到用户 PATH（Windows 上不需要 \bin 后缀），然后重新打开 PowerShell。

    Windows：如何获取详细的安装程序输出

    install.ps1 不提供 -Verbose 开关。 使用 PowerShell 跟踪进行脚本级诊断：

    powershell
    Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-PSDebug -Trace 0
    安装后找不到 openclaw

    通常是 PATH 问题。请参阅 Node.js 故障排查。

    相关内容

    Was this useful?
    On this page

    On this page