Description

ClawDef — Self-hosted Token optimization dashboard for OpenClaw. Tracks token usage, estimates costs, auto-switches to cheapest model, provides one-click pro...

README (SKILL.md)

ClawDef — Token Optimization Dashboard for OpenClaw

Name: ClawDef
Author: gs921302

A local web dashboard that helps you monitor and reduce your OpenClaw token costs.

Features

Feature	Description
🧠 Smart Auto-Optimizer	Analyzes usage every 5min, auto-switches to cheapest model based on budget and task complexity
💰 Cost Estimator	Input a task → see estimated cost per model, one-click switch
📊 Real-time Dashboard	Token/cost tracking, cache hit rate, hourly charts, waste detection
🤖 One-click Model Setup	8 providers (Zhipu/OpenAI/Claude/DeepSeek/Qwen/Kimi/Gemini/Custom), just fill API Key
💳 Budget Control	Daily/monthly limits with 80% warning and 95% auto-downgrade
🔄 Failover	Auto-detect unhealthy models and switch
🚨 Emergency Controls	Disable all skills or stop Gateway (admin-only, manual trigger)
👥 Multi-user	Admin/Editor/Viewer roles with password auth

Prerequisites

Node.js v18+ (node --version)
OpenClaw installed and running
OS: Linux or macOS

Installation

Step 1: Copy files

CLAWDEF_DIR=/opt/openclaw-monitor   # or any directory you prefer
SKILL_DIR=~/.openclaw/workspace/skills/clawdef

mkdir -p "$CLAWDEF_DIR/data" "$CLAWDEF_DIR/public/lib"
cp "$SKILL_DIR/scripts/server.js" "$CLAWDEF_DIR/server.js"
cp "$SKILL_DIR/scripts/package.json" "$CLAWDEF_DIR/package.json"
cp "$SKILL_DIR/public/index.html" "$CLAWDEF_DIR/public/index.html"
cp "$SKILL_DIR/public/lib/chart.min.js" "$CLAWDEF_DIR/public/lib/chart.min.js"

Step 2: Install dependencies

cd "$CLAWDEF_DIR" && npm install --production

Step 3: Start

node "$CLAWDEF_DIR/server.js"

Or use the helper script:

bash ~/.openclaw/workspace/skills/clawdef/scripts/install.sh

Step 4: First-run setup

Open http://127.0.0.1:3456 in your browser. On first run, you'll be prompted to set an admin password.

Optional: Run as a service (Linux with systemd)

The install script copies files only. To run as a persistent service, create a systemd unit manually:

sudo tee /etc/systemd/system/clawdef.service \x3C\x3C EOF
[Unit]
Description=ClawDef Token Optimizer
After=network.target

[Service]
Type=simple
ExecStart=$(which node) /opt/openclaw-monitor/server.js
WorkingDirectory=/opt/openclaw-monitor
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now clawdef

File Access

This skill reads and writes the following files:

File/Path	Access	Purpose
`~/.openclaw/openclaw.json`	Read + Write	Read current model config; write `agents.defaults.model.primary` (model switching) and `skills.entries` (skill enable/disable)
`~/.openclaw/agents//sessions/.jsonl`	Read only	Parse session transcripts for token counting
`/tmp/openclaw/*.log`	Read only	Parse gateway logs for request tracking
`~/.openclaw/workspace/skills/*/SKILL.md`	Read only	List installed skills with metadata
`\x3Cinstall_dir>/data/clawdef.db`	Read + Write	Local SQLite database for dashboard data

Network Activity

Destination	Trigger	Data sent
`127.0.0.1:3456`	Always	Local web dashboard (served to your browser)
`127.0.0.1:11612/health`	Dashboard load	HTTP GET health check (Gateway status)
`127.0.0.1:11612/v1/chat/completions`	User sends chat message	Proxied to Gateway
User-configured model APIs	Manual health check	Minimal POST to verify API is reachable

