ATBASH Plugin — Installation Guide

This guide walks you through installing the ATBASH plugin into OpenClaw. After installation, every tool call your agent makes will pass through the ATBASH judgment layer before it runs.

What you're about to do

1. Get an agent key file. The simplest path is to sign in to atbash.ai, onboard your agent, and click Download Keys — that registers the agent on-chain and gives you the key file in one step. There are also CLI fallbacks if you can't use the website.
2. Install the plugin with openclaw plugins install @atbash/atbash-openclaw.
3. Edit ~/.openclaw/openclaw.json to allow, load, and configure the plugin.
4. Restart the OpenClaw gateway.

Prerequisites

• Node.js v18 or later (node --version to check)
• OpenClaw CLI installed and on your PATH (openclaw --version to check)
• A terminal with access to your home directory

Step 1 — Get your agent key file

Your agent identifies itself to the ATBASH service with a secp256k1 keypair stored locally at ~/.config/atbash/guard-client-key — the same model SSH uses with ~/.ssh/id_rsa. The private key stays on your machine; the plugin only uses it to sign outgoing requests so ATBASH can verify they came from your agent.

There are three ways to get this file. Pick one — Path A is recommended for first-time users.

Skip this step if you already have a valid key file at ~/.config/atbash/guard-client-key (verify with grep '^pubkey=' ~/.config/atbash/guard-client-key).

Important: Whatever path you choose, the private key inside this file is your agent's identity. Treat it like a password — keep a backup somewhere safe (password manager, secure note). If you lose it you have to onboard a new agent from scratch.

bash
Copy
mkdir -p ~/.config/atbash

bash
Copy
cat > ~/.config/atbash/guard-client-key <<'EOF'
privkey=PASTE_YOUR_64_CHAR_PRIVATE_KEY_HERE
pubkey=PASTE_YOUR_66_CHAR_PUBLIC_KEY_HERE
EOF

bash
Copy
chmod 600 ~/.config/atbash/guard-client-key

bash
Copy
npx @atbash/cli keygen --output ~/.config/atbash/guard-client-key

bash
Copy
node -e "
const crypto = require('crypto');
const fs = require('fs');
const os = require('os');
const path = require('path');

const privkey = crypto.randomBytes(32).toString('hex');
const ec = crypto.createECDH('secp256k1');
ec.setPrivateKey(privkey, 'hex');
const pubkey = ec.getPublicKey('hex', 'compressed');

const content = [
  '#Keypair generated using secp256k1',
  '#' + new Date().toString(),
  'privkey=' + privkey,
  'pubkey=' + pubkey,
].join('\n') + '\n';

const dir = path.join(os.homedir(), '.config', 'atbash');
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(path.join(dir, 'guard-client-key'), content, { mode: 0o600 });

process.stdout.write('pubkey=' + pubkey + '\n');
"

Verify (any path)

After completing one of the paths above, confirm the file is in place and parseable:

bash
Copy
grep '^pubkey=' ~/.config/atbash/guard-client-key

You should see one line starting with pubkey= followed by a 66-character hex string. If you used Path C, also make sure you've completed the on-chain registration on atbash.ai before moving on.

Step 2 — Install the plugin via OpenClaw

bash
Copy
openclaw plugins install @atbash/atbash-openclaw

This downloads @atbash/atbash-openclaw from npm and places it at ~/.openclaw/extensions/openclaw. It also writes a partial entry into ~/.openclaw/openclaw.json — but the install is not complete yet. You still need to finish the config in Step 3.

If you've already installed it before

OpenClaw refuses to re-install over an existing folder:

plugin already exists: /Users/<you>/.openclaw/extensions/openclaw (delete it first)

Remove the folder and re-run:

bash
Copy
# macOS / Linux
rm -rf ~/.openclaw/extensions/openclaw
openclaw plugins install @atbash/atbash-openclaw

# Windows (PowerShell)
Remove-Item -Recurse -Force "$HOME\.openclaw\extensions\openclaw"
openclaw plugins install @atbash/atbash-openclaw

If you see Invalid config ... plugin not found: openclaw

A previous failed install can leave a stale entry behind that blocks the next install. Open ~/.openclaw/openclaw.json in a text editor and delete the "openclaw": { ... } block under plugins.entries, then save and re-run openclaw plugins install @atbash/atbash-openclaw.

The block looks like this — remove the whole "openclaw" key and its value:

json
Copy
"entries": {
  "openclaw": {
    "enabled": true
  }
}

Known issue on Windows: spawn EINVAL

Some users on Windows hit:

[openclaw] Failed to start CLI: Error: spawn EINVAL

This is a known issue with how the OpenClaw CLI spawns npm on Windows; there is no clean workaround yet. If you hit it, please report it in the OpenClaw issue tracker so we can prioritize a fix.

Step 3 — Configure ~/.openclaw/openclaw.json

Open ~/.openclaw/openclaw.json in a text editor (VS Code, vim, etc.). Find the "plugins" block — openclaw plugins install already added part of it.

You need the plugins block to end up looking exactly like this. Diff three things against your current file:

1. Add "openclaw" to plugins.allow.
2. Under plugins add this configuration (remember to add it correctly without erasing the existing configurations)

json
Copy
{
  "plugins": {
    "allow": [
      "openclaw"
    ],
    "load": {
      "paths": [
        "/Users/<your-username>/.openclaw/extensions/openclaw"
      ]
    },
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": {
          "enabled": true,
          "enforceDecision": true,
          "chromiaSecretPath": "~/.config/atbash/guard-client-key"
        },
        "hooks": {
          "allowConversationAccess": true,
          "allowPromptInjection": true
      }
      }
    }
  }
}

Note: If you already have entries in plugins.allow or plugins.load.paths (for example "ai-guardian-plugin"), keep them — just add "openclaw" and the install path alongside what's already there.

Important: Replace <your-username> with your actual home-directory username in both plugins.load.paths and plugins.installs.openclaw.installPath. The chromiaSecretPath value uses ~ and will be expanded automatically, so leave it as ~/.config/atbash/guard-client-key unless you saved your key somewhere different in Step 1.

What each field does

Save the file.

Step 4 — Restart the gateway

bash
Copy
openclaw gateway restart

Confirm the plugin is registered and enabled:

bash
Copy
openclaw plugins list

You should see openclaw in the list with enabled: true. If it doesn't appear, re-check Step 3 — the most common mistake is forgetting to add "openclaw" to plugins.allow.

That's it — every tool call your OpenClaw agent makes will now be judged by ATBASH before it runs. Open the Atbash dashboard at atbash.ai to see audit logs as your agent operates.

Final state checklist

After completing all steps, your setup should match the following:

Troubleshooting

• plugin already exists: ... (delete it first) — remove the folder under ~/.openclaw/extensions/ and re-run openclaw plugins install. See Step 2.
• Invalid config ... plugin not found: openclaw — open ~/.openclaw/openclaw.json, delete the stale plugins.entries.openclaw block, save, and re-run openclaw plugins install. See Step 2.
• spawn EINVAL on Windows — known OpenClaw CLI issue. Please report it upstream.
• Plugin doesn't show up in openclaw plugins list — almost always means "openclaw" is missing from plugins.allow in openclaw.json. See Step 3.
• Plugin loads but doesn't audit calls — check that plugins.entries.openclaw.config.enforceDecision is true and that chromiaSecretPath points at a readable file containing valid privkey=/pubkey= lines.