跳转至

安装

系统要求

  • Node 24.16+ 或 26.1+ - 建议使用 Node 26;当系统缺少 Node 时,安装程序会在 macOS 上预装 Node 26,在 Linux 上预装 Node 24 LTS(参见 Node.js 兼容性)。
  • macOS、Linux 或 Windows - Windows 用户可以使用原生 Windows Hub 应用、PowerShell CLI 安装程序或 WSL2 Gateway 开始使用。参见 Windows。
  • 仅当你想从源码构建时才需要 pnpm。

下载桌面应用

比起 CLI,更喜欢普通的应用下载?OpenClaw 提供了桌面伴侣应用:

两个桌面应用都可以在首次运行设置时预置本地 Gateway,或连接到现有的远程 Gateway。

这是最快的安装方式。它会检测你的操作系统,在需要时安装 Node,安装 OpenClaw,并启动引导设置。

Note

Windows 桌面用户也可以安装原生的 Windows Hub 伴侣应用,它包含设置、托盘状态、聊天、节点模式和本地 MCP 模式。

curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex

若要安装但不运行引导设置:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

所有标志及 CI/自动化选项,请参阅 安装程序内部机制。

其他安装方法

本地前缀安装程序(install-cli.sh){#local-prefix-installer-install-clish}

如果你希望将 OpenClaw 和 Node 放在 ~/.openclaw 这样的本地前缀目录下,并且不依赖系统级的 Node 安装,可以使用此方式:

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

它默认支持 npm 安装,并在相同的前缀流程下支持 git 检出安装。完整参考:安装程序内部机制。

已经安装了吗?你可以使用 openclaw update --channel dev 和 openclaw update --channel stable 在包安装和 git 安装之间切换。参见 更新。

npm、pnpm 或 bun

如果你已经自行管理 Node:

在 npm 12 或 npm 11.16+ 上:

```bash
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon
```

在 npm 11.15 及更早版本上,使用相同的命令,但不加 `--allow-scripts=openclaw`。

Note

npm 12 默认会阻止未经批准的包生命周期脚本。--allow-scripts=openclaw 选项明确允许 OpenClaw 的 preinstall 和 postinstall 步骤;如果不加此选项,npm 会报告它们为 blocked because they are not covered by allowScripts。

npm 11.16 接受该选项,但仅警告脚本 not yet covered by allowScripts,并且仍然会运行它们。npm 11.15 及更早版本既没有该策略也没有该选项,因此它们使用的命令必须不带该标志。npm 11.16 建议的 npm approve-scripts openclaw 命令不适用于全局安装——它会导致 ENOMATCH No installed packages match: openclaw 错误。

Note

托管安装程序会清除针对 OpenClaw 包安装的 npm 新鲜度过滤器(例如 min-release-age)。如果你手动使用 npm 安装,你自己的 npm 策略仍然生效。

```bash
pnpm add -g --allow-build=openclaw openclaw@latest
openclaw onboard --install-daemon
```

Note

pnpm 要求对包含构建脚本的包进行明确批准。approve-builds -g 不支持全局安装,因此请在 pnpm add -g 命令中传递 --allow-build=openclaw。

```bash
bun add -g --trust openclaw@latest
bun run --bun openclaw onboard --install-daemon --daemon-runtime bun
```

Note

--trust 允许 OpenClaw 的包生命周期脚本用于本次安装。Bun 1.4 或更高版本也可以运行 OpenClaw 的 CLI、本地代理和 Gateway。Node 仍是主要运行时,因此普通的 openclaw 可执行文件保留其 Node shebang。bun run --bun 强制使用 Bun 运行时,而 --daemon-runtime bun 则在 Bun 下安装托管的 Gateway。

从源码构建

适用于贡献者或任何希望从本地检出运行的人:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install && pnpm build && pnpm ui:build
pnpm add --global "openclaw@link:$PWD"
openclaw onboard --install-daemon

pnpm add --global "openclaw@link:$PWD" 会将 CLI 链接到本次检出,而不会更改其包文件。如果 pnpm 报告其全局 bin 目录不在 PATH 中,请运行 pnpm setup,重新打开 shell,然后重试。

Corepack 会从 package.json 中选择确切的 pnpm 版本(当前为 pnpm 12)。 如果 Corepack 不可用,请从检出中读取该版本并显式安装:

pnpm_spec=$(node -p "require('./package.json').packageManager.split('+')[0]")
npm install -g "$pnpm_spec" --allow-scripts="$pnpm_spec"

+ 后缀记录 Corepack 的完整性哈希,并且不属于 npm 包说明符的一部分。 请保持启用 npm 安装脚本和可选依赖,以便 pnpm 可以安装其原生可执行文件。

或者跳过全局安装,并在仓库内部使用 pnpm openclaw ...。有关完整的开发工作流,请参阅 设置。

从 GitHub main 检出安装

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

容器和包管理器

Ansible

自动化集群配置。

Bun

可选依赖安装器和包脚本运行器。

Docker

容器化或无头部署。

Nix

通过 Nix flake 进行声明式安装。

Podman

Docker 的无 root 容器替代方案。

验证安装

openclaw --version      # confirm the CLI is available
openclaw doctor         # check for config issues
openclaw gateway status # verify the Gateway is running

如果希望在安装后启用受管理的启动:

  • macOS:通过 openclaw onboard --install-daemon 或 openclaw gateway install 使用 LaunchAgent
  • Linux/WSL2:通过相同命令使用 systemd 用户服务
  • 原生 Windows:优先使用计划任务;如果任务创建被拒绝,则回退到按用户的启动文件夹登录项

下一步:运行入门引导并连接频道

快速开始

运行入门引导,安装 Gateway 服务,并打开仪表板。

连接频道

从 Telegram、Discord、Slack、WhatsApp 等向你的代理发送消息。

托管和部署

在云服务器或 VPS 上部署 OpenClaw。有关完整的 提供商选择器(DigitalOcean、Hetzner、Hostinger、Fly.io、GCP、Azure、Railway、 Northflank、Oracle Cloud、Raspberry Pi 等),请参阅 Linux 服务器,在 Render 上声明式部署,或尝试实验性的 Cloudflare Containers 模板。

Cloudflare

实验性 Worker + Container 部署。

Docker VM

共享的 Docker 步骤。

Kubernetes

K8s 部署。

macOS VM

隔离的本地或托管 macOS 部署。

Upstash Box

带 SSH 隧道访问的托管 Linux 主机。

VPS

选择提供商。

备份、更新、迁移或卸载

备份

创建、验证并恢复状态归档。

更新

保持 OpenClaw 为最新状态。

迁移

迁移到新机器。

卸载

完全移除 OpenClaw。

故障排查:openclaw 未找到

几乎总是 PATH 问题:npm 的全局 bin 目录不在你的 shell 的 PATH 中。有关完整修复方法(包括 Windows 路径),请参阅 Node.js 故障排查。

node -v           # Node installed?
npm prefix -g     # Where are global packages?
echo "$PATH"      # Is the global bin dir in PATH?

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw