@fidacy/openclaw-plugin

The AI Agent Firewall as a native OpenClaw plugin. Fidacy puts signed authority outside the model and checks consequential money, data, credential and record actions before a connected executor can perform them.

YOUR AI AGENT IS UNPROTECTED. GET YOUR FREE API KEY NOW. Installing this plugin does not activate protection. Create the key at app.fidacy.com/signup, configure engineApiKey or FIDACY_ENGINE_API_KEY, and connect the executor that owns the downstream credential.

What this plugin observes, and what leaves your machine

Read this before installing. Since 0.5.0 the plugin is not payment-only: it hooks every agent tool call to build a session report, and each session ends in a hash digest anyone can recompute.

The session log IS written to disk, and it holds the detail. At the end of each session the plugin writes ~/.fidacy/sessions/<session-id>.json (file mode 0600, directory 0700) containing the full action record: the command, file path and arguments of every tool call it observed, plus the hash chain over them. The path is printed in your terminal at session end, on the [fidacy] log line, so you can open it and read exactly what was kept. It stays on your machine and it is yours to delete. Read this paragraph as the important one: this plugin observes everything the agent does, and that observation lands on your disk.

What leaves is only the hash digest of that record plus per-category counts (for example shell: 9, file: 4). The commands, paths and arguments themselves are never transmitted.

Written to disk, and this is the complete list:

• ~/.fidacy/sessions/<session-id>.json (0600, directory 0700): the full action record described above
• ~/.fidacy/config.json (0600): local install state and mandate rules
• ~/.fidacy/audit/audit.log: the hash-chained decision log
• ~/.fidacy/pending-anchors.jsonl: one line per finished session holding its digest, id, timestamp and per-category counts, with no command, path or argument. Lines are removed once anchored.
• ~/.fidacy/pending-anchors.taking: a lock file, present only while that queue is being drained

rm -rf ~/.fidacy clears all five.

