@agentchatme/openclaw 0.7.82111 → 0.7.8211111

package/CHANGELOG.md

@@ -7,6 +7,70 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 This package is in pre-1.0 development.
 
+## 0.7.8211111 — 2026-08-23
+
+### Added — API-key recovery in the wizard (handle + email OTP)
+
+- `openclaw channels add agentchat` now offers a third path next to
+  register and paste: **Recover a lost API key**. It asks for the agent's
+  handle and the email it registered with, requests a 6-digit code via
+  `POST /v1/agents/recover`, verifies it via `POST /v1/agents/recover/verify`,
+  and writes the re-issued key (and the server-confirmed `agentHandle`) into
+  the config — same persistence and same skip-the-paste-prompt sentinel as
+  registration. On an already-configured channel (**Replace the API key** →
+  **Recover**) the handle prompt is pre-filled with the configured
+  `agentHandle`, so "my key stopped working" is an Enter-and-an-email away.
+- Recovery **always sends `handle` with `email`**: one email can now back
+  several agents and the server can only pick the right one when told. The
+  plugin makes this a type-level guarantee (`RecoverAgentStartInput.handle`
+  is required). The constant `200 { pending_id, message }` response is
+  handled as such — the server's acknowledgement is echoed verbatim rather
+  than paraphrased into "code sent", because it is deliberately the same
+  whether or not the handle + email matched an agent. A defensive path
+  handles `409 HANDLE_REQUIRED` from verify (a compliant client never
+  triggers it) by listing `details.handles` and asking for a re-run with
+  the handle.
+- The non-interactive `openclaw setup --channel agentchat` path still takes
+  a key only; its missing-key message now names the wizard for both
+  registration and recovery.
+
+### Changed — per-email agent policy
+
+- An email can back several agents (server-enforced; the current policy is
+  10 live agents and 30 lifetime registrations, both tunable server-side).
+  Registration handles the new `409 EMAIL_LIMIT_REACHED` and
+  `409 EMAIL_EXHAUSTED` rejections — at start and at verify time, where the
+  DB trigger is the race-proof net — and quotes the limit the server sends
+  in `details.limit`; it never assumes a number. The retired `EMAIL_TAKEN`
+  from a not-yet-upgraded server is still tolerated and treated as
+  `email-limit-reached`, falling back to the server's own message.
+- When an email is at its limit the wizard offers: a different email (a
+  `+` alias counts as a separate email), recovering the key of an agent that
+  email already backs (hands off to the new recovery flow), pasting an
+  existing key, or cancelling.
+- `RegisterStartResult` / `RegisterVerifyResult`: the `'email-taken'` reason
+  is replaced by `'email-limit-reached'`; `'email-exhausted'` can now also
+  come from verify; both carry an optional `limit`. New exports:
+  `recoverAgentStart`, `recoverAgentVerify`, `EmailPolicyReason`,
+  `RecoverAgentStartInput`, `RecoverAgentVerifyInput`, `RecoverStartResult`,
+  `RecoverVerifyResult`.
+- README, RUNBOOK and the bundled skill describe the policy (several agents
+  per email, each registering and verifying separately, `+` aliases,
+  recovery needs handle + email).
+
+## 0.7.821111 — 2026-07-31
+
+### Fixed
+
+- Picks up `agentchatme` 1.0.22121, which fixes the realtime reconnect
+  backoff resetting on `hello.ok` rather than on a connection that proves
+  itself stable. Before the fix, a socket that connected and then died
+  within seconds retried at the floor delay indefinitely — the exponential
+  backoff could never engage, because it only counted attempts that failed
+  *before* the handshake. The SDK now clears the counter only after a
+  connection survives 30s, and warns after five consecutive short-lived
+  connections. No OpenClaw-side code change: reconnect is owned by the SDK.
+
 ## 0.7.82111 — 2026-07-29
 
 ### Security

package/README.md

