Last updated on

OpenClaw 部署教程：从安装到跑通的最小可用指南

如果你是第一次接触 OpenClaw，这篇文章可以当成一份先跑通、再慢慢扩展的入门指南。

这篇教程只做一件事：帮你把 OpenClaw 跑到最小可用。

也就是说，读完之后，你至少应该能做到：

  1. 把 OpenClaw 安装到自己的机器上
  2. 让 Gateway 正常启动
  3. 确认 CLI 和基础交互是可用的
  4. 出问题时知道应该先查哪里

我不会一上来就把消息渠道、浏览器、自动化、节点设备全部塞进来。那样信息很多，但对第一次部署的人并不友好。

先把第一版跑通，比什么都重要。

一句话理解 OpenClaw

OpenClaw 可以理解成一个运行在你自己环境里的个人 assistant 系统。

它不只是一个聊天界面，还能逐步连接：

  • 文件系统
  • 浏览器
  • 定时任务
  • 消息渠道
  • 节点设备
  • 你自己的工作区和记忆文件

如果你想要的不只是“问一句答一句”的 AI，而是一个能真正参与日常工作流的助手，那 OpenClaw 这种系统就很值得折腾。

这篇教程适合谁

这篇文章更适合下面几类读者：

  • 第一次部署 OpenClaw
  • 想先把本地环境跑通，再慢慢加功能
  • 不想一开始就碰太复杂的配置
  • 遇到过“装上了，但不知道算不算能用”的情况

如果你已经熟悉 OpenClaw 的整体架构，这篇更像是一份快速回忆版检查清单。

先说一个安全建议：别直接拿 root 账号开搞

如果这是台长期要跑 OpenClaw 的机器，我更建议你新建一个普通用户专门来装和运行，而不是直接用 root，也不要把你自己的 sudo 密码直接交给它。

这样做的好处很直接：

  • 权限边界更清楚
  • 就算后面接更多工具，也更容易控制风险
  • 出问题时，不容易把整台机器一起带歪

如果你现在还没有合适的普通用户，可以先在 Linux 上这样创建一个：

sudo adduser openclaw

如果你希望这个用户具备必要时自己安装软件的能力，再按需把它加入 sudo 组：

sudo usermod -aG sudo openclaw

但即便加了 sudo，我的建议仍然是：不要默认把 sudo 密码交给这个运行环境，也不要长期用 root 直接部署和日常操作。

后面的命令，你都可以切到这个新用户下面再继续做。

切换用户:

su - openclaw

部署前需要准备什么

根据官方文档，OpenClaw 的基础要求至少包括：

  • Node.js 22 或更高版本
  • macOS、Linux 或 Windows
  • 如果从源码构建，需要 pnpm

如果你在 Windows 上部署，官方更推荐放在 WSL2 里运行，而不是直接在原生 Windows 环境里硬怼。

我建议你额外准备这几样

虽然不是绝对必须，但会明显减少踩坑：

  • 一个正常可用的 shell 环境
  • 能稳定联网
  • 基本的命令行操作能力
  • 对 PATH、配置文件、后台服务这些概念有基础认识

第一步：确认 Homebrew（可选但推荐）

先把一件事说清楚：Homebrew 不是 OpenClaw 的硬前置，也不在官方一键安装脚本的自动安装范围内。

也就是说：

  • 没有 Homebrew，你依然可以安装 OpenClaw
  • 一键脚本不会负责帮你把 Homebrew 装好
  • 但如果你后面还会折腾更多命令行工具，先有 Homebrew 往往更省事

先检查它是否可用：

brew --version

如果你还没有安装，可以去官网按系统说明处理：https://brew.sh/。

这一步是可选但推荐，尤其适合后面还要接浏览器、额外 CLI 工具或其他依赖的读者。

第二步：确认 Node.js 版本正确

OpenClaw 对 Node 版本有要求，所以先别急着安装，先确认当前环境：

node -v
npm -v

如果 node -v 不是 v22.x 或更高，建议先升级。

建议使用 Node 版本管理工具来安装和管理 Node 版本，这样更灵活，也更容易排查版本相关问题。

安装教程：https://nodejs.org/en/download

当然，也可以直接安装：

Ubuntu / Debian系统：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

（其他系统自行查找相关安装教程）

这一步为什么重要

很多“看起来很玄学”的问题，本质上只是 Node 版本不对。

所以部署 OpenClaw 时，先确认 Node 版本，几乎总是值得的。

第三步：选择安装方式

