ClawHub

Akounter

OpenClaw account manager plugin with SQLite ledger and GLM-OCR receipt ingestion.

Install

openclaw plugins install clawhub:akounter

Akounter

Author: Prabakaran Thavamani

Akounter is a production-oriented OpenClaw tool plugin that keeps a local personal ledger in SQLite and supports first-run locale onboarding, fast transaction capture, balance lookups, summaries, explicit export-style transaction views for chat channels, and OCR receipt ingestion through GLM-OCR.

Overview

Akounter is designed for local-first bookkeeping inside OpenClaw. It stores all state in SQLite, preserves original source text for auditability, and keeps OCR provenance so receipt extraction errors are diagnosable instead of silently discarded.

Features

  • CRUD for transactions with transactional SQLite writes
  • Natural language capture for common income and expense phrases
  • GLM-OCR receipt and bill ingestion for image and PDF inputs
  • Fast listing and search with normalized integer minor units and indexes
  • Balance calculation with optional date and category filters
  • Latest 20 transactions by default with deterministic ordering
  • Export-style transaction output only when the user explicitly asks for export or download
  • One-time onboarding for currency and number formatting persisted in akounter-settings.json
  • Migration-backed schema initialization
  • Raw OCR text and structured metadata retention for audit/debugging

Architecture

  • index.ts: native OpenClaw plugin entrypoint
  • src/tool.ts: tool registration and tool-facing response formatting
  • src/service.ts: orchestration for CRUD, OCR, search, balance, and export
  • src/db.ts: SQLite access, migrations, filters, and transactional writes
  • src/parser.ts: deterministic natural language parser
  • src/ocr.ts: GLM-OCR integration and structured receipt extraction
  • src/export.ts: file export helpers reserved for a later release
  • src/settings.ts: onboarding settings persistence and locale-aware number formatting
  • src/prompts.ts: OCR prompt and export trigger constants
  • src/migrations/001_init.sql: schema and indexes

Install Steps

  1. Ensure Node 22 or newer is installed.
  2. Install OpenClaw plugin dependencies in this plugin root:
pnpm install
  1. Configure OpenClaw to load the plugin package from this directory or publish/install it as a standard OpenClaw plugin.
  2. For local GLM-OCR via Ollama:
ollama pull glm-ocr:latest
ollama serve
  1. This build does not execute local shell commands inside the plugin, so pass image receipts directly. If you have a PDF, convert the first page to PNG/JPG outside the plugin before ingestion.

Config

Supported environment variables:

  • AKOUNTER_DB_PATH: SQLite file path. Default: OPENCLAW_STATE_DIR/.openclaw/akounter/akounter.sqlite when OPENCLAW_STATE_DIR is set, otherwise ~/.openclaw/akounter/akounter.sqlite
  • AKOUNTER_DEFAULT_CURRENCY: default currency used to seed first-run onboarding. It can be overridden later in akounter-settings.json
  • AKOUNTER_TIMEZONE: IANA timezone used for default timestamps. Default: Asia/Kolkata
  • AKOUNTER_MAX_LIST_LIMIT: maximum rows returned by list/search. Default: 20
  • AKOUNTER_EXPORT_DIR: reserved for future file export support. Default: OPENCLAW_STATE_DIR/.openclaw/akounter/exports when OPENCLAW_STATE_DIR is set, otherwise ~/.openclaw/akounter/exports
  • AKOUNTER_GLM_OCR_API_URL: GLM-OCR endpoint. Default: http://localhost:11434/api/generate
  • AKOUNTER_GLM_OCR_MODEL: GLM-OCR model name. Default: glm-ocr:latest
  • ZHIPU_API_KEY: reserved for alternative GLM-hosted deployments if you adapt the OCR client

Equivalent plugin config keys are available in openclaw.plugin.json: dbPath, defaultCurrency, timezone, maxListLimit, exportDir, and ocr.{apiUrl,model}.

Onboarding

Akounter creates akounter-settings.json in the plugin root on first load. That file stores the one-time onboarding state for:

  • preferred currency code
  • locale
  • numbering system
  • grouping preference
  • currency display mode

If onboarding is still pending, Akounter will ask the user to complete setup before it allows normal ledger actions. Use akounter_setup or akounter_configure_settings to save the chosen values, then akounter_show_settings to inspect the persisted configuration.

OpenClaw Integration

Akounter registers these tools:

  • akounter_add_transaction
  • akounter_setup
  • akounter_configure_settings
  • akounter_update_transaction
  • akounter_delete_transaction
  • akounter_get_transaction
  • akounter_list_transactions
  • akounter_search_transactions
  • akounter_get_balance
  • akounter_ingest_receipt
  • akounter_export_csv
  • akounter_show_settings

Tools with write side effects are registered as optional tools, following OpenClaw guidance for tools that mutate local state.

Examples

Natural language capture examples:

  • sent 100 to Rajesh
  • received 2000 from Arjun
  • paid 450 for lunch
  • got 1200 from client
  • add expense 899 Amazon
  • add income 5000 salary
  • log 250 fuel
  • spent 99 on tea

Typical retrieval examples:

  • show transactions
  • show transactions for Rajesh
  • top 20 transactions
  • search expenses this month
  • what is my balance

OCR Flow

  1. akounter_ingest_receipt accepts an image file path.
  2. GLM-OCR is called through Ollama’s native /api/generate endpoint.
  3. Akounter stores:
    • raw OCR text
    • raw OCR JSON
    • extracted vendor/invoice/date/totals
    • optional line items
  4. One expense transaction is inserted using the receipt total, or subtotal if total is missing.
  5. Low-confidence or partial extraction is still stored with provenance metadata.

Testing

Run the unit test suite:

pnpm test

Run the real OCR integration test against the bundled sample receipt image:

RUN_AKOUNTER_OCR_INTEGRATION=1 pnpm vitest run tests/test_ocr_integration.ts

Requirements for the integration test:

  • Ollama running locally
  • glm-ocr:latest pulled
  • AKOUNTER_GLM_OCR_API_URL pointing at the active GLM-OCR endpoint if you are not using the default http://localhost:11434/api/generate

Export Flow

CSV is never generated during normal listing. Use akounter_export_csv only for explicit export/download/CSV requests. In the current release, Akounter returns a fixed-width WhatsApp/Telegram-safe transaction table instead of a file attachment. Direct CSV file delivery is deferred to a later release.

Limitations

  • The deterministic text parser focuses on compact bookkeeping phrases, not full free-form accounting narratives.
  • PDF receipts must be converted to an image outside the plugin before ingestion.
  • The default OCR flow targets local Ollama-hosted glm-ocr:latest.
  • Balance is computed as total income minus total expense, without multi-currency conversion.
  • CSV file delivery is deferred; explicit export requests currently return a channel-safe text table.

Security Notes

  • SQLite queries are parameterized; no dynamic SQL string interpolation is used for user values.
  • Receipt raw text is retained for auditability, so protect the database file and export directory appropriately.
  • The plugin keeps all ledger state local and does not require an external database.

Future Improvements

  • Richer date phrase parsing for natural language filters
  • Better category normalization and configurable rules
  • Multi-currency reporting is intentionally not supported; all stored currency codes are INR
  • Provider abstraction for non-Ollama GLM-OCR deployments
  • Native CSV/file attachment delivery for channels that support document sends cleanly
  • Contract tests once integrated into a larger in-repo OpenClaw workspace