Skip to main content

Feishu Integration Configuration

ACE = AI Computing Explorer

This guide explains how to configure Feishu (Lark) integration for:

  • imported-session user and group name resolution
  • local org sync of Feishu departments and users into Open ACE teams and users

It does not provide a Feishu SSO login flow or a general-purpose Feishu chatbot.

Overview​

Open ACE can integrate with Feishu to:

  • Display real user names instead of ou_xxxxx IDs
  • Display group names instead of oc_xxxxx identifiers
  • Sync Feishu departments into Open ACE collaboration teams
  • Sync Feishu users into local users + team memberships

Prerequisites​

  1. A Feishu developer account
  2. Admin access to create a custom app

Setup​

1. Create a Feishu App​

  1. Visit Feishu Open Platform
  2. Click "Create App" → "Enterprise Custom App"
  3. Fill in app name (e.g., "Open ACE")
  4. Save the App ID and App Secret

2. Configure Permissions​

In the app settings:

  1. Go to "Permissions"
  2. Request the following permissions:
PermissionDescription
contact:contact:user:readonlyRead user information
contact:contact:department:readonlyRead department information
chat:chat:readonlyRead chat information
  1. Submit for approval if required
  2. Publish the app

3. Configure Open ACE​

Edit ~/.open-ace/config.json:

{
  "feishu": {
    "app_id": "cli_xxxxxxxxxxxxxxxx",
    "app_secret": "your_app_secret_here",
    "org_sync_enabled": true,
    "org_sync_tenant_id": 1,
    "org_sync_interval_minutes": 60
  }
}

4. Test Configuration​

# Test user info query
python3 scripts/shared/feishu_user_cache.py test ou_xxxxx <app_id> <app_secret>

# Test group info query
python3 scripts/shared/feishu_group_cache.py test chat_xxxxx <app_id> <app_secret>

5. Sync the organization structure​

After saving the config:

  1. Restart Open ACE if you changed config.json
  2. Open Manage -> Users
  3. Click Sync Feishu

When feishu.org_sync_enabled=true, the background data-fetch scheduler also performs periodic sync based on feishu.org_sync_interval_minutes.

Current sync behavior:

  • departments are mirrored into collaboration teams
  • users are provisioned into local users
  • Feishu identities are linked through sso_identities
  • team memberships are reconciled for Feishu-managed teams

Current non-goals:

  • disabling or deleting local users when they disappear from Feishu
  • removing Feishu-managed teams automatically when departments disappear
  • Feishu SSO login flow
  • general-purpose Feishu chatbot commands

config.json vs the feishu_settings Table​

There are two configuration channels; know which one you are using:

config.json (feishu section)feishu_settings table
Managed byServer operators, by editing the fileSystem administrators, via the admin UI (Manage -> Users -> Feishu settings) backed by /api/management/feishu-config (admin-only GET/PUT/DELETE/test)
Secret storagePlaintext app_secret in the fileEncrypted at rest (app_secret_enc, Fernet); the API only returns a masked indicator, never the secret
Change flowEdit file + restartUI save + test connection; no restart needed; changing credentials resets the stored verification status

Behavior at runtime (verified against app/services/feishu_org_sync.py and app/repositories/notification_settings_repository.py):

  • One-time legacy import: the first time the settings are read, if no feishu_settings row exists yet, the feishu section of config.json is imported into the table once and recorded in config_import_state. From then on config.json is not re-imported, and later edits to the file have no effect on stored settings.
  • Priority: when both exist, the database row wins field by field; config.json only supplies values while no database row exists.
  • Deleting via the admin UI removes the row and writes a tombstone that prevents the legacy config.json values from being silently re-imported.

Security recommendation: prefer the management-UI (database) channel, especially in production — it keeps the App Secret out of plaintext config files. After the one-time import has run (or once you have saved credentials through the UI), remove the plaintext app_secret from config.json. If the instance encryption key is later rotated, the stored secret becomes undecryptable and the connection test returns FEISHU_SECRET_UNREADABLE (HTTP 409); re-enter and save the App Secret to fix it.

Cache Management​

User and group information is cached to avoid frequent API calls.

CommandDescription
python3 scripts/shared/feishu_user_cache.py listList cached users
python3 scripts/shared/feishu_user_cache.py clearClear user cache
python3 scripts/shared/feishu_group_cache.py listList cached groups
python3 scripts/shared/feishu_group_cache.py clearClear group cache

Cache location: ~/.open-ace/feishu_users.json and ~/.open-ace/feishu_groups.json

Cache TTL: 1 hour (3600 seconds)

Troubleshooting​

User names not showing​

  1. Check if the app has contact:contact:user:readonly permission
  2. Ensure the app is published
  3. Verify App ID and App Secret are correct
  4. Check if the user is an external contact (not in organization)

Group names not showing​

  1. Check if the app has chat:chat:readonly permission
  2. Note: OpenClaw uses internal oc_ prefixed IDs, not Feishu chat_ IDs
  3. For OpenClaw integration, group names may require additional configuration

API returns 403​

  • Verify App ID and App Secret
  • Ensure the app is published
  • Check if permissions are approved

Org sync creates fewer users than expected​

  • Check whether the app can read the relevant departments
  • Check whether an existing local user with the same email belongs to another tenant
  • Review server logs for Skipped Feishu user ... warnings

Disabling Integration​

To disable Feishu integration, remove the feishu section from your config file.

References​