---
name: feishu-openclaw-onboarding
version: 0.1.0
description: "当用户需要安装、升级、迁移、排查 OpenClaw 的飞书官方插件（尤其是从旧的官方内置/旧版飞书插件切到 @larksuite/openclaw-lark），或提到‘飞书官方插件’、‘openclaw-lark’、‘/feishu auth’、‘/feishu start’、‘/feishu doctor’、‘飞书插件不行了’、‘学会飞书插件有哪些能力’时使用。也用于把迁移完成后的能力路由到对应的文档、消息、多维表格、日历、任务等专项 skill。"
metadata:
  requires:
    bins: ["openclaw", "npx"]
---

# Feishu OpenClaw Onboarding

这是一个**飞书官方插件安装 / 升级 / 迁移 / 验证 / 排障总入口 skill**。

它解决的问题不是“代替所有飞书能力”，而是：
- 帮用户把旧的飞书插件切到新的官方插件链路
- 帮用户完成授权、验证、排障
- 帮 agent 在迁移完成后，正确切到对应的专项 skill

---

## 这个 skill 该做什么

优先处理下面 5 类事情：

1. **从零安装** 飞书官方插件
2. **从旧插件迁移/升级** 到 `@larksuite/openclaw-lark`
3. **批量授权与验证**（`/feishu auth`、`/feishu start`、`/feishu doctor`）
4. **排查插件异常**（权限、卡片回调、配置、版本兼容）
5. **迁移完成后路由能力** 到文档 / IM / 多维表格 / 日历 / 任务等专项 skill

---

## 这个 skill 不该做什么

不要把它写成“飞书全能操作手册”。

以下场景不应继续停留在本 skill：
- 用户要读写云文档
- 用户要查聊天记录
- 用户要操作多维表格
- 用户要建日程
- 用户要建任务

这些都应在**迁移完成后**切到对应专项 skill。

路由规则见：
- `references/feature-routing.md`

---

## 实际交互体验规则

### 1. 先判断用户处于哪个阶段

优先识别为三类：

- **A. 从零安装**：还没装插件，想接飞书
- **B. 旧版迁移**：之前装过旧官方插件/旧内置插件，现在要升级到新链路
- **C. 已安装但异常**：突然不能用、报权限问题、卡片没反应、授权不完整

### 2. 回复不要上来就倒整份文档

默认按这个顺序输出：
1. 当前状态
2. 当前卡点
3. 下一步
4. 必要时给一条可直接执行的命令

### 3. 只补最关键的一个问题

如果信息不全，只追问最关键缺口，例如：
- 你是还没安装，还是之前装过旧版？
- 现在卡在安装、授权、还是使用报错？

不要一次抛很多问题。

### 4. 安装链路优先“先跑通，再展开”

默认先把：
- 版本
- 安装
- 授权
- 验证
这四步跑通。

不要在用户还没装好时，先展开很多高级配置。

---

## 标准判断流程

### Step 1：判断当前状态

先根据上下文判断是：
- 新装
- 迁移旧版
- 故障排查

如果用户提到这些关键词，优先视为**迁移旧版**：
- “旧飞书插件”
- “官方内置飞书插件”
- “以前能用现在不行”
- “升级飞书插件”
- “从旧版切到 openclaw-lark”

### Step 2：检查运行前提

先确认两个前提：

```bash
openclaw -v
node -v
```

版本要求：
- OpenClaw：
  - Linux / macOS `>= 2026.2.26`
  - Windows `>= 2026.3.2`
- Node.js：`>= 22`

如果 OpenClaw 版本过低，先升级：

```bash
npm install -g openclaw
```

### Step 3：选择安装/迁移路径

#### 路径 A：新装最新版官方插件

```bash
npx -y @larksuite/openclaw-lark install
```

#### 路径 B：明确升级到指定版本

```bash
npx -y @larksuite/openclaw-lark@2026.4.1 install --version 2026.4.1 --tools-version 1.0.37
```

> 如果系统权限导致失败，可提示用户在命令前加 `sudo`（仅在确有权限问题时再提）。

#### 路径 C：旧版迁移判断

如果用户仍在使用旧链路（例如旧 `feishu-plugin-onboard` / 旧 `feishu-openclaw-plugin` 文档或习惯），先说明：

- 新推荐链路是：`@larksuite/openclaw-lark`
- 旧链路不再作为默认推荐入口
- 当前迁移重点是：**安装新插件 → 批量授权 → 验证可用 → 再按专项能力使用**

旧版与新版差异见：
- `references/migration-map.md`

