Feishu Contacts Sync

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 aft...

Security Scan

The skill's code and instructions match its stated purpose: it reads Feishu app credentials from the provided openclaw.json, calls Feishu APIs to fetch users, and updates USER.md with an open_id→name table; nothing requested or installed is disproportionate to that task.

Purpose & Capability

The name/description describe syncing Feishu contacts into USER.md. The script and SKILL.md only perform actions required for that (read openclaw.json for app credentials, call Feishu APIs, and write the contacts table to USER.md). No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

Runtime instructions explicitly tell the operator to run the provided script with a path to openclaw.json and the USER.md path. The script only reads those two paths and performs HTTPS calls to Feishu endpoints to fetch users, then updates the contacts table. It does not attempt to read other files, environment variables, or transmit data to unexpected endpoints.

Install Mechanism

No install spec is present (instruction-only + a small included script). Nothing is downloaded from arbitrary URLs or written to nonstandard system locations. The script relies on standard Python library modules only (urllib, json, re, os, sys).

Credentials

The skill requests no environment variables and uses app credentials only from the openclaw.json path you supply. Those credentials are necessary and proportionate for calling Feishu's contacts API. The script does not exfiltrate credentials or require unrelated secrets.

Persistence & Privilege

The skill does not request permanent presence (always:false), does not modify other skills or system-wide settings, and only writes the contacts section of USER.md as described. Optional crontab instructions are local scheduling guidance, not an automatic persistent installer.

Assessment

This skill appears coherent and limited to its stated purpose, but before installing/running: (1) verify the openclaw.json path and that it contains only the Feishu app credentials you expect (appId/appSecret), (2) ensure openclaw.json is stored with appropriate filesystem permissions since it contains secrets, (3) review USER.md backups — the script will overwrite the contacts section, and (4) confirm the Feishu app has only the minimal contact scope needed. If you plan to run it periodically (crontab), ensure the scheduled job runs with an account that has limited privileges and access only to the needed files. If you want extra assurance, inspect the included script contents (it's small and readable) before running.

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