OpenClaw 安装与快速上手（含常用命令手册）

type

Post

status

Published

date

slug

openclaw-install

summary

本文面向「第一次安装 + 立即跑通」场景，按最短可用路径组织步骤，同时补齐必要概念与排错入口。目标：你能在本机启动 OpenClaw 网关（Gateway）与控制台（Dashboard），并完成渠道（Channels）登录与自检（Doctor）。

1. 你将获得什么

OpenClaw 通常包含三类核心组件/能力：

**CLI（命令行工具）**：用于安装、初始化、登录渠道、启动网关、运行诊断等。

**Gateway（网关/守护服务）**：负责与渠道/节点通信、调度任务、承载本地控制面。

**Dashboard（控制台）**：本地 Web 控制台，默认地址：

**http://127.0.0.1:18789**

---

2. 环境前置条件

在安装前，建议确认：

**Node.js / npm 可用**

- 你需要可工作的 `node` 与 `npm`（通常建议使用较新的 LTS 版本）。

**网络可访问 npm 源**

（可选但推荐）**终端具备管理员权限**

- 某些系统在安装守护进程（daemon/service）或绑定端口时需要提升权限。

快速检查：

---

3. 安装（npm 全局安装）

使用 npm 全局安装 OpenClaw CLI：

验证安装是否成功：

> 说明：`-g` 代表全局安装，使 `openclaw` 命令在任意目录可用。

---

4. 初始化与安装守护进程（onboard）

首次使用建议执行 onboarding，并安装守护进程（daemon/service），让 Gateway 能以服务方式稳定运行：

你通常会看到：

注册并安装后台服务（daemon）

提示后续登录渠道与启动网关的步骤

> 术语说明：

> - **daemon / service / 守护进程**：后台常驻运行的系统服务。

> - 安装 daemon 的价值：免手工常驻终端、支持开机自启（取决于系统与配置）。

---

5. 登录消息渠道（channels login）

OpenClaw 通过「渠道（Channels）」接收/发送消息（例如 Telegram / Discord 等）。先登录你要使用的渠道：

一般流程（不同渠道略有差异）：

选择渠道类型（例如 telegram / discord）

按提示完成授权/令牌配置

CLI 输出“登录成功”或显示已绑定的账户信息

> 建议：首次只登录一个渠道，把链路跑通后再逐步扩展。

---

6. 启动与管理网关（gateway run/status/restart）

Gateway 是核心运行时。常见管理命令如下（本文要求的命令均包含）：

6.1 前台运行（用于调试/观察日志）

适合：

首次安装后确认启动是否正常

需要实时查看日志输出定位问题

6.2 查看服务状态

你期望看到类似信息：

服务是否在运行（running/active）

监听端口（若有展示）

最近启动时间/异常提示（视版本实现而定）

6.3 重启服务（修改配置后常用）

适合：

刚完成 `channels login`

修改环境变量/配置后需要重新加载

---

7. 打开控制台（dashboard）

控制台用于查看运行状态、会话、节点、渠道、日志等。启动/打开方式：

默认控制台地址（本文硬性要求）：

**http://127.0.0.1:18789**

如果你已经启动了 Gateway，但无法打开控制台：

先执行 `openclaw gateway status` 确认服务运行

再检查端口是否被占用或被防火墙/代理拦截（见 [常见问题](#9-常见问题快速定位)）

---

8. 健康检查与诊断（doctor --non-interactive）

当你需要“快速自检 + 输出可复制的诊断结果”时，使用非交互模式：

它通常会检查：

CLI/Gateway 版本与运行环境

关键配置是否存在/可读

渠道登录状态（能否找到凭据）

网络/端口可用性（视实现）

建议做法：

**遇到启动失败/收不到消息/控制台打不开**：优先跑一次 doctor，把输出粘贴到问题记录中，定位效率最高。

---

9. 常见问题（快速定位）

9.1 `openclaw` 命令不存在

重新安装并确保 npm 全局 bin 在 `PATH` 内：

```bash

npm i -g openclaw

```

检查：

```bash

which openclaw

```

9.2 Gateway 状态不正常 / 反复崩溃

按顺序做：

查看状态：

```bash

openclaw gateway status

```

前台运行观察日志：

```bash

openclaw gateway run

```

运行诊断：

```bash

openclaw doctor --non-interactive

```

9.3 控制台打不开（127.0.0.1:18789 无法访问）

优先确认：

Gateway 是否在运行：

```bash

openclaw gateway status

```

端口是否被占用（可选，按系统工具）：

- Linux/macOS：`lsof -i :18789` 或 `ss -lntp | grep 18789`

- Windows：`netstat -ano | findstr 18789`

---

10. 命令速查

> 下面是“最常用、最关键”的一组命令，覆盖安装、初始化、登录、运行、状态、重启、控制台与诊断。

10.1 安装与版本

10.2 初始化（含安装守护进程）

10.3 渠道登录

10.4 网关运行与管理

10.5 打开控制台

控制台默认地址：

**http://127.0.0.1:18789**

10.6 诊断（非交互）

---

最小跑通清单（建议照抄执行顺序）

安装：

```bash

npm i -g openclaw

```

初始化并安装守护进程：

```bash

openclaw onboard --install-daemon

```

登录渠道：

```bash

openclaw channels login

```

启动/确认网关：

```bash

openclaw gateway restart

openclaw gateway status

```

打开控制台：

```bash

openclaw dashboard

```

访问：**http://127.0.0.1:18789**

有问题就跑诊断：

```bash

openclaw doctor --non-interactive

```

一次多-agent 路由与 sessions_spawn 派工链路的真实修复过程