feishu-contacts

# 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

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

Example:
```bash
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:

```markdown
## 飞书通讯录 (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 t...