name

feishu-sync

description

Backup and restore OpenClaw agent configuration to/from Feishu Wiki (飞书知识库). Use this skill whenever the user wants to sync, backup, push, pull, clone, migrate, or check the status of their agent configuration with Feishu. Also trigger when the user mentions backing up their agent to Feishu, moving to a new device, recovering agent settings, or syncing soul files to Feishu Wiki. Trigger on Chinese keywords too: "备份到飞书", "同步到飞书", "飞书同步", "搬家", "恢复配置", "同步状态", "知识库".

Feishu Sync — Agent Backup & Restore

Sync OpenClaw agent soul files, skills, models, and bindings to Feishu Wiki (飞书知识库). Your agent's soul is backed up to the cloud and can be restored to any device.

Prerequisites

Python 3.11+
FEISHU_APP_ID and FEISHU_APP_SECRET environment variables set (create an app at https://open.feishu.cn/)
A Feishu Wiki space with the app added as a member (edit permission)
App permissions: wiki:wiki, docx:document

Installation

pip install -e /path/to/openclaw-feishu-sync

Or if installed globally, the openclaw-feishu command is available directly.

Workflows

First-Time Backup

Run these two commands to back up your agent for the first time:

openclaw-feishu init --space-id <wiki-space-id>
openclaw-feishu sync

The space ID can be found in your Feishu Wiki URL or via the Wiki space settings page.

This creates a wiki tree with agent nodes (each containing soul files and skills), a Models document, Bindings document, and Dashboard page, then pushes all local config to Feishu.

Daily Backup

openclaw-feishu sync

Only changed files are synced (incremental via mtime detection). Use --force to push everything.

Restore to New Device

On the new machine, after installing openclaw-feishu-sync and setting credentials:

openclaw-feishu clone --space-id <space-id>

This discovers existing wiki nodes on Feishu and pulls all agent config to the local machine. Paths are automatically adapted.

To skip model/binding config (configure locally instead):

openclaw-feishu clone --space-id <space-id> --skip-models --skip-bindings

Pull Changes from Feishu

If you edited soul files in Feishu's web editor:

openclaw-feishu pull

Check Status

openclaw-feishu status

Shows sync state, tracked wiki nodes, agent pages, and file counts.

Command Reference

openclaw-feishu init --space-id <id>          # Create wiki structure
openclaw-feishu sync                          # Push local → Feishu
openclaw-feishu sync --only soul              # Push only soul files
openclaw-feishu sync --force                  # Force full push
openclaw-feishu push                          # Alias for sync
openclaw-feishu pull                          # Pull Feishu → local
openclaw-feishu pull --only identity          # Pull only identity files
openclaw-feishu pull --only models            # Pull only model config
openclaw-feishu pull --skip-models            # Pull all except models
openclaw-feishu clone --space-id <id>         # Clone to new device
openclaw-feishu migrate                       # Add missing wiki nodes
openclaw-feishu status                        # Show sync state

Sync Types

Per-Agent Filtering

In the sync state, each agent has a sync-enabled flag. Disabled agents are excluded from sync/pull operations.

Security

API keys, bot tokens, and passwords are never overwritten during pull — sensitive fields are preserved from local config
Config is backed up to .json.bak before any write
.env file containing credentials is excluded from git

Troubleshooting

"FEISHU_APP_ID not set" — Create a .env file with credentials in your working directory, or set the environment variables
"Not initialized" — Run openclaw-feishu init --space-id <id> first
Permission errors — Make sure the app is added to the Wiki space with edit permission
"invalid param" on sync — Some Feishu block types (callout, quote_container) are container blocks requiring special handling; the tool uses styled text paragraphs as fallback