Feishu Group Manager

Quick Reference

When a write operation returns {"error": "payment_required", ...}: stop, show the message field to the user, and wait for them to top up before retrying.

First Use: Credential Check + Permission Verification

The user is already chatting via Feishu, so the app exists and credentials are configured. No need to ask them to set anything up.

Credentials are resolved automatically in this order:

1. Environment variables FEISHU_APP_ID / FEISHU_APP_SECRET
2. ~/.openclaw/openclaw.json → channels.feishu.accounts.\x3Cany>.appId / appSecret

On the first request of a session, run:

python3 {baseDir}/scripts/feishu.py check_permissions

If all_ok: true — proceed directly.

If all_ok: false — show the user a friendly message listing missing permissions and how to grant them, e.g.:

"Before I can manage your groups, your Feishu app needs a couple of extra permissions (takes ~2 min).

Missing:

• im:chat.member — add/remove group members
• contact:user.id:readonly — search members by name

Steps:

1. Open https://open.feishu.cn/app and find your app
2. Go to Permission Management → search and enable the permissions above
3. Go to Version Management → create a new version → submit for review
4. Once approved (usually a few minutes), let me know and I'll continue."

Re-run check_permissions after the user confirms. Cache the result for the session — only re-check if the user says they just updated permissions, or if Feishu returns error code 99991672.

Execution Flow

Step 1 — Understand intent

Confirm briefly in the user's language, e.g.: "Got it, I'll add Zhang San to the Marketing group."

Step 2 — Gather info

python3 {baseDir}/scripts/feishu.py get_token
python3 {baseDir}/scripts/feishu.py find_chat --token TOKEN --name "marketing"
python3 {baseDir}/scripts/feishu.py find_user --token TOKEN --name "Zhang San"

If multiple matches are returned, list them and ask the user to confirm.

Step 3 — Confirm before any write

"I'm about to add Zhang San (Marketing dept.) to Marketing Group. Confirm?"

Wait for confirmation before executing.

Step 4 — Execute and report

Success: "Done! Zhang San has been added to Marketing Group." Failure: Explain in plain language — never expose raw API errors.

Command Reference

# Check app permissions
python3 {baseDir}/scripts/feishu.py check_permissions

# Get tenant access token (auto-reads credentials)
python3 {baseDir}/scripts/feishu.py get_token

# List all groups
python3 {baseDir}/scripts/feishu.py list_chats --token TOKEN

# Find group by name (fuzzy)
python3 {baseDir}/scripts/feishu.py find_chat --token TOKEN --name "NAME"

# List group members
python3 {baseDir}/scripts/feishu.py list_members --token TOKEN --chat_id CHAT_ID

# Search user by name
python3 {baseDir}/scripts/feishu.py find_user --token TOKEN --name "NAME"

# Add member to group (billed)
python3 {baseDir}/scripts/feishu.py add_member \
  --token TOKEN --chat_id CHAT_ID \
  --target_user_id TARGET_UID --user_id CALLER_UID

# Remove member from group (billed)
python3 {baseDir}/scripts/feishu.py remove_member \
  --token TOKEN --chat_id CHAT_ID \
  --target_user_id TARGET_UID --user_id CALLER_UID

# Send message to group (billed)
python3 {baseDir}/scripts/feishu.py send_message \
  --token TOKEN --chat_id CHAT_ID --text "MESSAGE" --user_id CALLER_UID

# Rename group (billed)
python3 {baseDir}/scripts/feishu.py rename_chat \
  --token TOKEN --chat_id CHAT_ID --name "NEW NAME" --user_id CALLER_UID

# Create group and add members (billed)
python3 {baseDir}/scripts/feishu.py create_chat \
  --token TOKEN --name "GROUP NAME" --user_ids "uid1,uid2" --user_id CALLER_UID

--user_id is the caller's Feishu open_id — used for billing. Retrieve it from conversation context or from find_user results.

Error Handling