全网最简单的 OpenClaw 部署教程，5 分钟拥有你的 AI 员工

优质文章学习记录

06 Apr 2026 — 9 min read

我们是由枫哥组建的IT技术团队，成立于2017年，致力于帮助IT从业者提供实力，成功入职理想企业，我们提供一对一学习辅导，由知名大厂导师指导，分享Java技术、参与项目实战等服务，并为学员定制职业规划，全面提升竞争力，过去8年，我们已成功帮助数千名求职者拿到满意的Offer：qiuzhiwang.vip。

前言

OpenClaw 是一款终端式 AI 助手，支持多模型适配、多渠道接入，既可本地部署，也支持云端一键安装。

本文聚焦“本地部署 + 飞书机器人接入”全流程，适配 macOS / Linux / Windows。

官网：https://openclaw.ai/
GitHub：https://github.com/openclaw/（以官方仓库为准）
部署方式：
- 本地部署（本文核心）
- 云端一键安装（阿里云 / 火山引擎 / MiniMax 等）
- Docker 镜像安装（需自行准备镜像环境）

一、准备工作：安装基础环境

OpenClaw 运行依赖 Node.js 24+ 和 Git。

npm 已包含在 Node.js 安装包中，无需单独安装。

注意：Windows 建议全程使用“管理员身份”运行 PowerShell。

1）安装 Node.js

方式 A：官方下载（新手推荐）

地址：https://nodejs.org/
选择 LTS v24+ 稳定版本

安装时勾选 `Add to PATH`

方式 B：包管理器安装（开发者推荐）

# macOS: 先安装 Homebrew（如未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装 Node.js brew install node # 强制重建软链接（部分环境需要） brew link node --overwrite --force # 配置 npm 国内镜像（可选，用于加速下载） npm config set registry https://registry.npmmirror.com/

2）安装 Git

方式 A：官方下载

地址：https://git-scm.com/
Windows 选择 64 位版本
安装时勾选 Add Git to PATH

方式 B：包管理器安装

# macOS brew install git # Debian / Ubuntu sudo apt install -y git # CentOS / RHEL sudo dnf install -y git

3）安装完成后验证（必做）

# 验证 Node.js node -v # 验证 npm npm -v # 验证 Git git --version

可选：配置 Git 全局身份，避免后续提交报错。

# 设置全局用户名 git config --global user.name "你的用户名" # 设置全局邮箱 git config --global user.email "你的邮箱"

二、OpenClaw 安装步骤

1）macOS / Linux

# 官方安装脚本 curl -fsSL https://openclaw.ai/install.sh | bash # 全局安装 openclaw 命令 npm i -g openclaw

2）Windows（管理员 PowerShell）

# 执行官方 PowerShell 安装脚本 iwr -useb https://openclaw.ai/install.ps1 | iex

说明：若 macOS/Linux 出现权限问题，可在命令前增加 sudo。

三、安装后交互式配置（核心）

安装完成后会进入交互式配置流程。

建议先按“最小可用”原则完成初始化，后续再在 Web UI 或终端细化配置。

建议按以下顺序确认：

运行模式与端口配置
模型提供方与密钥配置
渠道接入配置（如飞书）
配置保存与服务启动

四、飞书机器人接入（实操）

以下步骤与飞书开发者后台对应，你可以配合截图逐步说明。

步骤 1：创建企业自建应用

在飞书开放平台创建“企业自建应用”，填写：

应用名称
应用描述
应用图标

步骤 2：添加应用能力

在应用左侧菜单选择“添加应用能力”，添加“机器人”能力。

步骤 3：获取应用凭证

进入“凭证与基础信息”，记录：

App ID
App Secret

这两个参数用于 OpenClaw 与飞书的鉴权，务必妥善保存。

步骤 4：配置事件与回调

进入“事件与回调”页面：

选择订阅方式（长连接 / 推送到开发服务器）
保存配置
按需添加事件

步骤 5：在 OpenClaw 中填写飞书参数

将 App ID 与 App Secret 写入 OpenClaw 配置（建议使用环境变量），然后重启服务。

五、建议的环境变量写法（推荐）

# 飞书应用 ID（来自飞书开放平台） export FEISHU_APP_ID="cli_xxxxxxxxxxxxx" # 飞书应用 Secret（来自飞书开放平台） export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx" # OpenClaw 监听端口（按需调整） export OPENCLAW_PORT="3000"

Windows PowerShell 可使用：

