@clanker-chain/clanker-cli 2026.9.8 → 2026.9.10

package/bin/clanker.mjs

@@ -3,6 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import os from "node:os";
 import process from "node:process";
 import { getAddress } from "viem";
@@ -26,6 +27,8 @@ import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/
 import { runSetup } from "../lib/setup.mjs";
 import { runDoctor } from "../lib/doctor.mjs";
 import {
+  botIdentityCard,
+  botIdentityJson,
   hubConnectChecklist,
   wireOpenClawMqtt,
 } from "../lib/openclaw-wire.mjs";
@@ -95,8 +98,15 @@ function runScript(scriptPath, args = []) {
 }
 
 function findRepoRoot() {
-  const here = dirname(new URL(import.meta.url).pathname);
-  return dirname(dirname(here));
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "chain", "foundry.toml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // npm install: package root (no monorepo checkout)
+  return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
 /** chain up/deploy and check * need the monorepo; npm installs only ship bin/ + lib/. */
@@ -167,6 +177,10 @@ Usage:
   clanker bot status <label> [--json]
   clanker bot revoke <label> [--json] [--yes]
   clanker bot rotate <label> <newKeyAddress> [--json] [--yes]
+  clanker pair add <operator-label> [--yes] [--auth-url URL] [--openclaw-home DIR]
+  clanker pair remove <operator-label> [--auth-url URL] [--openclaw-home DIR]
+  clanker pair list [--auth-url URL]
+  clanker pair status <operator-label> [--auth-url URL]
   clanker init-openclaw
   clanker chain up|deploy|mint-operator|mint-bot|rotate-bot-key|revoke-bot ...
   clanker check mqtt <bot_id> <operator_id>
@@ -178,10 +192,11 @@ Profile:
   ~/.clanker/keys/           bot keys (also written to ~/.openclaw/keys/)
 
 Humans: \`clanker setup\` then \`clanker doctor\` / \`whoami\`.
+Pairing (Policy): both operators run \`clanker pair add\` before DMs deliver on the hub.
 Mutates print a plan and confirm unless --yes or --json.
 whoami is fast by default; pass --with-bots to enrich child bots (or use \`clanker bots\`).
 
-See docs/operator-cli.md.
+See docs/operator-cli.md and docs/trust-model.md.
 `);
 }
 
@@ -439,6 +454,93 @@ async function main() {
     return;
   }
 
