OpenClaw 安装详细教程(Windows / macOS 小白版)

这是一份给新手准备的 OpenClaw 安装教程，覆盖 Windows 和 macOS 两个平台。你可以跟着步骤一步一步操作，不需要一开始就理解所有概念。先装好、先跑起来，再逐步优化配置就行。

• 安装前需要准备什么
• Windows 怎么安装（含推荐的 WSL2 方案）
• macOS 怎么安装
• Node.js、Git 等前置环境怎么装
• OpenClaw 本体怎么安装
• 第一次启动和初始化怎么做
• 怎么配置 API Key 或订阅
• 怎么配置飞书机器人
• 常见配置项怎么理解
• 如果后面想换订阅或换模型，应该怎么改

一、先理解 OpenClaw 是什么

OpenClaw 可以理解成一个“可连接多种渠道和工具的 AI 助手框架”。它本身不是单独的大模型，而是一个运行平台。你需要给它接上模型能力，比如：

• OpenAI API Key
• OpenAI Codex / ChatGPT 订阅登录
• 其他模型提供商的 API Key装好以后，你可以让它：
• 在本机命令行里使用
• 在网页面板里聊天
• 接入飞书、Telegram、Discord 等渠道
• 配置工具、插件、技能和自动化能力

二、安装前准备

1. 电脑要求

Windows

建议以下两种方式任选其一：

• 推荐：WSL2 + Ubuntu 安装 OpenClaw
• 可用：原生 Windows 安装 OpenClaw对于新手，如果你愿意多做一步配置，WSL2 更稳、更接近官方推荐路径。

macOS

• 建议使用较新的 macOS 系统版本
• 终端使用系统自带 Terminal 或 iTerm2 都可以

2. 需要提前准备的东西

开始前建议准备好下面这些：

• 一台可以联网的电脑
• 管理员权限（安装软件时可能会用到）
• 一个模型账号或 API Key
• 如果你要接飞书：一个飞书账号，以及创建企业应用的权限

3. 前置软件清单

安装 OpenClaw 前，建议先准备：

• Node.js：必须，官方要求 Node 22.14 以上，推荐 Node 24
• Git：建议安装，方便拉代码、更新和排查问题
• 终端工具：Windows 用 PowerShell / WSL，macOS 用 Terminal

官方文档当前建议：Node.js 推荐使用 Node 24；Node 22.14+ 也可以。

三、Windows 安装教程

3.1 先决定你走哪条路

Windows 安装有两种常见路径：

路线 A：WSL2 安装（推荐）

优点：

• 兼容性更好
• 更接近 Linux/macOS 的官方使用体验
• 后续很多命令、教程更容易对上适合：
• 想稳一点
• 可以接受在 Ubuntu 终端里操作

路线 B：原生 Windows 安装

优点：

• 操作直观
• 全程在 Windows 里完成适合：
• 不想装 WSL2
• 只想先快速体验下面我会把两条路径都写出来。

3.2 Windows 路线 A：WSL2 安装（推荐）

第一步：安装 WSL2

用管理员身份打开 PowerShell，执行：

wsl --install

如果你想指定 Ubuntu 版本，也可以这样：

wsl --list --onlinewsl --install -d Ubuntu-24.04

安装完成后，如果系统提示重启，就先重启电脑。

第二步：第一次进入 Ubuntu

重启后打开 Ubuntu，系统会让你创建一个 Linux 用户名和密码。这一步很重要，后面很多命令都会用到这个账号。

第三步：开启 systemd（推荐）

在 Ubuntu 终端里执行：

sudo tee /etc/wsl.conf > /dev/null <<&#x27;EOF&#x27;[boot]systemd=trueEOF

然后回到 PowerShell，执行：

wsl --shutdown

再重新打开 Ubuntu。检查 systemd 是否正常：

systemctl --user status

如果能正常返回状态，说明 systemd 已经启用。

第四步：安装 Node.js

OpenClaw 需要 Node.js。先检查有没有安装：

node -v

如果没有安装，或者版本太低，建议装新版 Node。在 Ubuntu 里可使用：

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

安装后验证：

node -vnpm -v

只要 Node 版本是 22.14+，就能满足要求；24.x 更推荐。

第五步：安装 Git

先检查：

git --version

如果没有安装：

sudo apt-get updatesudo apt-get install -y git

第六步：安装 OpenClaw

在 WSL 的 Ubuntu 里执行：

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