# 设置当前会话环境变量 $env:FEISHU_APP_ID="cli_xxxxxxxxxxxxx" $env:FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx" $env:OPENCLAW_PORT="3000"

六、联调与验证

建议按以下链路验证：

启动 OpenClaw 服务
在飞书群内 @机器人 发送测试消息
检查 OpenClaw 终端日志是否收到事件
确认机器人是否正常回复

七、常见问题与排查（快速版）

1）机器人无回复

检查机器人是否已加入目标群聊
检查事件订阅是否保存成功
检查应用可见范围与发布状态

2）鉴权失败

核对 App ID / App Secret 是否有误
排查是否存在前后空格或旧密钥未更新

3）回调失败

推送模式下需保证回调地址公网可达
检查端口、防火墙、网关和证书配置

八、问题排查与卸载

这部分覆盖最常见的安装、运行、飞书接入问题，以及本地卸载回滚方法。

8.1 常见问题排查

1）命令找不到：`openclaw: command not found`

可能原因：

全局安装失败
npm 全局路径未加入 PATH

排查步骤：

# 检查是否全局安装成功 npm list -g --depth=0 | grep openclaw # 查看 npm 全局安装目录 npm root -g npm config get prefix

若未安装成功，重新安装：

npm i -g openclaw

2）Node 版本过低或不兼容

OpenClaw 依赖 Node.js 24+。先确认版本：

node -v

如果版本过低，升级 Node.js 后重试安装。

3）安装时报权限错误（EACCES）

常见于 macOS/Linux 全局安装。可使用以下两种方式：

# 方式 A：临时提升权限 sudo npm i -g openclaw # 方式 B：调整 npm 全局目录到用户目录（更推荐） mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm i -g openclaw

若使用 zsh，请把 .bashrc 改为 .zshrc。

4）飞书机器人收不到消息

优先检查：

应用是否已添加“机器人”能力
机器人是否已拉入群聊
事件与回调配置是否保存
订阅事件是否已添加
应用是否发布到可用范围

5）飞书鉴权失败（401 / 无权限）

常见原因：

App ID、App Secret 填写错误
使用了旧密钥（重置后未同步）
环境变量存在空格或引号问题

建议重新复制后再写入环境变量并重启服务。

6）端口被占用，服务启动失败

检查端口占用并更换端口：

# macOS / Linux：查看 3000 端口占用 lsof -i :3000 # Windows PowerShell：查看 3000 端口占用 netstat -ano | findstr 3000

修改端口后重启服务。

7）代理或网络导致依赖下载失败

可先切换 npm 镜像：

npm config set registry https://registry.npmmirror.com/

安装完成后如需恢复官方源：

npm config set registry https://registry.npmjs.org/

8.2 运行日志与诊断建议

建议保留三类日志：

OpenClaw 启动日志（是否启动成功）
渠道接入日志（飞书事件是否到达）
错误堆栈日志（鉴权、网络、权限）

排查优先级建议：

先看“是否启动成功”
再看“事件是否进来”
最后看“业务处理是否返回”

8.3 卸载 OpenClaw（按系统）

1）通用卸载（npm 全局安装）

# 卸载全局 openclaw npm uninstall -g openclaw

校验是否卸载成功：

openclaw --version # 如果提示 command not found，说明卸载完成

2）清理 npm 缓存（可选）

npm cache verify # 如需强制清理： npm cache clean --force

3）清理本地配置与数据（可选，谨慎）

# 以下为示例路径，请按你的实际安装目录调整 rm -rf ~/.openclaw rm -rf ~/.config/openclaw

Windows PowerShell 示例：

# 按实际目录删除 Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw" Remove-Item -Recurse -Force "$env:USERPROFILE\.config\openclaw"

注意：删除配置目录会清空本地配置与缓存，请先备份密钥和自定义配置。

8.4 飞书侧回滚（可选）

若你暂时不再使用飞书接入，可在飞书开放平台执行：

移除机器人能力（或停用应用）
删除事件订阅
重置 App Secret（防止旧配置继续生效）

8.5 一键“最小回滚”建议

如果只想恢复到“干净可重装”状态，建议执行：

卸载 openclaw
清理本地配置目录
保留 Node.js / Git（避免重复装环境）
重新按本文安装流程走一遍

结语

到这里，你已经完成了：

OpenClaw 本地环境搭建
OpenClaw 安装与初始化
飞书机器人能力开通
事件订阅与联调验证
常见问题排查与卸载回滚

⭐️推荐:

前言