Home

深色模式

OpenClaw 安装步骤 ​

概述 ​

OpenClaw 的安装并不复杂，真正决定体验的通常是后面的初始化和健康检查。比较稳妥的顺序是：

  1. 确认运行环境
  2. 安装 OpenClaw CLI
  3. 执行首次引导
  4. 检查 Gateway 状态
  5. 打开控制台验证是否可用

如果你按这个顺序做，通常第一次上手会顺很多。

环境要求 ​

根据官方文档，当前建议使用较新的 Node 环境：

  • Node 24 为推荐版本
  • Node 22 LTS 仍然兼容

在开始之前，建议先检查本机版本：

bash
node --version

如果版本过低，先升级 Node，再继续安装。

对于不同系统，OpenClaw 的常见使用方式大致是：

  • macOS：体验最完整，官方文档覆盖最充分
  • Linux：适合长期运行 Gateway
  • Windows：更推荐通过 WSL2 使用 CLI 方案

安装 OpenClaw ​

官方推荐方式 ​

官方 Getting Started 当前更推荐直接使用安装脚本。

macOS 或 Linux：

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

Windows PowerShell：

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

安装完成后，先确认命令已经可用：

bash
openclaw --version

其他安装方式 ​

如果你更习惯 Node 包管理器，也可以使用全局安装方式。不过不同版本的官方资料里，推荐入口有变化，所以更稳妥的选择仍然是以上安装脚本。

例如：

bash
npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

如果你使用的是团队环境或已有 Node 工具链，这种方式也很常见。

首次初始化 ​

安装完成后，不建议立刻手改配置文件，先跑一次官方引导流程更省心：

bash
openclaw onboard --install-daemon

这个过程通常会引导你完成下面几件事：

  • 选择 QuickStart 或 Advanced 模式
  • 配置本地 Gateway
  • 设置端口、绑定地址和认证方式
  • 选择模型提供方并配置认证
  • 选择是否配置聊天渠道
  • 设置 workspace 目录
  • 安装后台服务

如果你只是想快速完成第一次可用环境，通常直接用默认的 QuickStart 就够了。

onboard 和 setup 的区别 ​

很多人看到官方文档里同时出现 openclaw onboard 和 openclaw setup，会有点混淆。

可以简单理解为：

  • openclaw onboard：更完整的首次引导流程，适合新手
  • openclaw setup：更偏向初始化配置和工作区

如果你是第一次安装，优先使用：

bash
openclaw onboard --install-daemon

如果你后面只是补建配置或重新整理环境，再考虑：

bash
openclaw setup

初始化完成后先检查什么 ​

检查 Gateway 状态 ​

如果安装流程里已经把服务装好了，第一步先看 Gateway 是否真的跑起来了：

bash
openclaw gateway status

如果状态正常，说明核心服务已经在运行。

打开本地控制台 ​

最直接的验证方式，是打开 OpenClaw 的本地控制台：

bash
openclaw dashboard

默认情况下，也可以直接访问：

text
http://127.0.0.1:18789/

如果页面能正常打开，通常说明本地 Gateway 已经可用了。

做一次健康检查 ​

除了打开页面，最好再做一遍命令行健康检查：

bash
openclaw health

如果这里没有明显报错，说明你的安装流程基本完成。

调试时的前台运行方式 ​

有时候你只是想快速验证，或者怀疑后台服务没有正常启动，这时可以直接以前台方式运行 Gateway：

bash
openclaw gateway --port 18789

这种方式更适合调试，因为你能直接看到终端输出。

如果你已经有配置文件，也可以进一步配合日志命令排查：

bash
openclaw logs
openclaw logs --follow

安装后的目录结构 ​

完成初始化后，本地通常会出现这些关键位置：

text
~/.openclaw/
├── openclaw.json
├── .env
├── workspace/
├── credentials/
└── agents/

其中最重要的几个目录分别负责：

  • openclaw.json：主配置文件
  • .env：环境变量和密钥引用
  • workspace/：长期工作区
  • credentials/：认证信息
  • agents/：不同 agent 的独立配置

常见问题 ​

openclaw 命令不可用 ​

这通常意味着安装没有完成，或者可执行文件目录还没有加入 PATH。先重新执行安装，再确认：

bash
openclaw --version

Gateway 没有启动 ​

优先按这个顺序检查：

  1. openclaw gateway status
  2. openclaw health
  3. openclaw logs --follow

如果只是想判断是不是后台服务问题，可以先以前台方式手动启动一次。

初始化做到一半想重新配置 ​

可以使用：

bash
openclaw configure

这比直接手改配置更适合新手。

安装完成后的下一步 ​

完成安装后，建议马上做两件事：

  1. 先理解 ~/.openclaw/openclaw.json 里的核心配置项
  2. 再去接入你真正要使用的渠道、模型和工作区

也就是说，安装只是第一步，真正决定日常体验的是后面的配置。

参考 ​