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)"）

css 复制代码

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

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

arduino 复制代码

# 配置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）

bash 复制代码

# 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/终端），输入以下命令，能显示对应版本号即安装成功：

bash 复制代码

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

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

arduino 复制代码

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

二、OpenClaw 安装步骤

1. macOS/Linux 系统

less 复制代码

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

npm i -g openclaw

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

arduino 复制代码

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

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

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

安装完成后自动进入交互式配置流程，按以下选项选择即可，部分配置可后续在Web UI/终端修改，配置项后附简单说明，方便理解选择原因：

配置项	选择/操作	配置说明
I understand this is powerful and inherently risky. Continue?	选择 "Yes"	确认知晓风险并继续部署
Onboarding mode	选择 "QuickStart"	快速启动模式，适合新手，简化配置
Model/auth provider	选免费Qwen / 选"Skip for now"	推荐先选Qwen（免费），后续可配置火山引擎等其他模型；暂不配置则选Skip
Filter models by provider	选择 "All providers"	显示所有模型提供商，方便后续切换
Default model	使用默认配置	保持默认，后续可在配置文件中修改
Select channel (QuickStart)	选择 "Skip for now"	暂不配置渠道，后续专门配置飞书渠道
Configure skills now? (recommended)	选择 "No"	暂不配置技能，后续按需添加
Enable hooks?	按空格键选中 → 按回车键下一步	启用钩子功能，支持命令日志、会话记忆等核心特性
How do you want to hatch your bot?	选择 "Hatch in TUI"	从终端界面启动机器人，基础交互更便捷

四、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>替换为自己的Qwen API Key：

json 复制代码

"models": {
  "providers": {
    "qwen-portal": {
      "baseUrl": "https://portal.qwen.ai/v1",
      "apiKey": "<QWEN_API_KEY>",
      "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`

css 复制代码

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

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

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

json 复制代码

"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. 配置命令黑名单（可选，禁止高风险命令）

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

json 复制代码

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

7. 保存并生效配置

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

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

1. 打开配置文件

bash 复制代码

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

2. 完整配置模板

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

json 复制代码

{
  "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": "<QWEN_API_KEY>",
        "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. 验证配置并重启服务

bash 复制代码

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

五、OpenClaw 基础使用

支持Web UI 和 TUI（终端界面） 两种交互方式，可根据需求选择，核心功能一致。

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

bash 复制代码

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

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

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

bash 复制代码

# 启动TUI终端界面
openclaw tui

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

bash 复制代码

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

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

六、接入飞书机器人

完成OpenClaw基础配置后，接入飞书机器人实现飞书内AI对话，分为安装飞书插件、创建飞书应用、配置OpenClaw飞书参数、配置飞书机器人权限四步。

前置准备

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

步骤一：安装OpenClaw飞书插件

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

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

bash 复制代码

openclaw plugins install @m1heng-clawd/feishu

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

bash 复制代码

# 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界面发送以下内容，替换<App ID>和<App Secret>（后续创建飞书应用后获取）：

bash 复制代码

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

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

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

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

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

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

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

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

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

arduino 复制代码

# 配置飞书App ID
openclaw config set channels.feishu.appId "<App ID>"
# 配置飞书App Secret
openclaw config set channels.feishu.appSecret "<App Secret>"
# 启用飞书渠道
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

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

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

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

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

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

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

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

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

飞书机器人配置完成后，需完成配对授权才能实现消息响应，未授权时发送消息会提示权限错误。

步骤1：获取配对码

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

vbnet 复制代码

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自带诊断工具，可自动修复大部分配置问题，优先执行以下命令：

bash 复制代码

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

状态正常标准

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

常见问题排查

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

bash 复制代码

# 查看端口占用进程
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

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

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

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

macOS/Linux 卸载

bash 复制代码

# 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管理员）

ruby 复制代码

# 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命令（速查）

bash 复制代码

# 服务管理
openclaw gateway start  # 启动网关
openclaw gateway stop   # 停止网关
openclaw gateway restart# 重启网关
openclaw gateway status # 查看网关状态
# 配置管理
openclaw config validate # 验证配置
openclaw config set <key> <value> # 设置配置项
# 插件管理
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

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

OpenClaw 完整本地部署安装与使用指南（接入飞书）

前言

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

1. Node.js 安装

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

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

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

2. Git 安装

方式1：官方下载

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

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

二、OpenClaw 安装步骤

1. macOS/Linux 系统

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

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

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

前置准备

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

1. 打开Web UI

2. 进入配置页面

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

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

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

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

7. 保存并生效配置

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

1. 打开配置文件

2. 完整配置模板

3. 保存并退出编辑器

4. 验证配置并重启服务

五、OpenClaw 基础使用

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

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

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

六、接入飞书机器人

前置准备

步骤一：安装OpenClaw飞书插件

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

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

方式3：OpenClaw自动安装

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

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

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

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

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

步骤1：获取配对码

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

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

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

八、问题排查与卸载

（一）自诊断与问题修复（安装/配置/使用中报错）

状态正常标准

常见问题排查

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

macOS/Linux 卸载

Windows 卸载（PowerShell管理员）

九、附录

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

附录2：常见问题FAQ

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

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

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