---

## 授权与验证顺序

安装完成后，**必须**按下面顺序推进：

### 1. 批量授权

让用户在飞书里执行：

```text
/feishu auth
```

### 2. 验证安装是否成功

```text
/feishu start
```

预期：返回插件版本号或启动成功信息。

### 3. 做诊断

```text
/feishu doctor
```

预期：能看到权限、账号、配置、缺失项诊断。

### 4. 让 agent 学会插件能力

```text
学习一下我安装的新飞书插件，列出有哪些能力
```

这个动作适合在完成安装与授权后做，用来让 agent 进入“已知能力面”的工作状态。

---

## 常用命令速查

### 终端命令

```bash
# 查看 OpenClaw 版本
openclaw -v

# 诊断（更详细）
npx @larksuite/openclaw-lark doctor

# 自动尝试修复
npx @larksuite/openclaw-lark doctor --fix

# 查看版本与详细配置
npx @larksuite/openclaw-lark info
npx @larksuite/openclaw-lark info --all
```

### 飞书内命令

```text
/feishu auth
/feishu start
/feishu doctor
```

---

## 高优先级排障规则

### 1. 卡片按钮点击没反应

优先怀疑：**没开卡片回传交互权限**。

检查点：
- 飞书开放平台
- 事件与回调
- 长链接订阅
- `card.action.trigger`

### 2. 提示权限不足

默认第一入口：

```text
/feishu doctor
```

不要先靠猜。

### 3. 用户说“以前能用，现在不行”

优先排查：
- OpenClaw 版本变化
- 插件版本变化
- 授权过期
- 权限配置缺项
- 群策略 / requireMention 配置变化

### 4. 只是群里不回复

优先检查：
- `requireMention`
- `groupPolicy`
- 群是否在 allowlist
- 是否开启 `threadSession`

### 5. 升级后配置不生效

先看：

```bash
openclaw config get channels.feishu
npx @larksuite/openclaw-lark info --all
```

---

## 配置类常见动作

```bash
# 开启流式输出
openclaw config set channels.feishu.streaming true

# 显示耗时
openclaw config set channels.feishu.footer.elapsed true

# 显示状态
openclaw config set channels.feishu.footer.status true

# 话题独立上下文
openclaw config set channels.feishu.threadSession true

# 群里只有 @ 才回复
openclaw config set channels.feishu.requireMention true --json

# 群里不需要 @（慎用）
openclaw config set channels.feishu.requireMention false --json
```

---

## 完成判断标准

只有满足下面 4 条，才算“迁移/安装跑通”：

1. 能成功执行安装命令
2. `/feishu auth` 已完成
3. `/feishu start` 能返回成功信息
4. `/feishu doctor` 没有关键阻塞项，或阻塞项已明确

没做到这 4 条前，不要轻易说“已经装好了”。

---

## 迁移完成后的能力路由

迁移成功后，不要继续在本 skill 里处理所有飞书任务。

按场景切换：

- 文档读取 / wiki 文档 → `feishu-fetch-doc`
- 新建文档 → `feishu-create-doc`
- 更新文档 → `feishu-update-doc`
- 消息 / 聊天记录 / 话题 → `feishu-im-read`
- 多维表格 → `feishu-bitable`
- 日历 / 日程 / 忙闲 → `feishu-calendar`
- 任务 / 清单 → `feishu-task`
- 排障 / 权限诊断 → `feishu-troubleshoot`

详见：
- `references/feature-routing.md`

---

## 推荐输出模板

### 模板 A：安装型

- 当前状态：还没装好飞书官方插件
- 当前卡点：先确认 OpenClaw 版本是否满足要求
- 下一步：先跑版本检查，再执行安装

```bash
openclaw -v
npx -y @larksuite/openclaw-lark install
```

### 模板 B：迁移型

- 当前状态：你之前用的是旧链路，现在目标是切到 `@larksuite/openclaw-lark`
- 当前卡点：先不要纠结旧文档细节，先把新链路装起来
- 下一步：安装 → `/feishu auth` → `/feishu start` → `/feishu doctor`

### 模板 C：故障型

- 当前状态：插件已安装，但当前处于异常状态
- 当前卡点：先定位是权限、配置还是回调问题
- 下一步：先跑 `/feishu doctor`，再根据结果继续

---

## 参考资料

- `references/migration-map.md`：旧版 vs 新版迁移关系
- `references/feature-routing.md`：迁移完成后如何切专项 skill
- `references/source-notes.md`：本 skill 所依据的资料摘要