# 📖 OpenClaw 对接企业钉钉&飞书配置教程

**版本**: v1.0  
**创建时间**: 2026-04-04  
**创建者**: 虾子 AI  
**适用**: 轻程智能科技工作室

---

## 📋 目录

1. [概述](#概述)
2. [钉钉集成配置](#钉钉集成配置)
3. [飞书集成配置](#飞书集成配置)
4. [对比总结](#对比总结)
5. [常见问题](#常见问题)
6. [最佳实践](#最佳实践)

---

## 概述

### 支持情况

| 平台 | OpenClaw 支持 | 插件状态 | 难度 |
|------|--------------|----------|------|
| **钉钉** | ✅ 支持 | 官方插件 | ⭐⭐⭐⭐ |
| **飞书** | ✅ 支持 | 官方插件 | ⭐⭐⭐⭐ |
| **企业微信** | ✅ 支持 | 官方插件 | ⭐⭐⭐ |

### 选择建议

| 场景 | 推荐平台 | 理由 |
|------|----------|------|
| **已有钉钉** | 钉钉 | 无需切换 |
| **已有飞书** | 飞书 | 无需切换 |
| **中小企业** | 企业微信 | 与微信互通 |
| **科技公司** | 飞书 | 功能强大 |
| **传统企业** | 钉钉 | 普及率高 |

---

## 钉钉集成配置

### 准备工作

```
□ 钉钉企业管理员账号
□ 钉钉开放平台账号
□ 企业 ID (CorpId)
□ 应用凭证 (AppKey/AppSecret)
□ 服务器公网 IP: 118.25.113.60
□ 域名：qingcheng.work (可选)
```

### 创建钉钉应用

#### 步骤 1: 登录钉钉开放平台

```
网址：https://open-dev.dingtalk.com/
登录：使用钉钉管理员扫码
```

#### 步骤 2: 创建企业内部应用

```
1. 进入"应用开发" → "企业内部开发"
2. 点击"创建应用"
3. 填写信息：
   - 应用名称：轻程智能助手
   - 应用图标：上传 Logo
   - 应用描述：AI 智能助手
4. 点击"创建"
```

#### 步骤 3: 获取应用凭证

```
1. 进入应用管理页面
2. 查看"凭证与基础信息"
3. 记录：
   - Client ID (AppKey)
   - Client Secret (AppSecret)
   - CorpId (企业 ID)
```

### 配置应用权限

#### 需要开通的权限

```
□ 发送工作通知消息
□ 接收消息回调
□ 读取用户信息
□ 发送群消息
□ 文件上传下载
```

### 配置回调地址

#### 步骤 1: 准备回调 URL

```
回调地址格式：
http://118.25.113.60:26106/dingtalk/callback

或 (有域名后)：
https://qingcheng.work/dingtalk/callback
```

#### 步骤 2: 配置事件订阅

```
1. 进入"事件订阅"
2. 点击"添加事件"
3. 选择事件：
   - 接收消息
   - 用户添加/删除
   - 群会话创建
4. 输入回调 URL
5. 输入 Token (自定义)
6. 输入 EncodingAESKey (自动生成)
7. 保存
```

### OpenClaw 配置

#### 步骤 1: 安装钉钉插件

```bash
# 检查插件
openclaw plugins list | grep dingtalk

# 如未安装
npm install -y @openclaw/dingtalk
```

#### 步骤 2: 配置钉钉通道

```bash
# 创建配置文件
nano ~/.openclaw/channels/dingtalk.json

# 配置内容：
{
  "id": "dingtalk",
  "name": "钉钉",
  "enabled": true,
  "corpId": "您的 CorpId",
  "clientId": "您的 Client ID",
  "clientSecret": "您的 Client Secret",
  "token": "事件订阅 Token",
  "encodingAesKey": "事件订阅 AES Key",
  "callbackUrl": "http://118.25.113.60:26106/dingtalk/callback"
}
```

#### 步骤 3: 重启 Gateway

```bash
openclaw gateway restart
```

#### 步骤 4: 验证连接

```bash
# 查看日志
tail -f ~/.openclaw/logs/gateway.log | grep dingtalk

# 查看通道状态
openclaw channels status
```

### 测试钉钉消息

#### 发送测试消息

```bash
openclaw message send \
  --channel dingtalk \
  --target "用户 ID 或群 ID" \
  --message "测试消息：轻程智能助手已连接"
```

---

## 飞书集成配置

### 准备工作

```
□ 飞书企业管理员账号
□ 飞书开放平台账号
□ 应用 ID (AppId)
□ 应用密钥 (AppSecret)
□ 验证 Token
□ 加密密钥 (EncryptKey)
□ 服务器公网 IP: 118.25.113.60
```

### 创建飞书应用

#### 步骤 1: 登录飞书开放平台

```
网址：https://open.feishu.cn/
登录：使用飞书管理员扫码
```

#### 步骤 2: 创建企业自建应用

```
1. 进入"应用开发" → "企业自建应用"
2. 点击"创建应用"
3. 填写信息：
   - 应用名称：轻程智能助手
   - 应用图标：上传 Logo
   - 应用描述：AI 智能助手
4. 点击"创建"
```

#### 步骤 3: 获取应用凭证

```
1. 进入应用管理页面
2. 查看"凭证与基础信息"
3. 记录：
   - App ID
   - App Secret
```

### 配置应用权限

#### 需要开通的权限

```
□ 发送消息
□ 接收消息
□ 读取用户信息
□ 发送群消息
□ 文件上传下载
□ 机器人功能
```

### 配置事件订阅

#### 步骤 1: 配置订阅地址

```
订阅地址格式：
http://118.25.113.60:26106/feishu/event

或 (有域名后)：
https://qingcheng.work/feishu/event
```

#### 步骤 2: 添加事件

```
1. 进入"事件订阅"
2. 开启"启用事件订阅"
3. 输入订阅地址
4. 输入验证 Token (自定义)
5. 输入加密密钥 (EncryptKey)
6. 添加事件：
   - 接收消息
   - 用户变更
   - 群组变更
7. 保存并验证
```

### 配置机器人

#### 步骤 1: 添加机器人能力

```
1. 进入"机器人"功能
2. 开启"机器人"
3. 配置：
   - 机器人名称：轻程智能助手
   - 机器人头像：上传 Logo
   - 功能：接收消息、发送消息
4. 保存
```

### OpenClaw 配置

#### 步骤 1: 安装飞书插件

```bash
# 检查插件
openclaw plugins list | grep feishu

# 如未安装
npm install -y @openclaw/feishu
```

#### 步骤 2: 配置飞书通道

```bash
# 创建配置文件
nano ~/.openclaw/channels/feishu.json

# 配置内容：
{
  "id": "feishu",
  "name": "飞书",
  "enabled": true,
  "appId": "您的 App ID",
  "appSecret": "您的 App Secret",
  "token": "事件订阅 Token",
  "encryptKey": "加密密钥",
  "eventUrl": "http://118.25.113.60:26106/feishu/event",
  "messageUrl": "http://118.25.113.60:26106/feishu/message"
}
```

#### 步骤 3: 重启 Gateway

```bash
openclaw gateway restart
```

#### 步骤 4: 验证连接

```bash
# 查看日志
tail -f ~/.openclaw/logs/gateway.log | grep feishu

# 查看通道状态
openclaw channels status
```

### 测试飞书消息

#### 发送测试消息

```bash
openclaw message send \
  --channel feishu \
  --target "用户 ID 或群 ID" \
  --message "测试消息：轻程智能助手已连接"
```

---

## 对比总结

### 配置难度对比

| 步骤 | 钉钉 | 飞书 | 企业微信 |
|------|------|------|----------|
| **注册账号** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **创建应用** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| **权限配置** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **回调配置** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| **OpenClaw 配置** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| **总体难度** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |

### 费用对比

| 项目 | 钉钉 | 飞书 | 企业微信 |
|------|------|------|----------|
| **基础版** | 免费 | 免费 | 免费 |
| **专业版** | 9800 元/年 | 19800 元/年 | 6000 元/年 |
| **推荐版本** | 免费版 | 免费版 | 免费版 |

---

## 常见问题

### Q1: 回调验证失败？

```
原因：
1. Gateway 未运行
2. 端口未开放
3. 配置错误

解决：
1. 确认 Gateway 正常运行
2. 检查防火墙规则
3. 核对配置参数
```

### Q2: 消息发送失败？

```
原因：
1. 权限未开通
2. 用户 ID 错误
3. 应用未发布

解决：
1. 检查权限配置
2. 确认用户/群 ID
3. 发布应用
```

### Q3: 收不到消息？

```
原因：
1. 事件订阅未配置
2. 机器人未添加到群
3. 消息类型不支持

解决：
1. 配置事件订阅
2. 添加机器人到群
3. 检查消息类型
```

---

## 最佳实践

### 安全建议

```
□ 使用 HTTPS (有域名后)
□ 定期更新 AppSecret
□ 开启二次验证
□ 限制 IP 访问
□ 定期审计日志
```

### 运维建议

```
□ 配置监控告警
□ 设置自动备份
□ 编写运维文档
□ 定期更新插件
□ 测试灾备方案
```

---

## 附录

### A. 相关文档

- [腾讯企业邮配置](/qc-mail-config.md)
- [开发测试环境指南](/dev-env-guide.md)
- [创业行动计划](/qc.md)

### B. 官方文档

- **钉钉开放平台**: https://open-dev.dingtalk.com/
- **飞书开放平台**: https://open.feishu.cn/
- **OpenClaw 文档**: https://docs.openclaw.ai/

### C. 配置文件位置

| 配置 | 路径 |
|------|------|
| 钉钉配置 | ~/.openclaw/channels/dingtalk.json |
| 飞书配置 | ~/.openclaw/channels/feishu.json |
| Gateway 日志 | ~/.openclaw/logs/gateway.log |

---

**文档版本**: v1.0  
**最后更新**: 2026-04-04 20:40 GMT+8  
**维护者**: 虾子 AI  
**轻程智能科技工作室** · 内部文档

---

*🦐 轻程智能科技工作室 - 轻量化智能，成就大未来*