OpenClaw 安装与入门：从零到跑通 Gateway（详细可操作）

OpenClaw 是个人可自托管的 AI 助手/Gateway：在本地运行控制面，可对接多种即时通讯渠道与工具。本文按官方文档整理 安装 → 引导 → 验证 → 排错 ，便于一步步照做。
权威来源 ：官方文档 Install · Getting Started · GitHub · npm

版本与命令随项目迭代可能变化，若与本文不一致，以官方文档为准。

一、安装前准备

1.1 系统与环境

项目	要求
Node.js	Node 24 推荐；Node 22.14+ 亦受支持（官方 Getting Started / Install 页）
操作系统	macOS、Linux；Windows 支持原生与 WSL2 ，官方更推荐 WSL2 以获得完整体验
包管理	全局安装可用 npm / pnpm ；从源码构建需 pnpm

1.2 检查 Node 是否已安装

在终端执行：

bash 复制代码

node --version

若未安装或版本过低，可：

使用官方 一键安装脚本（下文方式 A）：脚本会按需处理 Node；或
自行安装：参见官方 Node setup。

1.3 你需要准备什么

至少一个 大模型厂商的 API Key （如 Anthropic、OpenAI、Google 等），openclaw onboard 向导里会提示配置。
稳定的网络（下载 Node 依赖、拉取模型接口时可能需要）。

二、方式 A（推荐）：官方一键安装脚本

适合：想最快装好并进入向导，且愿意用官方脚本管理 Node/OpenClaw。

2.1 macOS / Linux / WSL2

在终端执行（将下载并执行远程脚本，请确保你信任官方域名）：

bash 复制代码

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

脚本会检测系统、按需安装 Node、安装 OpenClaw，并通常会引导进入后续步骤。

2.2 Windows（PowerShell）

以管理员或当前用户可执行策略为准，在 PowerShell 中执行：

powershell 复制代码

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

2.3 仅安装、暂不运行引导（自动化/CI）

macOS / Linux / WSL2：

bash 复制代码

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

Windows PowerShell：

powershell 复制代码

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

更多安装脚本参数见官方：Installer internals。

三、方式 B：已自备 Node 时用 npm / pnpm 全局安装

适合：本机已固定使用某版本 Node，希望与现有工具链一致。

3.1 使用 npm

bash 复制代码

npm install -g openclaw@latest

安装完成后执行引导（并安装 Gateway 常驻服务，推荐）：

bash 复制代码

openclaw onboard --install-daemon

3.2 使用 pnpm

bash 复制代码

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

说明：pnpm 对带 build 脚本的包需显式批准 ，首次全局安装后务必执行 pnpm approve-builds -g（官方 Install 文档要求）。

3.3 npm 安装时 `sharp` 构建失败（与全局 libvips 冲突）

若报错与 sharp / libvips 相关，可尝试：

bash 复制代码

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

四、安装后必做：引导与守护进程

无论用脚本还是 npm，正式使用前建议完成 CLI 引导：

bash 复制代码

openclaw onboard --install-daemon

--install-daemon ：安装 Gateway 守护进程 （如 macOS 的 launchd / Linux 的 systemd 用户服务），使 Gateway 常驻运行（与 npm README 描述一致）。
向导约 2 分钟，包括：选择模型提供商、填写 API Key、Gateway 基础配置等。
完整说明：Onboarding (CLI)。

若你使用了 --no-onboard 安装，稍后仍需手动执行一次：

bash 复制代码

openclaw onboard --install-daemon

五、验证是否安装成功

按顺序执行以下命令，全部符合预期即说明 CLI 与 Gateway 基本正常。

5.1 查看 CLI 版本

bash 复制代码

openclaw --version

能输出版本号即表示 openclaw 已在 PATH 中。

5.2 健康检查

bash 复制代码

openclaw doctor

用于发现配置风险、通道策略等问题（官方建议升级后也运行）。

5.3 查看 Gateway 状态

bash 复制代码

openclaw gateway status

成功时通常可看到 Gateway 监听 18789 端口（与 Getting Started 一致）。

5.4 打开控制面板（浏览器）

bash 复制代码

openclaw dashboard

浏览器应打开 Control UI ；在内置聊天里发一条消息，若能收到模型回复，说明 端到端已通。

5.5（可选）命令行发消息 / 调 Agent

以下为官方 Quick start 示例，需你已配置好通道与模型（详见官方文档）：

bash 复制代码

openclaw gateway --port 18789 --verbose

# 示例：向号码发送（请改为真实目标与合规用途）
openclaw message send --to +1234567890 --message "Hello from OpenClaw"

openclaw agent --message "Ship checklist" --thinking high

六、可选安装方式速查

方式	适用场景	命令或链接
Docker / Podman	容器化、无头部署	Docker 文档
Nix	声明式环境	Nix OpenClaw
从 GitHub main 安装	跟踪最新主干	`npm install -g github:openclaw/openclaw#main`
源码开发	贡献代码或本地调试	`git clone` → `pnpm install` → `pnpm ui:build` → `pnpm build`，详见官方 Install / From source

源码开发典型流程（摘自官方）：

bash 复制代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

日常开发也可用仓库内：pnpm openclaw ...、pnpm gateway:watch（以官方 Setup 为准）。

七、常见问题排错

7.1 提示 `openclaw: command not found`

确认 Node 与全局包路径：

bash 复制代码

node -v
npm prefix -g
echo "$PATH"

若 $(npm prefix -g)/bin 不在 PATH 中，在 ~/.zshrc 或 ~/.bashrc 中加入：

bash 复制代码

export PATH="$(npm prefix -g)/bin:$PATH"

重新打开终端 再试 openclaw --version。
更多见：Node setup。

7.2 Windows 下体验不完整

优先使用 WSL2 按 Linux 方式安装；见 Windows 平台说明。

7.3 升级与迁移

升级：Updating，并可定期执行 openclaw doctor。
发布渠道：stable / beta / dev，可用 openclaw update --channel stable|beta|dev（详见 Development channels）。

7.4 环境变量（自定义目录）

在系统服务或特殊账户下运行时可能需要：

变量	作用
`OPENCLAW_HOME`	内部路径解析用的「家目录」
`OPENCLAW_STATE_DIR`	状态目录覆盖
`OPENCLAW_CONFIG_PATH`	配置文件路径覆盖

完整列表：Environment variables。

八、安全提示（必读）

OpenClaw 会连接真实消息渠道，私信内容应视为不可信输入 。默认对 Telegram/WhatsApp 等多平台有 DM pairing（配对） 等策略；若改为完全开放策略，需显式配置并理解风险。

安全总览：Security
定期执行：openclaw doctor 检查危险配置。

九、安装完成后可以做什么

接通道 ：如 Telegram 机器人 Token 上手较快，见 Channels。
配对与许可：控制谁能给你的 Agent 发消息。
调模型与工具 ： Models、Tools、Skills。
部署到 VPS ：官方提供 Docker、K8s、Fly、Railway 等索引，见 Install 页 Hosting。

十、参考链接汇总

主题	URL
官网	https://openclaw.ai
文档首页	https://docs.openclaw.ai
安装总览	https://docs.openclaw.ai/install
新手 5 分钟	https://docs.openclaw.ai/start/getting-started
引导向导	https://docs.openclaw.ai/start/wizard
GitHub	https://github.com/openclaw/openclaw
npm 包	https://www.npmjs.com/package/openclaw

本文整理自 OpenClaw 官方文档与 npm 包说明，便于本地沉淀与团队 onboarding；执行远程安装脚本前请自行评估安全策略。

OpenClaw 安装与入门：从零到跑通 Gateway（详细可操作）