Excel Workflow#

Complete workflow for Excel file management with local processing, Google Drive backup, formula preservation, and SQLite tracking.

Features#

• ✅ Formula Preservation — Update cells without losing formulas (powered by openpyxl)
• ✅ Google Drive Sync — Automatic backup to Google Drive using rclone
• ✅ SQLite Tracking — Track all files, formulas, and metadata in local database
• ✅ Multi-file Support — Work with multiple Excel files simultaneously
• ✅ Data Analysis — Query data, read formulas, and analyze structure
• ✅ Mass Operations — Create formulas for entire columns at once

Quick Start#

1. Upload Excel File#

Simply drop an .xlsx file into the chat. The workflow automatically:

1. Analyzes file structure (sheets, formulas)
2. Uploads to Google Drive ( gdrive:Excel/)
3. Saves metadata to SQLite tracker

bash

# Manual processing
~/.openclaw/tools/openclaw-excel/excel-workflow process /path/to/file.xlsx

2. Query Data#

bash

# Ask questions about your data
~/.openclaw/tools/openclaw-excel/excel-workflow query "what is total revenue?" --file sales.xlsx

3. Update Cells (Formulas Preserved!)#

bash

# Update values - formulas stay intact
~/.openclaw/tools/openclaw-excel/excel-workflow update '{"C2": 100}' --file sales.xlsx

# Update formulas
~/.openclaw/tools/openclaw-excel/excel-workflow update '{"D2": "=B2*C2*1.5"}' --file sales.xlsx

Installation#

Prerequisites#

1. Python 3.8+ with openpyxl
2. rclone for Google Drive integration
3. Google Drive account

Step 1: Install Dependencies#

bash

# Install rclone (macOS)
brew install rclone

# Python packages (installed in venv automatically)
pip install openpyxl

Step 2: Setup Google Drive#

bash

# Configure rclone with Google Drive
rclone config

Follow prompts:

• Name: gdrive
• Storage: drive (Google Drive)
• Scope: 1 (Full access)
• Auto config: y (opens browser for OAuth)

Verify:

bash

rclone lsd gdrive:

Step 3: Create Excel Folder#

bash

rclone mkdir gdrive:Excel/

Step 4: Install Skill Files#

The skill consists of 3 components:

1. Excel CLI ( ~/.openclaw/tools/openclaw-excel/excel)
   • Commands: info, read, update, show-formulas, get-cell
2. Tracker CLI ( ~/.openclaw/tools/openclaw-excel/excel-tracker)
   • SQLite database at ~/.openclaw/excel_tracker.db
   • Commands: add, get-latest, search, list, stats
3. Workflow Orchestrator ( ~/.openclaw/tools/openclaw-excel/excel-workflow)
   • Commands: process, query, update, list, stats

See Installation Guide for detailed setup.

Commands#

Process Command#

Analyze file, upload to Drive, and save to tracker:

bash

excel-workflow process /path/to/file.xlsx [--telegram-id ID]

Output:

json

{
  "status": "success",
  "filename": "sales.xlsx",
  "file_id": 1,
  "drive_url": "gdrive:Excel/sales.xlsx",
  "analysis": {
    "sheets": 2,
    "formulas": 15,
    "sheet_names": ["Sales", "Summary"]
  },
  "message": "✅ File processed successfully!"
}

Query Command#

Read data and answer questions:

bash

excel-workflow query "show me the data" [--file filename.xlsx]

Output:

json

{
  "filename": "sales.xlsx",
  "file_id": 1,
  "sheets": ["Sales", "Summary"],
  "data": [
    [
      {"address": "A1", "value": "Product", "type": "str"},
      {"address": "B1", "value": "Price", "type": "int"}
    ]
  ],
  "formulas": [
    {"cell": "D2", "formula": "=B2*C2"}
  ],
  "question": "show me the data",
  "context": {
    "sheet_count": 2,
    "formula_count": 15,
    "uploaded_at": "2026-02-20 10:30:00"
  }
}

Update Command#

Update cells (values or formulas):

bash

# Update values
excel-workflow update '{"C2": 100, "C3": 200}' [--file filename.xlsx]

# Update formulas
excel-workflow update '{"D2": "=B2*C2*1.5"}' --file sales.xlsx