装完以后，检查版本：

openclaw --version

第七步：运行初始化向导

执行：

openclaw onboard --install-daemon

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

• 模型认证或 API Key 配置
• Gateway 配置
• 后台服务安装

第八步：检查网关状态

openclaw gateway status

正常情况下，你应该能看到 Gateway 正在运行。

第九步：打开控制面板

openclaw dashboard

浏览器如果能正常打开页面，基本说明安装成功。

3.3 Windows 路线 B：原生 Windows 安装

第一步：安装 Node.js

官方建议先安装 Node.js。

方法 1：使用 winget（推荐）

以管理员身份打开 PowerShell：

winget install OpenJS.NodeJS.LTS

方法 2：使用 Chocolatey

choco install nodejs-lts

方法 3：去官网下载安装包

去 Node.js 官网下载安装包，安装完成后执行：

node -vnpm -v

第二步：安装 Git

方法 1：使用 winget

winget install Git.Git

安装后验证：

git --version

第三步：安装 OpenClaw

PowerShell 中执行：

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

安装完成后检查：

openclaw --version

第四步：运行初始化向导

openclaw onboard --install-daemon

如果你只是想先安装 CLI，不想先折腾服务，也可以先用：

openclaw onboard --non-interactive --skip-health

或者直接运行网关：

openclaw gateway run

第五步：检查状态

openclaw gateway status

第六步：打开控制面板

openclaw dashboard

虽然原生 Windows 也支持，但官方目前仍然更推荐 WSL2 路线。如果你后续遇到奇怪兼容问题，优先考虑切回 WSL2。

四、macOS 安装教程

4.1 先安装 Homebrew（如果还没有）

先打开终端，输入：

brew --version

如果提示没有这个命令，说明还没安装 Homebrew。去 Homebrew 官网按提示安装，或使用官方命令安装。

4.2 安装 Node.js

macOS 推荐直接用 Homebrew：

brew install node

安装后检查：

node -vnpm -v

建议版本：

• 推荐：Node 24
• 最低要求：Node 22.14+

4.3 安装 Git

先检查：

git --version

如果没有安装：

brew install git

4.4 安装 OpenClaw

macOS / Linux 官方推荐的快速安装命令：

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

安装后执行：

openclaw --version

4.5 首次初始化

openclaw onboard --install-daemon

这个命令会引导你完成初始化配置。

4.6 检查服务状态

openclaw gateway status

4.7 打开控制面板

openclaw dashboard

如果浏览器成功打开，并且你能看到界面，说明 OpenClaw 已经可以使用。

五、如果命令执行后提示找不到 openclaw

有时并不是安装失败，而是 PATH 没配置好。你可以先执行：

npm prefix -g

然后查看你的 PATH：

echo "$PATH"

macOS / Linux 常见处理方法是在 ~/.zshrc 或 ~/.bashrc 里加入：

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

保存后重新打开终端。Windows 则需要把 `npm prefix -g` 输出的目录加入系统环境变量 PATH。

六、OpenClaw 安装完成后，目录和配置在哪

一般你会接触到两个重要位置：

• 配置文件：~/.openclaw/openclaw.json
• 工作区：~/.openclaw/workspace你也可以先执行：

openclaw setup

它会初始化基础配置和工作区。如果你是第一次安装，通常 `openclaw onboard` 已经帮你处理了不少事情。

七、如何配置模型：API Key 或订阅

OpenClaw 自己不提供模型，你需要给它接入模型能力。最常见的是 OpenAI，两种方式：

方式 A：使用 OpenAI API Key

适合：

• 想按量计费
• 有 OpenAI Platform API Key可以在命令行配置：

openclaw onboard --auth-choice openai-api-key

或者：

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

配置示例（写在 ~/.openclaw/openclaw.json）：

{  env: { OPENAI_API_KEY: "sk-xxx" },  agents: {    defaults: {      model: { primary: "openai/gpt-5.4" }    }  }}

这表示：

• 使用 OpenAI 官方 API
• 默认模型是 openai/gpt-5.4

方式 B：使用 OpenAI Codex / ChatGPT 订阅登录

适合：

• 想使用 ChatGPT / Codex 登录授权
• 不想直接填 API Key可以执行：

openclaw onboard --auth-choice openai-codex

或者单独登录：

openclaw models auth login --provider openai-codex

配置示例：

