安装
系统要求¶
- 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 提供了桌面伴侣应用:
- Windows:Windows Hub 伴侣应用 — 这是一个已签名的安装程序,下载后像任何 Windows 应用一样运行,包含设置、托盘状态、聊天和节点模式:
- OpenClawCompanion-Setup-x64.exe
- OpenClawCompanion-Setup-arm64.exe
- 所有 Hub 版本:Windows Hub 版本发布页
- macOS:macOS 菜单栏应用 — 从 OpenClaw GitHub 发布页 下载
OpenClaw-<version>.dmg(首选)或.zip资源,然后安装并启动 OpenClaw.app。有关详细信息,包括当最新版本没有附带 macOS 资源时该怎么做,请参阅 macOS 应用页面。
两个桌面应用都可以在首次运行设置时预置本地 Gateway,或连接到现有的远程 Gateway。
推荐:安装脚本¶
这是最快的安装方式。它会检测你的操作系统,在需要时安装 Node,安装 OpenClaw,并启动引导设置。
Note
Windows 桌面用户也可以安装原生的 Windows Hub 伴侣应用,它包含设置、托盘状态、聊天、节点模式和本地 MCP 模式。
若要安装但不运行引导设置:
所有标志及 CI/自动化选项,请参阅 安装程序内部机制。
其他安装方法¶
本地前缀安装程序(install-cli.sh){#local-prefix-installer-install-clish}¶
如果你希望将 OpenClaw 和 Node 放在 ~/.openclaw 这样的本地前缀目录下,并且不依赖系统级的 Node 安装,可以使用此方式:
它默认支持 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
容器和包管理器¶
自动化集群配置。
可选依赖安装器和包脚本运行器。
容器化或无头部署。
通过 Nix flake 进行声明式安装。
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 模板。
实验性 Worker + Container 部署。
共享的 Docker 步骤。
K8s 部署。
隔离的本地或托管 macOS 部署。
带 SSH 隧道访问的托管 Linux 主机。
选择提供商。
备份、更新、迁移或卸载¶
创建、验证并恢复状态归档。
保持 OpenClaw 为最新状态。
迁移到新机器。
完全移除 OpenClaw。
故障排查:openclaw 未找到¶
几乎总是 PATH 问题:npm 的全局 bin 目录不在你的 shell 的 PATH 中。有关完整修复方法(包括 Windows 路径),请参阅 Node.js 故障排查。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw