OpenClaw Tax Plugin — AI Agent Tax Filing Integration

What is OpenClaw?

OpenClaw is an open protocol for composable AI-agent plugins. Agents discover tools via a standard manifest, invoke them over HTTP, and receive results as structured JSON or streamed SSE events.

The OpenTax plugin exposes the full tax engine through this protocol. An agent can create a return, feed it income data, compute results, and trace any number—all through tool calls, with no UI required.

Installation

Start the plugin server and register it with your agent.

Start the plugin server


            $ git clone https://github.com/opentax-org/opentax.git

            $ cd opentax

            $ npm install

            $ npm run server

            

            # Plugin manifest at http://localhost:7891/.well-known/openclaw.json


            # In your OpenClaw agent config, add the plugin URL:

            "plugins": [

              { "url": "http://localhost:7891" }

            ]

The agent will auto-discover all 16 tax tools from the manifest and make them available in conversation.

Agent tools

The plugin exposes 16 tools organized into four groups. Each tool accepts JSON input and returns structured JSON output.

1 Return lifecycle

Tool	Description
create_return	Create a new tax return for a given tax year and filing status.
get_return	Retrieve the current state of a return by ID.
delete_return	Delete a return and all associated data.
list_returns	List all returns managed by this plugin instance.

2 Data input

Tool	Description
set_filing_status	Set filing status (Single, MFJ, MFS, HoH, QSS).
add_w2	Add W-2 wage data (employer, wages, withholding, etc.).
add_1099	Add 1099 income (INT, DIV, B, R subtypes supported).
add_dependent	Add a dependent (name, SSN, relationship, qualifying tests).
set_deductions	Set itemized deduction amounts or elect standard deduction.
set_credits	Set credit-related data (education expenses, child care, etc.).

3 Computation

Tool	Description
compute	Run the rules engine on the current return data. Returns full Form 1040 + schedules.
get_summary	Get a human-readable summary: AGI, taxable income, total tax, refund/owed.
trace_line	Trace any computed line back to its inputs, IRS citations, and source documents.

4 Export

Tool	Description
generate_pdf	Generate IRS-ready PDF forms. Returns a download URL.
export_json	Export the full return as structured JSON for archival or downstream processing.
get_dashboard	Get a dashboard snapshot: completion progress, warnings, and next suggested action.

Example agent conversation

Here's what a typical agent ↔ plugin exchange looks like.

I made $85,000 from my W-2 and $1,200 in bank interest. I'm filing as single.

tool: create_return { year: 2025, status: "single" }
tool: add_w2 { wages: 85000, fedWithholding: 12750 }
tool: add_1099 { type: "INT", amount: 1200 }
tool: compute
tool: get_summary

Your return is computed. Here's the summary:

Adjusted Gross Income …… $86,200
Standard Deduction ……… $15,000
Taxable Income ………… $71,200
Total Tax ……………… $11,734
Refund …………………… $1,016

Would you like me to trace how any of these numbers were calculated?

TaxService API

For deeper integrations, import TaxService directly in Node.js. No HTTP server needed.

Node.js


import { TaxService } from 'opentax/services/TaxService';



// Create a return and feed it data

const svc = new TaxService();

const ret = svc.createReturn({ year: 2025, status: 'single' });



svc.addW2(ret.id, { wages: 85_000, fedWithholding: 12_750 });

svc.add1099(ret.id, { type: 'INT', amount: 1_200 });



// Compute and trace

const result = svc.compute(ret.id);

const trace  = svc.traceLine(ret.id, 'form1040.line24');



console.log(result.summary);  // { agi, taxableIncome, totalTax, refund }

console.log(trace.tree);     // Full trace tree with IRS citations

SSE streaming

Long-running computations (complex returns with many schedules) stream progress via Server-Sent Events so agents can show real-time status.

computation:start

Fired when the engine begins processing a return.

computation:progress

Emitted per-form as each schedule completes. Includes form name and percent.

computation:complete

Final event with the full computed result and trace tree.

SSE stream

GET /api/returns/{id}/compute/stream
Accept: text/event-stream

event: computation:start
data:  { "returnId": "abc-123" }

event: computation:progress
data:  { "form": "1040", "percent": 40 }

event: computation:progress
data:  { "form": "scheduleD", "percent": 75 }

event: computation:complete
data:  { "summary": { "agi": 86200, "totalTax": 11734, ... } }

REST API

Every agent tool has a corresponding REST endpoint for direct HTTP integration.

Method	Endpoint	Description
POST	/api/returns	Create a new return
GET	/api/returns/:id	Get return by ID
POST	/api/returns/:id/w2	Add W-2 data
POST	/api/returns/:id/1099	Add 1099 data
POST	/api/returns/:id/compute	Run computation
GET	/api/returns/:id/trace/:line	Trace a specific line
GET	/api/returns/:id/pdf	Download generated PDF

OpenClaw Plugin