{  agents: {    defaults: {      model: { primary: "openai-codex/gpt-5.4" }    }  }}

这表示默认走 Codex / ChatGPT 订阅登录方式。

八、怎么理解 API Key 和订阅的区别

简单理解：

方式

你需要什么

适合谁

API Key

OpenAI 平台密钥

想稳定按量付费的用户

Codex / ChatGPT 订阅

ChatGPT/Codex 登录权限

想用订阅身份接入的人

API Key 的特点

• 配置简单
• 计费明确
• 更适合稳定生产使用

订阅登录的特点

• 不一定要单独准备 API Key
• 更适合已有 ChatGPT / Codex 订阅的人
• 某些模型能力和权限可能与订阅状态相关

如果你是第一次接触，最容易理解的方式通常是：

1. 有 API Key 就先走 API Key
2. 没有 API Key，但已有 ChatGPT / Codex 订阅，就试订阅登录

九、飞书插件和飞书机器人怎么配置

如果你想让 OpenClaw 在飞书里工作，需要配置飞书渠道。根据当前官方文档，飞书通常已经是随版本捆绑提供的插件，很多情况下不需要单独安装。如果你的版本比较旧，或者环境里没有捆绑，也可以手动安装：

openclaw plugins install @openclaw/feishu

安装或变更后，重启网关：

openclaw gateway restart

十、飞书配置详细步骤

10.1 在飞书开放平台创建应用

进入飞书开放平台：

• 国内版：https://open.feishu.cn/app
• 国际版 Lark：https://open.larksuite.com/app然后：

1. 创建企业自建应用
2. 设置应用名称、描述、图标
3. 进入凭证页面，复制：

• App ID
• App Secret

10.2 配置权限

在权限页面中，按官方推荐导入需要的权限。关键点是至少要保证和消息收发相关的权限存在，例如：

• 读取消息
• 发送消息
• 获取资源
• 获取群成员或聊天相关信息

10.3 开启 Bot 能力

在应用能力里启用机器人（Bot）。

10.4 配置事件订阅

OpenClaw 当前支持用 WebSocket 长连接接飞书事件，优点是：

• 不一定需要公网 webhook 地址
• 本地调试更方便在飞书开放平台里：

1. 打开 Event Subscription
2. 选择 Use long connection to receive events
3. 添加事件：im.message.receive_v1

10.5 发布应用

应用配置完以后，记得：

• 创建版本
• 提交审核
• 发布应用否则机器人可能配置好了但不能正常收发消息。

十一、在 OpenClaw 中写入飞书配置

你可以用命令方式添加：

openclaw channels add

然后在交互流程中选择 Feishu，填入：

• App ID
• App Secret也可以手动编辑配置文件 ~/.openclaw/openclaw.json。示例：

{  channels: {    feishu: {      enabled: true,      dmPolicy: "pairing",      accounts: {        main: {          appId: "cli_xxx",          appSecret: "xxx",          name: "My AI assistant"        }      }    }  }}

这些字段是什么意思

• enabled: true：启用飞书渠道
• dmPolicy: "pairing"：私聊默认走配对机制
• accounts.main：定义一个飞书账号配置
• appId / appSecret：飞书应用凭证
• name：这个账号配置的说明名

十二、飞书里机器人为什么还不能直接用

因为默认通常有一个“配对”机制。也就是说，第一次有人给机器人发私信时，OpenClaw 可能会返回一个配对码。你需要在命令行批准它。查看和批准命令通常是：

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

批准以后，这个用户就能正常和机器人对话。

十三、群聊里怎么让飞书机器人工作

飞书群聊常见配置点有几个：

1. 群组策略

groupPolicy 常见值：

• open：允许所有群组，默认常见配置
• allowlist：只允许指定群
• disabled：禁用群消息

2. 是否必须 @ 机器人

groups.<chat_id>.requireMention常见默认值是：

• true：必须 @ 机器人，它才回复示例：

{  channels: {    feishu: {      groupPolicy: "open",      groups: {        "oc_xxx": {          requireMention: true        }      }    }  }}

这表示在指定群里，必须 @ 机器人它才会回应。

十四、一些常见配置项，给新手解释一下

下面这些是你后面可能会接触到的配置项：

**配置项**

**作用**

**给新手的理解**

`agents.defaults.model.primary`

设置默认模型

决定 OpenClaw 默认调用哪个模型

`env.OPENAI_API_KEY`

OpenAI API 密钥

