ClawHub
Code Pluginsource linked

Akounterv0.1.0

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

akounter·runtime akounter·by @webtamizhan
Community code plugin. Review compatibility and verification before install.
openclaw plugins install clawhub:akounter
Latest release: v0.1.0Download zip

Capabilities

Tags
executes-code
configSchema
Yes
Executes code
Yes
HTTP routes
0
Runtime ID
akounter

Compatibility

Built With Open Claw Version
2026.3.24-beta.2
Min Gateway Version
2026.3.24-beta.2
Plugin Api Range
>=2026.3.24-beta.2
Plugin Sdk Version
2026.3.24-beta.2
Security Scan
VirusTotalVirusTotal
Benign
View report →
OpenClawOpenClaw
Benign
high confidence
✓
Purpose & Capability
Name/description (SQLite ledger + GLM‑OCR receipt ingestion) match the included code, tests, and SKILL.md. Declared config keys and optional env vars (dbPath, exportDir, AKOUNTER_GLM_OCR_API_URL, etc.) are appropriate and expected for the described functionality. The plugin registers ledger CRUD and OCR ingestion tools that align with the stated purpose.
✓
Instruction Scope
The SKILL.md runtime instructions are narrowly scoped: create a local settings file, persist a local SQLite DB, accept images for OCR ingestion, call a GLM‑OCR endpoint, and only export CSV on explicit user request. The instructions do not ask the agent to read unrelated system files or credentials. Note: OCR ingestion explicitly sends receipt image data to the configured AKOUNTER_GLM_OCR_API_URL, so the destination determines whether receipt data leaves the host.
ℹ
Install Mechanism
There is no special install spec in the plugin manifest, but the README/SKILL.md instructs running `pnpm install` in the plugin root. That will fetch packages from registries (the repository includes a pnpm-lock.yaml). The lockfile shows many dependencies pulled via the environment (likely from OpenClaw SDK dependencies) — this is expected but means network activity and multiple packages will be installed. There are no downloads from arbitrary URLs or archive extraction steps in the plugin itself.
✓
Credentials
No required secrets are declared. Optional env vars are proportional to the plugin (DB path, timezone, max list limit, OCR API URL/model). The presence of `ZHIPU_API_KEY` as an optional/alternate provider key is reasonable for alternate hosted OCR providers, but if you set a non-local AKOUNTER_GLM_OCR_API_URL or provide a hosted API key, receipt images and raw OCR text will be transmitted to that external service — consider the privacy implications.
✓
Persistence & Privilege
The plugin is not always-enabled and follows normal OpenClaw invocation rules. It persistently writes its own files (SQLite DB, akounter-settings.json, future export files) under the plugin root / OPENCLAW_STATE_DIR; this is expected for a ledger. It does not request system-wide privileges or modify other skills' configs.
Assessment
This plugin appears to do what it says: local SQLite ledger and OCR ingestion. Before installing: - Be aware that running `pnpm install` will download many packages from public registries (normal but network-active). Inspect the lockfile if you audit installs. - By default OCR is pointed to a local Ollama endpoint (http://localhost:11434). If you change AKOUNTER_GLM_OCR_API_URL to a remote service or provide a hosted API key (e.g., ZHIPU_API_KEY), your receipt images and extracted OCR text will be sent off-host — only do that to services you trust. - The plugin writes akounter-settings.json and the SQLite file under the plugin root / OPENCLAW_STATE_DIR; protect those files because they contain raw receipt text and ledger data. - If you need stricter guarantees, review the src/ocr client implementation to confirm exactly what metadata and fields are sent to the OCR endpoint and test using a local Ollama instance first.
!
src/ocr.ts:2
File read combined with network send (possible exfiltration).
About static analysis
These patterns were detected by automated regex scanning. They may be normal for skills that integrate with external APIs. Check the VirusTotal and OpenClaw results above for context-aware analysis.

Verification

Tier
source linked
Scope
artifact only
Summary
Validated package structure and linked the release to source metadata.
Source
github.com/webtamizhan/akounter
Commit
https://gith
Tag
main
Provenance
No
Scan status
clean

Tags

latest
0.1.0

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