# Mass update - create formulas for entire column
excel-workflow update '{"D2": "=B2*0.5", "D3": "=B3*0.5", ...}' --file data.xlsx

Output:

json

{
  "status": "success",
  "filename": "sales.xlsx",
  "updated": 2,
  "changes": [
    {"cell": "C2", "old_value": 50, "new_value": 100},
    {"cell": "C3", "old_value": 75, "new_value": 200}
  ],
  "message": "✅ Updated and re-uploaded to Google Drive"
}

List Command#

Show tracked files:

bash

excel-workflow list [--limit 10]

Output:

json

[
  {
    "id": 2,
    "original_filename": "sales_2026.xlsx",
    "sheet_count": 2,
    "formula_count": 15,
    "uploaded_at": "2026-02-20 14:20:00"
  },
  {
    "id": 1,
    "original_filename": "budget.xlsx",
    "sheet_count": 3,
    "formula_count": 42,
    "uploaded_at": "2026-02-19 09:15:30"
  }
]

Stats Command#

Show statistics:

bash

excel-workflow stats

Output:

json

{
  "total_files": 5,
  "files_on_drive": 5,
  "total_sheets": 12,
  "total_formulas": 87
}

Usage Patterns for AI Agents#

Pattern 1: User Uploads Excel File#

User action: Uploads sales.xlsx via Telegram

Agent workflow:

1. File saved to temporary location by Telegram handler
2. Detect .xlsx extension
3. Run: excel-workflow process /path/to/sales.xlsx --telegram-id <id>
4. Parse JSON result and respond:

text

Agent: "✅ I've received and processed sales.xlsx!

📊 Analysis:
- 2 sheets: Sales, Summary
- 15 formulas detected
- ☁️ Uploaded to Google Drive

What would you like to know about this file?"

Pattern 2: User Asks Question#

User: "What's the total revenue in my sales file?"

Agent workflow:

1. Run: excel-workflow query "what is total revenue?" --file sales.xlsx
2. Receive data with all rows and formulas
3. Analyze the data to find revenue-related columns and totals
4. Respond with answer:

text

Agent: "Looking at your sales.xlsx file:

Total Revenue: 650,000 руб

Breakdown:
- iPhone: 150,000 (3 × 50,000)
- MacBook: 200,000 (2 × 100,000)
- iPad: 300,000 (5 × 60,000)

The file has a SUM formula in cell D5 that calculates this automatically."

Pattern 3: User Requests Update#

User: "Change iPhone quantity to 20"

Agent workflow:

1. Query to understand structure: excel-workflow query "find iPhone row"
2. Identify that iPhone is in row 2, quantity in column C
3. Run: excel-workflow update '{"C2": 20}' --file sales.xlsx
4. Confirm update:

text

Agent: "✅ Updated sales.xlsx:

Changed C2 (iPhone quantity): 3 → 20

New revenue for iPhone: 1,000,000 руб (was 150,000)
Total revenue updated automatically thanks to formulas!

File has been re-uploaded to Google Drive."

Pattern 4: Mass Formula Creation#

User: "Create a column that multiplies price by 0.5 for all products"

Agent workflow:

1. Read file to determine row count
2. Generate update JSON with formulas for each row
3. Run: excel-workflow update '{"D2": "=B2*0.5", "D3": "=B3*0.5", ...}' --file prices.xlsx
4. Confirm:

text

Agent: "✅ Created formulas for 50 rows!

Column D now contains =B*0.5 formula for all products.
File updated on Google Drive."

Technical Details#

Components#

1. Excel CLI — openpyxl-based tool for reading/writing Excel files
   • Preserves formulas using data_only=False
   • Commands: read, update, info, show-formulas, get-cell
2. Tracker — SQLite database for file metadata
   • Location: ~/.openclaw/excel_tracker.db
   • Tracks: filename, sheets, formulas, paths, timestamps
3. Workflow Orchestrator — Integrates Excel CLI, rclone, and tracker
   • Orchestrates: analyze → upload → track → update cycle
   • Progress messages to stderr, JSON results to stdout

File Locations#

• Tracker database: ~/.openclaw/excel_tracker.db
• Google Drive folder: gdrive:Excel/
• Local files: User-specified paths (Telegram downloads to ~/.openclaw/media/)