如果你走 API Key 路线，这里通常要配置

`channels.feishu.enabled`

启用飞书渠道

相当于总开关

`channels.feishu.accounts..appId`

飞书 App ID

你的飞书应用身份

`channels.feishu.accounts..appSecret`

飞书 App Secret

你的飞书应用密钥，注意保密

`channels.feishu.groupPolicy`

群组访问策略

控制哪些群可以用机器人

`channels.feishu.streaming`

是否开启流式回复

开启后，回复会边生成边显示

十五、怎么查看当前 OpenClaw 是否正常

你可以优先用这几个命令：

openclaw gateway statusopenclaw statusopenclaw status --all

这些命令可以帮助你看：

• Gateway 是否正常运行
• 渠道是否连通
• 当前状态有没有明显异常如果你要看更详细的运行信息，也可以用日志命令：

openclaw logs --follow

十六、以后如果要换订阅、换 API Key、换模型，怎么改

这个问题很常见，别担心，OpenClaw 的思路就是：改认证方式 + 改默认模型。

场景 1：从旧 API Key 换成新 API Key

你只需要更新配置里的 API Key。例如原来是：

{  env: { OPENAI_API_KEY: "sk-old" },  agents: {    defaults: {      model: { primary: "openai/gpt-5.4" }    }  }}

改成：

{  env: { OPENAI_API_KEY: "sk-new" },  agents: {    defaults: {      model: { primary: "openai/gpt-5.4" }    }  }}

然后重启 Gateway：

openclaw gateway restart

场景 2：从 API Key 切换到 Codex / ChatGPT 订阅

你可以重新走认证：

openclaw models auth login --provider openai-codex

然后把默认模型改成：

{  agents: {    defaults: {      model: { primary: "openai-codex/gpt-5.4" }    }  }}

最后重启：

openclaw gateway restart

场景 3：从 Codex / ChatGPT 订阅切回 API Key

把模型切回 API 路径，例如：

{  env: { OPENAI_API_KEY: "sk-xxx" },  agents: {    defaults: {      model: { primary: "openai/gpt-5.4" }    }  }}

然后重启 Gateway。

场景 4：想换成别的模型提供商

核心思路也一样：

1. 配置对应提供商的认证信息
2. 把 model.primary 改成对应的 provider/model
3. 重启 Gateway

十七、推荐给新手的最小可用配置思路

如果你只想先跑起来，不追求高级配置，可以按这个最小思路：

macOS / WSL 用户

1. 安装 Node.js
2. 安装 Git
3. 安装 OpenClaw
4. 执行 openclaw onboard --install-daemon
5. 配一个 OpenAI API Key
6. 先用 openclaw dashboard 验证能聊天
7. 再去接飞书

飞书接入最小路径

1. 创建飞书应用
2. 配 App ID / App Secret
3. 开启 Bot
4. 配置事件订阅（长连接）
5. 发布应用
6. 在 OpenClaw 中添加 Feishu 渠道
7. 重启 Gateway
8. 私聊机器人测试

十八、常见问题排查

1. `node` 命令找不到

说明 Node.js 没装好，或者 PATH 没配好。

2. `openclaw` 命令找不到

通常是安装成功了，但全局 npm 路径没有加入 PATH。

3. `gateway status` 显示异常

优先检查：

• 是否已经执行过 openclaw onboard
• 是否安装了后台服务
• 当前配置文件是否写错

4. 飞书机器人不回复

优先检查：

• 飞书应用是否已发布
• 是否启用了 Bot 能力
• 是否配置了 im.message.receive_v1
• Gateway 是否在运行
• 群里是否需要 @ 机器人

5. 飞书机器人能收到消息但发不出去

优先检查：

• 是否有消息发送权限
• App Secret 是否正确
• 日志里有没有报错

6. 切换模型后不生效

优先检查：

• model.primary 是否改对
• 认证方式是否匹配
• Gateway 是否已经重启

十九、给新手的最后建议

不要一开始就试图把所有插件、渠道、自动化全部配完。最稳的顺序是： 1. 先把 OpenClaw 本体装好 1. 先把模型接好 1. 先确认 dashboard 能聊天 1. 再接飞书 1. 最后再做高级配置如果你已经能做到下面这三件事，就说明你已经安装成功了： - `openclaw --version` 能输出版本 - `openclaw gateway status` 显示正常 - `openclaw dashboard` 打开后可以聊天