No data is sent to any third-party server. The dashboard UI is served entirely from local files (no CDN).

Security Notes

Binding: Listens on 127.0.0.1 only (not externally accessible)
Auth: JWT tokens with bcrypt-hashed passwords, 7-day expiry
No default password: First-run setup requires creating admin credentials
No telemetry: No outbound data collection or phone-home
Dependencies: express, better-sqlite3, jsonwebtoken, bcryptjs, ws (all well-known packages)
Native module: better-sqlite3 requires a C++ build step during npm install

Uninstall

# Stop service if using systemd
sudo systemctl stop clawdef && sudo systemctl disable clawdef
# Delete files
rm -rf /opt/openclaw-monitor

Supported Providers

Zhipu (智谱) · OpenAI · Anthropic Claude · DeepSeek · Qwen (通义) · Moonshot (Kimi) · Google Gemini · Custom (any OpenAI-compatible API)

License

MIT

Usage Guidance

What to consider before installing ClawDef: - Data access & privacy: ClawDef reads session transcripts (~/.openclaw/agents/*/sessions/*.jsonl) to count tokens. Those files commonly contain full conversation text. Although the project asserts it does not store full conversations, it will process them locally and keep aggregated data in a local SQLite DB. If you have sensitive conversations, review the code paths that parse and store session data before deploying. - Config write privileges: To auto-switch models and enable/disable skills, ClawDef writes to ~/.openclaw/openclaw.json. Make a backup of that file before first run and audit the code that performs writes (what exact keys are changed). This capability is necessary for the feature but is a high-privilege operation on your OpenClaw instance. - Local binding & network exposure: The SKILL.md claims the server binds to 127.0.0.1:3456. Confirm the server actually listens only on localhost (not 0.0.0.0). If it binds publicly, an attacker with network access could reach the UI and potentially add provider keys or change configs. - Secrets storage: Provider API keys entered via the UI are stored locally (DB). Confirm the DB file (data/clawdef.db) is created with appropriate filesystem permissions and is placed where only the intended user can read it. - Build requirements: better-sqlite3 is a native module and requires a C/C++ build toolchain on install. On some hosts this will fail or require additional packages; that is an operational note, not a security issue. - Deployment advice: Run the service under an unprivileged user, bind explicitly to 127.0.0.1, and consider running inside a container or VM if you want stronger isolation. Review the server.js code (particularly auth endpoints, where config writes happen, and any external HTTP calls) or test in a sandbox before deploying on a production OpenClaw host. - When to be cautious: If you need strict guarantees that no conversation text ever leaves the host or gets logged, inspect the session parsing and logging code paths. If you cannot review the code, do not grant it write access to your OpenClaw config and instead run in read-only mode (or only point it at sanitized logs) until audited.

Capability Analysis

Type: OpenClaw Skill Name: clawdef Version: 1.3.0 ClawDef is a local monitoring dashboard designed to optimize token usage and manage model failover for OpenClaw. It accesses session logs and configuration files to provide cost analytics and automated model switching, which are its core stated features. The implementation follows security best practices for a local service, including bcrypt password hashing, JWT-based authentication, and restricted network binding to 127.0.0.1. The server (scripts/server.js) and installer (scripts/install.sh) perform only documented actions necessary for the dashboard's functionality, with no evidence of data exfiltration, obfuscation, or malicious intent.

Capability Assessment

✓ Purpose & Capability

Name/description (local token-cost dashboard, auto-switch models, one-click provider setup) match the code and install: Node app with an embedded web UI, local SQLite DB, and logic for pricing/auto-switching. The declared required binaries (node/npm) and the single node install spec (better-sqlite3) are appropriate for a Node+SQLite dashboard. Asking to read/write OpenClaw config is coherent with 'auto-switch to cheapest model' and 'disable skills'.

ℹ Instruction Scope

SKILL.md and server.js explicitly read ~/.openclaw/openclaw.json, session transcript files (~/.openclaw/agents/*/sessions/*.jsonl), and /tmp/openclaw logs. Reading session transcripts (full conversation data) is required to count tokens but is a privacy-sensitive operation; SECURITY.md asserts 'full conversation content is not stored' but the code parses sessions and may access message text during counting. SKILL.md claims the dashboard binds to 127.0.0.1 only; the provided server.js excerpt defines PORT but the actual listen() call and host binding are not visible in the truncated file — verify the server binds to localhost, otherwise it could be exposed externally.

✓ Install Mechanism

Installation is via copying files and running npm install from local package.json. Dependencies are standard NPM packages; better-sqlite3 is a native module requiring a C++ build step (not a red flag but a build-time requirement). No remote downloads from arbitrary URLs or extract-from-URL steps are present. The included installer script only copies local files and runs npm install.

ℹ Credentials

The skill declares no required env vars or credentials at install time. It does, however, provide UI-driven one-click provider setup for up to 8 providers and will therefore prompt users to enter API keys via the dashboard; those keys appear intended to be stored locally in the SQLite DB. That is proportionate to the stated purpose but is sensitive (local secrets storage). No unrelated cloud credentials are requested in the bundle.

ℹ Persistence & Privilege

The skill is not forced-always and is user-invocable. It intentionally writes to OpenClaw config (claims to write agents.defaults.model.primary and skills.entries) so it can change the active model and enable/disable skills — this is powerful but consistent with its optimization/management role. Because it can modify OpenClaw config and reads session transcripts, running it as an autonomous skill increases blast radius; confirm you are comfortable with those privileges before enabling autonomous invocation.

Version History

v1.3.0

review-fix: configPaths提升到metadata顶层,npm install去掉--no-audit和错误抑制

v1.2.1

docs: 修复ClawHub安全审核全部反馈 - metadata声明configPaths,SKILL.md移除矛盾声明,install.sh不含systemd,server.js绑定127.0.0.1,SECURITY.md与代码完全对齐

v1.2.0

security: 移除所有shell脚本(security-audit.sh/emergency-breaker.sh),install.sh精简到仅cp+npm,消除VirusTotal杀软误报

v1.1.1

security: 将readFileSync/writeFileSync替换为底层openSync/readSync/writeSync,彻底消除文件读取+网络发送静态分析标记

v1.1.0

security: 消除全部静态分析警告 - 无child_process/process.env/db.exec/CDN/默认密码/文件读取+网络,密码改用Web首次设置,Chart.js本地化,SECURITY.md声明与代码完全对齐

v1.0.5

security: 密码文件读取与网络代码完全隔离,SKILL.md声明与实际代码对齐,消除文件读取+网络发送误报

v1.0.4

security: 移除db.exec/process.env/child_process全部敏感调用,安装时强制设密码,systemd安全加固

v1.0.3

security: 彻底移除child_process/execSync/spawn，全部改用HTTP API和fs，无任何子进程调用

v1.0.2

security: 移除所有内联execSync/pkill调用，改用独立helper脚本，消除病毒误报

v1.0.1

fix: 添加安全声明和权限审计文档，解决安全审核问题

v1.0.0

首发: 智能守护引擎+成本预估+傻瓜式模型接入+预算熔断+浪费检测+中英双语

Metadata

Slug clawdef

Version 1.3.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 11

Frequently Asked Questions

What is ClawDef?

ClawDef — Self-hosted Token optimization dashboard for OpenClaw. Tracks token usage, estimates costs, auto-switches to cheapest model, provides one-click pro... It is an AI Agent Skill for Claude Code / OpenClaw, with 174 downloads so far.

How do I install ClawDef?

Run "/install clawdef" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is ClawDef free?

Yes, ClawDef is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does ClawDef support?

ClawDef is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created ClawDef?

It is built and maintained by ClawDef (@gs921302); the current version is v1.3.0.

More Skills

ClawDef