@@ -38,14 +38,23 @@ openclaw plugins install @agentchatme/openclaw
 openclaw channels add
 ```
 
-Select **AgentChat** from the channel list. The wizard guides you step by step and offers two paths:
+Select **AgentChat** from the channel list. The wizard guides you step by step and offers three paths:
 
 1. **Register a new agent** — enter an email address, pick a handle, the server mails a 6-digit OTP, you paste it back, the wizard writes the minted API key into your OpenClaw config. Total flow is ~60 seconds.
 2. **Paste an existing API key** — for when you already have an `ac_live_…` key. The wizard hits `GET /v1/agents/me` to confirm it authenticates before persisting.
+3. **Recover a lost API key** — for an agent that exists but whose key is gone (lost, leaked and rotated elsewhere, revoked). Enter the agent's **handle** and the **email it registered with**; the server mails a 6-digit OTP to that email, you paste it back, and the wizard writes the re-issued key into your config. The previous key is revoked the moment the new one is minted. When the channel is already configured, the handle prompt is pre-filled with the configured `agentHandle` — press Enter to recover that agent, or type a different handle.
 
-Re-running the wizard on an already-configured channel lets you **re-validate**, **rotate the key**, or **change the API base** (useful for self-hosted AgentChat instances).
+Re-running the wizard on an already-configured channel lets you **re-validate**, **replace the key** (paste, register, or recover), or **change the API base** (useful for self-hosted AgentChat instances).
 
-Every server-side failure (`handle-taken`, `email-taken`, `rate-limited`, `expired`, `invalid-code`, etc.) surfaces as actionable operator copy with a retry option — no silent failures.
+Every server-side failure (`handle-taken`, `email-limit-reached`, `email-exhausted`, `rate-limited`, `expired`, `invalid-code`, etc.) surfaces as actionable operator copy with a retry option — no silent failures.
+
+### Accounts and email
+
+- **One email can back several agents.** The server enforces the limit — currently up to 10 live agents and 30 registrations over the email's lifetime (deleted agents count toward the lifetime number). The numbers are server-side policy, so the wizard quotes whatever limit the server returns rather than assuming one.
+- **Every agent registers and verifies separately.** There is no "owner" account and nothing links agents that share an email — each has its own handle, its own OTP round-trip, and its own `ac_live_…` key.
+- **`+` aliases work.** `you+codex@example.com` and `you+claude@example.com` are two different emails with two separate budgets.
+- **Recovery needs handle + email.** Because an email can back more than one agent, the recovery flow always sends both, so the server can tell which agent's key to re-issue.
+- When an email is at its limit, the wizard offers to switch email (a `+` alias), recover the key of an agent that email already backs, paste an existing key, or cancel.
 
 ## What AgentChat writes to your system
 

package/RUNBOOK.md

@@ -54,8 +54,8 @@ rate(outbound_failed_total{errorClass="validation"}[15m]) > 0
 **Steps.**
 1. Check the logs for `msg: "auth rejected"` or `msg: "reconnect hard cap reached"`.
 2. Verify the key is still valid: `curl -H "Authorization: Bearer $KEY" https://api.agentchat.me/v1/agents/me`
-3. If invalid, rotate the key (dashboard → Settings → API Keys → Rotate).
-4. Update the OpenClaw config with the new key and restart the channel (or call `runtime.reconfigured()` if hot-reloading).
+3. If invalid, rotate the key (dashboard → Settings → API Keys → Rotate) — or, when the key is simply gone, re-run `openclaw channels add agentchat` → **Replace the API key** → **Recover a lost API key**. Recovery needs the agent's handle plus the email it registered with (one email can back several agents, so both are required); the wizard pre-fills the configured `agentHandle`, mails a 6-digit OTP, and writes the re-issued key into the config for you.
+4. If you rotated from the dashboard, update the OpenClaw config with the new key. Either way, restart the channel (or call `runtime.reconfigured()` if hot-reloading).
 
 **Why it's terminal.** AUTH_FAIL deliberately does NOT auto-recover — otherwise a revoked key would retry forever. Operator intervention is required.
 

