OpenClaw + 飞书机器人完整安装配置指南

> 🦞 OpenClaw 是一个个人 AI 助手，可以部署在本地并通过飞书等平台与你对话。本文档将带你从零开始完成安装、配置和调试。

**适用人群**：技术小白也能看懂的详细指南  

**预计时间**：30-60 分钟  

**系统要求**：macOS / Linux / Windows (WSL2)

---

## 📋 目录

1. [环境准备](#1-环境准备)

2. [安装 OpenClaw](#2-安装-openclaw)

3. [配置 Qwen 模型](#3-配置-qwen-模型)

4. [配置飞书机器人](#4-配置飞书机器人)

5. [启动 Gateway](#5-启动-gateway)

6. [测试与调试](#6-测试与调试)

7. [常见问题](#7-常见问题)

---

## 1. 环境准备

### 1.1 检查 Node.js 版本

OpenClaw 需要 **Node.js ≥ 22.16.0**。

```bash

node --version

```

如果版本低于 22.16.0，需要升级：

#### macOS 升级 Node.js

```bash

# 使用 n 工具升级（推荐）

npx n latest

# 升级后验证

node --version  # 应显示 v22.16.0 或更高

```

#### 或者使用官方安装包

访问 [Node.js 官网](https://nodejs.org/) 下载最新 LTS 版本安装。

### 1.2 安装 pnpm

pnpm 是推荐的包管理器：

```bash

npm install -g pnpm

pnpm --version  # 验证安装

```

---

## 2. 安装 OpenClaw

### 2.1 克隆项目

```bash

cd ~

git clone https://github.com/openclaw/openclaw.git

cd openclaw

```

### 2.2 安装依赖

```bash

pnpm install

```

安装过程约需 5-10 分钟，请耐心等待。

### 2.3 构建项目

```bash

pnpm build

```

构建成功后会显示 `Done` 字样。

---

## 3. 配置 Qwen 模型

### 3.1 获取阿里云 DashScope API Key

1. 访问 [阿里云百炼平台](https://bailian.console.aliyun.com/)

2. 登录阿里云账号

3. 进入 **API-KEY 管理** 页面

4. 点击 **创建新的 API-KEY**

5. 复制生成的 API Key（格式：`sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`）

> 💰 **费用说明**：新用户有免费额度，qwen3.5-plus 约 0.002 元/千 tokens

### 3.2 创建配置文件

创建配置目录：

```bash

mkdir -p ~/.openclaw

```

创建配置文件 `~/.openclaw/openclaw.json`：

```bash

cat > ~/.openclaw/openclaw.json << 'EOF'

{

  "gateway": {

    "mode": "local",

    "auth": {

      "mode": "token",

      "token": "openclaw-dev-token-2026"

    },

    "bind": "loopback",

    "port": 18789

  },

  "env": {

    "MODELSTUDIO_API_KEY": "sk-你的 API_KEY_替换这里"

  },

  "models": {

    "providers": {

      "modelstudio": {

        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",

        "api": "openai-completions",

        "models": [

          {

            "id": "qwen3.5-plus",

            "name": "qwen3.5-plus",

            "reasoning": false,

            "input": ["text", "image"],

            "contextWindow": 1000000,

            "maxTokens": 65536

          }

        ]

      }

    }

  },

  "agents": {

    "defaults": {

      "model": "modelstudio/qwen3.5-plus"

    }

  },

  "browser": {

    "enabled": true,

    "color": "#FF4500"

  }

}

EOF

```

> ⚠️ **重要**：将 `sk-你的 API_KEY_替换这里` 替换为你实际的 API Key

### 3.3 验证模型配置

```bash

cd ~/openclaw

/Users/qiwen/.n/bin/node dist/index.js models status

```

应显示 `modelstudio effective=env:sk-xxx` 表示配置成功。

---

## 4. 配置飞书机器人

### 4.1 创建飞书应用

1. 访问 [飞书开放平台](https://open.feishu.cn/app)

2. 点击 **创建企业应用**

3. 填写应用信息：

   - 应用名称：例如 "OpenClaw 助手"

   - 应用图标：可选

4. 点击 **创建**

### 4.2 获取应用凭证

1. 进入创建的应用

2. 点击 **凭证与基础信息**

3. 复制以下信息：

   - **App ID**（格式：`cli_xxx`）

   - **App Secret**

> ⚠️ **重要**：App Secret 只显示一次，请妥善保存！

### 4.3 配置应用权限

在 **权限管理** 页面：

1. 点击 **批量导入**

2. 粘贴以下 JSON：

```json

{

  "scopes": {

    "tenant": [

      "im:message",

      "im:message:send_as_bot",

      "im:message.group_at_msg:readonly",

      "im:message.p2p_msg:readonly",

      "im:message:readonly",

      "im:chat.access_event.bot_p2p_chat:read",

      "im:chat.members:bot_access"

    ],

    "user": []

  }

}

```

3. 点击 **申请权限** 并 **开通**

### 4.4 启用机器人功能

1. 点击 **应用功能** > **机器人**

2. 开启 **机器人** 开关

3. 设置机器人名称和头像

4. 点击 **保存**

### 4.5 配置事件订阅

1. 点击 **事件订阅**

2. 选择 **使用长连接接收事件** (WebSocket)

3. 点击 **添加事件**

4. 搜索并添加：`im.message.receive_v1`

5. 点击 **保存**

### 4.6 发布应用

1. 点击 **版本管理与发布**

2. 点击 **创建版本**

3. 填写版本号（如 1.0.0）和更新说明

4. 点击 **提交发布**

5. 等待审核（通常自动通过）

### 4.7 配置 OpenClaw 飞书集成

编辑 `~/.openclaw/openclaw.json`，添加飞书配置：

```json

{

  "channels": {

    "feishu": {

      "enabled": true,

      "appId": "你的 App_ID_替换这里",

      "appSecret": "你的 App_Secret_替换这里",

      "domain": "feishu",

      "connectionMode": "websocket",

      "dmPolicy": "pairing"

    }

  }

}

```

> ⚠️ **重要**：替换 `appId` 和 `appSecret` 为你的实际值

完整配置文件示例：

```json

{

  "gateway": {

    "mode": "local",

    "auth": {

      "mode": "token",

      "token": "openclaw-dev-token-2026"

    },

    "bind": "loopback",

    "port": 18789

  },

  "env": {

    "MODELSTUDIO_API_KEY": "sk-你的 API_KEY"

  },

  "models": {

    "providers": {

      "modelstudio": {

        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",

        "api": "openai-completions",

        "models": [

          {

            "id": "qwen3.5-plus",

            "name": "qwen3.5-plus",

            "reasoning": false,

            "input": ["text", "image"],

            "contextWindow": 1000000,

            "maxTokens": 65536

          }

        ]

      }

    }

  },

  "channels": {

    "feishu": {

      "enabled": true,

      "appId": "cli_xxxx",

      "appSecret": "xxxx",

      "domain": "feishu",

      "connectionMode": "websocket",

      "dmPolicy": "pairing"

    }

  },

  "agents": {

    "defaults": {

      "model": "modelstudio/qwen3.5-plus"

    }

  },

  "browser": {

    "enabled": true,

    "color": "#FF4500"

  }

}

```

---

## 5. 启动 Gateway

Gateway 是 OpenClaw 的核心服务，负责处理消息和 AI 对话。

### 5.1 启动 Gateway

```bash

cd ~/openclaw

/Users/qiwen/.n/bin/node dist/index.js gateway --port 18789

```

启动成功后，终端会显示 Gateway 运行信息。

> 💡 **提示**：保持此终端窗口打开，Gateway 需要持续运行

### 5.2 验证 Gateway 状态

打开新终端窗口，运行：

```bash

lsof -i :18789

```

应显示端口 18789 正在监听。

---

## 6. 测试与调试

### 6.1 命令行测试

在飞书配置前，可以先通过命令行测试 AI：

```bash

cd ~/openclaw

/Users/qiwen/.n/bin/node dist/index.js agent --session-id test001 --message "你好，请介绍一下你自己"

```

应看到 AI 回复内容。

### 6.2 飞书消息测试

1. 打开飞书 App

2. 搜索你的机器人名称

3. 点击进入聊天窗口

4. 发送消息："你好"

### 6.3 处理配对请求（重要！）

首次收到消息时，由于安全设置，需要管理员批准：

```bash

# 查看配对请求

cd ~/openclaw

/Users/qiwen/.n/bin/node dist/index.js pairing list

# 批准配对（替换 CODE 为实际配对码）

/Users/qiwen/.n/bin/node dist/index.js pairing approve feishu CODE

```

### 6.4 查看消息记录

```bash

# 查看会话列表

/Users/qiwen/.n/bin/node dist/index.js sessions

# 查看配对记录

cat ~/.openclaw/credentials/feishu-pairing.json

# 查看允许列表

cat ~/.openclaw/credentials/feishu-default-allowFrom.json

```

---

## 7. 常见问题

### 7.1 机器人不回复消息

**问题**：发送消息后机器人没有回复

**排查步骤**：

1. **检查配对状态**

   ```bash

   /Users/qiwen/.n/bin/node dist/index.js pairing list

   ```

   如有待批准请求，执行批准命令

2. **检查 Gateway 是否运行**

   ```bash

   lsof -i :18789

   ```

   如无输出，重启 Gateway

3. **检查飞书权限**

   - 访问 https://open.feishu.cn/app/你的 AppID

   - 确认已添加 `im:message` 和 `im:message:send_as_bot` 权限

   - 确认应用已发布

4. **查看会话记录**

   ```bash

   cat ~/.openclaw/agents/main/sessions/*.jsonl | tail -50

   ```

   查看消息是否到达和 AI 是否生成回复

### 7.2 API Key 无效（401 错误）

**错误信息**：`HTTP 401: invalid access token or token expired`

**解决方案**：

1. 确认 API Key 正确（无多余空格）

2. 确认使用正确的 endpoint：

   ```json

   "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"

   ```

3. 在阿里云百炼平台确认 API Key 状态正常

4. 确认账户有可用额度

### 7.3 飞书权限错误（400 错误）

**错误信息**：`Access denied. One of the following scopes is required`

**解决方案**：

1. 访问飞书开放平台权限申请链接（错误信息中提供）

2. 添加所需权限

3. **发布应用**（必须步骤！）

4. 等待 1-2 分钟生效

### 7.4 Node.js 版本过低

**错误信息**：`openclaw requires Node >=22.16.0`

**解决方案**：

```bash

# 使用 n 升级

npx n latest

# 或使用官方安装包

# 访问 https://nodejs.org/ 下载最新版

```

### 7.5 Gateway 无法启动

**可能原因**：

- 端口被占用

- 配置文件格式错误

**解决方案**：

```bash

# 检查端口占用

lsof -i :18789

# 如有占用，停止旧进程

pkill -f "openclaw-gateway"

# 验证配置文件

cat ~/.openclaw/openclaw.json | python -m json.tool

```

### 7.6 消息已读但无回复

查看会话记录确认 AI 是否生成回复：

```bash

# 查看最新会话

ls -lt ~/.openclaw/agents/main/sessions/*.jsonl | head -3

# 查看会话内容

tail -20 ~/.openclaw/agents/main/sessions/最新会话文件.jsonl

```

如 AI 已生成回复但未发送，检查飞书权限配置。

---

## 📚 参考资源

- [OpenClaw 官方文档](https://docs.openclaw.ai)

- [飞书开放平台](https://open.feishu.cn)

- [阿里云百炼平台](https://bailian.console.aliyun.com)

- [Node.js 下载](https://nodejs.org)

---

## 🎉 完成！

恭喜你成功配置 OpenClaw + 飞书机器人！现在你可以：

- 在飞书中与 AI 助手对话

- 通过命令行测试各种功能

- 配置更多聊天渠道（Telegram、Discord 等）

- 开发和添加自定义技能

如有问题，欢迎查阅官方文档或提交 Issue。🦞