二十、附：本文常用命令速查

# 查看版本openclaw --version# 初始化openclaw onboard --install-daemon# 查看网关状态openclaw gateway status# 重启网关openclaw gateway restart# 打开控制面板openclaw dashboard# 查看综合状态openclaw statusopenclaw status --all# 查看日志openclaw logs --follow# 安装飞书插件（仅在需要手动安装时）openclaw plugins install @openclaw/feishu# 添加飞书渠道openclaw channels add# 批准飞书配对openclaw pairing list feishuopenclaw pairing approve feishu <CODE># OpenAI API Key 方式openclaw onboard --auth-choice openai-api-key# OpenAI Codex / ChatGPT 订阅方式openclaw onboard --auth-choice openai-codexopenclaw models auth login --provider openai-codex

一、先理解 OpenClaw 是什么

二、安装前准备

1. 电脑要求

Windows

macOS

2. 需要提前准备的东西

3. 前置软件清单

三、Windows 安装教程

3.1 先决定你走哪条路

路线 A：WSL2 安装（推荐）

路线 B：原生 Windows 安装

3.2 Windows 路线 A：WSL2 安装（推荐）

第一步：安装 WSL2

第二步：第一次进入 Ubuntu

第三步：开启 systemd（推荐）

第四步：安装 Node.js

第五步：安装 Git

第六步：安装 OpenClaw

第七步：运行初始化向导

第八步：检查网关状态

第九步：打开控制面板

浏览器如果能正常打开页面，基本说明安装成功。

3.3 Windows 路线 B：原生 Windows 安装

第一步：安装 Node.js

方法 1：使用 winget（推荐）

方法 2：使用 Chocolatey

方法 3：去官网下载安装包

第二步：安装 Git

方法 1：使用 winget

第三步：安装 OpenClaw

第四步：运行初始化向导

第五步：检查状态

第六步：打开控制面板

四、macOS 安装教程

4.1 先安装 Homebrew（如果还没有）

4.2 安装 Node.js

4.3 安装 Git

4.4 安装 OpenClaw

4.5 首次初始化

4.6 检查服务状态

4.7 打开控制面板

如果浏览器成功打开，并且你能看到界面，说明 OpenClaw 已经可以使用。

五、如果命令执行后提示找不到 openclaw

保存后重新打开终端。Windows 则需要把 npm prefix -g 输出的目录加入系统环境变量 PATH。

六、OpenClaw 安装完成后，目录和配置在哪

它会初始化基础配置和工作区。如果你是第一次安装，通常 openclaw onboard 已经帮你处理了不少事情。

七、如何配置模型：API Key 或订阅

方式 A：使用 OpenAI API Key

方式 B：使用 OpenAI Codex / ChatGPT 订阅登录

这表示默认走 Codex / ChatGPT 订阅登录方式。

八、怎么理解 API Key 和订阅的区别

API Key 的特点

订阅登录的特点

九、飞书插件和飞书机器人怎么配置

十、飞书配置详细步骤

10.1 在飞书开放平台创建应用

10.2 配置权限

10.3 开启 Bot 能力

10.4 配置事件订阅

10.5 发布应用

十一、在 OpenClaw 中写入飞书配置

这些字段是什么意思

十二、飞书里机器人为什么还不能直接用

批准以后，这个用户就能正常和机器人对话。

十三、群聊里怎么让飞书机器人工作

1. 群组策略

2. 是否必须 @ 机器人

这表示在指定群里，必须 @ 机器人它才会回应。

十四、一些常见配置项，给新手解释一下

十五、怎么查看当前 OpenClaw 是否正常

十六、以后如果要换订阅、换 API Key、换模型，怎么改

场景 1：从旧 API Key 换成新 API Key

场景 2：从 API Key 切换到 Codex / ChatGPT 订阅

场景 3：从 Codex / ChatGPT 订阅切回 API Key

场景 4：想换成别的模型提供商

十七、推荐给新手的最小可用配置思路

macOS / WSL 用户

飞书接入最小路径

十八、常见问题排查

1. node 命令找不到

保存后重新打开终端。Windows 则需要把 `npm prefix -g` 输出的目录加入系统环境变量 PATH。

它会初始化基础配置和工作区。如果你是第一次安装，通常 `openclaw onboard` 已经帮你处理了不少事情。

1. `node` 命令找不到

2. `openclaw` 命令找不到

3. `gateway status` 显示异常