Formula Preservation#

How it works:

• openpyxl loads workbooks with data_only=False
• Formulas stored as text strings (e.g., "=B2*C2")
• When updating cell with formula string, openpyxl preserves it
• Excel recalculates formulas when file is opened

Example:

python

# This preserves formulas
ws['D2'] = '=B2*C2'  # Formula remains
ws['B2'] = 100       # Data changes, formula in D2 recalculates

What's Preserved vs Not Preserved#

✅ Preserved:

• Formulas (=SUM, =IF, =B2*C2, etc.)
• Data (numbers, text, dates)
• Structure (sheets, tables)
• Formatting (colors, fonts, borders, bold)
• Charts (diagrams update automatically)

⚠️ May Not Work:

• Conditional formatting (complex rules)
• Macros (.xlsm files not supported)
• Pivot tables (may break)
• Slicers and advanced filters

Error Handling#

Common errors:

1. File not found json

   {"error": "File not found: /path/to/file.xlsx"}
   
   

2. Google Drive not configured json

   {"error": "rclone remote 'gdrive' not configured"}
   
   

   Solution: Run rclone config

3. Formula syntax error json

   {"error": "Invalid formula: =B2*"}
   
   

   Solution: Check formula syntax

4. Database locked json

   {"error": "Database is locked"}
   
   

   Solution: Wait and retry

Examples#

Example 1: Financial Data Analysis#

bash

# Upload stock data
excel-workflow process ~/Desktop/ARKK.xlsx

# Query
excel-workflow query "show last 10 rows" --file ARKK.xlsx

# Add calculated column (50% of price)
# First, find row count, then generate formulas
excel-workflow update '{"C2": "=B2*0.5", "C3": "=B3*0.5", ...}' --file ARKK.xlsx

Example 2: Price List Update#

bash

# Process price list
excel-workflow process prices.xlsx

# Update prices
excel-workflow update '{"B10": 99.99, "B11": 149.99}' --file prices.xlsx

# Add tax column
excel-workflow update '{"D2": "=B2*1.2"}' --file prices.xlsx

Example 3: Multiple Files#

bash

# Upload multiple files
excel-workflow process january.xlsx
excel-workflow process february.xlsx

# List all files
excel-workflow list

# Query specific file
excel-workflow query "total sales" --file january.xlsx

# Stats
excel-workflow stats

Troubleshooting#

Issue: "rclone not found"#

bash

# Install rclone
brew install rclone  # macOS
sudo apt install rclone  # Linux

Issue: "openpyxl not installed"#

bash

# Install in virtual environment
cd ~/.openclaw/tools/openclaw-excel
python3 -m venv venv
./venv/bin/pip install openpyxl

Issue: "Google Drive permission denied"#

bash

# Reconfigure rclone
rclone config
# Delete old gdrive remote and create new one

Issue: "Formulas become values"#

This should NOT happen! If it does:

1. Check that excel CLI uses data_only=False when loading workbook
2. Ensure formula strings start with =
3. Verify openpyxl version: pip show openpyxl (should be 3.1.0+)

Best Practices#

For Users#

1. Name files descriptively
   • Good: sales_2026_Q1.xlsx
   • Bad: Book1.xlsx
2. Ask specific questions
   • Good: "What's the total revenue in January?"
   • Bad: "Tell me about the file"
3. Keep file structure consistent
   • Makes it easier for AI to understand

For Developers#

1. Always check file existence before processing
2. Use sessions for multiple operations on same file
3. Handle errors gracefully with try/except
4. Show progress in stderr, results in stdout
5. Validate formulas before updating cells

API Reference#

See Excel CLI Documentation and Tracker Documentation for detailed API reference.

Resources#

• openpyxl Documentation
• rclone Documentation
• Microsoft Excel File Format
• Google Drive with rclone

Support#

• GitHub Issues: [your-repo/excel-workflow/issues]
• Documentation: [your-repo/excel-workflow/docs]
• Community: [OpenClaw Community]

License#

MIT License - see LICENSE.txt

Changelog#

Version 1.0.0 (2026-02-20)#

• Initial release
• Formula preservation with openpyxl
• Google Drive sync via rclone
• SQLite tracking
• Multi-file support
• Mass formula operations
• AI agent integration patterns