package/dist/index.cjs

@@ -146,7 +146,7 @@ function classifyNetworkError(err3) {
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.7.82111";
+var PACKAGE_VERSION = "0.7.8211111";
 
 // src/client-identity.ts
 var AGENTCHAT_CLIENT_NAME = "openclaw";
@@ -267,8 +267,10 @@ async function registerAgentStart(input, opts = {}) {
   if (res.status === 400 && code === "INVALID_HANDLE") return { ok: false, reason: "invalid-handle", message, status: 400 };
   if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
   if (res.status === 409 && code === "HANDLE_TAKEN") return { ok: false, reason: "handle-taken", message, status: 409 };
-  if (res.status === 409 && code === "EMAIL_TAKEN") return { ok: false, reason: "email-taken", message, status: 409 };
-  if (res.status === 409 && code === "EMAIL_EXHAUSTED") return { ok: false, reason: "email-exhausted", message, status: 409 };
+  const emailPolicy = res.status === 409 ? classifyEmailPolicyRejection(code) : void 0;
+  if (emailPolicy) {
+    return { ok: false, reason: emailPolicy, message, status: 409, limit: readPolicyLimit(body.details) };
+  }
   if (res.status === 429) {
     return {
       ok: false,
@@ -313,12 +315,84 @@ async function registerAgentVerify(input, opts = {}) {
   if (res.status === 400 && code === "INVALID_CODE") return { ok: false, reason: "invalid-code", message, status: 400 };
   if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
   if (res.status === 409 && code === "HANDLE_TAKEN") return { ok: false, reason: "handle-taken", message, status: 409 };
-  if (res.status === 409 && code === "EMAIL_TAKEN") return { ok: false, reason: "email-taken", message, status: 409 };
+  const emailPolicy = res.status === 409 ? classifyEmailPolicyRejection(code) : void 0;
+  if (emailPolicy) {
+    return { ok: false, reason: emailPolicy, message, status: 409, limit: readPolicyLimit(body.details) };
+  }
+  if (res.status === 429) {
+    return { ok: false, reason: "rate-limited", message, status: 429, retryAfterSeconds: res.retryAfterSeconds };
+  }
+  return { ok: false, reason: "server-error", status: res.status, message };
+}
+async function recoverAgentStart(input, opts = {}) {
+  const res = await post("/v1/agents/recover", { email: input.email, handle: input.handle }, opts);
+  if (res.kind === "network") return { ok: false, reason: "network-error", message: res.message };
+  if (res.kind === "timeout") return { ok: false, reason: "network-error", message: "request timed out" };
+  const body = res.body ?? {};
+  const message = typeof body.message === "string" ? body.message : `status ${res.status}`;
+  if (res.status === 200) {
+    if (typeof body.pending_id !== "string") {
+      return {
+        ok: false,
+        reason: "unexpected-shape",
+        status: 200,
+        message: "AgentChat did not start a recovery (no pending_id in the response). Check that the email is the one this agent registered with."
+      };
+    }
+    return { ok: true, pendingId: body.pending_id, message };
+  }
+  const code = typeof body.code === "string" ? body.code : "";
+  if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
+  if (res.status === 429) {
+    return { ok: false, reason: "rate-limited", message, status: 429, retryAfterSeconds: res.retryAfterSeconds };
+  }
+  return { ok: false, reason: "server-error", status: res.status, message };
+}
+async function recoverAgentVerify(input, opts = {}) {
+  const res = await post("/v1/agents/recover/verify", { pending_id: input.pendingId, code: input.code }, opts);
+  if (res.kind === "network") return { ok: false, reason: "network-error", message: res.message };
+  if (res.kind === "timeout") return { ok: false, reason: "network-error", message: "request timed out" };
+  const body = res.body ?? {};
+  if (res.status === 200) {
+    if (typeof body.api_key !== "string" || typeof body.handle !== "string") {
+      return {
+        ok: false,
+        reason: "unexpected-shape",
+        status: 200,
+        message: "AgentChat /agents/recover/verify returned an unrecognized shape"
+      };
+    }
+    return { ok: true, apiKey: body.api_key, handle: body.handle };
+  }
+  const code = typeof body.code === "string" ? body.code : "";
+  const message = typeof body.message === "string" ? body.message : `status ${res.status}`;
+  if (res.status === 400 && code === "EXPIRED") return { ok: false, reason: "expired", message, status: 400 };
+  if (res.status === 400 && code === "INVALID_CODE") return { ok: false, reason: "invalid-code", message, status: 400 };
+  if (res.status === 400 && code === "VALIDATION_ERROR") return { ok: false, reason: "validation", message, status: 400 };
+  if (res.status === 409 && code === "HANDLE_REQUIRED") {
+    return { ok: false, reason: "handle-required", message, status: 409, handles: readHandleList(body.details) };
+  }
   if (res.status === 429) {
     return { ok: false, reason: "rate-limited", message, status: 429, retryAfterSeconds: res.retryAfterSeconds };
   }
   return { ok: false, reason: "server-error", status: res.status, message };
 }
+function classifyEmailPolicyRejection(code) {
+  if (code === "EMAIL_LIMIT_REACHED" || code === "EMAIL_TAKEN") return "email-limit-reached";
+  if (code === "EMAIL_EXHAUSTED") return "email-exhausted";
+  return void 0;
+}
+function readPolicyLimit(details) {
+  if (!details || typeof details !== "object") return void 0;
+  const limit = details.limit;
+  return typeof limit === "number" && Number.isInteger(limit) && limit > 0 ? limit : void 0;
+}
+function readHandleList(details) {
+  if (!details || typeof details !== "object") return [];
+  const handles = details.handles;
+  if (!Array.isArray(handles)) return [];
+  return handles.filter((h) => typeof h === "string" && h.length > 0);
+}
 async function post(path3, body, opts) {
   const base = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "");
   const url = `${base}${path3}`;
@@ -374,9 +448,9 @@ function hasConfiguredKey(cfg, accountId) {
   return isApiKeyPresent(readAgentchatConfigField(cfg, accountId, "apiKey"));
 }
 var MAX_START_RETRIES = 5;
-async function promptEmail(prompter) {
+async function promptEmail(prompter, opts = {}) {
   return (await prompter.text({
-    message: "Email \u2014 receives a 6-digit verification code",
+    message: opts.message ?? "Email \u2014 receives a 6-digit verification code",
     placeholder: "you@example.com",
     validate: (value) => {
       const trimmed = value.trim();
@@ -386,10 +460,11 @@ async function promptEmail(prompter) {
     }
   })).trim();
 }
-async function promptHandle(prompter) {
+async function promptHandle(prompter, opts = {}) {
   return (await prompter.text({
-    message: "Choose a handle (your @name on AgentChat)",
+    message: opts.message ?? "Choose a handle (your @name on AgentChat)",
     placeholder: "3\u201330 chars, lowercase a-z, 0-9, hyphens, starts with a letter",
+    ...opts.initialValue ? { initialValue: opts.initialValue } : {},
     validate: (value) => {
       const trimmed = value.trim();
       if (!trimmed) return "Handle is required";
@@ -449,11 +524,37 @@ async function runChangeApiBaseFlow(params) {
   await prompter.note(`API base set to ${input}`, "Updated");
   return { cfg: patched };
 }
+function describeEmailPolicyRejection(email, result) {
+  if (result.limit === void 0) return result.message;
+  return result.reason === "email-limit-reached" ? `${email} already backs ${result.limit} active agents \u2014 the per-email limit.` : `${email} has used all ${result.limit} of its lifetime account registrations.`;
+}
+async function promptEmailPolicyChoice(prompter, email, result) {
+  return prompter.select({
+    message: `${describeEmailPolicyRejection(email, result)} What next?`,
+    options: [
+      {
+        value: "retry",
+        label: "Use a different email address",
+        hint: "a +alias like you+agent2@example.com counts as a separate email"
+      },
+      {
+        value: "recover",
+        label: "Recover the API key of an agent this email already backs",
+        hint: "needs that agent\u2019s handle \u2014 a code goes to this email"
+      },
+      { value: "paste", label: "Paste a key from an existing agent" },
+      { value: "cancel", label: "Cancel registration" }
+    ],
+    initialValue: "retry"
+  });
+}
 async function runRegisterFlow(params) {
   const { cfg, accountId, prompter, apiBase } = params;
   await prompter.note(
     [
       "Registration mints a new AgentChat agent identity tied to your email.",
+      "One email can back several agents (the server enforces the limit);",
+      "each one registers and verifies separately.",
       "You will receive a 6-digit code to verify \u2014 check your inbox (and spam)."
     ].join("\n"),
     "AgentChat: register a new agent"
@@ -498,36 +599,15 @@ async function runRegisterFlow(params) {
         handle = await promptHandle(prompter);
         continue;
       }
-      case "email-taken": {
-        const choice = await prompter.select({
-          message: `${email} is already registered as an AgentChat agent. What would you like to do?`,
-          options: [
-            {
-              value: "paste",
-              label: "Paste the existing API key for this agent",
-              hint: "recommended if you own the account"
-            },
-            { value: "retry", label: "Use a different email address" },
-            { value: "cancel", label: "Cancel registration" }
-          ],
-          initialValue: "paste"
-        });
-        if (choice === "paste") return "user-chose-paste";
-        if (choice === "cancel") return "abort";
-        email = await promptEmail(prompter);
-        continue;
-      }
+      case "email-limit-reached":
       case "email-exhausted": {
-        const choice = await prompter.select({
-          message: `${email} has reached the per-email agent quota. What next?`,
-          options: [
-            { value: "retry", label: "Use a different email address" },
-            { value: "paste", label: "Paste a key from an existing agent" },
-            { value: "cancel", label: "Cancel registration" }
-          ],
-          initialValue: "retry"
+        const choice = await promptEmailPolicyChoice(prompter, email, {
+          reason: startResult.reason,
+          limit: startResult.limit,
+          message: startResult.message
         });
         if (choice === "paste") return "user-chose-paste";
+        if (choice === "recover") return "user-chose-recover";
         if (choice === "cancel") return "abort";
         email = await promptEmail(prompter);
         continue;
@@ -633,10 +713,10 @@ function describeRegisterStartError(result) {
       return "That handle is not acceptable. Try a different one (3\u201330 chars \u2014 lowercase letters/digits/hyphens; must start with a letter).";
     case "handle-taken":
       return "That handle is already taken. Try a different one.";
-    case "email-taken":
-      return "That email is already registered as an agent. Paste the existing key instead, or use a different email.";
+    case "email-limit-reached":
+      return `${result.limit === void 0 ? result.message : `This email already backs ${result.limit} active agents \u2014 the per-email limit.`} Use a different email (a +alias works), recover a key for one of its agents, or paste an existing key.`;
     case "email-exhausted":
-      return "This email has reached the agent quota. Use a different email, or paste a key from an existing agent.";
+      return `${result.limit === void 0 ? result.message : `This email has used all ${result.limit} of its lifetime account registrations.`} Use a different email (a +alias works), or paste a key from an existing agent.`;
     case "rate-limited": {
       const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
       return `Rate limited.${wait}`;
@@ -658,8 +738,158 @@ function describeRegisterVerifyError(result) {
       return "Too many incorrect codes. Restart the wizard to receive a new one.";
     case "handle-taken":
       return "Your chosen handle was claimed by another registration in the meantime. Restart with a different handle.";
-    case "email-taken":
-      return "This email is already registered. Paste the existing key instead.";
+    case "email-limit-reached":
+      return `${result.limit === void 0 ? result.message : `This email reached its limit of ${result.limit} active agents while you were verifying.`} Restart with a different email (a +alias works), or paste an existing key.`;
+    case "email-exhausted":
+      return `${result.limit === void 0 ? result.message : `This email used all ${result.limit} of its lifetime account registrations while you were verifying.`} Restart with a different email (a +alias works), or paste an existing key.`;
+    case "rate-limited": {
+      const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
+      return `Rate limited.${wait}`;
+    }
+    case "network-error":
+    case "server-error":
+    case "unexpected-shape":
+    case "validation":
+    default:
+      return result.message;
+  }
+}
+async function runRecoverFlow(params) {
+  const { cfg, accountId, prompter, apiBase } = params;
+  const storedHandle = readAgentchatConfigField(cfg, accountId, "agentHandle");
+  const defaultHandle = storedHandle && isValidHandleShape(storedHandle) ? storedHandle : void 0;
+  await prompter.note(
+    [
+      "Recovery re-issues the API key for ONE agent \u2014 the handle you name below.",
+      "You need that handle and the email it registered with; a 6-digit code",
+      "goes to that email. The old key stops working the moment the new one",
+      "is minted.",
+      ...defaultHandle ? ["", `@${defaultHandle} is configured here \u2014 press Enter at the handle prompt to recover it.`] : []
+    ].join("\n"),
+    "AgentChat: recover a lost API key"
+  );
+  const handle = await promptHandle(prompter, {
+    message: "Handle of the agent to recover (its @name on AgentChat)",
+    ...defaultHandle ? { initialValue: defaultHandle } : {}
+  });
+  const email = await promptEmail(prompter, {
+    message: `Email @${handle} registered with \u2014 receives a 6-digit recovery code`
+  });
+  const startSpinner = prompter.progress("Requesting recovery code\u2026");
+  let startResult;
+  try {
+    startResult = await recoverAgentStart({ email, handle }, { apiBase });
+  } catch (err3) {
+    startSpinner.stop("Could not reach AgentChat");
+    await prompter.note(
+      `${err3 instanceof Error ? err3.message : String(err3)}. Try again when the network is available, or paste an existing key instead.`,
+      "Recovery failed"
+    );
+    return "abort";
+  }
+  if (!startResult.ok) {
+    startSpinner.stop("Recovery rejected");
+    await prompter.note(describeRecoverStartError(startResult), "Could not start recovery");
+    return "abort";
+  }
+  startSpinner.stop(startResult.message);
+  const maxCodeAttempts = 3;
+  let verifyResult = null;
+  for (let attempt = 1; attempt <= maxCodeAttempts; attempt += 1) {
+    const code = (await prompter.text({
+      message: attempt === 1 ? `Enter the 6-digit recovery code (check ${email}, including spam)` : `Recovery code (attempt ${attempt}/${maxCodeAttempts})`,
+      placeholder: "123456",
+      validate: (value) => {
+        const trimmed = value.trim();
+        if (!trimmed) return "Code is required";
+        if (!OTP_PATTERN.test(trimmed)) return "Code is 6 digits";
+        return void 0;
+      }
+    })).trim();
+    const verifySpinner = prompter.progress("Verifying code\u2026");
+    try {
+      verifyResult = await recoverAgentVerify({ pendingId: startResult.pendingId, code }, { apiBase });
+    } catch (err3) {
+      verifySpinner.stop("Could not reach AgentChat");
+      await prompter.note(
+        `${err3 instanceof Error ? err3.message : String(err3)}. Try again, or paste an existing key instead.`,
+        "Recovery failed"
+      );
+      return "abort";
+    }
+    if (verifyResult.ok) {
+      verifySpinner.stop(`Recovered @${verifyResult.handle}`);
+      break;
+    }
+    verifySpinner.stop("Verification failed");
+    if (verifyResult.reason === "invalid-code" && attempt < maxCodeAttempts) {
+      await prompter.note(
+        "That code did not match. Check your email and try again \u2014 if no code arrived, the handle and email may not belong to the same agent.",
+        "Invalid recovery code"
+      );
+      continue;
+    }
+    await prompter.note(describeRecoverVerifyError(verifyResult), "Recovery failed");
+    return "abort";
+  }
+  if (!verifyResult || !verifyResult.ok) {
+    await prompter.note(
+      "Too many incorrect codes. Restart the wizard to request a new one \u2014 and double-check the handle and email belong to the same agent.",
+      "Recovery failed"
+    );
+    return "abort";
+  }
+  const patch = { apiKey: verifyResult.apiKey };
+  if (isValidHandleShape(verifyResult.handle)) {
+    patch.agentHandle = verifyResult.handle;
+  }
+  const nextCfg = applyAgentchatAccountPatch(cfg, accountId, patch);
+  await prompter.note(
+    [
+      `Handle:       @${verifyResult.handle}`,
+      `API key:      ${redactKey(verifyResult.apiKey)} (saved to your OpenClaw config)`,
+      "",
+      "The previous key for this agent has been revoked."
+    ].join("\n"),
+    "AgentChat API key recovered"
+  );
+  return {
+    cfg: nextCfg,
+    credentialValues: {
+      token: verifyResult.apiKey,
+      [JUST_REGISTERED_SENTINEL]: "1"
+    }
+  };
+}
+function describeRecoverStartError(result) {
+  switch (result.reason) {
+    case "rate-limited": {
+      const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
+      return `Too many recovery attempts from this network.${wait}`;
+    }
+    case "validation":
+      return `AgentChat rejected the request: ${result.message}`;
+    case "network-error":
+    case "server-error":
+    case "unexpected-shape":
+    default:
+      return result.message;
+  }
+}
+function describeRecoverVerifyError(result) {
+  switch (result.reason) {
+    case "expired":
+      return "This recovery code expired. Restart the wizard to request a new one.";
+    case "invalid-code":
+      return "Too many incorrect codes. Restart the wizard to request a new one.";
+    case "handle-required": {
+      const handles = result.handles ?? [];
+      const list = handles.length > 0 ? `
+
+Agents on this email:
+${handles.map((h) => `  @${h}`).join("\n")}` : "";
+      return `This email backs more than one agent. Run recovery again and enter the handle you want to recover.${list}`;
+    }
     case "rate-limited": {
       const wait = result.retryAfterSeconds ? ` Try again in ${result.retryAfterSeconds}s.` : "";
       return `Rate limited.${wait}`;
@@ -707,7 +937,7 @@ var agentchatSetupWizard = {
     resolveStatusLines: ({ cfg, accountId, configured }) => {
       const id = accountId ?? "default";
       if (!configured) {
-        return ["AgentChat: not configured \u2014 the wizard will register you or accept an existing key."];
+        return ["AgentChat: not configured \u2014 the wizard will register you, accept an existing key, or recover a lost one."];
       }
       const handle = readAgentchatConfigField(cfg, id, "agentHandle");
       return [`AgentChat: configured${handle ? ` (@${handle})` : ""}`];
@@ -719,8 +949,9 @@ var agentchatSetupWizard = {
       "AgentChat is a messaging platform for AI agents \u2014 direct messages,",
       "groups, presence, attachments. Registration is free.",
       "",
-      "This wizard will either mint a new account via email OTP, or accept",
-      "an existing API key \u2014 your choice in the next prompt."
+      "This wizard will mint a new account via email OTP, accept an existing",
+      "API key, or recover a lost key (handle + email OTP) \u2014 your choice in",
+      "the next prompt."
     ]
   },
   prepare: async ({ cfg, accountId, credentialValues, prompter }) => {
@@ -741,7 +972,7 @@ var agentchatSetupWizard = {
           {
             value: "replace-key",
             label: "Replace the API key",
-            hint: "paste a new key, or register a new agent"
+            hint: "paste a new key, register a new agent, or recover a lost key"
           }
         ],
         initialValue: "keep"
@@ -763,6 +994,11 @@ var agentchatSetupWizard = {
           value: "paste",
           label: "I already have an API key",
           hint: "paste ac_live_\u2026 on the next prompt"
+        },
+        {
+          value: "recover",
+          label: "Recover a lost API key (handle + email OTP)",
+          hint: "an agent exists but its key is gone \u2014 re-issue it"
         }
       ],
       initialValue: "register"
@@ -771,19 +1007,32 @@ var agentchatSetupWizard = {
       return;
     }
     const apiBase = readAgentchatConfigField(cfg, accountId, "apiBase");
-    try {
-      const result = await runRegisterFlow({ cfg, accountId, prompter, apiBase });
-      if (result === "abort") {
+    const recover = async () => {
+      try {
+        const result = await runRecoverFlow({ cfg, accountId, prompter, apiBase });
+        if (result === "abort") {
+          await prompter.note(
+            "Recovery was not completed. You can still paste an existing API key at the next prompt, or cancel the wizard.",
+            "Falling back to credential entry"
+          );
+          return;
+        }
+        return result;
+      } catch (err3) {
+        if (err3 instanceof setup.WizardCancelledError) throw err3;
         await prompter.note(
-          "Registration was not completed. You can still paste an existing API key at the next prompt, or cancel the wizard.",
-          "Falling back to credential entry"
+          `${err3 instanceof Error ? err3.message : String(err3)}`,
+          "Recovery flow failed"
         );
         return;
       }
-      if (result === "user-chose-paste") {
-        return;
-      }
-      return result;
+    };
+    if (choice === "recover") {
+      return await recover();
+    }
+    let registerOutcome;
+    try {
+      registerOutcome = await runRegisterFlow({ cfg, accountId, prompter, apiBase });
     } catch (err3) {
       if (err3 instanceof setup.WizardCancelledError) throw err3;
       await prompter.note(
@@ -792,6 +1041,20 @@ var agentchatSetupWizard = {
       );
       return;
     }
+    if (registerOutcome === "abort") {
+      await prompter.note(
+        "Registration was not completed. You can still paste an existing API key at the next prompt, or cancel the wizard.",
+        "Falling back to credential entry"
+      );
+      return;
+    }
+    if (registerOutcome === "user-chose-paste") {
+      return;
+    }
+    if (registerOutcome === "user-chose-recover") {
+      return await recover();
+    }
+    return registerOutcome;
   },
   credentials: [
     {
@@ -5129,7 +5392,7 @@ var uiHints = {
     label: "AgentChat API key",
     placeholder: "ac_live_...",
     sensitive: true,
-    help: "The setup wizard registers you via email OTP and mints a key \u2014 or paste an existing ac_live_\u2026 key."
+    help: "The setup wizard registers you via email OTP and mints a key, recovers a lost key (handle + email OTP), or accepts an existing ac_live_\u2026 key."
   },
   apiBase: {
     label: "API base URL",
@@ -5240,7 +5503,7 @@ var agentchatPlugin = {
      */
     validateInput({ input }) {
       if (typeof input.token !== "string" || input.token.trim().length === 0) {
-        return "apiKey is required \u2014 pass via --token or run the register flow";
+        return "apiKey is required \u2014 pass via --token, or run `openclaw channels add agentchat` to register a new agent or recover a lost key (handle + email OTP)";
       }
       if (input.token.length < MIN_API_KEY_LENGTH) {
         return `apiKey looks too short (got ${input.token.length} chars, expect \u2265${MIN_API_KEY_LENGTH})`;
@@ -5357,6 +5620,8 @@ exports.assertApiKeyValid = assertApiKeyValid;
 exports.default = agentchatChannelEntry;
 exports.hasAgentChatConfiguredState = hasAgentChatConfiguredState;
 exports.parseChannelConfig = parseChannelConfig;
+exports.recoverAgentStart = recoverAgentStart;
+exports.recoverAgentVerify = recoverAgentVerify;
 exports.registerAgentStart = registerAgentStart;
 exports.registerAgentVerify = registerAgentVerify;
 exports.validateApiKey = validateApiKey;