Agent Wallet OpenClaw Extension

Workspace extension for the official OpenClaw agent.

External install path:

openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin

This extension registers wallet tools through the official OpenClaw plugin API and forwards execution to the local Python agent-wallet backend.

It is designed so the OpenClaw agent sees a small operational wallet surface instead of raw key management. In practice this means the agent works through explicit tools for:

• EVM native balance, ERC-20 balance/metadata, fee-rate, receipt, Velora and Uniswap swap quote/execute, Aave V3 account/reserve/position flows, and transfer flows through the local wdk-evm-wallet backend
• wallet address, balances, and portfolio reads
• native SOL and SPL token transfers
• Jupiter swap and price lookup, including Solana swap intent execution that refreshes quotes inside user-approved limits
• Kamino lending read/deposit/withdraw/borrow/repay flows
• native Solana staking, stake deactivation, and stake withdrawal

Expected local layout:

• this extension lives at .openclaw/extensions/agent-wallet
• the Python package lives at agent-wallet/

Recommended config:

{
  "plugins": {
    "allow": ["agent-wallet"],
    "entries": {
      "agent-wallet": {
        "enabled": true,
        "config": {
          "userId": "openclaw-local-user",
          "backend": "solana_local",
          "network": "mainnet",
          "rpcUrls": [
            "https://your-primary-rpc.example",
            "https://api.mainnet-beta.solana.com"
          ],
          "signOnly": false,
          "encryptUserWallets": true,
          "migratePlaintextUserWallets": true,
          "refuseMainnetWalletRecreation": true,
          "packageRoot": "/absolute/path/to/agent-wallet",
          "pythonBin": "/absolute/path/to/python"
        }
      }
    }
  }
}

Recommended local installer entrypoint:

sh ./setup.sh

For packaged installs, keep the runtime installer path:

npx @agentlayer.tech/wallet install --yes

The ClawHub plugin package only installs the native OpenClaw plugin. It expects the authoritative Python runtime to already exist, and by default it now looks for it at:

~/.openclaw/agent-wallet-runtime/current/agent-wallet

If that runtime is not present, set plugins.entries.agent-wallet.config.packageRoot explicitly.

That installs the Python backend, Node dependencies for the local EVM runtime, patches the OpenClaw plugin config, and provisions the first encrypted per-user Solana mainnet wallet when no explicit signer is already configured. EVM readiness can still be auto-healed during normal wallet switching when the runtime has sealed local vault credentials.

For self-hosted installs, prefer SOLANA_RPC_URL / SOLANA_RPC_URLS in local env and treat the plugin rpcUrl / rpcUrls fields as fallback only. If the local runtime exposes ALCHEMY_API_KEY or HELIUS_API_KEY, the wallet can derive the Solana RPC URL automatically for mainnet. Local env always takes precedence over openclaw.json.

Provide only AGENT_WALLET_BOOT_KEY to the runtime. Provision master_key, approval_secret, and any signer private_key into sealed_keys.json, not openclaw.json.

Important:

• For a local official OpenClaw install, userId should represent the wallet owner for that agent install.
• The public OpenClaw plugin docs do not document a per-request end-user identifier in registerTool(...).execute(...), so dynamic multi-user wallet selection is intentionally kept in the Python/runtime layer, not inside the TypeScript plugin itself.
• Helper scripts in agent-wallet/scripts/ are generic patch/finalize utilities and no longer assume a specific local username, path, or temporary master key.
• The OpenClaw plugin API in this repo exposes tool registration, not host password prompts. EVM wallet create/unlock still is not a public agent tool, but the runtime can now auto-create or auto-unlock the local EVM wallet during set_wallet_backend or EVM tool calls when sealed_keys.json contains the local EVM vault password.
• The EVM flow also only supports local service URLs (127.0.0.1 / localhost / ::1) and uses a bearer token loaded from ~/.openclaw/wdk-evm-wallet/local-auth-token.
• The installer now provisions a sealed local EVM vault password under sealed_keys.json by default, and host-side EVM setup helpers refresh that sealed value whenever the operator enters a new password.
• The EVM tool surface is intentionally narrow: Velora and Uniswap swap quote/execute, Aave V3 account/reserve/position flows, native transfers, ERC-20 transfers, fee quotes, and receipt lookup only. No arbitrary calldata, standalone approvals, or generic contract execution are exposed to the agent.
• Velora swap and Aave V3 support are currently limited to ethereum and base. Test carefully because the upstream WDK protocol packages are still beta.
• Agents can call set_wallet_backend to switch the active wallet for the current OpenClaw plugin session between Solana and EVM. This does not edit openclaw.json; plugin config remains the startup default.
• EVM core read and transfer tools accept an optional per-call network override for ethereum, base, or robinhood; Velora/Aave remain limited to Ethereum/Base, while Uniswap supports all three.
• Agents can also call set_evm_network to select the active EVM network for the current OpenClaw plugin session. After that, EVM tools default to the selected network unless a specific call passes its own network value. Do not edit code, plugin config, or environment variables just to switch between Base, Ethereum, and Robinhood.
• get_wallet_balance returns an enriched wallet overview for Solana and EVM: native balance, discovered token balances, per-asset USD values when pricing is available, and total_value_usd.
• Solana wallet overview uses Solana RPC only for balance and token-account discovery. Token prices come from Jupiter, not RPC, and internal transfer/staking checks continue to use native-only balance reads.
• Optional Jupiter overrides are available via jupiterBaseUrl, jupiterUltraBaseUrl, jupiterPriceBaseUrl, jupiterPortfolioBaseUrl, and jupiterApiKey.
• Optional Kamino overrides are available via kaminoBaseUrl and kaminoProgramId.
• Jupiter Portfolio implementation remains in the backend, but those agent-facing tools are temporarily disabled for now.
• Mainnet wallets are pinned by address. If a pinned mainnet wallet file disappears, the runtime refuses to silently create a replacement wallet.

