# daily-inspection

Daily inspection reports for all OpenClaw containers.

## File Structure

```
daily-inspection/
├── main.py                      # Main entry script
├── gen_open_id_mapping.py     # Query user names for unmapped open_ids
├── open_id_and_user_mapping.json  # Existing user mapping (open_id → user_name)
├── README.md
└── __pycache__/               # Python cache
```

## Workflow

```
main.py
  │
  ├── 1. Load existing mappings (open_id_and_user_mapping.json)
  │
  ├── 2. Aggregate daily stats (including .jsonl and .jsonl.reset.* files)
  │     ├── calculate_tokens()      - Token usage stats
  │     ├── calculate_messages()    - Message count stats
  │     └── get_user_stats_from_sessions_json() - User message stats
  │
  ├── 3. Collect unmapped open_ids
  │     └── Save to unmapped_open_id_list.json
  │
  ├── 4. Call gen_open_id_mapping.py to query user names
  │     └── Auto-try multiple Feishu app credentials
  │
  ├── 5. Generate report (with all mappings)
  │     └── Save to ~/openclaw-team/skill-scripts/inspection-YYYY-MM-DD.md
  │
  ├── 6. Upload to Feishu Wiki
  │
  └── 7. Send notification to Feishu group

gen_open_id_mapping.py
  │
  ├── 1. Read unmapped_open_id_list.json
  │
  ├── 2. Read container's openclaw.json for Feishu credentials
  │     └── Support multiple app accounts (accounts.main, accounts.explorer, etc.)
  │
  ├── 3. Query Feishu API for user info
  │     └── BatchUserRequest API
  │
  └── 4. Save to mapped_open_id_list.json
```

## Usage

### Run script (default: yesterday)

```bash
cd ~/github/data-service-infra-ai-configurations/cronjobs/team-admin/daily-inspection
python3 main.py
```

### Specify date

```bash
python3 main.py 2026-03-15
```

### Query user mapping separately

```bash
python3 gen_open_id_mapping.py unmapped_open_id_list.json
```

## Key Configuration

### Environment Variables

Script automatically loads from `~/.bashrc`:

- `CRONJOB_TEAM_ADMIN_APP_ID` - Feishu app ID (for sending notifications)
- `CRONJOB_TEAM_ADMIN_APP_SECRET` - Feishu app secret

### Feishu Credentials Location

Each container's Feishu credentials are in `~/openclaw-config/{container}/openclaw.json`:

```json
{
  "channels": {
    "feishu": {
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx"
        },
        "explorer": {
          "appId": "cli_xxx", 
          "appSecret": "xxx"
        }
      }
    }
  }
}
```

## Session File Explanation

OpenClaw session data is stored in:

```
~/openclaw-config/{container}/agents/{agent}/sessions/
  ├── {uuid}.jsonl           # Active session
  └── {uuid}.jsonl.reset.*   # History after session reset
```

**Important**: When aggregating stats, must read both `.jsonl` and `.jsonl.reset.*` files, otherwise historical data before session reset will be missed.

## Output Files

| File | Description |
|------|-------------|
| `~/openclaw-team/skill-scripts/inspection-YYYY-MM-DD.md` | Inspection report (Markdown) |
| `~/openclaw-config/.../open_id_and_user_mapping.json` | Existing user mapping |
| `unmapped_open_id_list.json` | Temp: Unmapped open_ids for the day |
| `mapped_open_id_list.json` | Temp: Newly queried mappings |

**Note**: Temp files are auto-deleted after execution.

## Report Content

- **Summary**: Total Tokens, Messages, Skills
- **Top 5 Token Usage**: Container token ranking
- **Top 5 User Messages**: User message ranking
- **Basic Info**: Container basic info (Security, Tokens, Messages, Skills, Cron)
- **Skills Info**: Skills installed per container
- **User Stats**: User detailed stats (Tokens, Messages, Container)

## Notes

1. **Date format**: Use `YYYY-MM-DD` (e.g., `2026-03-15`)
2. **Stats scope**: Day definition is based on UTC time
3. **User mapping**: If an open_id exists in multiple Feishu apps, will try sequentially
4. **Cross-org issue**: Some users may be in different Feishu organizations, resulting in not found