OpenClaw本地部署完全指南：安装与飞书接入教程

前言

先说结论：OpenClaw这套终端式AI助手，确实有点意思。它支持多模型适配、多渠道接入，你可以在本地部署，也可以选择云端一键安装——实际部署下来你会发现，这套方案更适合跑在本机上。

• 官方官网：openclaw.ai/
• GitHub仓库：github.com/openclaw/op…
• 部署方式：本地部署（本文核心）、云端一键安装（阿里云/火山引擎/mini max均提供）、Docker镜像安装（需自行下载镜像）

下面这份文档，是本地部署 +飞书机器人接入的完整实操指南，适配macOS/Linux/Windows系统。从安装到配置、从调试到接入飞书，一条龙走完。

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

OpenClaw运行时需要Node.js 24+ 和 Git这两位老朋友。Node.js安装包自带npm，不用单独下载。各系统的安装步骤略有差异，但都不复杂——唯一要注意的是，Windows操作全程要以管理员身份打开PowerShell，否则有些步骤会卡住。

1. Node.js 安装

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

官方地址：nodejs.org/

• 选择LTS v24+（稳定）版本，页面会自动识别你的系统，直接下载对应安装包；
• 安装时默认选项即可，务必勾选Add to PATH，这样命令行里才能识别到。

方式2：包管理器安装（推荐开发人员，macOS/Linux）

• macOS需要先安装Homebrew，命令：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install node
brew link node --overwrite --force

国内镜像源加速（解决下载缓慢）

# 配置npm淘宝镜像
npm config set registry https://registry.npmmirror.com/

2. Git 安装

方式1：官方下载

官方地址：git-scm.com/

• 页面自动识别系统，Windows选64位版本，macOS/Linux选对应入口；
• 安装时务必勾选Add Git to PATH，新手保持默认选项即可。

方式2：包管理器安装（macOS/Linux）

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

3. 安装后验证（必做，确认环境生效）

打开命令行（Windows用PowerShell，macOS/Linux用终端），输入以下命令，能显示对应版本号即安装成功：

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

补充：Git安装后可配置全局用户信息（可选，避免部分git操作报错）

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

二、OpenClaw 安装步骤

1. macOS/Linux 系统

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

2. Windows 系统（PowerShell 管理员身份）

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

注意：macOS/Linux部分目录安装需要sudo权限，若出现权限错误，可在命令前加sudo。

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

安装完成后会自动进入交互式配置流程，按以下选项选择即可。部分配置后续可以在Web UI或终端修改——每个配置项后面附了说明，方便理解选择原因，不至于盲目点下一步。

四、OpenClaw 配置指南（适配Qwen模型）

配置的核心在于模型提供商。这里以免费的Qwen模型为例，提供两种配置方式：Web UI（可视化，推荐新手）和终端（配置文件，适合开发人员）。

前置准备

Qwen API Key获取地址：bailian.console.aliyun.com/cn-beijing/，后续配置需替换占位符。

方式一：Web UI 配置（可视化，推荐新手）

1. 打开Web UI

openclaw dashboard
打开后自动在浏览器弹出页面，若未弹出，手动访问本地地址即可。

2. 进入配置页面

左侧菜单栏依次选择：Settings → Config → Authentication → 页面底部选择Raw模式（纯文本编辑配置）。

3. 配置models.providers（Qwen模型核心配置）

替换原有内容，将替换为自己的Qwen API Key：

"models": {
"providers": {
"qwen-portal": {
"baseUrl": "https://portal.qwen.ai/v1",
"apiKey": "",
"api": "openai-completions",
"models": [
{
"id": "coder-model",
"name": "Qwen Coder",
"reasoning": false,
"input": ["text"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
},
{
"id": "vision-model",
"name": "Qwen Vision",
"reasoning": false,
"input": ["text", "image"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
}
]
}
}
}

4. 增加认证配置信息auth.profiles

"auth": {
"profiles": {
"qwen-portal:default": {
"provider": "qwen-portal",
"mode": "oauth"
}
}
}

5. 修改agents.defaults（默认模型与工作空间配置）

将<你的工作空间目录>替换为实际路径（macOS/Linux默认/Users/你的用户名/.openclaw/workspace，Windows默认C:Users你的用户名.openclawworkspace，目录不存在会自动创建）：

"agents": {
"defaults": {
"model": {
"primary": "qwen-portal/coder-model"
},
"models": {
"qwen-portal/coder-model": {
"alias": "qwen"
},
"qwen-portal/vision-model": {}
},
"workspace": "<你的工作空间目录>",
"compaction": {
"mode": "safeguard"
},
"maxConcurrent": 1,
"subagents": {
"maxConcurrent": 2
}
}
}

6. 配置命令黑名单（可选，禁止高风险命令）

添加在配置文件对应位置，防止机器人执行摄像头、录屏等高危操作：

"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"calendar.add",
"contacts.add",
"reminders.add"
]
}