OpenClaw UX

The intended user-facing flow inside OpenClaw is:

1. Read first: use wallet address, balance, portfolio, validator list, or stake account inspection tools.
2. Preview next: transfers, swaps, Aave position changes, staking, stake deactivation, and stake withdrawals should start in preview.
3. Prepare only with intent: prepare is for explicit execution planning intent and returns no signed transaction bytes.
4. Execute only after chat confirmation: after the user explicitly confirms the shown preview/prepare summary in chat, call execute with the same semantic params. The OpenClaw extension handles the internal execution authorization automatically and binds it to the cached operation.
5. On mainnet, restate the network, asset, amount, and destination, validator, or stake account before execute.

For staking specifically, the normal agent flow should be:

1. get_solana_staking_validators
2. stake_sol_native in preview
3. stake_sol_native in execute
4. get_solana_stake_account
5. later, deactivate_solana_stake and withdraw_solana_stake

Switching networks

The extension is already network-aware:

• plugins.entries.agent-wallet.config.network selects mainnet for Solana or the supported EVM networks
• Solana mainnet wallets keep the same per-user file layout
• switching the configured backend network does not merge balances across chains

Recommended local switch helper:

python agent-wallet/scripts/switch_openclaw_wallet_network.py --network mainnet

Use --show-only first if you want to inspect the target wallet path before changing the config.

Private card storage

The cards skill uses the existing x402 tools. The Python runtime encrypts Laso responses before returning a vault reference, status and masked last4. No PAN, CVV or issuer token is returned to the extension. Installation and updates provision a card vault automatically on macOS; the backend also handles missing vaults for custom runtime user IDs before card payment.

The private key is held in macOS login Keychain with system authentication, separately from the wallet boot-key store. Use wallet vault list, wallet vault refresh <reference> and wallet vault reveal <reference> in your own terminal. The CLI reads the configured user ID; --user-id overrides it. macOS displays its own password dialog. Never pass passwords through plugin configuration or chat. Existing password vaults need one-time migration via wallet vault migrate. Managed Kernel checkout is available; local Chrome autofill remains separate.

Agent tools list_saved_cards, get_saved_card_status and refresh_saved_card forward to Python for a masked catalog and free pending-issuance retrieval. They take only local references/pagination, never user IDs, issuer credentials, URLs or headers. Pending retrieval uses backend-encrypted working credentials; card data is encrypted for the owner and is never returned to the extension. These are provider reads with local cache updates and no spending or signing. The Python bundle, Codex MCP bridge and OpenClaw schemas expose the same tools.

Private card use

use_saved_card previews an exact HTTPS request with card-field placeholders and can combine Laso issuance and use under one normal host confirmation. Execute with its operation_id. continue_vault_operation resumes an already authorized delayed task without a second approval or owner unlock; get_vault_operation reads its cached state. The fixed executor substitutes fields internally and returns HTTP status only. It never exposes PAN/CVV or raw provider output and never automatically repeats an uncertain payment.

Runtime-encrypted .use card capsules enable this path without a Keychain prompt per use. They are decryptable by the wallet runtime, including after issuance; this is a different boundary from the owner-authenticated reveal CLI. Authorization lasts 48 hours and binds the exact request/card/wallet. This supports private HTTPS use and managed Kernel checkout; local Chrome autofill remains separate.

Kernel browser connection

Run wallet vault kernel-connect in your own terminal and paste the dashboard API key at the hidden prompt. The key is saved in the encrypted runtime bundle, never in plugin config or chat. wallet vault kernel-status reports configuration; wallet vault kernel-disconnect removes the saved key.

kernel_browser prepares a billable cloud checkout with public form data. use_saved_card(checkout=...) binds the browser, exact page, USD total, field selectors and submit action to the existing host confirmation. It can issue a card in that same task. The backend fills privately, locks observations and closes the session after one attempt. Kernel and the merchant process the real card data; the model receives only safe status. No local browser installation is needed. See the vault guide for limits and cleanup behavior.