这里我建议直接分成两种理解：

  • 自动安装：适合想尽快跑起来的人
  • 手动安装：适合想把每一步看得更清楚的人

两种方式都能装上 OpenClaw，区别主要在于：自动安装更省事，手动安装更可控。

方案 A：自动安装（官方脚本）

如果你想先快速跑通，可以直接用官方一键安装脚本：

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

这条命令适合想尽快完成安装的读者，因为它会自动处理一部分环境准备和安装流程。

你可以把它理解成什么

对多数新手来说，这个脚本的价值是：

  • 少敲几步命令
  • 少记一些安装细节
  • 更快进入“先跑起来”的阶段

但它不等于“什么都替你搞定”

这里要特别说明两个边界：

  1. 这个脚本可以自动处理 npm 安装链路，所以你不需要再额外手动执行一次 npm install -g openclaw@latest
  2. 这个脚本不能替你安装 Homebrew，所以不要把它理解成“系统级全自动环境配置器”

换句话说，这个脚本更像是 OpenClaw 安装脚本，不是一份“把整台机器所有开发环境都配好”的万能脚本。

自动安装后建议立刻做的事

脚本跑完后，建议马上确认命令是否可用：

openclaw help

如果能正常看到帮助信息，再继续执行：

openclaw onboard --install-daemon

这一步通常会帮你完成第一轮初始化，比如：

  • 生成初始配置
  • 安装 Gateway 守护进程
  • 引导你完成基础设置

对第一次部署的人来说，这通常比自己手改配置更稳。

方案 B：手动安装（自己一步一步装）

如果你更希望每一步都清清楚楚，建议用手动安装。

1）先用 npm 安装 OpenClaw

npm install -g openclaw@latest

2）再执行初始化 / 引导配置

openclaw onboard --install-daemon

如果你只想先完成基础引导，不顺手安装 daemon，也可以先运行：

openclaw onboard

手动安装适合哪些读者

这种方式更适合：

  • 想知道每一步到底做了什么
  • 需要自己控制环境变更
  • 已经有一定命令行经验
  • 后面准备继续排查、定制、扩展

如果你本来就习惯自己管理 Node、npm、PATH 和 shell 配置，那我会更偏向推荐你用手动安装。

第四步：确认 openclaw 命令真的可用

无论你走的是自动安装还是手动安装，安装完成后都别急着继续配功能，先确认 CLI 是否真正可用：

openclaw help

如果提示 openclaw: command not found，大概率不是 OpenClaw 本身坏了，而是 npm 全局 bin 目录没有进 PATH。

你可以先这样排查：

npm prefix -g
echo "$PATH"

如果发现 npm 的全局 bin 没有进环境变量，可以在 ~/.bashrc 或 ~/.zshrc 里补上：

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

然后重新打开终端，或者执行：

hash -r

第五步：检查 Gateway 状态

Gateway 是 OpenClaw 的核心组件之一。很多能力最终都绕不过它。

常用命令有这几个：

openclaw gateway status
openclaw gateway start
openclaw gateway restart

推荐按这个顺序检查：

1）先看状态

openclaw gateway status

2）如果没起来，就启动

openclaw gateway start

3）改完关键配置后，再重启

openclaw gateway restart

如果你只是想临时在前台调试，也可以运行：

openclaw gateway run

这种方式适合排查问题，因为你能直接看到前台输出。

第六步：只做最小配置，不要一次配满

OpenClaw 默认会读取配置文件：

~/.openclaw/openclaw.json

如果文件不存在，它会使用安全默认值。

对新手来说，我最推荐的原则其实就一句话：

先做最小可用配置，不要一开始就把所有渠道、工具和自动化一起打开。

刚开始你最值得关心的通常是：

  • 工作区路径是否正确
  • 模型是否已经配置好
  • Gateway 是否正常
  • 权限是不是过宽

如果你想继续调整配置，常见入口有：

openclaw onboard
openclaw configure
openclaw config get agents.defaults.workspace

第七步：不要只看“启动成功”，要做真实验证

很多人部署完之后只看服务在不在，然后就以为完成了。

其实更可靠的判断方式是：你能不能真的用它。

建议至少检查下面这些：

  • openclaw status 是否能正常返回
  • openclaw doctor 是否报出明显错误
  • Gateway 是否已启动
  • 你是否能实际和它交互
  • 它是否能正确访问你的工作区

最少可以先跑：

openclaw doctor
openclaw status
openclaw dashboard