+  if (cmd === "pair") {
+    const [sub, ...pairRest] = rest;
+    if (!sub || !["add", "remove", "list", "status"].includes(sub)) {
+      console.error("Usage: clanker pair add|remove|list|status [operator-label]");
+      process.exit(1);
+    }
+
+    let peerLabel = null;
+    for (let i = 0; i < pairRest.length; i += 1) {
+      const a = pairRest[i];
+      if (a.startsWith("--")) {
+        if (a !== "--json" && a !== "--yes" && pairRest[i + 1] && !pairRest[i + 1].startsWith("--")) {
+          i += 1; // skip flag value
+        }
+        continue;
+      }
+      peerLabel = a;
+      break;
+    }
+
+    const { runPairAction } = await import("../lib/pair.mjs");
+    try {
+      if (sub === "add") {
+        const planRows = [
+          ["action", "pair add (Policy)"],
+          ["peer", peerLabel ?? "(missing)"],
+          ["note", "One-way allow; peer must pair you for bidirectional DMs"],
+        ];
+        const ok = await confirmPlan(pairRest, planRows, `Allow operator ${peerLabel}?`);
+        if (!ok) process.exit(0);
+      }
+      const out = await runPairAction(pairRest, sub, peerLabel);
+      if (hasFlag(pairRest, "--json")) {
+        console.log(JSON.stringify(out, null, 2));
+      } else if (sub === "list") {
+        console.log(`Operator: ${out.operatorId}`);
+        console.log(`Auth: ${out.authUrl}`);
+        const allows = out.listed?.allows ?? [];
+        if (!allows.length) {
+          console.log("(no allows)");
+        } else {
+          for (const a of allows) {
+            console.log(
+              `  ${a.peer_operator_id}  ${a.mutual ? "mutual" : "pending (one-way)"}`,
+            );
+          }
+        }
+      } else if (sub === "status") {
+        console.log(`peer:    ${out.peerLabel}`);
+        console.log(`allowed: ${out.allowed}`);
+        console.log(`mutual:  ${out.mutual}`);
+        if (out.allowed && !out.mutual) {
+          console.log("Waiting for peer to run: clanker pair add <your-operator>");
+        }
+      } else {
+        console.log(
+          `${sub} ${out.peerLabel}: ${out.result?.mutual ? "mutual" : "one-way / pending"}`,
+        );
+        if (out.openclawSync?.synced) {
+          console.log(`Synced allowOperators → ${out.openclawSync.path}`);
+          console.log(
+            "Restart (or reload) the OpenClaw gateway so channels.mqtt.allowOperators is picked up.",
+          );
+        } else if (out.openclawSync?.reason === "missing_openclaw_json") {
+          console.log(
+            `Hub Policy updated, but no openclaw.json at ${out.openclawSync.path} — ` +
+              "client allowOperators was not synced. Create OpenClaw config or set allowOperators manually.",
+          );
+        }
+        if (sub === "add" && !out.result?.mutual) {
+          nextHint(`Ask ${out.peerLabel} to run: clanker pair add ${out.operatorId}`);
+        }
+      }
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "pairing needs operator key + mqtt-auth /pair endpoints",
+        try: [
+          "clanker doctor",
+          "clanker pair add org.peer --auth-url http://127.0.0.1:9090 --yes",
+          "See docs/trust-model.md",
+        ],
+      });
+    }
+    return;
+  }
+
   if (cmd === "operator") {
     const [sub, ...opArgv] = rest;
     const {
@@ -615,18 +717,30 @@ async function main() {
         keyPath: result.key_path,
       });
       if (hasFlag(flags, "--json")) {
-        printJson({ ...result, openclaw: wire });
+        printJson({
+          ...result,
+          openclaw: wire,
+          bot_identity: botIdentityJson({
+            botId: botLabel,
+            keyPath: result.key_path,
+            openclawConfigPath: wire.path,
+          }),
+        });
       } else {
         console.log(c.green(`Minted bot ${botLabel} under ${operatorLabel}`));
         console.log(`botKey:   ${result.bot_key}`);
-        console.log(`key file: ${result.key_path}`);
-        console.log(`also:     ${result.clanker_key_path}`);
         console.log(`tx:       ${result.tx}`);
-        console.log(
-          wire.created
-            ? c.green(`Wrote ${wire.path}`)
-            : c.green(`Updated channels.mqtt in ${wire.path}`),
-        );
+        console.log(c.dim(`also:     ${result.clanker_key_path}`));
+        console.log("");
+        for (const line of botIdentityCard({
+          botId: botLabel,
+          operatorId: operatorLabel,
+          keyPath: result.key_path,
+          openclawPath: wire.path,
+          created: wire.created,
+        })) {
+          console.log(line);
+        }
         nextHint(
           hubConnectChecklist({
             botId: botLabel,
@@ -921,7 +1035,7 @@ async function main() {
     nextHint([
       "clanker bot mint <label>",
       "Then channels.mqtt.botId / operatorId / privateKeyFile update automatically",
-      "See docs/operator-cli.md and docs/closed-beta-invite.md",
+      "See docs/operator-cli.md and docs/public-testnet-hub.md",
     ]);
     process.exit(0);
   }

package/lib/identity-query.mjs

@@ -13,7 +13,7 @@ import {
 } from "viem";
 import { clankerIdentityAbi } from "./clanker-identity-abi.mjs";
 
-/** Match identity-service EVM_LOG_CHUNK_BLOCKS — public RPCs reject wide ranges. */
+/** Public RPC eth_getLogs chunk size — wide ranges are often rejected. */
 export const LOG_CHUNK_BLOCKS = 2000n;
 
 export function labelToId(label) {

package/lib/openclaw-wire.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { harnessSnippet } from "./profile.mjs";
 
 /** Current published OpenClaw plugin pins for closed-beta invite. */
-export const OPENCLAW_PLUGIN_PIN = "2026.7.29";
+export const OPENCLAW_PLUGIN_PIN = "2026.9.10";
 
 /**
  * @param {string} [openclawHome]
@@ -94,11 +94,52 @@ export function wireOpenClawMqtt(opts) {
 export function hubConnectChecklist(opts) {
   const pin = opts.pluginPin ?? OPENCLAW_PLUGIN_PIN;
   return [
+    "Your bot login is already wired — install plugins and restart OpenClaw.",
     `openclaw plugins install @clanker-chain/mqtt-channel-plugin@${pin}`,
     `openclaw plugins install @clanker-chain/mqtt-tools@${pin}`,
     "Enable plugin ids mqtt + mqtt-tools (already set in openclaw.json if we wired it)",
     `CONNECT broker: ${opts.channelsMqtt?.brokerUrl ?? "mqtts://mqtt.clanker-chain.com:8883"}`,
-    `Ask hub operator to allow bot_id "${opts.botId}" in france dmPolicy / allowFrom`,
+    "Both operators: clanker pair add <peer-operator>  (Policy — required before DMs deliver)",
     "DM openclaw.france.prod-1 to smoke the mesh",
   ];
 }
+
+/**
+ * Plain-language card: what the bot uses vs operator mint key.
+ * @param {{
+ *   botId: string,
+ *   operatorId: string,
+ *   keyPath: string,
+ *   openclawPath: string,
+ *   created?: boolean,
+ * }} opts
+ * @returns {string[]}
+ */
+export function botIdentityCard(opts) {
+  const openclawState = opts.created
+    ? `${opts.openclawPath} (channels.mqtt created)`
+    : `${opts.openclawPath} (channels.mqtt updated)`;
+  return [
+    "Bot identity (what OpenClaw uses to CONNECT):",
+    `bot id:     ${opts.botId}`,
+    `operator:   ${opts.operatorId}`,
+    `bot key:    ${opts.keyPath}`,
+    `openclaw:   ${openclawState}`,
+    "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  ];
+}
+
+/**
+ * Structured bot_identity for --json mint output.
+ * @param {{ botId: string, keyPath: string, openclawConfigPath: string }} opts
+ */
+export function botIdentityJson(opts) {
+  return {
+    botId: opts.botId,
+    keyPath: opts.keyPath,
+    openclawConfigPath: opts.openclawConfigPath,
+    warnOperatorKey:
+      "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  };
+}
+

package/lib/operator-key.mjs

@@ -0,0 +1,50 @@
+/**
+ * Consumer-path operator key helpers (generate local op.key).
+ * Never logs private keys.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { defaultOperatorKeyPath } from "./foundry.mjs";
+
+export { defaultOperatorKeyPath };
+
+/** Coinbase Developer Platform faucet UI (Base Sepolia). */
+export const BASE_SEPOLIA_FAUCET_URL =
+  "https://portal.cdp.coinbase.com/products/faucet";
+
+/**
+ * Generate a new secp256k1 key and write it to destPath (mode 0o600).
+ * Does not print the key.
+ *
+ * @param {string} destPath
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function generateOperatorKeyFile(destPath, opts = {}) {
+  if (existsSync(destPath) && !opts.force) {
+    throw new Error(
+      `Key file already exists: ${destPath} (pass --force to overwrite)`,
+    );
+  }
+  const key = generatePrivateKey();
+  const address = privateKeyToAccount(key).address;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Plain-language next steps after creating an operator key on Sepolia.
+ * @param {{ address: string, label?: string }} opts
+ */
+export function consumerFundHints(opts) {
+  const mintLabel = opts.label ? ` ${opts.label}` : "";
+  return [
+    `Your operator address is ${opts.address} — fund it with Base Sepolia ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+    "clanker doctor",
+    `clanker operator mint${mintLabel} --yes`,
+    "clanker bot mint <bot_label> --yes",
+  ];
+}

package/lib/pair.mjs

@@ -0,0 +1,252 @@
+/**
+ * Operator pairing client (Policy layer — docs/trust-model.md).
+ * Signs with the operator owner key; never the bot key.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { privateKeyToAccount } from "viem/accounts";
+import { loadOperator } from "./profile.mjs";
+import { openclawConfigPath } from "./openclaw-wire.mjs";
+import { resolveOperatorKey } from "./resolve.mjs";
+
+/**
+ * @param {string} baseUrl
+ * @param {{ operatorId: string, action: 'add'|'remove'|'list', peerLabel?: string }} opts
+ */
+export async function fetchPairNonce(baseUrl, opts) {
+  const url = new URL("/pair-nonce", baseUrl.replace(/\/$/, ""));
+  url.searchParams.set("operator_id", opts.operatorId);
+  url.searchParams.set("action", opts.action);
+  if (opts.peerLabel) url.searchParams.set("peer_label", opts.peerLabel);
+  const res = await fetch(url.toString());
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair-nonce: unexpected response: ${text}`);
+  }
+  if (!res.ok || !body.nonce || !body.message) {
+    throw new Error(body.error || `pair-nonce failed: HTTP ${res.status}`);
+  }
+  return /** @type {{ nonce: string, message: string, expires_at?: string }} */ (body);
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {{
+ *   operatorId: string,
+ *   peerLabel: string,
+ *   action: 'add'|'remove',
+ *   nonce: string,
+ *   signature: `0x${string}`,
+ * }} opts
+ */
+export async function postPair(baseUrl, opts) {
+  const res = await fetch(new URL("/pair", baseUrl.replace(/\/$/, "")).toString(), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      operator_id: opts.operatorId,
+      peer_label: opts.peerLabel,
+      action: opts.action,
+      nonce: opts.nonce,
+      signature: opts.signature,
+    }),
+  });
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair: unexpected response: ${text}`);
+  }
+  if (!res.ok) {
+    throw new Error(body.error || `pair failed: HTTP ${res.status}`);
+  }
+  return body;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {{ operatorId: string, nonce: string, signature: `0x${string}` }} opts
+ */
+export async function getPairList(baseUrl, opts) {
+  const url = new URL("/pair", baseUrl.replace(/\/$/, ""));
+  url.searchParams.set("operator_id", opts.operatorId);
+  url.searchParams.set("nonce", opts.nonce);
+  url.searchParams.set("signature", opts.signature);
+  const res = await fetch(url.toString());
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`pair list: unexpected response: ${text}`);
+  }
+  if (!res.ok) {
+    throw new Error(body.error || `pair list failed: HTTP ${res.status}`);
+  }
+  return body;
+}
+
+/**
+ * Merge allowOperators + dmPolicy into ~/.openclaw/openclaw.json channels.mqtt.
+ * @param {{ peerLabel: string, action: 'add'|'remove', openclawHome?: string }} opts
+ */
+export function syncAllowOperators(opts) {
+  const openclawHome = opts.openclawHome ?? join(homedir(), ".openclaw");
+  const cfgPath = openclawConfigPath(openclawHome);
+  if (!existsSync(cfgPath)) {
+    return { synced: false, path: cfgPath, reason: "missing_openclaw_json" };
+  }
+  const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+  const channels = { ...(cfg.channels ?? {}) };
+  const mqtt = { ...(channels.mqtt && typeof channels.mqtt === "object" ? channels.mqtt : {}) };
+  const prev = Array.isArray(mqtt.allowOperators)
+    ? mqtt.allowOperators.filter((x) => typeof x === "string")
+    : [];
+  let next;
+  if (opts.action === "add") {
+    next = prev.includes(opts.peerLabel) ? prev : [...prev, opts.peerLabel];
+  } else {
+    next = prev.filter((x) => x !== opts.peerLabel);
+  }
+  mqtt.allowOperators = next;
+  if (!mqtt.dmPolicy) mqtt.dmPolicy = "pairing";
+  channels.mqtt = mqtt;
+  cfg.channels = channels;
+  mkdirSync(openclawHome, { recursive: true });
+  writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+  return { synced: true, path: cfgPath, allowOperators: next };
+}
+
+/**
+ * Resolve mqtt-auth base URL from network / env / flag.
+ * @param {string[]} argv
+ * @param {{ mqttAuthServiceUrl?: string|null }} network
+ */
+export function resolvePairAuthUrl(argv, network) {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--auth-url" && argv[i + 1]) return argv[i + 1];
+  }
+  if (process.env.MQTT_AUTH_SERVICE_URL) return process.env.MQTT_AUTH_SERVICE_URL;
+  if (network.mqttAuthServiceUrl) return network.mqttAuthServiceUrl;
+  throw new Error(
+    "mqttAuthServiceUrl required for pairing. Set profile via clanker setup, " +
+      "pass --auth-url, or set MQTT_AUTH_SERVICE_URL.",
+  );
+}
+
+/**
+ * Optional OpenClaw home for allowOperators sync (directory containing openclaw.json).
+ * @param {string[]} argv
+ * @returns {string|undefined}
+ */
+export function resolveOpenclawHome(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--openclaw-home" && argv[i + 1]) return argv[i + 1];
+  }
+  if (process.env.OPENCLAW_HOME) return process.env.OPENCLAW_HOME;
+  return undefined;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {'add'|'remove'|'list'|'status'} action
+ * @param {string|null} peerLabel
+ */
+export async function runPairAction(argv, action, peerLabel) {
+  const resolved = resolveOperatorKey(argv, { requireRegistry: true });
+  const operator =
+    loadOperator(resolved.network.home) ??
+    (resolved.network.operatorLabel
+      ? { label: resolved.network.operatorLabel }
+      : null);
+  const operatorId =
+    argv.includes("--operator") && argv[argv.indexOf("--operator") + 1]
+      ? argv[argv.indexOf("--operator") + 1]
+      : operator?.label;
+  if (!operatorId) {
+    throw new Error(
+      "Operator label required. Run clanker setup / write operator.json, or pass --operator org.you.",
+    );
+  }
+
+  const authUrl = resolvePairAuthUrl(argv, resolved.network);
+  const account = privateKeyToAccount(resolved.key);
+
+  if (action === "list" || action === "status") {
+    const { nonce, message } = await fetchPairNonce(authUrl, {
+      operatorId,
+      action: "list",
+    });
+    const signature = await account.signMessage({ message });
+    const listed = await getPairList(authUrl, {
+      operatorId,
+      nonce,
+      signature,
+    });
+    if (action === "status") {
+      if (!peerLabel) throw new Error("Usage: clanker pair status <operator-label>");
+      // Resolve peer by scanning allows — mutual flag is per peer_operator_id;
+      // we match by requesting add-style peer label via a second pair-nonce is heavy.
+      // Instead: check if any allow entry is mutual when peer label hashes match… we
+      // only have peer_operator_id hex. Re-fetch is unnecessary: call add-path status
+      // by computing whether peer is in allow list via a dedicated pair status using
+      // the peer label through POST-less approach — GET list doesn't include labels.
+      // Best effort: show mutual if we can add then remove? No.
+      // Call /pair-nonce + post with action that doesn't mutate? Use list + ask user.
+      // Simpler: after list, for status we POST nothing — check if peer's keccak is in list.
+      // We need peer id: keccak of peerLabel.
+      const { keccak256, toBytes } = await import("viem");
+      const peerId = keccak256(toBytes(peerLabel)).toLowerCase();
+      const hit = (listed.allows ?? []).find(
+        (a) => String(a.peer_operator_id).toLowerCase() === peerId,
+      );
+      return {
+        action: "status",
+        operatorId,
+        peerLabel,
+        allowed: Boolean(hit),
+        mutual: hit?.mutual === true,
+        authUrl,
+        listed,
+      };
+    }
+    return { action: "list", operatorId, authUrl, listed };
+  }
+
+  if (!peerLabel) {
+    throw new Error(`Usage: clanker pair ${action} <operator-label>`);
+  }
+
+  const { nonce, message } = await fetchPairNonce(authUrl, {
+    operatorId,
+    action,
+    peerLabel,
+  });
+  const signature = await account.signMessage({ message });
+  const result = await postPair(authUrl, {
+    operatorId,
+    peerLabel,
+    action,
+    nonce,
+    signature,
+  });
+  const sync = syncAllowOperators({
+    peerLabel,
+    action,
+    openclawHome: resolveOpenclawHome(argv),
+  });
+  return {
+    action,
+    operatorId,
+    peerLabel,
+    authUrl,
+    result,
+    openclawSync: sync,
+  };
+}

package/lib/setup.mjs

@@ -33,6 +33,11 @@ import {
   exportFoundryKey,
   resolveFoundryAddress,
 } from "./foundry.mjs";
+import {
+  BASE_SEPOLIA_FAUCET_URL,
+  consumerFundHints,
+  generateOperatorKeyFile,
+} from "./operator-key.mjs";
 import { c, nextHint } from "./ui.mjs";
 import { join } from "node:path";
 
@@ -52,6 +57,7 @@ export function parseSetupFlags(argv) {
   let skipChainCheck = false;
   let foundryAccount = null;
   let exportKey = false;
+  let generateKey = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -63,6 +69,7 @@ export function parseSetupFlags(argv) {
     else if (a === "--from-block" && argv[i + 1]) fromBlock = BigInt(argv[++i]);
     else if (a === "--foundry-account" && argv[i + 1]) foundryAccount = argv[++i];
     else if (a === "--export-key") exportKey = true;
+    else if (a === "--generate-key") generateKey = true;
     else if (a === "--force") force = true;
     else if (a === "--yes" || a === "-y") yes = true;
     else if (a === "--skip-key") skipKey = true;
@@ -82,6 +89,7 @@ export function parseSetupFlags(argv) {
     skipChainCheck,
     foundryAccount,
     exportKey,
+    generateKey,
   };
 }
 
@@ -203,7 +211,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   if (!flags.preset || !PRESETS[flags.preset]) {
     throw new Error(
       "Non-interactive setup requires --preset sepolia|local (stdin is not a TTY). " +
-        "Also pass --operator <label> and --address 0x…",
+        "Also pass --operator <label> and --generate-key (or --address / --key-file)",
     );
   }
   if (!flags.operator) {
@@ -218,6 +226,23 @@ export async function runSetupNonInteractive(argv, opts = {}) {
     inheritStdio: false,
   };
 
+  if (flags.generateKey) {
+    if (flags.skipKey) {
+      throw new Error("Cannot combine --generate-key with --skip-key");
+    }
+    const dest = keyFile || defaultOperatorKeyPath(home);
+    const created = generateOperatorKeyFile(dest, {
+      force: flags.force,
+    });
+    keyFile = created.path;
+    if (address && getAddress(address) !== getAddress(created.address)) {
+      throw new Error(
+        `Generated key address ${created.address} does not match --address ${getAddress(address)}`,
+      );
+    }
+    address = created.address;
+  }
+
   if (flags.foundryAccount) {
     if (!address) {
       address = resolveFoundryAddress(flags.foundryAccount, castOpts);
@@ -238,7 +263,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
   if (!address && env.OPERATOR_PRIVATE_KEY) address = addressFromEnv(env);
   if (!address) {
     throw new Error(
-      "Non-interactive setup requires --address 0x…, --key-file, OPERATOR_PRIVATE_KEY, or --foundry-account",
+      "Non-interactive setup requires --generate-key, --address 0x…, --key-file, OPERATOR_PRIVATE_KEY, or --foundry-account",
     );
   }
 
@@ -305,9 +330,13 @@ export async function runSetupInteractive(argv, opts = {}) {
   });
 
   clack.intro(c.bold("clanker setup"));
-  clack.log.step("Creates ~/.clanker/config.json (network) and operator.json (identity).");
+  clack.log.step(
+    "Sets up your operator identity (org account) and network for OpenClaw bots.",
+  );
   clack.log.message(
-    c.dim("whoami works from owner without a key; mint/revoke need a key pointer later."),
+    c.dim(
+      "New here? Create a key file — no wallet app or Foundry required. Mint needs a little test ETH later.",
+    ),
   );
   clack.log.message(c.dim(`Profile: ${home}`));
   console.log("");
@@ -366,6 +395,28 @@ export async function runSetupInteractive(argv, opts = {}) {
 
   let address = flags.address ?? null;
   let foundryAccountUsed = null;
+  let generatedKeyFile = null;
+  if (!address && flags.generateKey) {
+    const dest = flags.keyFile || defaultOperatorKeyPath(home);
+    let forceGen = flags.force;
+    if (existsSync(dest) && !forceGen) {
+      forceGen = cancelIf(
+        await clack.confirm({
+          message: `Overwrite existing ${dest}?`,
+          initialValue: false,
+        }),
+      );
+      if (!forceGen) {
+        clack.cancel("Aborted.");
+        process.exit(0);
+      }
+    }
+    const created = generateOperatorKeyFile(dest, { force: true });
+    generatedKeyFile = created.path;
+    address = created.address;
+    clack.log.success(`Created operator key at ${created.path}`);
+    clack.log.info(`Your operator address: ${created.address}`);
+  }
   if (!address && flags.keyFile) {
     address = addressFromKeyFile(flags.keyFile);
     clack.log.info(`Address from --key-file: ${address}`);
@@ -388,23 +439,95 @@ export async function runSetupInteractive(argv, opts = {}) {
     );
     if (useOp) address = hints.operator.owner;
   }
-  if (!address && hints.foundryAccounts.length) {
+  if (!address) {
     const options = [
-      ...hints.foundryAccounts.map((n) => ({
-        value: n,
-        label: n,
-        hint: "resolve via cast wallet address",
-      })),
-      { value: "__paste__", label: "Paste an address…", hint: "0x…" },
+      {
+        value: "__generate__",
+        label: "Create a new operator key for me",
+        hint: "writes ~/.clanker/op.key (recommended)",
+      },
+      {
+        value: "__keyfile__",
+        label: "Use an existing key file…",
+        hint: "path to a 0x private key file",
+      },
     ];
+    if (hints.foundryAccounts.length) {
+      for (const n of hints.foundryAccounts) {
+        options.push({
+          value: n,
+          label: `Foundry: ${n}`,
+          hint: "advanced — cast wallet",
+        });
+      }
+    } else {
+      options.push({
+        value: "__foundry_missing__",
+        label: "Foundry account…",
+        hint: "advanced — install Foundry first",
+      });
+    }
+    options.push({
+      value: "__paste__",
+      label: "Paste an address…",
+      hint: "read-only unless you add a key later",
+    });
+
     const pick = cancelIf(
       await clack.select({
-        message: "Operator owner source",
+        message: "How do you want to set your operator identity?",
         options,
-        initialValue: hints.foundryAccounts[0],
+        initialValue: "__generate__",
       }),
     );
-    if (pick === "__paste__") {
+
+    if (pick === "__generate__") {
+      const dest = defaultOperatorKeyPath(home);
+      let forceGen = flags.force;
+      if (existsSync(dest) && !forceGen) {
+        forceGen = cancelIf(
+          await clack.confirm({
+            message: `Overwrite existing ${dest}?`,
+            initialValue: false,
+          }),
+        );
+        if (!forceGen) {
+          clack.cancel("Aborted.");
+          process.exit(0);
+        }
+      }
+      const created = generateOperatorKeyFile(dest, { force: true });
+      generatedKeyFile = created.path;
+      address = created.address;
+      clack.log.success(`Created operator key at ${created.path}`);
+      clack.log.info(`Your operator address: ${created.address}`);
+    } else if (pick === "__keyfile__") {
+      const path = cancelIf(
+        await clack.text({
+          message: "Path to operator key file",
+          placeholder: join(home, "op.key"),
+          validate: (v) =>
+            v && String(v).trim() && existsSync(String(v).trim())
+              ? undefined
+              : "File not found",
+        }),
+      );
+      generatedKeyFile = String(path).trim();
+      address = addressFromKeyFile(generatedKeyFile);
+      clack.log.info(`Address from key file: ${address}`);
+    } else if (pick === "__foundry_missing__") {
+      clack.log.warn(
+        "Foundry (cast) is not available. Install https://book.getfoundry.sh/ or choose Create a new operator key.",
+      );
+      address = cancelIf(
+        await clack.text({
+          message: "Operator owner address",
+          placeholder: "0x…",
+          validate: (v) =>
+            /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
+        }),
+      );
+    } else if (pick === "__paste__") {
       address = cancelIf(
         await clack.text({
           message: "Operator owner address",
@@ -436,16 +559,6 @@ export async function runSetupInteractive(argv, opts = {}) {
       }
     }
   }
-  if (!address) {
-    address = cancelIf(
-      await clack.text({
-        message: "Operator owner address",
-        placeholder: "0x…",
-        validate: (v) =>
-          /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
-      }),
-    );
-  }
   address = getAddress(address);
 
   let label = flags.operator || hints.operator?.label || null;
@@ -483,7 +596,7 @@ export async function runSetupInteractive(argv, opts = {}) {
     throw err;
   }
 
-  let keyFile = flags.keyFile;
+  let keyFile = flags.keyFile || generatedKeyFile;
   let keyEnv = flags.keyEnv;
   let skipKey = flags.skipKey;
   if (!skipKey && !keyFile && !keyEnv) {
@@ -579,7 +692,16 @@ export async function runSetupInteractive(argv, opts = {}) {
   if (!key) {
     nextHint([
       "clanker whoami",
-      "clanker setup --key-file ~/.clanker/op.key --force   # when you need mint",
+      "clanker setup — choose Create a new operator key when you need mint",
+    ]);
+  } else if (preset === "sepolia" && generatedKeyFile) {
+    nextHint(consumerFundHints({ address, label }));
+  } else if (preset === "sepolia") {
+    nextHint([
+      `If this address needs test ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+      "clanker doctor",
+      "clanker whoami",
+      `clanker bot mint <label>`,
     ]);
   } else {
     nextHint(["clanker whoami", `clanker bot mint <label>`]);
@@ -593,23 +715,20 @@ export async function runSetupInteractive(argv, opts = {}) {
 export async function runSetup(argv, opts = {}) {
   const flags = parseSetupFlags(argv);
   const isTTY = opts.isTTY ?? Boolean(input.isTTY);
+  const hasIdentitySource = Boolean(
+    flags.address ||
+      flags.keyFile ||
+      flags.generateKey ||
+      flags.foundryAccount ||
+      opts.env?.OPERATOR_PRIVATE_KEY ||
+      process.env.OPERATOR_PRIVATE_KEY,
+  );
 
-  if (
-    !isTTY ||
-    (flags.yes && flags.preset && flags.operator && (flags.address || flags.keyFile))
-  ) {
+  if (!isTTY || (flags.yes && flags.preset && flags.operator && hasIdentitySource)) {
     if (!isTTY && !(flags.preset && flags.operator)) {
       return runSetupNonInteractive(argv, opts);
     }
-    if (
-      flags.yes &&
-      flags.preset &&
-      flags.operator &&
-      (flags.address ||
-        flags.keyFile ||
-        opts.env?.OPERATOR_PRIVATE_KEY ||
-        process.env.OPERATOR_PRIVATE_KEY)
-    ) {
+    if (flags.yes && flags.preset && flags.operator && hasIdentitySource) {
       return runSetupNonInteractive(argv, opts);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.8",
+  "version": "2026.9.10",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {