OpenClaw 完整安装教程和控制面板设置详细指南：按官方文档整理的新手版

OpenClaw Series

这篇文章属于 OpenClaw 安装总览篇

如果你想先看一篇按官方文档整理的标准安装流程，这篇最适合；如果你更想看本地实战、踩坑和排错，可以继续去 OpenClaw 专题页或后面的相关文章。

查看 OpenClaw 专题看本地安装实战篇

本文按 2026 年 3 月 29 日可查到的 OpenClaw 官方文档整理。目标不是把命令堆给你，而是让你看完后知道应该怎么装、怎么验收、怎么打开控制面板，以及远程访问时怎么尽量保持安全。

先说结论：第一次安装，最稳的路线就是这 5 步

如果你只是普通新手用户，可以直接按下面顺序来：

准备好 Node 24
用官方安装脚本安装 OpenClaw
运行 openclaw onboard --install-daemon
用 openclaw doctor 和 openclaw status 做验收
用 openclaw dashboard 打开控制面板

如果你后面还需要远程访问，优先考虑：

Tailscale Serve
SSH 隧道

除非你非常明确知道自己在做什么，否则不建议一开始就把 Dashboard 暴露到公网。

一、系统要求

按官方安装文档，当前主线要求如下：

Node 24 为推荐版本
Node 22 LTS 仍支持兼容使用，目前官方写的是 22.16+
支持 macOS、Linux、Windows
在 Windows 上，官方更推荐 WSL2
只有你准备从源码构建时，才需要额外准备 pnpm

如果你是新手，我建议再额外满足这几个实践条件：

至少保持网络稳定
日常使用建议 4GB+ RAM
如果你还要同时跑 Docker、本地模型、多个渠道或长期后台任务，建议 8GB+ RAM

二、安装方式怎么选

OpenClaw 官方其实给了不止一种安装方式，但不同人适合的路线不一样。

你可以这样理解：

想省事，选官方安装脚本
你已经长期维护 Node 环境，选 npm 或 pnpm
你没有 root 权限，或者不想折腾系统全局 npm，选 install-cli.sh
你是开发者，或者想跟着仓库一起改，选源码安装
你要做隔离环境、服务器容器化，才考虑 Docker

如果你只是第一次本地安装，最推荐的仍然是官方安装脚本。

三、安装方法

方法 1：官方一键安装脚本

这是官方最推荐的方式，会帮你处理 Node 检测、安装和新手引导。

macOS / Linux / WSL2：

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

Windows PowerShell：

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

如果你只想先把 CLI 装上，暂时不进入新手引导：

macOS / Linux / WSL2：

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

Windows PowerShell：

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

方法 2：npm 安装

如果你本机已经把 Node 环境整理好了，可以直接这样装：

1 2	npm install -g openclaw@latest openclaw onboard --install-daemon

如果安装时遇到 sharp / libvips 相关报错，官方给出的兼容写法是：

1	SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

方法 3：pnpm 安装

1
2
3

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

这里要注意一点：pnpm 默认会拦截带构建脚本的依赖，所以第一次安装后，通常还要执行一次 pnpm approve-builds -g。

方法 4：无 root 的本地前缀安装

如果你的机器权限受限，或者你不想动全局环境，可以用：

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

如果希望安装后直接进入向导，也可以加参数：

1	curl -fsSL https://openclaw.ai/install-cli.sh \| bash -s -- --onboard

方法 5：源码安装

如果你是开发者，想直接跑本地仓库版本，可以这样：

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

如果你不想全局 link，也可以在仓库里用 pnpm openclaw ... 来执行命令。

方法 6：Docker 安装

Docker 是官方支持的可选方案，但不是最推荐的新手本机主路线。它更适合：

想做容器化 Gateway
服务器部署
想做隔离环境验证

官方 Docker 主路线是进入仓库后跑脚本：

1
2
3

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh

如果你想直接用预构建镜像：

1 2	export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./scripts/docker/setup.sh

Docker 方案有几个关键点要知道：

官方明确把 Docker 定义为 optional
Docker 前提一般是 Docker Compose v2
Docker 文档默认更偏向通过 setup.sh 和 Compose 跑起来，而不是只给一个孤立的 docker run
如果容器要让宿主机浏览器访问到 127.0.0.1:18789，Docker 里的 gateway.bind 配置要注意 lan 和 loopback 的区别

四、新手引导怎么跑

安装完成后，建议直接执行：

1	openclaw onboard --install-daemon

这个向导通常会带你完成：

模型提供商和认证配置
Gateway 端口、绑定方式和认证方式配置
渠道接入配置，比如 Telegram、WhatsApp、Discord
守护进程安装
健康检查
Skills 基础设置

如果你重复运行向导，OpenClaw 一般会检测现有配置，并允许你选择：

保留
修改
重置

所以它不是那种“一跑就全部覆盖”的粗暴流程。

五、如何验证自己真的装好了

很多人装完以后，只看见命令没报错，就以为完事了。

其实更稳的验收方式是按下面顺序跑一遍：

openclaw --version
openclaw doctor
openclaw gateway status
openclaw status
openclaw dashboard

你可以这样理解每条命令的作用：

openclaw --version：确认 CLI 是否真的装上
openclaw doctor：检查环境和配置问题
openclaw gateway status：看 Gateway 运行状态和探测结果
openclaw status：看整体状态摘要
openclaw dashboard：直接打开控制面板

有一个点很重要：

如果 gateway.mode 没设成 local，Gateway 默认会拒绝启动。也就是说，不是你命令输入错了，而是它本来就有这个安全保护。

六、如何打开控制面板

最简单的方式就是：

1	openclaw dashboard

或者你也可以直接访问默认地址：

1	http://127.0.0.1:18789/

但我还是更建议优先用 openclaw dashboard，因为它会尽量基于你当前的认证配置打开正确入口，也更不容易把 token 之类的信息暴露在终端历史里。

如果你能打开 UI，但总感觉授权不对、入口不对、浏览器标签页里地址怪怪的，优先重新执行一次：

1	openclaw dashboard

七、远程访问控制面板的 4 种常见方式

方式 1：Tailscale Serve

这是官方更推荐的远程访问方式之一。特点是：

Gateway 仍然保持在 127.0.0.1
Tailscale 提供 HTTPS 和路由
安全性和可维护性通常比裸公网好得多

命令示例：

1	openclaw gateway --tailscale serve

常见访问形式：

1	https://<你的 MagicDNS 地址>/

如果你启用了 gateway.auth.allowTailscale: true，Serve 模式下还可以使用 Tailscale 身份头做认证，而不一定每次都要手动带 token。

方式 2：直接绑定到 Tailnet IP

如果你不想用 Serve / Funnel，而是想让 Gateway 直接监听 Tailnet 地址，可以改成：

{
  "gateway": {
    "bind": "tailnet",
    "auth": {
      "mode": "token",
      "token": "your-token"
    }
  }
}

然后从另一台 Tailnet 设备访问：

1	http://<tailscale-ip>:18789/

这种方式要注意：

它不是 HTTPS
它不是 Serve
在这个模式下，http://127.0.0.1:18789/ 不再代表同一套远程访问语义

方式 3：Tailscale Funnel

Funnel 会把 Gateway 公开到公网，是风险最高的方式。

官方文档里明确要求：

Funnel 模式必须使用 password 认证
更推荐用环境变量 OPENCLAW_GATEWAY_PASSWORD

命令示例：

1	openclaw gateway --tailscale funnel --auth password

如果你对公网暴露、安全策略和共享密码管理还不熟，建议先不要碰这条路线。

方式 4：SSH 隧道

如果你只是临时远程连一下，最稳的替代方案往往还是 SSH 隧道：

1	ssh -N -L 18789:127.0.0.1:18789 user@remote-host

然后本机访问：

1	http://127.0.0.1:18789/

这也是官方 Runbook 里给出的推荐回退路线之一。

八、首次从新设备访问时的配对问题

很多人第一次从新浏览器、新电脑、Tailnet 远程设备访问时，会看到：

1	disconnected (1008): pairing required

这通常不代表服务坏了，而是设备配对还没批准。

解决方法：

1 2	openclaw devices list openclaw devices approve <requestId>

如果你就是批准最近一条待处理请求，也可以：

1	openclaw devices approve --latest

这里有几个很容易忽略的点：

本地 127.0.0.1 访问，很多时候会自动批准
远程设备更容易触发手动配对
不同浏览器 profile 会产生不同设备身份
如果设备重试配对时公钥或权限变了，旧请求可能会被新请求替换，所以批准前最好先重新跑一次 openclaw devices list

九、控制面板里到底能做什么

按官方首页和 Control UI 相关文档，目前浏览器面板最核心的用途包括：

聊天与会话操作
查看配置和状态
管理节点与设备
跟踪日志
管理渠道
处理执行审批
做更新、重启和日常运维操作

对大多数新手来说，最常用的通常还是下面这几类：

聊天
渠道管理
日志
配置
设备与配对

所以如果你只是第一次安装，不用一开始就把所有功能都摸一遍，先把本地 UI、认证和日志看明白，就已经够用了。

十、安全配置这一节一定别跳过

OpenClaw 的控制面板本质上是你的管理入口，所以安全策略不能太随意。

我建议你至少记住下面几条：

非 loopback 绑定时，一定要配置认证
非 loopback 的 Control UI 部署，最好显式设置 gateway.controlUi.allowedOrigins
向导通常会帮你生成 token，但你最好确认 gateway.auth.mode
如果你同时设置了 gateway.auth.token 和 gateway.auth.password，一定要显式指定 gateway.auth.mode
如果你使用密码认证，优先用 OPENCLAW_GATEWAY_PASSWORD，不要把密码长期明文写进配置文件
如果机器上会跑不受信任的本地代码，尽量关闭 gateway.auth.allowTailscale，不要依赖隐式身份头
除非有明确需求，否则不要把 Dashboard 直接公开到互联网

还有两个名字就很危险的开关，我建议只在排障时临时使用：

allowInsecureAuth
dangerouslyDisableDeviceAuth

它们不是“增强兼容性的小优化”，而是真会降低安全边界的配置。

十一、配置文件和环境变量在哪里

默认情况下，配置文件一般在：

1	~/.openclaw/openclaw.json

如果你不确定当前机器实际读的是哪个配置文件，最稳的方式不是靠猜，而是直接执行：

1	openclaw config file

常见环境变量包括：

1
2
3

export OPENCLAW_HOME=/path/to/openclaw-home
export OPENCLAW_STATE_DIR=/path/to/openclaw-state
export OPENCLAW_CONFIG_PATH=/path/to/openclaw.json

它们分别控制：

OPENCLAW_HOME：home 语义路径
OPENCLAW_STATE_DIR：可变状态目录
OPENCLAW_CONFIG_PATH：配置文件位置

如果你一台机器上要跑多个实例，这几个变量会非常重要。

十二、常见故障排查

1. 安装后提示找不到 `openclaw`

先执行：

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

如果发现全局 npm bin 不在 PATH 里，补上：

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

然后重新打开终端。

2. Gateway 启不来

先看这几个命令：

openclaw doctor
openclaw gateway status
openclaw status
openclaw logs --follow

优先检查：

gateway.mode 有没有设成 local
端口是否被占用
认证配置是否冲突
守护进程是否真的跑起来

3. 本地面板打不开

如果 http://127.0.0.1:18789/ 打不开，不要第一时间怪浏览器。

先确认：

Gateway 是否在监听
gateway.bind 是否还是本地预期模式
你是不是误切到 tailnet 绑定了

很多人是配置变了，但还在按旧地址访问。

4. 看日志比盲猜快得多

最直接的方式：

1	openclaw logs --follow

官方文档里默认滚动文件日志路径通常在：

1	/tmp/openclaw/openclaw-YYYY-MM-DD.log

如果你是 Docker 部署，还要额外关注挂载目录、容器健康检查和 /tmp/openclaw/ 里的滚动日志。

十三、更新和维护

官方当前更推荐的升级方式，是重新执行官网安装器：

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

如果你不想再次进入新手引导，可以这样：

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

如果你是源码安装，官方更偏向直接使用：

1	openclaw update

openclaw update 会根据安装方式尽量走安全更新流程，并在适合的情况下自动重启 Gateway。

升级后，我建议再手动做一遍简短验收：

1
2
3

openclaw doctor
openclaw gateway status
openclaw dashboard

如果你是 Docker 部署，更新逻辑还要结合镜像版本、Compose 配置和持久化挂载一起看，不能完全套本地 CLI 的思路。

十四、如果你是第一次装 OpenClaw，我建议这样做

把这篇文章压缩成一句话，就是：

先走官方安装脚本，再走新手引导，然后用 doctor、status、dashboard 做验收；要远程访问时，先选 Tailscale Serve 或 SSH 隧道，不要一上来就把控制面板暴露到公网。

如果你更偏实操，可以继续看这些文章：