这里面：

  • doctor 适合检查配置和环境问题
  • status 适合看整体状态
  • dashboard 适合打开控制 UI，确认你能不能顺利进入界面

如果你想做更深入的状态检查，也可以试试：

openclaw status --deep

第八步：第一次交互，优先试试 Dashboard 或 TUI

当 CLI、Gateway 和最小配置都跑通后，建议直接进行一次真实交互。

你可以选自己更顺手的入口：

方案 A：Dashboard

openclaw dashboard

适合刚开始确认系统整体是否已经连起来。

方案 B：TUI

openclaw tui

如果你平时更习惯终端，这通常是很自然的入口。

一个更稳妥的部署顺序

如果你想尽量少踩坑，我建议按下面这个顺序来：

  1. 确认是否需要 Homebrew（可选）
  2. 安装或升级到 Node 22+
  3. 二选一：执行自动安装脚本，或手动执行 npm install -g openclaw@latest
  4. 确认 openclaw help 可用
  5. 运行 openclaw onboard --install-daemon
  6. 检查 openclaw gateway status
  7. 执行 openclaw doctor
  8. 执行 openclaw status
  9. 打开 openclaw dashboard 或 openclaw tui
  10. 再去接消息渠道、浏览器、cron、节点设备

这个顺序的好处在于：任何一步出问题，你都比较容易判断问题大概在哪一层，而不是所有东西一起炸。

部署时最常见的坑

1. Node 版本不对

这是最常见的问题之一。版本太旧，后面会出现很多看似随机、实际上并不随机的问题。

2. 把自动安装脚本理解成“万能装机脚本”

它能帮你更快装 OpenClaw，但它不是替你把所有系统依赖、所有包管理器都装好的全自动方案。

尤其是 Homebrew 不在这个脚本的自动安装范围内，这一点最好单独说明清楚。

3. openclaw 已安装，但 PATH 没配好

命令明明装好了，却提示找不到。这通常是 shell 环境问题，不是 OpenClaw 核心本身的问题。

4. 一开始就给太多权限

我不建议在第一阶段就开太多高风险能力。先在小范围里稳定跑起来，再逐步放权，会更稳。

5. 只看服务启动，不做实际验证

“启动成功”不等于“能用”。

真正的完成标准应该是：

  • 你能进入交互界面
  • 你能正常执行基础命令
  • 你知道出问题去哪里排查

6. 把配置问题和环境问题混在一起查

比如明明是 Node 版本不对，却一直怀疑是 Gateway 没起；或者明明是 PATH 问题，却一直在重装。

部署时最好按层排查：

  1. 环境层
  2. 安装层
  3. CLI 层
  4. Gateway 层
  5. 配置层
  6. 实际交互层

这样会清楚很多。

如果部署失败，建议按这个顺序排查

如果你跑到一半卡住了，可以按这个顺序回头看：

  1. node -v 是否已经到 22+
  2. openclaw help 是否可用
  3. openclaw gateway status 是否正常
  4. openclaw doctor 报了什么
  5. openclaw status 是否能返回完整信息
  6. openclaw dashboard 或 openclaw tui 是否能真正进入

这样排查通常比“重装一次试试”更有效。

关于配置，我的建议

如果你不是做生产级部署，而是个人使用，我建议这样理解配置：

  • 先保守：安全和可控优先
  • 先简单：先跑起来，再慢慢扩展
  • 先私有：优先在自己的环境里验证
  • 先逐步扩展：需要什么，再打开什么

OpenClaw 不是那种“装完就结束”的工具，它更像一个会逐渐长成你工作流形状的系统。

部署完成后，下一步可以做什么

当基础部署完成后，下一步通常会想做这些：

  • 接入 Telegram、Discord 等消息渠道
  • 配置 heartbeat 和 cron 提醒
  • 让它读写工作区文件
  • 连接浏览器做自动化
  • 配置多 Agent 或不同工作区
  • 建立记忆文件和长期工作规范

这时候你才会开始真正体会到 OpenClaw 的乐趣：

不是“它能不能答题”，而是“它能不能真正帮你做事”。

最后

如果你是第一次部署这类 assistant 系统，不要追求一步到位。

第一阶段的成功标准，其实很朴素：

  • 装上
  • 跑起来
  • 能交互
  • 出问题时知道怎么查

只要这四件事做到，后面不管是美化、扩展，还是做自动化，都会顺很多。

等你把第一版跑通之后，再去折腾更高级的玩法，心态会轻松很多。