@agentlayer.tech/wallet 0.1.58 → 0.1.64

package/.openclaw/extensions/agent-wallet/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Official OpenClaw plugin bridge for the agent-wallet backends, including Solana, local BTC, and local EVM.",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "contracts": {
     "tools": [
       "agentlayer_autonomous_approve",

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## v0.1.62 - 2026-07-04
+
+- Made default boot-key storage prompt-free on macOS. The automatic keystore
+  selection no longer probes macOS Keychain because even a read/probe through
+  `/usr/bin/security` can open a GUI password dialog during install or session
+  startup. macOS Keychain remains available only through explicit opt-in with
+  `AGENT_WALLET_KEYSTORE_BACKEND=macos-keychain` (or `native`), while the
+  default path uses the local fallback without showing Keychain prompts.
+  - `agent-wallet/agent_wallet/keystore.py`
+  - `agent-wallet/tests/smoke_keystore.py`
+
+## v0.1.61 - 2026-07-04
+
+- Hardened boot-key installation and migration around desktop keystores:
+  - The npm installer provisions the boot key through the runtime Python
+    keystore bridge instead of unconditionally persisting it in the release
+    `.env`, while keeping a legacy `.env` fallback when no non-interactive
+    keystore round-trip is available.
+  - The Node keystore bridge is bounded by a timeout so a hung Python/keychain
+    operation cannot stall install or reinstall.
+  - macOS keychain writes now run with non-interactive stdin, convert timeouts
+    into failed command results, and make the problematic
+    `set-generic-password-partition-list` ACL update strictly best-effort.
+  - Keystore resolution now verifies that a native backend can read the live
+    boot key or complete a write/read/delete probe before selecting it, falling
+    back cleanly when the OS tool exists but cannot authorize writes.
+  - `agent-wallet/agent_wallet/keystore.py`
+  - `bin/openclaw-agent-wallet.mjs`
+  - `agent-wallet/tests/smoke_keystore.py`
+
 ## v0.1.58 - 2026-07-01
 
 - Resolved SPL token symbol/name in `get_wallet_portfolio` via a batched,

package/README.md

@@ -102,7 +102,7 @@ The CLI uses a versioned runtime layout:
 ~/.openclaw/agent-wallet-runtime/current              # symlink → active release
 ```
 
-On first install, `--yes` generates local runtime secrets. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; only the boot key needed to unlock that sealed bundle is written to the runtime `.env`.
+On first install, `--yes` generates local runtime secrets. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; the boot key needed to unlock that sealed bundle stays in the prompt-free local fallback by default. macOS Keychain is opt-in (`AGENT_WALLET_KEYSTORE_BACKEND=macos-keychain`) because probing it can open a system password dialog during install or startup.
 
 Useful CLI commands (require the global install above):
 

package/VERSION

@@ -1 +1 @@
-0.1.58
+0.1.64

package/agent-wallet/agent_wallet/__init__.py

@@ -2,7 +2,7 @@
 
 # Keep in sync with package.json, pyproject.toml, and the npm installer version.
 # scripts/check_release_version.mjs enforces this on release.
-__version__ = "0.1.58"
+__version__ = "0.1.64"
 
 __all__ = [
     "config",

package/agent-wallet/agent_wallet/boot_key_migration.py

@@ -0,0 +1,158 @@
+"""Transparent, verified migration of the boot key into the OS keystore.
+
+Runs at backend startup. Non-destructive: plaintext is swept ONLY after the
+keystore read-back verifies. Idempotent and best-effort — a partial sweep
+re-runs cleanly next start. See BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from agent_wallet.config import (
+    read_boot_key_from_keystore,
+    resolve_openclaw_home,
+    settings,
+)
+from agent_wallet.file_ops import atomic_write_text
+from agent_wallet.keystore import BOOT_KEY_ITEM, PlaintextFileStore, resolve_keystore
+
+_ENV_LINE_PREFIX = "AGENT_WALLET_BOOT_KEY="
+
+
+def _read_legacy_boot_key() -> str:
+    """The authoritative live key from legacy sources only (env override -> file)."""
+    direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    if direct:
+        return direct
+    key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
+    if key_file:
+        try:
+            return Path(key_file).expanduser().read_text(encoding="utf-8").strip()
+        except OSError:
+            return ""
+    return ""
+
+
+def _env_boot_key_value(line: str) -> str | None:
+    """Return the boot-key value on an AGENT_WALLET_BOOT_KEY= line, else None."""
+    stripped = line.strip()
+    if not stripped.startswith(_ENV_LINE_PREFIX):
+        return None
+    return stripped[len(_ENV_LINE_PREFIX):].strip().strip('"').strip("'")
+
+
+def _strip_boot_key_line(env_path: Path, expected: str) -> bool:
+    """Remove only the AGENT_WALLET_BOOT_KEY line whose value == expected.
+
+    Preserve all other vars, and never strip a line carrying a *different* value
+    (that would signal a key mismatch a human should look at). Returns True if
+    the file changed.
+    """
+    try:
+        lines = env_path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return False
+    kept = [ln for ln in lines if _env_boot_key_value(ln) != expected]
+    if len(kept) == len(lines):
+        return False
+    atomic_write_text(env_path, ("\n".join(kept) + "\n") if kept else "", mode=0o600)
+    return True
+
+
+def _candidate_env_files(runtime: Path) -> list[Path]:
+    """Boot-key .env locations to sweep, deduped.
+
+    Deliberately bounded: a recursive ``**/.env`` walk descends into the hundreds
+    of ``node_modules`` trees under the release dirs and effectively hangs onboarding
+    (observed: 650+ node_modules, glob never returns). The boot key was only ever
+    written to ``releases/<v>/agent-wallet/.env``; ``current``/``previous`` are
+    symlinks into ``releases`` and are resolved to dedupe against their targets.
+    """
+    candidates = list(runtime.glob("releases/*/agent-wallet/.env"))
+    candidates.append(runtime / "current" / "agent-wallet" / ".env")
+    candidates.append(runtime / "previous" / "agent-wallet" / ".env")
+    seen: set[str] = set()
+    out: list[Path] = []
+    for path in candidates:
+        try:
+            key = str(path.resolve())
+        except OSError:
+            key = str(path)
+        if key in seen:
+            continue
+        seen.add(key)
+        if path.exists():
+            out.append(path)
+    return out
+
+
+def _sweep_plaintext(home: Path, expected: str) -> tuple[int, bool]:
+    """Strip matching boot-key lines from every runtime .env; delete the boot-key file.
+
+    Idempotent and value-scoped: only plaintext equal to the authoritative
+    keystore key is removed, so re-running after a fresh installer write (which
+    re-emits the same key) cleans it up on the next start.
+    """
+    runtime = home / "agent-wallet-runtime"
+    swept = 0
+    for env_path in _candidate_env_files(runtime):
+        try:
+            if _strip_boot_key_line(env_path, expected):
+                swept += 1
+        except Exception:
+            continue  # best-effort; re-runs next start
+    removed = False
+    boot_file = runtime / "boot-key"
+    try:
+        if boot_file.read_text(encoding="utf-8").strip() == expected:
+            boot_file.unlink()
+            removed = True
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+    return swept, removed
+
+
+def migrate_boot_key_to_keystore() -> dict:
+    """Move a legacy plaintext boot key into the keystore, verify, then sweep plaintext.
+
+    Runs on every startup (guarded once per process). When the keystore already
+    holds the key, it still re-sweeps any plaintext an installer re-emitted, so a
+    per-release .env write never re-establishes a permanent leak.
+    """
+    store = resolve_keystore()
+    home = resolve_openclaw_home()
+
+    # Do not sweep into a plaintext fallback: that offers no at-rest improvement,
+    # and the user explicitly chose to stay on the current file in that case.
+    if isinstance(store, PlaintextFileStore):
+        return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                "removed_boot_key_file": False, "reason": "no-os-keystore"}
+
+    authoritative = read_boot_key_from_keystore()
+    first_time = False
+    if not authoritative:
+        legacy_key = _read_legacy_boot_key()
+        if not legacy_key:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": "no-legacy-key"}
+        try:
+            store.set(BOOT_KEY_ITEM, legacy_key)
+        except Exception as exc:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": f"keystore-set-failed: {exc}"}
+        # Verify-before-delete.
+        if read_boot_key_from_keystore() != legacy_key:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": "verify-failed"}
+        authoritative = legacy_key
+        first_time = True
+
+    swept, removed = _sweep_plaintext(home, authoritative)
+    migrated = first_time or swept > 0 or removed
+    return {"migrated": migrated, "backend": store.backend_id, "swept_env_files": swept,
+            "removed_boot_key_file": removed,
+            "reason": "ok" if migrated else "already-clean"}

package/agent-wallet/agent_wallet/boot_key_recovery.py

@@ -0,0 +1,46 @@
+"""User-facing boot-key export/import for paper backup and machine recovery.
+
+The boot key is a retrievable string (baseline A), so recovery is simple: show
+it for a paper backup, or write a recorded value back into the keystore on a new
+machine. Full recovery kit = boot key + the already-encrypted sealed_keys.json +
+wallet files. See BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+from agent_wallet.config import read_boot_key_from_keystore, resolve_boot_key
+from agent_wallet.keystore import BOOT_KEY_ITEM, resolve_keystore
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+_EXPORT_WARNING = (
+    "SENSITIVE: anyone with this boot key AND your ~/.openclaw encrypted files "
+    "controls every wallet (Solana/EVM/BTC). Write it down and store it offline."
+)
+
+
+def export_boot_key() -> str:
+    """Return the live boot key. Raises if none is resolvable."""
+    key = resolve_boot_key()
+    if not key:
+        raise WalletBackendError(
+            "No boot key is available to export. The wallet is not set up on this machine."
+        )
+    return key
+
+
+def import_boot_key(value: str) -> dict:
+    """Write a recorded boot key into the OS keystore and verify the read-back."""
+    key = str(value or "").strip()
+    if not key:
+        raise WalletBackendError("A non-empty boot key is required for import.")
+    store = resolve_keystore()
+    store.set(BOOT_KEY_ITEM, key)
+    if read_boot_key_from_keystore() != key:
+        raise WalletBackendError(
+            f"Boot key import could not be verified from the {store.backend_id} keystore."
+        )
+    return {"imported": True, "backend": store.backend_id}
+
+
+def export_warning() -> str:
+    return _EXPORT_WARNING

package/agent-wallet/agent_wallet/config.py

@@ -385,11 +385,31 @@ def _env_bool(name: str, default: bool) -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def read_boot_key_from_keystore() -> str:
+    """Read the boot key from the OS keystore. Never raises; '' on any failure."""
+    try:
+        from agent_wallet.keystore import BOOT_KEY_ITEM, resolve_keystore
+
+        value = resolve_keystore().get(BOOT_KEY_ITEM)
+        return value.strip() if isinstance(value, str) else ""
+    except Exception:
+        return ""
+
+
 def resolve_boot_key() -> str:
-    """Resolve the boot key used to unlock sealed secrets from disk."""
+    """Resolve the boot key used to unlock sealed secrets from disk.
+
+    Precedence (superset of the legacy lookup, so existing installs keep working):
+      1. AGENT_WALLET_BOOT_KEY env / settings override
+      2. OS keystore (the hardened path)
+      3. AGENT_WALLET_BOOT_KEY_FILE / boot-key file (legacy)
+    """
     direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
     if direct:
         return direct
+    from_keystore = read_boot_key_from_keystore()
+    if from_keystore:
+        return from_keystore
     key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
     if not key_file:
         return ""

package/agent-wallet/agent_wallet/keystore.py

@@ -0,0 +1,303 @@
+"""Cross-platform, dependency-free secret storage for the wallet boot key.
+
+Backends shell out to tools already present on each desktop OS:
+  - macOS:   /usr/bin/security (generic password in the login keychain)
+  - Windows: powershell DPAPI (ConvertFrom/ConvertTo-SecureString), per-user+machine
+  - Linux:   secret-tool (libsecret) iff a Secret Service is reachable
+  - fallback: a 0600 plaintext file (current behavior) — never chosen over a
+              working keystore.
+
+The store holds ONE install-level secret (the boot key). See
+BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from agent_wallet.config import resolve_openclaw_home
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+
+KEYSTORE_SERVICE = "ai.agentlayer.wallet"
+BOOT_KEY_ITEM = "boot_key"
+_PROBE_ITEM = "__probe__"
+_KEYSTORE_BACKEND_ENV = "AGENT_WALLET_KEYSTORE_BACKEND"
+
+_SECURITY_BIN = "/usr/bin/security"
+_SUBPROCESS_TIMEOUT = 10.0
+
+
+def _service() -> str:
+    """Keychain/Secret-Service service name. Overridable so tests never touch the
+    real shared slot (the OS keychain is global, not scoped to OPENCLAW_HOME)."""
+    return os.getenv("AGENT_WALLET_KEYSTORE_SERVICE", "").strip() or KEYSTORE_SERVICE
+
+
+def _backend_preference() -> str:
+    """Selected keystore backend.
+
+    auto (default) prefers the native OS keystore (macOS Keychain / Windows DPAPI /
+    Linux Secret Service) and falls back to a 0600 plaintext file. macOS Keychain
+    is prompt-free because set() writes with `-A` (open ACL, no partition-list).
+    Override with AGENT_WALLET_KEYSTORE_BACKEND=plaintext|macos-keychain|native|...
+    """
+    return os.getenv(_KEYSTORE_BACKEND_ENV, "auto").strip().lower()
+
+
+class KeyStoreError(Exception):
+    """Raised when a keystore backend operation fails unexpectedly."""
+
+
+@runtime_checkable
+class KeyStore(Protocol):
+    backend_id: str
+
+    def available(self) -> bool: ...
+    def get(self, name: str) -> str | None: ...
+    def set(self, name: str, value: str) -> None: ...
+    def delete(self, name: str) -> None: ...
+
+
+def _timeout_output(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return value
+
+
+def _run(
+    argv: list[str],
+    *,
+    input_text: str | None = None,
+    timeout: float = _SUBPROCESS_TIMEOUT,
+) -> subprocess.CompletedProcess[str]:
+    kwargs: dict[str, object] = {
+        "capture_output": True,
+        "text": True,
+        "timeout": timeout,
+        "check": False,
+    }
+    if input_text is None:
+        kwargs["stdin"] = subprocess.DEVNULL
+    else:
+        kwargs["input"] = input_text
+    try:
+        return subprocess.run(argv, **kwargs)
+    except subprocess.TimeoutExpired as exc:
+        return subprocess.CompletedProcess(
+            argv,
+            124,
+            _timeout_output(exc.stdout),
+            _timeout_output(exc.stderr) or f"timed out after {timeout:g}s",
+        )
+
+
+class MacKeychainStore:
+    backend_id = "macos-keychain"
+
+    def available(self) -> bool:
+        return platform.system() == "Darwin" and Path(_SECURITY_BIN).exists()
+
+    def get(self, name: str) -> str | None:
+        proc = _run([_SECURITY_BIN, "find-generic-password", "-s", _service(), "-a", name, "-w"])
+        if proc.returncode != 0:
+            return None  # item not found (44) or other non-fatal lookup miss
+        value = proc.stdout.rstrip("\n")
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        # Recreate the item fresh with an open ACL. This is the ONLY reliably
+        # prompt-free way to write a login-keychain item non-interactively:
+        #   -A          -> accessible to any application without a prompt, and it
+        #                  bypasses the Sierra+ partition-list mechanism entirely.
+        #   delete+add  -> never -U-update an existing item; updating one created
+        #                  with a different ACL (or setting its partition list)
+        #                  pops a GUI keychain-password dialog in the background.
+        # Trade-off: any process running as this user can read the key without a
+        # prompt — the same runtime exposure as a 0600 file. At-rest protection
+        # (backups, synced home dirs, a stolen disk) is fully preserved.
+        _run([_SECURITY_BIN, "delete-generic-password", "-s", _service(), "-a", name])
+        proc = _run([
+            _SECURITY_BIN, "add-generic-password",
+            "-s", _service(), "-a", name,
+            "-w", value, "-A",
+        ])
+        if proc.returncode != 0:
+            raise KeyStoreError(f"security add-generic-password failed: {proc.stderr.strip()}")
+
+    def delete(self, name: str) -> None:
+        _run([_SECURITY_BIN, "delete-generic-password", "-s", _service(), "-a", name])
+
+
+class WindowsDpapiStore:
+    backend_id = "windows-dpapi"
+
+    def _blob_path(self, name: str) -> Path:
+        return resolve_openclaw_home() / "keystore" / f"{name}.dpapi"
+
+    def available(self) -> bool:
+        return platform.system() == "Windows" and shutil.which("powershell") is not None
+
+    def get(self, name: str) -> str | None:
+        path = self._blob_path(name)
+        if not path.exists():
+            return None
+        blob = path.read_text(encoding="utf-8").strip()
+        if not blob:
+            return None
+        script = (
+            "$ErrorActionPreference='Stop';"
+            "$b=[Console]::In.ReadToEnd().Trim();"
+            "$ss=ConvertTo-SecureString $b;"
+            "$p=[Runtime.InteropServices.Marshal]::PtrToStringUni("
+            "[Runtime.InteropServices.Marshal]::SecureStringToBSTR($ss));"
+            "[Console]::Out.Write($p)"
+        )
+        proc = _run(["powershell", "-NoProfile", "-NonInteractive", "-Command", script], input_text=blob)
+        if proc.returncode != 0:
+            return None
+        return proc.stdout or None
+
+    def set(self, name: str, value: str) -> None:
+        script = (
+            "$ErrorActionPreference='Stop';"
+            "$v=[Console]::In.ReadToEnd();"
+            "$ss=ConvertTo-SecureString $v -AsPlainText -Force;"
+            "[Console]::Out.Write((ConvertFrom-SecureString $ss))"
+        )
+        proc = _run(["powershell", "-NoProfile", "-NonInteractive", "-Command", script], input_text=value)
+        if proc.returncode != 0 or not proc.stdout.strip():
+            raise KeyStoreError(f"DPAPI ConvertFrom-SecureString failed: {proc.stderr.strip()}")
+        atomic_write_text(self._blob_path(name), proc.stdout.strip() + "\n", mode=0o600)
+
+    def delete(self, name: str) -> None:
+        path = self._blob_path(name)
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+
+class LinuxSecretServiceStore:
+    backend_id = "linux-secretservice"
+
+    def available(self) -> bool:
+        if platform.system() != "Linux" or shutil.which("secret-tool") is None:
+            return False
+        # A probe lookup succeeds (rc 0/1) only when a Secret Service answers;
+        # a missing/unreachable service errors out (rc >1) or times out.
+        try:
+            proc = _run(["secret-tool", "lookup", "service", _service(), "account", "__probe__"])
+        except subprocess.TimeoutExpired:
+            return False
+        return proc.returncode in (0, 1)
+
+    def get(self, name: str) -> str | None:
+        proc = _run(["secret-tool", "lookup", "service", _service(), "account", name])
+        if proc.returncode != 0:
+            return None
+        value = proc.stdout.rstrip("\n")
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        proc = _run(
+            ["secret-tool", "store", "--label", f"{_service()} {name}",
+             "service", _service(), "account", name],
+            input_text=value,
+        )
+        if proc.returncode != 0:
+            raise KeyStoreError(f"secret-tool store failed: {proc.stderr.strip()}")
+
+    def delete(self, name: str) -> None:
+        _run(["secret-tool", "clear", "service", _service(), "account", name])
+
+
+class PlaintextFileStore:
+    """Fallback: a 0600 file under OPENCLAW_HOME/keystore. Always available."""
+
+    backend_id = "plaintext-file"
+
+    def _path(self, name: str) -> Path:
+        return resolve_openclaw_home() / "keystore" / f"{name}.plaintext"
+
+    def available(self) -> bool:
+        return True
+
+    def get(self, name: str) -> str | None:
+        path = self._path(name)
+        if not path.exists():
+            return None
+        chmod_if_exists(path)
+        value = path.read_text(encoding="utf-8").strip()
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        atomic_write_text(self._path(name), value.strip() + "\n", mode=0o600)
+
+    def delete(self, name: str) -> None:
+        try:
+            self._path(name).unlink()
+        except FileNotFoundError:
+            pass
+
+
+def resolve_keystore() -> KeyStore:
+    """Return the first available OS-native backend, else the plaintext fallback."""
+    preference = _backend_preference()
+    if preference in {"plain", "plaintext", "plaintext-file", "file"}:
+        return PlaintextFileStore()
+
+    candidates: list[KeyStore]
+    if preference in {"macos", "macos-keychain", "keychain"}:
+        candidates = [MacKeychainStore()]
+    elif preference in {"windows", "windows-dpapi", "dpapi"}:
+        candidates = [WindowsDpapiStore()]
+    elif preference in {"linux", "linux-secretservice", "secretservice"}:
+        candidates = [LinuxSecretServiceStore()]
+    elif preference == "native":
+        candidates = [MacKeychainStore(), WindowsDpapiStore(), LinuxSecretServiceStore()]
+    else:
+        # Auto: native OS keystore first, plaintext fallback last. macOS Keychain
+        # is prompt-free now that set() uses `-A` (open ACL, no partition-list) and
+        # _backend_usable falls back gracefully if a session still can't authorize.
+        candidates = [MacKeychainStore(), WindowsDpapiStore(), LinuxSecretServiceStore()]
+
+    for candidate in candidates:
+        try:
+            if candidate.available() and _backend_usable(candidate):
+                return candidate
+        except Exception:
+            continue
+    return PlaintextFileStore()
+
+
+def _backend_usable(candidate: KeyStore) -> bool:
+    """Return true when a native backend can read the live key or write safely.
+
+    A desktop keystore binary can exist while the session cannot authorize
+    non-interactive writes. Treat that as unavailable so install/migration uses
+    the bounded fallback instead of hanging or repeatedly failing.
+    """
+    try:
+        if candidate.get(BOOT_KEY_ITEM):
+            return True
+    except Exception:
+        pass
+
+    probe_value = "ok"
+    try:
+        candidate.set(_PROBE_ITEM, probe_value)
+        return candidate.get(_PROBE_ITEM) == probe_value
+    except Exception:
+        return False
+    finally:
+        try:
+            candidate.delete(_PROBE_ITEM)
+        except Exception:
+            pass

package/agent-wallet/agent_wallet/openclaw_cli.py

@@ -582,6 +582,15 @@ def main() -> int:
     read_worker_parser.add_argument("--user-id", required=True)
     read_worker_parser.add_argument("--config-json", default="{}")
 
+    subparsers.add_parser("boot-key-export")
+
+    boot_key_import_parser = subparsers.add_parser("boot-key-import")
+    boot_key_import_parser.add_argument(
+        "--key-stdin",
+        action="store_true",
+        help="Read the boot key to import from stdin.",
+    )
+
     args = parser.parse_args()
 
     try:
@@ -705,6 +714,17 @@ def main() -> int:
             payload = asyncio.run(_run_evm_wallet_lock(args.user_id, config))
         elif args.command == "read-worker":
             return asyncio.run(_serve_read_worker(args.user_id, config))
+        elif args.command == "boot-key-export":
+            from agent_wallet.boot_key_recovery import export_boot_key, export_warning
+
+            print(export_warning(), file=sys.stderr)
+            payload = {"boot_key": export_boot_key()}
+        elif args.command == "boot-key-import":
+            if not args.key_stdin:
+                raise WalletBackendError("boot-key-import requires --key-stdin.")
+            from agent_wallet.boot_key_recovery import import_boot_key
+
+            payload = import_boot_key(_read_stdin_secret("boot key"))
         else:
             payload = asyncio.run(
                 _run_invoke(

package/agent-wallet/agent_wallet/openclaw_runtime.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from agent_wallet.approval import issue_approval_token
+from agent_wallet.boot_key_migration import migrate_boot_key_to_keystore
 from agent_wallet.btc_user_wallets import get_user_btc_wallet_binding
 from agent_wallet.config import normalize_btc_network, normalize_evm_network, settings
 from agent_wallet.evm_user_wallets import ensure_user_evm_wallet_ready
@@ -19,6 +20,24 @@ from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendErro
 from agent_wallet.wallet_layer.wdk_evm import WdkEvmLocalWalletBackend
 from agent_wallet.wallet_layer.wdk_btc import WdkBtcLocalWalletBackend
 
+_boot_key_migration_done = False
+
+
+def ensure_boot_key_migrated_once() -> None:
+    """Run the boot-key keystore migration at most once per process. Never raises.
+
+    Best-effort: a failure here must never block wallet onboarding — the legacy
+    plaintext sources still resolve via ``resolve_boot_key``.
+    """
+    global _boot_key_migration_done
+    if _boot_key_migration_done:
+        return
+    _boot_key_migration_done = True
+    try:
+        migrate_boot_key_to_keystore()
+    except Exception:
+        pass
+
 
 @dataclass(slots=True)
 class OpenClawWalletRuntimeContext:
@@ -98,6 +117,7 @@ def onboard_openclaw_user_wallet(
     wdk_evm_account_index: int | None = None,
 ) -> OpenClawWalletRuntimeContext:
     """Provision and assemble a runtime-ready wallet context for one OpenClaw user."""
+    ensure_boot_key_migrated_once()
     backend_name = str(backend or settings.agent_wallet_backend).strip().lower()
     effective_sign_only = True if read_only else (
         settings.agent_wallet_sign_only if sign_only is None else sign_only

package/agent-wallet/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Plugin-friendly wallet backend for OpenClaw agents with safe wallet tools and runtime instructions across Solana, local BTC, and local EVM.",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "skills": ["skills/wallet-operator"],
   "configSchema": {
     "type": "object",

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.58"
+version = "0.1.64"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/bin/openclaw-agent-wallet.mjs

@@ -23,6 +23,7 @@ const TELEMETRY_FLUSH_THROTTLE_SECONDS = 20;
 const TELEMETRY_FORCE_LINES = 25;
 const TELEMETRY_MAX_EVENTS_PER_FLUSH = 100;
 const TELEMETRY_HTTP_TIMEOUT_MS = 1500;
+const KEYSTORE_BRIDGE_TIMEOUT_MS = 30000;
 
 function printHelp() {
   console.log(`openclaw-agent-wallet
@@ -148,6 +149,11 @@ function telemetrySource(env = process.env) {
     : "global_cli";
 }
 
+function positiveIntEnv(name, fallback, env = process.env) {
+  const parsed = Number.parseInt(String(env[name] || ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 function telemetryGatewayUrl(env = process.env) {
   return String(env.PROVIDER_GATEWAY_URL || DEFAULT_PROVIDER_GATEWAY_URL).trim().replace(/\/+$/, "");
 }
@@ -900,6 +906,60 @@ function ensureBootKeyFile(env = process.env) {
   return { path: keyFile, status: "created" };
 }
 
+// Read the boot key from the OS keystore via the current runtime's Python
+// (best-effort, "" on any failure). Lets a re-install after the runtime migration
+// — which moves the key into the keystore and deletes every plaintext copy — still
+// resolve the existing boot key instead of refusing to touch sealed secrets.
+function readBootKeyFromKeystore(env = process.env) {
+  const runtimeRoot = resolvedCurrentRuntimeRoot(env);
+  if (!runtimeRoot) return "";
+  const py = resolveVenvPython(runtimeRoot);
+  if (!py) return "";
+  try {
+    const res = spawnSync(
+      py,
+      ["-c", "from agent_wallet.config import read_boot_key_from_keystore as r; print(r())"],
+      {
+        cwd: path.join(runtimeRoot, "agent-wallet"),
+        encoding: "utf8",
+        timeout: positiveIntEnv("AGENT_WALLET_KEYSTORE_BRIDGE_TIMEOUT_MS", KEYSTORE_BRIDGE_TIMEOUT_MS, env),
+        env: { ...env, OPENCLAW_HOME: resolveOpenclawHome(env) },
+      },
+    );
+    if ((res.status ?? 1) !== 0) return "";
+    return String(res.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+// Provision the boot key into the OS keystore via the freshly installed runtime's
+// Python. Returns true only when the import stored AND verified the key, so the
+// caller may safely drop the plaintext .env copy. Best-effort: false on any failure
+// (e.g. no usable keystore), in which case the caller keeps the legacy .env write.
+function provisionBootKeyToKeystore(releaseRoot, env, bootKey) {
+  const key = String(bootKey || "").trim();
+  if (!key) return false;
+  const py = resolveVenvPython(releaseRoot);
+  if (!py) return false;
+  try {
+    const res = spawnSync(
+      py,
+      ["-m", "agent_wallet.openclaw_cli", "boot-key-import", "--key-stdin"],
+      {
+        cwd: path.join(releaseRoot, "agent-wallet"),
+        input: key,
+        encoding: "utf8",
+        timeout: positiveIntEnv("AGENT_WALLET_KEYSTORE_BRIDGE_TIMEOUT_MS", KEYSTORE_BRIDGE_TIMEOUT_MS, env),
+        env: { ...env, OPENCLAW_HOME: resolveOpenclawHome(env) },
+      },
+    );
+    return (res.status ?? 1) === 0;
+  } catch {
+    return false;
+  }
+}
+
 function resolveVenvPython(releaseRoot) {
   const candidates = [
     path.join(releaseRoot, "agent-wallet", ".venv", "bin", "python"),
@@ -1169,7 +1229,8 @@ function buildInstallerEnv(args) {
     const existingBootKey =
       resolveBootKeyFromFile(env) ||
       readTextIfExists(defaultBootKeyFile(env)).trim() ||
-      currentBootKey(env);
+      currentBootKey(env) ||
+      readBootKeyFromKeystore(env);
     if (existingBootKey) {
       env.AGENT_WALLET_BOOT_KEY = existingBootKey;
     }
@@ -1318,9 +1379,17 @@ function runInstall(args, { commandName = "install" } = {}) {
   }
 
   if (env.AGENT_WALLET_BOOT_KEY) {
-    envFileSet(path.join(releaseRoot, "agent-wallet", ".env"), {
-      AGENT_WALLET_BOOT_KEY: env.AGENT_WALLET_BOOT_KEY,
-    });
+    const envPath = path.join(releaseRoot, "agent-wallet", ".env");
+    // Prefer the OS keystore: provision the boot key there and keep the plaintext
+    // out of the release .env entirely. Only fall back to the legacy .env write when
+    // no keystore round-trip is possible, so the runtime can still resolve the key.
+    if (provisionBootKeyToKeystore(releaseRoot, env, env.AGENT_WALLET_BOOT_KEY)) {
+      envFileUnset(envPath, ["AGENT_WALLET_BOOT_KEY"]);
+    } else {
+      envFileSet(envPath, {
+        AGENT_WALLET_BOOT_KEY: env.AGENT_WALLET_BOOT_KEY,
+      });
+    }
   }
 
   const pythonInfo = activePythonRuntimeInfo(env);

package/claude-code/plugins/agent-wallet/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-wallet",
   "displayName": "Agent Wallet",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "description": "Claude Code bridge for the existing AgentLayer wallet runtime. Connects to Solana, Bitcoin, and EVM wallets without creating a new one.",
   "author": {
     "name": "AgentLayer"

package/codex/plugins/agent-wallet/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-wallet",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "description": "Codex plugin bridge for the AgentLayer wallet runtime.",
   "author": {
     "name": "AgentLayer"

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -1,5 +1,5 @@
 name: agent-wallet
-version: 0.1.58
+version: 0.1.64
 description: Thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend
 provides_tools:
   - agent_wallet_tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {

package/wdk-btc-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-btc-wallet",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "private": true,
   "type": "module",
   "description": "Separate BTC-only wallet service built on Tether WDK.",

package/wdk-evm-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-evm-wallet",
-  "version": "0.1.58",
+  "version": "0.1.64",
   "private": true,
   "type": "module",
   "description": "Separate EVM wallet service built on Tether WDK.",