Feishu Contacts Sync

核心功能：同步飞书通讯录生成open_id到姓名的映射表，嵌入USER.md，让Agent无需工具调用即可匹配飞书DM的open_id识别发送者（飞书DM仅携带open_id无姓名）。典型场景：飞书身份识别配置、HR人员变动后更新通讯录、多用户Agent权限配置。需飞书应用具备通讯录权限，通过脚本同步，支持定期更新，同步后需重启网关生效。

4ier

热度 67.76

最近更新 2026-05-11 17:29:40

分类：自动化依赖：代码执行 / 读写文件 / 第三方 API应用场景：自动化脚本 / 任务管理

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add feishu-contacts-sync

Metadata

name: feishu-contacts
description: Sync Feishu (Lark) contacts into USER.md so the agent can identify DM senders by name. Use when setting up Feishu identity recognition, updating contacts after HR changes, or configuring multi-user agent access. Feishu DMs only include open_id (no sender name), so this skill embeds an open_id→name lookup table directly in USER.md for zero-tool-call identification.

Feishu Contacts Sync

Problem

Feishu (Lark) DM messages only include the sender's open_id — no name. Group messages include Sender metadata with the name, but DMs don't. Without a lookup table, the agent will either:

Assume all DMs are from the person in USER.md (wrong)
Fail to identify the sender entirely

Solution

Embed the full contacts table directly in USER.md. Since workspace files are injected into the system prompt at gateway startup, the agent can match open_id from inbound metadata against the table — zero tool calls needed.

Important: open_id is per-app

Feishu open_id is scoped to each app. The same person has different open_ids across different Feishu apps. Each OpenClaw instance using a different Feishu app must pull contacts with its own app credentials.

Setup

1. Ensure Feishu app has contacts permission

The app needs contact:user.employee_id:readonly or contact:user.base:readonly scope to list users via the contacts API.

2. Run the sync script

python3 scripts/sync_feishu_contacts.py <openclaw_config_path> <feishu_account_name> <user_md_path>

Example:

python3 scripts/sync_feishu_contacts.py ~/.openclaw/openclaw.json my_app ~/workspace/USER.md

Arguments:

openclaw_config_path: Path to your openclaw.json (contains Feishu app credentials)
feishu_account_name: The account name under channels.feishu.accounts in your config
user_md_path: Path to your USER.md file

3. USER.md format

The script expects USER.md to contain a contacts section with this format:

## 飞书通讯录 (App Name)
飞书 DM 不携带发送者姓名。用 inbound metadata 的 chat_id（格式 `user:ou_xxx`）匹配下表识别发送者。
| 姓名 | open_id |
|------|---------|
| Alice | ou_abc123 |
| Bob | ou_def456 |

On first run, if no contacts section exists, add the section header and description line manually, then run the script to populate the table.

4. Add sender identification to AGENTS.md

Add this to your startup sequence:

识别消息发送者（必须执行）：飞书 DM 不携带发送者姓名，只有 open_id（inbound metadata 的 chat_id 格式 `user:ou_xxx`）。提取 open_id，在 USER.md 的飞书通讯录表格中匹配找到姓名。不要假设 DM 对方就是主人——任何人都可能给你发私聊。群聊消息自带 Sender metadata 可直接使用。

5. Set up periodic sync (optional)

Add a system crontab to keep contacts fresh (e.g., weekly Monday 7am):

0 7 * * 1 python3 /path/to/scripts/sync_feishu_contacts.py ~/.openclaw/openclaw.json my_app ~/workspace/USER.md

Note: After sync updates USER.md, restart the gateway for changes to take effect (workspace files are cached at gateway startup).

Multi-user principle

USER.md should clearly state:

Who the "primary human" (主人) is
That the agent serves multiple users and must not assume DM sender identity
A communication preference to address people by their actual name

Privacy

The contacts table contains only names and open_ids (no emails, phone numbers, or other PII)
open_id is an opaque identifier meaningful only within your Feishu app
The sync script reads app credentials from openclaw.json but never outputs them