# 飞书文档创建失败经验总结

> **创建日期**: 2026-03-18  
> **问题类型**: API 调用失败 / 工具超时  
> **来源**: 欢欢助理与欢哥的对话记录

---

## 📋 问题描述

**任务**: 创建飞书云文档"欢欢助理运行环境配置"  
**期望**: 使用 `feishu-create-doc` 技能创建到个人知识库  
**结果**: 多次尝试均超时失败

---

## 🔍 尝试方案

### 方案 1: 使用子代理调用技能
```
sessions_spawn → subagent → feishu-create-doc
```
**结果**: ❌ 超时 (60 秒)

**可能原因**:
- 子代理初始化耗时过长
- 技能加载慢
- 飞书 API 响应慢

---

### 方案 2: 使用 ACP 运行时
```
sessions_spawn --runtime=acp --agentId=@larksuite/openclaw-lark
```
**结果**: ❌ 错误 "ACP runtime backend is not configured"

**原因**: ACP 运行时后端未配置

---

### 方案 3: 使用 openclaw CLI
```bash
openclaw feishu_doc create --title "xxx" --wiki-space "my_library"
```
**结果**: ❌ 错误 "unknown command 'feishu_doc'"

**原因**: CLI 不支持该命令

---

### 方案 4: 直接调用 Gateway API
```python
# 尝试通过 Python 调用
payload = {
    'tool': 'feishu_create_doc',
    'params': {...}
}
```
**结果**: ⏳ 未完全尝试

---

## ✅ 可行方案

### 方案 A: 手动创建（推荐）
1. 打开飞书 → 知识库 → 个人知识库
2. 新建文档
3. 粘贴 Markdown 内容
4. 设置标题

**优点**: 100% 可靠，即时可见  
**缺点**: 需要人工介入

---

### 方案 B: 使用飞书导入功能
1. 准备 Markdown 文件
2. 飞书文档 → 导入 → 选择文件
3. 选择目标位置

**优点**: 保留格式  
**缺点**: 需要手动操作

---

### 方案 C: 使用 feishu_chat 工具（待验证）
```
通过 message 工具发送文档内容到飞书
```

---

## 📝 经验教训

### 1. 子代理超时问题
**问题**: 子代理调用技能容易超时  
**教训**: 
- 简单任务尽量在主会话完成
- 子代理适合长时间任务
- 超时时间设置至少 120 秒

---

### 2. ACP 运行时配置
**问题**: 默认未配置 ACP 运行时  
**教训**:
- 使用前先检查配置
- `agents_list` 只返回 subagent 允许列表
- ACP 需要额外配置 `acp.defaultAgent`

---

### 3. CLI 命令限制
**问题**: 不是所有工具都有 CLI 命令  
**教训**:
- CLI 命令有限，主要工具需通过 Gateway API
- 先用 `openclaw --help` 查看可用命令
- 不确定时先测试

---

### 4. 飞书 API 权限
**问题**: 可能需要额外权限  
**教训**:
- 检查飞书应用权限配置
- 确认 OAuth token 有效
- 知识库写入需要相应 scope

---

## 🛠️ 解决方案建议

### 短期方案
1. **手动创建**文档，后续自动化
2. 准备 Markdown 模板，减少重复工作

### 中期方案
1. 配置 ACP 运行时
2. 测试 Gateway API 直接调用

### 长期方案
1. 创建 `feishu-doc-creator` 技能
2. 集成到工作流自动化

---

## 📞 相关资源

| 资源 | 链接/位置 |
|------|-----------|
| 飞书文档 API | https://open.feishu.cn/document/ukTMukTMukTM/uEDO4QjLxgDM14SM2gTN/ |
| OpenClaw 飞书插件 | `~/.openclaw/extensions/openclaw-lark/` |
| feishu-create-doc 技能 | `~/.openclaw/extensions/openclaw-lark/skills/feishu-create-doc/SKILL.md` |

---

## ✅ 检查清单

创建飞书文档前检查：

- [ ] 飞书插件已启用
- [ ] OAuth token 有效
- [ ] 知识库权限已授权
- [ ] Markdown 内容格式正确
- [ ] 目标位置 (wiki_space/folder_token) 正确
- [ ] 超时时间设置充足 (≥120 秒)

---

*本文档由欢欢助理整理，避免重复踩坑。*