English | Español | 简体中文 | Português | العربية | Français | Русский
Auditable SMB finance-agent control plane.
Agents can propose finance work; deterministic policy, tenant boundaries, approval gates, and evidence logs decide what can run.
Architecture · What It Does · What It Does Not Do · Install · Usage · Security · Docs
What it does. ClawKeeper is a control plane for finance agents in small and medium businesses. Agents propose accounts payable, accounts receivable, reconciliation, and reporting work; a deterministic policy engine (src/openclaw/policy.ts), PostgreSQL row-level security, approval gates, and a redacted append-only audit log decide what is allowed to run.
Who it serves. Operators and developers who want to put LLM agents on SMB bookkeeping tasks without granting them autonomous money movement or cross-tenant data access: an accounting team running several client tenants, or a builder evaluating guardrail patterns for finance agents.
Why Alex built it. The repository was created on 2026-02-02 (GitHub created_at). The first commit 38226cf (2026-02-02, "feat: initial ClawKeeper MVP release") describes "a production-grade multi-tenant AI agent system that automates bookkeeping, invoice processing, bank reconciliation, and financial reporting for SMBs" with row-level security, RBAC, and audit trails from the start. Later history narrowed the thesis to governance: v1.5 (10f86fa, 2026-05-17, "Release ClawKeeper v1.5 OpenClaw agent infrastructure") and PR #2 (2026-05-27) frame the project as "an OpenClaw-native SMB finance-agent platform with TypeScript-first agents, deterministic policy guardrails, tenant isolation, and auditable financial execution", and PRs #54 and #55 (2026-10-20) moved invoice write authorization and per-request tenant context into database-enforced boundaries.
Real-world use case (2025–2026 evidence). Verified in this repository. An SMB finance operator onboards a tenant, uploads supplier invoices for OCR, and asks agents to schedule payments. Viewer roles are rejected before OCR runs, cross-tenant reads are denied by RLS, and payments above the configured threshold return approval_required instead of executing. This path is exercised by tests/api/invoice-upload-roles.test.ts, tests/api/tenant-database.test.ts (against a real PostgreSQL service in CI), test/openclaw.policy.test.ts, and the four deterministic FDE benchmark scenarios behind npm run fde:benchmark; all demo data is synthetic. The threat model follows the risks catalogued for autonomous agents in the OWASP Top 10 for Agentic Applications for 20261 and the agent-runtime threats described for OpenClaw in 20262. CI exercises the RLS boundary on PostgreSQL 15 while PostgreSQL 18 is the current major release line3, and CI pins Bun 1.3.11 (.github/workflows/ci.yml), from the Bun 1.3 line released in October 20254.
Related research, not an evaluation of this code. arXiv:2603.24414 (Liu et al., 2026-03-25) describes an independent safety framework for OpenClaw agents that is also named ClawKeeper. That paper did not benchmark this repository, and no claim of superior performance is made here; it is cited only as threat-model context. Agent security is continuous, not absolute: prompt injection, cross-tenant leakage, and unsanctioned money movement remain under active research and are not considered solved.
ClawKeeper v2.0 is packaged around an inspectable proof spine:
- Backend quality gate:
npm run quality - Dashboard production build:
cd dashboard && npm run build - Dependency audit:
npm audit --audit-level=moderate - FDE benchmark:
npm run fde:benchmark - Proof bundle validation:
npm run proof:v2:validate - Docker build gate:
.github/workflows/ci.yml
See docs/proof/v2.0/README.md for the v2 proof bundle and verification commands. The proof bundle is deterministic, offline, synthetic, and redacted.
ClawKeeper models a finance department as a three-layer agent hierarchy: one CEO orchestrator, nine domain leads, and 100 specialized workers. Every agent inherits from BaseAgent, which evaluates the OpenClaw policy engine before task execution. No agent touches a high-risk financial workflow without passing deterministic policy checks in code -- not in prompts.
ClawKeeper CEO
(top-level orchestrator)
|
┌──────────────────┼──────────────────┐
| | |
┌──────┴──────┐ ┌─────┴─────┐ ┌───────┴───────┐
| CFO Lead | | AP Lead | | AR Lead |
| (8 workers)| |(15 workers)| | (15 workers) |
└─────────────┘ └───────────┘ └───────────────┘
| | |
┌──────┴──────┐ ┌─────┴─────┐ ┌───────┴───────┐
| Recon Lead | |Compliance | | Reporting |
|(12 workers) | | Lead | | Lead |
| | |(10 workers)| | (12 workers) |
└─────────────┘ └───────────┘ └───────────────┘
| | |
┌──────┴──────┐ ┌─────┴─────┐ ┌───────┴───────┐
|Integration | | Data/ETL | | Support |
| Lead | | Lead | | Lead |
|(12 workers) | |(10 workers)| | (6 workers) |
└─────────────┘ └───────────┘ └───────────────┘
── APPROVAL GATE ──
Every high-risk action (payment, writeback, tax filing,
cross-tenant operation) requires approval metadata before
the policy engine permits execution. The gate is
deterministic code in src/openclaw/policy.ts, not an
LLM judgment call.
The policy layer is deliberately deterministic. It does not ask an LLM whether a payment, writeback, or tenant-crossing action is safe.
Agent requests task execution
│
▼
┌─────────────────────┐ ┌─────────────────┐
│ Tenant isolation │──X──│ DENY: wrong │
│ check │ │ tenant context │
└────────┬────────────┘ └─────────────────┘
│ pass
▼
┌─────────────────────┐ ┌─────────────────┐
│ Capability check │──X──│ DENY: missing │
│ (role + permissions)│ │ capability │
└────────┬────────────┘ └─────────────────┘
│ pass
▼
┌─────────────────────┐ ┌─────────────────┐
│ Prompt-safety scan │──X──│ DENY: injection │
│ (injection, bypass) │ │ attempt detected │
└────────┬────────────┘ └─────────────────┘
│ pass
▼
┌─────────────────────┐ ┌──────────────────┐
│ Risk tier + amount │──?──│ GATE: approval │
│ threshold check │ │ metadata required │
└────────┬────────────┘ └──────────────────┘
│ approved or low-risk
▼
┌─────────────────────┐
│ EXECUTE + emit │
│ redacted audit event│
└─────────────────────┘
Policy implementation: src/openclaw/policy.ts · Runtime adapter: src/openclaw/runtime.ts · Base agent enforcement: src/agents/base.ts
| Domain | Agents | What they handle |
|---|---|---|
| Accounts Payable | 15 | Invoice parsing, OCR validation, three-way matching (PO-invoice-receipt), duplicate detection, approval routing, payment scheduling, vendor management |
| Accounts Receivable | 15 | Customer invoicing, payment matching, collections follow-up, dispute handling, revenue recognition, aging analysis, statement generation |
| Reconciliation | 12 | Bank transaction import via Plaid, fuzzy matching by date/amount/payee, discrepancy investigation, adjustment entries, exception handling |
| Reporting | 12 | P&L, balance sheet, cash flow statements, custom report building, financial ratios, chart generation, scheduled report delivery |
| Integration | 12 | Plaid bank feeds, Stripe payments, QuickBooks sync, Xero sync, OAuth flow management, webhook processing, circuit breakers |
| Compliance | 10 | Tax compliance checks, audit preparation, segregation-of-duties verification, fraud detection, document retention, regulatory reporting |
| Data / ETL | 10 | CSV/Excel/JSON import, schema mapping, data validation, deduplication, enrichment, bulk processing, migration support |
| CFO / Strategic | 8 | Cash flow forecasting, budget management, financial modeling, KPI tracking, variance analysis, risk assessment |
| Support | 6 | Help desk, error diagnosis, recovery, escalation management, onboarding |
Total: 110 agents (1 CEO orchestrator + 9 domain leads + 100 specialized workers).
Naming the failure modes matters more than naming the features.
| Boundary | Why it exists |
|---|---|
| No autonomous financial execution without human approval | Payment processing, accounting-system writes, tax filings, and high-risk operations require explicit approval metadata. The policy engine will deny execution if approval is missing -- even if the agent has the technical capability. This is the most important architectural constraint. |
| No cross-tenant data sharing | Agents are tenant-scoped. The policy engine denies any request where the agent's tenant context does not match the target resource. RLS enforcement in PostgreSQL provides a second boundary at the data layer. |
| No LLM-based security decisions | The policy engine is deterministic TypeScript code, not a prompt. Prompt-injection detection, capability checks, and approval gates are evaluated in src/openclaw/policy.ts before any LLM is invoked. This does not make the system injection-proof -- it reduces the attack surface by removing the LLM from the security decision path. |
| No unredacted audit logging | PII and secrets are redacted from audit events before database persistence. Audit records use PostgreSQL append-only triggers -- once written, they cannot be modified or deleted through the application layer. |
| No unbounded LLM spending | Cost-sensitive LLM client configuration and rate-limit backoff prevent runaway API costs during concurrent multi-agent runs. This mitigates but does not eliminate cost risk in high-volume scenarios. |
git clone https://github.com/Alexi5000/ClawKeeper.git
cd ClawKeeper
bun install
cp .env.example .env# Required
DATABASE_URL=postgresql://clawkeeper:password@localhost:5432/clawkeeper
JWT_SECRET=<random-string-minimum-32-chars>
OPENAI_API_KEY=<your-key> # or ANTHROPIC_API_KEY
# Optional integrations
PLAID_CLIENT_ID= # bank feeds
STRIPE_API_KEY= # payment processing
QUICKBOOKS_CLIENT_ID= # accounting sync
XERO_CLIENT_ID= # accounting syncbun run setup:full # schema, RLS, RBAC, seed data
bun run dev # Hono API server + agent control plane
bun run dashboard:dev # React command centernpm run quality # typecheck + lint + test suiteUse the offline proof path when you want a no-database verification run:
bun install --frozen-lockfile
npm run quality
cd dashboard && npm ci && npm run build
cd ..
npm run fde:benchmark
npm run proof:v2
npm run proof:v2:validate
npm run demo:offlineUse the database-backed demo path when Docker is available:
docker compose up -d postgres
export DATABASE_URL=postgresql://clawkeeper:clawkeeper_local_password@localhost:5432/clawkeeper
npm run demo:db
docker build -t clawkeeper:v2 .The demo data is synthetic. The v2 proof path does not call Plaid, Stripe, QuickBooks, Xero, or live payment rails.
Check whether a proposed agent action would be allowed, approval-gated, or denied -- without executing anything.
curl -X POST http://localhost:4004/api/agents/openclaw/policy/evaluate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
"agentId": "payment-processor",
"capability": "process_payment",
"tenantId": "tenant_001",
"amount": 15000,
"approvalMetadata": null
}'
# Response: { "decision": "approval_required", "reason": "amount exceeds threshold", ... }curl http://localhost:4004/api/agents/openclaw/manifest \
-H "Authorization: Bearer $TOKEN"
# Returns: full agent registry, capabilities, risk tiers, approval rulescurl -X POST http://localhost:4004/api/invoices/upload \
-H "Authorization: Bearer $TOKEN" \
-F "file=@invoice.pdf"
# Triggers: OCR extraction → line-item validation → duplicate check
# → expense categorization → approval routing
# Failure mode: OCR sum-matching guardrail will reject the invoice
# if line-item totals do not match the stated total.The backend uses bun.lock as its canonical dependency lock for development, CI, Docker, and Dependabot. The dashboard independently uses dashboard/package-lock.json with npm ci. CI retains the full typecheck, lint, test, FDE, build, and moderate-severity dependency audit gates.
Agent security is a continuous practice, not a shipped feature. The ClawKeeper threat model focuses on the attack surfaces specific to autonomous financial agents: prompt injection, cross-tenant leakage, unsanctioned money movement, and audit tampering.
| Guardrail | Implementation | Known limitation |
|---|---|---|
| Tenant isolation | Policy engine + PostgreSQL RLS | RLS bypass is possible if raw SQL access is granted outside the application layer |
| Approval gates | Deterministic policy checks in src/openclaw/policy.ts |
Approval metadata is trusted once provided -- the approval workbench is roadmap v2.1 |
| Prompt-injection denial | Pattern-matching guardrails evaluated before LLM invocation | Pattern-based detection does not catch novel injection techniques; this is an active research area |
| Audit immutability | PostgreSQL append-only triggers; PII/secret redaction before write | Database-level bypass (direct SQL) can circumvent triggers; mitigated by network access controls |
| OCR validation | Programmatic sum-matching of line items vs. stated totals | Adversarial invoices designed to pass sum checks while containing incorrect individual line items are a known gap |
| Rate-limit resilience | Exponential backoff retry on 429/transient errors | Backoff caps exist but sustained rate limiting during peak concurrency can degrade agent throughput |
Related research (independent framework with the same name, not an evaluation of this code): arXiv:2603.24414 · Security model: docs/SECURITY_MODEL.md · Vulnerability reports: SECURITY.md
GET /health # liveness
POST /api/auth/login # JWT authentication
POST /api/auth/register # tenant registration
GET /api/agents # agent registry
GET /api/agents/openclaw/manifest # OpenClaw manifest inspection
POST /api/agents/openclaw/policy/evaluate # dry-run policy evaluation
GET /api/invoices # invoice list
POST /api/invoices/upload # OCR invoice processing
POST /api/reconciliation/start # bank reconciliation
GET /api/reports/:type # financial reports
WS /ws # real-time agent events
The test suite validates the parts of the system that matter for a finance-agent release: manifest correctness, policy decisions, approval requirements, tenant isolation, prompt-injection denial, and audit redaction. Dashboard behavior tests are secondary. As of 2026-10-20 npm test runs 164 tests in 41 suites; 163 pass and the PostgreSQL-backed RLS suite is skipped unless RLS_TEST_DATABASE is set (CI provides it).
npm run typecheck # TypeScript strict mode
npm run lint # ESLint
npm test # OpenClaw manifest + policy tests
npm run quality # all three, sequential
npm run fde:benchmark # deterministic finance-agent benchmark
npm run proof:v2:validate # proof bundle validation| Test file | What it validates |
|---|---|
test/openclaw.manifest.test.ts |
App identity, agent registration, high-risk capability policy, runtime adapter health |
test/openclaw.policy.test.ts |
Autonomous reporting, approval-required payment flows, tenant isolation denial, missing capability denial, prompt-injection denial, audit redaction |
test/schema-records.test.ts |
Database schema record contracts |
tests/api/*.test.ts |
Invoice upload role enforcement, per-request tenant database context against PostgreSQL (skipped locally without RLS_TEST_DATABASE), health route, WebSocket events |
tests/agents/*, tests/guardrails/*, tests/memory/*, tests/services/*, tests/integrations/* |
Orchestrator and worker behavior, validators, pgvector semantic search, OCR service, Molten bridge, observability |
tests/fde/*.test.ts |
Finance-agent (FDE) contracts and harness |
tests/dependency-compatibility.test.ts |
Runtime lock and chart API compatibility |
ClawKeeper/
├── src/
│ ├── agents/ # CEO, orchestrator, worker, BaseAgent execution
│ ├── api/ # Hono server, finance + control-plane routes
│ ├── core/ # Types, LLM client, observability, scheduling
│ ├── guardrails/ # Validation, PII detection, injection checks
│ ├── integrations/ # Plaid, Stripe, QuickBooks, Xero, Document AI
│ ├── memory/ # Agent memory and context primitives
│ └── openclaw/ # Manifest, policy engine, runtime adapter
├── agents/ # 110 AGENT.md definitions (CEO + leads + workers)
├── test/ # OpenClaw manifest + policy tests
├── dashboard/ # React/Vite/Tailwind command center
├── db/ # PostgreSQL schema, RLS, RBAC, seed data
├── docs/ # Architecture, security model, API, deployment
└── skills/ # Finance skill definitions
| Document | Purpose |
|---|---|
docs/README.md |
Current documentation index |
docs/ARCHITECTURE.md |
System architecture and agent hierarchy |
docs/SECURITY_MODEL.md |
OpenClaw agent boundary, approval gates, finance guardrails |
docs/proof/v2.0/README.md |
v2 proof bundle and verification commands |
docs/API.md |
API reference |
docs/DEPLOYMENT.md |
Deployment guidance |
docs/MULTI-TENANCY.md |
Tenant isolation and RBAC model |
AGENTS.md |
Full 110-agent index with hierarchy |
SECURITY.md |
Vulnerability reporting policy |
CONTRIBUTING.md |
Contribution workflow |
CONTRIBUTORS.md |
Contributor acknowledgments |
| Version | Direction | Open risk |
|---|---|---|
| v2.1 | Approval workbench -- human approval queue, reviewer comments, immutable approval evidence in dashboard | Approval UX latency for high-volume AP operations |
| v2.2 | Integration hardening -- contract tests for Plaid, Stripe, QuickBooks, Xero adapters | Third-party API schema drift between test and production |
| v2.3 | Runtime expansion -- distributed agent scheduling, tool sandboxing, execution replay | Replay fidelity when external system state has changed |
| v3.0 | Finance autopilot -- end-to-end workflows combining approvals, reconciliation, reporting, and writeback | Compounding error rates across multi-step agent chains |
MIT. See LICENSE.
Alex Cinovoj, Founder & CTO of TechTide AI · Columbus, Ohio
For production deployment, security review, or integration support: techtideai.io
Footnotes
-
OWASP Gen AI Security Project, "OWASP Top 10 for Agentic Applications for 2026", published 2025-12-09. https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/ ↩
-
Liu et al., "ClawKeeper: Comprehensive Safety Protection for OpenClaw Agents Through Skills, Plugins, and Watchers", arXiv:2603.24414, 2026-03-25. https://arxiv.org/abs/2603.24414 ↩
-
PostgreSQL Global Development Group, "PostgreSQL 18 Released!", 2025-09-25. https://www.postgresql.org/about/news/postgresql-18-released-3142/ ↩
-
Bun, "Bun 1.3", 2025-10-10. https://bun.com/blog/bun-v1.3 ↩