7. 保存并生效配置

1. 点击页面右上角Sa ve保存配置；
2. 保存完成后点击Update更新配置；
3. 验证配置：终端执行openclaw config validate，无报错即配置正确。

方式二：终端配置（配置文件编辑，适合开发人员）

1. 打开配置文件

# macOS/Linux
nano ~/.openclaw/openclaw.json
# Windows（PowerShell）
notepad $HOME/.openclaw/openclaw.json

2. 完整配置模板

替换配置文件原有内容，需修改和<你的工作空间目录>，其他保持默认：

{
"meta": {
"lastTouchedVersion": "2026.2.25",
"lastTouchedAt": "2026-02-26T12:51:37.823Z"
},
"wizard": {
"lastRunAt": "2026-02-26T12:51:37.794Z",
"lastRunCommand": "doctor",
"lastRunVersion": "2026.2.25",
"lastRunMode": "local"
},
"auth": {
"profiles": {
"qwen-portal:default": {
"provider": "qwen-portal",
"mode": "oauth"
}
}
},
"models": {
"providers": {
"qwen-portal": {
"baseUrl": "https://portal.qwen.ai/v1",
"apiKey": "",
"api": "openai-completions",
"models": [
{
"id": "coder-model",
"name": "Qwen Coder",
"reasoning": false,
"input": ["text"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
},
{
"id": "vision-model",
"name": "Qwen Vision",
"reasoning": false,
"input": ["text", "image"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "qwen-portal/coder-model"
},
"models": {
"qwen-portal/coder-model": {
"alias": "qwen"
},
"qwen-portal/vision-model": {}
},
"workspace": "<你的工作空间目录>",
"compaction": {
"mode": "safeguard"
},
"maxConcurrent": 1,
"subagents": {
"maxConcurrent": 2
}
}
},
"messages": {
"ackReactionScope": "group-mentions"
},
"commands": {
"native": "auto",
"nativeSkills": "auto",
"restart": true,
"ownerDisplay": "raw"
},
"session": {
"dmScope": "per-channel-peer"
},
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback",
"auth": {
"mode": "token",
"token": "__OPENCLAW_REDACTED__"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"nodes": {
"denyCommands": [
"camera.snap",
"camera.clip",
"screen.record",
"calendar.add",
"contacts.add",
"reminders.add"
]
}
}
}

3. 保存并退出编辑器

• nano编辑器（macOS/Linux）：按Ctrl + O保存 → 按Enter确认 → 按Ctrl + X退出；
• 记事本（Windows）：直接点击保存并关闭。

4. 验证配置并重启服务

# 验证配置是否正确
openclaw config validate
# 重启网关使配置生效
openclaw gateway restart

五、OpenClaw 基础使用

支持Web UI 和 TUI（终端界面）两种交互方式，核心功能一致，按自己的习惯选择就行。

方式一：Web UI 交互（可视化，推荐）

# 启动Web UI，自动在浏览器打开
openclaw dashboard

• 核心功能：Chat对话、模型配置、渠道管理、插件管理；
• 关键页面：Chat（AI对话）、Settings（配置）、Plugins（插件）。

方式二：TUI 终端交互（轻量，无需浏览器）

# 启动TUI终端界面
openclaw tui

TUI 常用命令（输入后按回车执行）

/status # 查看网关状态（核心，确认服务是否运行）
/help # 查看所有常用命令
/exit # 退出TUI界面
/model # 切换AI模型

状态正常标准：/status显示Runtime: running、RPC probe: success，无任何错误提示。

六、接入飞书机器人

完成OpenClaw基础配置后，就可以接入飞书机器人在飞书里实现AI对话了。整个过程分四步：安装飞书插件、创建飞书应用、配置OpenClaw飞书参数、配置飞书机器人权限。

前置准备

飞书开放平台入口：open.feishu.cn

步骤一：安装OpenClaw飞书插件

提供3种安装方式，按顺序尝试，方式1失败则用方式2/3。

方式1：官方命令安装（推荐）

openclaw plugins install @m1heng-clawd/feishu

方式2：手动下载安装（方式1失败时）

# 1. 下载插件包到当前目录
curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.3.tgz
# 2. 从本地安装插件
openclaw plugins install ./feishu-0.1.3.tgz

方式3：OpenClaw自动安装

在TUI/Web UI的Chat界面发送以下内容，替换和（后续创建飞书应用后获取）：

帮我安装飞书插件：https://github.com/AlexAnys/openclaw-feishu
我的飞书应用配置信息如下：
App ID:
App Secret:

OpenClaw会自动完成安装、配置、重启。

方式4：回到 openclaw config 自行选择 feishu 插件进行安装（新版支持，最便捷）

步骤二：在飞书开放平台创建企业自建应用

1. 飞书开放平台登录后，点击右上角开发者后台；
2. 点击创建企业自建应用，填写应用名称（如OpenClaw机器人）、应用描述（可选），点击创建；

3.应用创建后，进入基础信息 → 凭证与基础信息，记录App ID和App Secret（后续配置需用）；

4.关键补充：进入测试企业和人员，添加测试人员/测试群组（发布前仅测试对象可使用机器人，避免企业审核驳回）。

步骤三：在OpenClaw中配置飞书参数

终端执行以下命令，将和替换为飞书应用的实际信息，命令逐行执行：（上述方式3和方式4不需要执行该参数配置，方式3自主配置，方式4界面选择）

# 配置飞书App ID
openclaw config set channels.feishu.appId ""
# 配置飞书App Secret
openclaw config set channels.feishu.appSecret ""
# 启用飞书渠道
openclaw config set channels.feishu.enabled true
# 配置长连接模式（飞书推荐）
openclaw config set channels.feishu.connectionMode websocket
# 单聊策略为配对授权
openclaw config set channels.feishu.dmPolicy pairing
# 群聊策略为白名单
openclaw config set channels.feishu.groupPolicy allowlist
# 群聊需@机器人才响应
openclaw config set channels.feishu.requireMention true

配置完成后重启网关：

openclaw gateway restart

步骤四：配置飞书机器人权限与事件订阅

回到飞书开发者后台的当前应用页面，按以下步骤配置，每一步均需保存：

1. 添加机器人能力：左侧菜单栏应用能力 → 添加应用能力，点击机器人卡片的添加；
2. 完善机器人说明：机器人配置区域，点击「如何开始使用」旁的编辑按钮，添加简单说明（如“OpenClaw AI机器人，输入问题即可解答”）；
3. 配置事件订阅：左侧菜单栏开发配置 → 事件与回调，订阅方式选择「使用长连接接收事件」并保存；

3.添加接收消息事件：点击添加事件，搜索im.message.receive_v1，添加该事件并确认开通对应权限；

4. 开通核心权限：左侧菜单栏开发配置 → 权限管理

• • 「应用身份权限」：搜索im:message，全部选中并开通；
  • 「用户身份权限」：搜索contact:user.base:readonly，选中并开通；

6. 创建版本并发布：点击页面顶部应用发布 → 版本管理与发布，创建新版本，填写更新说明后申请线上发布（企业自建应用发布后无需平台审核，直接生效）。

七、飞书机器人配对授权（最后一步，实现对话）

飞书机器人配置完成后，还需要完成配对授权才能正常收发消息。没授权的时候发消息会提示权限错误——这是很多人会卡住的一步，注意了。

步骤1：获取配对码

在飞书向配置的机器人发送任意消息（如“测试”），机器人会回复包含配对码的提示，格式如下：

OpenClaw: access not configured.
Your Feishu user id: ou_fxxxxxx
Pairing code: xxxx
Ask the bot owner to approve with: openclaw pairing approve feishu xxxx

步骤2：终端执行配对命令

复制回复中的配对命令，替换xxxx为实际配对码，在终端执行：

openclaw pairing approve feishu xxxx

配对成功：终端输出Pairing approved successfully。

步骤3：重启网关使授权生效

openclaw gateway restart

步骤4：验证授权是否成功

再次在飞书向机器人发送消息（如“你好”），机器人能正常响应即授权成功。

• 若仍提示权限问题，等待2-3分钟再试（飞书权限同步有延迟）；
• 群聊中需 @机器人 才能响应，单聊可直接发送消息。

补充：Web UI中会显示两个会话：main（本地基础会话）、fe-xxx（飞书会话），可自由切换查看。

八、问题排查与卸载

（一）自诊断与问题修复

OpenClaw自带诊断工具，可以自动修复大部分配置问题——优先执行以下命令：

# 1. 自动诊断并修复配置
openclaw doctor --fix
# 2. 重启网关
openclaw gateway restart
# 3. 检查网关状态，确认无错误
openclaw gateway status

状态正常标准

1. 无Config invalid（配置无效）错误；
2. gateway status显示Runtime: running、RPC probe: success；
3. 无Unrecognized key（未知配置项）、Invalid input（无效输入）提示。

常见问题排查

1. 网关启动失败（端口18789占用）

# 查看端口占用进程
lsof -i:18789 # macOS/Linux
netstat -ano | findstr "18789" # Windows
# 杀死占用进程（替换PID为实际进程号）
kill -9 PID # macOS/Linux
taskkill /F /PID PID # Windows
# 或修改OpenClaw网关端口
openclaw config set agents.gateway.port 18788
openclaw gateway restart

2. 飞书机器人无响应（长连接未建立）：重新安装飞书插件 → 重启网关 → 检查飞书事件订阅是否为「长连接模式」。
3. 模型调用失败：检查Qwen API Key是否正确 → 验证网络是否能访问 → 重启网关。

（二）彻底卸载OpenClaw（全清理，无残留）

若需卸载，执行以下命令，仅杀死OpenClaw相关进程，不影响其他Node.js应用。

macOS/Linux 卸载

# 1. 停止网关服务
openclaw gateway stop
# 2. 卸载全局npm包
npm uninstall -g openclaw
# 3. 删除配置、插件、缓存目录
rm -rf ~/.openclaw
rm -rf /tmp/openclaw
# 4. 删除macOS启动项
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 5. 删除Linux启动项（systemd）
sudo rm -f /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload
# 6. 精准杀死OpenClaw相关进程（仅杀死本应用，不影响其他Node服务）
pkill -f "node.*openclaw"
pkill -f openclaw

Windows 卸载（PowerShell管理员）

# 1. 停止网关服务
openclaw gateway stop
# 2. 卸载全局npm包
npm uninstall -g openclaw
# 3. 删除配置、插件、缓存目录
Remove-Item -Recurse -Force $HOME/.openclaw
Remove-Item -Recurse -Force $env:TMP/openclaw
# 4. 精准杀死OpenClaw相关进程
taskkill /F /IM node.exe /FI "WINDOWTITLE eq openclaw"
taskkill /F /IM openclaw.exe

九、附录

附录1：常用OpenClaw命令（速查）

# 服务管理
openclaw gateway start # 启动网关
openclaw gateway stop # 停止网关
openclaw gateway restart # 重启网关
openclaw gateway status # 查看网关状态
# 配置管理
openclaw config validate # 验证配置
openclaw config set # 设置配置项
# 插件管理
openclaw plugins list # 查看已安装插件
openclaw plugins install <插件地址> # 安装插件
openclaw plugins uninstall <插件名> # 卸载插件
# 诊断与修复
openclaw doctor # 诊断问题
openclaw doctor --fix # 诊断并修复
# 交互方式
openclaw dashboard # 启动Web UI
openclaw tui # 启动TUI终端
# 飞书配对
openclaw pairing approve feishu <配对码> # 飞书授权

附录2：常见问题FAQ

1. Q：安装时提示curl/wget缺失？
   A：macOS安装curl：brew install curl；Linux安装：sudo apt install curl wget；Windows需安装Git Bash（自带curl）。
2. Q：配置文件修改后不生效？
   A：执行openclaw config validate验证配置 → 执行openclaw gateway restart重启网关。
3. Q：飞书机器人发布后企业内无法使用？
   A：飞书开发者后台「测试企业和人员」中添加企业所有成员 → 重新发布版本。
4. Q：TUI/Web UI无法启动？
   A：检查Node.js版本是否为v22+ → 执行openclaw doctor --fix → 重启网关。