OpenClaw 完整本地部署安装与使用指南 手把手接入飞书机器人

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

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

1. 进入配置页面

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

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

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

"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
        }
      ]
    }
  }
}

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

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

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

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

"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
    }
  }
}

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

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

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

1. 保存并生效配置

点击页面右上角Save保存配置；
保存完成后点击Update更新配置；
验证配置：

openclaw config validate

无报错即配置正确。

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

1. 打开配置文件

# macOS/Linux
nano ~/.openclaw/openclaw.json

# Windows（PowerShell）
notepad $HOME/.openclaw/openclaw.json

1. 完整配置模板

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

{
  "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"
        ]
      }
    }
  }
}

1. 保存并退出编辑器

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

1. 验证配置并重启服务

# 验证配置是否正确
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界面发送以下内容，替换<App ID>和<App Secret>：

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

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

方式4：界面选择安装

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

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

1. 飞书开放平台登录后，点击右上角开发者后台；
2. 点击创建企业自建应用，填写应用名称、应用描述，点击创建；
3. 进入基础信息 → 凭证与基础信息，记录App ID和App Secret；
4. 进入测试企业和人员，添加测试人员/测试群组。

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

终端执行以下命令，替换<App ID>和<App Secret>：

# 配置飞书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

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

1. 应用能力 → 添加机器人卡片；
2. 完善机器人使用说明；
3. 事件与回调选择「使用长连接接收事件」；
4. 添加事件 im.message.receive_v1 并开通权限；
5. 权限管理开通 im:message、contact:user.base:readonly；
6. 应用发布 → 创建版本并发布生效。

七、飞书机器人配对授权

步骤1：获取配对码

在飞书向机器人发送任意消息，会收到配对提示。

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

openclaw pairing approve feishu xxxx

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

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

openclaw gateway restart

步骤4：验证授权

再次发送消息能正常回复即配置完成。

八、问题排查与卸载

（一）自诊断与问题修复

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

常见问题排查

1. 网关端口18789占用

# macOS/Linux 查看端口
lsof -i:18789
# Windows 查看端口
netstat -ano | findstr "18789"

# 杀死进程 macOS/Linux
kill -9 PID
# Windows
taskkill /F /PID PID

# 修改网关端口
openclaw config set agents.gateway.port 18788
openclaw gateway restart

1. 飞书机器人无响应：重装插件 → 重启网关 → 核对长连接配置。
2. 模型调用失败：核对API Key、检查网络、重启网关。

（二）彻底卸载OpenClaw

macOS/Linux 卸载

# 停止网关服务
openclaw gateway stop
# 卸载全局npm包
npm uninstall -g openclaw
# 删除配置缓存
rm -rf ~/.openclaw
rm -rf /tmp/openclaw
# 删除macOS启动项
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# 删除Linux systemd服务
sudo rm -f /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload
# 杀死相关进程
pkill -f "node.*openclaw"
pkill -f openclaw

Windows 卸载（PowerShell管理员）

# 停止网关服务
openclaw gateway stop
# 卸载全局npm包
npm uninstall -g openclaw
# 删除配置缓存
Remove-Item -Recurse -Force $HOME/.openclaw
Remove-Item -Recurse -Force $env:TMP/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 <key> <value>

# 插件管理
openclaw plugins list
openclaw plugins install <插件地址>
openclaw plugins uninstall <插件名>

# 诊断与修复
openclaw doctor
openclaw doctor --fix

# 交互方式
openclaw dashboard
openclaw tui

# 飞书配对
openclaw pairing approve feishu <配对码>

附录2：常见问题FAQ

Q：安装时提示curl/wget缺失？
A：macOS执行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版本≥v24，执行openclaw doctor --fix修复后重启服务。

优质API服务推荐

在使用OpenClaw本地部署过程中，除了自带模型外，搭配KoalaAPI使用体验极佳，非常适合个人及小型团队接入多模型调用。

KoalaAPI 完美兼容OpenClaw的OpenAI接口协议格式，无需额外修改配置即可直接接入；聚合了主流大模型接口，响应速度稳定、延迟低，计费性价比高，支持按量计费无门槛使用。同时适配本地私有化部署的OpenClaw终端调用、飞书机器人模型对话等场景，省去自行申请各大模型官方密钥的繁琐流程，是搭配OpenClaw搭建本地AI助手、企业内部智能机器人的优选API服务。