{"id":50082948,"url":"https://github.com/nk3750/clawlens","last_synced_at":"2026-05-22T16:47:11.820Z","repository":{"id":357226834,"uuid":"1235923517","full_name":"nk3750/clawlens","owner":"nk3750","description":"Agent observability and guardrails for OpenClaw — risk scoring, audit trails, dashboard.","archived":false,"fork":false,"pushed_at":"2026-05-19T01:30:52.000Z","size":16766,"stargazers_count":4,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T03:43:17.975Z","etag":null,"topics":["agent-observability","ai-agents","guardrails","local-first","openclaw","openclaw-plugin","risk-scoring","typescript"],"latest_commit_sha":null,"homepage":"https://clawhub.ai/plugins/@nk3750/openclaw-clawlens","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nk3750.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T19:35:49.000Z","updated_at":"2026-05-19T02:00:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nk3750/clawlens","commit_stats":null,"previous_names":["nk3750/clawlens"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nk3750/clawlens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nk3750%2Fclawlens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nk3750%2Fclawlens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nk3750%2Fclawlens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nk3750%2Fclawlens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nk3750","download_url":"https://codeload.github.com/nk3750/clawlens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nk3750%2Fclawlens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33354637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-observability","ai-agents","guardrails","local-first","openclaw","openclaw-plugin","risk-scoring","typescript"],"created_at":"2026-05-22T16:47:11.029Z","updated_at":"2026-05-22T16:47:11.813Z","avatar_url":"https://github.com/nk3750.png","language":"TypeScript","funding_links":[],"categories":["Security","Integrations \u0026 Features"],"sub_categories":["Security Tools","Monitoring \u0026 Dashboards"],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-logo.jpeg\" alt=\"ClawLens\" width=\"120\"\u003e\u003cbr\u003e\n  ClawLens\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAgent observability and guardrails for \u003ca href=\"https://openclaw.ai/\"\u003eOpenClaw\u003c/a\u003e.\u003c/strong\u003e\u003cbr\u003e\n  See every tool call, understand the risk, and add guardrails from the same dashboard.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/nk3750/clawlens/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/nk3750/clawlens/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg src=\"https://img.shields.io/github/package-json/v/nk3750/clawlens\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/openclaw-plugin-orange\" alt=\"OpenClaw Plugin\"\u003e\n\u003c/p\u003e\n\nClawLens is a local OpenClaw plugin for monitoring agent activity. It records tool calls, scores risky behavior, shows live sessions in a dashboard, and lets you create `block`, `require_approval`, or `allow_notify` guardrails from real agent actions.\n\nUse it when your agents can run shell commands, edit files, call external APIs, or operate across multiple sessions and you want an audit trail plus operator-controlled guardrails.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://youtu.be/AKzhw5GWw5I\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-thumbnail.png\" alt=\"Watch the ClawLens product demo\" width=\"900\"\u003e\n  \u003c/a\u003e\u003cbr\u003e\n  \u003csub\u003e\u003ca href=\"https://youtu.be/AKzhw5GWw5I\"\u003eWatch the 2-minute product demo\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n## Quickstart\n\nClawLens requires a running OpenClaw gateway (`\u003e= 2026.4.0`).\n\n```bash\nopenclaw plugins install @nk3750/openclaw-clawlens\n```\n\nOpen the dashboard:\n\n```text\nhttp://localhost:18789/plugins/clawlens/\n```\n\nYour agents appear after their first tool call. The standard npm install path updates OpenClaw's plugin config automatically; you do not need to edit `~/.openclaw/openclaw.json` by hand.\n\n\u003cdetails\u003e\n\u003csummary\u003eOther install paths\u003c/summary\u003e\n\nInstall from the public GitHub mirror:\n\n```bash\nopenclaw plugins install clawlens --marketplace nk3750/clawlens\n```\n\nInstall from source:\n\n```bash\ngit clone https://github.com/nk3750/clawlens.git\ncd clawlens\nnpm install\nopenclaw plugins install ./\n```\n\nIf you plan to modify the source, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\u003c/details\u003e\n\n---\n\n## Why ClawLens\n\nAgents often take many small actions before the one that matters. ClawLens gives you the activity stream, risk context, and guardrail controls in one place.\n\n| Need | ClawLens gives you |\n|---|---|\n| Know what happened | A local JSONL audit log plus live dashboard views for agents, sessions, and individual tool calls. |\n| Spot risky behavior | Deterministic risk scores and tags for destructive commands, external network access, remote operations, sensitive system paths, credential access, and persistence. |\n| Respond quickly | Guardrails created from observed actions, scoped to one agent or the whole fleet. |\n| Review later | Hash-chained audit entries that make later edits, deletes, or reordering detectable. |\n| Add LLM context | Optional LLM risk evaluation and session summaries when `risk.llmEnabled=true`, using redacted tool-call metadata. |\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-homepage.png\" target=\"_self\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-homepage.png\" alt=\"ClawLens dashboard\" width=\"900\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## How It Works\n\n1. OpenClaw runs your agents and tool calls as usual.\n2. ClawLens observes each tool call, computes a deterministic local risk score, redacts common credential patterns, and writes an audit entry.\n3. The local dashboard updates with agents, sessions, risk mix, recent actions, and Attention Inbox items.\n4. When you create a guardrail, matching future tool calls can be blocked, paused for approval, or allowed with a local notification record.\n\nNo SDK, proxy, database, or separate service stack is required.\n\n---\n\n## Guardrails\n\nGuardrails are rules you create from real activity.\n\n| Action | Behavior |\n|---|---|\n| `block` | Rejects matching tool calls before they run. |\n| `require_approval` | Pauses matching calls and uses OpenClaw's configured approval flow. |\n| `allow_notify` | Allows the call while creating local audit and Attention Inbox signals. |\n\nRules can match specific commands, paths, URLs, tools, agents, or broader patterns. They can apply to one agent or the whole fleet.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-guardrail-add.png\" target=\"_self\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/nk3750/clawlens/main/docs/assets/clawlens-guardrail-add.png\" alt=\"Create a ClawLens guardrail\" width=\"900\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Data Handling\n\nClawLens is designed for local operation by default. It is still an observability plugin, so it sees tool names and tool parameters; treat its audit log like other sensitive development logs.\n\n| Flow | Default | Leaves your machine? | Notes |\n|---|---:|---:|---|\n| Dashboard | On | No | Served by the local OpenClaw gateway. |\n| Audit log | On | No | Written to `~/.openclaw/clawlens/audit.jsonl`; hash-chained, not encrypted. |\n| Deterministic scoring | On | No | Runs locally on tool names and params. |\n| Credential redaction | On | No | Best-effort redaction before audit persistence, summaries, alerts, approval text, and opt-in LLM evaluation. |\n| LLM evaluation | Off | Yes, if enabled | Sends redacted tool-call metadata to your configured OpenClaw LLM provider when `risk.llmEnabled=true`. |\n| Generic high-risk alerts | Off | Depends on OpenClaw routing | Alert text is redacted by default. |\n| `require_approval` guardrails | User-created only | Depends on OpenClaw approval channel | External approval channels may receive prompt text. |\n| `allow_notify` guardrails | User-created only | No by default | Creates local audit rows and local Attention Inbox items. |\n\nOn POSIX systems, ClawLens creates the audit directory/file with owner-only permissions where supported. On Windows, audit-log access follows the parent directory's ACLs.\n\nTo remove local audit history:\n\n```bash\nrm -f ~/.openclaw/clawlens/audit.jsonl\n```\n\n### Optional LLM Evaluation\n\nLLM evaluation is disabled unless you set `risk.llmEnabled=true`. When enabled, ClawLens can use your configured OpenClaw LLM provider to add context to eligible risk evaluations and generate session summaries.\n\nWhen enabled, ClawLens sends a redacted JSON payload containing:\n\n- current tool name\n- redacted current tool parameters\n- up to 5 recent actions with tool name, redacted parameters, and risk score\n- preliminary deterministic risk score, tier, and tags\n\nClawLens does not read LLM API keys from environment variables and does not send LLM API keys in prompts. Provider credentials are handled by OpenClaw's model/auth runtime.\n\nRedaction is best-effort. ClawLens removes common credential patterns before LLM evaluation, but you should still avoid placing secrets in tool parameters.\n\n---\n\n## Configuration\n\nMost users do not need custom configuration. Common settings live under `plugins.entries.clawlens.config` in `~/.openclaw/openclaw.json`.\n\n| Setting | Default | What it controls |\n|---|---|---|\n| `auditLogPath` | `~/.openclaw/clawlens/audit.jsonl` | Where ClawLens writes the JSONL audit log. |\n| `risk.llmEnabled` | `false` | Enables opt-in LLM risk evaluation and LLM-generated summaries. |\n| `risk.llmEvalThreshold` | `50` | Score above which opt-in LLM evaluation can run when enabled. |\n| `alerts.enabled` | `false` | Enables generic high-risk alerts. If routed externally by OpenClaw, alert text may leave your machine. |\n| `alerts.threshold` | `80` | Score above which generic high-risk alerts fire when alerts are enabled. |\n| `alerts.includeParamValues` | `false` | Includes sanitized command/path/URL details in alert messages. Credential patterns are still redacted. |\n\n`risk.llmEvalThreshold` only controls opt-in LLM evaluation. It does not control guardrail matching or Attention Inbox freshness. Guardrails fire when a user-created rule matches. `alerts.threshold` only controls generic high-risk alerts when `alerts.enabled=true`.\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced settings and v1.0.1 migration notes\u003c/summary\u003e\n\nThe plugin manifest also supports storage-path overrides for guardrails, attention state, saved searches, digest settings, and dashboard alert links. See [openclaw.plugin.json](openclaw.plugin.json) for the full schema.\n\n`risk.llmProvider`, `risk.llmModel`, and `risk.llmApiKeyEnv` are deprecated no-ops in v1.0.1. They are accepted temporarily so existing configs continue to load, but ClawLens ignores them. Remove them from your config before v1.1.0.\n\n\u003c/details\u003e\n\n---\n\n## Scope And Limits\n\nClawLens complements OpenClaw's built-in security. It does not replace tool profiles, exec approvals, prompt-injection detection, OS permissions, or secret scanning.\n\n- Guardrails enforce on OpenClaw tool calls. They do not inspect every byte inside arbitrary payloads.\n- Pattern matching catches obvious risky shapes, but ClawLens is not a full shell interpreter.\n- LLM evaluation can add context when explicitly enabled; deterministic local scoring remains the default.\n- The audit log is tamper-evident, not encrypted or hidden from your OS user, backups, or administrators.\n- Sub-agents are observed and scored, but guardrails set for a parent agent do not automatically apply to spawned children.\n\n---\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes ClawLens collect telemetry?\u003c/strong\u003e\u003c/summary\u003e\n\nClawLens does not operate a cloud service, analytics pipeline, telemetry endpoint, install-ping system, or machine-ID system. Installing through npm, GitHub, or ClawHub may still create ordinary registry or download metadata outside ClawLens.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes it block tool calls by default?\u003c/strong\u003e\u003c/summary\u003e\n\nNo. By default, ClawLens observes and scores. Blocking only happens after you create a `block` or `require_approval` guardrail.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I run it without any external data flow?\u003c/strong\u003e\u003c/summary\u003e\n\nYes. Keep `risk.llmEnabled=false`, leave `alerts.enabled=false`, and avoid external OpenClaw approval channels for ClawLens guardrails. The default dashboard, audit log, deterministic scoring, and local guardrail records run locally.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat does LLM evaluation cost?\u003c/strong\u003e\u003c/summary\u003e\n\nNothing by default because LLM evaluation is off. When enabled, ClawLens uses your configured OpenClaw model/auth runtime, so usage is billed according to your existing provider setup.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I export the audit log?\u003c/strong\u003e\u003c/summary\u003e\n\nYes. Use the dashboard export action, run `openclaw clawlens audit export --format json --since 7d` (or `csv`), or read the hash-chained JSONL at `~/.openclaw/clawlens/audit.jsonl`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat if OpenClaw blocks installation?\u003c/strong\u003e\u003c/summary\u003e\n\nThe standard v1.0.1 install should not require `--dangerously-force-unsafe-install`. If OpenClaw blocks installation, do not force it; open an issue with the full installer warning.\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). All changes need tests, and `npm run check` must pass before merge.\n\n## Reporting Issues\n\n- **Bugs:** [open a GitHub issue](https://github.com/nk3750/clawlens/issues/new?template=bug_report.md)\n- **Security:** see [SECURITY.md](SECURITY.md)\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnk3750%2Fclawlens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnk3750%2Fclawlens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnk3750%2Fclawlens/lists"}