Leaves your machine. Every one goes to your configured engine (https://api.fidacy.com by default) and nowhere else. In the default local mode these five are the complete list:

• /v1/telemetry: legacy anonymous usage events from older versions. The current engine refuses anonymous telemetry and requires workspace activation.
• /v1/provision: a legacy background provisioning request. The current engine refuses anonymous provisioning and directs the operator to account signup.
• /v1/artifacts: per-category counts and the session digest, plus any hash you anchor with anchor_artifact. Hashes and counts only; no file content and no command text. This one is automatic, so be clear on when it fires: if an engine key is set, the queued digests are drained on the first tool call of a LATER session, not at the end of the session that produced them. Nobody confirms it. With no engine key nothing is ever sent and the queue simply sits on your disk; delete ~/.fidacy/pending-anchors.jsonl to discard it.
• /v1/assess: only when you call assess_action yourself, and only if you set an engine API key. Sends the action you passed to the tool.
• /v1/register: only if you set operatorEmail, which is opt-in and removable. Sends that email and nothing else.

There is a sixth path, and it is opt-in: setting FIDACY_MODE=http moves the decision itself to a hosted core, which adds /v1/decide, /v1/mandate/get, /v1/audit/proof and /v1/audit/list. Those carry the payment request, so leave FIDACY_MODE unset if you want decisions to stay on your machine. The default is local.

With no account-owned key, consequential actions are refused with activation_required. Installing or loading the plugin alone is not presented as protection.

The tools

• request_payment: authorize a payment against the active signed mandate. ALLOW returns a short-lived Ed25519 grant the executor requires; DENY returns the violated rule and no grant.
• verify_mandate: the active mandate envelope + Fidacy's public key.
• get_audit_proof: tamper-evident, hash-chained proof for any decision.
• assess_action: a SIGNED trust verdict from the live Fidacy engine (requires an engine API key), verifiable by anyone via @fidacy/verify.
• fidacy_upgrade: upgrade the local install to a real Fidacy account.

Plus spend_summary, list_decisions, sentinel_alerts, explain_decision, anchor_artifact and check_artifact.

Same engine as @fidacy/mcp: one engine, many shells. Local-first, deny-by-default, non-custodial: Fidacy authorizes, it never holds funds.

Upgrading from an older Fidacy version

Package registries cannot send a message into an installation that never runs again. When an older installation is started or updated, the current release shows the activation warning. If that installation has a legacy anon_id, run grep anon_id ~/.fidacy/config.json and open https://fidacy.com/claim?ref=<that id> to attach its legacy history to a free account.

Install (2 minutes)

Step 1: get your free API key at app.fidacy.com/signup (free tier, no card).

Step 2: install and set the key.

openclaw plugins install @fidacy/openclaw-plugin

Plugin config (plugins.entries.fidacy.config):

{
  "engineApiKey": "fky_live_...",
  "engineUrl": "https://api.fidacy.com",
  "subject": "agent:my-agent"
}

engineApiKey activates signed authority and verdicts (assess_action). Environment variables (FIDACY_ENGINE_API_KEY, FIDACY_ENGINE_URL, FIDACY_SUBJECT) are the fallback. Decisions run locally, deny-by-default (deny-unknown-payee + per-tx cap); add trusted payees/caps in ~/.fidacy/config.json.

No key yet? YOUR AI AGENT IS UNPROTECTED. Consequential actions are refused with activation_required. Get your free key now at https://app.fidacy.com/signup, configure engineApiKey or FIDACY_ENGINE_API_KEY, and connect the executor before retrying.

Verify any verdict yourself: https://api.fidacy.com/.well-known/jwks.json

Security and privacy, point by point

This is a payment-control plugin, so audit it like one. What it actually does:

• Network calls it makes: the five default endpoints listed under "what leaves your machine" above, plus the four that only exist if you opt into FIDACY_MODE=http. The list is stated once, at the top, on purpose: this section used to carry a second, shorter copy naming only two of them, and a privacy disclosure that contradicts itself is worse than a long one. None of the default five is on the decision path, so payment gating works fully offline. The FIDACY_MODE=http four ARE the decision path, which is the whole reason that switch is opt-in and called out separately.
• Local state: the five files listed above, and nothing else. Earlier versions of this bullet were wrong twice over: it named two files and ended with "Nothing else" while pending-anchors.jsonl went undisclosed, and a later attempt to fix that claimed the session log was never written to disk at all. It is written, it holds the command, path and arguments of every observed tool call, and it is the first item on the list above. rm -rf ~/.fidacy clears everything.
• FIDACY_SIGNING_KEY_B64: an OPTIONAL env var the operator sets to pin a stable local Ed25519 signing key for grants. If unset, a per-session key is generated. The plugin reads it; it never writes or transmits it.
• API keys: read from your plugin config (engineApiKey) or the FIDACY_ENGINE_API_KEY env var, sent only to your configured engine URL (default api.fidacy.com) as a bearer token. There are no hardcoded keys or secrets in the published bundle. A static analyser will flag this as suspicious.env_credential_access ("environment variable access combined with network send"), and that description is accurate: reading your key and sending it to your engine is what a bearer token IS, and every tool that takes an API key matches the same pattern. What the rule cannot tell you is WHOSE key and WHICH host, so check both yourself: the bundle ships unminified, the source is at github.com/lucaslubi/fidacy (packages/openclaw-plugin), and every release is provenance-linked to the commit it was built from. The command below settles the "hardcoded secret" question in one line, and the test suite fails the build if a literal ever gets in.
• Verify our signatures, not our word: every verdict checks against the public JWKS at api.fidacy.com/.well-known/jwks.json with the open-source @fidacy/verify.

Security

This plugin sits in front of money-moving tool calls, so it should be precise about what it touches.

What it reads. Your engine credential, from the plugin config field engineApiKey or from FIDACY_ENGINE_API_KEY. Optionally FIDACY_SIGNING_KEY_B64, which is your own Ed25519 key, so grants are signed with a stable key instead of a per-session one. Both belong to you. Without an account-owned engine key, the plugin refuses consequential actions.

No credential is embedded. There is no API key, token, or private key literal in the published package, in any version. Check it yourself:

cd $(mktemp -d) && curl -sL $(npm view @fidacy/openclaw-plugin dist.tarball) | tar xz && grep -rE "fky_(live|test)_[A-Za-z0-9]{8,}|BEGIN [A-Z ]*PRIVATE KEY" package/ || echo "no credential literals found"

On the suspicious.env_credential_access finding a static analyser reports here, see the "API keys" bullet above. It is stated in one place rather than two, because the two copies had drifted into giving different reasons for the same flag.

Legacy network switches. FIDACY_DISABLE_TELEMETRY=1 and FIDACY_DISABLE_PROVISION=1 disable calls retained for compatibility with older installations. Current protection requires an account-owned key.

Where the history lives. Decisions go to a hash-chained log under ~/.fidacy on your machine. That local chain is what makes spend_summary, list_decisions and get_audit_proof work with no network. Delete the directory to clear it.

Files are never uploaded. anchor_artifact and check_artifact hash the file locally with SHA-256 and send only the 64 hex characters.

Prefer MCP instead?

If you'd rather run Fidacy as an MCP server (out-of-process), use openclaw mcp add fidacy --command npx --arg -y --arg @fidacy/mcp , same tools, same engine. This plugin is the native, in-process variant.

Build (development)

pnpm --filter @fidacy/openclaw-plugin build      # esbuild → dist/index.js (self-contained)
pnpm --filter @fidacy/openclaw-plugin typecheck  # tsc against the real openclaw plugin-sdk types

openclaw/plugin-sdk/* stays external (the host provides it at runtime); everything else (the shared @fidacy/firewall engine and @fidacy/mcp shell wiring) is inlined so the published package is self-contained.

Apache-2.0 · https://fidacy.com