feishu-contacts-sync（飞书通讯录同步）

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