# feishu-integration

> Feishu (Lark) integration for OpenClaw. Create, read, and manage documents, folders, and app permissions. Actions: create_doc, read_doc, write_doc, append_doc, update_block, delete_block, list_blocks, list_folders, get_scopes. Topics: feishu, lark, document, folder, collaboration, team.

- Author: MoltBot-Stardust
- Repository: ETZhang/openclaw-skills
- Version: 20260201211922
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ETZhang/openclaw-skills
- Web: https://mule.run/skillshub/@@ETZhang/openclaw-skills~feishu-integration:20260201211922

---

---
name: feishu-integration
description: "Feishu (Lark) integration for OpenClaw. Create, read, and manage documents, folders, and app permissions. Actions: create_doc, read_doc, write_doc, append_doc, update_block, delete_block, list_blocks, list_folders, get_scopes. Topics: feishu, lark, document, folder, collaboration, team."
---

# Feishu Integration

OpenClaw 与飞书（Feishu/Lark）的集成技能，支持文档管理、文件夹操作和权限查询。

## Features

- 📄 **文档管理** - 创建、读取、更新、删除飞书文档
- 📁 **文件夹操作** - 列出文档和子文件夹
- 🔐 **权限查询** - 查询应用权限范围
- ✍️ **内容编辑** - 追加、更新、删除文档块
- 📋 **块操作** - 获取和操作文档结构

## Available Tools

| Tool | Description |
|------|-------------|
| `feishu_doc_read` | 读取文档纯文本内容和元数据 |
| `feishu_doc_create` | 创建新空白文档 |
| `feishu_doc_write` | 写入Markdown内容（覆盖） |
| `feishu_doc_append` | 追加Markdown内容到末尾 |
| `feishu_doc_update_block` | 更新特定块的文本内容 |
| `feishu_doc_delete_block` | 删除特定块 |
| `feishu_doc_list_blocks` | 列出文档所有块（获取结构） |
| `feishu_doc_get_block` | 获取特定块的详细内容 |
| `feishu_folder_list` | 列出文件夹中的文档和子文件夹 |
| `feishu_app_scopes` | 列出当前应用权限范围 |

## Setup

### 1. Create Feishu App

1. Go to [Feishu Open Platform](https://open.feishu.cn/)
2. Create a new application
3. Get App ID and App Secret
4. Enable required permissions:
   - `docx:document` - Document read/write
   - `docx:folder` - Folder access
   - `approval:instance` - Approval (optional)

### 2. Configure Credentials

Create `.env` file in the skill directory:

```bash
# Feishu App Credentials
FEISHU_APP_ID=your_app_id_here
FEISHU_APP_SECRET=your_app_secret_here

# Optional: Custom API endpoint
FEISHU_API_BASE_URL=https://open.feishu.cn/open-apis
```

Or set environment variables:

```bash
export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"
```

### 3. Install Dependencies

```bash
cd feishu-integration
pip install -r requirements.txt  # If needed
```

## Usage

### Create a New Document

```python
from openclaw.tools import feishu_doc_create

result = feishu_doc_create(
    folder_token="optional_parent_folder_token",
    title="My New Document"
)
doc_token = result.doc_token
```

### Read Document Content

```python
from openclaw.tools import feishu_doc_read

result = feishu_doc_read(
    doc_token="your_document_token"
)
# Returns: plain text content and metadata
```

### Write Content

```python
from openclaw.tools import feishu_doc_write

feishu_doc_write(
    doc_token="your_document_token",
    content="# Hello World\n\nThis is a **Feishu** document!"
)
```

### Append Content

```python
from openclaw.tools import feishu_doc_append

feishu_doc_append(
    doc_token="your_document_token",
    content="## Additional Section\n\nMore content here."
)
```

### Update a Block

```python
from openclaw.tools import feishu_doc_update_block

feishu_doc_update_block(
    doc_token="your_document_token",
    block_id="block_id_from_list_blocks",
    content="Updated text content"
)
```

### List Document Blocks

```python
from openclaw.tools import feishu_doc_list_blocks

result = feishu_doc_list_blocks(
    doc_token="your_document_token"
)
# Returns: list of all blocks with their IDs
```

### List Folder Contents

```python
from openclaw.tools import feishu_folder_list

result = feishu_folder_list(
    folder_token="your_folder_token"
)
# Returns: documents and subfolders in the folder
```

### Check App Permissions

```python
from openclaw.tools import feishu_app_scopes

result = feishu_app_scopes()
# Returns: list of available permissions/scopes
```

## Document Structure

Feishu documents are block-based. Common block types:
- `paragraph` - 文本段落
- `heading1` - 一级标题
- `heading2` - 二级标题
- `heading3` - 三级标题
- `bullet` - 无序列表
- `ordered` - 有序列表
- `code` - 代码块
- `quote` - 引用
- `table` - 表格
- `image` - 图片

## Best Practices

1. **Security First**
   - Never commit `.env` or credentials
   - Use `.gitignore` to exclude sensitive files
   - Rotate app secrets periodically

2. **Error Handling**
   - Check `result` for success status
   - Handle rate limits gracefully
   - Log errors for debugging

3. **Content Format**
   - Use Markdown for content
   - Note: Tables not supported in write/append
   - Use blocks API for complex structures

4. **Rate Limits**
   - Respect Feishu API rate limits
   - Implement backoff for retries
   - Cache frequently accessed data

## Example Workflow

```python
# Create a meeting notes document
from openclaw.tools import (
    feishu_doc_create,
    feishu_doc_write,
    feishu_doc_append
)

# 1. Create new document
doc = feishu_doc_create(title="Meeting Notes - 2024-01-15")

# 2. Write initial content
feishu_doc_write(
    doc_token=doc.doc_token,
    content="# Team Meeting\n\n## Attendees\n- Alice\n- Bob\n- Charlie\n\n## Agenda\n1. Project updates\n2. Q1 planning"
)

# 3. Append action items
feishu_doc_append(
    doc_token=doc.doc_token,
    content="## Action Items\n- [ ] Review PR #123 (Alice)\n- [ ] Update documentation (Bob)"
)

print(f"Document created: https://example.feishu.cn/docx/{doc.doc_token}")
```

## Troubleshooting

### "App not found" Error
- Verify App ID and Secret are correct
- Check app is published (not in draft mode)

### "Permission denied" Error
- Check required permissions are enabled
- Verify tenant-level consent if needed

### "Rate limit exceeded" Error
- Implement exponential backoff
- Reduce API call frequency

### Document not updating
- Check block_id is valid
- Ensure content format is correct
- Verify document hasn't been deleted

## Resources

- [Feishu Open Platform Docs](https://open.feishu.cn/document/)
- [Document API Reference](https://open.feishu.cn/document/server-docs/docs/docx/intro)
- [App Creation Guide](https://open.feishu.cn/document/server-docs/docs/bitable/quickstart)

## License

MIT