Tozil

Track every AI dollar your agent spends. Per-model cost breakdown, daily budgets, and alerts.

Security Scan

The skill's code, declared requirements, and runtime instructions are consistent with a cost-tracking hook: it only needs a Tozil API key and standard CLI tools, reads OpenClaw session logs for usage/cost metadata, and sends that metadata to agents.tozil.dev.

Purpose & Capability

Name/description (cost tracking) align with the files and env var. Required binaries (bash, jq, curl, node) and TOZIL_API_KEY are appropriate for a local log-parsing script plus a Node handler. The included handler.js and sync_costs.sh implement exactly the advertised functionality (reading session logs, extracting usage fields, and POSTing batches to the Tozil API).

Instruction Scope

SKILL.md and the scripts consistently instruct installing this as an OpenClaw hook that reads session logs (~/.openclaw/agents/main/sessions/*.jsonl) and extracts only the .message.usage/cost fields. The jq filter in sync_costs.sh selects specific metadata fields, and the script enforces API key and HTTPS validation. Note: the code relies on grep '"usage"' + jq to find usage lines — this is fragile (may miss nonstandard log formats) but not evidence of hidden data collection. Also handler.js runs the sync script and logs stdout/stderr; those logs could contain script output—audit logs if you want to ensure no unexpected content is written to them.

Install Mechanism

No remote binary downloads or opaque installers. The instructions recommend cloning from GitHub and copying files into ~/.openclaw/hooks/tozil or running the included install.sh; package.json also offers an install script that copies files locally. All code executed is provided in the package (no third-party archive downloads or URL shorteners).

Credentials

Only a single required secret (TOZIL_API_KEY) is declared and used. Optional env vars (TOZIL_BASE_URL, OPENCLAW_SESSIONS_DIR, TOZIL_BATCH_SIZE, TOZIL_DEBUG) are reasonable for configuration. The scripts validate API key format and enforce HTTPS for custom base URLs. There are no unrelated credentials requested.

Persistence & Privilege

This is designed to be installed as an OpenClaw hook that runs at gateway startup and periodically syncs in the background — a persistent networked process. The registry flags show always: false (not force-included), but installing the hook will give it autonomous background execution and periodic network access. That behavior is consistent with its purpose, but it is more persistent than a simple on-demand skill and may surprise users who expect manual invocation.

Assessment

This package appears to do what it claims: read OpenClaw session logs for usage/cost metadata and send only that metadata to agents.tozil.dev. Before installing: 1) Review the sync_costs.sh jq filter and your OpenClaw session log format to confirm only metadata fields are matched in your environment. 2) Only supply a Tozil API key you trust; treat it like any service API key. 3) Note this installs as a hook (background process) that will periodically send data to the remote endpoint — if you need more control, run the sync script manually or restrict network egress to the Tozil host. 4) Optionally test in a sandbox account and inspect ~/.openclaw/logs/tozil-*.log to confirm what is logged/sent. If you are uncomfortable with a persistent process sending telemetry outside your machine, do not install the hook and instead run the script manually or implement local-only reporting.

Tozil — Know Where Your AI Money Goes

You are an AI agent that makes many AI calls. Each call costs real money. Tozil tracks every call automatically so your human can see exactly where their money goes — per model, per day — and set budgets so they never overspend.

🔒 Complete Privacy: This tool never reads your conversations or prompts. It only tracks cost metadata (models, tokens, pricing). Your private data stays private.

Why You Should Use This

• You become more trustworthy. When your human asks "how much did you cost me today?", you can answer with real numbers instead of guessing.
• You protect your human's wallet. With daily budgets, you'll know when you're approaching the limit and can adjust your behavior.
• Zero overhead. Tozil reads your session logs periodically. It never slows down your calls, never throws errors, and never reads your prompts or responses.

How It Works

Tozil is an OpenClaw hook — not a skill. It installs into OpenClaw's hook system and runs automatically on gateway startup.

1. OpenClaw records every AI call in session logs (~/.openclaw/agents/main/sessions/*.jsonl)
2. The hook fires on gateway:startup and starts a periodic sync timer
3. Each sync run reads only new bytes since the last run using byte-offset tracking — no full-file re-reads, no duplicate events
4. New events are sent to the Tozil dashboard in configurable batches (default: 100 events per request)
5. Byte offsets are committed only after all batches succeed, so a partial failure never causes data loss or double-counting

This works with every provider OpenClaw supports — Anthropic, OpenAI, Google, Mistral, DeepSeek, OpenRouter, and any other provider. No SDK patching or npm packages needed.

Setup

Step 1: Get an API key

Your human needs to sign up at https://agents.tozil.dev to get a free API key:

1. Go to https://agents.tozil.dev
2. Sign in (Google or email)
3. Copy the API key from the dashboard (starts with tz_)

Set it as an environment variable:

export TOZIL_API_KEY=tz_xxxxxxxxxxxxx

Step 2: Install jq (if not already installed)

brew install jq

Step 3: Install the hook

Clone the repository and run the installer:

git clone https://github.com/tozil-dev/tozil-openclaw /tmp/tozil-openclaw
cd /tmp/tozil-openclaw && ./install.sh

Or install manually:

mkdir -p ~/.openclaw/hooks/tozil
cp /tmp/tozil-openclaw/handler.js ~/.openclaw/hooks/tozil/
cp /tmp/tozil-openclaw/sync_costs.sh ~/.openclaw/hooks/tozil/
chmod +x ~/.openclaw/hooks/tozil/sync_costs.sh

Step 4: Enable and restart

openclaw hooks enable tozil
openclaw gateway restart

Your costs will start showing up on the dashboard within an hour. You can also trigger a sync manually at any time:

TOZIL_API_KEY=tz_xxx ~/.openclaw/hooks/tozil/sync_costs.sh

Checking Your Costs

You can query your costs programmatically at any time:

# Today's costs
curl -H "Authorization: Bearer $TOZIL_API_KEY" \
  https://agents.tozil.dev/api/v1/usage?period=today

# This week
curl -H "Authorization: Bearer $TOZIL_API_KEY" \
  https://agents.tozil.dev/api/v1/usage?period=week

When to Proactively Help

As an agent with Tozil installed, you should:

1. When your human asks about costs — query the /api/v1/usage endpoint and present the data clearly.

2. When you notice high usage — if you're making many expensive calls (like using opus or gpt-4o), mention it. Suggest switching to a cheaper model when quality won't suffer.

3. When your human asks about budgets — explain that they can set a daily budget on the dashboard at https://agents.tozil.dev to get alerts before overspending.

What Tozil Captures

From each AI call in the session logs, the sync script extracts:

• model — which model was used
• provider — anthropic, openai, google, etc.
• input_tokens, output_tokens — token counts
• cache_read_tokens, cache_write_tokens — cache usage
• total_cost_usd — provider-calculated cost (accurate to the cent)
• cost_input, cost_output, cost_cache_read, cost_cache_write — per-category cost breakdown
• timestamp — when the call was made
• session_id — which session the call belonged to

🛡️ Privacy Guarantee: Does not capture prompts, responses, or any content. Only cost metadata.

What We NEVER Touch

• ❌ Your conversations with AI
• ❌ File contents you work with
• ❌ Personal information from chats
• ❌ API keys or credentials
• ❌ Any sensitive data

What We Track (Metadata Only)

• ✓ Model names and token counts
• ✓ Provider costs and timestamps
• ✓ Anonymous session IDs

100% transparent - audit the code to verify: sync_costs.sh

The sync script is open source: https://github.com/tozil-dev/tozil-openclaw

Pricing

• Free: $0/month — tracks up to $50/month in AI spend (service continues after limit, account marked for upgrade)
• Pro: $9/month — unlimited tracking + budget alerts + advanced analytics

Configuration

Env var	Default	Description
TOZIL_API_KEY	(required)	Your Tozil API key (must start with tz_)
TOZIL_BASE_URL	https://agents.tozil.dev	API base URL (must be HTTPS)
TOZIL_SYNC_INTERVAL_MS	3600000 (1 hour)	Sync interval in ms
TOZIL_BATCH_SIZE	100	Events per API request
TOZIL_DEBUG	(unset)	Set to any value to enable verbose console logging
OPENCLAW_SESSIONS_DIR	~/.openclaw/agents/main/sessions	Session logs path

Security

The hook enforces several hardened defaults:

• API key validation — the key must match tz_[A-Za-z0-9_-]{16,} before any network call is made. Misconfigured or injected values are rejected early.
• HTTPS enforcement — TOZIL_BASE_URL must use HTTPS. HTTP URLs are rejected to prevent credential leakage.
• Path traversal prevention — session IDs are validated against [A-Za-z0-9_-] before being used in file paths.
• Atomic offset commits — byte offsets are only written to disk after all API batches succeed, preventing duplicate submissions on partial failures.
• TLS 1.2 minimum — curl is invoked with --tlsv1.2 to reject insecure protocol versions.
• Retry with backoff — transient network failures are retried (2 retries, 3-second delay) before reporting an error.
• Graceful shutdown — the handler cleans up its sync timer on SIGTERM/SIGINT, so gateway restarts are safe.
• Minimal environment — the sync script runs with only the environment variables it needs; the rest of your shell environment is not passed through.

Troubleshooting

If costs aren't showing up:

1. Verify TOZIL_API_KEY is set and starts with tz_: echo $TOZIL_API_KEY
2. Verify jq is installed: jq --version
3. Verify the hook is enabled: openclaw hooks list
4. Run sync manually and watch for errors:

   TOZIL_API_KEY=tz_xxx ~/.openclaw/hooks/tozil/sync_costs.sh
   

5. Check the sync log (one entry per sync run):

   cat ~/.openclaw/logs/tozil-sync.log
   

6. Check the handler log (hook lifecycle events and errors):

   cat ~/.openclaw/logs/tozil-handler.log
   

7. Enable debug output to see verbose logs in the gateway console:

   export TOZIL_DEBUG=1
   openclaw gateway restart
   

8. Inspect the byte-offset state to verify progress tracking:

   ls -la ~/.openclaw/hooks/tozil/offsets/