From 24cf00ee0e14f0682ca2d5c110a1b8e52ea043a9 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 20:23:04 +0800 Subject: [PATCH 01/44] fix --- docs/Agent-Wallet/FAQ.md | 164 ++++++ docs/Agent-Wallet/FullExample.md | 490 +++++++++++++++++ docs/Agent-Wallet/Intro.md | 123 +++++ docs/Agent-Wallet/QuickStart.md | 341 ++++++++++++ docs/Agent-Wallet/SDKQuickStart.md | 472 +++++++++++++++++ .../current/Agent-Wallet/FAQ.md | 164 ++++++ .../current/Agent-Wallet/FullExample.md | 500 ++++++++++++++++++ .../current/Agent-Wallet/Intro.md | 123 +++++ .../current/Agent-Wallet/QuickStart.md | 345 ++++++++++++ .../current/Agent-Wallet/SDKQuickStart.md | 472 +++++++++++++++++ .../current/sidebars.js | 6 + sidebars.js | 6 + 12 files changed, 3206 insertions(+) create mode 100644 docs/Agent-Wallet/FAQ.md create mode 100644 docs/Agent-Wallet/FullExample.md create mode 100644 docs/Agent-Wallet/Intro.md create mode 100644 docs/Agent-Wallet/QuickStart.md create mode 100644 docs/Agent-Wallet/SDKQuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md new file mode 100644 index 00000000..d8e87380 --- /dev/null +++ b/docs/Agent-Wallet/FAQ.md @@ -0,0 +1,164 @@ +# FAQ + +--- + +## About Agent-wallet + +### What is Agent-wallet and what does it do? + +Agent-wallet is a **signing-only SDK**. It does two things: stores private keys encrypted locally, and signs messages, transactions, and EIP-712 typed data locally. + +It does NOT: connect to RPCs, query on-chain data, build transactions, broadcast transactions, or initiate transfers or payments autonomously. + +This separation is intentional — signing is a highly sensitive operation that should be as simple, auditable, and dependency-free as possible. The more focused the SDK, the smaller the attack surface. + +### How is it different from a regular blockchain wallet? + +Regular wallets (like MetaMask or TronLink) are designed for human users — they typically include balance displays, transfer UIs, DApp connections, and require manual confirmation for every operation. + +Agent-wallet is designed for programs. It exposes only a signing interface, with no UI, no network functionality, and no need for human interaction. The caller (an MCP Server, workflow code, etc.) is responsible for building transactions; Agent-wallet only signs and returns the result for the caller to broadcast. + +### What about transfers and payments? + +Agent-wallet does not implement transfers itself. A complete transfer flow requires three steps: + +1. **Build the transaction** — The caller constructs an unsigned transaction object via TronGrid, Infura, or another RPC +2. **Sign** — The caller passes the unsigned transaction to Agent-wallet, which signs it locally and returns the result +3. **Broadcast** — The caller submits the signed transaction to the RPC for broadcasting + +Agent-wallet only participates in step 2. + +### What's the difference between the CLI and the SDK? Which should I use? + +Both provide the same underlying capabilities, but for different scenarios: + +- **CLI** is for manual operation — initializing wallets, managing keys, testing signatures by hand. Day-to-day key management is done through the CLI. +- **SDK** is for programmatic integration — calling the signing interface from your own code, such as inside an MCP Server or an automation script. + +Most users will use both: the CLI to initialize and manage wallets, and the SDK to call signing in code. + +--- + +## Local Mode vs. Static Mode + +### When should I use local mode vs. static mode? + +**Local mode** (set `AGENT_WALLET_PASSWORD`) is suitable when: +- You need to manage multiple wallets +- You want keys encrypted and persisted locally long-term +- You need to interact with wallets via the CLI + +**Static mode** (set `AGENT_WALLET_PRIVATE_KEY` or `AGENT_WALLET_MNEMONIC`) is suitable when: +- You only need a single wallet +- You're in a CI/CD or one-off script scenario +- Keys are already managed by an external system and you don't want an additional local storage layer + +### Can I use both modes at the same time? + +No, you can't run both simultaneously — but you can switch at any time. `AGENT_WALLET_PASSWORD` takes precedence over the private key / mnemonic variables. `AGENT_WALLET_PRIVATE_KEY` and `AGENT_WALLET_MNEMONIC` cannot be set at the same time. + +### How do I fill in the `network` parameter? + +The `network` parameter determines which chain adapter to use: + +| Value | Description | +| :--- | :--- | +| `eip155:1` | Ethereum Mainnet | +| `eip155:56` | BSC Mainnet | +| `eip155:137` | Polygon Mainnet | +| `eip155:8453` | Base Mainnet | +| `eip155:42161` | Arbitrum Mainnet | +| `tron:mainnet` | TRON Mainnet | +| `tron:nile` | TRON Nile Testnet | +| `tron:shasta` | TRON Shasta Testnet | + +Any value with the `eip155:` prefix routes to the EVM adapter; `tron:` routes to the TRON adapter. The chain ID itself doesn't affect signing logic — it only determines which adapter handles the request. + +--- + +## Security + +### How are private keys stored? + +In local mode, private keys are stored encrypted in **Keystore V3** format, using scrypt (N=262144, r=8, p=1) + AES-128-CTR + keccak256 MAC. This is the encryption standard widely used across the Ethereum ecosystem. The computational cost of scrypt is extremely high, making brute-force attacks effectively infeasible. + +The master password is never stored. `master.json` holds only an encrypted sentinel value used to verify whether a password is correct — not the password itself. + +### Will my keys ever be sent over the network? + +Never. All signing operations are pure local computation. Agent-wallet makes no network calls. Your private keys never leave your machine. + +### How should I protect my master password? + +- Pass it via an environment variable (`AGENT_WALLET_PASSWORD`) rather than writing it in code +- Don't commit `.env` files containing passwords to Git — add them to `.gitignore` +- Use a password manager (such as 1Password or Bitwarden) to store your master password + +### What if I forget my master password? + +The master password cannot be recovered. Agent-wallet does not store it and provides no recovery mechanism. + +If you forget your master password: +- If you have another backup of your private key (such as a mnemonic), run `agent-wallet reset` to wipe local data, then re-initialize and re-import your key +- If you have no other backup, the encrypted key files cannot be decrypted and access to those wallets is permanently lost + +This is why we strongly recommend **backing up your private key or mnemonic separately** when creating a wallet — don't rely solely on Agent-wallet's local storage. + +### Are keys used by AI agents safe? + +That depends on how you configure them. Recommended practices: + +- Create a dedicated wallet for the agent — don't use your personal primary wallet +- Fund that wallet with only the small amount the agent needs to operate +- Pass keys or passwords via environment variables — never hardcode them + +This way, even if the agent behaves unexpectedly, losses are limited to the pre-funded amount. + +--- + +## Cross-Language Compatibility + +### Are key files interchangeable between Python and TypeScript? + +Yes. Both implementations use the exact same Keystore V3 format. A key file created by Python can be read directly by TypeScript and vice versa. This means you can initialize a wallet with the CLI (TypeScript) and use the same keys directly in Python code. + +### Do both language versions produce the same signatures? + +Yes. The same private key signing the same data produces identical results in both Python and TypeScript. Address derivation rules and EIP-712 encoding logic are also identical. + +### What are the API differences between the two language versions? + +The interface design is a 1:1 correspondence. The main difference is naming convention: TypeScript uses camelCase (`signMessage`, `getActiveWallet`) while Python uses snake_case (`sign_message`, `get_active_wallet`). Behavior is otherwise identical. + +--- + +## Relationship with Other Components + +### What is the relationship between Agent-wallet and MCP Server? + +MCP Servers (such as TRON MCP Server and BSC MCP Server) provide AI agents with on-chain operation tools — querying balances, building transactions, etc. When an MCP Server needs a signature, it calls Agent-wallet to sign, then handles broadcasting itself. + +Agent-wallet is the signing backend for MCP Servers. MCP Servers do not directly handle private keys. + +### What is the relationship between Agent-wallet and the x402 protocol? + +x402 is an HTTP payment protocol. When an agent needs to complete an x402 payment, it must sign the PaymentPermit typed data (EIP-712 format). That signature is provided by Agent-wallet. + +The x402 SDK handles building payment requests and managing the protocol flow; Agent-wallet handles signing. Their responsibilities are clearly separated — Agent-wallet has no knowledge of or concern for x402 business logic. + +--- + +## Supported Chains + +| Chain Type | Network Identifier | Specific Networks | +| :--- | :--- | :--- | +| EVM | `eip155:*` | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | +| TRON | `tron:*` | TRON Mainnet, Nile Testnet, Shasta Testnet | + +--- + +## Next Steps + +- Initialize a wallet and start signing → [CLI Quick Start](./QuickStart.md) +- Integrate signing in your code → [SDK Quick Start](./SDKQuickStart.md) +- Understand the overall design → [Introduction](./Intro.md) diff --git a/docs/Agent-Wallet/FullExample.md b/docs/Agent-Wallet/FullExample.md new file mode 100644 index 00000000..0aa855a8 --- /dev/null +++ b/docs/Agent-Wallet/FullExample.md @@ -0,0 +1,490 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Full Usage Examples + +Agent-wallet handles signing only — building and broadcasting transactions is your responsibility. This page walks through complete end-to-end examples that chain all three steps together: TRON transfers, EVM transfers, and x402 PaymentPermit signing. + +All examples are available in both TypeScript and Python — use the tabs to switch. + +--- + +## Prerequisites + +Before running any example below, make sure you have: + +1. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) +2. Initialized a local wallet via the CLI, or configured static mode environment variables +3. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) + +--- + +## TRON Transfer + +**Use case**: An AI agent needs to initiate a TRX transfer on the TRON network — for example, paying API call fees, sweeping funds to another address, or settling a reward after completing an automated task. + +**How it works**: + +TRON transactions cannot be constructed directly by the client from scratch. The flow must start with a call to TronGrid's `createtransaction` endpoint, which returns an unsigned transaction object containing `txID` and `raw_data` generated by the network node. That object is then passed to Agent-wallet for local signing — the signing process is fully offline and the private key never leaves the machine. Finally, the signed transaction is submitted to TronGrid's `broadcasttransaction` endpoint to be published on-chain. + +``` +TronGrid (build) → Agent-wallet (sign) → TronGrid (broadcast) +``` + +Agent-wallet only participates in the middle signing step. It requires no RPC connection and has no awareness of the transaction's business meaning. + +### Install Dependencies + + + + +```bash +npm install @bankofai/agent-wallet axios +``` + + + + +```bash +pip install aiohttp +``` + +(The Agent-wallet Python SDK is already included — no separate install needed.) + + + + +### Full Code + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import axios from "axios"; + +const TRONGRID_API = "https://nile.trongrid.io"; // Nile testnet; change to https://api.trongrid.io for mainnet + +async function transferTRX( + fromAddress: string, + toAddress: string, + amountSun: number // 1 TRX = 1_000_000 SUN +) { + // Step 1: Initialize Agent-wallet + const provider = resolveWalletProvider({ network: "tron:nile" }); + const wallet = await provider.getActiveWallet(); + + // Step 2: Build the unsigned transaction via TronGrid + const { data: unsignedTx } = await axios.post( + `${TRONGRID_API}/wallet/createtransaction`, + { + owner_address: fromAddress, + to_address: toAddress, + amount: amountSun, + } + ); + + if (!unsignedTx.txID) { + throw new Error("Failed to build transaction: " + JSON.stringify(unsignedTx)); + } + + console.log("Unsigned txID:", unsignedTx.txID); + + // Step 3: Sign locally with Agent-wallet + const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + console.log("Signed, signature:", signedTx.signature); + + // Step 4: Broadcast via TronGrid + const { data: broadcastResult } = await axios.post( + `${TRONGRID_API}/wallet/broadcasttransaction`, + signedTx + ); + + if (broadcastResult.result) { + console.log("Broadcast successful! txID:", signedTx.txID); + } else { + console.error("Broadcast failed:", broadcastResult); + } + + return signedTx.txID; +} + +// Example usage +transferTRX( + "YOUR_TRON_ADDRESS", // replace with your wallet address + "RECIPIENT_TRON_ADDRESS", // replace with the recipient address + 1_000_000 // 1 TRX +).catch(console.error); +``` + + + + +```python +import asyncio +import json +import aiohttp +from agent_wallet import resolve_wallet_provider + +TRONGRID_API = "https://nile.trongrid.io" # Nile testnet; change to https://api.trongrid.io for mainnet + +async def transfer_trx( + from_address: str, + to_address: str, + amount_sun: int, # 1 TRX = 1_000_000 SUN +): + # Step 1: Initialize Agent-wallet + provider = resolve_wallet_provider(network="tron:nile") + wallet = await provider.get_active_wallet() + + async with aiohttp.ClientSession() as session: + # Step 2: Build the unsigned transaction via TronGrid + async with session.post( + f"{TRONGRID_API}/wallet/createtransaction", + json={ + "owner_address": from_address, + "to_address": to_address, + "amount": amount_sun, + }, + ) as resp: + unsigned_tx = await resp.json() + + if "txID" not in unsigned_tx: + raise ValueError(f"Failed to build transaction: {unsigned_tx}") + + print("Unsigned txID:", unsigned_tx["txID"]) + + # Step 3: Sign locally with Agent-wallet + signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) + print("Signed, signature:", signed_tx["signature"]) + + # Step 4: Broadcast via TronGrid + async with session.post( + f"{TRONGRID_API}/wallet/broadcasttransaction", + json=signed_tx, + ) as resp: + broadcast_result = await resp.json() + + if broadcast_result.get("result"): + print("Broadcast successful! txID:", signed_tx["txID"]) + else: + print("Broadcast failed:", broadcast_result) + + return signed_tx["txID"] + +# Example usage +asyncio.run( + transfer_trx( + from_address="YOUR_TRON_ADDRESS", # replace with your wallet address + to_address="RECIPIENT_TRON_ADDRESS", # replace with the recipient address + amount_sun=1_000_000, # 1 TRX + ) +) +``` + + + + +:::caution Notes +- Use the Nile testnet for testing. Get test tokens from the [Nile Faucet](https://nileex.io/join/getJoinPage). +- For mainnet, change `TRONGRID_API` to `https://api.trongrid.io` and `network` to `tron:mainnet`. +::: + +--- + +## EVM Transfer (BSC / Ethereum) + +**Use case**: An AI agent needs to initiate a native token transfer on BSC, Ethereum, or any other EVM-compatible chain — for example, paying gas, transferring to a contract to trigger business logic, or settling a payment on-chain after completing a task. + +**How it works**: + +EVM transactions require the caller to construct the transaction object themselves. Unlike TRON, the fields of an EVM transaction (`nonce`, `gas`, `chainId`, etc.) must be queried from the current chain state via RPC and filled in manually — there is no centralized API that generates them for you. Once the unsigned transaction is built, it is passed to Agent-wallet for local signing, which returns a hex-encoded signed transaction. That signed transaction is then broadcast to the network via `sendRawTransaction`. + +``` +RPC query nonce/gas (build) → Agent-wallet (sign) → RPC sendRawTransaction (broadcast) +``` + +The example uses BSC Testnet, but switching to Ethereum, Polygon, Base, or any other EVM chain only requires changing `RPC_URL` and `CHAIN_ID` — the Agent-wallet calling code stays exactly the same. + +### Install Dependencies + + + + +```bash +npm install @bankofai/agent-wallet ethers +``` + + + + +```bash +pip install web3 +``` + + + + +### Full Code + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { ethers } from "ethers"; + +// BSC Testnet +const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; +const CHAIN_ID = 97; // BSC testnet; use 56 for mainnet + +async function transferBNB( + toAddress: string, + amountEther: string // e.g. "0.001" +) { + // Step 1: Initialize Agent-wallet + const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); + const wallet = await provider.getActiveWallet(); + const fromAddress = await wallet.getAddress(); + + // Step 2: Query nonce and gas info via RPC + const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); + const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); + const feeData = await rpcProvider.getFeeData(); + + // Step 3: Build the unsigned transaction + const unsignedTx = { + to: toAddress, + value: ethers.parseEther(amountEther), + gas: 21000n, + maxFeePerGas: feeData.maxFeePerGas!, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas!, + nonce, + chainId: CHAIN_ID, + type: 2, // EIP-1559 + }; + + console.log("Transaction built, nonce:", nonce); + + // Step 4: Sign locally with Agent-wallet + const signedTxHex = await wallet.signTransaction(unsignedTx); + console.log("Signed"); + + // Step 5: Broadcast + const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); + console.log("Broadcast successful! txHash:", txResponse.hash); + + // Wait for confirmation (optional) + const receipt = await txResponse.wait(); + console.log("Confirmed in block:", receipt?.blockNumber); + + return txResponse.hash; +} + +// Example usage +transferBNB( + "0xYOUR_RECIPIENT_ADDRESS", // replace with the recipient address + "0.001" // send 0.001 BNB +).catch(console.error); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider +from web3 import AsyncWeb3 + +# BSC Testnet +RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" +CHAIN_ID = 97 # BSC testnet; use 56 for mainnet + +async def transfer_bnb(to_address: str, amount_ether: str): + # Step 1: Initialize Agent-wallet + provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") + wallet = await provider.get_active_wallet() + from_address = await wallet.get_address() + + # Step 2: Query nonce and gas info via RPC + w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) + nonce = await w3.eth.get_transaction_count(from_address, "latest") + fee_data = await w3.eth.fee_history(1, "latest", [50]) + base_fee = fee_data["baseFeePerGas"][-1] + priority_fee = await w3.eth.max_priority_fee + + # Step 3: Build the unsigned transaction + unsigned_tx = { + "to": to_address, + "value": w3.to_wei(amount_ether, "ether"), + "gas": 21000, + "maxFeePerGas": base_fee + priority_fee, + "maxPriorityFeePerGas": priority_fee, + "nonce": nonce, + "chainId": CHAIN_ID, + "type": 2, # EIP-1559 + } + + print("Transaction built, nonce:", nonce) + + # Step 4: Sign locally with Agent-wallet + signed_tx_hex = await wallet.sign_transaction(unsigned_tx) + print("Signed") + + # Step 5: Broadcast + tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) + print("Broadcast successful! txHash:", tx_hash.hex()) + + # Wait for confirmation (optional) + receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) + print("Confirmed in block:", receipt["blockNumber"]) + + return tx_hash.hex() + +# Example usage +asyncio.run( + transfer_bnb( + to_address="0xYOUR_RECIPIENT_ADDRESS", # replace with the recipient address + amount_ether="0.001", + ) +) +``` + + + + +:::caution Notes +- Use BSC Testnet (chainId=97) for testing. Get test tokens from the [BSC Faucet](https://testnet.binance.org/faucet-smart). +- For mainnet, change `RPC_URL` to a mainnet RPC endpoint, `CHAIN_ID` to `56`, and `network` to `eip155:56`. +::: + +--- + +## x402 PaymentPermit Signing + +**Use case**: An AI agent is accessing a paid API protected by the x402 protocol — such as fetching real-time data, calling an AI inference service, or triggering an on-chain operation. The server responds with HTTP 402, requiring the agent to provide a payment authorization before it can retrieve the content. + +**How it works**: + +x402 payments do not work by sending a direct transfer. Instead, they use a "sign first, verify to proceed" model. The agent signs a `TransferWithAuthorization` structure (EIP-712 format), and the resulting signature is sent alongside the request as a payment credential. The server verifies the signature and returns the content only if it is valid. The agent never has to wait for on-chain confirmation — latency is minimal. + +``` +Server returns 402 → Agent builds PaymentPermit → Agent-wallet signs → Resend request with signature → Server verifies and responds +``` + +The PaymentPermit data is automatically constructed by the x402 SDK based on the payment parameters returned by the server. Agent-wallet is only responsible for the final signing step. The example below shows the underlying signing logic, useful for scenarios that require custom integration or bypassing the x402 SDK. + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +async function signPaymentPermit(authorization: { + from: string; + to: string; + value: string; + validAfter: string; + validBefore: string; + nonce: string; +}) { + // Initialize Agent-wallet (EVM wallet, network must match the x402 payment network) + const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base mainnet + const wallet = await provider.getActiveWallet(); + + // Build EIP-712 typed data (aligned with the x402 protocol spec) + const typedData = { + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "version", type: "string" }, + { name: "chainId", type: "uint256" }, + { name: "verifyingContract", type: "address" }, + ], + TransferWithAuthorization: [ + { name: "from", type: "address" }, + { name: "to", type: "address" }, + { name: "value", type: "uint256" }, + { name: "validAfter", type: "uint256" }, + { name: "validBefore", type: "uint256" }, + { name: "nonce", type: "bytes32" }, + ], + }, + primaryType: "TransferWithAuthorization", + domain: { + name: "USD Coin", + version: "2", + chainId: 8453, + verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC + }, + message: authorization, + }; + + // Sign locally with Agent-wallet + const signature = await wallet.signTypedData(typedData); + console.log("PaymentPermit signature:", signature); + + return signature; +} +``` + + + + +```python +from agent_wallet import resolve_wallet_provider + +async def sign_payment_permit(authorization: dict) -> str: + # Initialize Agent-wallet (EVM wallet, network must match the x402 payment network) + provider = resolve_wallet_provider(network="eip155:8453") # Base mainnet + wallet = await provider.get_active_wallet() + + # Build EIP-712 typed data (aligned with the x402 protocol spec) + typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"}, + ], + "TransferWithAuthorization": [ + {"name": "from", "type": "address"}, + {"name": "to", "type": "address"}, + {"name": "value", "type": "uint256"}, + {"name": "validAfter", "type": "uint256"}, + {"name": "validBefore", "type": "uint256"}, + {"name": "nonce", "type": "bytes32"}, + ], + }, + "primaryType": "TransferWithAuthorization", + "domain": { + "name": "USD Coin", + "version": "2", + "chainId": 8453, + "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # Base USDC + }, + "message": authorization, + } + + # Sign locally with Agent-wallet + signature = await wallet.sign_typed_data(typed_data) + print("PaymentPermit signature:", signature) + + return signature +``` + + + + +:::tip +The x402 SDK automatically constructs the PaymentPermit data and calls the signing interface, so you typically won't need to write this code manually. The example above shows the underlying signing logic, which is useful for custom integration scenarios. See the [x402 Protocol documentation](../../x402/index.md) for details. +::: + +--- + +## Next Steps + +- Review the full signing API reference → [SDK Quick Start](./SDKQuickStart.md) +- Learn how x402 and Agent-wallet work together → [x402 Introduction](../../x402/index.md) +- Browse common questions → [FAQ](./FAQ.md) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md new file mode 100644 index 00000000..7fa9e4df --- /dev/null +++ b/docs/Agent-Wallet/Intro.md @@ -0,0 +1,123 @@ +# Introduction + +AI agents are increasingly involved in on-chain operations: paying API fees, signing authorizations, executing transfers. But there's an unavoidable challenge — private keys. + +Hardcoding private keys in source code is unsafe. Delegating them to a cloud service means losing control. Requiring manual confirmation for every operation defeats the purpose of "autonomous." + +AI agents need a way to **keep keys securely local, sign locally, and expose only a clean interface to the outside world**. + +That's the problem **Agent-wallet** is designed to solve. + +--- + +## What is Agent-wallet + +**Agent-wallet** is a **signing-only SDK** that enables AI agents (MCP servers, autonomous workflows, etc.) to securely manage and use blockchain keys. + +:::tip It does two things + +- **Key storage** — Encrypts and stores private keys locally using the Keystore V3 format +- **Local signing** — Signs messages, transactions, and EIP-712 typed data with zero network calls + +::: + +:::caution What it does NOT do + +- Does not connect to any RPC or query on-chain data +- Does not build transactions (the caller is responsible) +- Does not broadcast transactions (the caller is responsible) +- Does not initiate transfers or payments autonomously + +::: + +This separation of concerns keeps Agent-wallet lightweight and free from any dependency on a specific RPC provider. + +--- + +## Why Agent-wallet + +### Built for AI Agents + +Traditional wallets are designed for humans — they have interfaces, require manual confirmation, and assume a user is present. Agent-wallet's interface is designed for programs: configured via environment variables, called through an SDK, and naturally suited for embedding inside an MCP Server or automated workflow. + +### Private Keys Never Leave the Machine + +All signing happens locally with zero network requests. Private keys are never sent to any server, and there is no dependency on cloud HSMs or custodial services. You retain full control of your keys. + +### Bank-Grade Key Encryption + +Private keys are stored encrypted in **Keystore V3** format, using scrypt (with a computational cost orders of magnitude higher than standard bcrypt) + AES-128-CTR + keccak256 MAC. Even if the key file is stolen, the private key cannot be extracted without the master password. The master password itself is never stored to disk in any form. + +### Not Tied to Any RPC Provider + +Because Agent-wallet performs no on-chain operations, you can use any RPC provider — TronGrid, Infura, a self-hosted node — without affecting signing logic. Migrating or switching providers requires zero changes to signing code. + +### Multi-chain, Dual-language, One Interface + +EVM and TRON share the same `BaseWallet` interface. The Python and TypeScript implementations behave identically and share the same key file format. The same key, in a different language, produces the exact same signature. + +--- + +## Two Ways to Use It + +### CLI (Command-Line Tool) + +Best for managing keys, manually testing signatures, and daily key management tasks. + +```bash +npm install -g @bankofai/agent-wallet +agent-wallet start # Initialize and create a default wallet +agent-wallet sign msg "Hello" # Sign a message +``` + +→ See [CLI Quick Start](./QuickStart.md) + +### SDK (Programmatic Interface) + +Best for integrating signing capabilities in code, such as inside an MCP Server. + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + +Available in both **Python** and **TypeScript**, with identical interfaces and fully compatible output. + +→ See [SDK Quick Start](./SDKQuickStart.md) + +--- + +## Supported Chains + +| Chain Type | Network Identifier | Supported Networks | +| :--- | :--- | :--- | +| **EVM** | `eip155:*` | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | +| **TRON** | `tron:*` | TRON Mainnet, Nile Testnet, Shasta Testnet | + +--- + +## Where Agent-wallet Fits in the BANK OF AI Ecosystem + +Agent-wallet is the signing layer of the entire ecosystem. Other components (such as MCP Server and x402 SDK) rely on Agent-wallet for private key operations when signing is required: + +``` +AI Agent + └── Skills / x402 SDK ← Decides "what to do" + └── MCP Server ← Builds transactions, queries on-chain data + └── Agent-wallet ← Signs (and only that) +``` + +Agent-wallet has no knowledge of business logic. Its only job is to securely hold keys and sign on demand. + +--- + +## Where to Start + +| Your Goal | Start Here | +| :--- | :--- | +| Initialize a wallet, manage keys and sign via command line | [CLI Quick Start](./QuickStart.md) | +| Integrate signing in Python or TypeScript code | [SDK Quick Start](./SDKQuickStart.md) | +| Browse common questions | [FAQ](./FAQ.md) | diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md new file mode 100644 index 00000000..5131b7d2 --- /dev/null +++ b/docs/Agent-Wallet/QuickStart.md @@ -0,0 +1,341 @@ +# CLI Quick Start + +This guide walks you through installing Agent-wallet, initializing a wallet, and signing your first message or transaction from the command line. After completing these four steps, you'll have a locally encrypted wallet and be ready to sign messages and transactions via CLI. + +The second half of this page is a full command reference — come back to it whenever you need it. + +If you're a developer looking to call the signing interface directly from Python or TypeScript code, see [SDK Quick Start](./SDKQuickStart.md). + +--- + +## Step 1: Install + +### Check Your Node.js Version + +Agent-wallet CLI requires Node.js ≥ 18. First check your current version: + +```bash +node -v +``` + +If the output is `v18.0.0` or higher, you can jump straight to installation. Otherwise, follow the instructions below. + +:::tip Install / Upgrade Node.js + +We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions: + +```bash +# Install nvm (skip if already installed) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# Reload shell config +source ~/.bashrc # or source ~/.zshrc + +# Install Node.js 18 LTS +nvm install 18 + +# Switch to Node.js 18 +nvm use 18 +``` + +You can also download the **LTS** installer directly from [nodejs.org](https://nodejs.org). + +::: + +### Install Agent-wallet CLI + +```bash +npm install -g @bankofai/agent-wallet +``` + +Verify the installation: + +```bash +agent-wallet --help +``` + +--- + +## Step 2: Initialize a Wallet + +The `start` command handles initialization and wallet creation in one step. There are three options: + +### Option A: Fully Automatic (Recommended for Beginners) + +```bash +agent-wallet start +``` + +The system auto-generates a strong password and creates one TRON wallet and one EVM wallet: + +``` +🔐 Wallet initialized! + +🪙 Wallets: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│ default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ +│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ + +⭐ Active wallet: default_tron + +🔑 Your master password: E&LCi*KL1Sp4mg4! + ⚠️ Save this password! You'll need it for signing and other operations. +``` + +:::caution Security Tips +- **Keep your master password safe** — It's the only credential that decrypts all your private keys. If lost, it cannot be recovered. Use a password manager. +- **Never hardcode it in source code** — For non-interactive use, pass it via the `AGENT_WALLET_PASSWORD` environment variable instead. +- **Don't commit `.env` files** — Add `.env` to `.gitignore` to prevent passwords or keys from leaking into version control. +- **Use a dedicated wallet for agents** — Don't give an AI agent your personal wallet's private key. Create a separate wallet and fund it with only the amount the agent needs. +::: + +### Option B: Custom Password + +```bash +agent-wallet start -p Abc12345! +``` + +Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. + +### Option C: Import an Existing Private Key + +If you already have a private key you'd like to import: + +```bash +agent-wallet start -p Abc12345! -i tron +``` + +You'll be prompted to paste the private key (input is hidden): + +``` +🔐 Wallet initialized! +✔ Paste private key (hex) + +🪙 Imported wallet: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│ default_tron │ tron_local │ TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ + +⭐ Active wallet: default_tron +``` + +The `-i` flag accepts `tron`, `evm`, `tron_local`, or `evm_local`. + +--- + +## Step 3: View Your Wallets + +List all wallets: + +```bash +agent-wallet list +``` + +``` +Wallets: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│* default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ +│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ +``` + +The `*` marks the currently active wallet, which is used by default for all signing operations. + +--- + +## Step 4: Sign + +### Sign a Message + +```bash title="Input" +agent-wallet sign msg "Hello" +``` + +```text title="Output" +Master password: ******** +Signature: 4a9c8f...e71b +``` + +### Sign a Transaction + +Pass the transaction as a JSON string (you must build the unsigned transaction via RPC first): + +```bash title="Input" +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' +``` + +```text title="Output" +Master password: ******** +Signed tx: +{ + "txID": "abc123...", + "signature": ["..."] +} +``` + +### Sign EIP-712 Typed Data + +```bash title="Input" +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' +``` + +```text title="Output" +Master password: ******** +Signature: 22008ffd...0e1c +``` + +--- + +## Command Reference + +Once you've completed the quick start, refer to this section as needed. + +### Skip the Password Prompt + +Typing the password on every signing command gets tedious. Set an environment variable to skip the interactive prompt: + +```bash +export AGENT_WALLET_PASSWORD="Abc12345!" +``` + +After this, all signing commands run without prompting: + +```bash +agent-wallet sign msg "Hello" +agent-wallet sign tx '{"txID":"..."}' +``` + +You can also pass the password inline with `-p`: + +```bash +agent-wallet sign msg "Hello" -p "Abc12345!" +``` + +### Manage Multiple Wallets + +#### 1. Add a New Wallet + +An interactive prompt lets you choose the wallet type (`tron_local` or `evm_local`) and generate or import a key: + +```bash title="Input" +agent-wallet add +``` + +```text title="Output" +Master password: ******** +Wallet name: my-bsc-wallet +> Wallet type: evm_local +> Private key: generate +Generated new private key. + Address: 0x8c714fe3... + Saved: id_my-bsc-wallet.json +Wallet 'my-bsc-wallet' added. +``` + +#### 2. Switch the Active Wallet + +```bash title="Input" +agent-wallet use my-bsc-wallet +``` + +```text title="Output" +Active wallet: my-bsc-wallet (evm_local) +``` + +#### 3. Sign with a Specific Wallet + +Use `-w` to sign with a specific wallet regardless of the active wallet setting: + +```bash +agent-wallet sign msg "Hello" -w my-bsc-wallet -p "Abc12345!" +``` + +#### 4. Inspect a Wallet + +```bash title="Input" +agent-wallet inspect my-bsc-wallet +``` + +```text title="Output" +Wallet my-bsc-wallet +Type evm_local +Address 0x8c714fe3... +Identity id_my-bsc-wallet.json ✓ +Credential — +``` + +#### 5. Remove a Wallet + +```bash title="Input" +agent-wallet remove my-bsc-wallet +``` + +```text title="Output" +Remove wallet 'my-bsc-wallet'? (y/N): y + Deleted: id_my-bsc-wallet.json +Wallet 'my-bsc-wallet' removed. +``` + +### Other Operations + +#### 1. Change Master Password + +The master password is the only credential used to encrypt all local private keys. Agent-wallet never stores the master password itself — it uses the password to encrypt each key file. When you change it, all key files are re-encrypted with the new password. + +```bash title="Input" +agent-wallet change-password +``` + +```text title="Output" +Current password: ******** +New password: ******** +Confirm new password: ******** +Password changed. Re-encrypted 3 files. +``` + +#### 2. Reset All Data + +```bash title="Input" +agent-wallet reset +``` + +```text title="Output" +⚠️ This will delete ALL wallet data in: /home/you/.agent-wallet +Are you sure you want to reset? This cannot be undone. (y/N): y +Really delete everything? Last chance! (y/N): y +✅ Wallet data reset complete. +``` + +Deletes everything in `~/.agent-wallet/`. This action is irreversible and requires double confirmation. + +#### 3. Custom Storage Directory + +All commands support `--dir` to specify a custom key storage directory (default: `~/.agent-wallet`): + +```bash +agent-wallet start --dir ./my-secrets +agent-wallet sign msg "Hello" --dir ./my-secrets +``` + +--- + +## Next Steps + +- Use signing in your code → [SDK Quick Start](./SDKQuickStart.md) +- Understand the design → [Introduction](./Intro.md) +- Browse common questions → [FAQ](./FAQ.md) diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/SDKQuickStart.md new file mode 100644 index 00000000..4c99ef9d --- /dev/null +++ b/docs/Agent-Wallet/SDKQuickStart.md @@ -0,0 +1,472 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SDK Quick Start + +This page is for developers who want to call Agent-wallet's signing interface directly from Python or TypeScript code. + +Unlike the CLI, the SDK is designed for embedding signing capabilities into your own program — such as providing signing support for an AI agent inside an MCP Server, or authorizing on-chain operations from an automation script. Your code is responsible for building and broadcasting transactions; Agent-wallet handles local signing and returns the result. + +By the end of this guide, you'll be able to initialize a wallet provider in code, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data. If you haven't initialized a local wallet yet, it's recommended to complete Steps 1 through 3 of the [CLI Quick Start](./QuickStart.md) first. + +Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch between them. + +--- + +## Step 1: Install + + + + +**Check Your Node.js Version** + +Requires Node.js ≥ 18. Check your current version: + +```bash +node -v +``` + +If the output is `v18.0.0` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. + +:::tip Install / Upgrade Node.js + +We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions: + +```bash +# Install nvm (skip if already installed) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# Reload shell config +source ~/.bashrc # or source ~/.zshrc + +# Install and switch to Node.js 18 LTS +nvm install 18 +nvm use 18 +``` + +You can also download the **LTS** installer directly from [nodejs.org](https://nodejs.org). + +::: + +**Install the SDK** + +```bash +npm install @bankofai/agent-wallet +``` + + + + +**Check Your Python Version** + +Requires Python ≥ 3.10. Check your current version: + +```bash +python3 --version +``` + +If the output is `3.10.x` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. + +:::tip Install / Upgrade Python + +We recommend using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions: + +```bash +# Install pyenv (skip if already installed) +curl https://pyenv.run | bash + +# Reload shell config +source ~/.bashrc # or source ~/.zshrc + +# Install Python 3.10 +pyenv install 3.10 +pyenv global 3.10 +``` + +You can also download an installer from [python.org](https://www.python.org/downloads/), selecting **3.10 or higher**. + +::: + +**Install the SDK** + +The Python package is not yet published to PyPI and must be installed from source: + +```bash +git clone https://github.com/BofAI/agent-wallet.git +cd agent-wallet/packages/python +pip install -e ".[all]" +``` + +Verify the installation: + +```bash +python -c "import agent_wallet; print('Installation successful')" +``` + + + + +--- + +## Step 2: Configure a Mode + +Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. The SDK provides two modes — local mode is best for long-term management of multiple wallets, while static mode is best for directly injecting a private key. `resolveWalletProvider()` automatically detects the environment variables that are set and selects the corresponding mode, with no additional logic needed in your code. + +### Local Mode + +Private keys are stored encrypted on disk. Best for managing multiple wallets or persisting keys long-term. You must initialize first via the CLI (`agent-wallet start`), then set the master password: + +```bash +export AGENT_WALLET_PASSWORD="Abc12345!" +# Optional: custom directory, defaults to ~/.agent-wallet +export AGENT_WALLET_DIR="$HOME/.agent-wallet" +``` + +### Static Mode + +Provide a private key or mnemonic directly via environment variable — no local key file required. Best for CI/CD or one-off scripts. The `network` parameter must be specified when using static mode: + +```bash +export AGENT_WALLET_PRIVATE_KEY="your-private-key-in-hex" +# or +export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." +``` + +:::caution Notes +- `AGENT_WALLET_PASSWORD` takes precedence over `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` — if both are set, local mode is used +- `AGENT_WALLET_PRIVATE_KEY` and `AGENT_WALLET_MNEMONIC` cannot be set at the same time +- Never hardcode private keys or passwords in source code — always pass them via environment variables or a `.env` file, and add `.env` to `.gitignore` +::: + +### Environment Variable Reference + +| Variable | Purpose | Mode | Required | +| :--- | :--- | :--- | :--- | +| `AGENT_WALLET_PASSWORD` | Master password, enables local mode | Local mode | Required | +| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | Local mode | Optional | +| `AGENT_WALLET_PRIVATE_KEY` | Private key (hex) | Static mode | Required (choose one with mnemonic) | +| `AGENT_WALLET_MNEMONIC` | Mnemonic phrase | Static mode | Required (choose one with private key) | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | Derivation index for mnemonic (default `0`) | Static mode | Optional | + +--- + +## Usage Examples + +### Initialize the Wallet Provider + +The starting point for all operations is `resolveWalletProvider()`. It reads the environment variables, selects the appropriate mode, and returns a wallet provider. Call `getActiveWallet()` to get the active wallet. + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); + +// Check the current wallet address +const address = await wallet.getAddress(); +console.log("Address:", address); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + wallet = await provider.get_active_wallet() + + # Check the current wallet address + address = await wallet.get_address() + print("Address:", address) + +asyncio.run(main()) +``` + + + + +Once you have `wallet`, you can call any of the three signing methods below. All signing methods return a hex-encoded signature string (without the `0x` prefix). + +### Sign a Message + + + + +```typescript +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_message(b"Hello") +print("Signature:", sig) +``` + + + + +### Sign a Transaction + +Agent-wallet only handles signing — not building or broadcasting. You need to construct the unsigned transaction via RPC (e.g. TronGrid, Infura) first, then pass it to the SDK for signing. + +#### TRON Transaction + + + + +```typescript +// 1. Caller builds the unsigned transaction via TronGrid +const unsignedTx = { + txID: "abc123...", + raw_data_hex: "0a02...", + raw_data: { /* raw data returned by TronGrid */ }, +}; + +// 2. SDK signs locally (no network call) +const signedTxJson = await wallet.signTransaction(unsignedTx); +console.log("Signed transaction:", signedTxJson); + +// 3. Caller is responsible for broadcasting +``` + + + + +```python +# 1. Caller builds the unsigned transaction via TronGrid +unsigned_tx = { + "txID": "abc123...", + "raw_data_hex": "0a02...", + "raw_data": {}, # raw data returned by TronGrid +} + +# 2. SDK signs locally (no network call) +signed_tx_json = await wallet.sign_transaction(unsigned_tx) +print("Signed transaction:", signed_tx_json) + +# 3. Caller is responsible for broadcasting +``` + + + + +#### EVM Transaction (BSC, Ethereum, etc.) + + + + +```typescript +const sig = await wallet.signTransaction({ + to: "0xRecipient...", + value: 0n, + gas: 21000n, + maxFeePerGas: 20000000000n, + nonce: 0, + chainId: 56, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_transaction({ + "to": "0xRecipient...", + "value": 0, + "gas": 21000, + "maxFeePerGas": 20000000000, + "nonce": 0, + "chainId": 56, +}) +print("Signature:", sig) +``` + + + + +### Sign EIP-712 Typed Data + +Used for x402 protocol PaymentPermit signatures, Permit2, and similar scenarios: + + + + +```typescript +const sig = await wallet.signTypedData({ + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "chainId", type: "uint256" }, + ], + Transfer: [ + { name: "to", type: "address" }, + { name: "amount", type: "uint256" }, + ], + }, + primaryType: "Transfer", + domain: { name: "MyDApp", chainId: 1 }, + message: { to: "0x...", amount: 1000000 }, +}); +console.log("Signature:", sig); +``` + + + + +```python +sig = await wallet.sign_typed_data({ + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + ], + "Transfer": [ + {"name": "to", "type": "address"}, + {"name": "amount", "type": "uint256"}, + ], + }, + "primaryType": "Transfer", + "domain": {"name": "MyDApp", "chainId": 1}, + "message": {"to": "0x...", "amount": 1000000}, +}) +print("Signature:", sig) +``` + + + + +--- + +### Manage Multiple Wallets + +If you need to manage multiple wallets in code, use `LocalWalletProvider` directly: + + + + +```typescript +import { LocalWalletProvider } from "@bankofai/agent-wallet"; + +const provider = new LocalWalletProvider("~/.agent-wallet", "Abc12345!"); + +// List all wallets +const wallets = await provider.listWallets(); +for (const w of wallets) { + console.log(`${w.id} (${w.type}): ${w.address}`); +} + +// Switch the active wallet +provider.setActive("my-evm-wallet"); + +// Get and use +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + + + + +```python +# Set the env var — resolve_wallet_provider automatically enters local mode +import os +os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" + +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider() + +async def main(): + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) + +asyncio.run(main()) +``` + + + + +--- + +### Error Handling + +When a signing operation fails, the SDK throws specific error types. It's recommended to catch and handle them explicitly in your code to avoid runtime crashes. + + + + +```typescript +import { + WalletNotFoundError, + SigningError, + DecryptionError, +} from "@bankofai/agent-wallet"; + +try { + const wallet = await provider.getActiveWallet(); + const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); + console.log("Signature:", sig); +} catch (e) { + if (e instanceof WalletNotFoundError) { + console.error("Wallet not found — check that an active wallet is set"); + } else if (e instanceof DecryptionError) { + console.error("Decryption failed — check that the master password is correct"); + } else if (e instanceof SigningError) { + console.error("Signing failed:", e.message); + } else { + throw e; + } +} +``` + + + + +```python +from agent_wallet import WalletNotFoundError, SigningError, DecryptionError + +try: + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("Signature:", sig) +except WalletNotFoundError: + print("Wallet not found — check that an active wallet is set") +except DecryptionError: + print("Decryption failed — check that the master password is correct") +except SigningError as e: + print(f"Signing failed: {e}") +``` + + + + +Error type hierarchy: + +``` +WalletError +├── WalletNotFoundError # Specified wallet not found +├── DecryptionError # Wrong password or corrupted key file +├── SigningError # Signing operation failed +├── NetworkError # Network identifier mismatch +├── InsufficientBalanceError # Insufficient balance (thrown by caller) +└── UnsupportedOperationError # Operation not supported by this wallet type +``` + +--- + +## Next Steps + +- Manage wallets from the command line → [CLI Quick Start](./QuickStart.md) +- Understand Agent-wallet's design → [Introduction](./Intro.md) +- Browse common questions → [FAQ](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md new file mode 100644 index 00000000..d04a3b0e --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -0,0 +1,164 @@ +# 常见问题 + +--- + +## 关于 Agent-wallet 的定位 + +### Agent-wallet 是什么？它能做什么？ + +Agent-wallet 是一个**仅用于签名的 SDK**。它做两件事：将私钥加密存储在本地，以及对消息、交易、EIP-712 结构化数据进行本地签名。 + +它不做：连接 RPC、查链上数据、构建交易、广播交易、自主发起转账或支付。 + +这种职责划分是有意为之的——签名是一个高度敏感的操作，应该尽量简单、可审计、无外部依赖。SDK 越专注，攻击面就越小。 + +### 它和普通区块链钱包有什么区别？ + +普通钱包（如 MetaMask、TronLink）是面向人类用户的，通常包含余额显示、转账界面、DApp 连接等完整功能，每次操作都需要人工确认。 + +Agent-wallet 是面向程序的。它只暴露一个签名接口，没有界面，没有网络功能，也不需要人工介入。调用者（MCP Server、工作流代码等）负责构建交易，Agent-wallet 只负责签名，然后把签名结果返回给调用者去广播。 + +### 那转账和支付怎么实现？ + +Agent-wallet 本身不实现转账。完整的转账流程需要三个步骤： + +1. **构建交易** — 调用者通过 TronGrid、Infura 等 RPC 接口构建未签名的交易对象 +2. **签名** — 调用者把未签名交易传给 Agent-wallet，SDK 在本地签名并返回签名结果 +3. **广播** — 调用者把签名后的交易提交给 RPC 广播到链上 + +Agent-wallet 只参与第 2 步。 + +### CLI 和 SDK 有什么区别，我该用哪个？ + +两者底层能力相同，使用场景不同： + +- **CLI** 适合人工操作——初始化钱包、管理密钥、手动测试签名。日常的密钥管理工作都通过 CLI 完成。 +- **SDK** 适合程序集成——在你自己的代码里调用签名接口，比如在 MCP Server 内部、或自动化脚本中使用。 + +大多数用户会同时用到两者：用 CLI 初始化和管理钱包，用 SDK 在代码里调用签名。 + +--- + +## 本地模式和静态模式 + +### 什么时候用本地模式，什么时候用静态模式？ + +**本地模式**（设置 `AGENT_WALLET_PASSWORD`）适合： +- 需要管理多个钱包 +- 希望密钥长期加密存储在本地 +- 需要通过 CLI 交互式操作钱包 + +**静态模式**（设置 `AGENT_WALLET_PRIVATE_KEY` 或 `AGENT_WALLET_MNEMONIC`）适合： +- 只需要一个钱包 +- CI/CD 或临时脚本场景 +- 私钥已由外部系统管理，不想再加一层本地存储 + +### 两种模式可以混用吗？ + +不可以同时用，但可以随时切换。`AGENT_WALLET_PASSWORD` 的优先级高于私钥/助记词。`AGENT_WALLET_PRIVATE_KEY` 和 `AGENT_WALLET_MNEMONIC` 不能同时设置。 + +### network 参数怎么填？ + +`network` 参数决定使用哪种链的适配器： + +| 值 | 说明 | +| :--- | :--- | +| `eip155:1` | Ethereum 主网 | +| `eip155:56` | BSC 主网 | +| `eip155:137` | Polygon 主网 | +| `eip155:8453` | Base 主网 | +| `eip155:42161` | Arbitrum 主网 | +| `tron:mainnet` | TRON 主网 | +| `tron:nile` | TRON Nile 测试网 | +| `tron:shasta` | TRON Shasta 测试网 | + +只要前缀是 `eip155:` 就走 EVM 适配器，前缀是 `tron:` 就走 TRON 适配器。链 ID 本身不影响签名逻辑，只是用于路由到正确的适配器。 + +--- + +## 安全性 + +### 私钥以什么方式存储？ + +本地模式下，私钥以 **Keystore V3** 格式加密存储，使用 scrypt（N=262144, r=8, p=1）+ AES-128-CTR + keccak256 MAC 组合。这是与 Ethereum 生态广泛兼容的加密标准，scrypt 的计算成本极高，有效抵抗暴力破解。 + +主密码本身从不存储。`master.json` 只保存一个加密的哨兵值，用于验证密码是否正确，而不是密码本身。 + +### 密钥会发送到网络吗？ + +不会。所有签名操作都是纯本地计算，Agent-wallet 没有任何网络调用。私钥永远不离开你的机器。 + +### 我应该怎么保护主密码？ + +- 通过环境变量（`AGENT_WALLET_PASSWORD`）传入，而不是写在代码里 +- 不要把包含密码的 `.env` 文件提交到 Git，将其加入 `.gitignore` +- 建议使用密码管理器（如 1Password、Bitwarden）保存主密码 + +### 忘记主密码了怎么办？ + +主密码无法找回。Agent-wallet 不存储主密码，也没有任何找回机制。 + +如果你忘记了主密码： +- 如果你有私钥的其他备份（如助记词），可以运行 `agent-wallet reset` 清空本地数据，然后重新初始化并导入私钥 +- 如果没有其他备份，加密的私钥文件将无法解密，对应的钱包访问权限会永久丢失 + +这也是为什么强烈建议在创建钱包时**单独备份私钥或助记词**，不要只依赖 Agent-wallet 的本地存储。 + +### 给 AI 代理使用的密钥安全吗？ + +取决于如何配置。推荐做法： + +- 为代理创建一个专用钱包，不要使用你的个人主钱包 +- 只向该钱包充入代理运行所需的小额资金 +- 通过环境变量传入私钥或密码，不要硬编码在代码里 + +这样即使代理行为异常，损失也被限制在预充的范围内。 + +--- + +## 跨语言兼容性 + +### Python 和 TypeScript 的密钥文件可以互换吗？ + +可以。两个实现使用完全相同的 Keystore V3 格式。Python 创建的密钥文件可以直接被 TypeScript 读取，反之亦然。这意味着你可以用 CLI（TypeScript 版）初始化钱包，然后在 Python 代码里直接使用同一套密钥。 + +### 两个语言版本签名结果一样吗？ + +是的。同一个私钥对同一段数据签名，Python 和 TypeScript 产生的签名结果完全一致。地址派生规则、EIP-712 编码逻辑也完全相同。 + +### 两个语言版本的 API 有什么差异？ + +接口设计完全对应，主要差异是命名风格：TypeScript 使用驼峰命名（`signMessage`、`getActiveWallet`），Python 使用下划线命名（`sign_message`、`get_active_wallet`）。除此之外行为一致。 + +--- + +## 与其他组件的关系 + +### Agent-wallet 和 MCP Server 是什么关系？ + +MCP Server（如 TRON MCP Server、BSC MCP Server）为 AI 代理提供链上操作工具，比如查询余额、构建交易。当 MCP Server 需要签名时，它调用 Agent-wallet 来完成签名，然后自己负责广播。 + +Agent-wallet 是 MCP Server 的签名后端，MCP Server 不直接接触私钥。 + +### Agent-wallet 和 x402 协议是什么关系？ + +x402 是一个 HTTP 支付协议，当代理需要完成一笔 x402 支付时，需要对 PaymentPermit 结构化数据（EIP-712 格式）进行签名。这个签名由 Agent-wallet 提供。 + +x402 SDK 负责构建支付请求和处理协议流程，Agent-wallet 负责签名。两者分工明确，Agent-wallet 本身不了解也不关心 x402 的业务逻辑。 + +--- + +## 支持哪些链 + +| 链类型 | 网络标识符 | 具体网络 | +| :--- | :--- | :--- | +| EVM | `eip155:*` | Ethereum、BSC、Polygon、Base、Arbitrum 以及任何 EVM 兼容链 | +| TRON | `tron:*` | TRON 主网、Nile 测试网、Shasta 测试网 | + +--- + +## 下一步 + +- 初始化钱包并开始签名 → [CLI 快速开始](./QuickStart.md) +- 在代码中集成签名能力 → [SDK 快速开始](./SDKQuickStart.md) +- 了解整体设计 → [简介](./Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md new file mode 100644 index 00000000..614d848a --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md @@ -0,0 +1,500 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 完整使用示例 + +Agent-wallet 只负责签名，构建交易和广播由调用者完成。本页通过完整的代码示例，演示如何将这三个步骤串联起来——包括 TRON 转账、EVM 转账，以及 x402 PaymentPermit 签名场景。 + +每个示例均提供 TypeScript 和 Python 两个版本，可通过标签切换。 + +--- + +## 准备工作 + +在运行以下示例前，请确保： + +1. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） +2. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 +3. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） + +--- + +## TRON 转账 + +**适用场景**：AI 代理需要在 TRON 链上发起一笔 TRX 转账，例如支付 API 调用费用、向另一个地址归集资金，或在自动化任务完成后结算报酬。 + +**流程说明**： + +TRON 的转账不能由客户端直接凭空构造，必须先调用 TronGrid 的 `createtransaction` 接口，由链上节点生成一个包含 `txID` 和 `raw_data` 的未签名交易对象。拿到这个对象后，交给 Agent-wallet 在本地完成签名——签名过程完全离线，私钥不离开本机。最后把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口广播上链。 + +``` +TronGrid（构建）→ Agent-wallet（签名）→ TronGrid（广播） +``` + +Agent-wallet 只参与中间的签名步骤，不依赖任何 RPC 连接，也不感知交易的业务含义。 + +### 安装依赖 + + + + +```bash +npm install @bankofai/agent-wallet axios +``` + + + + +```bash +pip install aiohttp +``` + +（Agent-wallet Python SDK 已包含，无需单独安装。） + + + + +### 完整代码 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import axios from "axios"; + +const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网，主网改为 https://api.trongrid.io + +async function transferTRX( + fromAddress: string, + toAddress: string, + amountSun: number // 1 TRX = 1_000_000 SUN +) { + // 第一步：初始化 Agent-wallet + const provider = resolveWalletProvider({ network: "tron:nile" }); + const wallet = await provider.getActiveWallet(); + + // 第二步：通过 TronGrid 构建未签名交易 + const { data: unsignedTx } = await axios.post( + `${TRONGRID_API}/wallet/createtransaction`, + { + owner_address: fromAddress, + to_address: toAddress, + amount: amountSun, + } + ); + + if (!unsignedTx.txID) { + throw new Error("构建交易失败：" + JSON.stringify(unsignedTx)); + } + + console.log("未签名交易 txID:", unsignedTx.txID); + + // 第三步：Agent-wallet 本地签名 + const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + console.log("签名完成，signature:", signedTx.signature); + + // 第四步：通过 TronGrid 广播 + const { data: broadcastResult } = await axios.post( + `${TRONGRID_API}/wallet/broadcasttransaction`, + signedTx + ); + + if (broadcastResult.result) { + console.log("广播成功！txID:", signedTx.txID); + } else { + console.error("广播失败：", broadcastResult); + } + + return signedTx.txID; +} + +// 使用示例 +transferTRX( + "YOUR_TRON_ADDRESS", // 替换为你的钱包地址 + "RECIPIENT_TRON_ADDRESS", // 替换为接收方地址 + 1_000_000 // 1 TRX +).catch(console.error); +``` + + + + +```python +import asyncio +import json +import aiohttp +from agent_wallet import resolve_wallet_provider + +TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网，主网改为 https://api.trongrid.io + +async def transfer_trx( + from_address: str, + to_address: str, + amount_sun: int, # 1 TRX = 1_000_000 SUN +): + # 第一步：初始化 Agent-wallet + provider = resolve_wallet_provider(network="tron:nile") + wallet = await provider.get_active_wallet() + + async with aiohttp.ClientSession() as session: + # 第二步：通过 TronGrid 构建未签名交易 + async with session.post( + f"{TRONGRID_API}/wallet/createtransaction", + json={ + "owner_address": from_address, + "to_address": to_address, + "amount": amount_sun, + }, + ) as resp: + unsigned_tx = await resp.json() + + if "txID" not in unsigned_tx: + raise ValueError(f"构建交易失败：{unsigned_tx}") + + print("未签名交易 txID:", unsigned_tx["txID"]) + + # 第三步：Agent-wallet 本地签名 + signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) + print("签名完成，signature:", signed_tx["signature"]) + + # 第四步：通过 TronGrid 广播 + async with session.post( + f"{TRONGRID_API}/wallet/broadcasttransaction", + json=signed_tx, + ) as resp: + broadcast_result = await resp.json() + + if broadcast_result.get("result"): + print("广播成功！txID:", signed_tx["txID"]) + else: + print("广播失败：", broadcast_result) + + return signed_tx["txID"] + +# 使用示例 +asyncio.run( + transfer_trx( + from_address="YOUR_TRON_ADDRESS", # 替换为你的钱包地址 + to_address="RECIPIENT_TRON_ADDRESS", # 替换为接收方地址 + amount_sun=1_000_000, # 1 TRX + ) +) +``` + + + + +:::caution 注意 +- 测试时请使用 Nile 测试网，可在 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取测试币 +- 主网操作请将 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet` +::: + +--- + +## EVM 转账（BSC / Ethereum） + +**适用场景**：AI 代理需要在 BSC、Ethereum 或其他 EVM 兼容链上发起原生代币转账，例如支付 Gas、向合约转账触发业务逻辑，或在任务执行后完成链上结算。 + +**流程说明**： + +EVM 交易需要调用方自行构造交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，不依赖中心化 API 生成。构建好未签名交易后，交给 Agent-wallet 在本地签名，返回一段十六进制编码的已签名交易数据，再通过 `sendRawTransaction` 广播到链上。 + +``` +RPC 查 nonce/gas（构建）→ Agent-wallet（签名）→ RPC sendRawTransaction（广播） +``` + +示例使用 BSC 测试网，但切换到 Ethereum、Polygon、Base 等链只需更改 `RPC_URL` 和 `CHAIN_ID` 两个参数，Agent-wallet 的调用代码完全不变。 + +### 安装依赖 + + + + +```bash +npm install @bankofai/agent-wallet ethers +``` + + + + +```bash +pip install web3 +``` + + + + +### 完整代码 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { ethers } from "ethers"; + +// BSC 测试网（Testnet） +const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; +const CHAIN_ID = 97; // BSC 测试网，主网为 56 + +async function transferBNB( + toAddress: string, + amountEther: string // 如 "0.001" +) { + // 第一步：初始化 Agent-wallet + const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); + const wallet = await provider.getActiveWallet(); + const fromAddress = await wallet.getAddress(); + + // 第二步：通过 RPC 查询 nonce 和 gas 信息 + const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); + const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); + const feeData = await rpcProvider.getFeeData(); + + // 第三步：构建未签名交易 + const unsignedTx = { + to: toAddress, + value: ethers.parseEther(amountEther), + gas: 21000n, + maxFeePerGas: feeData.maxFeePerGas!, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas!, + nonce, + chainId: CHAIN_ID, + type: 2, // EIP-1559 + }; + + console.log("构建交易完成，nonce:", nonce); + + // 第四步：Agent-wallet 本地签名 + const signedTxHex = await wallet.signTransaction(unsignedTx); + console.log("签名完成"); + + // 第五步：广播 + const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); + console.log("广播成功！txHash:", txResponse.hash); + + // 等待确认（可选） + const receipt = await txResponse.wait(); + console.log("交易已确认，区块号:", receipt?.blockNumber); + + return txResponse.hash; +} + +// 使用示例 +transferBNB( + "0xYOUR_RECIPIENT_ADDRESS", // 替换为接收方地址 + "0.001" // 发送 0.001 BNB +).catch(console.error); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider +from web3 import AsyncWeb3 + +# BSC 测试网（Testnet） +RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" +CHAIN_ID = 97 # BSC 测试网，主网为 56 + +async def transfer_bnb(to_address: str, amount_ether: str): + # 第一步：初始化 Agent-wallet + provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") + wallet = await provider.get_active_wallet() + from_address = await wallet.get_address() + + # 第二步：通过 RPC 查询 nonce 和 gas 信息 + w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) + nonce = await w3.eth.get_transaction_count(from_address, "latest") + fee_data = await w3.eth.fee_history(1, "latest", [50]) + base_fee = fee_data["baseFeePerGas"][-1] + priority_fee = await w3.eth.max_priority_fee + + # 第三步：构建未签名交易 + unsigned_tx = { + "to": to_address, + "value": w3.to_wei(amount_ether, "ether"), + "gas": 21000, + "maxFeePerGas": base_fee + priority_fee, + "maxPriorityFeePerGas": priority_fee, + "nonce": nonce, + "chainId": CHAIN_ID, + "type": 2, # EIP-1559 + } + + print("构建交易完成，nonce:", nonce) + + # 第四步：Agent-wallet 本地签名 + signed_tx_hex = await wallet.sign_transaction(unsigned_tx) + print("签名完成") + + # 第五步：广播 + tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) + print("广播成功！txHash:", tx_hash.hex()) + + # 等待确认（可选） + receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) + print("交易已确认，区块号:", receipt["blockNumber"]) + + return tx_hash.hex() + +# 使用示例 +asyncio.run( + transfer_bnb( + to_address="0xYOUR_RECIPIENT_ADDRESS", # 替换为接收方地址 + amount_ether="0.001", # 发送 0.001 BNB + ) +) +``` + + + + +:::caution 注意 +- 测试时请使用 BSC 测试网（chainId=97），可在 [BSC Faucet](https://testnet.binance.org/faucet-smart) 领取测试币 +- 主网操作请将 `RPC_URL` 改为主网 RPC，`CHAIN_ID` 改为 `56`，`network` 改为 `eip155:56` +::: + +--- + +## x402 PaymentPermit 签名 + +**适用场景**：AI 代理正在访问一个受 x402 协议保护的付费 API——比如获取实时数据、调用 AI 推理服务，或触发某个链上操作。服务端返回 HTTP 402 状态码，要求代理先完成链上支付授权，才能继续获取内容。 + +**流程说明**： + +x402 协议的支付不是直接发起转账，而是采用"先签名授权、后验证放行"的方式。代理需要对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，签名结果作为支付凭证随请求头一起发送给服务端。服务端验证签名合法后才返回内容，整个过程不需要代理等待链上确认，延迟极低。 + +``` +服务端返回 402 → 代理构建 PaymentPermit → Agent-wallet 签名 → 携带签名重发请求 → 服务端验证放行 +``` + +PaymentPermit 数据由 x402 SDK 根据服务端返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面展示的是底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +async function signPaymentPermit( + paymentPayload: { + x402Version: number; + scheme: string; + network: string; + payload: { + signature: string; + authorization: { + from: string; + to: string; + value: string; + validAfter: string; + validBefore: string; + nonce: string; + }; + }; + } +) { + // 初始化 Agent-wallet（EVM 钱包，网络与 x402 支付网络对应） + const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base 主网 + const wallet = await provider.getActiveWallet(); + + // 构建 EIP-712 typed data（与 x402 协议规范一致） + const typedData = { + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "version", type: "string" }, + { name: "chainId", type: "uint256" }, + { name: "verifyingContract", type: "address" }, + ], + TransferWithAuthorization: [ + { name: "from", type: "address" }, + { name: "to", type: "address" }, + { name: "value", type: "uint256" }, + { name: "validAfter", type: "uint256" }, + { name: "validBefore", type: "uint256" }, + { name: "nonce", type: "bytes32" }, + ], + }, + primaryType: "TransferWithAuthorization", + domain: { + name: "USD Coin", + version: "2", + chainId: 8453, + verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC + }, + message: paymentPayload.payload.authorization, + }; + + // Agent-wallet 本地签名 + const signature = await wallet.signTypedData(typedData); + console.log("PaymentPermit 签名:", signature); + + return signature; +} +``` + + + + +```python +from agent_wallet import resolve_wallet_provider + +async def sign_payment_permit(authorization: dict) -> str: + # 初始化 Agent-wallet（EVM 钱包，网络与 x402 支付网络对应） + provider = resolve_wallet_provider(network="eip155:8453") # Base 主网 + wallet = await provider.get_active_wallet() + + # 构建 EIP-712 typed data（与 x402 协议规范一致） + typed_data = { + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "version", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + {"name": "verifyingContract", "type": "address"}, + ], + "TransferWithAuthorization": [ + {"name": "from", "type": "address"}, + {"name": "to", "type": "address"}, + {"name": "value", "type": "uint256"}, + {"name": "validAfter", "type": "uint256"}, + {"name": "validBefore", "type": "uint256"}, + {"name": "nonce", "type": "bytes32"}, + ], + }, + "primaryType": "TransferWithAuthorization", + "domain": { + "name": "USD Coin", + "version": "2", + "chainId": 8453, + "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", # Base USDC + }, + "message": authorization, + } + + # Agent-wallet 本地签名 + signature = await wallet.sign_typed_data(typed_data) + print("PaymentPermit 签名:", signature) + + return signature +``` + + + + +:::tip +x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不需要手动编写上述代码。这里展示的是底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。 +::: + +--- + +## 下一步 + +- 回顾签名接口的完整参数说明 → [SDK 快速开始](./SDKQuickStart.md) +- 了解 x402 协议与 Agent-wallet 的配合方式 → [x402 简介](../../x402/index.md) +- 查看常见问题 → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md new file mode 100644 index 00000000..babdaf1d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -0,0 +1,123 @@ +# 简介 + +AI 代理正在越来越多地参与链上操作：支付 API 费用、签署授权、执行转账。但这件事有一个绕不开的问题——私钥。 + +把私钥硬编码在代码里不安全，托管给云端服务意味着失去控制权，每次操作都弹出人工确认又失去了"自主"的意义。 + +AI 代理需要一种方式：**让密钥安全地留在本地，让签名在本地完成，同时对外只暴露一个干净的接口**。 + +这就是 **Agent-wallet** 要解决的问题。 + +--- + +## Agent-wallet 是什么 + +**Agent-wallet** 是一个**仅用于签名的 SDK**，让 AI 代理（MCP 服务器、自主工作流等）能安全地管理和使用区块链密钥。 + +:::tip 它做两件事 + +- **密钥存储** — 用 Keystore V3 加密方式将私钥安全保存在本地 +- **本地签名** — 对消息、交易、EIP-712 结构化数据进行签名，全程无网络调用 + +::: + +:::caution 它不做的事 + +- 不连接 RPC，不查链上数据 +- 不构建交易（调用者负责构建） +- 不广播交易（调用者负责广播） +- 不自主发起转账或支付 + +::: + +这种职责分离让 Agent-wallet 保持轻量，且不依赖任何特定的 RPC 服务商。 + +--- + +## 为什么选择 Agent-wallet + +### 专为 AI 代理设计 + +传统钱包是给人用的——有界面、需要手动确认。Agent-wallet 的接口设计面向程序，通过环境变量配置，通过 SDK 调用，天然适合在 MCP Server 或自动化工作流中内嵌。 + +### 私钥永不离开本地 + +所有签名都在本地完成，没有任何网络请求。私钥不会被发送到任何服务器，不依赖任何云端 HSM 或托管服务，你对密钥有完全的控制权。 + +### 银行级密钥加密 + +私钥以 **Keystore V3** 格式加密存储，使用 scrypt（计算成本是普通 bcrypt 的数十倍）+ AES-128-CTR + keccak256 MAC 的组合。即使密钥文件被盗，没有主密码也无法解出私钥。主密码本身也从不以任何形式存储在磁盘上。 + +### 不绑定任何 RPC 服务商 + +因为 Agent-wallet 不做任何链上操作，你可以自由选择任意 RPC——TronGrid、自建节点——完全不影响签名逻辑。迁移或切换服务商时，签名代码不需要任何修改。 + +### 多链、双语言、一套接口 + +EVM 和 TRON 使用同一套 `BaseWallet` 接口，Python 和 TypeScript 两个实现行为完全一致、密钥文件格式互通。同一套密钥，换一门语言，签出来的结果完全相同。 + +--- + +## 两种使用方式 + +### CLI（命令行工具） + +适合需要管理密钥、手动测试签名的场景。 + +```bash +npm install -g @bankofai/agent-wallet +agent-wallet start # 初始化并创建默认钱包 +agent-wallet sign msg "Hello" # 签名消息 +``` + +→ 详见 [CLI 快速开始](./QuickStart.md) + +### SDK（编程接口） + +适合在代码中集成签名能力，比如在 MCP Server 内部使用。 + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + +提供 **Python** 和 **TypeScript** 两个版本，接口相同，输出完全兼容。 + +→ 详见 [SDK 快速开始](./SDKQuickStart.md) + +--- + +## 支持哪些链 + +| 链类型 | 网络标识符 | 支持的网络 | +| :--- | :--- | :--- | +| **EVM** | `eip155:*` | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链 | +| **TRON** | `tron:*` | TRON 主网、Nile 测试网、Shasta 测试网 | + +--- + +## 在 BANK OF AI 体系中的位置 + +Agent-wallet 是整个生态的签名层。其他组件（如 MCP Server、x402 SDK）在需要签名时，依赖 Agent-wallet 提供私钥操作： + +``` +AI 代理 + └── Skills / x402 SDK ← 决定"做什么" + └── MCP Server ← 构建交易，查询链上数据 + └── Agent-wallet ← 签名（仅此一件事） +``` + +Agent-wallet 本身不知道业务逻辑，只负责安全地持有密钥、按需签名。 + +--- + +## 从哪里开始 + +| 你的目标 | 从这里开始 | +| :--- | :--- | +| 初始化钱包、用命令行管理密钥和签名 | [CLI 快速开始](./QuickStart.md) | +| 在 Python 或 TypeScript 代码中集成签名能力 | [SDK 快速开始](./SDKQuickStart.md) | +| 查看常见问题 | [常见问题](./FAQ.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md new file mode 100644 index 00000000..e9b3bd0f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -0,0 +1,345 @@ +# CLI 快速开始 + +本指南帮你通过命令行完成 Agent-wallet 的安装、钱包初始化和签名操作。完成四个步骤后，你将拥有一个加密保存在本地的钱包，并能通过命令行对消息和交易进行签名。 + +页面后半段是完整的命令参考，日常使用时按需查阅即可。 + +如果你是开发者，想在 Python 或 TypeScript 代码中直接调用签名接口，参阅 [SDK 快速开始](./SDKQuickStart.md)。 + +--- + +## 第一步：安装 + +### 确认 Node.js 版本 + +需要 Node.js ≥ 18，先检查当前版本： + +```bash +node -v +``` + +如果输出 `v18.0.0` 或更高，可以直接跳到安装步骤。如果版本不足或提示命令不存在，按下方说明安装或升级。 + +:::tip 安装 / 升级 Node.js + +推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本，方便随时切换： + +```bash +# 安装 nvm（已安装可跳过） +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# 重新加载 shell 配置 +source ~/.bashrc # 或 source ~/.zshrc + +# 安装 Node.js 18 LTS +nvm install 18 + +# 切换到 Node.js 18 +nvm use 18 +``` + +也可以直接从 [nodejs.org](https://nodejs.org) 下载安装包，选择 **LTS** 版本即可。 + +::: + +### 安装 Agent-wallet CLI + +```bash +npm install -g @bankofai/agent-wallet +``` + +验证安装： + +```bash +agent-wallet --help +``` + +--- + +## 第二步：初始化钱包 + +`start` 命令一步完成初始化并创建默认钱包，有三种方式可选： + +### 方式 A：全自动（推荐新手） + +```bash +agent-wallet start +``` + +系统会自动生成强密码，同时创建一个 TRON 钱包和一个 EVM 钱包： + +``` +🔐 Wallet initialized! + +🪙 Wallets: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│ default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ +│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ + +⭐ Active wallet: default_tron + +🔑 Your master password: E&LCi*KL1Sp4mg4! + ⚠️ Save this password! You'll need it for signing and other operations. +``` + +:::caution 安全提示 +- **保管好主密码** — 主密码是解密所有私钥的唯一凭据，丢失后无法恢复。建议使用密码管理器保存。 +- **不要明文写在代码里** — 如果需要非交互式使用，通过环境变量 `AGENT_WALLET_PASSWORD` 传入，而不是硬编码在脚本中。 +- **不要提交 `.env` 文件** — 将 `.env` 加入 `.gitignore`，避免密码或私钥泄露到版本库。 +- **为代理使用专用钱包** — 不要把个人主钱包的私钥交给 AI 代理，而是创建独立钱包并只充入所需的小额资金。 +::: + + +### 方式 B：自定义密码 + +```bash +agent-wallet start -p Abc12345! +``` + +密码要求：至少 8 个字符，包含大写字母、小写字母、数字和特殊符号。 + +### 方式 C：导入已有私钥 + +如果你已有一个私钥希望直接导入： + +```bash +agent-wallet start -p Abc12345! -i tron +``` + +运行后会提示你粘贴私钥（输入内容不会显示在屏幕上）： + +``` +🔐 Wallet initialized! +✔ Paste private key (hex) + +🪙 Imported wallet: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│ default_tron │ tron_local │ TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ + +⭐ Active wallet: default_tron +``` + +`-i` 参数支持 `tron`、`evm`、`tron_local`、`evm_local`。 + + +--- + +## 第三步：查看钱包 + +列出所有钱包： + +```bash +agent-wallet list +``` + +``` +Wallets: +┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ +│ Wallet ID │ Type │ Address │ +├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ +│* default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ +│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ +``` + +`*` 标记当前活跃钱包，签名时默认使用活跃钱包。 + +--- + +## 第四步：签名 + +### 签名消息 + +```bash title="输入" +agent-wallet sign msg "Hello" +``` + +```text title="输出" +Master password: ******** +Signature: 4a9c8f...e71b +``` + +### 签名交易 + +交易内容以 JSON 字符串形式传入（你需要先通过 RPC 构建好未签名的交易）： + +```bash title="输入" +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' +``` + +```text title="输出" +Master password: ******** +Signed tx: +{ + "txID": "abc123...", + "signature": ["..."] +} +``` + +### 签名 EIP-712 结构化数据 + +```bash title="输入" +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' +``` + +```text title="输出" +Master password: ******** +Signature: 22008ffd...0e1c +``` + +--- + +## 命令参考 + +完成快速开始后，可以按需查阅以下内容。 + +### 跳过密码提示 + +每次签名都输入密码很麻烦。通过环境变量可以跳过交互式提示： + +```bash +export AGENT_WALLET_PASSWORD="Abc12345!" +``` + +设置后，所有签名命令不再提示输入密码，直接输出结果： + +```bash +agent-wallet sign msg "Hello" +agent-wallet sign tx '{"txID":"..."}' +``` + +也可以在单条命令中通过 `-p` 参数传入： + +```bash +agent-wallet sign msg "Hello" -p "Abc12345!" +``` + +### 管理多个钱包 + +#### 1. 添加新钱包 + +交互式提示中选择钱包类型（`tron_local` 或 `evm_local`）、生成或导入私钥： + +```bash title="输入" +agent-wallet add +``` + +```text title="输出" +Master password: ******** +Wallet name: my-bsc-wallet +> Wallet type: evm_local +> Private key: generate +Generated new private key. + Address: 0x8c714fe3... + Saved: id_my-bsc-wallet.json +Wallet 'my-bsc-wallet' added. +``` + +#### 2. 切换活跃钱包 + +```bash title="输入" +agent-wallet use my-bsc-wallet +``` + +```text title="输出" +Active wallet: my-bsc-wallet (evm_local) +``` + +#### 3. 指定钱包签名 + +签名时可以用 `-w` 显式指定钱包，不受活跃钱包影响： + +```bash +agent-wallet sign msg "Hello" -w my-bsc-wallet -p "Abc12345!" +``` + +#### 4. 查看钱包详情 + +```bash title="输入" +agent-wallet inspect my-bsc-wallet +``` + +```text title="输出" +Wallet my-bsc-wallet +Type evm_local +Address 0x8c714fe3... +Identity id_my-bsc-wallet.json ✓ +Credential — +``` + +#### 5. 删除钱包 + +```bash title="输入" +agent-wallet remove my-bsc-wallet +``` + +```text title="输出" +Remove wallet 'my-bsc-wallet'? (y/N): y + Deleted: id_my-bsc-wallet.json +Wallet 'my-bsc-wallet' removed. +``` + +### 其他操作 + +#### 1. 修改主密码 + +主密码是加密所有本地私钥的唯一凭据。Agent-wallet 不存储主密码本身，而是用它对每个私钥文件进行加密——修改主密码时，所有密钥文件会用新密码重新加密。 + +```bash title="输入" +agent-wallet change-password +``` + +```text title="输出" +Current password: ******** +New password: ******** +Confirm new password: ******** +Password changed. Re-encrypted 3 files. +``` + +会重新加密所有密钥文件。 + +#### 2. 重置所有数据 + +```bash title="输入" +agent-wallet reset +``` + +```text title="输出" +⚠️ This will delete ALL wallet data in: /home/you/.agent-wallet +Are you sure you want to reset? This cannot be undone. (y/N): y +Really delete everything? Last chance! (y/N): y +✅ Wallet data reset complete. +``` + +删除 `~/.agent-wallet/` 目录下的全部数据，操作不可逆，会要求二次确认。 + +#### 3. 自定义存储目录 + +所有命令都支持 `--dir` 参数指定自定义密钥目录（默认 `~/.agent-wallet`）： + +```bash +agent-wallet start --dir ./my-secrets +agent-wallet sign msg "Hello" --dir ./my-secrets +``` + +--- + +## 下一步 + +- 在代码中使用签名能力 → [SDK 快速开始](./SDKQuickStart.md) +- 了解整体设计 → [简介](./Intro.md) +- 查看常见问题 → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md new file mode 100644 index 00000000..ca8aad95 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md @@ -0,0 +1,472 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SDK 快速开始 + +这个页面面向开发者，介绍如何在 Python 或 TypeScript 代码中直接调用 Agent-wallet 的签名接口。 + +与 CLI 不同，SDK 的使用场景是将签名能力嵌入你自己的程序——比如在 MCP Server 里为 AI 代理提供签名支持，或在自动化脚本中对链上操作进行授权。你的代码负责构建交易和广播，Agent-wallet 负责在本地完成签名并返回结果。 + +完成本指南后，你将能够通过代码初始化钱包提供者、获取活跃钱包，并对消息、交易和 EIP-712 结构化数据进行签名。如果你还没有初始化过本地钱包，建议先完成 [CLI 快速开始](./QuickStart.md) 中的第一步到第三步。 + +安装和代码示例均提供 TypeScript 和 Python 两个版本，通过标签切换查看。 + +--- + +## 第一步：安装 + + + + +**确认 Node.js 版本** + +需要 Node.js ≥ 18，先检查当前版本： + +```bash +node -v +``` + +如果输出 `v18.0.0` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 + +:::tip 安装 / 升级 Node.js + +推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本： + +```bash +# 安装 nvm（已安装可跳过） +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash + +# 重新加载 shell 配置 +source ~/.bashrc # 或 source ~/.zshrc + +# 安装并切换到 Node.js 18 LTS +nvm install 18 +nvm use 18 +``` + +也可以直接从 [nodejs.org](https://nodejs.org) 下载 **LTS** 安装包。 + +::: + +**安装 SDK** + +```bash +npm install @bankofai/agent-wallet +``` + + + + +**确认 Python 版本** + +需要 Python ≥ 3.10，先检查当前版本： + +```bash +python3 --version +``` + +如果输出 `3.10.x` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 + +:::tip 安装 / 升级 Python + +推荐使用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本： + +```bash +# 安装 pyenv（已安装可跳过） +curl https://pyenv.run | bash + +# 重新加载 shell 配置 +source ~/.bashrc # 或 source ~/.zshrc + +# 安装 Python 3.10 +pyenv install 3.10 +pyenv global 3.10 +``` + +也可以直接从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.10 或更高版本**。 + +::: + +**安装 SDK** + +Python 包目前未发布到 PyPI，需从源码安装： + +```bash +git clone https://github.com/BofAI/agent-wallet.git +cd agent-wallet/packages/python +pip install -e ".[all]" +``` + +验证安装： + +```bash +python -c "import agent_wallet; print('安装成功')" +``` + + + + +--- + +## 第二步：配置模式 + +在调用 SDK 之前，需要先通过环境变量告诉 Agent-wallet 如何找到你的密钥。SDK 提供两种模式——本地模式适合长期管理多个钱包，静态模式适合直接注入私钥。`resolveWalletProvider()` 会自动识别当前设置的环境变量，选择对应的模式，无需在代码里做任何额外判断。 + +### 本地模式 + +私钥加密存储在本地，适合需要管理多个钱包或长期持久化密钥的场景。使用前需要先通过 CLI 完成初始化（`agent-wallet start`），然后设置主密码： + +```bash +export AGENT_WALLET_PASSWORD="Abc12345!" +# 可选：自定义目录，默认 ~/.agent-wallet +export AGENT_WALLET_DIR="$HOME/.agent-wallet" +``` + +### 静态模式 + +直接通过环境变量提供私钥或助记词，无需本地密钥文件，适合 CI/CD 或一次性脚本场景。静态模式下必须同时指定 `network` 参数： + +```bash +export AGENT_WALLET_PRIVATE_KEY="你的私钥（十六进制）" +# 或 +export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." +``` + +:::caution 注意事项 +- `AGENT_WALLET_PASSWORD` 优先级高于 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`，两者同时设置时走本地模式 +- `AGENT_WALLET_PRIVATE_KEY` 和 `AGENT_WALLET_MNEMONIC` 不能同时设置 +- 不要将私钥或密码硬编码在代码里，始终通过环境变量或 `.env` 文件传入，并将 `.env` 加入 `.gitignore` +::: + +### 环境变量速查 + +| 变量名 | 用途 | 模式 | 是否必选 | +| :--- | :--- | :--- | :--- | +| `AGENT_WALLET_PASSWORD` | 主密码，启用本地模式 | 本地模式 | 必选 | +| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 本地模式 | 可选 | +| `AGENT_WALLET_PRIVATE_KEY` | 私钥（十六进制） | 静态模式 | 必选（与助记词二选一） | +| `AGENT_WALLET_MNEMONIC` | 助记词 | 静态模式 | 必选（与私钥二选一） | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 助记词派生地址索引（默认 `0`） | 静态模式 | 可选 | + +--- + +## 用法示例 + +### 初始化钱包提供者 + +所有操作的起点是 `resolveWalletProvider()`，它根据环境变量自动选择工作模式并返回一个钱包提供者，再通过 `getActiveWallet()` 拿到活跃钱包。 + + + + +```typescript +import { resolveWalletProvider } from "@bankofai/agent-wallet"; + +const provider = resolveWalletProvider({ network: "tron:nile" }); +const wallet = await provider.getActiveWallet(); + +// 查看当前钱包地址 +const address = await wallet.getAddress(); +console.log("地址:", address); +``` + + + + +```python +import asyncio +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider(network="tron:nile") + +async def main(): + wallet = await provider.get_active_wallet() + + # 查看当前钱包地址 + address = await wallet.get_address() + print("地址:", address) + +asyncio.run(main()) +``` + + + + +拿到 `wallet` 后，可以调用以下三种签名方法。所有签名方法均返回十六进制编码的签名字符串（无 `0x` 前缀）。 + +### 签名消息 + + + + +```typescript +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +console.log("签名:", sig); +``` + + + + +```python +sig = await wallet.sign_message(b"Hello") +print("签名:", sig) +``` + + + + +### 签名交易 + +Agent-wallet 只负责签名，不负责构建或广播交易。你需要先通过 RPC（如 TronGrid、Infura）构建未签名的交易，再传给 SDK 签名。 + +#### TRON 交易 + + + + +```typescript +// 1. 调用者通过 TronGrid 构建未签名交易 +const unsignedTx = { + txID: "abc123...", + raw_data_hex: "0a02...", + raw_data: { /* TronGrid 返回的原始数据 */ }, +}; + +// 2. SDK 本地签名（无网络调用） +const signedTxJson = await wallet.signTransaction(unsignedTx); +console.log("已签名交易:", signedTxJson); + +// 3. 调用者负责广播 +``` + + + + +```python +# 1. 调用者通过 TronGrid 构建未签名交易 +unsigned_tx = { + "txID": "abc123...", + "raw_data_hex": "0a02...", + "raw_data": {}, # TronGrid 返回的原始数据 +} + +# 2. SDK 本地签名（无网络调用） +signed_tx_json = await wallet.sign_transaction(unsigned_tx) +print("已签名交易:", signed_tx_json) + +# 3. 调用者负责广播 +``` + + + + +#### EVM 交易（BSC、Ethereum 等） + + + + +```typescript +const sig = await wallet.signTransaction({ + to: "0xRecipient...", + value: 0n, + gas: 21000n, + maxFeePerGas: 20000000000n, + nonce: 0, + chainId: 56, +}); +console.log("签名:", sig); +``` + + + + +```python +sig = await wallet.sign_transaction({ + "to": "0xRecipient...", + "value": 0, + "gas": 21000, + "maxFeePerGas": 20000000000, + "nonce": 0, + "chainId": 56, +}) +print("签名:", sig) +``` + + + + +### 签名 EIP-712 结构化数据 + +用于 x402 协议的 PaymentPermit 签名、Permit2 等场景： + + + + +```typescript +const sig = await wallet.signTypedData({ + types: { + EIP712Domain: [ + { name: "name", type: "string" }, + { name: "chainId", type: "uint256" }, + ], + Transfer: [ + { name: "to", type: "address" }, + { name: "amount", type: "uint256" }, + ], + }, + primaryType: "Transfer", + domain: { name: "MyDApp", chainId: 1 }, + message: { to: "0x...", amount: 1000000 }, +}); +console.log("签名:", sig); +``` + + + + +```python +sig = await wallet.sign_typed_data({ + "types": { + "EIP712Domain": [ + {"name": "name", "type": "string"}, + {"name": "chainId", "type": "uint256"}, + ], + "Transfer": [ + {"name": "to", "type": "address"}, + {"name": "amount", "type": "uint256"}, + ], + }, + "primaryType": "Transfer", + "domain": {"name": "MyDApp", "chainId": 1}, + "message": {"to": "0x...", "amount": 1000000}, +}) +print("签名:", sig) +``` + + + + +--- + +### 管理多个钱包 + +如果你需要在代码中管理多个钱包，可以直接使用 `LocalWalletProvider`： + + + + +```typescript +import { LocalWalletProvider } from "@bankofai/agent-wallet"; + +const provider = new LocalWalletProvider("~/.agent-wallet", "Abc12345!"); + +// 列出所有钱包 +const wallets = await provider.listWallets(); +for (const w of wallets) { + console.log(`${w.id} (${w.type}): ${w.address}`); +} + +// 切换活跃钱包 +provider.setActive("my-evm-wallet"); + +// 获取并使用 +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +``` + + + + +```python +# 设置环境变量后，resolve_wallet_provider 自动进入本地模式 +import os +os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" + +from agent_wallet import resolve_wallet_provider + +provider = resolve_wallet_provider() + +async def main(): + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("签名:", sig) + +asyncio.run(main()) +``` + + + + +--- + +### 错误处理 + +签名操作失败时，SDK 会抛出具体的错误类型，建议在代码中显式捕获并处理，避免运行时崩溃。 + + + + +```typescript +import { + WalletNotFoundError, + SigningError, + DecryptionError, +} from "@bankofai/agent-wallet"; + +try { + const wallet = await provider.getActiveWallet(); + const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); + console.log("签名:", sig); +} catch (e) { + if (e instanceof WalletNotFoundError) { + console.error("找不到钱包，检查活跃钱包是否已设置"); + } else if (e instanceof DecryptionError) { + console.error("解密失败，检查主密码是否正确"); + } else if (e instanceof SigningError) { + console.error("签名失败:", e.message); + } else { + throw e; + } +} +``` + + + + +```python +from agent_wallet import WalletNotFoundError, SigningError, DecryptionError + +try: + wallet = await provider.get_active_wallet() + sig = await wallet.sign_message(b"Hello") + print("签名:", sig) +except WalletNotFoundError: + print("找不到钱包，检查活跃钱包是否已设置") +except DecryptionError: + print("解密失败，检查主密码是否正确") +except SigningError as e: + print(f"签名失败: {e}") +``` + + + + +错误类型层级： + +``` +WalletError +├── WalletNotFoundError # 找不到指定钱包 +├── DecryptionError # 密码错误或密钥文件损坏 +├── SigningError # 签名操作失败 +├── NetworkError # 网络标识符不匹配 +├── InsufficientBalanceError # 余额不足（由调用方抛出） +└── UnsupportedOperationError # 当前钱包类型不支持该操作 +``` + +--- + +## 下一步 + +- 用命令行管理钱包 → [CLI 快速开始](./QuickStart.md) +- 了解 agent-wallet 的设计 → [简介](./Intro.md) +- 查看常见问题 → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js index 4df37998..ffbf739e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -148,6 +148,12 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Agent Wallet', + collapsed: false, + items: ['Agent-Wallet/Intro', 'Agent-Wallet/QuickStart', 'Agent-Wallet/FAQ'], + }, { type: 'category', label: 'Openclaw 扩展插件', diff --git a/sidebars.js b/sidebars.js index 79785b69..3843ccac 100644 --- a/sidebars.js +++ b/sidebars.js @@ -145,6 +145,12 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Agent Wallet', + collapsed: false, + items: ['Agent-Wallet/Intro', 'Agent-Wallet/QuickStart', 'Agent-Wallet/SDKQuickStart', 'Agent-Wallet/FullExample', 'Agent-Wallet/FAQ'], + }, { type: 'category', label: 'Openclaw Extension', From e5f417ef60afbea405d8e5828b5a80c109f992bf Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 20:31:38 +0800 Subject: [PATCH 02/44] fix --- .github/workflows/docker.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 0882e992..ce4caf7d 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -5,14 +5,12 @@ on: branches: - main - master - - ai-bankofai-patch-1 tags: - 'test' pull_request: branches: - main - master - - ai-bankofai-patch-1 workflow_dispatch: env: From 956060e58cfdef221392ed72c763dab7811755f6 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 20:48:17 +0800 Subject: [PATCH 03/44] fix --- .github/workflows/docker.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index ce4caf7d..d8c714f5 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -5,12 +5,14 @@ on: branches: - main - master + - update-mcp-server tags: - 'test' pull_request: branches: - main - master + - update-mcp-server workflow_dispatch: env: From a541e971551b788bd93c8a09f7240171e5741d36 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 21:07:50 +0800 Subject: [PATCH 04/44] fix --- docs/Agent-Wallet/Intro.md | 15 --------------- docs/Agent-Wallet/QuickStart.md | 10 +++++----- .../current/Agent-Wallet/Intro.md | 15 --------------- .../current/Agent-Wallet/QuickStart.md | 12 ++++++------ 4 files changed, 11 insertions(+), 41 deletions(-) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 7fa9e4df..ea270143 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -99,21 +99,6 @@ Available in both **Python** and **TypeScript**, with identical interfaces and f --- -## Where Agent-wallet Fits in the BANK OF AI Ecosystem - -Agent-wallet is the signing layer of the entire ecosystem. Other components (such as MCP Server and x402 SDK) rely on Agent-wallet for private key operations when signing is required: - -``` -AI Agent - └── Skills / x402 SDK ← Decides "what to do" - └── MCP Server ← Builds transactions, queries on-chain data - └── Agent-wallet ← Signs (and only that) -``` - -Agent-wallet has no knowledge of business logic. Its only job is to securely hold keys and sign on demand. - ---- - ## Where to Start | Your Goal | Start Here | diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 5131b7d2..866d4f64 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -75,8 +75,8 @@ The system auto-generates a strong password and creates one TRON wallet and one ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ -│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +│ default_tron │ tron_local │ TB37... │ +│ default_evm │ evm_local │ 0xd679B... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ⭐ Active wallet: default_tron @@ -118,7 +118,7 @@ You'll be prompted to paste the private key (input is hidden): ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB │ +│ default_tron │ tron_local │ TNmo... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ⭐ Active wallet: default_tron @@ -141,8 +141,8 @@ Wallets: ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│* default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ -│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +│* default_tron │ tron_local │ TB37... │ +│ default_evm │ evm_local │ 0xd679B... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index babdaf1d..516211f5 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -99,21 +99,6 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); --- -## 在 BANK OF AI 体系中的位置 - -Agent-wallet 是整个生态的签名层。其他组件（如 MCP Server、x402 SDK）在需要签名时，依赖 Agent-wallet 提供私钥操作： - -``` -AI 代理 - └── Skills / x402 SDK ← 决定"做什么" - └── MCP Server ← 构建交易，查询链上数据 - └── Agent-wallet ← 签名（仅此一件事） -``` - -Agent-wallet 本身不知道业务逻辑，只负责安全地持有密钥、按需签名。 - ---- - ## 从哪里开始 | 你的目标 | 从这里开始 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index e9b3bd0f..e49468ee 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -18,7 +18,7 @@ node -v ``` -如果输出 `v18.0.0` 或更高，可以直接跳到安装步骤。如果版本不足或提示命令不存在，按下方说明安装或升级。 +如果输出 `v18.0.0` 或更高，可以直接跳到安装步骤。如果版本较低或提示命令不存在，按下方说明安装或升级。 :::tip 安装 / 升级 Node.js @@ -75,8 +75,8 @@ agent-wallet start ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ -│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +│ default_tron │ tron_local │ TB37... │ +│ default_evm │ evm_local │ 0xd679B... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ⭐ Active wallet: default_tron @@ -119,7 +119,7 @@ agent-wallet start -p Abc12345! -i tron ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TNmoJ3Be59WFEq5dsW6eCkZjveiL3G8HVB │ +│ default_tron │ tron_local │ TNmo... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ⭐ Active wallet: default_tron @@ -143,8 +143,8 @@ Wallets: ┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ │ Wallet ID │ Type │ Address │ ├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│* default_tron │ tron_local │ TB37CfKbRacD6TUBNPK7GirUheUJwbAGH5 │ -│ default_evm │ evm_local │ 0xd679B660f6b331e1fdA877cee0aAd361A7f3b628 │ +│* default_tron │ tron_local │ TB37... │ +│ default_evm │ evm_local │ 0xd679B... │ └──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ ``` From 5dfcb8a529c9d690723b9e219608cb372e563d28 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 21:43:31 +0800 Subject: [PATCH 05/44] fix --- docs/Openclaw-extension/Intro.md | 2 +- .../current/Openclaw-extension/Intro.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index d4814867..d3bb9c5f 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -31,7 +31,7 @@ MCP Servers are bridges between your AI assistant and the blockchain, providing | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | -| **bankofai-recharge** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | +| **[bankofai-recharge](https://recharge.bankofai.io/mcp)** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | ### Skills — Pre-built Workflows diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index cec7b4e9..5cdf597d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -31,7 +31,7 @@ MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Prot | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | -| **bankofai-recharge** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | +| **[bankofai-recharge](https://recharge.bankofai.io/mcp)** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | ### Skills — 预构建工作流 From 2e02caba832425a2a5931a82883cad056443e099 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 21:50:11 +0800 Subject: [PATCH 06/44] fix --- docs/Agent-Wallet/SDKQuickStart.md | 20 +++++++++++++++---- .../current/Agent-Wallet/SDKQuickStart.md | 20 +++++++++++++++---- 2 files changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/SDKQuickStart.md index 4c99ef9d..6ebe07f4 100644 --- a/docs/Agent-Wallet/SDKQuickStart.md +++ b/docs/Agent-Wallet/SDKQuickStart.md @@ -72,13 +72,25 @@ If the output is `3.10.x` or higher, you can proceed directly to installation. O We recommend using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions: ```bash -# Install pyenv (skip if already installed) +# Step 1: Install pyenv curl https://pyenv.run | bash +``` -# Reload shell config -source ~/.bashrc # or source ~/.zshrc +After installation, you need to add pyenv to your shell config manually — otherwise the terminal won't find the `pyenv` command: + +```bash +# Append these three lines to ~/.bashrc (or ~/.zshrc for zsh users) +echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc +echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(pyenv init -)"' >> ~/.bashrc -# Install Python 3.10 +# Reload config to apply changes in the current terminal +source ~/.bashrc +``` + +Once pyenv is available, install Python: + +```bash pyenv install 3.10 pyenv global 3.10 ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md index ca8aad95..f7e4a341 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md @@ -72,13 +72,25 @@ python3 --version 推荐使用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本： ```bash -# 安装 pyenv（已安装可跳过） +# 第一步：安装 pyenv curl https://pyenv.run | bash +``` -# 重新加载 shell 配置 -source ~/.bashrc # 或 source ~/.zshrc +安装完成后，需要手动将 pyenv 加入 shell 配置，否则终端找不到 `pyenv` 命令： + +```bash +# 将以下三行追加到 ~/.bashrc（zsh 用户改为 ~/.zshrc） +echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc +echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc +echo 'eval "$(pyenv init -)"' >> ~/.bashrc -# 安装 Python 3.10 +# 重新加载配置，使当前终端立即生效 +source ~/.bashrc +``` + +确认 pyenv 可用后，安装 Python： + +```bash pyenv install 3.10 pyenv global 3.10 ``` From 47b8030d4bdde700789ac925a4d178c8cd0b4f5c Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Thu, 19 Mar 2026 14:57:35 +0800 Subject: [PATCH 07/44] fxi --- docs/Agent-Wallet/FullExample.md | 32 ++++- docs/Agent-Wallet/QuickStart.md | 15 ++- docs/Agent-Wallet/SDKQuickStart.md | 47 +++++-- .../current/Agent-Wallet/FullExample.md | 122 +++++++++++------- .../current/Agent-Wallet/QuickStart.md | 15 ++- .../current/Agent-Wallet/SDKQuickStart.md | 47 +++++-- 6 files changed, 206 insertions(+), 72 deletions(-) diff --git a/docs/Agent-Wallet/FullExample.md b/docs/Agent-Wallet/FullExample.md index 0aa855a8..aaa2f178 100644 --- a/docs/Agent-Wallet/FullExample.md +++ b/docs/Agent-Wallet/FullExample.md @@ -13,9 +13,10 @@ All examples are available in both TypeScript and Python — use the tabs to swi Before running any example below, make sure you have: -1. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) -2. Initialized a local wallet via the CLI, or configured static mode environment variables -3. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) +1. Python ≥ 3.11 (the SDK uses `StrEnum` and other 3.11+ features); no version constraint for TypeScript +2. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) +3. Initialized a local wallet via the CLI, or configured static mode environment variables +4. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) --- @@ -45,15 +46,36 @@ npm install @bankofai/agent-wallet axios +This example uses `aiohttp` (a third-party HTTP library) and `asyncio` (Python standard library — no install needed): + ```bash pip install aiohttp ``` -(The Agent-wallet Python SDK is already included — no separate install needed.) +:::caution If you see missing standard library module errors +If importing `asyncio` or other standard library modules fails, it's usually because system dependencies were missing when pyenv built Python from source. Install the following packages and then re-run `pyenv install 3.11`: + +```bash +# CentOS / RHEL / Amazon Linux +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` +::: +:::tip `visible: true` and address format +The code passes `visible: true` to TronGrid. This parameter affects the address format the API expects: + +- **`visible: true`**: the API expects addresses in **Base58 format** (the standard human-readable TRON address, e.g. `TNmo...`) +- **`visible: false` (or omitted)**: the API expects addresses in **hex format** (e.g. `41b9f...`) + +The example uses Base58 addresses, consistent with `visible: true`. +::: + ### Full Code @@ -81,6 +103,7 @@ async function transferTRX( owner_address: fromAddress, to_address: toAddress, amount: amountSun, + visible: true, } ); @@ -145,6 +168,7 @@ async def transfer_trx( "owner_address": from_address, "to_address": to_address, "amount": amount_sun, + "visible": True, }, ) as resp: unsigned_tx = await resp.json() diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 866d4f64..21f259dc 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -210,9 +210,22 @@ Once you've completed the quick start, refer to this section as needed. Typing the password on every signing command gets tedious. Set an environment variable to skip the interactive prompt: ```bash -export AGENT_WALLET_PASSWORD="Abc12345!" +export AGENT_WALLET_PASSWORD='Abc12345!' ``` +:::caution Always use single quotes when the password contains special characters +Master passwords — especially auto-generated ones — may contain `$`, `!`, or other shell-special characters. **Always use single quotes** to prevent the shell from expanding them: + +```bash +# ✅ Correct +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong: $ gets expanded by the shell +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + + After this, all signing commands run without prompting: ```bash diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/SDKQuickStart.md index 6ebe07f4..a0bfadb4 100644 --- a/docs/Agent-Wallet/SDKQuickStart.md +++ b/docs/Agent-Wallet/SDKQuickStart.md @@ -59,13 +59,13 @@ npm install @bankofai/agent-wallet **Check Your Python Version** -Requires Python ≥ 3.10. Check your current version: +Requires Python ≥ 3.11 (the SDK uses `StrEnum` and other 3.11+ features). Check your current version: ```bash python3 --version ``` -If the output is `3.10.x` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. +If the output is `3.11.x` or higher, you can proceed directly to installation. Otherwise, follow the instructions below. :::tip Install / Upgrade Python @@ -88,14 +88,24 @@ echo 'eval "$(pyenv init -)"' >> ~/.bashrc source ~/.bashrc ``` -Once pyenv is available, install Python: +Once pyenv is available, install the required system dependencies first. **Skipping this step will cause modules like `_ctypes` and `ssl` to be missing, which can break standard library imports including `asyncio`.** ```bash -pyenv install 3.10 -pyenv global 3.10 +# CentOS / RHEL / Amazon Linux / Fedora +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` + +Then build Python: + +```bash +pyenv install 3.11 +pyenv global 3.11 ``` -You can also download an installer from [python.org](https://www.python.org/downloads/), selecting **3.10 or higher**. +You can also download an installer from [python.org](https://www.python.org/downloads/), selecting **3.11 or higher**. ::: @@ -106,13 +116,19 @@ The Python package is not yet published to PyPI and must be installed from sourc ```bash git clone https://github.com/BofAI/agent-wallet.git cd agent-wallet/packages/python -pip install -e ".[all]" +pip3.11 install -e ".[all]" +``` + +The SDK depends on `tronpy` and `eth_account` for TRON and EVM signing. If you encounter import errors for either package after installation, install them manually: + +```bash +pip3.11 install tronpy eth_account ``` Verify the installation: ```bash -python -c "import agent_wallet; print('Installation successful')" +python3.11 -c "import agent_wallet; print('Installation successful')" ``` @@ -129,11 +145,24 @@ Before calling the SDK, you need to tell Agent-wallet where to find your keys vi Private keys are stored encrypted on disk. Best for managing multiple wallets or persisting keys long-term. You must initialize first via the CLI (`agent-wallet start`), then set the master password: ```bash -export AGENT_WALLET_PASSWORD="Abc12345!" +export AGENT_WALLET_PASSWORD='Abc12345!' # Optional: custom directory, defaults to ~/.agent-wallet export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` +:::caution Always use single quotes when the password contains special characters +Master passwords — especially auto-generated strong ones — may contain `$`, `!`, or other shell-special characters. **Always use single quotes** to prevent the shell from expanding them, which would silently corrupt the password: + +```bash +# ✅ Correct: single quotes, password passed as-is +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong: double quotes, $ gets expanded by the shell +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + + ### Static Mode Provide a private key or mnemonic directly via environment variable — no local key file required. Best for CI/CD or one-off scripts. The `network` parameter must be specified when using static mode: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md index 614d848a..6d7a06ef 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md @@ -13,9 +13,10 @@ Agent-wallet 只负责签名，构建交易和广播由调用者完成。本页 在运行以下示例前，请确保： -1. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） -2. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 -3. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） +1. Python >= 3.11（SDK 使用了 `StrEnum` 等 3.11+ 特性）；TypeScript 无版本限制 +2. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） +3. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 +4. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） --- @@ -45,15 +46,36 @@ npm install @bankofai/agent-wallet axios +本示例用到了 `aiohttp`（第三方 HTTP 库）和 `asyncio`（Python 标准库，无需安装）： + ```bash pip install aiohttp ``` -（Agent-wallet Python SDK 已包含，无需单独安装。） +:::caution 如果运行时提示标准库模块缺失 +如果导入 `asyncio` 等标准库时报错，通常是用 pyenv 构建 Python 时缺少系统依赖所致。请先安装以下包，再重新执行 `pyenv install 3.11`： + +```bash +# CentOS / RHEL / Amazon Linux +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` +::: +:::tip `visible: true` 与地址格式 +代码中向 TronGrid 传入了 `visible: true` 参数。该参数会影响 API 对地址格式的要求： + +- **`visible: true`**：API 期望地址为 **Base58 格式**（即普通 TRON 地址，如 `TNmo...`） +- **`visible: false`（或不传）**：API 期望地址为 **十六进制格式**（如 `41b9f...`） + +示例代码使用的是 Base58 格式地址，保持与 `visible: true` 一致即可。 +::: + ### 完整代码 @@ -63,47 +85,48 @@ pip install aiohttp import { resolveWalletProvider } from "@bankofai/agent-wallet"; import axios from "axios"; -const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网，主网改为 https://api.trongrid.io +const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网, 主网改为 https://api.trongrid.io async function transferTRX( fromAddress: string, toAddress: string, amountSun: number // 1 TRX = 1_000_000 SUN ) { - // 第一步：初始化 Agent-wallet + // 第一步: 初始化 Agent-wallet const provider = resolveWalletProvider({ network: "tron:nile" }); const wallet = await provider.getActiveWallet(); - // 第二步：通过 TronGrid 构建未签名交易 + // 第二步: 通过 TronGrid 构建未签名交易 const { data: unsignedTx } = await axios.post( `${TRONGRID_API}/wallet/createtransaction`, { owner_address: fromAddress, to_address: toAddress, amount: amountSun, + visible: true, } ); if (!unsignedTx.txID) { - throw new Error("构建交易失败：" + JSON.stringify(unsignedTx)); + throw new Error("构建交易失败: " + JSON.stringify(unsignedTx)); } console.log("未签名交易 txID:", unsignedTx.txID); - // 第三步：Agent-wallet 本地签名 + // 第三步: Agent-wallet 本地签名 const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); - console.log("签名完成，signature:", signedTx.signature); + console.log("签名完成, signature:", signedTx.signature); - // 第四步：通过 TronGrid 广播 + // 第四步: 通过 TronGrid 广播 const { data: broadcastResult } = await axios.post( `${TRONGRID_API}/wallet/broadcasttransaction`, signedTx ); if (broadcastResult.result) { - console.log("广播成功！txID:", signedTx.txID); + console.log("广播成功! txID:", signedTx.txID); } else { - console.error("广播失败：", broadcastResult); + console.error("广播失败: ", broadcastResult); } return signedTx.txID; @@ -126,39 +149,42 @@ import json import aiohttp from agent_wallet import resolve_wallet_provider -TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网，主网改为 https://api.trongrid.io +TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网, 主网改为 https://api.trongrid.io async def transfer_trx( from_address: str, to_address: str, amount_sun: int, # 1 TRX = 1_000_000 SUN ): - # 第一步：初始化 Agent-wallet + # 第一步: 初始化 Agent-wallet provider = resolve_wallet_provider(network="tron:nile") wallet = await provider.get_active_wallet() async with aiohttp.ClientSession() as session: - # 第二步：通过 TronGrid 构建未签名交易 + # 第二步: 通过 TronGrid 构建未签名交易 async with session.post( f"{TRONGRID_API}/wallet/createtransaction", json={ "owner_address": from_address, "to_address": to_address, "amount": amount_sun, + "visible": True, }, ) as resp: unsigned_tx = await resp.json() + print("TronGrid 返回原始响应:", json.dumps(unsigned_tx, indent=2, ensure_ascii=False)) + if "txID" not in unsigned_tx: - raise ValueError(f"构建交易失败：{unsigned_tx}") + raise ValueError(f"构建交易失败: {unsigned_tx}") print("未签名交易 txID:", unsigned_tx["txID"]) - # 第三步：Agent-wallet 本地签名 + # 第三步: Agent-wallet 本地签名 signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) - print("签名完成，signature:", signed_tx["signature"]) + print("签名完成, signature:", signed_tx["signature"]) - # 第四步：通过 TronGrid 广播 + # 第四步: 通过 TronGrid 广播 async with session.post( f"{TRONGRID_API}/wallet/broadcasttransaction", json=signed_tx, @@ -166,9 +192,9 @@ async def transfer_trx( broadcast_result = await resp.json() if broadcast_result.get("result"): - print("广播成功！txID:", signed_tx["txID"]) + print("广播成功! txID:", signed_tx["txID"]) else: - print("广播失败：", broadcast_result) + print("广播失败: ", broadcast_result) return signed_tx["txID"] @@ -234,25 +260,25 @@ pip install web3 import { resolveWalletProvider } from "@bankofai/agent-wallet"; import { ethers } from "ethers"; -// BSC 测试网（Testnet） +// BSC 测试网 (Testnet) const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; -const CHAIN_ID = 97; // BSC 测试网，主网为 56 +const CHAIN_ID = 97; // BSC 测试网, 主网为 56 async function transferBNB( toAddress: string, amountEther: string // 如 "0.001" ) { - // 第一步：初始化 Agent-wallet + // 第一步: 初始化 Agent-wallet const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); const wallet = await provider.getActiveWallet(); const fromAddress = await wallet.getAddress(); - // 第二步：通过 RPC 查询 nonce 和 gas 信息 + // 第二步: 通过 RPC 查询 nonce 和 gas 信息 const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); const feeData = await rpcProvider.getFeeData(); - // 第三步：构建未签名交易 + // 第三步: 构建未签名交易 const unsignedTx = { to: toAddress, value: ethers.parseEther(amountEther), @@ -264,19 +290,19 @@ async function transferBNB( type: 2, // EIP-1559 }; - console.log("构建交易完成，nonce:", nonce); + console.log("构建交易完成, nonce:", nonce); - // 第四步：Agent-wallet 本地签名 + // 第四步: Agent-wallet 本地签名 const signedTxHex = await wallet.signTransaction(unsignedTx); console.log("签名完成"); - // 第五步：广播 + // 第五步: 广播 const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); - console.log("广播成功！txHash:", txResponse.hash); + console.log("广播成功! txHash:", txResponse.hash); - // 等待确认（可选） + // 等待确认 (可选) const receipt = await txResponse.wait(); - console.log("交易已确认，区块号:", receipt?.blockNumber); + console.log("交易已确认, 区块号:", receipt?.blockNumber); return txResponse.hash; } @@ -296,24 +322,24 @@ import asyncio from agent_wallet import resolve_wallet_provider from web3 import AsyncWeb3 -# BSC 测试网（Testnet） +# BSC 测试网 (Testnet) RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" -CHAIN_ID = 97 # BSC 测试网，主网为 56 +CHAIN_ID = 97 # BSC 测试网, 主网为 56 async def transfer_bnb(to_address: str, amount_ether: str): - # 第一步：初始化 Agent-wallet + # 第一步: 初始化 Agent-wallet provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") wallet = await provider.get_active_wallet() from_address = await wallet.get_address() - # 第二步：通过 RPC 查询 nonce 和 gas 信息 + # 第二步: 通过 RPC 查询 nonce 和 gas 信息 w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) nonce = await w3.eth.get_transaction_count(from_address, "latest") fee_data = await w3.eth.fee_history(1, "latest", [50]) base_fee = fee_data["baseFeePerGas"][-1] priority_fee = await w3.eth.max_priority_fee - # 第三步：构建未签名交易 + # 第三步: 构建未签名交易 unsigned_tx = { "to": to_address, "value": w3.to_wei(amount_ether, "ether"), @@ -325,19 +351,19 @@ async def transfer_bnb(to_address: str, amount_ether: str): "type": 2, # EIP-1559 } - print("构建交易完成，nonce:", nonce) + print("构建交易完成, nonce:", nonce) - # 第四步：Agent-wallet 本地签名 + # 第四步: Agent-wallet 本地签名 signed_tx_hex = await wallet.sign_transaction(unsigned_tx) print("签名完成") - # 第五步：广播 + # 第五步: 广播 tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) - print("广播成功！txHash:", tx_hash.hex()) + print("广播成功! txHash:", tx_hash.hex()) - # 等待确认（可选） + # 等待确认 (可选) receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) - print("交易已确认，区块号:", receipt["blockNumber"]) + print("交易已确认, 区块号:", receipt["blockNumber"]) return tx_hash.hex() @@ -398,11 +424,11 @@ async function signPaymentPermit( }; } ) { - // 初始化 Agent-wallet（EVM 钱包，网络与 x402 支付网络对应） + // 初始化 Agent-wallet (EVM 钱包, 网络与 x402 支付网络对应) const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base 主网 const wallet = await provider.getActiveWallet(); - // 构建 EIP-712 typed data（与 x402 协议规范一致） + // 构建 EIP-712 typed data (与 x402 协议规范一致) const typedData = { types: { EIP712Domain: [ @@ -445,11 +471,11 @@ async function signPaymentPermit( from agent_wallet import resolve_wallet_provider async def sign_payment_permit(authorization: dict) -> str: - # 初始化 Agent-wallet（EVM 钱包，网络与 x402 支付网络对应） + # 初始化 Agent-wallet (EVM 钱包, 网络与 x402 支付网络对应) provider = resolve_wallet_provider(network="eip155:8453") # Base 主网 wallet = await provider.get_active_wallet() - # 构建 EIP-712 typed data（与 x402 协议规范一致） + # 构建 EIP-712 typed data (与 x402 协议规范一致) typed_data = { "types": { "EIP712Domain": [ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index e49468ee..43f83712 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -212,9 +212,22 @@ Signature: 22008ffd...0e1c 每次签名都输入密码很麻烦。通过环境变量可以跳过交互式提示： ```bash -export AGENT_WALLET_PASSWORD="Abc12345!" +export AGENT_WALLET_PASSWORD='Abc12345!' ``` +:::caution 密码包含特殊字符时必须用单引号 +主密码（尤其是自动生成的强密码）可能包含 `$`、`!` 等 shell 特殊字符，**必须用单引号**包裹，否则 shell 会展开这些字符导致密码错误： + +```bash +# ✅ 正确 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ 错误：$ 会被 shell 展开 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + + 设置后，所有签名命令不再提示输入密码，直接输出结果： ```bash diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md index f7e4a341..1f9a71ff 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md @@ -59,13 +59,13 @@ npm install @bankofai/agent-wallet **确认 Python 版本** -需要 Python ≥ 3.10，先检查当前版本： +需要 Python ≥ 3.11（SDK 使用了 `StrEnum` 等 3.11+ 特性），先检查当前版本： ```bash python3 --version ``` -如果输出 `3.10.x` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 +如果输出 `3.11.x` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 :::tip 安装 / 升级 Python @@ -88,14 +88,24 @@ echo 'eval "$(pyenv init -)"' >> ~/.bashrc source ~/.bashrc ``` -确认 pyenv 可用后，安装 Python： +确认 pyenv 可用后，先安装构建 Python 所需的系统依赖。**跳过这一步会导致 `_ctypes`、`ssl` 等模块缺失，进而引发标准库模块（如 `asyncio`）无法导入。** ```bash -pyenv install 3.10 -pyenv global 3.10 +# CentOS / RHEL / Amazon Linux / Fedora +sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel + +# Ubuntu / Debian +sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev +``` + +安装好系统依赖后，再构建 Python： + +```bash +pyenv install 3.11 +pyenv global 3.11 ``` -也可以直接从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.10 或更高版本**。 +也可以直接从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.11 或更高版本**。 ::: @@ -106,13 +116,19 @@ Python 包目前未发布到 PyPI，需从源码安装： ```bash git clone https://github.com/BofAI/agent-wallet.git cd agent-wallet/packages/python -pip install -e ".[all]" +pip3.11 install -e ".[all]" +``` + +SDK 依赖 `tronpy` 和 `eth_account` 处理 TRON 和 EVM 签名，若安装后遇到这两个包的导入错误，手动补装： + +```bash +pip3.11 install tronpy eth_account ``` 验证安装： ```bash -python -c "import agent_wallet; print('安装成功')" +python3.11 -c "import agent_wallet; print('安装成功')" ``` @@ -129,11 +145,24 @@ python -c "import agent_wallet; print('安装成功')" 私钥加密存储在本地，适合需要管理多个钱包或长期持久化密钥的场景。使用前需要先通过 CLI 完成初始化（`agent-wallet start`），然后设置主密码： ```bash -export AGENT_WALLET_PASSWORD="Abc12345!" +export AGENT_WALLET_PASSWORD='Abc12345!' # 可选：自定义目录，默认 ~/.agent-wallet export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` +:::caution 密码包含特殊字符时必须用单引号 +如果主密码包含 `$`、`!` 等 shell 特殊字符（例如自动生成的强密码），**必须用单引号**包裹，否则 shell 会对这些字符进行展开，导致密码被篡改： + +```bash +# ✅ 正确：单引号，密码原样传入 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ 错误：双引号，$ 会被 shell 展开 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + + ### 静态模式 直接通过环境变量提供私钥或助记词，无需本地密钥文件，适合 CI/CD 或一次性脚本场景。静态模式下必须同时指定 `network` 参数： From 17c1057797c52a3c7ffffa5ed06c3297b9352568 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Thu, 19 Mar 2026 15:11:05 +0800 Subject: [PATCH 08/44] fix --- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 41 +++---------------- .../SUNMCPServer/LocalPrivatizedDeployment.md | 19 ++------- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 15 ++----- .../LocalPrivatizedDeployment.md | 19 ++------- .../MCP/TRONMCPServer/ToolList.md | 4 +- docs/McpServer-Skills/SKILLS/Faq.md | 2 +- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 41 +++---------------- .../SUNMCPServer/LocalPrivatizedDeployment.md | 19 ++------- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 15 ++----- .../LocalPrivatizedDeployment.md | 19 ++------- .../MCP/TRONMCPServer/ToolList.md | 4 +- .../current/McpServer-Skills/SKILLS/Faq.md | 2 +- 12 files changed, 38 insertions(+), 162 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 45160178..c008d790 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -85,10 +85,7 @@ This page collects frequently asked questions when using SUN MCP Server and thei **Solution:** -1. **Configure Agent Wallet** - ```bash - export AGENT_WALLET_PASSWORD="your_secure_password" - ``` +1. **Configure [Agent Wallet](../../../Agent-Wallet/Intro)** (recommended) — set `AGENT_WALLET_PASSWORD` 2. **Or Configure Private Key (Testnet Only)** ```bash @@ -136,32 +133,9 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **Resolution Steps:** -1. **Verify Password Environment Variable** - ```bash - echo $AGENT_WALLET_PASSWORD - # Should output your password - ``` - -2. **Check Agent Wallet Directory** - ```bash - # Default location - ls ~/.agent-wallet/ - # Should contain wallet.json and other files - ``` - -3. **Reinitialize Wallet** - ```bash - # Delete existing wallet (backup important data!) - rm -rf ~/.agent-wallet/ - - # Restart server with correct password - export AGENT_WALLET_PASSWORD="your_new_password" - sun-mcp-server - ``` - -4. **Verify Password Complexity** - - Use strong password (minimum 8 characters) - - Avoid special characters, use alphanumeric combination +1. **Verify password**: Run `echo $AGENT_WALLET_PASSWORD` to confirm the variable is set correctly. +2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. +3. **If password is lost**: You'll need to re-initialize the wallet. See the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### "Conflicting Wallet Modes" @@ -297,12 +271,7 @@ sun-mcp-server - Check Permit2 request structured data - Confirm chain ID, token address, deadline correct -3. **Reinitialize Wallet** - ```bash - rm -rf ~/.agent-wallet/ - export AGENT_WALLET_PASSWORD="your_password" - sun-mcp-server - ``` +3. **Reinitialize Wallet** — see [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) for re-initialization instructions. 4. **Use Alternate Authorization Method** ``` diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index e6876113..7b7c1bdd 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -61,26 +61,15 @@ The wallet determines which identity the AI assistant uses to perform on-chain o #### Option 1: Agent Wallet (Recommended) -This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. +This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. -**Install and initialize Agent Wallet:** +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). -```bash -# Install -npm install -g @bankofai/agent-wallet - -# Create encrypted wallet -agent-wallet start -``` -Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. - -> For detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). - -**Set environment variables:** +**Set environment variables after initializing Agent Wallet:** ```bash # Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD="" +export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) export AGENT_WALLET_DIR="~/.agent-wallet" diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index d515d7b8..58ec6948 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -57,7 +57,7 @@ This is not an error — it's by design. Write tools (transfers, staking, etc.) To unlock write tools, configure one of the three wallet modes: -- Set `AGENT_WALLET_PASSWORD` (Agent Wallet mode, recommended) +- Set `AGENT_WALLET_PASSWORD` ([Agent Wallet](../../../Agent-Wallet/Intro) mode, recommended) - Set `TRON_PRIVATE_KEY` (Private Key mode) - Set `TRON_MNEMONIC` (Mnemonic mode) @@ -91,18 +91,9 @@ If the server reports an invalid private key at startup, it's usually a format i ### "Agent wallet password incorrect" error -`AGENT_WALLET_PASSWORD` must exactly match the master password set during `agent-wallet init`. If you're not sure: +`AGENT_WALLET_PASSWORD` must exactly match the master password set during wallet initialization. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. -1. **Check that the wallet directory exists**: - ```bash - ls ~/.agent-wallet/ # Default location - ``` - If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. - -2. **If the password is lost**, you'll need to re-initialize. Note: this creates a new wallet — funds in the old wallet must be recovered through other means. - ```bash - agent-wallet init - ``` +If the password is lost, you'll need to re-initialize — see the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### TronGrid API Key not working diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 989afc6f..cdf08be1 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -67,26 +67,15 @@ The wallet determines which identity the AI assistant uses to perform on-chain o #### Option 1: Agent Wallet (Recommended) -This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. +This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports **multi-wallet management** and runtime wallet switching via the `select_wallet` tool. -**Install and initialize Agent Wallet:** +> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro). -```bash -# Install -npm install -g @bankofai/agent-wallet - -# Create encrypted wallet -agent-wallet start -``` -Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. - -> For detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). - -**Set environment variables:** +**Set environment variables after initializing Agent Wallet:** ```bash # Add to ~/.zshrc or ~/.bashrc -export AGENT_WALLET_PASSWORD="" +export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) export AGENT_WALLET_DIR="~/.agent-wallet" diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index d5f361cf..f71eddb4 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -29,8 +29,8 @@ During testing, it is recommended to explicitly set `nile` each time to avoid un | Tool Name | Description | Key Parameters | Mode | | :--- | :--- | :--- | :--- | | `get_wallet_address` | Get the address (Base58 & Hex) of the currently configured wallet. | - | Read | -| `list_wallets` | List all available wallets with IDs and addresses (Agent Wallet mode). | - | Read | -| `select_wallet` | Switch the active wallet at runtime (Agent Wallet mode). | `walletId` | Write | +| `list_wallets` | List all available wallets with IDs and addresses ([Agent Wallet](../../../Agent-Wallet/Intro) mode). | - | Read | +| `select_wallet` | Switch the active wallet at runtime ([Agent Wallet](../../../Agent-Wallet/Intro) mode). | `walletId` | Write | | `sign_message` | Sign an arbitrary message using the configured wallet. | `message` | Write | | `convert_address` | Convert addresses between Hex (`41...`/`0x...`) and Base58 (`T...`) formats. | `address` | Read | diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index d21c64d0..59e6b7f2 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -186,7 +186,7 @@ The default uses the `v1.4.12` tag version. 5. Revoke token approvals on all protocols using the old wallet 6. Review the transaction history of the old wallet to confirm whether any unauthorized operations have occurred -Agent Wallet (encrypted storage) is safer than plaintext private keys — even if environment variables are compromised, attackers still need additional encryption keys to access funds. If you manage significant capital, consider switching to Agent Wallet mode. +[Agent Wallet](../../Agent-Wallet/Intro) (encrypted storage) is safer than plaintext private keys — even if environment variables are compromised, attackers still need additional encryption keys to access funds. If you manage significant capital, consider switching to Agent Wallet mode. ### How do I uninstall or update a skill? diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 9e29354e..9bb892f9 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -85,10 +85,7 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi **解决方案：** -1. **配置 Agent Wallet** - ```bash - export AGENT_WALLET_PASSWORD="your_secure_password" - ``` +1. **配置 [Agent Wallet](../../../Agent-Wallet/Intro)**（推荐）— 设置 `AGENT_WALLET_PASSWORD` 2. **或配置私钥（仅测试网）** ```bash @@ -136,32 +133,9 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **解决步骤：** -1. **验证密码环境变量** - ```bash - echo $AGENT_WALLET_PASSWORD - # 应输出你的密码 - ``` - -2. **检查 Agent Wallet 目录** - ```bash - # 默认位置 - ls ~/.agent-wallet/ - # 应包含 wallet.json 等文件 - ``` - -3. **重新初始化 Wallet** - ```bash - # 删除现有 wallet（备份重要数据！） - rm -rf ~/.agent-wallet/ - - # 使用正确的密码重启服务器 - export AGENT_WALLET_PASSWORD="your_new_password" - sun-mcp-server - ``` - -4. **验证密码复杂性** - - 使用强密码（最少 8 字符） - - 避免特殊字符，使用字母数字组合 +1. **验证密码**：运行 `echo $AGENT_WALLET_PASSWORD` 确认变量已正确设置。 +2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 +3. **密码丢失**：需要重新初始化钱包——详见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### "Conflicting wallet modes" @@ -297,12 +271,7 @@ sun-mcp-server - 检查 Permit2 请求的结构化数据 - 确认链 ID、代币地址、截止时间正确 -3. **重新初始化 Wallet** - ```bash - rm -rf ~/.agent-wallet/ - export AGENT_WALLET_PASSWORD="your_password" - sun-mcp-server - ``` +3. **重新初始化 Wallet** — 参见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart) 了解重新初始化步骤。 4. **使用备用授权方法** ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 74b51e8a..05ac541f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -61,26 +61,15 @@ import TabItem from '@theme/TabItem'; #### 方式一：通过 Agent Wallet（推荐）创建钱包 -这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。Agent Wallet 还支持**多钱包管理**和运行时通过 `select_wallet` 工具切换钱包。 -**安装并初始化 Agent Wallet：** +> Agent Wallet 的安装、初始化及详细用法请参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro)。 -```bash -# 安装 -npm install -g @bankofai/agent-wallet - -# 创建加密钱包 -agent-wallet start -``` -Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 - -> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 - -**设置环境变量：** +**初始化 Agent Wallet 后设置环境变量：** ```bash # 添加到 ~/.zshrc 或 ~/.bashrc -export AGENT_WALLET_PASSWORD="<你的主密码>" +export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） export AGENT_WALLET_DIR="~/.agent-wallet" diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 1f7053e9..e93ba0cc 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -57,7 +57,7 @@ 要解锁写入工具，配置以下三种钱包模式之一： -- 设置 `AGENT_WALLET_PASSWORD`（Agent Wallet 模式，推荐） +- 设置 `AGENT_WALLET_PASSWORD`（[Agent Wallet](../../../Agent-Wallet/Intro) 模式，推荐） - 设置 `TRON_PRIVATE_KEY`（私钥模式） - 设置 `TRON_MNEMONIC`（助记词模式） @@ -91,18 +91,9 @@ ### "Agent Wallet 密码错误" -`AGENT_WALLET_PASSWORD` 必须与执行 `agent-wallet init` 时设置的主密码完全一致。如果你不确定： +`AGENT_WALLET_PASSWORD` 必须与钱包初始化时设置的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -1. **检查钱包目录是否存在**： - ```bash - ls ~/.agent-wallet/ # 默认位置 - ``` - 如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 - -2. **密码丢失**时需要重新初始化。注意：这会创建一个新的钱包，旧钱包的资金需要通过其他方式恢复。 - ```bash - agent-wallet init - ``` +如果密码丢失，需要重新初始化钱包——详见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 62c96127..e0416d24 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -67,26 +67,15 @@ node --version # 应输出 v20.x.x 或更高 #### 方式一：通过 Agent Wallet（推荐）创建钱包 -这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。Agent Wallet 还支持**多钱包管理**和运行时通过 `select_wallet` 工具切换钱包。 -**安装并初始化 Agent Wallet：** +> Agent Wallet 的安装、初始化及详细用法请参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro)。 -```bash -# 安装 -npm install -g @bankofai/agent-wallet - -# 创建加密钱包 -agent-wallet start -``` -Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 - -> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 - -**设置环境变量：** +**初始化 Agent Wallet 后设置环境变量：** ```bash # 添加到 ~/.zshrc 或 ~/.bashrc -export AGENT_WALLET_PASSWORD="<你的主密码>" +export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） export AGENT_WALLET_DIR="~/.agent-wallet" diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index dd5dd885..f3c8ac77 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -30,8 +30,8 @@ TRON MCP Server 提供 **95 个工具**、**6 个提示词模板**和 **1 个资 | 工具名称 | 描述 | 关键参数 | 模式 | | :--- | :--- | :--- | :--- | | `get_wallet_address` | 获取当前已配置钱包的地址（Base58 和 Hex 格式） | - | 读取 | -| `list_wallets` | 列出所有可用钱包的 ID 和地址（Agent Wallet 模式） | - | 读取 | -| `select_wallet` | 在运行时切换活跃钱包（Agent Wallet 模式） | `walletId` | 写入 | +| `list_wallets` | 列出所有可用钱包的 ID 和地址（[Agent Wallet](../../../Agent-Wallet/Intro) 模式） | - | 读取 | +| `select_wallet` | 在运行时切换活跃钱包（[Agent Wallet](../../../Agent-Wallet/Intro) 模式） | `walletId` | 写入 | | `sign_message` | 使用已配置的钱包对任意消息进行签名 | `message` | 写入 | | `convert_address` | 在 Hex（`41...`/`0x...`）和 Base58（`T...`）格式之间转换地址 | `address` | 读取 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index 3f094c6e..98ab0668 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -186,7 +186,7 @@ GITHUB_BRANCH=main ./install.sh # 使用最新主分支 5. 撤销旧钱包在所有协议上的代币授权 6. 查看旧钱包的交易记录，确认是否已有未授权的操作 -Agent Wallet（加密存储）比明文私钥更安全——即使环境变量泄露，攻击者还需要额外的加密密钥才能访问资金。如果你管理较多资金，建议切换到 Agent Wallet 模式。 +[Agent Wallet](../../Agent-Wallet/Intro)（加密存储）比明文私钥更安全——即使环境变量泄露，攻击者还需要额外的加密密钥才能访问资金。如果你管理较多资金，建议切换到 Agent Wallet 模式。 ### 如何卸载或更新技能？ From 824c0d70123a24d5d8534cf515e7e307bee166e3 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Thu, 19 Mar 2026 15:49:02 +0800 Subject: [PATCH 09/44] fix --- docs/Agent-Wallet/FullExample.md | 23 ++++++++++--------- .../current/Agent-Wallet/FullExample.md | 23 ++++++++++--------- 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/Agent-Wallet/FullExample.md b/docs/Agent-Wallet/FullExample.md index aaa2f178..38b209f4 100644 --- a/docs/Agent-Wallet/FullExample.md +++ b/docs/Agent-Wallet/FullExample.md @@ -13,10 +13,9 @@ All examples are available in both TypeScript and Python — use the tabs to swi Before running any example below, make sure you have: -1. Python ≥ 3.11 (the SDK uses `StrEnum` and other 3.11+ features); no version constraint for TypeScript -2. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) -3. Initialized a local wallet via the CLI, or configured static mode environment variables -4. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) +1. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) +2. Initialized a local wallet via the CLI, or configured static mode environment variables +3. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) --- @@ -67,14 +66,7 @@ sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqli -:::tip `visible: true` and address format -The code passes `visible: true` to TronGrid. This parameter affects the address format the API expects: - -- **`visible: true`**: the API expects addresses in **Base58 format** (the standard human-readable TRON address, e.g. `TNmo...`) -- **`visible: false` (or omitted)**: the API expects addresses in **hex format** (e.g. `41b9f...`) -The example uses Base58 addresses, consistent with `visible: true`. -::: ### Full Code @@ -214,6 +206,15 @@ asyncio.run( - For mainnet, change `TRONGRID_API` to `https://api.trongrid.io` and `network` to `tron:mainnet`. ::: +:::tip `visible: true` and address format +The code passes `visible: true` to TronGrid. This parameter affects the address format the API expects: + +- **`visible: true`**: the API expects addresses in **Base58 format** (the standard human-readable TRON address, e.g. `TNmo...`) +- **`visible: false` (or omitted)**: the API expects addresses in **hex format** (e.g. `41b9f...`) + +The example uses Base58 addresses, consistent with `visible: true`. +::: + --- ## EVM Transfer (BSC / Ethereum) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md index 6d7a06ef..4e66f74e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md @@ -13,10 +13,9 @@ Agent-wallet 只负责签名，构建交易和广播由调用者完成。本页 在运行以下示例前，请确保： -1. Python >= 3.11（SDK 使用了 `StrEnum` 等 3.11+ 特性）；TypeScript 无版本限制 -2. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） -3. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 -4. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） +1. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） +2. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 +3. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） --- @@ -67,14 +66,7 @@ sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqli -:::tip `visible: true` 与地址格式 -代码中向 TronGrid 传入了 `visible: true` 参数。该参数会影响 API 对地址格式的要求： - -- **`visible: true`**：API 期望地址为 **Base58 格式**（即普通 TRON 地址，如 `TNmo...`） -- **`visible: false`（或不传）**：API 期望地址为 **十六进制格式**（如 `41b9f...`） -示例代码使用的是 Base58 格式地址，保持与 `visible: true` 一致即可。 -::: ### 完整代码 @@ -216,6 +208,15 @@ asyncio.run( - 主网操作请将 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet` ::: +:::tip `visible: true` 与地址格式 +代码中向 TronGrid 传入了 `visible: true` 参数。该参数会影响 API 对地址格式的要求： + +- **`visible: true`**：API 期望地址为 **Base58 格式**（即普通 TRON 地址，如 `TNmo...`） +- **`visible: false`（或不传）**：API 期望地址为 **十六进制格式**（如 `41b9f...`） + +示例代码使用的是 Base58 格式地址，保持与 `visible: true` 一致即可。 +::: + --- ## EVM 转账（BSC / Ethereum） From 3b87508402cfb5590596794f25f0875d59af2806 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Fri, 20 Mar 2026 21:09:49 +0800 Subject: [PATCH 10/44] fix --- .github/workflows/release-publish.yml | 81 +++++++++++++++++++++++++++ package.json | 1 + 2 files changed, 82 insertions(+) create mode 100644 .github/workflows/release-publish.yml diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml new file mode 100644 index 00000000..0882e992 --- /dev/null +++ b/.github/workflows/release-publish.yml @@ -0,0 +1,81 @@ +name: Build and Push Docker Image + +on: + push: + branches: + - main + - master + - ai-bankofai-patch-1 + tags: + - 'test' + pull_request: + branches: + - main + - master + - ai-bankofai-patch-1 + workflow_dispatch: + +env: + IMAGE_NAME: bankofai/docs + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Debug Docker Hub secrets + if: github.event_name != 'pull_request' + env: + DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} + DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} + run: | + echo "username=[$DOCKERHUB_USERNAME]" + echo "token_length=${#DOCKERHUB_TOKEN}" + + - name: Log in to Docker Hub + if: github.event_name != 'pull_request' + env: + DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} + DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} + run: | + echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin + + - name: Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.IMAGE_NAME }} + tags: | + type=raw,value=test + + - name: Determine APP_ENV + id: app_env + run: | + if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/master" ]]; then + echo "APP_ENV=production" >> $GITHUB_OUTPUT + elif [[ "${{ github.ref }}" == refs/tags/* ]]; then + echo "APP_ENV=production" >> $GITHUB_OUTPUT + else + echo "APP_ENV=development" >> $GITHUB_OUTPUT + fi + + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + context: . + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + build-args: | + APP_ENV=${{ steps.app_env.outputs.APP_ENV }} + cache-from: type=gha + cache-to: type=gha,mode=max + platforms: linux/amd64 \ No newline at end of file diff --git a/package.json b/package.json index 4bb0d72e..5f00a0d0 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,6 @@ { "name": "@x402-tron/docs", + "version": "1.2.4", "description": "x402-tron documentation", "license": "MIT", "scripts": { From 224d32dc4f99bc6f34ff502a0603a4246a8fd157 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Fri, 20 Mar 2026 21:17:54 +0800 Subject: [PATCH 11/44] fiix --- .github/workflows/release-publish.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml index 0882e992..d8c714f5 100644 --- a/.github/workflows/release-publish.yml +++ b/.github/workflows/release-publish.yml @@ -5,14 +5,14 @@ on: branches: - main - master - - ai-bankofai-patch-1 + - update-mcp-server tags: - 'test' pull_request: branches: - main - master - - ai-bankofai-patch-1 + - update-mcp-server workflow_dispatch: env: From 822bdae986af835dbe0230ea06243d79231881c8 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Fri, 20 Mar 2026 21:19:53 +0800 Subject: [PATCH 12/44] fix --- .github/workflows/release-publish.yml | 55 +++++++-------------------- 1 file changed, 14 insertions(+), 41 deletions(-) diff --git a/.github/workflows/release-publish.yml b/.github/workflows/release-publish.yml index d8c714f5..94f7d0c6 100644 --- a/.github/workflows/release-publish.yml +++ b/.github/workflows/release-publish.yml @@ -1,27 +1,18 @@ -name: Build and Push Docker Image +name: Release Publish on: push: branches: - main - - master - - update-mcp-server - tags: - - 'test' - pull_request: - branches: - - main - - master - - update-mcp-server - workflow_dispatch: env: IMAGE_NAME: bankofai/docs jobs: - build-and-push: + build-and-publish: runs-on: ubuntu-latest permissions: + id-token: write contents: read steps: @@ -31,51 +22,33 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - - name: Debug Docker Hub secrets - if: github.event_name != 'pull_request' - env: - DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} - DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - run: | - echo "username=[$DOCKERHUB_USERNAME]" - echo "token_length=${#DOCKERHUB_TOKEN}" - - name: Log in to Docker Hub - if: github.event_name != 'pull_request' env: DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} run: | echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin - - name: Extract Docker metadata - id: meta - uses: docker/metadata-action@v5 - with: - images: ${{ env.IMAGE_NAME }} - tags: | - type=raw,value=test + - name: Get version from package.json + id: version + run: echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT - - name: Determine APP_ENV - id: app_env + - name: Set Docker tags + id: meta run: | - if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/master" ]]; then - echo "APP_ENV=production" >> $GITHUB_OUTPUT - elif [[ "${{ github.ref }}" == refs/tags/* ]]; then - echo "APP_ENV=production" >> $GITHUB_OUTPUT - else - echo "APP_ENV=development" >> $GITHUB_OUTPUT - fi + echo "tags<> $GITHUB_OUTPUT + echo "${{ env.IMAGE_NAME }}:${{ steps.version.outputs.VERSION }}" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT - name: Build and push Docker image uses: docker/build-push-action@v6 with: context: . - push: ${{ github.event_name != 'pull_request' }} + push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} build-args: | - APP_ENV=${{ steps.app_env.outputs.APP_ENV }} + APP_ENV=production cache-from: type=gha cache-to: type=gha,mode=max - platforms: linux/amd64 \ No newline at end of file + platforms: linux/amd64 From 6728342b7cba39faadf0ae274f0b20461b51180b Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sat, 21 Mar 2026 01:58:05 +0800 Subject: [PATCH 13/44] update --- docs/Agent-Wallet/FAQ.md | 172 ++++----- docs/Agent-Wallet/FullExample.md | 8 +- docs/Agent-Wallet/Intro.md | 148 +++++--- docs/Agent-Wallet/QuickStart.md | 352 +++++++----------- docs/Agent-Wallet/SDKQuickStart.md | 40 +- .../current/Agent-Wallet/FAQ.md | 170 ++++----- .../current/Agent-Wallet/FullExample.md | 242 ++++++------ .../current/Agent-Wallet/Intro.md | 151 +++++--- .../current/Agent-Wallet/QuickStart.md | 352 +++++++----------- .../current/Agent-Wallet/SDKQuickStart.md | 160 ++++---- 10 files changed, 828 insertions(+), 967 deletions(-) diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index d8e87380..37d471fe 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -1,164 +1,120 @@ # FAQ +Let's answer the three things you're probably most worried about, then cover the day-to-day details. + --- -## About Agent-wallet +## 💰 Will AI drain my entire wallet? -### What is Agent-wallet and what does it do? +This is the most common question, and the answer is: **even if your AI agent gets compromised, your core assets stay safe.** -Agent-wallet is a **signing-only SDK**. It does two things: stores private keys encrypted locally, and signs messages, transactions, and EIP-712 typed data locally. +We strongly recommend creating a dedicated wallet just for your AI agent, topped up with only the small amount it actually needs (e.g., enough to cover gas fees). Your main wallet and large holdings never get touched. Worst case, the loss is limited to whatever was in that small agent wallet. -It does NOT: connect to RPCs, query on-chain data, build transactions, broadcast transactions, or initiate transfers or payments autonomously. +```bash +# Create a dedicated small wallet for your AI agent +agent-wallet add +``` -This separation is intentional — signing is a highly sensitive operation that should be as simple, auditable, and dependency-free as possible. The more focused the SDK, the smaller the attack surface. +And your wallet file is protected by strong encryption. Even if someone gets hold of the file, without the master password it's just garbage — brute-forcing it is economically worthless. -### How is it different from a regular blockchain wallet? +--- -Regular wallets (like MetaMask or TronLink) are designed for human users — they typically include balance displays, transfer UIs, DApp connections, and require manual confirmation for every operation. +## 🔌 Can my AI still sign if I go offline? -Agent-wallet is designed for programs. It exposes only a signing interface, with no UI, no network functionality, and no need for human interaction. The caller (an MCP Server, workflow code, etc.) is responsible for building transactions; Agent-wallet only signs and returns the result for the caller to broadcast. +Yes. **All Agent-wallet signing operations complete 100% on your local machine.** -### What about transfers and payments? +There's no network dependency by design — no RPC calls, no cloud services, no remote API requests. Your private key never touches the network. -Agent-wallet does not implement transfers itself. A complete transfer flow requires three steps: +Going offline only affects transaction building and broadcasting (that's the MCP Server's job). Signing itself is fully offline. -1. **Build the transaction** — The caller constructs an unsigned transaction object via TronGrid, Infura, or another RPC -2. **Sign** — The caller passes the unsigned transaction to Agent-wallet, which signs it locally and returns the result -3. **Broadcast** — The caller submits the signed transaction to the RPC for broadcasting +--- -Agent-wallet only participates in step 2. +## 🔑 What if I forget my password? -### What's the difference between the CLI and the SDK? Which should I use? +**It's gone.** -Both provide the same underlying capabilities, but for different scenarios: +The master password is the only credential for decrypting all private keys. We don't store it — not on disk, not in memory (it's wiped immediately after signing). There's no "forgot password" flow, no backdoor. -- **CLI** is for manual operation — initializing wallets, managing keys, testing signatures by hand. Day-to-day key management is done through the CLI. -- **SDK** is for programmatic integration — calling the signing interface from your own code, such as inside an MCP Server or an automation script. +If you forget your password: +- Have another backup of your private key or mnemonic? Run `agent-wallet reset`, reinitialize, and reimport. +- No backup at all? Access to that wallet is permanently lost. -Most users will use both: the CLI to initialize and manage wallets, and the SDK to call signing in code. +**So do this right now**: open your password manager and store the master password. Seriously. --- -## Local Mode vs. Static Mode +## Everyday Use -### When should I use local mode vs. static mode? +### What exactly is Agent-wallet? -**Local mode** (set `AGENT_WALLET_PASSWORD`) is suitable when: -- You need to manage multiple wallets -- You want keys encrypted and persisted locally long-term -- You need to interact with wallets via the CLI +A purely local encrypted signing tool. It does two things: 1) encrypts and stores your private keys; 2) signs locally. No internet, no cloud. It has no standalone UI of its own — instead, it operates as an invisible security hub that integrates seamlessly into AI frontends like OpenClaw. -**Static mode** (set `AGENT_WALLET_PRIVATE_KEY` or `AGENT_WALLET_MNEMONIC`) is suitable when: -- You only need a single wallet -- You're in a CI/CD or one-off script scenario -- Keys are already managed by an external system and you don't want an additional local storage layer +### CLI vs SDK — which do I need? -### Can I use both modes at the same time? +- **CLI** — command-line tool for creating wallets, managing keys, and manually testing signatures +- **SDK** — TypeScript / Python library for calling signing directly from your own code + +Most users don't need the SDK. If you're using OpenClaw and MCP Server, creating a wallet with the CLI and setting the environment variable is all you need. The SDK is for developers building their own agents. + +--- -No, you can't run both simultaneously — but you can switch at any time. `AGENT_WALLET_PASSWORD` takes precedence over the private key / mnemonic variables. `AGENT_WALLET_PRIVATE_KEY` and `AGENT_WALLET_MNEMONIC` cannot be set at the same time. +## Wallet Types -### How do I fill in the `network` parameter? +### What's the difference between `local_secure` and `raw_secret`? -The `network` parameter determines which chain adapter to use: +| | `local_secure` | `raw_secret` | +| :--- | :---: | :---: | +| **Key encryption** | ✅ Strong encryption | ❌ Plaintext | +| **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly | +| **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev environments only | + +**Always use `local_secure`** unless you're 100% certain no other agent is running on that machine. + +### What values does the `network` parameter accept? | Value | Description | | :--- | :--- | +| `tron:mainnet` | TRON Mainnet | +| `tron:nile` | TRON Nile Testnet | +| `tron:shasta` | TRON Shasta Testnet | | `eip155:1` | Ethereum Mainnet | | `eip155:56` | BSC Mainnet | | `eip155:137` | Polygon Mainnet | | `eip155:8453` | Base Mainnet | | `eip155:42161` | Arbitrum Mainnet | -| `tron:mainnet` | TRON Mainnet | -| `tron:nile` | TRON Nile Testnet | -| `tron:shasta` | TRON Shasta Testnet | - -Any value with the `eip155:` prefix routes to the EVM adapter; `tron:` routes to the TRON adapter. The chain ID itself doesn't affect signing logic — it only determines which adapter handles the request. --- ## Security -### How are private keys stored? - -In local mode, private keys are stored encrypted in **Keystore V3** format, using scrypt (N=262144, r=8, p=1) + AES-128-CTR + keccak256 MAC. This is the encryption standard widely used across the Ethereum ecosystem. The computational cost of scrypt is extremely high, making brute-force attacks effectively infeasible. - -The master password is never stored. `master.json` holds only an encrypted sentinel value used to verify whether a password is correct — not the password itself. - -### Will my keys ever be sent over the network? - -Never. All signing operations are pure local computation. Agent-wallet makes no network calls. Your private keys never leave your machine. - -### How should I protect my master password? - -- Pass it via an environment variable (`AGENT_WALLET_PASSWORD`) rather than writing it in code -- Don't commit `.env` files containing passwords to Git — add them to `.gitignore` -- Use a password manager (such as 1Password or Bitwarden) to store your master password +### Does the private key ever leave my machine? -### What if I forget my master password? +Never. Agent-wallet makes zero network requests. Zero RPC calls, zero cloud services. Your private key never leaves your machine. -The master password cannot be recovered. Agent-wallet does not store it and provides no recovery mechanism. +### How should I store the master password securely? -If you forget your master password: -- If you have another backup of your private key (such as a mnemonic), run `agent-wallet reset` to wipe local data, then re-initialize and re-import your key -- If you have no other backup, the encrypted key files cannot be decrypted and access to those wallets is permanently lost - -This is why we strongly recommend **backing up your private key or mnemonic separately** when creating a wallet — don't rely solely on Agent-wallet's local storage. - -### Are keys used by AI agents safe? - -That depends on how you configure them. Recommended practices: - -- Create a dedicated wallet for the agent — don't use your personal primary wallet -- Fund that wallet with only the small amount the agent needs to operate -- Pass keys or passwords via environment variables — never hardcode them - -This way, even if the agent behaves unexpectedly, losses are limited to the pre-funded amount. - ---- - -## Cross-Language Compatibility - -### Are key files interchangeable between Python and TypeScript? - -Yes. Both implementations use the exact same Keystore V3 format. A key file created by Python can be read directly by TypeScript and vice versa. This means you can initialize a wallet with the CLI (TypeScript) and use the same keys directly in Python code. - -### Do both language versions produce the same signatures? - -Yes. The same private key signing the same data produces identical results in both Python and TypeScript. Address derivation rules and EIP-712 encoding logic are also identical. - -### What are the API differences between the two language versions? - -The interface design is a 1:1 correspondence. The main difference is naming convention: TypeScript uses camelCase (`signMessage`, `getActiveWallet`) while Python uses snake_case (`sign_message`, `get_active_wallet`). Behavior is otherwise identical. +- ✅ Use a password manager (1Password, Bitwarden) +- ✅ Pass it via the `AGENT_WALLET_PASSWORD` environment variable +- ❌ Don't hardcode it in source code +- ❌ Don't commit a `.env` containing the password to git --- -## Relationship with Other Components - -### What is the relationship between Agent-wallet and MCP Server? +## Cross-language -MCP Servers (such as TRON MCP Server and BSC MCP Server) provide AI agents with on-chain operation tools — querying balances, building transactions, etc. When an MCP Server needs a signature, it calls Agent-wallet to sign, then handles broadcasting itself. +### Are key files compatible between Python and TypeScript? -Agent-wallet is the signing backend for MCP Servers. MCP Servers do not directly handle private keys. - -### What is the relationship between Agent-wallet and the x402 protocol? - -x402 is an HTTP payment protocol. When an agent needs to complete an x402 payment, it must sign the PaymentPermit typed data (EIP-712 format). That signature is provided by Agent-wallet. - -The x402 SDK handles building payment requests and managing the protocol flow; Agent-wallet handles signing. Their responsibilities are clearly separated — Agent-wallet has no knowledge of or concern for x402 business logic. - ---- +Yes. Both implementations use exactly the same encryption format. A wallet created with the CLI works directly with the Python SDK, and vice versa. -## Supported Chains +### Do both languages produce the same signature? -| Chain Type | Network Identifier | Specific Networks | -| :--- | :--- | :--- | -| EVM | `eip155:*` | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | -| TRON | `tron:*` | TRON Mainnet, Nile Testnet, Shasta Testnet | +Identical. Same private key + same data = same signature. --- -## Next Steps +## What's Next -- Initialize a wallet and start signing → [CLI Quick Start](./QuickStart.md) -- Integrate signing in your code → [SDK Quick Start](./SDKQuickStart.md) -- Understand the overall design → [Introduction](./Intro.md) +- Set up your full environment → [CLI Quick Start](./QuickStart.md) +- Sign from code → [SDK Quick Start](./SDKQuickStart.md) +- See real transfer examples → [Full Examples](./FullExample.md) +- Learn about OpenClaw Extension → [OpenClaw Introduction](../Openclaw-extension/Intro.md) diff --git a/docs/Agent-Wallet/FullExample.md b/docs/Agent-Wallet/FullExample.md index 38b209f4..cec62891 100644 --- a/docs/Agent-Wallet/FullExample.md +++ b/docs/Agent-Wallet/FullExample.md @@ -1,9 +1,11 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Full Usage Examples +# Full Examples -Agent-wallet handles signing only — building and broadcasting transactions is your responsibility. This page walks through complete end-to-end examples that chain all three steps together: TRON transfers, EVM transfers, and x402 PaymentPermit signing. +You know how to sign. Now let's put it all together — build a transaction, sign it with Agent-wallet, and broadcast it to the network. + +This page walks through three real-world scenarios end to end: sending TRX on TRON, sending BNB on BSC, and signing an x402 payment permit. Each example is complete and runnable — copy, configure your addresses, and go. All examples are available in both TypeScript and Python — use the tabs to switch. @@ -15,7 +17,7 @@ Before running any example below, make sure you have: 1. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) 2. Initialized a local wallet via the CLI, or configured static mode environment variables -3. Set `AGENT_WALLET_PASSWORD` (local mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) +3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) --- diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index ea270143..5e321fc8 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -1,108 +1,154 @@ # Introduction -AI agents are increasingly involved in on-chain operations: paying API fees, signing authorizations, executing transfers. But there's an unavoidable challenge — private keys. +## Profit from AI Agents Without the Private Key Risk -Hardcoding private keys in source code is unsafe. Delegating them to a cloud service means losing control. Requiring manual confirmation for every operation defeats the purpose of "autonomous." +### Your Private Key Is One File Read Away from Being Stolen -AI agents need a way to **keep keys securely local, sign locally, and expose only a clean interface to the outside world**. +You want your AI agent to handle on-chain work automatically — airdrop farming, token swaps, paying gas fees, scheduled transfers. To do any of that, the agent needs a "key" (your private key) to sign transactions on your behalf. -That's the problem **Agent-wallet** is designed to solve. +So you drop it into a `.env` file. + +**That's like writing your bank card number and PIN on a sticky note and walking into a room full of strangers.** + +That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read your `.env` file. Your private key has no password protection, no encryption, no access control — it's just plaintext, one file read away from being gone. --- -## What is Agent-wallet +### This Isn't Hypothetical — It's Already Happening -**Agent-wallet** is a **signing-only SDK** that enables AI agents (MCP servers, autonomous workflows, etc.) to securely manage and use blockchain keys. +- **Dependency chain poisoning.** You install a useful MCP server. Three months later, one of its 200 npm dependencies gets a malicious update — quietly scanning all `.env` and `*.json` files for anything that looks like a private key, then sending it out. You never see it happen. By the time you notice, your wallet is empty. -:::tip It does two things +- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your `.env` is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. -- **Key storage** — Encrypts and stores private keys locally using the Keystore V3 format -- **Local signing** — Signs messages, transactions, and EIP-712 typed data with zero network calls +- **Git's perfect memory.** You hardcoded a key during development and deleted it later. But you committed it once, three weeks ago. It's still in `git log -p`. If that repo ever touched GitHub, even for 30 seconds, automated scrapers already found it. -::: +- **Cloud wallets: trading one exposure for another.** "Just use a cloud wallet service" — your key is off your machine, but now it's on someone else's server. Their breach is your breach. Their downtime is your agent's downtime. You've just moved the risk from one hand to the other. + +The common thread: **your private key is always exposed somewhere** — on disk, in logs, in git history, or on someone else's infrastructure. -:::caution What it does NOT do +--- -- Does not connect to any RPC or query on-chain data -- Does not build transactions (the caller is responsible) -- Does not broadcast transactions (the caller is responsible) -- Does not initiate transfers or payments autonomously +## The Fix: Agent-wallet -::: +Agent-wallet is a **local encrypted safe** that works even when you're offline. -This separation of concerns keeps Agent-wallet lightweight and free from any dependency on a specific RPC provider. +It does exactly one thing: **use industry-grade encryption to lock your vulnerable plaintext private key on your own machine, and sign locally.** ---- +Even if someone gets hold of your wallet file, without the master password it's pure garbage data. Brute-forcing it would take longer than the age of the universe — economically pointless. At the same time, all signing operations complete on your machine — no network calls, no third-party APIs, no cloud intermediaries. -## Why Agent-wallet +**Bottom line: steal the file all you want — it's unreadable. Sign locally — nothing to intercept.** -### Built for AI Agents +--- -Traditional wallets are designed for humans — they have interfaces, require manual confirmation, and assume a user is present. Agent-wallet's interface is designed for programs: configured via environment variables, called through an SDK, and naturally suited for embedding inside an MCP Server or automated workflow. +## How It Compares -### Private Keys Never Leave the Machine +| | Plaintext key / `.env` | Cloud wallet | Agent-wallet | +| :--- | :---: | :---: | :---: | +| **Agent reads your key file** | ❌ Stolen instantly | — Key is remote | ✅ Encrypted — useless without password | +| **Who owns the key** | ⚠️ Whoever can read the file | ❌ The provider | ✅ Only you (master password) | +| **Works offline** | ⚠️ Depends | ❌ Must be online | ✅ 100% offline signing | +| **Designed for AI agents** | ❌ Manual integration | ⚠️ REST API, latency | ✅ CLI + SDK, local, instant | +| **Multi-chain support** | ❌ Build it yourself | ⚠️ Provider-dependent | ✅ EVM + TRON, one interface | +| **Production-ready** | ❌ Dangerous | ⚠️ Trust a third party | ✅ Self-hosted, auditable | -All signing happens locally with zero network requests. Private keys are never sent to any server, and there is no dependency on cloud HSMs or custodial services. You retain full control of your keys. +--- -### Bank-Grade Key Encryption +## Three Commands, Under a Minute -Private keys are stored encrypted in **Keystore V3** format, using scrypt (with a computational cost orders of magnitude higher than standard bcrypt) + AES-128-CTR + keccak256 MAC. Even if the key file is stolen, the private key cannot be extracted without the master password. The master password itself is never stored to disk in any form. +No need to understand everything first — get it running, then explore: -### Not Tied to Any RPC Provider +**Step 1 — Install:** +```bash +npm install -g @bankofai/agent-wallet +``` -Because Agent-wallet performs no on-chain operations, you can use any RPC provider — TronGrid, Infura, a self-hosted node — without affecting signing logic. Migrating or switching providers requires zero changes to signing code. +**Step 2 — Create your encrypted safe:** +```bash +agent-wallet start +``` +The wizard will initialize your Agent-wallet encrypted safe and generate a **master password**. This is the only key to all your assets — if you lose it, there's no recovery. Save it in a password manager now. -### Multi-chain, Dual-language, One Interface +**Step 3 — Your first signature:** +```bash +agent-wallet sign msg "Hello from my AI agent" -n tron +``` -EVM and TRON share the same `BaseWallet` interface. The Python and TypeScript implementations behave identically and share the same key file format. The same key, in a different language, produces the exact same signature. +When a hash string appears on screen — congratulations, your encrypted safe is live. + +> Want the full step-by-step walkthrough? Head to **[Quick Setup — CLI Quick Start](./QuickStart.md)**. --- -## Two Ways to Use It +## Next: Connect Your AI Agent + +Your safe is set up and signing works. Now the question is: **how do I get my AI agent to actually use this wallet?** -### CLI (Command-Line Tool) +Pick the path that fits you: -Best for managing keys, manually testing signatures, and daily key management tasks. +### 🎮 I'm a casual user — using existing tools + +No code required. Many AI tools natively support Agent-wallet (we **strongly recommend our [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)** — one-click install, works out of the box). All you need to do is tell the tool your master password: ```bash -npm install -g @bankofai/agent-wallet -agent-wallet start # Initialize and create a default wallet -agent-wallet sign msg "Hello" # Sign a message +export AGENT_WALLET_PASSWORD='your-master-password' ``` -→ See [CLI Quick Start](./QuickStart.md) +:::caution Password contains special characters? Always use single quotes +Auto-generated passwords often include `$`, `!`, and other shell-special characters. **Wrap in single quotes** or the shell will silently mangle the value: -### SDK (Programmatic Interface) +```bash +# ✅ Correct +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: -Best for integrating signing capabilities in code, such as inside an MCP Server. +Once set, your tools automatically call your Agent-wallet encrypted safe to sign. The tool only ever receives the signature result — never the private key itself. + +> Want to see supported tools? Go to **[OpenClaw Extension](../Openclaw-extension/Intro.md)**. + +### 🛠️ I'm a developer — building my own agent + +
+Expand developer path — TypeScript / Python SDK + +Agent-wallet ships a complete SDK with TypeScript and Python support — both sharing the same interface: ```typescript import { resolveWalletProvider } from "@bankofai/agent-wallet"; const provider = resolveWalletProvider({ network: "tron:nile" }); -const wallet = await provider.getActiveWallet(); -const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); ``` -Available in both **Python** and **TypeScript**, with identical interfaces and fully compatible output. +Same key file, same data, same signature — across both languages. -→ See [SDK Quick Start](./SDKQuickStart.md) +> **[SDK Quick Start](./SDKQuickStart.md)** — step-by-step integration guide. +> **[Full Examples](./FullExample.md)** — end-to-end real transactions: TRON transfers, BSC transfers, x402 payment signing. + +
--- ## Supported Chains -| Chain Type | Network Identifier | Supported Networks | -| :--- | :--- | :--- | -| **EVM** | `eip155:*` | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | -| **TRON** | `tron:*` | TRON Mainnet, Nile Testnet, Shasta Testnet | +| Chain Type | Networks | +| :--- | :--- | +| **EVM** | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | +| **TRON** | TRON Mainnet, Nile Testnet, Shasta Testnet | + +Both chain types share the same interface — learn it once, use it everywhere. --- -## Where to Start +## Still Have Questions? -| Your Goal | Start Here | +| I'm wondering… | Go here | | :--- | :--- | -| Initialize a wallet, manage keys and sign via command line | [CLI Quick Start](./QuickStart.md) | -| Integrate signing in Python or TypeScript code | [SDK Quick Start](./SDKQuickStart.md) | -| Browse common questions | [FAQ](./FAQ.md) | +| Will AI drain my wallet? | [FAQ](./FAQ.md) — we have a dedicated risk isolation solution | +| Ready to set it up now | [Quick Setup — CLI Quick Start](./QuickStart.md) | +| Want to use it in code | [SDK Quick Start](./SDKQuickStart.md) | +| Want to see real transaction examples | [Full Examples](./FullExample.md) | diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 21f259dc..839a3971 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -1,344 +1,280 @@ # CLI Quick Start -This guide walks you through installing Agent-wallet, initializing a wallet, and signing your first message or transaction from the command line. After completing these four steps, you'll have a locally encrypted wallet and be ready to sign messages and transactions via CLI. +Four steps, from zero to your first signature. The whole thing takes under a minute — just copy and paste. -The second half of this page is a full command reference — come back to it whenever you need it. - -If you're a developer looking to call the signing interface directly from Python or TypeScript code, see [SDK Quick Start](./SDKQuickStart.md). +:::tip Already a developer? +If you want to call signing directly from TypeScript or Python code, skip to [SDK Quick Start](./SDKQuickStart.md). +::: --- -## Step 1: Install +## 🧰 Step 1: Set Up Your Environment -### Check Your Node.js Version - -Agent-wallet CLI requires Node.js ≥ 18. First check your current version: +Agent-wallet CLI requires Node.js ≥ 18. Check what you have: ```bash node -v ``` -If the output is `v18.0.0` or higher, you can jump straight to installation. Otherwise, follow the instructions below. +Output is `v18.x.x` or higher? Jump to Step 2. Nothing installed or version too old? Follow the steps below: -:::tip Install / Upgrade Node.js +:::tip Install / upgrade Node.js -We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions: +We recommend [nvm](https://github.com/nvm-sh/nvm) — one command handles everything: +**1 — Install nvm** (skip if already installed): ```bash -# Install nvm (skip if already installed) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +``` -# Reload shell config -source ~/.bashrc # or source ~/.zshrc +**2 — Reload your shell config:** +```bash +source ~/.bashrc # zsh users: source ~/.zshrc +``` -# Install Node.js 18 LTS +**3 — Install Node.js 18:** +```bash nvm install 18 +``` -# Switch to Node.js 18 +**4 — Switch to Node.js 18:** +```bash nvm use 18 ``` -You can also download the **LTS** installer directly from [nodejs.org](https://nodejs.org). - +Or download the LTS installer directly from [nodejs.org](https://nodejs.org). ::: -### Install Agent-wallet CLI +--- + +## 📦 Step 2: Install Agent-wallet + +One command: ```bash npm install -g @bankofai/agent-wallet ``` -Verify the installation: +Python users can also install via pip: +```bash +pip install bankofai-agent-wallet +``` +Verify the install worked: ```bash agent-wallet --help ``` ---- - -## Step 2: Initialize a Wallet +If you see the help output, you're good to go. -The `start` command handles initialization and wallet creation in one step. There are three options: +--- -### Option A: Fully Automatic (Recommended for Beginners) +## 🔐 Step 3: Create Your Personal Encrypted Safe +Run: ```bash agent-wallet start ``` -The system auto-generates a strong password and creates one TRON wallet and one EVM wallet: +This initializes your **Agent-wallet encrypted safe**. The process is interactive — just follow the prompts. + +If you don't specify a password manually (the `-p` flag), the system auto-generates a strong one and shows it once: ``` -🔐 Wallet initialized! +? Quick start type: local_secure — Encrypted key stored locally (recommended) +Wallet ID (e.g. my_wallet_1) (default): -🪙 Wallets: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TB37... │ -│ default_evm │ evm_local │ 0xd679B... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ +Wallet initialized! +? Import source: generate — Generate a new random private key -⭐ Active wallet: default_tron +Wallets: +┌───────────┬──────────────┐ +│ Wallet ID │ Type │ +├───────────┼──────────────┤ +│ default │ local_secure │ +└───────────┴──────────────┘ -🔑 Your master password: E&LCi*KL1Sp4mg4! - ⚠️ Save this password! You'll need it for signing and other operations. +Your master password: WiJxcI#t6@73K#OE + Save this password! You'll need it for signing and other operations. + +Active wallet: default ``` -:::caution Security Tips -- **Keep your master password safe** — It's the only credential that decrypts all your private keys. If lost, it cannot be recovered. Use a password manager. -- **Never hardcode it in source code** — For non-interactive use, pass it via the `AGENT_WALLET_PASSWORD` environment variable instead. -- **Don't commit `.env` files** — Add `.env` to `.gitignore` to prevent passwords or keys from leaking into version control. -- **Use a dedicated wallet for agents** — Don't give an AI agent your personal wallet's private key. Create a separate wallet and fund it with only the amount the agent needs. -::: +:::caution ⚠️ Master password = the only key to all your assets +This password is the sole credential for decrypting all your private keys. **Lose it and it's gone forever — no backup, no backdoor, no recovery.** -### Option B: Custom Password +Do this right now: +1. Open your password manager (1Password, Bitwarden, etc.) +2. Create a new entry and paste in the master password +3. Don't screenshot it, don't put it in a desktop sticky note, don't text it to yourself +::: +**Want to set your own password?** ```bash agent-wallet start -p Abc12345! ``` +Requirements: at least 8 characters, with uppercase, lowercase, numbers, and special characters. -Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. - -### Option C: Import an Existing Private Key - -If you already have a private key you'd like to import: - +**Already have a private key to import?** ```bash -agent-wallet start -p Abc12345! -i tron +agent-wallet start -p Abc12345! -k your-private-key-hex ``` -You'll be prompted to paste the private key (input is hidden): - -``` -🔐 Wallet initialized! -✔ Paste private key (hex) - -🪙 Imported wallet: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TNmo... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ - -⭐ Active wallet: default_tron +**Have a mnemonic phrase?** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." ``` -The `-i` flag accepts `tron`, `evm`, `tron_local`, or `evm_local`. - --- -## Step 3: View Your Wallets +## ✨ Step 4: Your First Test Signature -List all wallets: +The exciting moment — run: ```bash -agent-wallet list +agent-wallet sign msg "Hello from my AI agent" -n tron ``` -``` -Wallets: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│* default_tron │ tron_local │ TB37... │ -│ default_evm │ evm_local │ 0xd679B... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ -``` - -The `*` marks the currently active wallet, which is used by default for all signing operations. - ---- +You'll be prompted for your master password, then see output like: -## Step 4: Sign - -### Sign a Message - -```bash title="Input" -agent-wallet sign msg "Hello" -``` - -```text title="Output" +```text Master password: ******** Signature: 4a9c8f...e71b ``` -### Sign a Transaction - -Pass the transaction as a JSON string (you must build the unsigned transaction via RPC first): - -```bash title="Input" -agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -``` +**When that hash string appears on screen — congratulations, your encrypted safe is live!** 🎉 -```text title="Output" -Master password: ******** -Signed tx: -{ - "txID": "abc123...", - "signature": ["..."] -} -``` +Your private key is encrypted on disk. That signature just happened entirely on your local machine, with zero data sent over the network. -### Sign EIP-712 Typed Data +--- -```bash title="Input" -agent-wallet sign typed-data '{ - "types": { - "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], - "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] - }, - "primaryType": "Transfer", - "domain": {"name":"MyDApp","chainId":1}, - "message": {"to":"0x7099...","amount":1000000} -}' -``` +## 🚀 Quick Start Done! What's Next? -```text title="Output" -Master password: ******** -Signature: 22008ffd...0e1c -``` +| I want to… | Do this | +| :--- | :--- | +| Connect my wallet to AI tools | Set `export AGENT_WALLET_PASSWORD='your-password'`, see [Introduction](./Intro.md) | +| Sign from my own code | Go to [SDK Quick Start](./SDKQuickStart.md) | +| See a complete transfer example | Go to [Full Examples](./FullExample.md) | +| Browse the full command reference | ↓ Keep reading | --- ## Command Reference -Once you've completed the quick start, refer to this section as needed. +Everything you'll need day-to-day after the quick start. Look things up as needed. -### Skip the Password Prompt +### Password-free Signing -Typing the password on every signing command gets tedious. Set an environment variable to skip the interactive prompt: +Typing your password interactively every time? That's a non-starter for automation. Three ways to skip it: +**Option A — Environment variable** (recommended for CI / agent pipelines): ```bash export AGENT_WALLET_PASSWORD='Abc12345!' ``` +Once set, all signing commands run silently: +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` -:::caution Always use single quotes when the password contains special characters -Master passwords — especially auto-generated ones — may contain `$`, `!`, or other shell-special characters. **Always use single quotes** to prevent the shell from expanding them: - +:::caution Password contains special characters? Always use single quotes ```bash -# ✅ Correct +# ✅ Correct — shell treats it literally export AGENT_WALLET_PASSWORD='P@ss$w0rd!' -# ❌ Wrong: $ gets expanded by the shell +# ❌ Wrong — $ gets expanded by the shell, password silently breaks export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: - -After this, all signing commands run without prompting: - +**Option B — Inline `-p`** (one-off use): ```bash -agent-wallet sign msg "Hello" -agent-wallet sign tx '{"txID":"..."}' +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" ``` -You can also pass the password inline with `-p`: - +**Option C — `--save-runtime-secrets`** (saves password to `~/.agent-wallet/runtime_secrets.json` for auto-loading): ```bash -agent-wallet sign msg "Hello" -p "Abc12345!" +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` -### Manage Multiple Wallets +### Signature Types -#### 1. Add a New Wallet +Every `sign` subcommand requires `--network` / `-n` to specify the chain: -An interactive prompt lets you choose the wallet type (`tron_local` or `evm_local`) and generate or import a key: +**Sign a message:** +```bash +agent-wallet sign msg "Hello" -n tron +``` -```bash title="Input" -agent-wallet add +**Sign a transaction** (build the unsigned tx via RPC first): +```bash +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron ``` -```text title="Output" -Master password: ******** -Wallet name: my-bsc-wallet -> Wallet type: evm_local -> Private key: generate -Generated new private key. - Address: 0x8c714fe3... - Saved: id_my-bsc-wallet.json -Wallet 'my-bsc-wallet' added. +**Sign EIP-712 typed data:** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 ``` -#### 2. Switch the Active Wallet +### Managing Multiple Wallets -```bash title="Input" -agent-wallet use my-bsc-wallet +**Add a new wallet:** +```bash +agent-wallet add ``` -```text title="Output" -Active wallet: my-bsc-wallet (evm_local) +**Switch the active wallet:** +```bash +agent-wallet use my-bsc-wallet ``` -#### 3. Sign with a Specific Wallet - -Use `-w` to sign with a specific wallet regardless of the active wallet setting: - +**Sign with a specific wallet** (without switching the active one): ```bash -agent-wallet sign msg "Hello" -w my-bsc-wallet -p "Abc12345!" +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" ``` -#### 4. Inspect a Wallet - -```bash title="Input" +**Inspect a wallet:** +```bash agent-wallet inspect my-bsc-wallet ``` -```text title="Output" -Wallet my-bsc-wallet -Type evm_local -Address 0x8c714fe3... -Identity id_my-bsc-wallet.json ✓ -Credential — +**List all wallets:** +```bash +agent-wallet list ``` -#### 5. Remove a Wallet - -```bash title="Input" +**Remove a wallet:** +```bash agent-wallet remove my-bsc-wallet ``` -```text title="Output" -Remove wallet 'my-bsc-wallet'? (y/N): y - Deleted: id_my-bsc-wallet.json -Wallet 'my-bsc-wallet' removed. -``` - -### Other Operations - -#### 1. Change Master Password +### Change Master Password -The master password is the only credential used to encrypt all local private keys. Agent-wallet never stores the master password itself — it uses the password to encrypt each key file. When you change it, all key files are re-encrypted with the new password. +All key files are re-encrypted with the new password: -```bash title="Input" +```bash agent-wallet change-password ``` -```text title="Output" -Current password: ******** -New password: ******** -Confirm new password: ******** -Password changed. Re-encrypted 3 files. -``` +### Reset Everything -#### 2. Reset All Data +Deletes all contents under `~/.agent-wallet/`. **Irreversible** — requires confirmation: -```bash title="Input" +```bash agent-wallet reset ``` -```text title="Output" -⚠️ This will delete ALL wallet data in: /home/you/.agent-wallet -Are you sure you want to reset? This cannot be undone. (y/N): y -Really delete everything? Last chance! (y/N): y -✅ Wallet data reset complete. -``` - -Deletes everything in `~/.agent-wallet/`. This action is irreversible and requires double confirmation. - -#### 3. Custom Storage Directory +### Custom Storage Directory -All commands support `--dir` to specify a custom key storage directory (default: `~/.agent-wallet`): +All commands support `--dir` to specify a custom key storage path (default: `~/.agent-wallet`): ```bash agent-wallet start --dir ./my-secrets @@ -347,8 +283,8 @@ agent-wallet sign msg "Hello" --dir ./my-secrets --- -## Next Steps +## What's Next -- Use signing in your code → [SDK Quick Start](./SDKQuickStart.md) -- Understand the design → [Introduction](./Intro.md) +- Connect AI tools to your wallet → [Introduction — casual user path](./Intro.md) +- Sign from code → [SDK Quick Start](./SDKQuickStart.md) - Browse common questions → [FAQ](./FAQ.md) diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/SDKQuickStart.md index a0bfadb4..2d69ae2a 100644 --- a/docs/Agent-Wallet/SDKQuickStart.md +++ b/docs/Agent-Wallet/SDKQuickStart.md @@ -3,13 +3,15 @@ import TabItem from '@theme/TabItem'; # SDK Quick Start -This page is for developers who want to call Agent-wallet's signing interface directly from Python or TypeScript code. +You've tried the CLI and can sign from the command line. Now you want signing inside your own code — an MCP Server, an automation script, an AI agent workflow. -Unlike the CLI, the SDK is designed for embedding signing capabilities into your own program — such as providing signing support for an AI agent inside an MCP Server, or authorizing on-chain operations from an automation script. Your code is responsible for building and broadcasting transactions; Agent-wallet handles local signing and returns the result. +This page shows you how. By the end, you'll be able to initialize a wallet provider, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data — all in a few lines of TypeScript or Python. -By the end of this guide, you'll be able to initialize a wallet provider in code, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data. If you haven't initialized a local wallet yet, it's recommended to complete Steps 1 through 3 of the [CLI Quick Start](./QuickStart.md) first. +:::tip New here? +If you haven't created a wallet yet, start with the [CLI Quick Start](./QuickStart.md) first (Steps 1–3 take under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. +::: -Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch between them. +Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch. --- @@ -111,24 +113,21 @@ You can also download an installer from [python.org](https://www.python.org/down **Install the SDK** -The Python package is not yet published to PyPI and must be installed from source: - ```bash -git clone https://github.com/BofAI/agent-wallet.git -cd agent-wallet/packages/python -pip3.11 install -e ".[all]" +pip install 'bankofai-agent-wallet[evm,tron]' ``` -The SDK depends on `tronpy` and `eth_account` for TRON and EVM signing. If you encounter import errors for either package after installation, install them manually: +If you only need one chain, install the corresponding extra: ```bash -pip3.11 install tronpy eth_account +pip install 'bankofai-agent-wallet[tron]' # TRON only +pip install 'bankofai-agent-wallet[evm]' # EVM only ``` Verify the installation: ```bash -python3.11 -c "import agent_wallet; print('Installation successful')" +python3 -c "import agent_wallet; print('Installation successful')" ``` @@ -138,9 +137,9 @@ python3.11 -c "import agent_wallet; print('Installation successful')" ## Step 2: Configure a Mode -Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. The SDK provides two modes — local mode is best for long-term management of multiple wallets, while static mode is best for directly injecting a private key. `resolveWalletProvider()` automatically detects the environment variables that are set and selects the corresponding mode, with no additional logic needed in your code. +Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. The SDK provides two modes — **local mode** (encrypted keys on disk, `local_secure`) is best for long-term management of multiple wallets, while **static mode** (env-based) is best for directly injecting a private key. `resolveWalletProvider()` automatically detects the environment variables that are set and selects the corresponding mode, with no additional logic needed in your code. -### Local Mode +### Local Mode (`local_secure`) Private keys are stored encrypted on disk. Best for managing multiple wallets or persisting keys long-term. You must initialize first via the CLI (`agent-wallet start`), then set the master password: @@ -163,7 +162,7 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ::: -### Static Mode +### Static Mode (env-based) Provide a private key or mnemonic directly via environment variable — no local key file required. Best for CI/CD or one-off scripts. The `network` parameter must be specified when using static mode: @@ -391,20 +390,21 @@ print("Signature:", sig) ### Manage Multiple Wallets -If you need to manage multiple wallets in code, use `LocalWalletProvider` directly: +If you need to manage multiple wallets in code, use `resolveWalletProvider()` in local mode. The provider reads the wallet configuration and lets you switch the active wallet: ```typescript -import { LocalWalletProvider } from "@bankofai/agent-wallet"; +import { resolveWalletProvider } from "@bankofai/agent-wallet"; -const provider = new LocalWalletProvider("~/.agent-wallet", "Abc12345!"); +// Local mode: AGENT_WALLET_PASSWORD must be set +const provider = resolveWalletProvider({ network: "tron:nile" }); // List all wallets const wallets = await provider.listWallets(); for (const w of wallets) { - console.log(`${w.id} (${w.type}): ${w.address}`); + console.log(`${w.id} (${w.type})`); } // Switch the active wallet @@ -425,7 +425,7 @@ os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" from agent_wallet import resolve_wallet_provider -provider = resolve_wallet_provider() +provider = resolve_wallet_provider(network="tron:nile") async def main(): wallet = await provider.get_active_wallet() diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index d04a3b0e..8e369cee 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -1,164 +1,120 @@ # 常见问题 +先回答你最关心的三件事，然后是日常使用中会碰到的细节。 + --- -## 关于 Agent-wallet 的定位 +## 💰 AI 会不会把我的钱全转走？ -### Agent-wallet 是什么？它能做什么？ +这是最常被问到的问题，答案是：**就算 AI 被入侵了，你的核心资产也是安全的。** -Agent-wallet 是一个**仅用于签名的 SDK**。它做两件事：将私钥加密存储在本地，以及对消息、交易、EIP-712 结构化数据进行本地签名。 +我们强烈建议你给 AI 单独创建一个钱包，只充入它实际需要的小额资金（比如当 Gas 费的额度）。你的主钱包、大额资产永远不碰。这样就算最坏情况发生，损失也只是那个小额钱包里的余额。 -它不做：连接 RPC、查链上数据、构建交易、广播交易、自主发起转账或支付。 +```bash +# 给 AI 单独建一个小额钱包 +agent-wallet add +``` -这种职责划分是有意为之的——签名是一个高度敏感的操作，应该尽量简单、可审计、无外部依赖。SDK 越专注，攻击面就越小。 +而且你的钱包文件是高强度加密的。就算黑客拿到了文件，没有主密码就是一堆乱码——暴力破解在经济上毫无意义。 -### 它和普通区块链钱包有什么区别？ +--- -普通钱包（如 MetaMask、TronLink）是面向人类用户的，通常包含余额显示、转账界面、DApp 连接等完整功能，每次操作都需要人工确认。 +## 🔌 断网了，AI 还能签名吗？ -Agent-wallet 是面向程序的。它只暴露一个签名接口，没有界面，没有网络功能，也不需要人工介入。调用者（MCP Server、工作流代码等）负责构建交易，Agent-wallet 只负责签名，然后把签名结果返回给调用者去广播。 +能。**Agent-wallet 所有签名操作 100% 在你本地机器上完成。** -### 那转账和支付怎么实现？ +从设计上就没有任何网络依赖——不调 RPC、不连云服务、不请求任何远端 API。你的私钥从始至终不碰网络。 -Agent-wallet 本身不实现转账。完整的转账流程需要三个步骤： +断网只会影响交易的构建和广播（那是 MCP Server 的事），签名本身完全离线。 -1. **构建交易** — 调用者通过 TronGrid、Infura 等 RPC 接口构建未签名的交易对象 -2. **签名** — 调用者把未签名交易传给 Agent-wallet，SDK 在本地签名并返回签名结果 -3. **广播** — 调用者把签名后的交易提交给 RPC 广播到链上 +--- -Agent-wallet 只参与第 2 步。 +## 🔑 密码忘了怎么办？ -### CLI 和 SDK 有什么区别，我该用哪个？ +**找不回来。** -两者底层能力相同，使用场景不同： +主密码是解密所有私钥的唯一凭证。我们不保存它——不在磁盘上、不在内存里（签完名就清除）。没有"忘记密码"功能，没有后门。 -- **CLI** 适合人工操作——初始化钱包、管理密钥、手动测试签名。日常的密钥管理工作都通过 CLI 完成。 -- **SDK** 适合程序集成——在你自己的代码里调用签名接口，比如在 MCP Server 内部、或自动化脚本中使用。 +如果你忘了密码： +- 有私钥或助记词的其他备份？运行 `agent-wallet reset`，重新初始化，重新导入 +- 什么备份都没有？那个钱包的访问权限就永久丢失了 -大多数用户会同时用到两者：用 CLI 初始化和管理钱包，用 SDK 在代码里调用签名。 +**所以请现在就做这件事**：打开密码管理器，把主密码存进去。认真的。 --- -## 本地模式和静态模式 +## 日常使用 -### 什么时候用本地模式，什么时候用静态模式？ +### Agent-wallet 到底是什么？ -**本地模式**（设置 `AGENT_WALLET_PASSWORD`）适合： -- 需要管理多个钱包 -- 希望密钥长期加密存储在本地 -- 需要通过 CLI 交互式操作钱包 +一个纯本地的加密签名工具。它做两件事：1）把你的私钥加密存储；2）在本地完成签名。不联网、不用云，本身没有独立界面——而是作为隐形的安全中枢，完美接入 OpenClaw 等 AI 前端工具中。 -**静态模式**（设置 `AGENT_WALLET_PRIVATE_KEY` 或 `AGENT_WALLET_MNEMONIC`）适合： -- 只需要一个钱包 -- CI/CD 或临时脚本场景 -- 私钥已由外部系统管理，不想再加一层本地存储 +### CLI 和 SDK 什么区别？用哪个？ -### 两种模式可以混用吗？ +- **CLI** — 命令行工具，用来建钱包、管密钥、手动测试签名 +- **SDK** — TypeScript / Python 库，用来在自己的代码里调用签名 + +大多数人不需要 SDK。如果你是用 OpenClaw 和 MCP Server 的普通用户，CLI 建完钱包、配好环境变量就够了。SDK 是给自己写代理的开发者用的。 + +--- -不可以同时用，但可以随时切换。`AGENT_WALLET_PASSWORD` 的优先级高于私钥/助记词。`AGENT_WALLET_PRIVATE_KEY` 和 `AGENT_WALLET_MNEMONIC` 不能同时设置。 +## 钱包类型 -### network 参数怎么填？ +### `local_secure` 和 `raw_secret` 有什么区别？ -`network` 参数决定使用哪种链的适配器： +| | `local_secure` | `raw_secret` | +| :--- | :---: | :---: | +| **密钥加密** | ✅ 高强度加密 | ❌ 明文 | +| **代理读了文件** | ✅ 拿不到密钥 | ❌ 直接被盗 | +| **适合场景** | ✅ 所有场景 | ⚠️ 完全隔离的开发环境 | + +**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理。 + +### `network` 参数怎么填？ | 值 | 说明 | | :--- | :--- | +| `tron:mainnet` | TRON 主网 | +| `tron:nile` | TRON Nile 测试网 | +| `tron:shasta` | TRON Shasta 测试网 | | `eip155:1` | Ethereum 主网 | | `eip155:56` | BSC 主网 | | `eip155:137` | Polygon 主网 | | `eip155:8453` | Base 主网 | | `eip155:42161` | Arbitrum 主网 | -| `tron:mainnet` | TRON 主网 | -| `tron:nile` | TRON Nile 测试网 | -| `tron:shasta` | TRON Shasta 测试网 | - -只要前缀是 `eip155:` 就走 EVM 适配器，前缀是 `tron:` 就走 TRON 适配器。链 ID 本身不影响签名逻辑，只是用于路由到正确的适配器。 --- ## 安全性 -### 私钥以什么方式存储？ - -本地模式下，私钥以 **Keystore V3** 格式加密存储，使用 scrypt（N=262144, r=8, p=1）+ AES-128-CTR + keccak256 MAC 组合。这是与 Ethereum 生态广泛兼容的加密标准，scrypt 的计算成本极高，有效抵抗暴力破解。 - -主密码本身从不存储。`master.json` 只保存一个加密的哨兵值，用于验证密码是否正确，而不是密码本身。 - -### 密钥会发送到网络吗？ - -不会。所有签名操作都是纯本地计算，Agent-wallet 没有任何网络调用。私钥永远不离开你的机器。 - -### 我应该怎么保护主密码？ - -- 通过环境变量（`AGENT_WALLET_PASSWORD`）传入，而不是写在代码里 -- 不要把包含密码的 `.env` 文件提交到 Git，将其加入 `.gitignore` -- 建议使用密码管理器（如 1Password、Bitwarden）保存主密码 +### 密钥会通过网络发出去吗？ -### 忘记主密码了怎么办？ +永远不会。Agent-wallet 不发起任何网络请求。零 RPC 调用、零云服务。你的私钥永远不离开你的机器。 -主密码无法找回。Agent-wallet 不存储主密码，也没有任何找回机制。 +### 主密码怎么保管才安全？ -如果你忘记了主密码： -- 如果你有私钥的其他备份（如助记词），可以运行 `agent-wallet reset` 清空本地数据，然后重新初始化并导入私钥 -- 如果没有其他备份，加密的私钥文件将无法解密，对应的钱包访问权限会永久丢失 - -这也是为什么强烈建议在创建钱包时**单独备份私钥或助记词**，不要只依赖 Agent-wallet 的本地存储。 - -### 给 AI 代理使用的密钥安全吗？ - -取决于如何配置。推荐做法： - -- 为代理创建一个专用钱包，不要使用你的个人主钱包 -- 只向该钱包充入代理运行所需的小额资金 -- 通过环境变量传入私钥或密码，不要硬编码在代码里 - -这样即使代理行为异常，损失也被限制在预充的范围内。 - ---- - -## 跨语言兼容性 - -### Python 和 TypeScript 的密钥文件可以互换吗？ - -可以。两个实现使用完全相同的 Keystore V3 格式。Python 创建的密钥文件可以直接被 TypeScript 读取，反之亦然。这意味着你可以用 CLI（TypeScript 版）初始化钱包，然后在 Python 代码里直接使用同一套密钥。 - -### 两个语言版本签名结果一样吗？ - -是的。同一个私钥对同一段数据签名，Python 和 TypeScript 产生的签名结果完全一致。地址派生规则、EIP-712 编码逻辑也完全相同。 - -### 两个语言版本的 API 有什么差异？ - -接口设计完全对应，主要差异是命名风格：TypeScript 使用驼峰命名（`signMessage`、`getActiveWallet`），Python 使用下划线命名（`sign_message`、`get_active_wallet`）。除此之外行为一致。 +- ✅ 用密码管理器（1Password、Bitwarden） +- ✅ 通过环境变量 `AGENT_WALLET_PASSWORD` 传入 +- ❌ 不要写在代码里 +- ❌ 不要提交含密码的 `.env` 到 git --- -## 与其他组件的关系 - -### Agent-wallet 和 MCP Server 是什么关系？ +## 跨语言 -MCP Server（如 TRON MCP Server、BSC MCP Server）为 AI 代理提供链上操作工具，比如查询余额、构建交易。当 MCP Server 需要签名时，它调用 Agent-wallet 来完成签名，然后自己负责广播。 +### Python 和 TypeScript 的密钥文件通用吗？ -Agent-wallet 是 MCP Server 的签名后端，MCP Server 不直接接触私钥。 - -### Agent-wallet 和 x402 协议是什么关系？ - -x402 是一个 HTTP 支付协议，当代理需要完成一笔 x402 支付时，需要对 PaymentPermit 结构化数据（EIP-712 格式）进行签名。这个签名由 Agent-wallet 提供。 - -x402 SDK 负责构建支付请求和处理协议流程，Agent-wallet 负责签名。两者分工明确，Agent-wallet 本身不了解也不关心 x402 的业务逻辑。 - ---- +通用。两个实现使用完全相同的加密格式。CLI 建的钱包，Python SDK 直接能用，反过来也一样。 -## 支持哪些链 +### 两种语言的签名结果一样吗？ -| 链类型 | 网络标识符 | 具体网络 | -| :--- | :--- | :--- | -| EVM | `eip155:*` | Ethereum、BSC、Polygon、Base、Arbitrum 以及任何 EVM 兼容链 | -| TRON | `tron:*` | TRON 主网、Nile 测试网、Shasta 测试网 | +完全一样。同一个私钥 + 同一份数据 = 同一个签名。 --- ## 下一步 -- 初始化钱包并开始签名 → [CLI 快速开始](./QuickStart.md) -- 在代码中集成签名能力 → [SDK 快速开始](./SDKQuickStart.md) -- 了解整体设计 → [简介](./Intro.md) +- 动手配置全套环境 → [CLI 快速开始](./QuickStart.md) +- 在代码里集成签名 → [SDK 快速开始](./SDKQuickStart.md) +- 看完整的转账示例 → [完整示例](./FullExample.md) +- 了解 OpenClaw Extension → [OpenClaw 简介](../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md index 4e66f74e..43fa5d1d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md @@ -1,37 +1,39 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# 完整使用示例 +# 完整示例 -Agent-wallet 只负责签名，构建交易和广播由调用者完成。本页通过完整的代码示例，演示如何将这三个步骤串联起来——包括 TRON 转账、EVM 转账，以及 x402 PaymentPermit 签名场景。 +签名会了，现在把所有环节串起来——构建交易、用 Agent-wallet 签名、广播上链。 -每个示例均提供 TypeScript 和 Python 两个版本，可通过标签切换。 +本页走完三个真实场景的完整流程：在 TRON 发送 TRX、在 BSC 发送 BNB、签名 x402 支付许可。每个示例都可以直接运行——复制代码、填入你的地址，就能跑。 + +文档提供 TypeScript 和 Python 两个版本，点击标签页切换。 --- -## 准备工作 +## 前置条件 -在运行以下示例前，请确保： +运行以下任何示例之前，确保已经完成： -1. 已安装 Agent-wallet SDK（参见 [SDK 快速开始](./SDKQuickStart.md)） -2. 已通过 CLI 初始化本地钱包，或已配置静态模式环境变量 -3. 已设置 `AGENT_WALLET_PASSWORD`（本地模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） +1. 安装 Agent-wallet SDK（详见 [SDK 快速开始](./SDKQuickStart.md)） +2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量 +3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） --- ## TRON 转账 -**适用场景**：AI 代理需要在 TRON 链上发起一笔 TRX 转账，例如支付 API 调用费用、向另一个地址归集资金，或在自动化任务完成后结算报酬。 +**使用场景**：AI 代理需要在 TRON 网络发起 TRX 转账——比如支付 API 调用费用、归集资金，或完成自动化任务后结算报酬。 -**流程说明**： +**工作原理**： -TRON 的转账不能由客户端直接凭空构造，必须先调用 TronGrid 的 `createtransaction` 接口，由链上节点生成一个包含 `txID` 和 `raw_data` 的未签名交易对象。拿到这个对象后，交给 Agent-wallet 在本地完成签名——签名过程完全离线，私钥不离开本机。最后把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口广播上链。 +TRON 交易不能由客户端直接从零构建。流程必须从调用 TronGrid 的 `createtransaction` 接口开始——该接口返回一个包含 `txID` 和 `raw_data` 的未签名交易对象，由网络节点生成。然后把这个对象传给 Agent-wallet 进行本地签名——签名过程完全离线，私钥不会离开本机。最后，把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口，发布到链上。 ``` TronGrid（构建）→ Agent-wallet（签名）→ TronGrid（广播） ``` -Agent-wallet 只参与中间的签名步骤，不依赖任何 RPC 连接，也不感知交易的业务含义。 +Agent-wallet 只参与中间的签名步骤，不需要 RPC 连接，也不感知交易的业务含义。 ### 安装依赖 @@ -45,14 +47,14 @@ npm install @bankofai/agent-wallet axios -本示例用到了 `aiohttp`（第三方 HTTP 库）和 `asyncio`（Python 标准库，无需安装）： +本示例使用 `aiohttp`（第三方 HTTP 库）和 `asyncio`（Python 标准库，无需安装）： ```bash pip install aiohttp ``` -:::caution 如果运行时提示标准库模块缺失 -如果导入 `asyncio` 等标准库时报错，通常是用 pyenv 构建 Python 时缺少系统依赖所致。请先安装以下包，再重新执行 `pyenv install 3.11`： +:::caution 如果出现标准库模块缺失的报错 +如果 `asyncio` 等标准库模块导入失败，通常是因为 pyenv 从源码编译 Python 时缺少系统依赖。先安装以下包，再重新运行 `pyenv install 3.11`： ```bash # CentOS / RHEL / Amazon Linux @@ -77,18 +79,18 @@ sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqli import { resolveWalletProvider } from "@bankofai/agent-wallet"; import axios from "axios"; -const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网, 主网改为 https://api.trongrid.io +const TRONGRID_API = "https://nile.trongrid.io"; // Nile 测试网；主网改为 https://api.trongrid.io async function transferTRX( fromAddress: string, toAddress: string, amountSun: number // 1 TRX = 1_000_000 SUN ) { - // 第一步: 初始化 Agent-wallet + // 第一步：初始化 Agent-wallet const provider = resolveWalletProvider({ network: "tron:nile" }); const wallet = await provider.getActiveWallet(); - // 第二步: 通过 TronGrid 构建未签名交易 + // 第二步：通过 TronGrid 构建未签名交易 const { data: unsignedTx } = await axios.post( `${TRONGRID_API}/wallet/createtransaction`, { @@ -100,34 +102,34 @@ async function transferTRX( ); if (!unsignedTx.txID) { - throw new Error("构建交易失败: " + JSON.stringify(unsignedTx)); + throw new Error("构建交易失败：" + JSON.stringify(unsignedTx)); } - console.log("未签名交易 txID:", unsignedTx.txID); + console.log("未签名 txID：", unsignedTx.txID); - // 第三步: Agent-wallet 本地签名 + // 第三步：用 Agent-wallet 本地签名 const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); - console.log("签名完成, signature:", signedTx.signature); + console.log("已签名，signature：", signedTx.signature); - // 第四步: 通过 TronGrid 广播 + // 第四步：通过 TronGrid 广播 const { data: broadcastResult } = await axios.post( `${TRONGRID_API}/wallet/broadcasttransaction`, signedTx ); if (broadcastResult.result) { - console.log("广播成功! txID:", signedTx.txID); + console.log("广播成功！txID：", signedTx.txID); } else { - console.error("广播失败: ", broadcastResult); + console.error("广播失败：", broadcastResult); } return signedTx.txID; } -// 使用示例 +// 示例调用 transferTRX( - "YOUR_TRON_ADDRESS", // 替换为你的钱包地址 - "RECIPIENT_TRON_ADDRESS", // 替换为接收方地址 + "你的 TRON 地址", // 替换成你的钱包地址 + "收款方 TRON 地址", // 替换成收款方地址 1_000_000 // 1 TRX ).catch(console.error); ``` @@ -141,19 +143,19 @@ import json import aiohttp from agent_wallet import resolve_wallet_provider -TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网, 主网改为 https://api.trongrid.io +TRONGRID_API = "https://nile.trongrid.io" # Nile 测试网；主网改为 https://api.trongrid.io async def transfer_trx( from_address: str, to_address: str, amount_sun: int, # 1 TRX = 1_000_000 SUN ): - # 第一步: 初始化 Agent-wallet + # 第一步：初始化 Agent-wallet provider = resolve_wallet_provider(network="tron:nile") wallet = await provider.get_active_wallet() async with aiohttp.ClientSession() as session: - # 第二步: 通过 TronGrid 构建未签名交易 + # 第二步：通过 TronGrid 构建未签名交易 async with session.post( f"{TRONGRID_API}/wallet/createtransaction", json={ @@ -165,18 +167,16 @@ async def transfer_trx( ) as resp: unsigned_tx = await resp.json() - print("TronGrid 返回原始响应:", json.dumps(unsigned_tx, indent=2, ensure_ascii=False)) - if "txID" not in unsigned_tx: - raise ValueError(f"构建交易失败: {unsigned_tx}") + raise ValueError(f"构建交易失败：{unsigned_tx}") - print("未签名交易 txID:", unsigned_tx["txID"]) + print("未签名 txID：", unsigned_tx["txID"]) - # 第三步: Agent-wallet 本地签名 + # 第三步：用 Agent-wallet 本地签名 signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) - print("签名完成, signature:", signed_tx["signature"]) + print("已签名，signature：", signed_tx["signature"]) - # 第四步: 通过 TronGrid 广播 + # 第四步：通过 TronGrid 广播 async with session.post( f"{TRONGRID_API}/wallet/broadcasttransaction", json=signed_tx, @@ -184,18 +184,18 @@ async def transfer_trx( broadcast_result = await resp.json() if broadcast_result.get("result"): - print("广播成功! txID:", signed_tx["txID"]) + print("广播成功！txID：", signed_tx["txID"]) else: - print("广播失败: ", broadcast_result) + print("广播失败：", broadcast_result) return signed_tx["txID"] -# 使用示例 +# 示例调用 asyncio.run( transfer_trx( - from_address="YOUR_TRON_ADDRESS", # 替换为你的钱包地址 - to_address="RECIPIENT_TRON_ADDRESS", # 替换为接收方地址 - amount_sun=1_000_000, # 1 TRX + from_address="你的 TRON 地址", # 替换成你的钱包地址 + to_address="收款方 TRON 地址", # 替换成收款方地址 + amount_sun=1_000_000, # 1 TRX ) ) ``` @@ -203,35 +203,35 @@ asyncio.run( -:::caution 注意 -- 测试时请使用 Nile 测试网，可在 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取测试币 -- 主网操作请将 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet` +:::caution 注意事项 +- 测试请使用 Nile 测试网，测试代币从 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取。 +- 切换主网：把 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet`。 ::: :::tip `visible: true` 与地址格式 -代码中向 TronGrid 传入了 `visible: true` 参数。该参数会影响 API 对地址格式的要求： +代码传了 `visible: true` 给 TronGrid，这个参数影响 API 期望的地址格式： -- **`visible: true`**：API 期望地址为 **Base58 格式**（即普通 TRON 地址，如 `TNmo...`） -- **`visible: false`（或不传）**：API 期望地址为 **十六进制格式**（如 `41b9f...`） +- **`visible: true`**：API 接受 **Base58 格式**（标准的 TRON 可读地址，例如 `TNmo...`） +- **`visible: false`（或不传）**：API 接受 **十六进制格式**（例如 `41b9f...`） -示例代码使用的是 Base58 格式地址，保持与 `visible: true` 一致即可。 +示例使用 Base58 地址，与 `visible: true` 保持一致。 ::: --- ## EVM 转账（BSC / Ethereum） -**适用场景**：AI 代理需要在 BSC、Ethereum 或其他 EVM 兼容链上发起原生代币转账，例如支付 Gas、向合约转账触发业务逻辑，或在任务执行后完成链上结算。 +**使用场景**：AI 代理需要在 BSC、Ethereum 或其他 EVM 兼容链上发起原生代币转账——比如支付 Gas、向合约转账触发业务逻辑，或完成链上任务后结算。 -**流程说明**： +**工作原理**： -EVM 交易需要调用方自行构造交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，不依赖中心化 API 生成。构建好未签名交易后，交给 Agent-wallet 在本地签名，返回一段十六进制编码的已签名交易数据，再通过 `sendRawTransaction` 广播到链上。 +EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，没有集中式 API 帮你生成。未签名交易构建完成后，传给 Agent-wallet 进行本地签名，返回十六进制编码的已签名交易，最后通过 `sendRawTransaction` 广播。 ``` -RPC 查 nonce/gas（构建）→ Agent-wallet（签名）→ RPC sendRawTransaction（广播） +RPC 查询 nonce/gas（构建）→ Agent-wallet（签名）→ RPC sendRawTransaction（广播） ``` -示例使用 BSC 测试网，但切换到 Ethereum、Polygon、Base 等链只需更改 `RPC_URL` 和 `CHAIN_ID` 两个参数，Agent-wallet 的调用代码完全不变。 +示例使用 BSC 测试网，切换到 Ethereum、Polygon、Base 或其他 EVM 链只需改 `RPC_URL` 和 `CHAIN_ID`——Agent-wallet 的调用代码一行不变。 ### 安装依赖 @@ -261,25 +261,25 @@ pip install web3 import { resolveWalletProvider } from "@bankofai/agent-wallet"; import { ethers } from "ethers"; -// BSC 测试网 (Testnet) +// BSC 测试网 const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"; -const CHAIN_ID = 97; // BSC 测试网, 主网为 56 +const CHAIN_ID = 97; // BSC 测试网；主网用 56 async function transferBNB( toAddress: string, - amountEther: string // 如 "0.001" + amountEther: string // 例如 "0.001" ) { - // 第一步: 初始化 Agent-wallet + // 第一步：初始化 Agent-wallet const provider = resolveWalletProvider({ network: `eip155:${CHAIN_ID}` }); const wallet = await provider.getActiveWallet(); const fromAddress = await wallet.getAddress(); - // 第二步: 通过 RPC 查询 nonce 和 gas 信息 + // 第二步：通过 RPC 查询 nonce 和 gas 信息 const rpcProvider = new ethers.JsonRpcProvider(RPC_URL); const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); const feeData = await rpcProvider.getFeeData(); - // 第三步: 构建未签名交易 + // 第三步：构建未签名交易 const unsignedTx = { to: toAddress, value: ethers.parseEther(amountEther), @@ -291,27 +291,27 @@ async function transferBNB( type: 2, // EIP-1559 }; - console.log("构建交易完成, nonce:", nonce); + console.log("交易已构建，nonce：", nonce); - // 第四步: Agent-wallet 本地签名 + // 第四步：用 Agent-wallet 本地签名 const signedTxHex = await wallet.signTransaction(unsignedTx); - console.log("签名完成"); + console.log("已签名"); - // 第五步: 广播 + // 第五步：广播 const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); - console.log("广播成功! txHash:", txResponse.hash); + console.log("广播成功！txHash：", txResponse.hash); - // 等待确认 (可选) + // 等待确认（可选） const receipt = await txResponse.wait(); - console.log("交易已确认, 区块号:", receipt?.blockNumber); + console.log("已在区块中确认：", receipt?.blockNumber); return txResponse.hash; } -// 使用示例 +// 示例调用 transferBNB( - "0xYOUR_RECIPIENT_ADDRESS", // 替换为接收方地址 - "0.001" // 发送 0.001 BNB + "0x收款方地址", // 替换成收款方地址 + "0.001" // 发送 0.001 BNB ).catch(console.error); ``` @@ -323,24 +323,24 @@ import asyncio from agent_wallet import resolve_wallet_provider from web3 import AsyncWeb3 -# BSC 测试网 (Testnet) +# BSC 测试网 RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545" -CHAIN_ID = 97 # BSC 测试网, 主网为 56 +CHAIN_ID = 97 # BSC 测试网；主网用 56 async def transfer_bnb(to_address: str, amount_ether: str): - # 第一步: 初始化 Agent-wallet + # 第一步：初始化 Agent-wallet provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}") wallet = await provider.get_active_wallet() from_address = await wallet.get_address() - # 第二步: 通过 RPC 查询 nonce 和 gas 信息 + # 第二步：通过 RPC 查询 nonce 和 gas 信息 w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL)) nonce = await w3.eth.get_transaction_count(from_address, "latest") fee_data = await w3.eth.fee_history(1, "latest", [50]) base_fee = fee_data["baseFeePerGas"][-1] priority_fee = await w3.eth.max_priority_fee - # 第三步: 构建未签名交易 + # 第三步：构建未签名交易 unsigned_tx = { "to": to_address, "value": w3.to_wei(amount_ether, "ether"), @@ -352,27 +352,27 @@ async def transfer_bnb(to_address: str, amount_ether: str): "type": 2, # EIP-1559 } - print("构建交易完成, nonce:", nonce) + print("交易已构建，nonce：", nonce) - # 第四步: Agent-wallet 本地签名 + # 第四步：用 Agent-wallet 本地签名 signed_tx_hex = await wallet.sign_transaction(unsigned_tx) - print("签名完成") + print("已签名") - # 第五步: 广播 + # 第五步：广播 tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) - print("广播成功! txHash:", tx_hash.hex()) + print("广播成功！txHash：", tx_hash.hex()) - # 等待确认 (可选) + # 等待确认（可选） receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) - print("交易已确认, 区块号:", receipt["blockNumber"]) + print("已在区块中确认：", receipt["blockNumber"]) return tx_hash.hex() -# 使用示例 +# 示例调用 asyncio.run( transfer_bnb( - to_address="0xYOUR_RECIPIENT_ADDRESS", # 替换为接收方地址 - amount_ether="0.001", # 发送 0.001 BNB + to_address="0x收款方地址", # 替换成收款方地址 + amount_ether="0.001", ) ) ``` @@ -380,26 +380,26 @@ asyncio.run( -:::caution 注意 -- 测试时请使用 BSC 测试网（chainId=97），可在 [BSC Faucet](https://testnet.binance.org/faucet-smart) 领取测试币 -- 主网操作请将 `RPC_URL` 改为主网 RPC，`CHAIN_ID` 改为 `56`，`network` 改为 `eip155:56` +:::caution 注意事项 +- 测试请使用 BSC 测试网（chainId=97），测试代币从 [BSC Faucet](https://testnet.binance.org/faucet-smart) 领取。 +- 切换主网：把 `RPC_URL` 改为主网 RPC 地址，`CHAIN_ID` 改为 `56`，`network` 改为 `eip155:56`。 ::: --- -## x402 PaymentPermit 签名 +## x402 支付许可签名 -**适用场景**：AI 代理正在访问一个受 x402 协议保护的付费 API——比如获取实时数据、调用 AI 推理服务，或触发某个链上操作。服务端返回 HTTP 402 状态码，要求代理先完成链上支付授权，才能继续获取内容。 +**使用场景**：AI 代理正在访问受 x402 协议保护的付费 API——比如获取实时数据、调用 AI 推理服务，或触发链上操作。服务器返回 HTTP 402，要求代理在获取内容之前提供支付授权。 -**流程说明**： +**工作原理**： -x402 协议的支付不是直接发起转账，而是采用"先签名授权、后验证放行"的方式。代理需要对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，签名结果作为支付凭证随请求头一起发送给服务端。服务端验证签名合法后才返回内容，整个过程不需要代理等待链上确认，延迟极低。 +x402 支付不是直接发一笔转账，而是"先签名、验证后放行"的模型。代理对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，把得到的签名随请求一起发给服务器作为支付凭证。服务器验证签名有效后才返回内容。代理不需要等待链上确认——延迟极低。 ``` -服务端返回 402 → 代理构建 PaymentPermit → Agent-wallet 签名 → 携带签名重发请求 → 服务端验证放行 +服务器返回 402 → 代理构建 PaymentPermit → Agent-wallet 签名 → 携带签名重发请求 → 服务器验证通过并响应 ``` -PaymentPermit 数据由 x402 SDK 根据服务端返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面展示的是底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。 +PaymentPermit 数据由 x402 SDK 根据服务器返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面的示例展示了底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。 @@ -407,29 +407,19 @@ PaymentPermit 数据由 x402 SDK 根据服务端返回的支付参数自动构 ```typescript import { resolveWalletProvider } from "@bankofai/agent-wallet"; -async function signPaymentPermit( - paymentPayload: { - x402Version: number; - scheme: string; - network: string; - payload: { - signature: string; - authorization: { - from: string; - to: string; - value: string; - validAfter: string; - validBefore: string; - nonce: string; - }; - }; - } -) { - // 初始化 Agent-wallet (EVM 钱包, 网络与 x402 支付网络对应) +async function signPaymentPermit(authorization: { + from: string; + to: string; + value: string; + validAfter: string; + validBefore: string; + nonce: string; +}) { + // 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配） const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base 主网 const wallet = await provider.getActiveWallet(); - // 构建 EIP-712 typed data (与 x402 协议规范一致) + // 构建 EIP-712 结构化数据（与 x402 协议规范对齐） const typedData = { types: { EIP712Domain: [ @@ -454,12 +444,12 @@ async function signPaymentPermit( chainId: 8453, verifyingContract: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC }, - message: paymentPayload.payload.authorization, + message: authorization, }; - // Agent-wallet 本地签名 + // 用 Agent-wallet 本地签名 const signature = await wallet.signTypedData(typedData); - console.log("PaymentPermit 签名:", signature); + console.log("PaymentPermit 签名：", signature); return signature; } @@ -472,11 +462,11 @@ async function signPaymentPermit( from agent_wallet import resolve_wallet_provider async def sign_payment_permit(authorization: dict) -> str: - # 初始化 Agent-wallet (EVM 钱包, 网络与 x402 支付网络对应) + # 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配） provider = resolve_wallet_provider(network="eip155:8453") # Base 主网 wallet = await provider.get_active_wallet() - # 构建 EIP-712 typed data (与 x402 协议规范一致) + # 构建 EIP-712 结构化数据（与 x402 协议规范对齐） typed_data = { "types": { "EIP712Domain": [ @@ -504,9 +494,9 @@ async def sign_payment_permit(authorization: dict) -> str: "message": authorization, } - # Agent-wallet 本地签名 + # 用 Agent-wallet 本地签名 signature = await wallet.sign_typed_data(typed_data) - print("PaymentPermit 签名:", signature) + print("PaymentPermit 签名：", signature) return signature ``` @@ -515,13 +505,13 @@ async def sign_payment_permit(authorization: dict) -> str: :::tip -x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不需要手动编写上述代码。这里展示的是底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。 +x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不需要手写这段代码。上面的示例展示了底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。 ::: --- ## 下一步 -- 回顾签名接口的完整参数说明 → [SDK 快速开始](./SDKQuickStart.md) -- 了解 x402 协议与 Agent-wallet 的配合方式 → [x402 简介](../../x402/index.md) +- 查看完整签名 API 参考 → [SDK 快速开始](./SDKQuickStart.md) +- 了解 x402 与 Agent-wallet 如何配合 → [x402 简介](../../x402/index.md) - 查看常见问题 → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index 516211f5..aba7c8ba 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -1,108 +1,153 @@ -# 简介 +# 简介 +## 享受 AI Agent 红利，告别私钥泄露焦虑 -AI 代理正在越来越多地参与链上操作：支付 API 费用、签署授权、执行转账。但这件事有一个绕不开的问题——私钥。 +### 你的私钥，距离被盗可能只差一次文件读取 -把私钥硬编码在代码里不安全，托管给云端服务意味着失去控制权，每次操作都弹出人工确认又失去了"自主"的意义。 +你想让 AI 代理帮你自动完成链上操作——刷空投、做兑换、付 Gas 费、定时转账。要做这些事，AI 需要一把"钥匙"（私钥）来替你签名。 -AI 代理需要一种方式：**让密钥安全地留在本地，让签名在本地完成，同时对外只暴露一个干净的接口**。 +于是你把私钥放进了 `.env` 文件里。 -这就是 **Agent-wallet** 要解决的问题。 +**这就好比把银行卡和密码贴在脑门上，走进了一间挤满陌生人的办公室。** + +那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读你的 `.env` 文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个进程拿走。 --- -## Agent-wallet 是什么 +### 这不是吓你，它正在发生 -**Agent-wallet** 是一个**仅用于签名的 SDK**，让 AI 代理（MCP 服务器、自主工作流等）能安全地管理和使用区块链密钥。 +- **依赖链投毒。** 你装了一个好用的 MCP Server。三个月后，它 200 个 npm 依赖中的某一个被注入了恶意代码——悄悄扫描所有 `.env` 和 `*.json` 文件，找到长得像私钥的字符串就发走。你完全不知道发生了什么，等你发现的时候，钱包已经空了。 -:::tip 它做两件事 +- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。`.env` 在目录里。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 -- **密钥存储** — 用 Keystore V3 加密方式将私钥安全保存在本地 -- **本地签名** — 对消息、交易、EIP-712 结构化数据进行签名，全程无网络调用 +- **Git 的"完美记忆"。** 你在开发时把私钥写进了代码，后来删了。但三周前你 commit 过一次。`git log -p` 里还有。仓库只要上过一次 GitHub，哪怕就 30 秒，自动化爬虫已经找到了。 -::: +- **云钱包：换了个地方暴露。** "用云钱包服务不就安全了吗？" ——你的密钥确实不在本地了，但现在在别人的服务器上。他们被黑 = 你被黑，他们宕机 = 你的代理停摆。你只是把风险从左手换到了右手。 -:::caution 它不做的事 +这些方式的共同点：**你的私钥总是在某个地方裸奔**——磁盘上、日志里、git 历史里、或者别人的基础设施上。 -- 不连接 RPC，不查链上数据 -- 不构建交易（调用者负责构建） -- 不广播交易（调用者负责广播） -- 不自主发起转账或支付 +--- -::: +## 破局之道：Agent-wallet -这种职责分离让 Agent-wallet 保持轻量，且不依赖任何特定的 RPC 服务商。 +Agent-wallet 是一个"断网也安全"的**本地加密保险箱**。 ---- +它只做一件事：**用行业顶级的加密算法把你脆弱的明文私钥锁死在你的电脑里，并在本地完成授权。** -## 为什么选择 Agent-wallet +就算有人拿到了你的钱包文件，没有主密码，它就是一堆垃圾数据。暴力破解需要的时间比宇宙年龄还长——经济上毫无意义。同时，所有签名操作在你本地完成，不联网、不调 API、不经过任何第三方。 -### 专为 AI 代理设计 +**一句话：文件随便偷，偷了打不开；签名纯本地，网络抓不到。** -传统钱包是给人用的——有界面、需要手动确认。Agent-wallet 的接口设计面向程序，通过环境变量配置，通过 SDK 调用，天然适合在 MCP Server 或自动化工作流中内嵌。 +--- -### 私钥永不离开本地 +## 和"老办法"对比一下 -所有签名都在本地完成，没有任何网络请求。私钥不会被发送到任何服务器，不依赖任何云端 HSM 或托管服务，你对密钥有完全的控制权。 +| | 明文密钥 / `.env` | 云钱包 | Agent-wallet | +| :--- | :---: | :---: | :---: | +| **代理读了你的密钥文件** | ❌ 直接被盗 | — 密钥在远端 | ✅ 加密文件——没密码打不开 | +| **密钥归谁** | ⚠️ 谁能读文件谁就能拿走 | ❌ 服务商持有 | ✅ 只有你（凭主密码） | +| **断网能签名吗** | ⚠️ 看情况 | ❌ 必须联网 | ✅ 100% 离线签名 | +| **为 AI 代理设计** | ❌ 需要手动集成 | ⚠️ REST API，有延迟 | ✅ CLI + SDK，本地即时响应 | +| **多链支持** | ❌ 自己搭 | ⚠️ 取决于服务商 | ✅ EVM + TRON，统一接口 | +| **生产环境就绪** | ❌ 非常危险 | ⚠️ 需要信任第三方 | ✅ 自托管，可审计 | -### 银行级密钥加密 +--- -私钥以 **Keystore V3** 格式加密存储，使用 scrypt（计算成本是普通 bcrypt 的数十倍）+ AES-128-CTR + keccak256 MAC 的组合。即使密钥文件被盗，没有主密码也无法解出私钥。主密码本身也从不以任何形式存储在磁盘上。 +## 三条命令，一分钟上手 -### 不绑定任何 RPC 服务商 +不需要先搞懂所有东西，先跑通再说： -因为 Agent-wallet 不做任何链上操作，你可以自由选择任意 RPC——TronGrid、自建节点——完全不影响签名逻辑。迁移或切换服务商时，签名代码不需要任何修改。 +**第一步 — 安装：** +```bash +npm install -g @bankofai/agent-wallet +``` + +**第二步 — 创建你的加密保险箱：** +```bash +agent-wallet start +``` +系统会引导你初始化 Agent-wallet 加密保险箱，并生成一个**主密码**。这是解开所有资产的唯一凭证——忘了神仙难救，请用密码管理器保存。 + +**第三步 — 第一次签名：** +```bash +agent-wallet sign msg "Hello from my AI agent" -n tron +``` -### 多链、双语言、一套接口 +当屏幕上吐出一串哈希字符时——恭喜，你的加密保险箱配置成功了。 -EVM 和 TRON 使用同一套 `BaseWallet` 接口，Python 和 TypeScript 两个实现行为完全一致、密钥文件格式互通。同一套密钥，换一门语言，签出来的结果完全相同。 +> 想看每一步的详细说明？去 **[极简部署 — CLI 快速开始](./QuickStart.md)**。 --- -## 两种使用方式 +## 接下来，让 AI 真正跑起来 + +保险箱建好了，签名也测试通过了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** -### CLI（命令行工具） +根据你的角色，走不同的路： -适合需要管理密钥、手动测试签名的场景。 +### 🎮 我是普通玩家——用现成的工具 + +你不需要写代码。很多 AI 工具已经原生支持 Agent-wallet（**推荐使用我们的 [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**）。你只需要做一件事——把主密码告诉工具： ```bash -npm install -g @bankofai/agent-wallet -agent-wallet start # 初始化并创建默认钱包 -agent-wallet sign msg "Hello" # 签名消息 +export AGENT_WALLET_PASSWORD='你的主密码' ``` -→ 详见 [CLI 快速开始](./QuickStart.md) +:::caution 密码有特殊字符？务必用单引号 +自动生成的密码经常含有 `$`、`!` 等特殊字符。**用单引号**包裹，否则 shell 会把它"消化"掉： -### SDK（编程接口） +```bash +# ✅ 正确 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ 错误 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: -适合在代码中集成签名能力，比如在 MCP Server 内部使用。 +设置好后，工具就能自动调用你的 Agent-wallet 加密保险箱来签名了。你的私钥全程加密，工具拿到的只是签名结果，不是密钥本身。 + +> 想看支持的工具列表？去 **[Openclaw 扩展](../Openclaw-extension/Intro.md)**。 + +### 🛠️ 我是开发者——自己写代理 + +
+展开开发者路径 — TypeScript / Python SDK + +Agent-wallet 提供了完整的 SDK，TypeScript 和 Python 双语言支持，共享同一套接口： ```typescript import { resolveWalletProvider } from "@bankofai/agent-wallet"; const provider = resolveWalletProvider({ network: "tron:nile" }); -const wallet = await provider.getActiveWallet(); -const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); +const wallet = await provider.getActiveWallet(); +const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); ``` -提供 **Python** 和 **TypeScript** 两个版本，接口相同，输出完全兼容。 +同一个密钥文件、同一份数据、同一个签名结果。 -→ 详见 [SDK 快速开始](./SDKQuickStart.md) +> **[SDK 快速开始](./SDKQuickStart.md)** 手把手教你接入。 +> **[完整示例](./FullExample.md)** 展示端到端的真实交易：TRON 转账、BSC 转账、x402 支付签名。 + +
--- -## 支持哪些链 +## 支持的链 + +| 链类型 | 网络 | +| :--- | :--- | +| **EVM** | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链 | +| **TRON** | TRON 主网、Nile 测试网、Shasta 测试网 | -| 链类型 | 网络标识符 | 支持的网络 | -| :--- | :--- | :--- | -| **EVM** | `eip155:*` | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链 | -| **TRON** | `tron:*` | TRON 主网、Nile 测试网、Shasta 测试网 | +两类链共用同一套接口——学一次，到处用。 --- -## 从哪里开始 +## 还有疑问？ -| 你的目标 | 从这里开始 | +| 我在想… | 去这里 | | :--- | :--- | -| 初始化钱包、用命令行管理密钥和签名 | [CLI 快速开始](./QuickStart.md) | -| 在 Python 或 TypeScript 代码中集成签名能力 | [SDK 快速开始](./SDKQuickStart.md) | -| 查看常见问题 | [常见问题](./FAQ.md) | +| AI 会不会把我的钱全转走？ | [常见问题](./FAQ.md) — 我们有专门的风险隔离方案 | +| 想马上动手试试 | [极简部署 — CLI 快速开始](./QuickStart.md) | +| 想在代码里用 | [SDK 快速开始](./SDKQuickStart.md) | +| 想看真实交易的完整流程 | [完整示例](./FullExample.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 43f83712..6ee92bca 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -1,348 +1,278 @@ # CLI 快速开始 -本指南帮你通过命令行完成 Agent-wallet 的安装、钱包初始化和签名操作。完成四个步骤后，你将拥有一个加密保存在本地的钱包，并能通过命令行对消息和交易进行签名。 +四步，从零到完成第一次签名。整个过程不到一分钟——复制粘贴就行。 -页面后半段是完整的命令参考，日常使用时按需查阅即可。 - -如果你是开发者，想在 Python 或 TypeScript 代码中直接调用签名接口，参阅 [SDK 快速开始](./SDKQuickStart.md)。 +:::tip 已经是开发者了？ +如果你想直接在 TypeScript 或 Python 代码里调用签名，跳到 [SDK 快速开始](./SDKQuickStart.md)。 +::: --- -## 第一步：安装 +## 🧰 第一步：准备环境 -### 确认 Node.js 版本 - -需要 Node.js ≥ 18，先检查当前版本： +Agent-wallet CLI 需要 Node.js ≥ 18。先看看你有没有： ```bash node -v ``` -如果输出 `v18.0.0` 或更高，可以直接跳到安装步骤。如果版本较低或提示命令不存在，按下方说明安装或升级。 +输出 `v18.x.x` 或更高？直接跳到第二步。没有或者版本太低？按下面的步骤安装： :::tip 安装 / 升级 Node.js -推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本，方便随时切换： +推荐用 [nvm](https://github.com/nvm-sh/nvm)，一条命令搞定： +**1 — 安装 nvm**（已有可跳过）： ```bash -# 安装 nvm（已安装可跳过） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +``` -# 重新加载 shell 配置 -source ~/.bashrc # 或 source ~/.zshrc +**2 — 重新加载终端配置：** +```bash +source ~/.bashrc # zsh 用户改成 source ~/.zshrc +``` -# 安装 Node.js 18 LTS +**3 — 安装 Node.js 18：** +```bash nvm install 18 +``` -# 切换到 Node.js 18 +**4 — 切换到 Node.js 18：** +```bash nvm use 18 ``` -也可以直接从 [nodejs.org](https://nodejs.org) 下载安装包，选择 **LTS** 版本即可。 - +也可以直接去 [nodejs.org](https://nodejs.org) 下载 LTS 安装包。 ::: -### 安装 Agent-wallet CLI +--- + +## 📦 第二步：安装 Agent-wallet ```bash npm install -g @bankofai/agent-wallet ``` -验证安装： +Python 用户也可以用 pip： +```bash +pip install bankofai-agent-wallet +``` +验证安装成功： ```bash agent-wallet --help ``` ---- - -## 第二步：初始化钱包 +看到帮助信息就说明安装好了。 -`start` 命令一步完成初始化并创建默认钱包，有三种方式可选： +--- -### 方式 A：全自动（推荐新手） +## 🔐 第三步：打造你的专属保险箱 +运行： ```bash agent-wallet start ``` -系统会自动生成强密码，同时创建一个 TRON 钱包和一个 EVM 钱包： +系统会引导你初始化 **Agent-wallet 加密保险箱**。整个过程是交互式的——跟着提示走就行。 -``` -🔐 Wallet initialized! +如果你没有手动指定密码（`-p` 参数），系统会自动生成一个强密码并显示一次： -🪙 Wallets: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TB37... │ -│ default_evm │ evm_local │ 0xd679B... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ - -⭐ Active wallet: default_tron - -🔑 Your master password: E&LCi*KL1Sp4mg4! - ⚠️ Save this password! You'll need it for signing and other operations. ``` +? Quick start type: local_secure — Encrypted key stored locally (recommended) +Wallet ID (e.g. my_wallet_1) (default): -:::caution 安全提示 -- **保管好主密码** — 主密码是解密所有私钥的唯一凭据，丢失后无法恢复。建议使用密码管理器保存。 -- **不要明文写在代码里** — 如果需要非交互式使用，通过环境变量 `AGENT_WALLET_PASSWORD` 传入，而不是硬编码在脚本中。 -- **不要提交 `.env` 文件** — 将 `.env` 加入 `.gitignore`，避免密码或私钥泄露到版本库。 -- **为代理使用专用钱包** — 不要把个人主钱包的私钥交给 AI 代理，而是创建独立钱包并只充入所需的小额资金。 -::: +Wallet initialized! +? Import source: generate — Generate a new random private key +Wallets: +┌───────────┬──────────────┐ +│ Wallet ID │ Type │ +├───────────┼──────────────┤ +│ default │ local_secure │ +└───────────┴──────────────┘ -### 方式 B：自定义密码 +Your master password: WiJxcI#t6@73K#OE + Save this password! You'll need it for signing and other operations. -```bash -agent-wallet start -p Abc12345! +Active wallet: default ``` -密码要求：至少 8 个字符，包含大写字母、小写字母、数字和特殊符号。 +:::caution ⚠️ 主密码 = 你所有资产的唯一钥匙 +这个密码是解开所有私钥的唯一凭证。**忘了就找不回来——我们也没有备份，没有后门，神仙难救。** -### 方式 C：导入已有私钥 - -如果你已有一个私钥希望直接导入： +请现在就做这件事： +1. 打开你的密码管理器（1Password、Bitwarden 等） +2. 新建一条记录，把主密码存进去 +3. 不要截图，不要记在桌面便签上，不要发给自己的微信 +::: +**想自己设密码？** ```bash -agent-wallet start -p Abc12345! -i tron +agent-wallet start -p Abc12345! ``` +密码要求：至少 8 位，包含大写、小写、数字和特殊字符。 -运行后会提示你粘贴私钥（输入内容不会显示在屏幕上）： - +**已经有私钥，想导入？** +```bash +agent-wallet start -p Abc12345! -k 你的私钥十六进制 ``` -🔐 Wallet initialized! -✔ Paste private key (hex) -🪙 Imported wallet: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│ default_tron │ tron_local │ TNmo... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ - -⭐ Active wallet: default_tron +**有助记词？** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." ``` -`-i` 参数支持 `tron`、`evm`、`tron_local`、`evm_local`。 - - --- -## 第三步：查看钱包 +## ✨ 第四步：第一次测试签名 -列出所有钱包： +激动人心的时刻——运行： ```bash -agent-wallet list +agent-wallet sign msg "Hello from my AI agent" -n tron ``` -``` -Wallets: -┌──────────────────────┬─────────────────┬──────────────────────────────────────────────┐ -│ Wallet ID │ Type │ Address │ -├──────────────────────┼─────────────────┼──────────────────────────────────────────────┤ -│* default_tron │ tron_local │ TB37... │ -│ default_evm │ evm_local │ 0xd679B... │ -└──────────────────────┴─────────────────┴──────────────────────────────────────────────┘ -``` - -`*` 标记当前活跃钱包，签名时默认使用活跃钱包。 - ---- - -## 第四步：签名 - -### 签名消息 - -```bash title="输入" -agent-wallet sign msg "Hello" -``` +系统会让你输入主密码，然后输出： -```text title="输出" +```text Master password: ******** Signature: 4a9c8f...e71b ``` -### 签名交易 +**当屏幕上吐出那串哈希字符时——恭喜你，保险箱配置成功了！** 🎉 -交易内容以 JSON 字符串形式传入（你需要先通过 RPC 构建好未签名的交易）： +你的私钥已经加密存储在磁盘上，刚才的签名完全在本地完成，没有任何数据发送到网络。 -```bash title="输入" -agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -``` - -```text title="输出" -Master password: ******** -Signed tx: -{ - "txID": "abc123...", - "signature": ["..."] -} -``` - -### 签名 EIP-712 结构化数据 +--- -```bash title="输入" -agent-wallet sign typed-data '{ - "types": { - "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], - "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] - }, - "primaryType": "Transfer", - "domain": {"name":"MyDApp","chainId":1}, - "message": {"to":"0x7099...","amount":1000000} -}' -``` +## 🚀 快速开始完成！接下来做什么？ -```text title="输出" -Master password: ******** -Signature: 22008ffd...0e1c -``` +| 我想… | 做这个 | +| :--- | :--- | +| 让 AI 工具用上我的钱包 | 设置环境变量 `export AGENT_WALLET_PASSWORD='你的密码'`，详见 [简介](./Intro.md) | +| 在自己的代码里签名 | 去 [SDK 快速开始](./SDKQuickStart.md) | +| 看完整的转账示例 | 去 [完整示例](./FullExample.md) | +| 继续看下面的命令手册 | ↓ 往下翻 | --- -## 命令参考 +## 命令手册 -完成快速开始后，可以按需查阅以下内容。 +快速开始之后，下面是你日常会用到的所有命令。按需查阅。 -### 跳过密码提示 +### 免密码签名 -每次签名都输入密码很麻烦。通过环境变量可以跳过交互式提示： +每次签名都要交互输密码？自动化流程里完全行不通。三种方式跳过： +**方式 A — 环境变量**（推荐用于 CI / 代理流水线）： ```bash export AGENT_WALLET_PASSWORD='Abc12345!' ``` +设置后，所有签名命令静默运行： +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` -:::caution 密码包含特殊字符时必须用单引号 -主密码（尤其是自动生成的强密码）可能包含 `$`、`!` 等 shell 特殊字符，**必须用单引号**包裹，否则 shell 会展开这些字符导致密码错误： - +:::caution 密码有特殊字符？务必用单引号 ```bash -# ✅ 正确 +# ✅ 正确 — shell 按字面意思处理 export AGENT_WALLET_PASSWORD='P@ss$w0rd!' -# ❌ 错误：$ 会被 shell 展开 +# ❌ 错误 — $ 被 shell 展开，密码静默出错 export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: - -设置后，所有签名命令不再提示输入密码，直接输出结果： - +**方式 B — 内联 `-p`**（临时用一次）： ```bash -agent-wallet sign msg "Hello" -agent-wallet sign tx '{"txID":"..."}' +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" ``` -也可以在单条命令中通过 `-p` 参数传入： - +**方式 C — `--save-runtime-secrets`**（密码存入 `~/.agent-wallet/runtime_secrets.json`，下次自动读取）： ```bash -agent-wallet sign msg "Hello" -p "Abc12345!" +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` -### 管理多个钱包 +### 签名类型 -#### 1. 添加新钱包 +每条 `sign` 子命令都需要 `--network` / `-n` 来指定链： -交互式提示中选择钱包类型（`tron_local` 或 `evm_local`）、生成或导入私钥： +**签名消息：** +```bash +agent-wallet sign msg "Hello" -n tron +``` -```bash title="输入" -agent-wallet add +**签名交易**（需要先通过 RPC 构建未签名交易）： +```bash +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron ``` -```text title="输出" -Master password: ******** -Wallet name: my-bsc-wallet -> Wallet type: evm_local -> Private key: generate -Generated new private key. - Address: 0x8c714fe3... - Saved: id_my-bsc-wallet.json -Wallet 'my-bsc-wallet' added. +**签名 EIP-712 结构化数据：** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 ``` -#### 2. 切换活跃钱包 +### 管理多个钱包 -```bash title="输入" -agent-wallet use my-bsc-wallet +**添加新钱包：** +```bash +agent-wallet add ``` -```text title="输出" -Active wallet: my-bsc-wallet (evm_local) +**切换活跃钱包：** +```bash +agent-wallet use my-bsc-wallet ``` -#### 3. 指定钱包签名 - -签名时可以用 `-w` 显式指定钱包，不受活跃钱包影响： - +**用指定钱包签名**（不切换活跃钱包）： ```bash -agent-wallet sign msg "Hello" -w my-bsc-wallet -p "Abc12345!" +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" ``` -#### 4. 查看钱包详情 - -```bash title="输入" +**查看钱包详情：** +```bash agent-wallet inspect my-bsc-wallet ``` -```text title="输出" -Wallet my-bsc-wallet -Type evm_local -Address 0x8c714fe3... -Identity id_my-bsc-wallet.json ✓ -Credential — +**查看所有钱包：** +```bash +agent-wallet list ``` -#### 5. 删除钱包 - -```bash title="输入" +**删除钱包：** +```bash agent-wallet remove my-bsc-wallet ``` -```text title="输出" -Remove wallet 'my-bsc-wallet'? (y/N): y - Deleted: id_my-bsc-wallet.json -Wallet 'my-bsc-wallet' removed. -``` +### 修改主密码 -### 其他操作 +修改后，所有密钥文件会用新密码重新加密： -#### 1. 修改主密码 - -主密码是加密所有本地私钥的唯一凭据。Agent-wallet 不存储主密码本身，而是用它对每个私钥文件进行加密——修改主密码时，所有密钥文件会用新密码重新加密。 - -```bash title="输入" +```bash agent-wallet change-password ``` -```text title="输出" -Current password: ******** -New password: ******** -Confirm new password: ******** -Password changed. Re-encrypted 3 files. -``` - -会重新加密所有密钥文件。 +### 重置所有数据 -#### 2. 重置所有数据 +删除 `~/.agent-wallet/` 下的所有内容，**不可撤销**，需要二次确认： -```bash title="输入" +```bash agent-wallet reset ``` -```text title="输出" -⚠️ This will delete ALL wallet data in: /home/you/.agent-wallet -Are you sure you want to reset? This cannot be undone. (y/N): y -Really delete everything? Last chance! (y/N): y -✅ Wallet data reset complete. -``` - -删除 `~/.agent-wallet/` 目录下的全部数据，操作不可逆，会要求二次确认。 - -#### 3. 自定义存储目录 +### 自定义存储目录 -所有命令都支持 `--dir` 参数指定自定义密钥目录（默认 `~/.agent-wallet`）： +所有命令支持 `--dir` 指定密钥存储路径（默认 `~/.agent-wallet`）： ```bash agent-wallet start --dir ./my-secrets @@ -353,6 +283,6 @@ agent-wallet sign msg "Hello" --dir ./my-secrets ## 下一步 -- 在代码中使用签名能力 → [SDK 快速开始](./SDKQuickStart.md) -- 了解整体设计 → [简介](./Intro.md) +- 让 AI 工具用上你的钱包 → [简介 — 普通玩家路径](./Intro.md) +- 在代码里集成签名 → [SDK 快速开始](./SDKQuickStart.md) - 查看常见问题 → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md index 1f9a71ff..b5c2a913 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md @@ -3,13 +3,15 @@ import TabItem from '@theme/TabItem'; # SDK 快速开始 -这个页面面向开发者，介绍如何在 Python 或 TypeScript 代码中直接调用 Agent-wallet 的签名接口。 +CLI 已经跑通了，能从命令行签名。现在你想把签名能力放进代码里——MCP Server、自动化脚本、AI 代理工作流。 -与 CLI 不同，SDK 的使用场景是将签名能力嵌入你自己的程序——比如在 MCP Server 里为 AI 代理提供签名支持，或在自动化脚本中对链上操作进行授权。你的代码负责构建交易和广播，Agent-wallet 负责在本地完成签名并返回结果。 +本页教你怎么做。完成后，你就能用几行 TypeScript 或 Python 初始化钱包 Provider、获取活跃钱包，并对消息、交易、EIP-712 结构化数据进行签名。 -完成本指南后，你将能够通过代码初始化钱包提供者、获取活跃钱包，并对消息、交易和 EIP-712 结构化数据进行签名。如果你还没有初始化过本地钱包，建议先完成 [CLI 快速开始](./QuickStart.md) 中的第一步到第三步。 +:::tip 刚刚入门？ +如果还没创建过钱包，先去 [CLI 快速开始](./QuickStart.md) 走一遍（前三步不到一分钟）。SDK 读取的就是 CLI 创建的那个钱包——不需要重复配置任何东西。 +::: -安装和代码示例均提供 TypeScript 和 Python 两个版本，通过标签切换查看。 +文档提供 TypeScript 和 Python 两个版本的安装说明和代码示例，点击标签页切换。 --- @@ -18,19 +20,19 @@ import TabItem from '@theme/TabItem'; -**确认 Node.js 版本** +**检查 Node.js 版本** -需要 Node.js ≥ 18，先检查当前版本： +需要 Node.js ≥ 18，查看当前版本： ```bash node -v ``` -如果输出 `v18.0.0` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 +输出 `v18.0.0` 或更高，可以直接安装；否则按下面的方法升级。 :::tip 安装 / 升级 Node.js -推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本： +推荐用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本： ```bash # 安装 nvm（已安装可跳过） @@ -57,26 +59,26 @@ npm install @bankofai/agent-wallet -**确认 Python 版本** +**检查 Python 版本** -需要 Python ≥ 3.11（SDK 使用了 `StrEnum` 等 3.11+ 特性），先检查当前版本： +需要 Python ≥ 3.11（SDK 使用了 3.11+ 的特性）： ```bash python3 --version ``` -如果输出 `3.11.x` 或更高，可以直接安装。如果版本不足或提示命令不存在，按下方说明安装或升级。 +输出 `3.11.x` 或更高，可以直接安装；否则按下面的方法升级。 :::tip 安装 / 升级 Python -推荐使用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本： +推荐用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本： ```bash # 第一步：安装 pyenv curl https://pyenv.run | bash ``` -安装完成后，需要手动将 pyenv 加入 shell 配置，否则终端找不到 `pyenv` 命令： +安装后需要手动添加到 shell 配置： ```bash # 将以下三行追加到 ~/.bashrc（zsh 用户改为 ~/.zshrc） @@ -88,7 +90,7 @@ echo 'eval "$(pyenv init -)"' >> ~/.bashrc source ~/.bashrc ``` -确认 pyenv 可用后，先安装构建 Python 所需的系统依赖。**跳过这一步会导致 `_ctypes`、`ssl` 等模块缺失，进而引发标准库模块（如 `asyncio`）无法导入。** +使用 pyenv 之前，先安装系统依赖，**跳过这步会导致 `_ctypes`、`ssl` 等模块缺失，进而影响 `asyncio` 等标准库的导入**： ```bash # CentOS / RHEL / Amazon Linux / Fedora @@ -98,37 +100,34 @@ sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev ``` -安装好系统依赖后，再构建 Python： +然后编译 Python： ```bash pyenv install 3.11 pyenv global 3.11 ``` -也可以直接从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.11 或更高版本**。 +也可以从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.11 或更高版本**。 ::: **安装 SDK** -Python 包目前未发布到 PyPI，需从源码安装： - ```bash -git clone https://github.com/BofAI/agent-wallet.git -cd agent-wallet/packages/python -pip3.11 install -e ".[all]" +pip install 'bankofai-agent-wallet[evm,tron]' ``` -SDK 依赖 `tronpy` 和 `eth_account` 处理 TRON 和 EVM 签名，若安装后遇到这两个包的导入错误，手动补装： +如果只需要其中一条链，单独安装对应的 extra： ```bash -pip3.11 install tronpy eth_account +pip install 'bankofai-agent-wallet[tron]' # 仅 TRON +pip install 'bankofai-agent-wallet[evm]' # 仅 EVM ``` 验证安装： ```bash -python3.11 -c "import agent_wallet; print('安装成功')" +python3 -c "import agent_wallet; print('Installation successful')" ``` @@ -138,64 +137,64 @@ python3.11 -c "import agent_wallet; print('安装成功')" ## 第二步：配置模式 -在调用 SDK 之前，需要先通过环境变量告诉 Agent-wallet 如何找到你的密钥。SDK 提供两种模式——本地模式适合长期管理多个钱包，静态模式适合直接注入私钥。`resolveWalletProvider()` 会自动识别当前设置的环境变量，选择对应的模式，无需在代码里做任何额外判断。 +调用 SDK 之前，需要通过环境变量告诉 Agent-wallet 去哪里找密钥。SDK 提供两种模式——**本地模式**（磁盘加密密钥，`local_secure`）适合长期管理多个钱包，**静态模式**（环境变量注入）适合直接传入单个私钥。`resolveWalletProvider()` 会自动检测已设置的环境变量并选择对应模式，代码里不需要写任何判断逻辑。 -### 本地模式 +### 本地模式（`local_secure`） -私钥加密存储在本地，适合需要管理多个钱包或长期持久化密钥的场景。使用前需要先通过 CLI 完成初始化（`agent-wallet start`），然后设置主密码： +私钥加密存储在磁盘上，适合长期管理多个钱包。使用前需要先通过 CLI 初始化（`agent-wallet start`），然后设置主密码： ```bash export AGENT_WALLET_PASSWORD='Abc12345!' -# 可选：自定义目录，默认 ~/.agent-wallet +# 可选：自定义目录，默认为 ~/.agent-wallet export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` -:::caution 密码包含特殊字符时必须用单引号 -如果主密码包含 `$`、`!` 等 shell 特殊字符（例如自动生成的强密码），**必须用单引号**包裹，否则 shell 会对这些字符进行展开，导致密码被篡改： +:::caution 密码含特殊字符时，务必用单引号 +自动生成的强密码可能含有 `$`、`!` 等 shell 特殊字符，**务必用单引号**，避免 shell 展开导致密码被篡改： ```bash # ✅ 正确：单引号，密码原样传入 export AGENT_WALLET_PASSWORD='P@ss$w0rd!' -# ❌ 错误：双引号，$ 会被 shell 展开 +# ❌ 错误：双引号，$ 被 shell 展开 export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: -### 静态模式 +### 静态模式（环境变量注入） -直接通过环境变量提供私钥或助记词，无需本地密钥文件，适合 CI/CD 或一次性脚本场景。静态模式下必须同时指定 `network` 参数： +直接通过环境变量传入私钥或助记词，不需要本地密钥文件，适合 CI/CD 或一次性脚本。静态模式必须指定 `network` 参数： ```bash -export AGENT_WALLET_PRIVATE_KEY="你的私钥（十六进制）" +export AGENT_WALLET_PRIVATE_KEY="你的私钥十六进制" # 或 export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." ``` :::caution 注意事项 -- `AGENT_WALLET_PASSWORD` 优先级高于 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`，两者同时设置时走本地模式 +- `AGENT_WALLET_PASSWORD` 优先于 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`——两者同时设置时，以本地模式为准 - `AGENT_WALLET_PRIVATE_KEY` 和 `AGENT_WALLET_MNEMONIC` 不能同时设置 -- 不要将私钥或密码硬编码在代码里，始终通过环境变量或 `.env` 文件传入，并将 `.env` 加入 `.gitignore` +- 私钥和密码不要硬编码在源代码里——始终通过环境变量或 `.env` 文件传入，并把 `.env` 加进 `.gitignore` ::: ### 环境变量速查 -| 变量名 | 用途 | 模式 | 是否必选 | +| 变量名 | 用途 | 模式 | 是否必填 | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | 主密码，启用本地模式 | 本地模式 | 必选 | +| `AGENT_WALLET_PASSWORD` | 主密码，启用本地模式 | 本地模式 | 必填 | | `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 本地模式 | 可选 | -| `AGENT_WALLET_PRIVATE_KEY` | 私钥（十六进制） | 静态模式 | 必选（与助记词二选一） | -| `AGENT_WALLET_MNEMONIC` | 助记词 | 静态模式 | 必选（与私钥二选一） | -| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 助记词派生地址索引（默认 `0`） | 静态模式 | 可选 | +| `AGENT_WALLET_PRIVATE_KEY` | 私钥（十六进制） | 静态模式 | 二选一（与助记词） | +| `AGENT_WALLET_MNEMONIC` | 助记词短语 | 静态模式 | 二选一（与私钥） | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 助记词派生索引（默认 `0`） | 静态模式 | 可选 | --- -## 用法示例 +## 使用示例 -### 初始化钱包提供者 +### 初始化钱包 Provider -所有操作的起点是 `resolveWalletProvider()`，它根据环境变量自动选择工作模式并返回一个钱包提供者，再通过 `getActiveWallet()` 拿到活跃钱包。 +所有操作的起点是 `resolveWalletProvider()`。它读取环境变量，选择对应模式，返回钱包 Provider。调用 `getActiveWallet()` 获取活跃钱包。 @@ -208,7 +207,7 @@ const wallet = await provider.getActiveWallet(); // 查看当前钱包地址 const address = await wallet.getAddress(); -console.log("地址:", address); +console.log("Address:", address); ``` @@ -225,7 +224,7 @@ async def main(): # 查看当前钱包地址 address = await wallet.get_address() - print("地址:", address) + print("Address:", address) asyncio.run(main()) ``` @@ -233,7 +232,7 @@ asyncio.run(main()) -拿到 `wallet` 后，可以调用以下三种签名方法。所有签名方法均返回十六进制编码的签名字符串（无 `0x` 前缀）。 +拿到 `wallet` 之后，就可以调用下面三种签名方法。所有签名方法返回十六进制编码的签名字符串（不带 `0x` 前缀）。 ### 签名消息 @@ -242,7 +241,7 @@ asyncio.run(main()) ```typescript const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); -console.log("签名:", sig); +console.log("Signature:", sig); ``` @@ -250,7 +249,7 @@ console.log("签名:", sig); ```python sig = await wallet.sign_message(b"Hello") -print("签名:", sig) +print("Signature:", sig) ``` @@ -258,7 +257,7 @@ print("签名:", sig) ### 签名交易 -Agent-wallet 只负责签名，不负责构建或广播交易。你需要先通过 RPC（如 TronGrid、Infura）构建未签名的交易，再传给 SDK 签名。 +Agent-wallet 只负责签名，不构建也不广播。你需要先通过 RPC（比如 TronGrid、Infura）构建未签名的交易，再传给 SDK 签名。 #### TRON 交易 @@ -266,7 +265,7 @@ Agent-wallet 只负责签名，不负责构建或广播交易。你需要先通 ```typescript -// 1. 调用者通过 TronGrid 构建未签名交易 +// 1. 调用方通过 TronGrid 构建未签名交易 const unsignedTx = { txID: "abc123...", raw_data_hex: "0a02...", @@ -275,16 +274,16 @@ const unsignedTx = { // 2. SDK 本地签名（无网络调用） const signedTxJson = await wallet.signTransaction(unsignedTx); -console.log("已签名交易:", signedTxJson); +console.log("Signed transaction:", signedTxJson); -// 3. 调用者负责广播 +// 3. 调用方负责广播 ``` ```python -# 1. 调用者通过 TronGrid 构建未签名交易 +# 1. 调用方通过 TronGrid 构建未签名交易 unsigned_tx = { "txID": "abc123...", "raw_data_hex": "0a02...", @@ -293,9 +292,9 @@ unsigned_tx = { # 2. SDK 本地签名（无网络调用） signed_tx_json = await wallet.sign_transaction(unsigned_tx) -print("已签名交易:", signed_tx_json) +print("Signed transaction:", signed_tx_json) -# 3. 调用者负责广播 +# 3. 调用方负责广播 ``` @@ -315,7 +314,7 @@ const sig = await wallet.signTransaction({ nonce: 0, chainId: 56, }); -console.log("签名:", sig); +console.log("Signature:", sig); ``` @@ -330,7 +329,7 @@ sig = await wallet.sign_transaction({ "nonce": 0, "chainId": 56, }) -print("签名:", sig) +print("Signature:", sig) ``` @@ -338,7 +337,7 @@ print("签名:", sig) ### 签名 EIP-712 结构化数据 -用于 x402 协议的 PaymentPermit 签名、Permit2 等场景： +用于 x402 协议 PaymentPermit 签名、Permit2 等场景： @@ -359,7 +358,7 @@ const sig = await wallet.signTypedData({ domain: { name: "MyDApp", chainId: 1 }, message: { to: "0x...", amount: 1000000 }, }); -console.log("签名:", sig); +console.log("Signature:", sig); ``` @@ -381,7 +380,7 @@ sig = await wallet.sign_typed_data({ "domain": {"name": "MyDApp", "chainId": 1}, "message": {"to": "0x...", "amount": 1000000}, }) -print("签名:", sig) +print("Signature:", sig) ``` @@ -391,20 +390,21 @@ print("签名:", sig) ### 管理多个钱包 -如果你需要在代码中管理多个钱包，可以直接使用 `LocalWalletProvider`： +需要在代码中管理多个钱包时，使用本地模式的 `resolveWalletProvider()`，Provider 会读取钱包配置并支持切换活跃钱包： ```typescript -import { LocalWalletProvider } from "@bankofai/agent-wallet"; +import { resolveWalletProvider } from "@bankofai/agent-wallet"; -const provider = new LocalWalletProvider("~/.agent-wallet", "Abc12345!"); +// 本地模式：需要设置 AGENT_WALLET_PASSWORD +const provider = resolveWalletProvider({ network: "tron:nile" }); // 列出所有钱包 const wallets = await provider.listWallets(); for (const w of wallets) { - console.log(`${w.id} (${w.type}): ${w.address}`); + console.log(`${w.id} (${w.type})`); } // 切换活跃钱包 @@ -419,18 +419,18 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); ```python -# 设置环境变量后，resolve_wallet_provider 自动进入本地模式 +# 设置环境变量——resolve_wallet_provider 自动进入本地模式 import os os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" from agent_wallet import resolve_wallet_provider -provider = resolve_wallet_provider() +provider = resolve_wallet_provider(network="tron:nile") async def main(): wallet = await provider.get_active_wallet() sig = await wallet.sign_message(b"Hello") - print("签名:", sig) + print("Signature:", sig) asyncio.run(main()) ``` @@ -442,7 +442,7 @@ asyncio.run(main()) ### 错误处理 -签名操作失败时，SDK 会抛出具体的错误类型，建议在代码中显式捕获并处理，避免运行时崩溃。 +签名操作失败时，SDK 会抛出特定的错误类型，建议在代码中显式捕获，避免运行时崩溃。 @@ -457,14 +457,14 @@ import { try { const wallet = await provider.getActiveWallet(); const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); - console.log("签名:", sig); + console.log("Signature:", sig); } catch (e) { if (e instanceof WalletNotFoundError) { - console.error("找不到钱包，检查活跃钱包是否已设置"); + console.error("钱包不存在——检查是否设置了活跃钱包"); } else if (e instanceof DecryptionError) { - console.error("解密失败，检查主密码是否正确"); + console.error("解密失败——检查主密码是否正确"); } else if (e instanceof SigningError) { - console.error("签名失败:", e.message); + console.error("签名失败：", e.message); } else { throw e; } @@ -480,13 +480,13 @@ from agent_wallet import WalletNotFoundError, SigningError, DecryptionError try: wallet = await provider.get_active_wallet() sig = await wallet.sign_message(b"Hello") - print("签名:", sig) + print("Signature:", sig) except WalletNotFoundError: - print("找不到钱包，检查活跃钱包是否已设置") + print("钱包不存在——检查是否设置了活跃钱包") except DecryptionError: - print("解密失败，检查主密码是否正确") + print("解密失败——检查主密码是否正确") except SigningError as e: - print(f"签名失败: {e}") + print(f"签名失败：{e}") ``` @@ -496,12 +496,12 @@ except SigningError as e: ``` WalletError -├── WalletNotFoundError # 找不到指定钱包 +├── WalletNotFoundError # 指定钱包不存在 ├── DecryptionError # 密码错误或密钥文件损坏 ├── SigningError # 签名操作失败 ├── NetworkError # 网络标识符不匹配 ├── InsufficientBalanceError # 余额不足（由调用方抛出） -└── UnsupportedOperationError # 当前钱包类型不支持该操作 +└── UnsupportedOperationError # 该钱包类型不支持此操作 ``` --- @@ -509,5 +509,5 @@ WalletError ## 下一步 - 用命令行管理钱包 → [CLI 快速开始](./QuickStart.md) -- 了解 agent-wallet 的设计 → [简介](./Intro.md) +- 了解 Agent-wallet 的设计思路 → [简介](./Intro.md) - 查看常见问题 → [常见问题](./FAQ.md) From a95631370a64244dd3b8c3dbd9835c462cb8de9f Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sat, 21 Mar 2026 14:53:56 +0800 Subject: [PATCH 14/44] update --- docs/Agent-Wallet/FAQ.md | 20 ++++- docs/Agent-Wallet/Intro.md | 35 +++++---- docs/Agent-Wallet/SDKQuickStart.md | 77 +++++++++++-------- .../current/Agent-Wallet/FAQ.md | 20 ++++- .../current/Agent-Wallet/Intro.md | 35 +++++---- .../current/Agent-Wallet/SDKQuickStart.md | 77 +++++++++++-------- 6 files changed, 176 insertions(+), 88 deletions(-) diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index 37d471fe..eaafbcf2 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -33,7 +33,7 @@ Going offline only affects transaction building and broadcasting (that's the MCP **It's gone.** -The master password is the only credential for decrypting all private keys. We don't store it — not on disk, not in memory (it's wiped immediately after signing). There's no "forgot password" flow, no backdoor. +The master password is the only credential for decrypting all private keys. There's no "forgot password" flow, no backdoor. If you forget your password: - Have another backup of your private key or mnemonic? Run `agent-wallet reset`, reinitialize, and reimport. @@ -87,6 +87,24 @@ Most users don't need the SDK. If you're using OpenClaw and MCP Server, creating ## Security +### The password is also stored in an environment variable — how is that different from a plaintext private key? + +The difference is enormous! It's the difference between leaving cash on the table and locking it in a double-layered safe. + +When you use a Web3 wallet like MetaMask, you never copy-paste your raw private key every time — you unlock it with a short password. Agent-wallet is essentially a command-line MetaMask built for AI agents. + +* Traditional approach (plaintext private key): It's like leaving cash right on the table. Any malicious browser extension, one careless code commit, or a background log scan — one glance at your `.env` file and the money is gone instantly. A classic single point of failure. +* Agent-wallet approach: It splits the risk into two locks. + 1. Physical safe: Your private key is encrypted with industry-grade algorithms and locked in a hidden folder deep in your system (`~/.agent-wallet`). + 2. Unlock password: What you put in your environment variable (`.env`) is merely the password to open this safe. + +This means if a leak occurs: + +* If a hacker only steals your password (e.g., by scanning environment variables), they don't have your encrypted wallet file — the password is just a useless string. +* If a hacker only steals your encrypted wallet file, they don't have your master password — the file is uncrackable gibberish that would take millennia to brute-force. + +A hacker would need to simultaneously break into your computer, locate and steal the hidden wallet file, AND steal the password from your environment variables to touch your funds. The difficulty of this attack is orders of magnitude higher than simply scanning a `.env` file! + ### Does the private key ever leave my machine? Never. Agent-wallet makes zero network requests. Zero RPC calls, zero cloud services. Your private key never leaves your machine. diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 5e321fc8..3ba8c775 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -28,28 +28,37 @@ The common thread: **your private key is always exposed somewhere** — on disk, --- -## The Fix: Agent-wallet +## The Fix: A Web3 Wallet Built for AI Agents -Agent-wallet is a **local encrypted safe** that works even when you're offline. +When you use a Web3 wallet like MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf. -It does exactly one thing: **use industry-grade encryption to lock your vulnerable plaintext private key on your own machine, and sign locally.** +**Agent-wallet is a local MetaMask purpose-built for AI agents.** -Even if someone gets hold of your wallet file, without the master password it's pure garbage data. Brute-forcing it would take longer than the age of the universe — economically pointless. At the same time, all signing operations complete on your machine — no network calls, no third-party APIs, no cloud intermediaries. +It minimizes your risk through a **"physical + password separation"** dual-lock mechanism: -**Bottom line: steal the file all you want — it's unreadable. Sign locally — nothing to intercept.** +1. **Lock #1 (Physical file):** Your private key is encrypted with industry-grade algorithms and stored in a hidden folder deep in your system (`~/.agent-wallet`). +2. **Lock #2 (Authorization password):** Your AI agent only needs the "unlock password" (which you can set in an environment variable) to operate. + +**🤔 You might ask: "What if the AI leaks my unlock password?"** + +This is the most elegant part of Agent-wallet: **a leaked password ≠ stolen assets.** + +If a hacker steals only your password through a malicious plugin, they can't do anything — because they don't have your encrypted wallet file. If they steal only the wallet file without the password, it's just uncrackable gibberish. + +**A hacker would need to simultaneously break into your system, locate the hidden wallet file, AND steal the password from your environment variables to touch your funds.** The difficulty and cost of this kind of attack is orders of magnitude higher than simply scanning a plaintext private key in a `.env` file! + +**Bottom line: steal the file — it's useless without the password. Leak the password — it's useless without the file.** --- ## How It Compares -| | Plaintext key / `.env` | Cloud wallet | Agent-wallet | -| :--- | :---: | :---: | :---: | -| **Agent reads your key file** | ❌ Stolen instantly | — Key is remote | ✅ Encrypted — useless without password | -| **Who owns the key** | ⚠️ Whoever can read the file | ❌ The provider | ✅ Only you (master password) | -| **Works offline** | ⚠️ Depends | ❌ Must be online | ✅ 100% offline signing | -| **Designed for AI agents** | ❌ Manual integration | ⚠️ REST API, latency | ✅ CLI + SDK, local, instant | -| **Multi-chain support** | ❌ Build it yourself | ⚠️ Provider-dependent | ✅ EVM + TRON, one interface | -| **Production-ready** | ❌ Dangerous | ⚠️ Trust a third party | ✅ Self-hosted, auditable | +| | Traditional (plaintext key in `.env`) | Cloud wallet | 🛡️ Agent-wallet Local Vault | +| :--- | :--- | :--- | :--- | +| **How it works** | Hand your card and PIN directly to the AI | Store your money on someone else's server | **Give AI the password, file stays locked locally** | +| **Log / env variable leak** | ❌ **Total loss** | ⚠️ Key is remote, still hackable | ✅ **Only the password leaks — no file, hacker gets nothing** | +| **Encrypted file stolen** | — | — | ✅ **No password, hacker can't open the file** | +| **Works offline?** | ⚠️ Depends | ❌ Must be online | ✅ **100% offline signing** | --- diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/SDKQuickStart.md index 2d69ae2a..ba8ffdbe 100644 --- a/docs/Agent-Wallet/SDKQuickStart.md +++ b/docs/Agent-Wallet/SDKQuickStart.md @@ -137,20 +137,26 @@ python3 -c "import agent_wallet; print('Installation successful')" ## Step 2: Configure a Mode -Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. The SDK provides two modes — **local mode** (encrypted keys on disk, `local_secure`) is best for long-term management of multiple wallets, while **static mode** (env-based) is best for directly injecting a private key. `resolveWalletProvider()` automatically detects the environment variables that are set and selects the corresponding mode, with no additional logic needed in your code. +Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables. -### Local Mode (`local_secure`) +Don't be intimidated by the concepts — `resolveWalletProvider()` is extremely smart. It automatically detects which environment variables you've set and decides the mode for you. No `if/else` logic needed in your code. -Private keys are stored encrypted on disk. Best for managing multiple wallets or persisting keys long-term. You must initialize first via the CLI (`agent-wallet start`), then set the master password: +It supports two modes: + +### 🛡️ Core Usage: Local Vault Mode (Strongly Recommended) + +If you've already followed the [CLI Quick Start](./QuickStart.md), your private key is already safely locked inside a hidden file on your machine. + +**In this mode, you never need to (and shouldn't) touch your plaintext private key.** Just tell the SDK your "unlock password" and you're good to go. ```bash export AGENT_WALLET_PASSWORD='Abc12345!' -# Optional: custom directory, defaults to ~/.agent-wallet +# Optional: if you changed the wallet storage directory, tell the SDK where to look export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` :::caution Always use single quotes when the password contains special characters -Master passwords — especially auto-generated strong ones — may contain `$`, `!`, or other shell-special characters. **Always use single quotes** to prevent the shell from expanding them, which would silently corrupt the password: +Auto-generated strong passwords may contain `$`, `!`, or other shell-special characters. Always use single quotes to prevent the shell from expanding and corrupting the password: ```bash # ✅ Correct: single quotes, password passed as-is @@ -161,10 +167,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: +### ⚠️ Fallback: Static Injection Mode (Test Environments Only) -### Static Mode (env-based) - -Provide a private key or mnemonic directly via environment variable — no local key file required. Best for CI/CD or one-off scripts. The `network` parameter must be specified when using static mode: +If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local vault and feed the private key directly to the SDK. ```bash export AGENT_WALLET_PRIVATE_KEY="your-private-key-in-hex" @@ -172,21 +177,23 @@ export AGENT_WALLET_PRIVATE_KEY="your-private-key-in-hex" export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." ``` -:::caution Notes -- `AGENT_WALLET_PASSWORD` takes precedence over `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` — if both are set, local mode is used -- `AGENT_WALLET_PRIVATE_KEY` and `AGENT_WALLET_MNEMONIC` cannot be set at the same time -- Never hardcode private keys or passwords in source code — always pass them via environment variables or a `.env` file, and add `.env` to `.gitignore` +:::danger Extremely Dangerous: Violates Core Security Principles! +Static mode reads your private key in plaintext, which means you forfeit Agent-wallet's encryption protection and fall back to the "single point of failure" approach described in the introduction. Only use this mode in fully isolated test environments or one-off CI/CD scripts! For mainnet operations with real funds, always use local vault mode. +::: + +:::tip What if environment variables conflict? +If both a password and a private key exist in your environment variables, the SDK prioritizes security: it forces `AGENT_WALLET_PASSWORD` to enter local vault mode and ignores the plaintext private key. ::: ### Environment Variable Reference | Variable | Purpose | Mode | Required | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | Master password, enables local mode | Local mode | Required | -| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | Local mode | Optional | -| `AGENT_WALLET_PRIVATE_KEY` | Private key (hex) | Static mode | Required (choose one with mnemonic) | -| `AGENT_WALLET_MNEMONIC` | Mnemonic phrase | Static mode | Required (choose one with private key) | -| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | Derivation index for mnemonic (default `0`) | Static mode | Optional | +| `AGENT_WALLET_PASSWORD` | Master password, unlocks the local hidden file | 🛡️ Local Vault | Core required | +| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | 🛡️ Local Vault | Optional | +| `AGENT_WALLET_PRIVATE_KEY` | Plaintext private key (hex) | ⚠️ Static Injection | Choose one (with mnemonic) | +| `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | ⚠️ Static Injection | Choose one (with private key) | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 derivation index (default `0`) | ⚠️ Static Injection | Optional | --- @@ -396,19 +403,21 @@ If you need to manage multiple wallets in code, use `resolveWalletProvider()` in ```typescript -import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet"; // Local mode: AGENT_WALLET_PASSWORD must be set const provider = resolveWalletProvider({ network: "tron:nile" }); -// List all wallets -const wallets = await provider.listWallets(); -for (const w of wallets) { - console.log(`${w.id} (${w.type})`); -} +if (provider instanceof ConfigWalletProvider) { + // List all wallets — returns [walletId, config, isActive] tuples + const wallets = provider.listWallets(); + for (const [id, config, isActive] of wallets) { + console.log(`${id} (${config.type})${isActive ? " ← active" : ""}`); + } -// Switch the active wallet -provider.setActive("my-evm-wallet"); + // Switch the active wallet + provider.setActive("my-evm-wallet"); +} // Get and use const wallet = await provider.getActiveWallet(); @@ -419,15 +428,23 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); ```python -# Set the env var — resolve_wallet_provider automatically enters local mode -import os -os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" - -from agent_wallet import resolve_wallet_provider +import asyncio +from agent_wallet import resolve_wallet_provider, ConfigWalletProvider +# AGENT_WALLET_PASSWORD must be set provider = resolve_wallet_provider(network="tron:nile") async def main(): + if isinstance(provider, ConfigWalletProvider): + # List all wallets — returns [(wallet_id, config, is_active)] tuples + wallets = provider.list_wallets() + for wallet_id, config, is_active in wallets: + print(f"{wallet_id} ({config.type}){' ← active' if is_active else ''}") + + # Switch the active wallet + provider.set_active("my-evm-wallet") + + # Get and use wallet = await provider.get_active_wallet() sig = await wallet.sign_message(b"Hello") print("Signature:", sig) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index 8e369cee..adeff26c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -33,7 +33,7 @@ agent-wallet add **找不回来。** -主密码是解密所有私钥的唯一凭证。我们不保存它——不在磁盘上、不在内存里（签完名就清除）。没有"忘记密码"功能，没有后门。 +主密码是解密所有私钥的唯一凭证。没有"忘记密码"功能，没有后门。 如果你忘了密码： - 有私钥或助记词的其他备份？运行 `agent-wallet reset`，重新初始化，重新导入 @@ -87,6 +87,24 @@ agent-wallet add ## 安全性 +### 既然密码也要配在环境变量里，那和直接放明文私钥有什么区别？ + +区别极大！这是"把现金摆在桌上"和"把钱锁进双重保险箱"的区别。 + +你平时用 Web3 钱包（比如 MetaMask）时，肯定不会每次都复制粘贴明文私钥，而是用一个短密码去解锁它。Agent-wallet 就是专为 AI 打造的命令行版 MetaMask。 + +* 传统方式（明文私钥）： 就像把现金直接放在桌子上。任何一个恶意的浏览器插件、一次不小心的代码提交、或者后台日志扫描，只要看一眼你的 `.env` 文件，钱瞬间就被转走了。这是典型的单点白给。 +* Agent-wallet 模式： 它把风险拆分成了两把锁。 + 1. 物理保险箱： 你的私钥被行业顶级的算法加密，锁死在你电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 + 2. 开箱密码： 你放在环境变量（`.env`）里的，仅仅是解锁这个保险箱的密码。 + +这就意味着，如果发生了泄露： + +* 黑客如果只偷到了你的密码（比如通过扫描环境变量），他没有你的加密钱包文件，密码就只是一串没用的字符。 +* 黑客如果只偷走了你的加密钱包文件，他没有你的主密码，文件就是一堆几万年都破解不开的乱码。 + +黑客必须同时黑进你的电脑、精准定位并偷走隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。这种攻击难度比仅仅扫描一下 `.env` 要高出无数倍！ + ### 密钥会通过网络发出去吗？ 永远不会。Agent-wallet 不发起任何网络请求。零 RPC 调用、零云服务。你的私钥永远不离开你的机器。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index aba7c8ba..b8491bd9 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -27,28 +27,37 @@ --- -## 破局之道：Agent-wallet +## 破局之道：AI 界专属的 Web3 钱包 -Agent-wallet 是一个"断网也安全"的**本地加密保险箱**。 +你平时用 Web3 钱包（比如 MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。 -它只做一件事：**用行业顶级的加密算法把你脆弱的明文私钥锁死在你的电脑里，并在本地完成授权。** +**Agent-wallet 就是专为 AI 代理打造的本地 MetaMask。** -就算有人拿到了你的钱包文件，没有主密码，它就是一堆垃圾数据。暴力破解需要的时间比宇宙年龄还长——经济上毫无意义。同时，所有签名操作在你本地完成，不联网、不调 API、不经过任何第三方。 +它通过**"物理与密码分离"**的双重机制，把你的风险降到了最低： -**一句话：文件随便偷，偷了打不开；签名纯本地，网络抓不到。** +1. **第一重锁（物理文件）：** 你的私钥会被行业顶级的算法加密，锁死在电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 +2. **第二重锁（授权密码）：** AI 只需要知道"开箱密码"（你可以配在环境变量里）就能干活。 + +**🤔 你可能会问："如果 AI 把我的开箱密码也泄露了怎么办？"** + +这就是 Agent-wallet 最精妙的地方：**密码泄露 ≠ 资产被盗。** + +如果黑客通过恶意插件只偷到了你的密码，他什么也干不了，因为他没有你的加密钱包文件。如果他只偷到了钱包文件，没有密码，那就是一堆无法破解的乱码。 + +**黑客必须同时黑进你的电脑系统，精准翻出隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。** 这种攻击难度和成本，比仅仅扫描一下 `.env` 里的明文私钥要高出无数倍！ + +一句话：**文件随便偷，没密码打不开；密码被泄露，没文件依然安全。** --- ## 和"老办法"对比一下 -| | 明文密钥 / `.env` | 云钱包 | Agent-wallet | -| :--- | :---: | :---: | :---: | -| **代理读了你的密钥文件** | ❌ 直接被盗 | — 密钥在远端 | ✅ 加密文件——没密码打不开 | -| **密钥归谁** | ⚠️ 谁能读文件谁就能拿走 | ❌ 服务商持有 | ✅ 只有你（凭主密码） | -| **断网能签名吗** | ⚠️ 看情况 | ❌ 必须联网 | ✅ 100% 离线签名 | -| **为 AI 代理设计** | ❌ 需要手动集成 | ⚠️ REST API，有延迟 | ✅ CLI + SDK，本地即时响应 | -| **多链支持** | ❌ 自己搭 | ⚠️ 取决于服务商 | ✅ EVM + TRON，统一接口 | -| **生产环境就绪** | ❌ 非常危险 | ⚠️ 需要信任第三方 | ✅ 自托管，可审计 | +| | 传统方式 (明文私钥放 `.env`) | 云钱包 | 🛡️ Agent-wallet 本地金库 | +| :--- | :--- | :--- | :--- | +| **工作原理** | 把银行卡和密码直接交给 AI | 把钱存到别人的服务器上 | **给 AI 密码，文件锁在本地** | +| **遭遇日志/环境变量泄露** | ❌ **直接倾家荡产** | ⚠️ 密钥在远端，有被黑风险 | ✅ **只丢了密码，没有文件，黑客偷不走钱** | +| **遭遇加密文件被窃取** | — | — | ✅ **没有密码，黑客打不开文件** | +| **断网能签名吗** | ⚠️ 看情况 | ❌ 必须联网 | ✅ **100% 离线签名** | --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md index b5c2a913..374aac90 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md @@ -137,20 +137,26 @@ python3 -c "import agent_wallet; print('Installation successful')" ## 第二步：配置模式 -调用 SDK 之前，需要通过环境变量告诉 Agent-wallet 去哪里找密钥。SDK 提供两种模式——**本地模式**（磁盘加密密钥，`local_secure`）适合长期管理多个钱包，**静态模式**（环境变量注入）适合直接传入单个私钥。`resolveWalletProvider()` 会自动检测已设置的环境变量并选择对应模式，代码里不需要写任何判断逻辑。 +调用 SDK 之前，需要通过环境变量告诉 Agent-wallet 去哪里找密钥。 -### 本地模式（`local_secure`） +不要被复杂的概念吓到，`resolveWalletProvider()` 极其聪明，它会自动检测你配置了什么环境变量，并决定工作模式，代码里不需要写任何 `if/else` 判断逻辑。 -私钥加密存储在磁盘上，适合长期管理多个钱包。使用前需要先通过 CLI 初始化（`agent-wallet start`），然后设置主密码： +它支持以下两种模式： + +### 🛡️ 核心用法：本地金库模式（强烈推荐） + +如果你刚才已经跟着 [CLI 快速开始](./QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。 + +**在这个模式下，你根本不需要（也不应该）接触明文私钥。** 你只需要告诉 SDK 你的"开箱密码"即可。 ```bash export AGENT_WALLET_PASSWORD='Abc12345!' -# 可选：自定义目录，默认为 ~/.agent-wallet +# 可选：如果你之前改过钱包存储目录，告诉 SDK 在哪找 export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` :::caution 密码含特殊字符时，务必用单引号 -自动生成的强密码可能含有 `$`、`!` 等 shell 特殊字符，**务必用单引号**，避免 shell 展开导致密码被篡改： +自动生成的强密码可能含有 `$`、`!` 等 shell 特殊字符，务必用单引号，避免 shell 展开导致密码被破坏： ```bash # ✅ 正确：单引号，密码原样传入 @@ -161,10 +167,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: +### ⚠️ 备用方案：静态注入模式（仅限测试环境） -### 静态模式（环境变量注入） - -直接通过环境变量传入私钥或助记词，不需要本地密钥文件，适合 CI/CD 或一次性脚本。静态模式必须指定 `network` 参数： +如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地金库，直接把私钥喂给 SDK。 ```bash export AGENT_WALLET_PRIVATE_KEY="你的私钥十六进制" @@ -172,21 +177,23 @@ export AGENT_WALLET_PRIVATE_KEY="你的私钥十六进制" export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." ``` -:::caution 注意事项 -- `AGENT_WALLET_PASSWORD` 优先于 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`——两者同时设置时，以本地模式为准 -- `AGENT_WALLET_PRIVATE_KEY` 和 `AGENT_WALLET_MNEMONIC` 不能同时设置 -- 私钥和密码不要硬编码在源代码里——始终通过环境变量或 `.env` 文件传入，并把 `.env` 加进 `.gitignore` +:::danger 极度危险：违背核心安全原则！ +静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地金库模式。 +::: + +:::tip 环境变量冲突怎么办？ +如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地金库模式，忽略明文私钥。 ::: ### 环境变量速查 | 变量名 | 用途 | 模式 | 是否必填 | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | 主密码，启用本地模式 | 本地模式 | 必填 | -| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 本地模式 | 可选 | -| `AGENT_WALLET_PRIVATE_KEY` | 私钥（十六进制） | 静态模式 | 二选一（与助记词） | -| `AGENT_WALLET_MNEMONIC` | 助记词短语 | 静态模式 | 二选一（与私钥） | -| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 助记词派生索引（默认 `0`） | 静态模式 | 可选 | +| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地金库 | 核心必填 | +| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地金库 | 可选 | +| `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（十六进制） | ⚠️ 静态注入 | 二选一（与助记词） | +| `AGENT_WALLET_MNEMONIC` | 明文助记词短语 | ⚠️ 静态注入 | 二选一（与私钥） | +| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 派生索引（默认 `0`） | ⚠️ 静态注入 | 可选 | --- @@ -396,19 +403,21 @@ print("Signature:", sig) ```typescript -import { resolveWalletProvider } from "@bankofai/agent-wallet"; +import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet"; // 本地模式：需要设置 AGENT_WALLET_PASSWORD const provider = resolveWalletProvider({ network: "tron:nile" }); -// 列出所有钱包 -const wallets = await provider.listWallets(); -for (const w of wallets) { - console.log(`${w.id} (${w.type})`); -} +if (provider instanceof ConfigWalletProvider) { + // 列出所有钱包 — 返回 [walletId, config, isActive] 元组数组 + const wallets = provider.listWallets(); + for (const [id, config, isActive] of wallets) { + console.log(`${id} (${config.type})${isActive ? " ← 活跃" : ""}`); + } -// 切换活跃钱包 -provider.setActive("my-evm-wallet"); + // 切换活跃钱包 + provider.setActive("my-evm-wallet"); +} // 获取并使用 const wallet = await provider.getActiveWallet(); @@ -419,15 +428,23 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello")); ```python -# 设置环境变量——resolve_wallet_provider 自动进入本地模式 -import os -os.environ["AGENT_WALLET_PASSWORD"] = "Abc12345!" - -from agent_wallet import resolve_wallet_provider +import asyncio +from agent_wallet import resolve_wallet_provider, ConfigWalletProvider +# 需要设置 AGENT_WALLET_PASSWORD provider = resolve_wallet_provider(network="tron:nile") async def main(): + if isinstance(provider, ConfigWalletProvider): + # 列出所有钱包 — 返回 [(wallet_id, config, is_active)] 元组列表 + wallets = provider.list_wallets() + for wallet_id, config, is_active in wallets: + print(f"{wallet_id} ({config.type}){' ← 活跃' if is_active else ''}") + + # 切换活跃钱包 + provider.set_active("my-evm-wallet") + + # 获取并使用 wallet = await provider.get_active_wallet() sig = await wallet.sign_message(b"Hello") print("Signature:", sig) From e88dbfcca7548d8099e4873fc1b5d1073d989e41 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 03:22:02 +0800 Subject: [PATCH 15/44] update agent-wallet --- docs/Agent-Wallet/Developer/CLI-Reference.md | 222 +++++++++++++++ .../SDK-Cookbook.md} | 15 +- .../SDK-Guide.md} | 13 +- docs/Agent-Wallet/FAQ.md | 93 ++++++- docs/Agent-Wallet/Intro.md | 53 ++-- docs/Agent-Wallet/QuickStart.md | 257 ++++++------------ .../current.json | 4 + .../Agent-Wallet/Developer/CLI-Reference.md | 221 +++++++++++++++ .../SDK-Cookbook.md} | 15 +- .../SDK-Guide.md} | 25 +- .../current/Agent-Wallet/FAQ.md | 93 ++++++- .../current/Agent-Wallet/Intro.md | 61 ++--- .../current/Agent-Wallet/QuickStart.md | 253 ++++++----------- .../current/sidebars.js | 16 +- sidebars.js | 16 +- 15 files changed, 898 insertions(+), 459 deletions(-) create mode 100644 docs/Agent-Wallet/Developer/CLI-Reference.md rename docs/Agent-Wallet/{FullExample.md => Developer/SDK-Cookbook.md} (95%) rename docs/Agent-Wallet/{SDKQuickStart.md => Developer/SDK-Guide.md} (96%) create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md rename i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/{FullExample.md => Developer/SDK-Cookbook.md} (95%) rename i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/{SDKQuickStart.md => Developer/SDK-Guide.md} (93%) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md new file mode 100644 index 00000000..a97ee24a --- /dev/null +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -0,0 +1,222 @@ +# CLI Reference + +A complete reference for every Agent-wallet command. Whether you're reviewing the basics or configuring automation scripts, you'll find the answer here. + +:::tip Just getting started? +If you haven't created a wallet yet, head to [Quick Start](../QuickStart.md) first — three steps, under a minute. +::: + +--- + +## Basic Commands + +The core operations you'll use most often — creating wallets and signing. + +### `agent-wallet start` (Initialize / Create Wallet) + +**Interactive creation (recommended):** +```bash +agent-wallet start +``` +The system walks you through choosing a wallet type, generating keys, and setting a master password. Just follow the prompts. + +**Custom password:** +```bash +agent-wallet start -p Abc12345! +``` +Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. + +**Import an existing private key:** +```bash +agent-wallet start -p Abc12345! -k your-private-key-hex +``` + +**Import a mnemonic:** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." +``` + +### `agent-wallet sign` (Core Signing Operations) + +Every `sign` subcommand requires `--network` / `-n` to specify the chain. + +**Sign a message:** +```bash +agent-wallet sign msg "Hello" -n tron +``` + +**Sign a transaction** (build the unsigned tx via RPC first): +```bash +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron +``` + +**Sign EIP-712 typed data:** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 +``` + +--- + +## Wallet Management + +Manage multiple wallets — add, switch, inspect, remove. + +**Add a new wallet:** +```bash +agent-wallet add +``` + +**List all wallets:** +```bash +agent-wallet list +``` + +**Switch the active wallet:** +```bash +agent-wallet use my-bsc-wallet +``` + +**Inspect a wallet:** +```bash +agent-wallet inspect my-bsc-wallet +``` + +**Sign with a specific wallet** (without switching the active one): +```bash +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" +``` + +**Remove a wallet:** +```bash +agent-wallet remove my-bsc-wallet +``` + +--- + +## Non-Interactive Execution (For Automation & Background Services) + +By default, signing commands pause and prompt you to type your password interactively. But if an AI agent is running in the background, or you're running an automation script, this "stop and wait for input" behavior will cause the program to hang or error out. + +To let the program run silently from start to finish (non-interactive mode), you need to pre-supply the password. Depending on your use case, there are three approaches: + +### Method A: Environment Variable Injection (Recommended for AI Agents / CI Pipelines) + +Store the password in the current system environment. When the program needs the password, it automatically retrieves it — fully silent: + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +``` + +Once set, all signing commands in the current window return results instantly, no more pausing: + +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` + +:::caution Password contains special characters? Always use single quotes +```bash +# ✅ Correct — shell treats it literally +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# ❌ Wrong — $ gets expanded by the shell, password silently breaks +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +### Method B: Local Password Cache (True "Set and Forget") + +The ultimate convenience solution. After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: + +```bash +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +``` + +### Method C: Inline `-p` Flag (For One-Off Commands) + +Pass the password directly at the end of the command. The program takes the password and runs immediately — no prompts: + +```bash +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +``` + +:::danger Security Warning +When using `-p` to pass the password inline, the plaintext password is permanently recorded in your terminal's `history`. Only use this method in fully isolated test environments! +::: + +### Custom Storage Directory + +All commands support the `--dir` flag to specify a custom encrypted safe storage path (default: `~/.agent-wallet`). For example, you can build your safe directly on an encrypted USB drive — plug and play, unplug and go: + +```bash +agent-wallet start --dir /Volumes/MyUSB/agent-wallet +agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet +``` + +--- + +## Dangerous Operations + +:::danger The following operations are irreversible — use with extreme caution! +::: + +### `agent-wallet change-password` (Change Master Password) + +After changing, **all key files are re-encrypted with the new password**. The old password becomes invalid immediately — make sure to update your password manager. + +```bash +agent-wallet change-password +``` + +### `agent-wallet reset` (Reset All Data) + +Deletes everything under `~/.agent-wallet/`. **This is a nuclear option — once executed, all wallets, keys, and configuration are permanently gone, with no recovery.** The system will ask for confirmation. + +```bash +agent-wallet reset +``` + +--- + +## Real-World Example: Signing in a Shell Script + +The CLI isn't just for manual typing — it integrates perfectly into your automation scripts. + +This minimal example demonstrates how to perform a non-interactive signing operation in a Bash script, cleanly capturing the signature result into a variable for subsequent use (no complex network request code involved): + +```bash +#!/bin/bash +# Enable strict mode: stop immediately on any error +set -e + +# 1. Pre-inject the password so all subsequent signing commands run silently +export AGENT_WALLET_PASSWORD='your-master-password' + +echo "Calling local encrypted safe for signing..." + +# 2. Core operation: execute signing, capture the hash output into the SIGNATURE variable +SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) + +# 3. Got the clean signature result — continue with downstream logic +echo "✅ Signing successful!" +echo "Extracted signature: $SIGNATURE" + +# From here, you can use $SIGNATURE to build requests, construct JSON, or pass it to other pipeline tasks... +``` + +--- + +## Next Steps + +- New to this? → [Quick Start](../QuickStart.md) +- Building your own agent? → [SDK Guide](./SDK-Guide.md) +- Looking for ready-made code? → [SDK Cookbook](./SDK-Cookbook.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/FullExample.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md similarity index 95% rename from docs/Agent-Wallet/FullExample.md rename to docs/Agent-Wallet/Developer/SDK-Cookbook.md index cec62891..d57d5556 100644 --- a/docs/Agent-Wallet/FullExample.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -1,9 +1,13 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Full Examples +# SDK Cookbook -You know how to sign. Now let's put it all together — build a transaction, sign it with Agent-wallet, and broadcast it to the network. +:::tip Why read this page? +In the [SDK Guide](./SDK-Guide.md), you learned how to use Agent-wallet for "offline signing." But in real-world scenarios, an AI agent can't just sign — it needs to: **1. Query the node to build a transaction → 2. Agent-wallet signs → 3. Broadcast to the blockchain.** + +Agent-wallet focuses on doing the core secure signing step (step 2) well. This page provides a set of **"ready-to-use"** complete scripts that combine TronGrid and Ethers.js / Web3.py to walk you through the full end-to-end flow. You can copy these scripts directly into your production environment! +::: This page walks through three real-world scenarios end to end: sending TRX on TRON, sending BNB on BSC, and signing an x402 payment permit. Each example is complete and runnable — copy, configure your addresses, and go. @@ -15,7 +19,7 @@ All examples are available in both TypeScript and Python — use the tabs to swi Before running any example below, make sure you have: -1. Installed the Agent-wallet SDK (see [SDK Quick Start](./SDKQuickStart.md)) +1. Installed the Agent-wallet SDK (see [SDK Guide](./SDK-Guide.md)) 2. Initialized a local wallet via the CLI, or configured static mode environment variables 3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) @@ -512,6 +516,7 @@ The x402 SDK automatically constructs the PaymentPermit data and calls the signi ## Next Steps -- Review the full signing API reference → [SDK Quick Start](./SDKQuickStart.md) +- Prefer the command line? → [CLI Reference](./CLI-Reference.md) +- Building your own agent? → [SDK Guide](./SDK-Guide.md) - Learn how x402 and Agent-wallet work together → [x402 Introduction](../../x402/index.md) -- Browse common questions → [FAQ](./FAQ.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/SDKQuickStart.md b/docs/Agent-Wallet/Developer/SDK-Guide.md similarity index 96% rename from docs/Agent-Wallet/SDKQuickStart.md rename to docs/Agent-Wallet/Developer/SDK-Guide.md index ba8ffdbe..b3012a9f 100644 --- a/docs/Agent-Wallet/SDKQuickStart.md +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -1,14 +1,14 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# SDK Quick Start +# SDK Guide You've tried the CLI and can sign from the command line. Now you want signing inside your own code — an MCP Server, an automation script, an AI agent workflow. This page shows you how. By the end, you'll be able to initialize a wallet provider, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data — all in a few lines of TypeScript or Python. :::tip New here? -If you haven't created a wallet yet, start with the [CLI Quick Start](./QuickStart.md) first (Steps 1–3 take under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. +If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md) first (Steps 1–3 take under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. ::: Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch. @@ -145,7 +145,7 @@ It supports two modes: ### 🛡️ Core Usage: Local Vault Mode (Strongly Recommended) -If you've already followed the [CLI Quick Start](./QuickStart.md), your private key is already safely locked inside a hidden file on your machine. +If you've already followed the [Quick Start](../QuickStart.md), your private key is already safely locked inside a hidden file on your machine. **In this mode, you never need to (and shouldn't) touch your plaintext private key.** Just tell the SDK your "unlock password" and you're good to go. @@ -525,6 +525,7 @@ WalletError ## Next Steps -- Manage wallets from the command line → [CLI Quick Start](./QuickStart.md) -- Understand Agent-wallet's design → [Introduction](./Intro.md) -- Browse common questions → [FAQ](./FAQ.md) +- Prefer the command line? → [CLI Reference](./CLI-Reference.md) +- Looking for ready-made code? → [SDK Cookbook](./SDK-Cookbook.md) +- Understand Agent-wallet's design → [Introduction](../Intro.md) +- Common questions → [FAQ](../FAQ.md) diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index eaafbcf2..aaff89b0 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -56,6 +56,14 @@ A purely local encrypted signing tool. It does two things: 1) encrypts and store Most users don't need the SDK. If you're using OpenClaw and MCP Server, creating a wallet with the CLI and setting the environment variable is all you need. The SDK is for developers building their own agents. +### What's the difference between Agent-wallet and MetaMask? + +MetaMask is a browser wallet designed for humans, with a graphical interface that requires you to manually click "Confirm" for every signature. Agent-wallet is a command-line wallet designed for AI agents, purpose-built for non-interactive use — AI can silently invoke signing in the background without anyone watching the screen. Both use similar encryption under the hood (Keystore V3), but they serve completely different use cases. + +### How many wallets can I create on one machine? + +No limit. You can create separate wallets for different AI agents, different chains, or different purposes. Use `agent-wallet add` to create and `agent-wallet use` to switch between them. + --- ## Wallet Types @@ -93,17 +101,17 @@ The difference is enormous! It's the difference between leaving cash on the tabl When you use a Web3 wallet like MetaMask, you never copy-paste your raw private key every time — you unlock it with a short password. Agent-wallet is essentially a command-line MetaMask built for AI agents. -* Traditional approach (plaintext private key): It's like leaving cash right on the table. Any malicious browser extension, one careless code commit, or a background log scan — one glance at your `.env` file and the money is gone instantly. A classic single point of failure. +* Traditional approach (plaintext private key): It's like leaving cash right on the table. Any malicious browser extension, one careless code commit, or a background log scan — one glance at your environment variables and the money is gone instantly. A classic single point of failure. * Agent-wallet approach: It splits the risk into two locks. 1. Physical safe: Your private key is encrypted with industry-grade algorithms and locked in a hidden folder deep in your system (`~/.agent-wallet`). - 2. Unlock password: What you put in your environment variable (`.env`) is merely the password to open this safe. + 2. Unlock password: What you put in your environment variable is merely the password to open this safe. This means if a leak occurs: * If a hacker only steals your password (e.g., by scanning environment variables), they don't have your encrypted wallet file — the password is just a useless string. * If a hacker only steals your encrypted wallet file, they don't have your master password — the file is uncrackable gibberish that would take millennia to brute-force. -A hacker would need to simultaneously break into your computer, locate and steal the hidden wallet file, AND steal the password from your environment variables to touch your funds. The difficulty of this attack is orders of magnitude higher than simply scanning a `.env` file! +A hacker would need to simultaneously break into your computer, locate and steal the hidden wallet file, AND steal the password from your environment variables to touch your funds. The difficulty of this attack is orders of magnitude higher than simply scanning environment variables! ### Does the private key ever leave my machine? @@ -114,7 +122,54 @@ Never. Agent-wallet makes zero network requests. Zero RPC calls, zero cloud serv - ✅ Use a password manager (1Password, Bitwarden) - ✅ Pass it via the `AGENT_WALLET_PASSWORD` environment variable - ❌ Don't hardcode it in source code -- ❌ Don't commit a `.env` containing the password to git +- ❌ Don't commit environment variable files containing the password to git + +### Is the encryption algorithm secure? Can it be brute-forced? + +Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), the exact same encryption scheme used by official Ethereum wallets. The scrypt algorithm is specifically designed to make brute-force attacks extremely expensive in both computation and memory — even with dedicated hardware, cracking a strong password would take tens of thousands of years. + +--- + +## Installation & Environment + +### What operating systems are supported? + +macOS, Linux, and Windows (via WSL) are all supported. As long as you can run Node.js >= 18 or Python >= 3.11, you're good to go. + +### `npm install -g` gives a permission error? + +This is common on macOS / Linux. Two solutions: + +**Method 1 (Recommended): Use nvm to manage Node.js** — it installs global packages in your user directory, no `sudo` needed. + +**Method 2: Fix npm global directory permissions:** +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc +source ~/.zshrc +``` + +### I configured the password but AI says "wallet not found" or "wrong password"? + +The three most common causes: + +1. **Password didn't take effect**: You ran `export` in Terminal A, but the AI runs in Terminal B. Solution: restart the AI backend service (see [Quick Start](./QuickStart.md) Step 2). +2. **Shell ate the password**: A password wrapped in double quotes contains `$` or `!`, which the shell expanded. Solution: switch to single quotes. +3. **Wrong storage directory**: You previously used `--dir` to specify a custom path, but the AI is looking at the default path. Solution: `export AGENT_WALLET_DIR="/your/custom/path"`. + +### `agent-wallet` command not found? + +The global installation didn't take effect. Check: +```bash +# Confirm the npm global bin directory is in your PATH +npm bin -g +``` +If the output path isn't in your `$PATH`, add it manually: +```bash +echo "export PATH=$(npm bin -g):$PATH" >> ~/.zshrc +source ~/.zshrc +``` --- @@ -130,9 +185,31 @@ Identical. Same private key + same data = same signature. --- -## What's Next +## OpenClaw Integration + +### Is OpenClaw required? + +No. Agent-wallet is a standalone signing tool that can be used independently via CLI or SDK. OpenClaw is simply the most convenient frontend — it lets you invoke signing using natural language, without writing any code. + +### OpenClaw says "signing failed" or "wallet not connected"? + +Troubleshoot in this order: + +1. Confirm the `AGENT_WALLET_PASSWORD` environment variable is set (run `echo $AGENT_WALLET_PASSWORD` in the terminal where OpenClaw is running) +2. Confirm the MCP Server was started **after** the environment variable was set +3. Confirm a wallet has been initialized: `agent-wallet list` should show at least one wallet +4. If everything above checks out, try signing manually via CLI: `agent-wallet sign msg "test" -n tron` + +### Does signing in OpenClaw cost gas fees? + +Signing itself costs zero gas. Signing is purely a local cryptographic operation using your private key — it's completed entirely on your machine. Gas fees are only incurred when a signed transaction is broadcast to the blockchain. Operations like checking addresses or signing messages are always free. + +--- + +## Next Steps -- Set up your full environment → [CLI Quick Start](./QuickStart.md) -- Sign from code → [SDK Quick Start](./SDKQuickStart.md) -- See real transfer examples → [Full Examples](./FullExample.md) +- Never written code? → [Quick Start](./QuickStart.md) +- Prefer the command line? → [CLI Reference](./Developer/CLI-Reference.md) +- Building your own agent? → [SDK Guide](./Developer/SDK-Guide.md) +- Looking for ready-made code? → [SDK Cookbook](./Developer/SDK-Cookbook.md) - Learn about OpenClaw Extension → [OpenClaw Introduction](../Openclaw-extension/Intro.md) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 3ba8c775..e0de6b3b 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -6,19 +6,19 @@ You want your AI agent to handle on-chain work automatically — airdrop farming, token swaps, paying gas fees, scheduled transfers. To do any of that, the agent needs a "key" (your private key) to sign transactions on your behalf. -So you drop it into a `.env` file. +So you put your private key into your environment variables. **That's like writing your bank card number and PIN on a sticky note and walking into a room full of strangers.** -That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read your `.env` file. Your private key has no password protection, no encryption, no access control — it's just plaintext, one file read away from being gone. +That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read your environment variables. Your private key has no password protection, no encryption, no access control — it's just plaintext, one read away from being gone. --- ### This Isn't Hypothetical — It's Already Happening -- **Dependency chain poisoning.** You install a useful MCP server. Three months later, one of its 200 npm dependencies gets a malicious update — quietly scanning all `.env` and `*.json` files for anything that looks like a private key, then sending it out. You never see it happen. By the time you notice, your wallet is empty. +- **Dependency chain poisoning.** You install a useful MCP server. Three months later, one of its 200 npm dependencies gets a malicious update — quietly scanning all files for anything that looks like a private key, then sending it out. You never see it happen. By the time you notice, your wallet is empty. -- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your `.env` is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. +- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your environment variable file is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. - **Git's perfect memory.** You hardcoded a key during development and deleted it later. But you committed it once, three weeks ago. It's still in `git log -p`. If that repo ever touched GitHub, even for 30 seconds, automated scrapers already found it. @@ -45,7 +45,7 @@ This is the most elegant part of Agent-wallet: **a leaked password ≠ stolen as If a hacker steals only your password through a malicious plugin, they can't do anything — because they don't have your encrypted wallet file. If they steal only the wallet file without the password, it's just uncrackable gibberish. -**A hacker would need to simultaneously break into your system, locate the hidden wallet file, AND steal the password from your environment variables to touch your funds.** The difficulty and cost of this kind of attack is orders of magnitude higher than simply scanning a plaintext private key in a `.env` file! +**A hacker would need to simultaneously break into your system, locate the hidden wallet file, AND steal the password from your environment variables to touch your funds.** The difficulty and cost of this kind of attack is orders of magnitude higher than simply scanning a plaintext private key in environment variables! **Bottom line: steal the file — it's useless without the password. Leak the password — it's useless without the file.** @@ -53,12 +53,12 @@ If a hacker steals only your password through a malicious plugin, they can't do ## How It Compares -| | Traditional (plaintext key in `.env`) | Cloud wallet | 🛡️ Agent-wallet Local Vault | -| :--- | :--- | :--- | :--- | -| **How it works** | Hand your card and PIN directly to the AI | Store your money on someone else's server | **Give AI the password, file stays locked locally** | -| **Log / env variable leak** | ❌ **Total loss** | ⚠️ Key is remote, still hackable | ✅ **Only the password leaks — no file, hacker gets nothing** | -| **Encrypted file stolen** | — | — | ✅ **No password, hacker can't open the file** | -| **Works offline?** | ⚠️ Depends | ❌ Must be online | ✅ **100% offline signing** | +| | :x: Traditional (plaintext key in environment variables) | :white_check_mark: Agent-wallet Local Encrypted Safe | +| :--- | :--- | :--- | +| **How it works** | :x: Hand your card and PIN directly to the AI | :white_check_mark: **Give AI the password, file stays locked locally** | +| **Log / env variable leak** | :rotating_light: **Total loss** | :shield: **Only the password leaks — no file, hacker gets nothing** | +| **Encrypted file stolen** | :x: Plaintext key, stolen instantly | :shield: **No password, hacker can't open the file** | +| **Works offline?** | :warning: Depends | :white_check_mark: **100% offline signing** | --- @@ -84,7 +84,7 @@ agent-wallet sign msg "Hello from my AI agent" -n tron When a hash string appears on screen — congratulations, your encrypted safe is live. -> Want the full step-by-step walkthrough? Head to **[Quick Setup — CLI Quick Start](./QuickStart.md)**. +> Want the full step-by-step walkthrough? Head to **[CLI Reference](./Developer/CLI-Reference.md)**. --- @@ -96,27 +96,19 @@ Pick the path that fits you: ### 🎮 I'm a casual user — using existing tools -No code required. Many AI tools natively support Agent-wallet (we **strongly recommend our [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)** — one-click install, works out of the box). All you need to do is tell the tool your master password: +No code required. We **strongly recommend our [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. All you need to do is one thing — tell the tool your master password: ```bash export AGENT_WALLET_PASSWORD='your-master-password' ``` -:::caution Password contains special characters? Always use single quotes -Auto-generated passwords often include `$`, `!`, and other shell-special characters. **Wrap in single quotes** or the shell will silently mangle the value: +Once set, your tools automatically call your Agent-wallet encrypted safe to sign. Your private key stays encrypted throughout — the tool only ever receives the signature result, never the key itself. -```bash -# ✅ Correct -export AGENT_WALLET_PASSWORD='P@ss$w0rd!' - -# ❌ Wrong -export AGENT_WALLET_PASSWORD="P@ss$w0rd!" -``` -::: +> Want the step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. -Once set, your tools automatically call your Agent-wallet encrypted safe to sign. The tool only ever receives the signature result — never the private key itself. +### 🛠️ I'm an advanced user — managing wallets via CLI -> Want to see supported tools? Go to **[OpenClaw Extension](../Openclaw-extension/Intro.md)**. +Need password-free signing, managing multiple wallets, or custom storage directories? Head to **[CLI Reference](./Developer/CLI-Reference.md)**. ### 🛠️ I'm a developer — building my own agent @@ -135,8 +127,8 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); Same key file, same data, same signature — across both languages. -> **[SDK Quick Start](./SDKQuickStart.md)** — step-by-step integration guide. -> **[Full Examples](./FullExample.md)** — end-to-end real transactions: TRON transfers, BSC transfers, x402 payment signing. +> **[SDK Guide](./Developer/SDK-Guide.md)** — step-by-step integration guide. +> **[SDK Cookbook](./Developer/SDK-Cookbook.md)** — end-to-end real transactions: TRON transfers, BSC transfers, x402 payment signing. @@ -158,6 +150,7 @@ Both chain types share the same interface — learn it once, use it everywhere. | I'm wondering… | Go here | | :--- | :--- | | Will AI drain my wallet? | [FAQ](./FAQ.md) — we have a dedicated risk isolation solution | -| Ready to set it up now | [Quick Setup — CLI Quick Start](./QuickStart.md) | -| Want to use it in code | [SDK Quick Start](./SDKQuickStart.md) | -| Want to see real transaction examples | [Full Examples](./FullExample.md) | +| Never written code? | [Quick Start](./QuickStart.md) | +| Prefer the command line? | [CLI Reference](./Developer/CLI-Reference.md) | +| Building your own agent? | [SDK Guide](./Developer/SDK-Guide.md) | +| Looking for ready-made code? | [SDK Cookbook](./Developer/SDK-Cookbook.md) | diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 839a3971..0bdc2725 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -1,84 +1,68 @@ -# CLI Quick Start +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -Four steps, from zero to your first signature. The whole thing takes under a minute — just copy and paste. +# Quick Start -:::tip Already a developer? -If you want to call signing directly from TypeScript or Python code, skip to [SDK Quick Start](./SDKQuickStart.md). +Three steps, from zero to invoking your encrypted safe in the OpenClaw chat box. No coding required, no gas fees — just copy and paste. + +:::tip Want CLI command details? +This page only walks you through the shortest path. For password-free configuration, managing multiple wallets, signature types, and other advanced topics, see the [CLI Reference](./Developer/CLI-Reference.md). ::: --- -## 🧰 Step 1: Set Up Your Environment +## Step 1: Install and Initialize Your Wallet + +### 1.1 Prepare Your Environment: Install Node.js + +Agent-wallet requires Node.js (a runtime environment, version >= 18) on your computer. -Agent-wallet CLI requires Node.js ≥ 18. Check what you have: +Open a terminal (Mac users press `Command + Space` and search for "Terminal"; Windows users search for "cmd" or "PowerShell"), then type: ```bash node -v ``` -Output is `v18.x.x` or higher? Jump to Step 2. Nothing installed or version too old? Follow the steps below: +- **If the output shows `v18.x.x` or higher:** Great, skip straight to 1.2! +- **If there's no output or an error:** Don't panic — go to the **[Node.js official website](https://nodejs.org)** and download the latest **LTS** installer. Install it like any regular software — double-click and follow the prompts. After installation, close and reopen your terminal, then run `node -v` again to confirm. -:::tip Install / upgrade Node.js +
+Developer preferred: Install via nvm (beginners can skip this) -We recommend [nvm](https://github.com/nvm-sh/nvm) — one command handles everything: - -**1 — Install nvm** (skip if already installed): ```bash +# 1. Install nvm (skip if already installed) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash -``` -**2 — Reload your shell config:** -```bash +# 2. Reload your terminal config source ~/.bashrc # zsh users: source ~/.zshrc -``` - -**3 — Install Node.js 18:** -```bash -nvm install 18 -``` -**4 — Switch to Node.js 18:** -```bash -nvm use 18 +# 3. Install and switch to Node.js 18 +nvm install 18 && nvm use 18 ``` -Or download the LTS installer directly from [nodejs.org](https://nodejs.org). -::: - ---- - -## 📦 Step 2: Install Agent-wallet +
-One command: +### 1.2 Install Agent-wallet ```bash npm install -g @bankofai/agent-wallet ``` -Python users can also install via pip: -```bash -pip install bankofai-agent-wallet -``` - -Verify the install worked: +Verify the installation: ```bash agent-wallet --help ``` If you see the help output, you're good to go. ---- - -## 🔐 Step 3: Create Your Personal Encrypted Safe +### 1.3 Create Your Encrypted Safe Run: ```bash agent-wallet start ``` -This initializes your **Agent-wallet encrypted safe**. The process is interactive — just follow the prompts. - -If you don't specify a password manually (the `-p` flag), the system auto-generates a strong one and shows it once: +The system will guide you through initializing your **Agent-wallet encrypted safe**. The process is interactive — just follow the prompts: ``` ? Quick start type: local_secure — Encrypted key stored locally (recommended) @@ -100,7 +84,7 @@ Your master password: WiJxcI#t6@73K#OE Active wallet: default ``` -:::caution ⚠️ Master password = the only key to all your assets +:::caution Master password = the only key to all your assets This password is the sole credential for decrypting all your private keys. **Lose it and it's gone forever — no backup, no backdoor, no recovery.** Do this right now: @@ -109,182 +93,103 @@ Do this right now: 3. Don't screenshot it, don't put it in a desktop sticky note, don't text it to yourself ::: -**Want to set your own password?** -```bash -agent-wallet start -p Abc12345! -``` -Requirements: at least 8 characters, with uppercase, lowercase, numbers, and special characters. +--- -**Already have a private key to import?** -```bash -agent-wallet start -p Abc12345! -k your-private-key-hex -``` +## Step 2: Feed the Password to Your AI (Critical!) -**Have a mnemonic phrase?** -```bash -agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." -``` +For OpenClaw to automatically use your wallet, you must configure the password in its runtime environment. Select the tab matching your operating system and **just copy-paste**: ---- +### 2.1 Permanently Save and Activate the Password -## ✨ Step 4: Your First Test Signature + + -The exciting moment — run: +**Step 1:** Copy the command below, replace the content inside the single quotes with your actual password, paste it into the terminal and press Enter: ```bash -agent-wallet sign msg "Hello from my AI agent" -n tron +echo "export AGENT_WALLET_PASSWORD='your-master-password'" >> ~/.zshrc ``` -You'll be prompted for your master password, then see output like: - -```text -Master password: ******** -Signature: 4a9c8f...e71b -``` - -**When that hash string appears on screen — congratulations, your encrypted safe is live!** 🎉 - -Your private key is encrypted on disk. That signature just happened entirely on your local machine, with zero data sent over the network. - ---- - -## 🚀 Quick Start Done! What's Next? - -| I want to… | Do this | -| :--- | :--- | -| Connect my wallet to AI tools | Set `export AGENT_WALLET_PASSWORD='your-password'`, see [Introduction](./Intro.md) | -| Sign from my own code | Go to [SDK Quick Start](./SDKQuickStart.md) | -| See a complete transfer example | Go to [Full Examples](./FullExample.md) | -| Browse the full command reference | ↓ Keep reading | - ---- - -## Command Reference - -Everything you'll need day-to-day after the quick start. Look things up as needed. - -### Password-free Signing - -Typing your password interactively every time? That's a non-starter for automation. Three ways to skip it: +**Step 2:** Copy this command, paste and press Enter to apply the config immediately: -**Option A — Environment variable** (recommended for CI / agent pipelines): ```bash -export AGENT_WALLET_PASSWORD='Abc12345!' -``` -Once set, all signing commands run silently: -```bash -agent-wallet sign msg "Hello" -n tron -agent-wallet sign tx '{"txID":"..."}' -n tron +source ~/.zshrc ``` -:::caution Password contains special characters? Always use single quotes -```bash -# ✅ Correct — shell treats it literally -export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + + -# ❌ Wrong — $ gets expanded by the shell, password silently breaks -export AGENT_WALLET_PASSWORD="P@ss$w0rd!" -``` -::: +**Step 1:** Copy the command below, replace the content inside the single quotes with your actual password, paste it into the terminal and press Enter: -**Option B — Inline `-p`** (one-off use): ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +echo "export AGENT_WALLET_PASSWORD='your-master-password'" >> ~/.bashrc ``` -**Option C — `--save-runtime-secrets`** (saves password to `~/.agent-wallet/runtime_secrets.json` for auto-loading): +**Step 2:** Copy this command, paste and press Enter to apply the config immediately: + ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +source ~/.bashrc ``` -### Signature Types + + -Every `sign` subcommand requires `--network` / `-n` to specify the chain: +:::caution Password has special characters? Don't touch the single quotes! +Auto-generated passwords often contain `$`, `!`, and other special characters. The commands above already use single quotes to wrap the password — **just replace the text inside the quotes, never switch to double quotes**, or the shell will silently mangle the value: -**Sign a message:** ```bash -agent-wallet sign msg "Hello" -n tron -``` +# ✅ Correct — single quotes, password saved as-is +echo "export AGENT_WALLET_PASSWORD='P@ss$w0rd!'" >> ~/.zshrc -**Sign a transaction** (build the unsigned tx via RPC first): -```bash -agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron +# ❌ Wrong — double quotes around password, $ gets expanded by shell, password silently breaks +echo "export AGENT_WALLET_PASSWORD=\"P@ss$w0rd!\"" >> ~/.zshrc ``` +::: -**Sign EIP-712 typed data:** -```bash -agent-wallet sign typed-data '{ - "types": { - "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], - "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] - }, - "primaryType": "Transfer", - "domain": {"name":"MyDApp","chainId":1}, - "message": {"to":"0x7099...","amount":1000000} -}' -n eip155:1 -``` +### 2.2 Restart Your AI Backend Service -### Managing Multiple Wallets +:::danger Many people forget this step, then wonder why AI can't find the password! +You just saved a new password, but the AI assistant running in the background hasn't refreshed yet — it's still blind to the change! You need to shut it down and restart it for the new password to take effect. +::: -**Add a new wallet:** -```bash -agent-wallet add -``` +Whether or not you currently have the OpenClaw backend service running, make sure to **shut it down**, then **restart it** from the same terminal window where you ran the commands above. -**Switch the active wallet:** -```bash -agent-wallet use my-bsc-wallet -``` - -**Sign with a specific wallet** (without switching the active one): -```bash -agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" -``` +--- -**Inspect a wallet:** -```bash -agent-wallet inspect my-bsc-wallet -``` +## Step 3: Wake Up Your Encrypted Safe in OpenClaw -**List all wallets:** -```bash -agent-wallet list -``` +Your safe is ready, the password is configured. Now open **OpenClaw** and test whether it can successfully invoke your local encrypted safe — just like chatting with a real person. -**Remove a wallet:** -```bash -agent-wallet remove my-bsc-wallet -``` +:::info Haven't installed OpenClaw Extension yet? +Head to [OpenClaw Extension Quick Start](../Openclaw-extension/QuickStart.md) first, then come back here. +::: -### Change Master Password +### Zero-Risk Test 1: Check Your Address -All key files are re-encrypted with the new password: +Type in the chat box: -```bash -agent-wallet change-password -``` +> Show me the wallet address currently bound to my local wallet (TRON network). -### Reset Everything +The AI will automatically read your encrypted safe and report back the wallet address you just created. **This proves the password configuration is working correctly!** -Deletes all contents under `~/.agent-wallet/`. **Irreversible** — requires confirmation: +### Zero-Risk Test 2: Let AI Sign for You -```bash -agent-wallet reset -``` +Then say: -### Custom Storage Directory +> Sign this message with my wallet: "Hello Agent-wallet!" -All commands support `--dir` to specify a custom key storage path (default: `~/.agent-wallet`): +The AI will complete the signing locally and offline, returning a hash string. -```bash -agent-wallet start --dir ./my-secrets -agent-wallet sign msg "Hello" --dir ./my-secrets -``` +**Congratulations!** You didn't spend a single cent on gas fees, you never touched your private key, but you've successfully given your AI secure cryptographic signing capability. --- -## What's Next +## You've Completed the Full Flow -- Connect AI tools to your wallet → [Introduction — casual user path](./Intro.md) -- Sign from code → [SDK Quick Start](./SDKQuickStart.md) -- Browse common questions → [FAQ](./FAQ.md) +| I want to… | Go here | +| :--- | :--- | +| Use CLI for advanced operations | [CLI Reference](./Developer/CLI-Reference.md) | +| Build my own agent with code | [SDK Guide](./Developer/SDK-Guide.md) | +| Find ready-made code examples | [SDK Cookbook](./Developer/SDK-Cookbook.md) | +| Understand the security design | [Introduction](./Intro.md) | +| Check common questions | [FAQ](./FAQ.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index 4de059a6..d33a3c60 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -67,5 +67,9 @@ "sidebar.docsSidebar.category.API": { "message": "API 参考", "description": "The label for category API in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Developer": { + "message": "开发者", + "description": "The label for category Developer in sidebar docsSidebar" } } diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md new file mode 100644 index 00000000..05d12f7d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -0,0 +1,221 @@ +# CLI 命令行手册 + +包含了 Agent-wallet 所有命令的完整参考。无论你是想复习基础操作，还是想配置自动化脚本，这里都有答案。 + +:::tip 刚刚入门？ +如果你还没创建过钱包，先去 [快速开始](../QuickStart.md) 走一遍——三步搞定，不到一分钟。 +::: + +--- + +## 基础命令 + +高频使用的核心操作——创建钱包和签名。 + +### `agent-wallet start`（初始化 / 创建钱包） + +**交互式创建（推荐）：** +```bash +agent-wallet start +``` +系统会一步步引导你选择钱包类型、生成密钥、设置主密码。跟着提示走就行。 + +**自定义密码：** +```bash +agent-wallet start -p Abc12345! +``` +密码要求：至少 8 位，包含大写、小写、数字和特殊字符。 + +**导入已有私钥：** +```bash +agent-wallet start -p Abc12345! -k 你的私钥十六进制 +``` + +**导入助记词：** +```bash +agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." +``` + +### `agent-wallet sign`（核心签名操作） + +每条 `sign` 子命令都需要 `--network` / `-n` 来指定链。 + +**签名消息：** +```bash +agent-wallet sign msg "Hello" -n tron +``` + +**签名交易**（需要先通过 RPC 构建未签名交易）： +```bash +agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron +``` + +**签名 EIP-712 结构化数据：** +```bash +agent-wallet sign typed-data '{ + "types": { + "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], + "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] + }, + "primaryType": "Transfer", + "domain": {"name":"MyDApp","chainId":1}, + "message": {"to":"0x7099...","amount":1000000} +}' -n eip155:1 +``` + +--- + +## 钱包管理 + +管理多个钱包——添加、切换、查看、删除。 + +**添加新钱包：** +```bash +agent-wallet add +``` + +**列出所有钱包：** +```bash +agent-wallet list +``` + +**切换活跃钱包：** +```bash +agent-wallet use my-bsc-wallet +``` + +**查看钱包详情：** +```bash +agent-wallet inspect my-bsc-wallet +``` + +**用指定钱包签名**（不切换活跃钱包）： +```bash +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" +``` + +**删除钱包：** +```bash +agent-wallet remove my-bsc-wallet +``` + +--- + +## 非交互式执行（专为自动化与后台设计） + +默认情况下，执行签名命令时，终端会停下来并出现一行提示，等待你手动敲击键盘输入密码。但如果是 AI 代理在后台运行，或者你在跑自动化脚本，这种"中途停下来等人输入"的机制会导致程序直接卡死报错。 + +为了让程序能一口气静默跑完（非交互模式），你需要提前把密码"喂"给命令。根据你的使用场景，有以下三种方式： + +### 方式 A：环境变量注入（推荐用于 AI 代理 / CI 流水线） + +将密码提前存在当前系统环境里，程序运行需要密码时会自动去环境里拿，全程静默： + +```bash +export AGENT_WALLET_PASSWORD='Abc12345!' +``` + +设置后，当前窗口的所有签名命令直接秒出结果，不再停顿等待： + +```bash +agent-wallet sign msg "Hello" -n tron +agent-wallet sign tx '{"txID":"..."}' -n tron +``` + +:::caution 密码有特殊字符？务必用单引号 +```bash +# 正确 — shell 按字面意思处理 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + +# 错误 — $ 被 shell 展开，导致密码在后台静默报错 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" +``` +::: + +### 方式 B：密码本地缓存（真正的"一劳永逸"） + +这是最省事的终极方案。执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： + +```bash +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +``` + +### 方式 C：命令行内联 `-p`（适合临时跑单次指令） + +直接把密码写在命令的结尾。程序拿到密码就直接干活，不会再停下来问你： + +```bash +agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +``` + +:::danger 安全提示 +直接用 `-p` 传递密码时，明文密码会被永久留在你电脑的终端 `history`（历史记录）中。强烈建议仅在完全隔离的测试环境中使用此方法！ +::: + +### 自定义存储目录 + +所有命令都支持 `--dir` 参数来指定加密保险箱的存储路径（默认在 `~/.agent-wallet`）。比如，你可以把保险箱直接建在加密 U 盘里，即插即用，拔下即走： + +```bash +agent-wallet start --dir /Volumes/MyUSB/agent-wallet +agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet +``` + +--- + +## 危险操作 + +:::danger 以下操作不可逆，请谨慎使用！ +::: + +### `agent-wallet change-password`（修改主密码） + +修改后，**所有密钥文件会用新密码重新加密**。旧密码立即失效，请确保已在密码管理器中更新。 + +```bash +agent-wallet change-password +``` + +### `agent-wallet reset`（重置所有数据） + +删除 `~/.agent-wallet/` 下的所有内容。**这是核弹级操作——一旦执行，所有钱包、密钥、配置全部消失，无法恢复。** 系统会要求二次确认。 + +```bash +agent-wallet reset +``` + +--- + +## 实战：在 Shell 脚本中调用签名 + +CLI 不只是拿来手敲的——它可以完美嵌入你的自动化脚本。 + +下面这个极简示例展示了如何在 Bash 脚本中完成一次非交互式签名，并把签名结果干净地存入变量，供后续业务使用（不涉及复杂的网络请求代码）： + +```bash +#!/bin/bash +# 开启严格模式：遇到报错立刻停止 +set -e + +# 1. 提前注入密码，让后续的签名命令全程静默无弹窗 +export AGENT_WALLET_PASSWORD='你的主密码' + +echo "正在调用本地保险箱签名..." + +# 2. 核心操作：执行签名，并将终端打印出的哈希结果直接存入 SIGNATURE 变量 +SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) + +# 3. 拿到干净的签名结果，继续后续流程 +echo "✅ 签名成功！" +echo "提取到的签名内容是: $SIGNATURE" + +# 接下来，你可以拿这个 $SIGNATURE 去发请求、拼 JSON，或者传给其他流水线任务... +``` +--- + +## 下一步 + +- 没写过代码？ → [快速上手](../QuickStart.md) +- 要开发应用？ → [SDK 接入指南](./SDK-Guide.md) +- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md similarity index 95% rename from i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md rename to i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index 43fa5d1d..7750bf4b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FullExample.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -1,9 +1,13 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# 完整示例 +# 完整代码示例 -签名会了，现在把所有环节串起来——构建交易、用 Agent-wallet 签名、广播上链。 +:::tip 为什么要看这个页面？ +在 [SDK 快速开始](./SDK-Guide.md) 中，你已经学会了如何让 Agent-wallet 完成"离线签名"。但在真实的业务中，AI 代理不能只会签名。它需要：**1. 去节点查数据构建交易 → 2. Agent-wallet 签名 → 3. 广播上链。** + +Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页为你提供了一套**"开箱即用"**的完整脚本，结合了 TronGrid 和 Ethers.js / Web3.py，带你跑通真正的全链路闭环。你可以直接复制这些代码用于你的生产环境！ +::: 本页走完三个真实场景的完整流程：在 TRON 发送 TRX、在 BSC 发送 BNB、签名 x402 支付许可。每个示例都可以直接运行——复制代码、填入你的地址，就能跑。 @@ -15,7 +19,7 @@ import TabItem from '@theme/TabItem'; 运行以下任何示例之前，确保已经完成： -1. 安装 Agent-wallet SDK（详见 [SDK 快速开始](./SDKQuickStart.md)） +1. 安装 Agent-wallet SDK（详见 [SDK 接入指南](./SDK-Guide.md)） 2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量 3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） @@ -512,6 +516,7 @@ x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不 ## 下一步 -- 查看完整签名 API 参考 → [SDK 快速开始](./SDKQuickStart.md) +- 喜欢敲命令？ → [CLI 命令行手册](./CLI-Reference.md) +- 要开发应用？ → [SDK 接入指南](./SDK-Guide.md) - 了解 x402 与 Agent-wallet 如何配合 → [x402 简介](../../x402/index.md) -- 查看常见问题 → [常见问题](./FAQ.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md similarity index 93% rename from i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md rename to i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md index 374aac90..9cf94c1b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/SDKQuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md @@ -1,14 +1,14 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# SDK 快速开始 +# SDK 接入指南 CLI 已经跑通了，能从命令行签名。现在你想把签名能力放进代码里——MCP Server、自动化脚本、AI 代理工作流。 本页教你怎么做。完成后，你就能用几行 TypeScript 或 Python 初始化钱包 Provider、获取活跃钱包，并对消息、交易、EIP-712 结构化数据进行签名。 :::tip 刚刚入门？ -如果还没创建过钱包，先去 [CLI 快速开始](./QuickStart.md) 走一遍（前三步不到一分钟）。SDK 读取的就是 CLI 创建的那个钱包——不需要重复配置任何东西。 +如果还没创建过钱包，先去 [快速上手](../QuickStart.md) 走一遍（不到一分钟）。SDK 读取的就是 CLI 创建的那个钱包——不需要重复配置任何东西。 ::: 文档提供 TypeScript 和 Python 两个版本的安装说明和代码示例，点击标签页切换。 @@ -143,9 +143,9 @@ python3 -c "import agent_wallet; print('Installation successful')" 它支持以下两种模式： -### 🛡️ 核心用法：本地金库模式（强烈推荐） +### 🛡️ 核心用法：本地加密保险箱模式（强烈推荐） -如果你刚才已经跟着 [CLI 快速开始](./QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。 +如果你刚才已经跟着 [快速上手](../QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。 **在这个模式下，你根本不需要（也不应该）接触明文私钥。** 你只需要告诉 SDK 你的"开箱密码"即可。 @@ -169,7 +169,7 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ### ⚠️ 备用方案：静态注入模式（仅限测试环境） -如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地金库，直接把私钥喂给 SDK。 +如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地加密保险箱，直接把私钥喂给 SDK。 ```bash export AGENT_WALLET_PRIVATE_KEY="你的私钥十六进制" @@ -178,19 +178,19 @@ export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." ``` :::danger 极度危险：违背核心安全原则！ -静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地金库模式。 +静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地加密保险箱模式。 ::: :::tip 环境变量冲突怎么办？ -如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地金库模式，忽略明文私钥。 +如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地加密保险箱模式，忽略明文私钥。 ::: ### 环境变量速查 | 变量名 | 用途 | 模式 | 是否必填 | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地金库 | 核心必填 | -| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地金库 | 可选 | +| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地加密保险箱 | 核心必填 | +| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地加密保险箱 | 可选 | | `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（十六进制） | ⚠️ 静态注入 | 二选一（与助记词） | | `AGENT_WALLET_MNEMONIC` | 明文助记词短语 | ⚠️ 静态注入 | 二选一（与私钥） | | `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 派生索引（默认 `0`） | ⚠️ 静态注入 | 可选 | @@ -525,6 +525,7 @@ WalletError ## 下一步 -- 用命令行管理钱包 → [CLI 快速开始](./QuickStart.md) -- 了解 Agent-wallet 的设计思路 → [简介](./Intro.md) -- 查看常见问题 → [常见问题](./FAQ.md) +- 喜欢敲命令？ → [CLI 命令行手册](./CLI-Reference.md) +- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md) +- 了解 Agent-wallet 的设计思路 → [简介](../Intro.md) +- 查看常见问题 → [FAQ](../FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index adeff26c..a07b70d3 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -56,6 +56,14 @@ agent-wallet add 大多数人不需要 SDK。如果你是用 OpenClaw 和 MCP Server 的普通用户，CLI 建完钱包、配好环境变量就够了。SDK 是给自己写代理的开发者用的。 +### Agent-wallet 和 MetaMask 有什么区别？ + +MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要你手动点"确认"。Agent-wallet 是给 AI 代理用的命令行钱包，专门设计为非交互式——AI 可以在后台静默调用签名，不需要人盯着屏幕点按钮。两者的加密原理类似（都是 Keystore V3），但使用场景完全不同。 + +### 一台电脑上可以创建多少个钱包？ + +没有限制。你可以为不同的 AI 代理、不同的链、不同的用途分别创建独立钱包。用 `agent-wallet add` 添加，用 `agent-wallet use` 切换。 + --- ## 钱包类型 @@ -93,17 +101,17 @@ agent-wallet add 你平时用 Web3 钱包（比如 MetaMask）时，肯定不会每次都复制粘贴明文私钥，而是用一个短密码去解锁它。Agent-wallet 就是专为 AI 打造的命令行版 MetaMask。 -* 传统方式（明文私钥）： 就像把现金直接放在桌子上。任何一个恶意的浏览器插件、一次不小心的代码提交、或者后台日志扫描，只要看一眼你的 `.env` 文件，钱瞬间就被转走了。这是典型的单点白给。 +* 传统方式（明文私钥）： 就像把现金直接放在桌子上。任何一个恶意的浏览器插件、一次不小心的代码提交、或者后台日志扫描，只要看一眼你的环境变量文件，钱瞬间就被转走了。这是典型的单点白给。 * Agent-wallet 模式： 它把风险拆分成了两把锁。 1. 物理保险箱： 你的私钥被行业顶级的算法加密，锁死在你电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 - 2. 开箱密码： 你放在环境变量（`.env`）里的，仅仅是解锁这个保险箱的密码。 + 2. 开箱密码： 你放在环境变量里的，仅仅是解锁这个保险箱的密码。 这就意味着，如果发生了泄露： * 黑客如果只偷到了你的密码（比如通过扫描环境变量），他没有你的加密钱包文件，密码就只是一串没用的字符。 * 黑客如果只偷走了你的加密钱包文件，他没有你的主密码，文件就是一堆几万年都破解不开的乱码。 -黑客必须同时黑进你的电脑、精准定位并偷走隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。这种攻击难度比仅仅扫描一下 `.env` 要高出无数倍！ +黑客必须同时黑进你的电脑、精准定位并偷走隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。这种攻击难度比仅仅扫描一下环境变量要高出无数倍！ ### 密钥会通过网络发出去吗？ @@ -114,7 +122,54 @@ agent-wallet add - ✅ 用密码管理器（1Password、Bitwarden） - ✅ 通过环境变量 `AGENT_WALLET_PASSWORD` 传入 - ❌ 不要写在代码里 -- ❌ 不要提交含密码的 `.env` 到 git +- ❌ 不要提交含密码的环境变量文件到 git + +### 加密算法安全吗？会不会被暴力破解？ + +Agent-wallet 使用 Keystore V3 标准加密（scrypt + AES-128-CTR），这和 Ethereum 官方钱包使用的加密方案完全一致。scrypt 算法的设计目标就是让暴力破解在计算和内存上都极其昂贵——即使使用专用硬件，破解一个强密码也需要数万年。 + +--- + +## 安装与环境 + +### 支持哪些操作系统？ + +macOS、Linux、Windows（通过 WSL）均可。只要能跑 Node.js >= 18 或 Python >= 3.11，就能用。 + +### `npm install -g` 报权限错误怎么办？ + +常见于 macOS / Linux。两种解法： + +**方法 1（推荐）：用 nvm 管理 Node.js**，它会把全局包装在用户目录下，不需要 `sudo`。 + +**方法 2：修复 npm 全局目录权限**： +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc +source ~/.zshrc +``` + +### 配了密码但 AI 说"找不到钱包"或"密码错误"？ + +最常见的三个原因： + +1. **密码没生效**：你在终端 A 配了 `export`，但 AI 在终端 B 运行。解决：重启 AI 后台服务（参考 [快速开始](./QuickStart.md) 第二步）。 +2. **密码被 shell 吃了**：双引号包裹的密码里有 `$` 或 `!`，被 shell 展开了。解决：改用单引号。 +3. **存储目录不对**：你之前用 `--dir` 指定了自定义路径，但 AI 在默认路径找。解决：`export AGENT_WALLET_DIR="/你的自定义路径"`。 + +### `agent-wallet` 命令找不到（command not found）？ + +说明全局安装没有生效。检查： +```bash +# 确认 npm 全局 bin 目录在 PATH 里 +npm bin -g +``` +如果输出的路径不在你的 `$PATH` 中，手动添加： +```bash +echo "export PATH=$(npm bin -g):$PATH" >> ~/.zshrc +source ~/.zshrc +``` --- @@ -130,9 +185,31 @@ agent-wallet add --- +## 与 OpenClaw 集成 + +### OpenClaw 是必须的吗？ + +不是。Agent-wallet 是一个独立的签名工具，可以通过 CLI 或 SDK 独立使用。OpenClaw 只是最方便的前端——它让你用自然语言就能调用签名，不用写代码。 + +### OpenClaw 里说"签名失败"或"钱包未连接"？ + +按以下顺序排查： + +1. 确认 `AGENT_WALLET_PASSWORD` 环境变量已设置（在运行 OpenClaw 的那个终端里执行 `echo $AGENT_WALLET_PASSWORD` 验证） +2. 确认 MCP Server 是在设置了环境变量**之后**启动的 +3. 确认钱包已初始化：`agent-wallet list` 应该能看到至少一个钱包 +4. 如果以上都正确，尝试用 CLI 手动签名测试：`agent-wallet sign msg "test" -n tron` + +### 在 OpenClaw 里签名需要花 Gas 费吗？ + +签名本身不花 Gas。签名只是用你的私钥对一段数据做密码学运算，完全在本地完成。只有当签名后的交易被广播到链上时，才需要 Gas 费。查地址、签名消息这类操作永远免费。 + +--- + ## 下一步 -- 动手配置全套环境 → [CLI 快速开始](./QuickStart.md) -- 在代码里集成签名 → [SDK 快速开始](./SDKQuickStart.md) -- 看完整的转账示例 → [完整示例](./FullExample.md) -- 了解 OpenClaw Extension → [OpenClaw 简介](../Openclaw-extension/Intro.md) +- 没写过代码？ → [快速开始](./QuickStart.md) +- 喜欢敲命令？ → [CLI 命令行手册](./Developer/CLI-Reference.md) +- 要开发应用？ → [SDK 接入指南](./Developer/SDK-Guide.md) +- 找现成代码？ → [完整代码示例](./Developer/SDK-Cookbook.md) +- 了解 OpenClaw Extension → [OpenClaw Extension 简介](../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index b8491bd9..b6975c0f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -1,23 +1,23 @@ -# 简介 +# 简介 ## 享受 AI Agent 红利，告别私钥泄露焦虑 ### 你的私钥，距离被盗可能只差一次文件读取 你想让 AI 代理帮你自动完成链上操作——刷空投、做兑换、付 Gas 费、定时转账。要做这些事，AI 需要一把"钥匙"（私钥）来替你签名。 -于是你把私钥放进了 `.env` 文件里。 +于是你把私钥放进了环境变量文件里。 **这就好比把银行卡和密码贴在脑门上，走进了一间挤满陌生人的办公室。** -那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读你的 `.env` 文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个进程拿走。 +那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读你的环境变量文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个进程拿走。 --- ### 这不是吓你，它正在发生 -- **依赖链投毒。** 你装了一个好用的 MCP Server。三个月后，它 200 个 npm 依赖中的某一个被注入了恶意代码——悄悄扫描所有 `.env` 和 `*.json` 文件，找到长得像私钥的字符串就发走。你完全不知道发生了什么，等你发现的时候，钱包已经空了。 +- **依赖链投毒。** 你装了一个好用的 MCP Server。三个月后，它 200 个 npm 依赖中的某一个被注入了恶意代码——悄悄扫描所有文件，找到长得像私钥的字符串就发走。你完全不知道发生了什么，等你发现的时候，钱包已经空了。 -- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。`.env` 在目录里。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 +- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。环境变量在目录里。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 - **Git 的"完美记忆"。** 你在开发时把私钥写进了代码，后来删了。但三周前你 commit 过一次。`git log -p` 里还有。仓库只要上过一次 GitHub，哪怕就 30 秒，自动化爬虫已经找到了。 @@ -38,13 +38,13 @@ 1. **第一重锁（物理文件）：** 你的私钥会被行业顶级的算法加密，锁死在电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 2. **第二重锁（授权密码）：** AI 只需要知道"开箱密码"（你可以配在环境变量里）就能干活。 -**🤔 你可能会问："如果 AI 把我的开箱密码也泄露了怎么办？"** +**你可能会问："如果 AI 把我的开箱密码也泄露了怎么办？"** 这就是 Agent-wallet 最精妙的地方：**密码泄露 ≠ 资产被盗。** 如果黑客通过恶意插件只偷到了你的密码，他什么也干不了，因为他没有你的加密钱包文件。如果他只偷到了钱包文件，没有密码，那就是一堆无法破解的乱码。 -**黑客必须同时黑进你的电脑系统，精准翻出隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。** 这种攻击难度和成本，比仅仅扫描一下 `.env` 里的明文私钥要高出无数倍！ +**黑客必须同时黑进你的电脑系统，精准翻出隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。** 这种攻击难度和成本，比仅仅扫描一下环境变量文件里的明文私钥要高出无数倍！ 一句话：**文件随便偷，没密码打不开；密码被泄露，没文件依然安全。** @@ -52,12 +52,12 @@ ## 和"老办法"对比一下 -| | 传统方式 (明文私钥放 `.env`) | 云钱包 | 🛡️ Agent-wallet 本地金库 | -| :--- | :--- | :--- | :--- | -| **工作原理** | 把银行卡和密码直接交给 AI | 把钱存到别人的服务器上 | **给 AI 密码，文件锁在本地** | -| **遭遇日志/环境变量泄露** | ❌ **直接倾家荡产** | ⚠️ 密钥在远端，有被黑风险 | ✅ **只丢了密码，没有文件，黑客偷不走钱** | -| **遭遇加密文件被窃取** | — | — | ✅ **没有密码，黑客打不开文件** | -| **断网能签名吗** | ⚠️ 看情况 | ❌ 必须联网 | ✅ **100% 离线签名** | +| | :x: 传统方式 (明文私钥放环境变量文件) | :white_check_mark: Agent-wallet 本地加密保险箱 | +| :--- | :--- | :--- | +| **工作原理** | :x: 把银行卡和密码直接交给 AI | :white_check_mark: **给 AI 密码，文件锁在本地** | +| **遭遇日志/环境变量泄露** | :rotating_light: **直接倾家荡产** | :shield: **只丢了密码，没有文件，黑客偷不走钱** | +| **遭遇加密文件被窃取** | :x: 明文私钥，直接被盗 | :shield: **没有密码，黑客打不开文件** | +| **断网能签名吗** | :warning: 看情况 | :white_check_mark: **100% 离线签名** | --- @@ -83,39 +83,31 @@ agent-wallet sign msg "Hello from my AI agent" -n tron 当屏幕上吐出一串哈希字符时——恭喜，你的加密保险箱配置成功了。 -> 想看每一步的详细说明？去 **[极简部署 — CLI 快速开始](./QuickStart.md)**。 +> 想看每一步的详细说明？去 **[CLI 工具手册](./Developer/CLI-Reference.md)**。 --- ## 接下来，让 AI 真正跑起来 -保险箱建好了，签名也测试通过了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** +保险箱建好了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** 根据你的角色，走不同的路： ### 🎮 我是普通玩家——用现成的工具 -你不需要写代码。很多 AI 工具已经原生支持 Agent-wallet（**推荐使用我们的 [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**）。你只需要做一件事——把主密码告诉工具： +你不需要写代码。推荐使用我们的 **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。你只需要做一件事——把主密码告诉工具： ```bash export AGENT_WALLET_PASSWORD='你的主密码' ``` -:::caution 密码有特殊字符？务必用单引号 -自动生成的密码经常含有 `$`、`!` 等特殊字符。**用单引号**包裹，否则 shell 会把它"消化"掉： +设置好后，工具就能自动调用你的 Agent-wallet 加密保险箱来签名了。你的私钥全程加密，工具拿到的只是签名结果，不是密钥本身。 -```bash -# ✅ 正确 -export AGENT_WALLET_PASSWORD='P@ss$w0rd!' +> 跟着做一遍？去 **[快速开始](./QuickStart.md)**。 -# ❌ 错误 -export AGENT_WALLET_PASSWORD="P@ss$w0rd!" -``` -::: - -设置好后，工具就能自动调用你的 Agent-wallet 加密保险箱来签名了。你的私钥全程加密，工具拿到的只是签名结果，不是密钥本身。 +### 🛠️ 我是进阶用户——想用 CLI 管理钱包 -> 想看支持的工具列表？去 **[Openclaw 扩展](../Openclaw-extension/Intro.md)**。 +需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 工具手册](./Developer/CLI-Reference.md)**。 ### 🛠️ 我是开发者——自己写代理 @@ -134,8 +126,8 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); 同一个密钥文件、同一份数据、同一个签名结果。 -> **[SDK 快速开始](./SDKQuickStart.md)** 手把手教你接入。 -> **[完整示例](./FullExample.md)** 展示端到端的真实交易：TRON 转账、BSC 转账、x402 支付签名。 +> **[SDK 接入指南](./Developer/SDK-Guide.md)** 手把手教你接入。 +> **[完整代码示例](./Developer/SDK-Cookbook.md)** 展示端到端的真实交易：TRON 转账、BSC 转账、x402 支付签名。 @@ -156,7 +148,8 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); | 我在想… | 去这里 | | :--- | :--- | -| AI 会不会把我的钱全转走？ | [常见问题](./FAQ.md) — 我们有专门的风险隔离方案 | -| 想马上动手试试 | [极简部署 — CLI 快速开始](./QuickStart.md) | -| 想在代码里用 | [SDK 快速开始](./SDKQuickStart.md) | -| 想看真实交易的完整流程 | [完整示例](./FullExample.md) | +| AI 会不会把我的钱全转走？ | [FAQ](./FAQ.md) — 我们有专门的风险隔离方案 | +| 没写过代码？ | [快速开始](./QuickStart.md) | +| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) | +| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) | +| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 6ee92bca..b864397f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -1,63 +1,53 @@ -# CLI 快速开始 +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -四步，从零到完成第一次签名。整个过程不到一分钟——复制粘贴就行。 +# 快速开始 -:::tip 已经是开发者了？ -如果你想直接在 TypeScript 或 Python 代码里调用签名，跳到 [SDK 快速开始](./SDKQuickStart.md)。 +三步，从零到在 OpenClaw 聊天框里唤醒你的加密保险箱。不用写代码，不花一分钱 Gas 费——复制粘贴就行。 + +:::tip 想看 CLI 命令细节？ +本页只带你跑通最短路径。免密配置、管理多个钱包、签名类型等进阶内容，请看 [CLI 命令行手册](./Developer/CLI-Reference.md)。 ::: --- -## 🧰 第一步：准备环境 +## 第一步：安装并初始化钱包 + +### 1.1 准备环境：安装 Node.js + +Agent-wallet 需要你的电脑里有 Node.js（这是一个运行环境，版本需 >= 18）。 -Agent-wallet CLI 需要 Node.js ≥ 18。先看看你有没有： +打开终端（Mac 用户按 `Command + 空格` 搜索"终端"；Windows 用户搜"cmd"或"PowerShell"），输入： ```bash node -v ``` -输出 `v18.x.x` 或更高？直接跳到第二步。没有或者版本太低？按下面的步骤安装： +- **如果输出 `v18.x.x` 或更高数字：** 太棒了，直接跳到 1.2！ +- **如果没有输出或报错：** 别慌，去 **[Node.js 官方网站](https://nodejs.org)** 下载最新的 **LTS** 安装包，像装普通软件一样双击安装，一路"下一步"即可。装完后关掉终端重新打开，再输入 `node -v` 确认。 -:::tip 安装 / 升级 Node.js +
+开发者首选：使用 nvm 安装（小白请跳过） -推荐用 [nvm](https://github.com/nvm-sh/nvm)，一条命令搞定： - -**1 — 安装 nvm**（已有可跳过）： ```bash +# 1. 安装 nvm（已有可跳过） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash -``` -**2 — 重新加载终端配置：** -```bash +# 2. 重新加载终端配置 source ~/.bashrc # zsh 用户改成 source ~/.zshrc -``` - -**3 — 安装 Node.js 18：** -```bash -nvm install 18 -``` -**4 — 切换到 Node.js 18：** -```bash -nvm use 18 +# 3. 安装并切换到 Node.js 18 +nvm install 18 && nvm use 18 ``` -也可以直接去 [nodejs.org](https://nodejs.org) 下载 LTS 安装包。 -::: +
---- - -## 📦 第二步：安装 Agent-wallet +### 1.2 安装 Agent-wallet ```bash npm install -g @bankofai/agent-wallet ``` -Python 用户也可以用 pip： -```bash -pip install bankofai-agent-wallet -``` - 验证安装成功： ```bash agent-wallet --help @@ -65,18 +55,14 @@ agent-wallet --help 看到帮助信息就说明安装好了。 ---- - -## 🔐 第三步：打造你的专属保险箱 +### 1.3 创建你的加密保险箱 运行： ```bash agent-wallet start ``` -系统会引导你初始化 **Agent-wallet 加密保险箱**。整个过程是交互式的——跟着提示走就行。 - -如果你没有手动指定密码（`-p` 参数），系统会自动生成一个强密码并显示一次： +系统会引导你初始化 **Agent-wallet 加密保险箱**。整个过程是交互式的——跟着提示走就行： ``` ? Quick start type: local_secure — Encrypted key stored locally (recommended) @@ -98,7 +84,7 @@ Your master password: WiJxcI#t6@73K#OE Active wallet: default ``` -:::caution ⚠️ 主密码 = 你所有资产的唯一钥匙 +:::caution 主密码 = 你所有资产的唯一钥匙 这个密码是解开所有私钥的唯一凭证。**忘了就找不回来——我们也没有备份，没有后门，神仙难救。** 请现在就做这件事： @@ -107,182 +93,103 @@ Active wallet: default 3. 不要截图，不要记在桌面便签上，不要发给自己的微信 ::: -**想自己设密码？** -```bash -agent-wallet start -p Abc12345! -``` -密码要求：至少 8 位，包含大写、小写、数字和特殊字符。 +--- -**已经有私钥，想导入？** -```bash -agent-wallet start -p Abc12345! -k 你的私钥十六进制 -``` +## 第二步：把密码"喂"给 AI（极其重要！） -**有助记词？** -```bash -agent-wallet start -p Abc12345! -m "word1 word2 word3 ..." -``` +为了让 OpenClaw 能自动使用你的钱包，你必须把密码配置到它的运行环境中。请根据你的电脑系统，选择对应的标签页，**无脑复制执行**即可。 ---- +### 2.1 永久保存并使密码生效 -## ✨ 第四步：第一次测试签名 + + -激动人心的时刻——运行： +**第 1 步：** 复制下面这条命令，把单引号里的内容换成你的真实密码，粘贴到终端里回车： ```bash -agent-wallet sign msg "Hello from my AI agent" -n tron +echo "export AGENT_WALLET_PASSWORD='你的主密码'" >> ~/.zshrc ``` -系统会让你输入主密码，然后输出： - -```text -Master password: ******** -Signature: 4a9c8f...e71b -``` - -**当屏幕上吐出那串哈希字符时——恭喜你，保险箱配置成功了！** 🎉 - -你的私钥已经加密存储在磁盘上，刚才的签名完全在本地完成，没有任何数据发送到网络。 - ---- - -## 🚀 快速开始完成！接下来做什么？ - -| 我想… | 做这个 | -| :--- | :--- | -| 让 AI 工具用上我的钱包 | 设置环境变量 `export AGENT_WALLET_PASSWORD='你的密码'`，详见 [简介](./Intro.md) | -| 在自己的代码里签名 | 去 [SDK 快速开始](./SDKQuickStart.md) | -| 看完整的转账示例 | 去 [完整示例](./FullExample.md) | -| 继续看下面的命令手册 | ↓ 往下翻 | - ---- +**第 2 步：** 再复制这条命令，粘贴回车，让配置立即生效： -## 命令手册 - -快速开始之后，下面是你日常会用到的所有命令。按需查阅。 - -### 免密码签名 - -每次签名都要交互输密码？自动化流程里完全行不通。三种方式跳过： - -**方式 A — 环境变量**（推荐用于 CI / 代理流水线）： -```bash -export AGENT_WALLET_PASSWORD='Abc12345!' -``` -设置后，所有签名命令静默运行： ```bash -agent-wallet sign msg "Hello" -n tron -agent-wallet sign tx '{"txID":"..."}' -n tron +source ~/.zshrc ``` -:::caution 密码有特殊字符？务必用单引号 -```bash -# ✅ 正确 — shell 按字面意思处理 -export AGENT_WALLET_PASSWORD='P@ss$w0rd!' + + -# ❌ 错误 — $ 被 shell 展开，密码静默出错 -export AGENT_WALLET_PASSWORD="P@ss$w0rd!" -``` -::: +**第 1 步：** 复制下面这条命令，把单引号里的内容换成你的真实密码，粘贴到终端里回车： -**方式 B — 内联 `-p`**（临时用一次）： ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +echo "export AGENT_WALLET_PASSWORD='你的主密码'" >> ~/.bashrc ``` -**方式 C — `--save-runtime-secrets`**（密码存入 `~/.agent-wallet/runtime_secrets.json`，下次自动读取）： +**第 2 步：** 再复制这条命令，粘贴回车，让配置立即生效： + ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +source ~/.bashrc ``` -### 签名类型 + + -每条 `sign` 子命令都需要 `--network` / `-n` 来指定链： +:::caution 密码有特殊字符？千万不要动单引号！ +自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉： -**签名消息：** ```bash -agent-wallet sign msg "Hello" -n tron -``` +# 正确 — 单引号，密码原样保存 +echo "export AGENT_WALLET_PASSWORD='P@ss$w0rd!'" >> ~/.zshrc -**签名交易**（需要先通过 RPC 构建未签名交易）： -```bash -agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron -``` - -**签名 EIP-712 结构化数据：** -```bash -agent-wallet sign typed-data '{ - "types": { - "EIP712Domain": [{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}], - "Transfer": [{"name":"to","type":"address"},{"name":"amount","type":"uint256"}] - }, - "primaryType": "Transfer", - "domain": {"name":"MyDApp","chainId":1}, - "message": {"to":"0x7099...","amount":1000000} -}' -n eip155:1 +# 错误 — 双引号包密码，$ 被 shell 展开，密码静默出错 +echo "export AGENT_WALLET_PASSWORD=\"P@ss$w0rd!\"" >> ~/.zshrc ``` +::: -### 管理多个钱包 +### 2.2 重启你的 AI 后台服务 -**添加新钱包：** -```bash -agent-wallet add -``` +:::danger 这一步很多人忘了，结果 AI 死活读不到密码！ +因为你刚才新存了密码，而正在后台运行的 AI 助手还没刷新——它还是个"瞎子"！只有关掉它重新启动，它才能"看"到你的新密码。 +::: -**切换活跃钱包：** -```bash -agent-wallet use my-bsc-wallet -``` +不管你现在是否正开着 OpenClaw 的后台服务，请务必将它**关闭**，然后在刚才执行过命令的终端窗口里，**重新启动**它。 -**用指定钱包签名**（不切换活跃钱包）： -```bash -agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" -``` +--- -**查看钱包详情：** -```bash -agent-wallet inspect my-bsc-wallet -``` +## 第三步：在 OpenClaw 里唤醒你的加密保险箱 -**查看所有钱包：** -```bash -agent-wallet list -``` +保险箱建好了，密码也配好了。现在打开 **OpenClaw**，就像和真人聊天一样，测试一下它能不能成功调用你的本地加密保险箱。 -**删除钱包：** -```bash -agent-wallet remove my-bsc-wallet -``` +:::info 还没装 OpenClaw Extension？ +先去 [OpenClaw Extension 快速开始](../Openclaw-extension/QuickStart.md) 安装好，再回来继续。 +::: -### 修改主密码 +### 零风险测试 1：查地址 -修改后，所有密钥文件会用新密码重新加密： +在聊天框里输入： -```bash -agent-wallet change-password -``` +> 帮我查一下我当前绑定的本地钱包地址（TRON 网络）。 -### 重置所有数据 +AI 会自动读取你的加密保险箱，并准确报出你刚才创建的钱包地址。**这证明密码配置完全正确！** -删除 `~/.agent-wallet/` 下的所有内容，**不可撤销**，需要二次确认： +### 零风险测试 2：让 AI 替你签名 -```bash -agent-wallet reset -``` +接着对它说： -### 自定义存储目录 +> 用我的钱包签名这段话："Hello Agent-wallet!" -所有命令支持 `--dir` 指定密钥存储路径（默认 `~/.agent-wallet`）： +AI 会在本地离线完成签名，并返回一串哈希字符。 -```bash -agent-wallet start --dir ./my-secrets -agent-wallet sign msg "Hello" --dir ./my-secrets -``` +**恭喜！** 全程没花一分钱 Gas 费，你也完全没接触私钥，但你已经成功让 AI 拥有了安全的密码学签名能力。 --- -## 下一步 +## 你已经跑通了全流程 -- 让 AI 工具用上你的钱包 → [简介 — 普通玩家路径](./Intro.md) -- 在代码里集成签名 → [SDK 快速开始](./SDKQuickStart.md) -- 查看常见问题 → [常见问题](./FAQ.md) +| 我想… | 去这里 | +| :--- | :--- | +| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) | +| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) | +| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) | +| 了解安全设计原理 | [简介](./Intro.md) | +| 查看常见问题 | [FAQ](./FAQ.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js index 055fcbdb..ccece162 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -152,7 +152,21 @@ const sidebars = { type: 'category', label: 'Agent Wallet', collapsed: false, - items: ['Agent-Wallet/Intro', 'Agent-Wallet/QuickStart', 'Agent-Wallet/FAQ'], + items: [ + 'Agent-Wallet/Intro', + 'Agent-Wallet/QuickStart', + { + type: 'category', + label: '开发者', + collapsed: true, + items: [ + 'Agent-Wallet/Developer/CLI-Reference', + 'Agent-Wallet/Developer/SDK-Guide', + 'Agent-Wallet/Developer/SDK-Cookbook', + ], + }, + 'Agent-Wallet/FAQ', + ], }, { type: 'category', diff --git a/sidebars.js b/sidebars.js index c46d1522..d97f206e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -148,7 +148,21 @@ const sidebars = { type: 'category', label: 'Agent Wallet', collapsed: false, - items: ['Agent-Wallet/Intro', 'Agent-Wallet/QuickStart', 'Agent-Wallet/SDKQuickStart', 'Agent-Wallet/FullExample', 'Agent-Wallet/FAQ'], + items: [ + 'Agent-Wallet/Intro', + 'Agent-Wallet/QuickStart', + { + type: 'category', + label: 'Developer', + collapsed: true, + items: [ + 'Agent-Wallet/Developer/CLI-Reference', + 'Agent-Wallet/Developer/SDK-Guide', + 'Agent-Wallet/Developer/SDK-Cookbook', + ], + }, + 'Agent-Wallet/FAQ', + ], }, { type: 'category', From bc4a8f0244e0ff15405525568c54d98930fce499 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 03:27:33 +0800 Subject: [PATCH 16/44] fix --- .../current/Agent-Wallet/Intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index b6975c0f..4bd315ca 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -83,7 +83,7 @@ agent-wallet sign msg "Hello from my AI agent" -n tron 当屏幕上吐出一串哈希字符时——恭喜，你的加密保险箱配置成功了。 -> 想看每一步的详细说明？去 **[CLI 工具手册](./Developer/CLI-Reference.md)**。 +> 想看每一步的详细说明？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。 --- @@ -107,7 +107,7 @@ export AGENT_WALLET_PASSWORD='你的主密码' ### 🛠️ 我是进阶用户——想用 CLI 管理钱包 -需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 工具手册](./Developer/CLI-Reference.md)**。 +需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。 ### 🛠️ 我是开发者——自己写代理 From b1bfecd035ef2ab403af924fa366d315f16278d3 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 12:20:23 +0800 Subject: [PATCH 17/44] update --- docs/Agent-Wallet/Intro.md | 4 ++-- i18n/zh-Hans/docusaurus-plugin-content-docs/current.json | 6 +++--- .../current/Agent-Wallet/Intro.md | 4 ++-- .../docusaurus-plugin-content-docs/current/sidebars.js | 2 +- sidebars.js | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index e0de6b3b..59a62375 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -106,11 +106,11 @@ Once set, your tools automatically call your Agent-wallet encrypted safe to sign > Want the step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. -### 🛠️ I'm an advanced user — managing wallets via CLI +### ⌨️ I'm an advanced user — managing wallets via CLI Need password-free signing, managing multiple wallets, or custom storage directories? Head to **[CLI Reference](./Developer/CLI-Reference.md)**. -### 🛠️ I'm a developer — building my own agent +### 👨‍💻 I'm a developer — building my own agent
Expand developer path — TypeScript / Python SDK diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json index d33a3c60..d8a44366 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -68,8 +68,8 @@ "message": "API 参考", "description": "The label for category API in sidebar docsSidebar" }, - "sidebar.docsSidebar.category.Developer": { - "message": "开发者", - "description": "The label for category Developer in sidebar docsSidebar" + "sidebar.docsSidebar.category.Explore Further": { + "message": "进一步探索", + "description": "The label for category Explore Further in sidebar docsSidebar" } } diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index 4bd315ca..3a4da198 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -105,11 +105,11 @@ export AGENT_WALLET_PASSWORD='你的主密码' > 跟着做一遍？去 **[快速开始](./QuickStart.md)**。 -### 🛠️ 我是进阶用户——想用 CLI 管理钱包 +### ⌨️ 我是进阶用户——想用 CLI 管理钱包 需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。 -### 🛠️ 我是开发者——自己写代理 +### 👨‍💻 我是开发者——自己写代理
展开开发者路径 — TypeScript / Python SDK diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js index ccece162..1edc900e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -157,7 +157,7 @@ const sidebars = { 'Agent-Wallet/QuickStart', { type: 'category', - label: '开发者', + label: '进一步探索', collapsed: true, items: [ 'Agent-Wallet/Developer/CLI-Reference', diff --git a/sidebars.js b/sidebars.js index d97f206e..f1ea72cf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -153,7 +153,7 @@ const sidebars = { 'Agent-Wallet/QuickStart', { type: 'category', - label: 'Developer', + label: 'Explore Further', collapsed: true, items: [ 'Agent-Wallet/Developer/CLI-Reference', From cf49298f36d7b2931a005d0abf90e738888ba8f2 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 12:32:10 +0800 Subject: [PATCH 18/44] fix --- docs/Agent-Wallet/Developer/CLI-Reference.md | 4 ++++ .../current/Agent-Wallet/Developer/CLI-Reference.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index a97ee24a..502765bb 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -140,6 +140,10 @@ The ultimate convenience solution. After running a command once with the `--save agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` +:::danger Security Warning +`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Only use this feature if you fully trust the runtime environment, and make sure this file is never committed to git or synced to the cloud. +::: + ### Method C: Inline `-p` Flag (For One-Off Commands) Pass the password directly at the end of the command. The program takes the password and runs immediately — no prompts: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 05d12f7d..0536a978 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -140,6 +140,10 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` +:::danger 安全提示 +`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。请仅在你完全信任运行环境的前提下使用此功能，且务必确保该文件不会被提交到 git 或同步到云端。 +::: + ### 方式 C：命令行内联 `-p`（适合临时跑单次指令） 直接把密码写在命令的结尾。程序拿到密码就直接干活，不会再停下来问你： From b8ea0825435fe771e238937041d03a5dab9a1a1d Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 12:48:19 +0800 Subject: [PATCH 19/44] fix --- .github/workflows/docker.yml | 9 ------ docs/Agent-Wallet/QuickStart.md | 28 +++++++++++++++---- .../current/Agent-Wallet/QuickStart.md | 28 +++++++++++++++---- 3 files changed, 44 insertions(+), 21 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index d8c714f5..aba2263a 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -31,15 +31,6 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - - name: Debug Docker Hub secrets - if: github.event_name != 'pull_request' - env: - DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} - DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - run: | - echo "username=[$DOCKERHUB_USERNAME]" - echo "token_length=${#DOCKERHUB_TOKEN}" - - name: Log in to Docker Hub if: github.event_name != 'pull_request' env: diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 0bdc2725..1df7a46f 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -104,13 +104,19 @@ For OpenClaw to automatically use your wallet, you must configure the password i -**Step 1:** Copy the command below, replace the content inside the single quotes with your actual password, paste it into the terminal and press Enter: +**Step 1:** Open `~/.zshrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): ```bash -echo "export AGENT_WALLET_PASSWORD='your-master-password'" >> ~/.zshrc +open -e ~/.zshrc ``` -**Step 2:** Copy this command, paste and press Enter to apply the config immediately: +Add this line at the very end, then save and close: + +```bash +export AGENT_WALLET_PASSWORD='your-master-password' +``` + +**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately: ```bash source ~/.zshrc @@ -119,13 +125,19 @@ source ~/.zshrc -**Step 1:** Copy the command below, replace the content inside the single quotes with your actual password, paste it into the terminal and press Enter: +**Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): + +```bash +nano ~/.bashrc +``` + +Add this line at the very end, then save and close (in nano, press `Ctrl + O` to save, `Ctrl + X` to exit): ```bash -echo "export AGENT_WALLET_PASSWORD='your-master-password'" >> ~/.bashrc +export AGENT_WALLET_PASSWORD='your-master-password' ``` -**Step 2:** Copy this command, paste and press Enter to apply the config immediately: +**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately: ```bash source ~/.bashrc @@ -134,6 +146,10 @@ source ~/.bashrc +:::tip Why not use the echo command? +While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history. +::: + :::caution Password has special characters? Don't touch the single quotes! Auto-generated passwords often contain `$`, `!`, and other special characters. The commands above already use single quotes to wrap the password — **just replace the text inside the quotes, never switch to double quotes**, or the shell will silently mangle the value: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index b864397f..14660535 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -104,13 +104,19 @@ Active wallet: default -**第 1 步：** 复制下面这条命令，把单引号里的内容换成你的真实密码，粘贴到终端里回车： +**第 1 步：** 用编辑器打开 `~/.zshrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： ```bash -echo "export AGENT_WALLET_PASSWORD='你的主密码'" >> ~/.zshrc +open -e ~/.zshrc ``` -**第 2 步：** 再复制这条命令，粘贴回车，让配置立即生效： +在文件末尾添加这一行，保存并关闭： + +```bash +export AGENT_WALLET_PASSWORD='你的主密码' +``` + +**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效： ```bash source ~/.zshrc @@ -119,13 +125,19 @@ source ~/.zshrc -**第 1 步：** 复制下面这条命令，把单引号里的内容换成你的真实密码，粘贴到终端里回车： +**第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： + +```bash +nano ~/.bashrc +``` + +在文件末尾添加这一行，保存并关闭（nano 中按 `Ctrl + O` 保存，`Ctrl + X` 退出）： ```bash -echo "export AGENT_WALLET_PASSWORD='你的主密码'" >> ~/.bashrc +export AGENT_WALLET_PASSWORD='你的主密码' ``` -**第 2 步：** 再复制这条命令，粘贴回车，让配置立即生效： +**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效： ```bash source ~/.bashrc @@ -134,6 +146,10 @@ source ~/.bashrc +:::tip 为什么不用 echo 命令？ +`echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。 +::: + :::caution 密码有特殊字符？千万不要动单引号！ 自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉： From bafd81bc968b834c1c46e36416e69d40f7f41482 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 12:57:00 +0800 Subject: [PATCH 20/44] fix audit suggestion --- .github/workflows/docker.yml | 2 -- docs/Agent-Wallet/Developer/CLI-Reference.md | 25 +++++++++++++++++++ docs/Agent-Wallet/Developer/SDK-Cookbook.md | 8 ++++-- docs/Openclaw-extension/Intro.md | 2 +- .../Agent-Wallet/Developer/CLI-Reference.md | 25 +++++++++++++++++++ .../Agent-Wallet/Developer/SDK-Cookbook.md | 8 ++++-- .../current/Openclaw-extension/Intro.md | 2 +- 7 files changed, 64 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index aba2263a..a2b42b1a 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -5,14 +5,12 @@ on: branches: - main - master - - update-mcp-server tags: - 'test' pull_request: branches: - main - master - - update-mcp-server workflow_dispatch: env: diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index 502765bb..cf06f1e7 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -122,6 +122,10 @@ agent-wallet sign msg "Hello" -n tron agent-wallet sign tx '{"txID":"..."}' -n tron ``` +:::tip Prevent this command from being recorded in shell history +Prefix the command with a space (requires `HISTCONTROL=ignorespace` in Bash or `setopt HIST_IGNORE_SPACE` in Zsh — both are enabled by default on most systems). Or edit `~/.zshrc` / `~/.bashrc` directly in a text editor to avoid history exposure entirely. +::: + :::caution Password contains special characters? Always use single quotes ```bash # ✅ Correct — shell treats it literally @@ -132,6 +136,25 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: +
+GitHub Actions / CI example + +In CI/CD environments, never hardcode the password in workflow files. Use repository secrets instead: + +```yaml +# .github/workflows/sign.yml +jobs: + sign: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: agent-wallet sign msg "Hello" -n tron + env: + AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }} +``` + +
+ ### Method B: Local Password Cache (True "Set and Forget") The ultimate convenience solution. After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: @@ -142,6 +165,8 @@ agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets :::danger Security Warning `runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Only use this feature if you fully trust the runtime environment, and make sure this file is never committed to git or synced to the cloud. + +The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`. ::: ### Method C: Inline `-p` Flag (For One-Off Commands) diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index d57d5556..2ccb46b0 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -283,13 +283,17 @@ async function transferBNB( const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); const feeData = await rpcProvider.getFeeData(); + if (!feeData.maxFeePerGas || !feeData.maxPriorityFeePerGas) { + throw new Error("Chain does not support EIP-1559 fee data"); + } + // Step 3: Build the unsigned transaction const unsignedTx = { to: toAddress, value: ethers.parseEther(amountEther), gas: 21000n, - maxFeePerGas: feeData.maxFeePerGas!, - maxPriorityFeePerGas: feeData.maxPriorityFeePerGas!, + maxFeePerGas: feeData.maxFeePerGas, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas, nonce, chainId: CHAIN_ID, type: 2, // EIP-1559 diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index d3bb9c5f..d4814867 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -31,7 +31,7 @@ MCP Servers are bridges between your AI assistant and the blockchain, providing | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | -| **[bankofai-recharge](https://recharge.bankofai.io/mcp)** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | +| **bankofai-recharge** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | ### Skills — Pre-built Workflows diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 0536a978..8aef1a8e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -122,6 +122,10 @@ agent-wallet sign msg "Hello" -n tron agent-wallet sign tx '{"txID":"..."}' -n tron ``` +:::tip 防止此命令被记录到 Shell 历史 +在命令前加一个空格（需要 Bash 中启用 `HISTCONTROL=ignorespace` 或 Zsh 中启用 `setopt HIST_IGNORE_SPACE`——大多数系统默认已开启）。或者直接用文本编辑器编辑 `~/.zshrc` / `~/.bashrc`，从根本上避免历史记录泄露。 +::: + :::caution 密码有特殊字符？务必用单引号 ```bash # 正确 — shell 按字面意思处理 @@ -132,6 +136,25 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ``` ::: +
+GitHub Actions / CI 示例 + +在 CI/CD 环境中，切勿将密码硬编码在工作流文件里。请使用仓库密钥（Secrets）： + +```yaml +# .github/workflows/sign.yml +jobs: + sign: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: agent-wallet sign msg "Hello" -n tron + env: + AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }} +``` + +
+ ### 方式 B：密码本地缓存（真正的"一劳永逸"） 这是最省事的终极方案。执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： @@ -142,6 +165,8 @@ agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets :::danger 安全提示 `runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。请仅在你完全信任运行环境的前提下使用此功能，且务必确保该文件不会被提交到 git 或同步到云端。 + +工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。 ::: ### 方式 C：命令行内联 `-p`（适合临时跑单次指令） diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index 7750bf4b..ad307580 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -283,13 +283,17 @@ async function transferBNB( const nonce = await rpcProvider.getTransactionCount(fromAddress, "latest"); const feeData = await rpcProvider.getFeeData(); + if (!feeData.maxFeePerGas || !feeData.maxPriorityFeePerGas) { + throw new Error("该链不支持 EIP-1559 费用数据"); + } + // 第三步：构建未签名交易 const unsignedTx = { to: toAddress, value: ethers.parseEther(amountEther), gas: 21000n, - maxFeePerGas: feeData.maxFeePerGas!, - maxPriorityFeePerGas: feeData.maxPriorityFeePerGas!, + maxFeePerGas: feeData.maxFeePerGas, + maxPriorityFeePerGas: feeData.maxPriorityFeePerGas, nonce, chainId: CHAIN_ID, type: 2, // EIP-1559 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index 5cdf597d..cec7b4e9 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -31,7 +31,7 @@ MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Prot | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | -| **[bankofai-recharge](https://recharge.bankofai.io/mcp)** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | +| **bankofai-recharge** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | ### Skills — 预构建工作流 From 5e9152bbba99e760656e8947e57eae264d55087f Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 13:18:31 +0800 Subject: [PATCH 21/44] fix audio report issue --- docs/Agent-Wallet/Developer/CLI-Reference.md | 14 ++++++++--- docs/Agent-Wallet/Developer/SDK-Cookbook.md | 25 ++++++++++++++++--- docs/Agent-Wallet/FAQ.md | 4 ++- docs/Agent-Wallet/QuickStart.md | 2 +- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 4 +-- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- .../Agent-Wallet/Developer/CLI-Reference.md | 15 ++++++++--- .../Agent-Wallet/Developer/SDK-Cookbook.md | 25 ++++++++++++++++--- .../current/Agent-Wallet/FAQ.md | 4 ++- .../current/Agent-Wallet/QuickStart.md | 2 +- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 4 +-- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- 12 files changed, 79 insertions(+), 24 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index cf06f1e7..e44754d0 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -26,6 +26,10 @@ agent-wallet start -p Abc12345! ``` Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. +:::caution Shell history risk +Passing `-p` inline records the password in your terminal's history file. For production wallets, prefer interactive mode (`agent-wallet start` without `-p`) or set `AGENT_WALLET_PASSWORD` as an environment variable — see [Non-Interactive Execution](#non-interactive-execution-for-automation--background-services). +::: + **Import an existing private key:** ```bash agent-wallet start -p Abc12345! -k your-private-key-hex @@ -155,16 +159,18 @@ jobs:
-### Method B: Local Password Cache (True "Set and Forget") +### Method B: Local Password Cache (Convenience vs. Security Trade-off) -The ultimate convenience solution. After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: +After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: ```bash agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` -:::danger Security Warning -`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Only use this feature if you fully trust the runtime environment, and make sure this file is never committed to git or synced to the cloud. +:::danger This disables the dual-lock protection +Caching the password next to the wallet file means a single file system compromise grants full access to your funds — defeating Agent-wallet's core "physical file + password separation" security model. **Only use this for throwaway test wallets.** + +`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Make sure this file is never committed to git or synced to the cloud. The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`. ::: diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index 2ccb46b0..1faede9f 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -21,7 +21,11 @@ Before running any example below, make sure you have: 1. Installed the Agent-wallet SDK (see [SDK Guide](./SDK-Guide.md)) 2. Initialized a local wallet via the CLI, or configured static mode environment variables -3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode) +3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode — strongly recommended) + +:::danger Avoid static mode (`AGENT_WALLET_PRIVATE_KEY`) for real funds +Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local encrypted safe. +::: --- @@ -112,7 +116,15 @@ async function transferTRX( console.log("Unsigned txID:", unsignedTx.txID); // Step 3: Sign locally with Agent-wallet - const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + let signedTx: Record; + try { + signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + } catch (e) { + throw new Error(`signTransaction returned invalid JSON: ${e}`); + } + if (!signedTx.signature) { + throw new Error("Signed transaction is missing the signature field"); + } console.log("Signed, signature:", signedTx.signature); // Step 4: Broadcast via TronGrid @@ -177,7 +189,13 @@ async def transfer_trx( print("Unsigned txID:", unsigned_tx["txID"]) # Step 3: Sign locally with Agent-wallet - signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) + raw_signed = await wallet.sign_transaction(unsigned_tx) + try: + signed_tx = json.loads(raw_signed) + except json.JSONDecodeError as e: + raise ValueError(f"signTransaction returned invalid JSON: {e}") from e + if "signature" not in signed_tx: + raise ValueError("Signed transaction is missing the signature field") print("Signed, signature:", signed_tx["signature"]) # Step 4: Broadcast via TronGrid @@ -306,6 +324,7 @@ async function transferBNB( console.log("Signed"); // Step 5: Broadcast + // signTransaction returns hex without '0x' prefix; ethers requires it const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); console.log("Broadcast successful! txHash:", txResponse.hash); diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index aaff89b0..7bb46cb4 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -76,7 +76,9 @@ No limit. You can create separate wallets for different AI agents, different cha | **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly | | **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev environments only | -**Always use `local_secure`** unless you're 100% certain no other agent is running on that machine. +:::danger `raw_secret` exposes your private key as plaintext +`raw_secret` stores your key unencrypted — the exact exposure `local_secure` mode is designed to prevent. If any other process on your machine can read files, your key can be stolen instantly. **Always use `local_secure`** unless you're 100% certain no other agent is running on that machine and it's a fully isolated, offline test environment. +::: ### What values does the `network` parameter accept? diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 1df7a46f..539b8d82 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -123,7 +123,7 @@ source ~/.zshrc ``` - + **Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index c008d790..5a9d86c0 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **Verify password**: Run `echo $AGENT_WALLET_PASSWORD` to confirm the variable is set correctly. 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. -3. **If password is lost**: You'll need to re-initialize the wallet. See the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +3. **If password is lost**: You'll need to re-initialize the wallet. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### "Conflicting Wallet Modes" @@ -271,7 +271,7 @@ sun-mcp-server - Check Permit2 request structured data - Confirm chain ID, token address, deadline correct -3. **Reinitialize Wallet** — see [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) for re-initialization instructions. +3. **Reinitialize Wallet** — run `agent-wallet reset` to wipe and start over. See [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) for details. 4. **Use Alternate Authorization Method** ``` diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 58ec6948..e7854b1c 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -93,7 +93,7 @@ If the server reports an invalid private key at startup, it's usually a format i `AGENT_WALLET_PASSWORD` must exactly match the master password set during wallet initialization. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. -If the password is lost, you'll need to re-initialize — see the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +If the password is lost, you'll need to re-initialize. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### TronGrid API Key not working diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 8aef1a8e..b150855d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -26,6 +26,10 @@ agent-wallet start -p Abc12345! ``` 密码要求：至少 8 位，包含大写、小写、数字和特殊字符。 +:::caution Shell 历史记录风险 +使用 `-p` 内联传递密码会将密码记录在终端的历史文件中。生产钱包建议使用交互式模式（不带 `-p` 的 `agent-wallet start`）或通过环境变量设置 `AGENT_WALLET_PASSWORD`——详见[非交互式执行](#非交互式执行专为自动化与后台设计)。 +::: + **导入已有私钥：** ```bash agent-wallet start -p Abc12345! -k 你的私钥十六进制 @@ -155,16 +159,18 @@ jobs:
-### 方式 B：密码本地缓存（真正的"一劳永逸"） +### 方式 B：密码本地缓存（便利性与安全性的取舍） -这是最省事的终极方案。执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： +执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： ```bash agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets ``` -:::danger 安全提示 -`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。请仅在你完全信任运行环境的前提下使用此功能，且务必确保该文件不会被提交到 git 或同步到云端。 +:::danger 此操作会使双重锁保护失效 +将密码缓存在钱包文件旁边，意味着一次文件系统入侵就能获取全部资金——彻底击溃 Agent-wallet 的核心"物理文件 + 密码分离"安全模型。**请仅对一次性测试钱包使用此功能。** + +`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。务必确保该文件不会被提交到 git 或同步到云端。 工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。 ::: @@ -240,6 +246,7 @@ echo "提取到的签名内容是: $SIGNATURE" # 接下来，你可以拿这个 $SIGNATURE 去发请求、拼 JSON，或者传给其他流水线任务... ``` + --- ## 下一步 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index ad307580..a272fbe1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -21,7 +21,11 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页 1. 安装 Agent-wallet SDK（详见 [SDK 接入指南](./SDK-Guide.md)） 2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量 -3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式） +3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式——强烈推荐） + +:::danger 真金白银操作请勿使用静态模式（`AGENT_WALLET_PRIVATE_KEY`） +静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地加密保险箱。 +::: --- @@ -112,7 +116,15 @@ async function transferTRX( console.log("未签名 txID：", unsignedTx.txID); // 第三步：用 Agent-wallet 本地签名 - const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + let signedTx: Record; + try { + signedTx = JSON.parse(await wallet.signTransaction(unsignedTx)); + } catch (e) { + throw new Error(`signTransaction 返回了无效的 JSON: ${e}`); + } + if (!signedTx.signature) { + throw new Error("签名后的交易缺少 signature 字段"); + } console.log("已签名，signature：", signedTx.signature); // 第四步：通过 TronGrid 广播 @@ -177,7 +189,13 @@ async def transfer_trx( print("未签名 txID：", unsigned_tx["txID"]) # 第三步：用 Agent-wallet 本地签名 - signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx)) + raw_signed = await wallet.sign_transaction(unsigned_tx) + try: + signed_tx = json.loads(raw_signed) + except json.JSONDecodeError as e: + raise ValueError(f"signTransaction 返回了无效的 JSON: {e}") from e + if "signature" not in signed_tx: + raise ValueError("签名后的交易缺少 signature 字段") print("已签名，signature：", signed_tx["signature"]) # 第四步：通过 TronGrid 广播 @@ -306,6 +324,7 @@ async function transferBNB( console.log("已签名"); // 第五步：广播 + // signTransaction 返回的十六进制不带 '0x' 前缀；ethers 需要加上 const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); console.log("广播成功！txHash：", txResponse.hash); diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index a07b70d3..70de7e35 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -76,7 +76,9 @@ MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要 | **代理读了文件** | ✅ 拿不到密钥 | ❌ 直接被盗 | | **适合场景** | ✅ 所有场景 | ⚠️ 完全隔离的开发环境 | -**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理。 +:::danger `raw_secret` 会以明文存储你的私钥 +`raw_secret` 不加密私钥——这恰恰是 `local_secure` 模式旨在防范的风险。如果你的机器上有任何其他进程能读取文件，你的私钥就会被直接盗走。**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理，且处于完全隔离的离线测试环境中。 +::: ### `network` 参数怎么填？ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 14660535..7a17e415 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -123,7 +123,7 @@ source ~/.zshrc ``` - + **第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 9bb892f9..b5082cb1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **验证密码**：运行 `echo $AGENT_WALLET_PASSWORD` 确认变量已正确设置。 2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -3. **密码丢失**：需要重新初始化钱包——详见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +3. **密码丢失**：需要重新初始化钱包。运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### "Conflicting wallet modes" @@ -271,7 +271,7 @@ sun-mcp-server - 检查 Permit2 请求的结构化数据 - 确认链 ID、代币地址、截止时间正确 -3. **重新初始化 Wallet** — 参见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart) 了解重新初始化步骤。 +3. **重新初始化 Wallet** — 运行 `agent-wallet reset` 清除并重新开始。详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)。 4. **使用备用授权方法** ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index e93ba0cc..a352ddec 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -93,7 +93,7 @@ `AGENT_WALLET_PASSWORD` 必须与钱包初始化时设置的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -如果密码丢失，需要重新初始化钱包——详见 [Agent-Wallet 快速开始](../../../Agent-Wallet/QuickStart)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +如果密码丢失，需要重新初始化钱包。运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 From ee9c759f8b4b6b3a6c1689753f40a1f73753abcd Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 13:33:26 +0800 Subject: [PATCH 22/44] fix audio issues --- .github/workflows/docker.yml | 2 +- docs/Agent-Wallet/Developer/SDK-Cookbook.md | 20 ++++++++++++++----- docs/Agent-Wallet/FAQ.md | 5 +++-- docs/Agent-Wallet/QuickStart.md | 17 +++++++++++++--- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 2 +- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- .../Agent-Wallet/Developer/SDK-Cookbook.md | 20 ++++++++++++++----- .../current/Agent-Wallet/FAQ.md | 5 +++-- .../current/Agent-Wallet/QuickStart.md | 19 ++++++++++++++---- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 2 +- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- 11 files changed, 70 insertions(+), 26 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index a2b42b1a..4516d0c9 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -11,7 +11,7 @@ on: branches: - main - master - workflow_dispatch: + workflow_dispatch: # Intentionally unrestricted — allows manual builds from any branch for flexibility env: IMAGE_NAME: bankofai/docs diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index 1faede9f..bda0a406 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -98,6 +98,12 @@ async function transferTRX( const provider = resolveWalletProvider({ network: "tron:nile" }); const wallet = await provider.getActiveWallet(); + // Ensure fromAddress matches the wallet — a mismatch will cause a TronGrid error + const walletAddress = await wallet.getAddress(); + if (fromAddress !== walletAddress) { + throw new Error(`fromAddress mismatch: expected ${walletAddress}, got ${fromAddress}`); + } + // Step 2: Build the unsigned transaction via TronGrid const { data: unsignedTx } = await axios.post( `${TRONGRID_API}/wallet/createtransaction`, @@ -328,9 +334,13 @@ async function transferBNB( const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); console.log("Broadcast successful! txHash:", txResponse.hash); - // Wait for confirmation (optional) - const receipt = await txResponse.wait(); - console.log("Confirmed in block:", receipt?.blockNumber); + // Wait for confirmation (optional — add timeout to avoid hanging) + try { + const receipt = await txResponse.wait(1); // wait 1 confirmation, throws on timeout + console.log("Confirmed in block:", receipt?.blockNumber); + } catch (e) { + console.warn("Receipt wait timed out or failed:", e); + } return txResponse.hash; } @@ -389,8 +399,8 @@ async def transfer_bnb(to_address: str, amount_ether: str): tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) print("Broadcast successful! txHash:", tx_hash.hex()) - # Wait for confirmation (optional) - receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) + # Wait for confirmation (optional — add timeout to avoid blocking forever) + receipt = await w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120) print("Confirmed in block:", receipt["blockNumber"]) return tx_hash.hex() diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index 7bb46cb4..9cb79e3d 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -165,11 +165,12 @@ The three most common causes: The global installation didn't take effect. Check: ```bash # Confirm the npm global bin directory is in your PATH -npm bin -g +npm prefix -g +# The global bin directory is: $(npm prefix -g)/bin ``` If the output path isn't in your `$PATH`, add it manually: ```bash -echo "export PATH=$(npm bin -g):$PATH" >> ~/.zshrc +echo "export PATH=$(npm prefix -g)/bin:$PATH" >> ~/.zshrc source ~/.zshrc ``` diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 539b8d82..19342579 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -146,6 +146,17 @@ source ~/.bashrc +:::info Windows without WSL? +If you're on native Windows (no WSL), set the environment variable via PowerShell or System Properties: + +```powershell +# PowerShell — set permanently for your user +[Environment]::SetEnvironmentVariable("AGENT_WALLET_PASSWORD", "your-master-password", "User") +``` + +Or open **System Properties → Advanced → Environment Variables** and add `AGENT_WALLET_PASSWORD` manually. Restart your terminal after setting it. +::: + :::tip Why not use the echo command? While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history. ::: @@ -155,10 +166,10 @@ Auto-generated passwords often contain `$`, `!`, and other special characters. T ```bash # ✅ Correct — single quotes, password saved as-is -echo "export AGENT_WALLET_PASSWORD='P@ss$w0rd!'" >> ~/.zshrc +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' -# ❌ Wrong — double quotes around password, $ gets expanded by shell, password silently breaks -echo "export AGENT_WALLET_PASSWORD=\"P@ss$w0rd!\"" >> ~/.zshrc +# ❌ Wrong — double quotes, $w0rd gets shell-expanded to empty string, password silently breaks +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # actual value becomes "P@ss!" ``` ::: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 5a9d86c0..07ec0983 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **Verify password**: Run `echo $AGENT_WALLET_PASSWORD` to confirm the variable is set correctly. 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. -3. **If password is lost**: You'll need to re-initialize the wallet. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. ### "Conflicting Wallet Modes" diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index e7854b1c..428265f8 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -93,7 +93,7 @@ If the server reports an invalid private key at startup, it's usually a format i `AGENT_WALLET_PASSWORD` must exactly match the master password set during wallet initialization. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. -If the password is lost, you'll need to re-initialize. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +If the password is lost, you'll need to re-initialize. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### TronGrid API Key not working diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index a272fbe1..4399f09a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -98,6 +98,12 @@ async function transferTRX( const provider = resolveWalletProvider({ network: "tron:nile" }); const wallet = await provider.getActiveWallet(); + // 确保 fromAddress 与钱包地址一致——不匹配会导致 TronGrid 报错 + const walletAddress = await wallet.getAddress(); + if (fromAddress !== walletAddress) { + throw new Error(`fromAddress 不匹配：预期 ${walletAddress}，实际 ${fromAddress}`); + } + // 第二步：通过 TronGrid 构建未签名交易 const { data: unsignedTx } = await axios.post( `${TRONGRID_API}/wallet/createtransaction`, @@ -328,9 +334,13 @@ async function transferBNB( const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex); console.log("广播成功！txHash：", txResponse.hash); - // 等待确认（可选） - const receipt = await txResponse.wait(); - console.log("已在区块中确认：", receipt?.blockNumber); + // 等待确认（可选 — 添加超时以防止无限阻塞） + try { + const receipt = await txResponse.wait(1); // 等待 1 个确认，超时则抛出异常 + console.log("已在区块中确认：", receipt?.blockNumber); + } catch (e) { + console.warn("等待回执超时或失败：", e); + } return txResponse.hash; } @@ -389,8 +399,8 @@ async def transfer_bnb(to_address: str, amount_ether: str): tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) print("广播成功！txHash：", tx_hash.hex()) - # 等待确认（可选） - receipt = await w3.eth.wait_for_transaction_receipt(tx_hash) + # 等待确认（可选 — 添加超时以防止无限阻塞） + receipt = await w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120) print("已在区块中确认：", receipt["blockNumber"]) return tx_hash.hex() diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index 70de7e35..efc75234 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -165,11 +165,12 @@ source ~/.zshrc 说明全局安装没有生效。检查： ```bash # 确认 npm 全局 bin 目录在 PATH 里 -npm bin -g +npm prefix -g +# 全局 bin 目录为：$(npm prefix -g)/bin ``` 如果输出的路径不在你的 `$PATH` 中，手动添加： ```bash -echo "export PATH=$(npm bin -g):$PATH" >> ~/.zshrc +echo "export PATH=$(npm prefix -g)/bin:$PATH" >> ~/.zshrc source ~/.zshrc ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 7a17e415..4c5a9e90 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -146,6 +146,17 @@ source ~/.bashrc +:::info 没有 WSL 的 Windows 用户？ +如果你使用的是原生 Windows（未安装 WSL），可以通过 PowerShell 或系统属性设置环境变量： + +```powershell +# PowerShell — 为当前用户永久设置 +[Environment]::SetEnvironmentVariable("AGENT_WALLET_PASSWORD", "你的主密码", "User") +``` + +或者打开 **系统属性 → 高级 → 环境变量**，手动添加 `AGENT_WALLET_PASSWORD`。设置后请重启终端。 +::: + :::tip 为什么不用 echo 命令？ `echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。 ::: @@ -154,11 +165,11 @@ source ~/.bashrc 自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉： ```bash -# 正确 — 单引号，密码原样保存 -echo "export AGENT_WALLET_PASSWORD='P@ss$w0rd!'" >> ~/.zshrc +# ✅ 正确 — 单引号，密码原样保存 +export AGENT_WALLET_PASSWORD='P@ss$w0rd!' -# 错误 — 双引号包密码，$ 被 shell 展开，密码静默出错 -echo "export AGENT_WALLET_PASSWORD=\"P@ss$w0rd!\"" >> ~/.zshrc +# ❌ 错误 — 双引号，$w0rd 被 shell 展开为空字符串，密码静默出错 +export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" ``` ::: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index b5082cb1..d32d7d29 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **验证密码**：运行 `echo $AGENT_WALLET_PASSWORD` 确认变量已正确设置。 2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -3. **密码丢失**：需要重新初始化钱包。运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +3. **密码丢失**：需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 ### "Conflicting wallet modes" diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index a352ddec..87e351a4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -93,7 +93,7 @@ `AGENT_WALLET_PASSWORD` 必须与钱包初始化时设置的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -如果密码丢失，需要重新初始化钱包。运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +如果密码丢失，需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 From b92448f823da726e982a60007eb2e0709c4a93e9 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 13:44:19 +0800 Subject: [PATCH 23/44] fix audio new issues --- docs/Agent-Wallet/Developer/CLI-Reference.md | 14 +++++++++++--- docs/Agent-Wallet/Developer/SDK-Cookbook.md | 19 ++++++++++++++++--- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- .../Agent-Wallet/Developer/CLI-Reference.md | 14 +++++++++++--- .../Agent-Wallet/Developer/SDK-Cookbook.md | 19 ++++++++++++++++--- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- 6 files changed, 56 insertions(+), 14 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index e44754d0..4e64cc66 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -95,7 +95,7 @@ agent-wallet inspect my-bsc-wallet **Sign with a specific wallet** (without switching the active one): ```bash -agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!' ``` **Remove a wallet:** @@ -164,7 +164,7 @@ jobs: After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets ``` :::danger This disables the dual-lock protection @@ -173,6 +173,14 @@ Caching the password next to the wallet file means a single file system compromi `runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Make sure this file is never committed to git or synced to the cloud. The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`. + +To remove the cached password and restore full dual-lock protection: + +```bash +rm ~/.agent-wallet/runtime_secrets.json +``` + +After deletion, signing commands will prompt for the password interactively again (or read from `AGENT_WALLET_PASSWORD` if set). ::: ### Method C: Inline `-p` Flag (For One-Off Commands) @@ -180,7 +188,7 @@ The tool automatically sets restrictive file permissions (`600` — owner-read-o Pass the password directly at the end of the command. The program takes the password and runs immediately — no prompts: ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' ``` :::danger Security Warning diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index bda0a406..b15231f3 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -131,6 +131,9 @@ async function transferTRX( if (!signedTx.signature) { throw new Error("Signed transaction is missing the signature field"); } + if (!signedTx.txID) { + throw new Error("Signed transaction is missing the txID field"); + } console.log("Signed, signature:", signedTx.signature); // Step 4: Broadcast via TronGrid @@ -399,9 +402,19 @@ async def transfer_bnb(to_address: str, amount_ether: str): tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) print("Broadcast successful! txHash:", tx_hash.hex()) - # Wait for confirmation (optional — add timeout to avoid blocking forever) - receipt = await w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120) - print("Confirmed in block:", receipt["blockNumber"]) + # Optional: wait for confirmation + # NOTE: This blocks the event loop for up to `timeout` seconds. + # For production AI agents, consider running this in a background task + # or using asyncio.wait_for() with a shorter timeout and retry logic. + import asyncio + try: + receipt = await asyncio.wait_for( + w3.eth.wait_for_transaction_receipt(tx_hash), + timeout=120 + ) + print("Confirmed in block:", receipt["blockNumber"]) + except asyncio.TimeoutError: + print("Confirmation timed out — the transaction may still confirm. txHash:", tx_hash.hex()) return tx_hash.hex() diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 428265f8..689eed9d 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -91,7 +91,7 @@ If the server reports an invalid private key at startup, it's usually a format i ### "Agent wallet password incorrect" error -`AGENT_WALLET_PASSWORD` must exactly match the master password set during wallet initialization. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. +`AGENT_WALLET_PASSWORD` must exactly match the master password generated when you ran `agent-wallet start`. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. If the password is lost, you'll need to re-initialize. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index b150855d..86d8b42c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -95,7 +95,7 @@ agent-wallet inspect my-bsc-wallet **用指定钱包签名**（不切换活跃钱包）： ```bash -agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p "Abc12345!" +agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!' ``` **删除钱包：** @@ -164,7 +164,7 @@ jobs: 执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets ``` :::danger 此操作会使双重锁保护失效 @@ -173,6 +173,14 @@ agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets `runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。务必确保该文件不会被提交到 git 或同步到云端。 工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。 + +要删除已缓存的密码并恢复完整的双重锁保护： + +```bash +rm ~/.agent-wallet/runtime_secrets.json +``` + +删除后，签名命令将再次以交互方式提示输入密码（或从 `AGENT_WALLET_PASSWORD` 环境变量读取）。 ::: ### 方式 C：命令行内联 `-p`（适合临时跑单次指令） @@ -180,7 +188,7 @@ agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets 直接把密码写在命令的结尾。程序拿到密码就直接干活，不会再停下来问你： ```bash -agent-wallet sign msg "Hello" -n tron -p "Abc12345!" +agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' ``` :::danger 安全提示 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index 4399f09a..90c4cacd 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -131,6 +131,9 @@ async function transferTRX( if (!signedTx.signature) { throw new Error("签名后的交易缺少 signature 字段"); } + if (!signedTx.txID) { + throw new Error("签名后的交易缺少 txID 字段"); + } console.log("已签名，signature：", signedTx.signature); // 第四步：通过 TronGrid 广播 @@ -399,9 +402,19 @@ async def transfer_bnb(to_address: str, amount_ether: str): tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(signed_tx_hex)) print("广播成功！txHash：", tx_hash.hex()) - # 等待确认（可选 — 添加超时以防止无限阻塞） - receipt = await w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120) - print("已在区块中确认：", receipt["blockNumber"]) + # 可选：等待确认 + # 注意：此调用会阻塞事件循环最多 `timeout` 秒。 + # 生产环境的 AI Agent 建议在后台任务中执行， + # 或使用 asyncio.wait_for() 配合更短的超时和重试逻辑。 + import asyncio + try: + receipt = await asyncio.wait_for( + w3.eth.wait_for_transaction_receipt(tx_hash), + timeout=120 + ) + print("已在区块中确认：", receipt["blockNumber"]) + except asyncio.TimeoutError: + print("等待确认超时——交易可能仍会被确认。txHash：", tx_hash.hex()) return tx_hash.hex() diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 87e351a4..77fd737b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -91,7 +91,7 @@ ### "Agent Wallet 密码错误" -`AGENT_WALLET_PASSWORD` 必须与钱包初始化时设置的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 +`AGENT_WALLET_PASSWORD` 必须与运行 `agent-wallet start` 时生成的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 如果密码丢失，需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 From 26ff9f52e645c54eeb526fc29a4d8475cfd6a86c Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 14:04:45 +0800 Subject: [PATCH 24/44] fix MAJOR-1: echo $AGENT_WALLET_PASSWORD Instructs Users to Print Password to Terminal --- docs/Agent-Wallet/Developer/CLI-Reference.md | 9 +++++++-- docs/Agent-Wallet/Developer/SDK-Guide.md | 4 ++-- docs/Agent-Wallet/FAQ.md | 2 +- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 12 ++++++------ .../Agent-Wallet/Developer/CLI-Reference.md | 11 +++++++++-- .../current/Agent-Wallet/Developer/SDK-Guide.md | 4 ++-- .../current/Agent-Wallet/FAQ.md | 2 +- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 16 ++++++++-------- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- 9 files changed, 37 insertions(+), 25 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index 4e64cc66..52e74f41 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -240,8 +240,13 @@ This minimal example demonstrates how to perform a non-interactive signing opera # Enable strict mode: stop immediately on any error set -e -# 1. Pre-inject the password so all subsequent signing commands run silently -export AGENT_WALLET_PASSWORD='your-master-password' +# 1. Password should already be set in the environment before running this script. +# e.g. via ~/.zshrc / ~/.bashrc — see "Permanently Save and Activate the Password" in QuickStart. +# NEVER hardcode a real password in a script file (it will end up in git history). +if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then + echo "Error: AGENT_WALLET_PASSWORD not set" >&2 + exit 1 +fi echo "Calling local encrypted safe for signing..." diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md index b3012a9f..92588604 100644 --- a/docs/Agent-Wallet/Developer/SDK-Guide.md +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -172,9 +172,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local vault and feed the private key directly to the SDK. ```bash -export AGENT_WALLET_PRIVATE_KEY="your-private-key-in-hex" +export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex' # or -export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." +export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' ``` :::danger Extremely Dangerous: Violates Core Security Principles! diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index 9cb79e3d..c71c8bf6 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -198,7 +198,7 @@ No. Agent-wallet is a standalone signing tool that can be used independently via Troubleshoot in this order: -1. Confirm the `AGENT_WALLET_PASSWORD` environment variable is set (run `echo $AGENT_WALLET_PASSWORD` in the terminal where OpenClaw is running) +1. Confirm the `AGENT_WALLET_PASSWORD` environment variable is set (run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` in the terminal where OpenClaw is running) 2. Confirm the MCP Server was started **after** the environment variable was set 3. Confirm a wallet has been initialized: `agent-wallet list` should show at least one wallet 4. If everything above checks out, try signing manually via CLI: `agent-wallet sign msg "test" -n tron` diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 07ec0983..4cdd62ba 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -133,7 +133,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **Resolution Steps:** -1. **Verify password**: Run `echo $AGENT_WALLET_PASSWORD` to confirm the variable is set correctly. +1. **Verify password is set**: Run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` to confirm the variable is set without revealing the value. 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. 3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. @@ -148,17 +148,17 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' ```bash # Option 1: Agent Wallet (recommended for production) -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' unset TRON_PRIVATE_KEY unset TRON_MNEMONIC # Option 2: Private Key (testnet only) -export TRON_PRIVATE_KEY="your_64_hex_chars" +export TRON_PRIVATE_KEY='your_64_hex_chars' unset AGENT_WALLET_PASSWORD unset TRON_MNEMONIC # Option 3: Mnemonic -export TRON_MNEMONIC="word1 word2 ... word12" +export TRON_MNEMONIC='word1 word2 ... word12' unset AGENT_WALLET_PASSWORD unset TRON_PRIVATE_KEY ``` @@ -169,7 +169,7 @@ unset TRON_PRIVATE_KEY unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC # Set only one -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' # Restart server sun-mcp-server @@ -264,7 +264,7 @@ sun-mcp-server 1. **Check Wallet Support** ```bash # Agent Wallet must support signTypedData - echo $AGENT_WALLET_PASSWORD # Confirm set + [[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set" ``` 2. **Verify Signature Data** diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 86d8b42c..0a71af4d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -219,6 +219,8 @@ agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet agent-wallet change-password ``` + + ### `agent-wallet reset`（重置所有数据） 删除 `~/.agent-wallet/` 下的所有内容。**这是核弹级操作——一旦执行，所有钱包、密钥、配置全部消失，无法恢复。** 系统会要求二次确认。 @@ -240,8 +242,13 @@ CLI 不只是拿来手敲的——它可以完美嵌入你的自动化脚本。 # 开启严格模式：遇到报错立刻停止 set -e -# 1. 提前注入密码，让后续的签名命令全程静默无弹窗 -export AGENT_WALLET_PASSWORD='你的主密码' +# 1. 密码应在运行此脚本之前已在环境中设置好。 +# 例如通过 ~/.zshrc / ~/.bashrc — 详见快速开始中的"永久保存并使密码生效"。 +# 切勿在脚本文件中硬编码真实密码（密码会随脚本进入 git 历史记录）。 +if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then + echo "错误：AGENT_WALLET_PASSWORD 未设置" >&2 + exit 1 +fi echo "正在调用本地保险箱签名..." diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md index 9cf94c1b..bdb6f202 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md @@ -172,9 +172,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" 如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地加密保险箱，直接把私钥喂给 SDK。 ```bash -export AGENT_WALLET_PRIVATE_KEY="你的私钥十六进制" +export AGENT_WALLET_PRIVATE_KEY='你的私钥十六进制' # 或 -export AGENT_WALLET_MNEMONIC="word1 word2 word3 ..." +export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' ``` :::danger 极度危险：违背核心安全原则！ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index efc75234..b87ecb9c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -198,7 +198,7 @@ source ~/.zshrc 按以下顺序排查： -1. 确认 `AGENT_WALLET_PASSWORD` 环境变量已设置（在运行 OpenClaw 的那个终端里执行 `echo $AGENT_WALLET_PASSWORD` 验证） +1. 确认 `AGENT_WALLET_PASSWORD` 环境变量已设置（在运行 OpenClaw 的那个终端里执行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 验证，不会泄露密码明文） 2. 确认 MCP Server 是在设置了环境变量**之后**启动的 3. 确认钱包已初始化：`agent-wallet list` 应该能看到至少一个钱包 4. 如果以上都正确，尝试用 CLI 手动签名测试：`agent-wallet sign msg "test" -n tron` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index d32d7d29..36d87241 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -133,9 +133,9 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' **解决步骤：** -1. **验证密码**：运行 `echo $AGENT_WALLET_PASSWORD` 确认变量已正确设置。 +1. **验证密码已设置**：运行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 确认变量已设置（不会泄露密码明文）。 2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -3. **密码丢失**：需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 +3. **密码丢失**：需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 ### "Conflicting wallet modes" @@ -148,17 +148,17 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' ```bash # 选项 1：Agent Wallet（推荐用于生产） -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' unset TRON_PRIVATE_KEY unset TRON_MNEMONIC # 选项 2：私钥（仅限测试网） -export TRON_PRIVATE_KEY="your_64_hex_chars" +export TRON_PRIVATE_KEY='your_64_hex_chars' unset AGENT_WALLET_PASSWORD unset TRON_MNEMONIC # 选项 3：助记词 -export TRON_MNEMONIC="word1 word2 ... word12" +export TRON_MNEMONIC='word1 word2 ... word12' unset AGENT_WALLET_PASSWORD unset TRON_PRIVATE_KEY ``` @@ -169,7 +169,7 @@ unset TRON_PRIVATE_KEY unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC # 只设置一个 -export AGENT_WALLET_PASSWORD="your_password" +export AGENT_WALLET_PASSWORD='your_password' # 重启服务器 sun-mcp-server @@ -264,14 +264,14 @@ sun-mcp-server 1. **检查 Wallet 支持** ```bash # Agent Wallet 必须支持 signTypedData - echo $AGENT_WALLET_PASSWORD # 确认已设置 + [[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置" ``` 2. **验证签名数据** - 检查 Permit2 请求的结构化数据 - 确认链 ID、代币地址、截止时间正确 -3. **重新初始化 Wallet** — 运行 `agent-wallet reset` 清除并重新开始。详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)。 +3. **重新初始化 Wallet** — 运行 `agent-wallet reset` 清除并重新开始。详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)。 4. **使用备用授权方法** ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 77fd737b..da701021 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -93,7 +93,7 @@ `AGENT_WALLET_PASSWORD` 必须与运行 `agent-wallet start` 时生成的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -如果密码丢失，需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +如果密码丢失，需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 From 4dff899eb2f53f165b4636b73e49896c19597ce5 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 14:20:28 +0800 Subject: [PATCH 25/44] fix new major audio issues --- docs/Agent-Wallet/Developer/CLI-Reference.md | 6 +++++- docs/Agent-Wallet/Intro.md | 2 +- docs/Agent-Wallet/QuickStart.md | 2 +- .../MCP/SUNMCPServer/LocalPrivatizedDeployment.md | 2 +- .../MCP/TRONMCPServer/LocalPrivatizedDeployment.md | 2 +- .../current/Agent-Wallet/Developer/CLI-Reference.md | 6 +++++- .../current/Agent-Wallet/Intro.md | 2 +- .../current/Agent-Wallet/QuickStart.md | 2 +- .../MCP/SUNMCPServer/LocalPrivatizedDeployment.md | 2 +- .../MCP/TRONMCPServer/LocalPrivatizedDeployment.md | 2 +- 10 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index 52e74f41..db46e9c2 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -20,6 +20,10 @@ agent-wallet start ``` The system walks you through choosing a wallet type, generating keys, and setting a master password. Just follow the prompts. +:::danger Avoid the `raw_secret` wallet type for real funds +The interactive wizard may offer a `raw_secret` option. This type stores your private key **unencrypted** on disk — any program with file system access can read it directly. Only use `raw_secret` in fully isolated test environments. For any wallet holding real funds, always choose `local_secure`. +::: + **Custom password:** ```bash agent-wallet start -p Abc12345! @@ -127,7 +131,7 @@ agent-wallet sign tx '{"txID":"..."}' -n tron ``` :::tip Prevent this command from being recorded in shell history -Prefix the command with a space (requires `HISTCONTROL=ignorespace` in Bash or `setopt HIST_IGNORE_SPACE` in Zsh — both are enabled by default on most systems). Or edit `~/.zshrc` / `~/.bashrc` directly in a text editor to avoid history exposure entirely. +To prevent the command from being recorded in shell history, edit `~/.zshrc` / `~/.bashrc` directly in a text editor rather than running the command in the terminal. Alternatively, prefix the command with a space — but only if you have verified that `HISTCONTROL=ignorespace` is active in Bash (`echo $HISTCONTROL`) or `HIST_IGNORE_SPACE` is active in Zsh (`setopt | grep HIST_IGNORE_SPACE`). These settings are **not** enabled by default on most systems and must be configured explicitly. ::: :::caution Password contains special characters? Always use single quotes diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 59a62375..354626a4 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -84,7 +84,7 @@ agent-wallet sign msg "Hello from my AI agent" -n tron When a hash string appears on screen — congratulations, your encrypted safe is live. -> Want the full step-by-step walkthrough? Head to **[CLI Reference](./Developer/CLI-Reference.md)**. +> Want the full step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. --- diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 19342579..8ad2855b 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -78,7 +78,7 @@ Wallets: │ default │ local_secure │ └───────────┴──────────────┘ -Your master password: WiJxcI#t6@73K#OE +Your master password: Save this password! You'll need it for signing and other operations. Active wallet: default diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 7b7c1bdd..a61b249c 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -72,7 +72,7 @@ This is the most secure option. Private keys are encrypted and stored on local d export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index cdf08be1..a411d406 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -78,7 +78,7 @@ This is the most secure option. Private keys are encrypted and stored on local d export AGENT_WALLET_PASSWORD='' # Optional: specify custom wallet directory (default: ~/.agent-wallet) -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 0a71af4d..9e571adf 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -20,6 +20,10 @@ agent-wallet start ``` 系统会一步步引导你选择钱包类型、生成密钥、设置主密码。跟着提示走就行。 +:::danger 切勿对真实资金使用 `raw_secret` 钱包类型 +交互式向导可能会提供 `raw_secret` 选项。该类型将私钥**以明文形式**存储在磁盘上——任何有文件系统访问权限的程序都能直接读取。`raw_secret` 仅适用于完全隔离的测试环境。持有真实资金的钱包请始终选择 `local_secure`。 +::: + **自定义密码：** ```bash agent-wallet start -p Abc12345! @@ -127,7 +131,7 @@ agent-wallet sign tx '{"txID":"..."}' -n tron ``` :::tip 防止此命令被记录到 Shell 历史 -在命令前加一个空格（需要 Bash 中启用 `HISTCONTROL=ignorespace` 或 Zsh 中启用 `setopt HIST_IGNORE_SPACE`——大多数系统默认已开启）。或者直接用文本编辑器编辑 `~/.zshrc` / `~/.bashrc`，从根本上避免历史记录泄露。 +建议直接用文本编辑器编辑 `~/.zshrc` / `~/.bashrc`，从根本上避免历史记录泄露。如果选择在命令前加空格来阻止记录，请先确认你的 Shell 已启用相应设置：Bash 中运行 `echo $HISTCONTROL` 确认包含 `ignorespace`，Zsh 中运行 `setopt | grep HIST_IGNORE_SPACE` 确认已开启。这些设置在大多数系统上**并非**默认启用，需要手动配置。 ::: :::caution 密码有特殊字符？务必用单引号 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index 3a4da198..895a3bb6 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -83,7 +83,7 @@ agent-wallet sign msg "Hello from my AI agent" -n tron 当屏幕上吐出一串哈希字符时——恭喜，你的加密保险箱配置成功了。 -> 想看每一步的详细说明？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。 +> 想看每一步的详细说明？去 **[快速开始](./QuickStart.md)**。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 4c5a9e90..abb4e04c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -78,7 +78,7 @@ Wallets: │ default │ local_secure │ └───────────┴──────────────┘ -Your master password: WiJxcI#t6@73K#OE +Your master password: <此处会显示你的专属密码> Save this password! You'll need it for signing and other operations. Active wallet: default diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 05ac541f..9447b5bf 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -72,7 +72,7 @@ import TabItem from '@theme/TabItem'; export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index e0416d24..6d7c8b8a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -78,7 +78,7 @@ node --version # 应输出 v20.x.x 或更高 export AGENT_WALLET_PASSWORD='<你的主密码>' # 可选：指定自定义钱包目录（默认：~/.agent-wallet） -export AGENT_WALLET_DIR="~/.agent-wallet" +export AGENT_WALLET_DIR="$HOME/.agent-wallet" ``` From 1ec91183d19b13334da7da836ef1aca898ebbc50 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 14:29:09 +0800 Subject: [PATCH 26/44] fix --- docs/Agent-Wallet/QuickStart.md | 16 ++++++++++------ .../current/Agent-Wallet/QuickStart.md | 16 ++++++++++------ 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 8ad2855b..fbb280bb 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -122,6 +122,10 @@ export AGENT_WALLET_PASSWORD='your-master-password' source ~/.zshrc ``` +:::tip Why not use the echo command? +While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history. +::: + @@ -143,9 +147,6 @@ export AGENT_WALLET_PASSWORD='your-master-password' source ~/.bashrc ``` - - - :::info Windows without WSL? If you're on native Windows (no WSL), set the environment variable via PowerShell or System Properties: @@ -157,9 +158,12 @@ If you're on native Windows (no WSL), set the environment variable via PowerShel Or open **System Properties → Advanced → Environment Variables** and add `AGENT_WALLET_PASSWORD` manually. Restart your terminal after setting it. ::: -:::tip Why not use the echo command? -While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history. -::: + + + + + + :::caution Password has special characters? Don't touch the single quotes! Auto-generated passwords often contain `$`, `!`, and other special characters. The commands above already use single quotes to wrap the password — **just replace the text inside the quotes, never switch to double quotes**, or the shell will silently mangle the value: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index abb4e04c..7f85ef09 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -122,6 +122,10 @@ export AGENT_WALLET_PASSWORD='你的主密码' source ~/.zshrc ``` +:::tip 为什么不用 echo 命令？ +`echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。 +::: + @@ -143,9 +147,6 @@ export AGENT_WALLET_PASSWORD='你的主密码' source ~/.bashrc ``` - - - :::info 没有 WSL 的 Windows 用户？ 如果你使用的是原生 Windows（未安装 WSL），可以通过 PowerShell 或系统属性设置环境变量： @@ -157,9 +158,12 @@ source ~/.bashrc 或者打开 **系统属性 → 高级 → 环境变量**，手动添加 `AGENT_WALLET_PASSWORD`。设置后请重启终端。 ::: -:::tip 为什么不用 echo 命令？ -`echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。 -::: + + + + + + :::caution 密码有特殊字符？千万不要动单引号！ 自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉： From a5b2e70e950a4871ecd03d3f99499b970de36d58 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Sun, 22 Mar 2026 19:36:24 +0800 Subject: [PATCH 27/44] highlight agent wallet --- docs/Agent-Wallet/Intro.md | 2 +- .../current/Agent-Wallet/Intro.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 354626a4..7385f22c 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -28,7 +28,7 @@ The common thread: **your private key is always exposed somewhere** — on disk, --- -## The Fix: A Web3 Wallet Built for AI Agents +## The Breakthrough: Agent-Wallet — The Web3 Wallet Designed Exclusively for AI When you use a Web3 wallet like MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index 895a3bb6..8b5b1df1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -27,7 +27,7 @@ --- -## 破局之道：AI 界专属的 Web3 钱包 +## 破局之道：Agent-Wallet —— 专为 AI 打造的 Web3 钱包 你平时用 Web3 钱包（比如 MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。 From b6e023f7aae5a79c39ebba64a451621d5375732b Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 10:58:36 +0800 Subject: [PATCH 28/44] workflow add update-mcp-server --- .github/workflows/docker.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 4516d0c9..5e67525d 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -5,12 +5,14 @@ on: branches: - main - master + - update-mcp-server tags: - 'test' pull_request: branches: - main - master + - update-mcp-server workflow_dispatch: # Intentionally unrestricted — allows manual builds from any branch for flexibility env: From b1e80c306eb2ac486d441e9d0b7b27746adbed49 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 11:09:43 +0800 Subject: [PATCH 29/44] update skills docs --- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 257 ++++++++---------- docs/McpServer-Skills/SKILLS/Faq.md | 223 +++++++-------- docs/McpServer-Skills/SKILLS/Intro.md | 143 ++++------ docs/McpServer-Skills/SKILLS/QuickStart.md | 151 ++++++++++ .../current/McpServer-Skills/Intro.md | 8 +- .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 257 ++++++++---------- .../current/McpServer-Skills/SKILLS/Faq.md | 225 ++++++++------- .../current/McpServer-Skills/SKILLS/Intro.md | 143 ++++------ .../McpServer-Skills/SKILLS/QuickStart.md | 151 ++++++++++ sidebars.js | 1 + 10 files changed, 841 insertions(+), 718 deletions(-) create mode 100644 docs/McpServer-Skills/SKILLS/QuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index af00d6c3..1eca2864 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,227 +1,192 @@ -# BANK OF AI Skills +# Skill Catalog -BANK OF AI Skills is a collection of ready-to-use skill packages designed for AI Agents, covering a wide range of scenarios within the TRON ecosystem—such as DEX trading, perpetual contracts, on-chain data queries, and payment protocols. Each skill encapsulates a complete business workflow, including how to call APIs, the order of execution steps, how to handle authorization, and how to safeguard user assets, all defined within `SKILL.md` and supporting scripts. +You don't need to write code or understand the technical details. Just copy the sample prompts below into your AI chat, hit enter, and the AI takes care of the rest. -You don't need to write code — just tell the AI in natural language what you want to do, and it will automatically find and execute the corresponding skill. +:::warning Three Golden Rules +BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactions are **irreversible** — there's no undo button, no customer service rollback. -:::warning Before Using Any Skill, Please Read -BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactions are **irreversible** once on-chain — there's no "undo" button, no customer service rollback, and funds sent to the wrong address cannot be recovered. Remember three essential rules before using: - -1. **Private keys must never appear in chat windows or config files.** Only pass them through environment variables (like `TRON_PRIVATE_KEY`). If a private key is compromised, move assets to a new wallet immediately. -2. **Test on testnet first, then mainnet.** Every new operation must be verified first on Nile or Shasta testnet before switching to mainnet execution. -3. **Write operations require manual confirmation.** Before executing any on-chain transaction, the AI should show you the complete operation details and wait for your explicit confirmation. +1. **Never paste your private key into a chat window.** Use [Agent Wallet](../../Agent-Wallet/Intro.md) instead (think of it as opening a dedicated "payment account" for your AI — you don't hand over your bank password directly). +2. **Practice with play money first.** Every new operation should be tested on the Nile testnet — it uses free test tokens, so there's nothing to lose. +3. **Read the confirmation prompt carefully.** Before any on-chain transaction, the AI will show you the full bill and wait for your explicit "yes." ::: --- -## Available Skills Overview +## Skill Summary -| Skill | Version | Functionality | Required Credentials | -| :--- | :--- | :--- | :--- | -| **sunswap** | v2.0.0 | SunSwap DEX trading — balance, quotes, swaps, V2/V3 liquidity | `TRON_PRIVATE_KEY` | -| **sunperp-skill** | v1.0.0 | SunPerp perpetual contracts — market data, orders, positions, withdrawals | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | -| **tronscan-skill** | v1.0.0 | TronScan on-chain data queries — accounts, transactions, tokens, blocks | `TRONSCAN_API_KEY` | -| **x402-payment** | v1.4.0 | x402 protocol payments — calling paid APIs and paid agents | `TRON_PRIVATE_KEY` or `EVM_PRIVATE_KEY` | -| **recharge-skill** | v1.1.1 | BANK OF AI balance queries, order history, TRC20 recharge via MCP | `BANKOFAI_API_KEY` | +| Skill | What It Does | What Key/Credential Do I Need? | +| :--- | :--- | :--- | +| **sunswap** | Check prices, get quotes, swap tokens, manage liquidity pools | Read-only: none. Trading: wallet credentials | +| **sunperp-skill** | Market data, open/close positions, withdrawals | Market data: none. Trading: SunPerp API keys | +| **tronscan-skill** | Look up accounts, transactions, tokens, blocks, network stats | Recommended: TronScan API key (may throttle without one) | +| **x402-payment** | Auto-pay for premium APIs and agents | Wallet credentials | +| **recharge-skill** | Balance, order history, account top-up | BANK OF AI API key | ---- +### 🔑 Where Do I Get These Keys? How Do I Set Them Up? + +If you just want the AI to look up public data (like token prices or block height), you don't need to configure anything — just start using it. -## Installation +But if you want to unlock advanced features or trading, grab the keys you need below: -The simplest installation method is using **OpenClaw Extension** — install all components with one command, automatically configure the skills directory, and the AI is ready out of the box: +**1. Wallet Credentials (for spending money and trading)** -```bash -# Method 1: Direct run (for trusted sources) -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +- **Where to get it:** You don't need to apply anywhere — this is simply your TRON wallet private key. +- **How to set it up:** We've prepared two options in [Quick Start](./QuickStart.md#-want-the-ai-to-trade-for-you) — pick whichever suits you: + - **Option 1 (Recommended):** Use [Agent Wallet](../../Agent-Wallet/QuickStart.md) — visual interface, 2 minutes, private key encrypted and never exposed. + - **Option 2:** Paste your private key directly into your system config file (the "notepad method") — great for power users or quick testing. -# Method 2: Check script before running (recommended) -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +**2. TronScan API Key (your VIP pass for data queries)** -After installation, skills will be placed in the `~/.openclaw/skills/` directory, and OpenClaw will automatically discover and load them. +You can query data without this, but if you query too fast, the system may rate-limit you. With a key, you get the VIP fast lane. -Verify that skills are ready after installation: +- **Where to get it (completely free):** Go to [TronScan](https://tronscan.org/), register an account, and click to generate a key. +- **How to set it up:** Follow the same "notepad method" in [Quick Start — "Want the AI to Trade for You?"](./QuickStart.md#-want-the-ai-to-trade-for-you) and paste `TRONSCAN_API_KEY` in the same way. -```bash -ls ~/.openclaw/skills -``` +**3. SunPerp API Keys (for perpetual contract trading)** -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. +- **Where to get them:** Go to [SunPerp](https://sunperp.com/), connect your wallet, then generate an API Key and Secret in your account settings. +- **How to set them up:** Use the same "notepad method" to paste `SUNPERP_ACCESS_KEY` and `SUNPERP_SECRET_KEY` into your config file. -### Installation on Other Platforms +**4. BANK OF AI API Key (for balance checks and account top-ups)** -If you use Claude Code, Cursor, or other AI tools that support Skills, you can also install manually: +- **Where to get it:** Go to [chat.bankofai.io/key](https://chat.bankofai.io/key) and log in to get your key. +- **How to set it up:** Use the notepad method to paste `BANKOFAI_API_KEY`. -**Claude Code:** +--- -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ -``` +## Haven't Installed Yet? -Claude Code will automatically load these skills when it starts. +Head over to **[Quick Start](./QuickStart.md)** — it takes about 1 minute. Come back here to pick your skills once you're set up. -**Cursor:** +--- -```bash -# Clone to project root -git clone https://github.com/BofAI/skills.git .cursor/skills -``` +## sunswap — Swap Tokens, Check Prices, Manage Pools -In Cursor Chat, use the `@` symbol to reference specific `SKILL.md` files for context, or add the skills path to `.cursorrules`. +Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. -**Universal Method (any AI tool):** +**Completely safe — looking only, no spending:** -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` +> What's the current price of TRX? -Then explicitly tell the AI to read a skill file in your conversation: +> How much TRX can I get for 100 USDT on SunSwap? -``` -Please read ~/bofai-skills/sunswap/SKILL.md and help me check the current price of TRX. -``` +> Show me the top 10 highest-APY pools on SunSwap. ---- +> Show me all my current SunSwap V3 liquidity positions. -## Verify Installation +**Requires your confirmation (AI shows the bill first):** -After installation, starting with read-only operations is the best entry point — no private keys needed, zero risk, perfect for getting familiar with how skills work. +> Swap 100 TRX for USDT on the SunSwap Nile testnet. -In your client, enter: +> Add 100 TRX and 15 USDT liquidity to the TRX/USDT pool on SunSwap V2. -``` -How much TRX can I get for 100 USDT on SunSwap? -``` +> Collect fee rewards from V3 position #12345. -``` -Help me check the current market data for BTC-USDT perpetual contract. -``` +**Real-world scenarios:** + +> Looking for arbitrage? Try: "Is it worth swapping 100 USDT to TRX on SunSwap right now?" + +> Interested in yield farming? Try: "Which V3 pool on SunSwap has the highest APY? Give me an analysis." + +> Looking to buy the dip? Try: "What's TRX's price trend over the last 7 days?" --- -## Usage Examples for Each Skill +## sunperp-skill — Perpetual Contract Trading -Each example is marked with an operation type: -- 🟢 **Read-only** — produces no on-chain transactions, no private key needed -- ⚠️ **Write operation** — initiates on-chain transactions, requires user confirmation before execution +Want to trade contracts? This skill handles market data, opening/closing positions, stop-loss, and withdrawals. Built-in safety: max 20x leverage, mandatory stop-loss — if losses exceed 5%, the AI automatically closes your position to prevent liquidation. -### sunswap +**Completely safe — looking only, no spending:** -``` -# 🟢 Query balance -Help me check my TRX and USDT balances. +> What's the current price, 24h change, and funding rate for BTC-USDT perpetual? -# 🟢 Query price -What's the current price of TRX? +> What's my SunPerp account balance and available margin? -# 🟢 Get swap quote -How much TRX can I get for 100 USDT on SunSwap? +> What open positions do I have? Show entry price, unrealized P&L, and liquidation price. -# ⚠️ Execute swap -Swap 100 TRX for USDT on SunSwap Nile testnet. +**Requires your confirmation:** -# ⚠️ Add liquidity -Add 100 TRX and 15 USDT liquidity to the TRX/USDT pool on SunSwap V2. +> Open 1 BTC-USDT long at market price on SunPerp with 10x leverage, 5% stop loss. -# 🟢 View V3 positions -Help me check all my current SunSwap V3 liquidity positions. +> Close all my BTC-USDT positions. -# ⚠️ Collect fees -Help me collect fee rewards from V3 position #12345. -``` +> Withdraw 10 USDT from SunPerp to my on-chain address. -### sunperp-skill +**Real-world scenarios:** -``` -# 🟢 View market data -What are the current price, 24h change, and funding rate for BTC-USDT perpetual contract? +> Stuck in a bad position? Try: "What's BTC's funding rate right now — should I go long or short?" -# 🟢 View account -What's my SunPerp account balance and available margin? +> Want to manage risk? Try: "Lower my BTC-USDT leverage to 5x and set stop-loss to 3%." -# 🟢 View open positions -What open positions do I have? Show entry price, unrealized P&L and liquidation price. +> Want the big picture? Try: "List all available perpetual contracts, sorted by 24h volume." -# ⚠️ Open position -Open 1 BTC-USDT long position at market price on SunPerp with 10x leverage, set 5% stop loss. +--- + +## tronscan-skill — On-Chain Data Detective -# ⚠️ Close position -Close all my BTC-USDT positions. +Want to know what's happening on-chain? This skill looks up accounts, transactions, tokens, blocks, and network stats. **Pure read-only, completely safe, costs nothing, needs no credentials.** The perfect first skill to get started. -# ⚠️ Withdraw -Withdraw 10 USDT from SunPerp to my on-chain address. -``` +> Look up the full account info and holdings for address TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf. -### tronscan-skill +> Show me the details of this transaction: abc123... -``` -# 🟢 Account query -Help me query the complete account info and holdings for address TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf. +> Show the top 10 TRC20 tokens by market cap. -# 🟢 Transaction query -Query the details of this transaction hash: abc123... +> Give me a TRON network overview: current TPS, Super Representatives, total accounts. -# 🟢 Token info -Show the top 10 TRC20 tokens by market cap. +> Show the last 20 USDT transfers from address TXX... -# 🟢 Network overview -Give me a TRON network overview: current TPS, number of Super Representatives, total accounts. +**Real-world scenarios:** -# 🟢 Transfer history -Query the last 20 USDT transfers from address TXX... -``` +> Found a new token and want to check if it's legit? "Check the holder distribution and contract verification for token TXX..." -### x402-payment +> Tracking a whale? "Show all transactions above 100,000 USDT from address TXX... in the last 24 hours." -``` -# ⚠️ Call paid endpoint -Use x402 protocol to call this paid agent endpoint: https://api.example.com -``` +> Verifying a transfer? "Did this transaction actually succeed: abc123...?" -### recharge-skill +--- -``` -# 🟢 Query balance -How much balance does my BANK OF AI account have? +## x402-payment — Auto-Pay for Premium Services -# 🟢 Query orders -Show my recent BANK OF AI order history. +Some APIs and AI agents charge a small fee to use. This skill handles the payment flow automatically — the AI detects the charge, pays it, gets the result, and reports back. It always asks for your confirmation before paying. -# ⚠️ Recharge -Recharge 1 USDT to my BANK OF AI account. +**Requires your confirmation:** -# ⚠️ Recharge (Chinese) -给 BANK OF AI 充值 1 USDT -``` +> Use x402 protocol to call this paid agent endpoint: https://api.example.com （replace with the actual paid endpoint URL you want to call） --- -## Recommended Learning Path +## recharge-skill — BANK OF AI Account Management + +Check your balance, view order history, or top up your account. + +**Completely safe — looking only, no spending:** + +> How much balance does my BANK OF AI account have? + +> Show my recent BANK OF AI order history. + +**Requires your confirmation:** -If you're just starting with BANK OF AI Skills, following this order makes it smoother: +> Recharge 1 USDT to my BANK OF AI account. + + +--- + +## Recommended Learning Path -Step 1: Read-only queries - → Start with tronscan-skill to query accounts and check transactions, get familiar with skill interaction - → Use sunswap to check prices and quotes, no real trades +**Start here — zero risk, zero config:** Use tronscan-skill to look up accounts and check transactions. Use sunswap to check prices and get quotes. Read-only, no credentials needed. -Step 2: Testnet write operations - → Execute swaps, add liquidity, open contracts on Nile testnet - → Confirm AI behavior matches expectations, parameters pass correctly +**Next — practice with play money:** Set up your wallet (see [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md)), then test swaps and liquidity operations on the Nile testnet. Confirm the AI behaves exactly as expected. -Step 3: Mainnet small transactions - → Verify the complete workflow with small amounts of capital +**Then — mainnet with small amounts:** Run the full flow with a small amount of real funds to make sure everything works. -Step 4: Mainnet production use - → Daily operations, adjust parameters and skill combinations as needed +**Finally — daily use:** Run your regular operations, adjust parameters, and combine skills as needed. --- ## Next Steps -- Want to understand how Skills work? → [What Are Skills?](./Intro.md) -- Encountering issues? → [FAQ](./Faq.md) +- Want to understand how skills work under the hood? → [What Are Skills?](./Intro.md) +- Running into issues? → [FAQ](./Faq.md) - Using OpenClaw Extension? → [OpenClaw Extension Documentation](../../Openclaw-extension/Intro.md) diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index 59e6b7f2..59650803 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -1,204 +1,191 @@ # FAQ -The following questions are arranged in the order you're most likely to encounter them. +Questions are ordered by urgency — the ones you're most likely to hit first are at the top, concepts at the bottom. --- -## Foundational Concepts +## Something Went Wrong -### What's the difference between Skill and MCP Server? +### The AI says "skill not found" or gives a completely wrong answer -This is the most common question. In one sentence: **MCP Server is a toolbox, Skill is an instruction manual.** +Tell the AI exactly where to find the skill file: -MCP Server provides atomic-level tools — like "check balance", "initiate transfer", or "call contract". Skills tell the AI how to combine these tools to complete a full task — for example, "swap tokens on a DEX" requires executing balance check, get quote, verify approval, and execute swap in sequence. Skills define this workflow. +``` +Please read ~/.openclaw/skills/sunswap/SKILL.md and check the current price of TRX. +``` -### Do Skills require separate installation? +If that works, the issue was just the AI's auto-matching. Add clearer keywords next time, like "use the sunswap skill." -No additional application needed. A Skill is just a folder — you only need to place it in a directory that your AI tool can read, and the AI will automatically discover and use it. +If that doesn't work either, check these in order: -However, if a skill contains a `scripts/` directory (as sunswap, sunperp-skill, and tronscan-skill do), you need to run `npm install` once in that directory to install script dependencies. This step is automatic when using OpenClaw Extension. +1. Does the skill directory exist? Run `ls ~/.openclaw/skills` in your terminal. +2. Are dependencies installed? Go to the skill folder and run `npm install` (e.g., `cd ~/.openclaw/skills/tronscan-skill && npm install`). +3. Are credentials configured? See [How do I configure credentials?](#how-do-i-configure-credentials) below. -### Which AI tools support Skills? +### Installation failed -Currently supported: **OpenClaw** (most complete integration), **Claude Code**, **Cursor**, and any AI assistant that can read local files (using explicit invocation method). +Skills require a program called "Node.js" on your computer (similar to how some apps need Java). If installation fails, it's most likely missing or outdated. ---- +**Simplest fix:** Go to [nodejs.org](https://nodejs.org/), download the latest LTS version (install it like any normal app — just click "Next" through the wizard), then try again. -## Installation and Configuration +:::tip Already have Node.js but still getting errors? +Run `node --version` in your terminal. Skills require **v20 or higher**. If your version is too old, download the latest from the official site and install over the old one. +::: -### How do I know the skill installed successfully? +### How do I know the skills installed successfully? + +Run this in your terminal: ```bash ls ~/.openclaw/skills ``` -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. +You should see directory names like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`. -Then verify in OpenClaw: +Then verify in your AI chat: ``` -Read the sunswap skill and tell me what this skill can do. +Read the sunswap skill and tell me what it can do. ``` -If the AI accurately describes the skill content, installation was successful. +If the AI accurately describes the skill's capabilities, you're good to go. -### What if npm install fails? +--- -First confirm your Node.js version: +## Is My Money Safe? -```bash -node --version # needs >= 18 -``` +### Will the AI secretly transfer my funds? -If the version is too old, use nvm to upgrade: +**No.** Every operation that involves spending money will pause first and show you the full "bill" — what it's doing, how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** -```bash -nvm install 18 -nvm use 18 -``` +That said, we recommend using a dedicated wallet with only the funds you intend to trade. Don't load your life savings — just like you wouldn't carry all your cash to the grocery store. -Then run `npm install` again in the skill directory. +### What if my private key is compromised? -### How do I configure credentials (private keys/API keys)? +**First — don't panic. Check which network you were using.** -Configure through environment variables. Depending on which skills you use, add the corresponding variables in `~/.zshrc` or `~/.bashrc`: +If you've been using the **Nile testnet** (which we strongly recommend for beginners), then congratulations — testnet tokens are free play money. Losing them means nothing. Just create a new wallet and move on. -```bash -# TRON wallet (needed for sunswap, sun-mcp-server, x402-payment) -export TRON_PRIVATE_KEY="your_private_key" -export TRONGRID_API_KEY="your_TronGrid_API_Key" +If it's a **mainnet** private key, act immediately: -# SunPerp contract trading (needed for sunperp-skill) -export SUNPERP_ACCESS_KEY="your_SunPerp_Access_Key" -export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" - -# TronScan data queries (needed for tronscan-skill) -export TRONSCAN_API_KEY="your_TronScan_API_Key" +1. Stop using your current AI tool. +2. Create a new wallet. +3. Transfer all assets from the old wallet to the new one. +4. Update all your configurations to point to the new key. +5. Revoke token approvals on all protocols (SunSwap, SunPerp, etc.) connected to the old wallet. -# BANK OF AI (needed for recharge-skill) -export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" -``` +:::tip Prevention is better than cure +Use [Agent Wallet](../../Agent-Wallet/Intro.md) from the start instead of plaintext private keys. Agent Wallet locks your key in an encrypted local vault — even if someone sees your environment variables, they can't open the vault without the encryption password. Two locks broken at once? Extremely unlikely. +::: -After adding them, run `source ~/.zshrc` to apply, then restart your AI tool. +### Why does the AI ask for confirmation before every transaction? ---- +By design. Every time the AI wants to spend your money, it shows you the full details first: what operation, which tokens and amounts, which chain, estimated fees. -## Usage Issues +**This is your last safety checkpoint before real money moves. Don't skip it.** -### The AI says "skill not found" or behaves unexpectedly. What should I do? +### How do I switch between testnet and mainnet? -First switch to **explicit invocation** — directly tell the AI where the skill file is: +Just tell the AI: ``` -Please read ~/.openclaw/skills/sunswap/SKILL.md and help me check the current price of TRX. +Swap 100 TRX for USDT on the Nile testnet. ``` -If explicit invocation works normally, the issue is with implicit triggering matching. Try adding clearer keywords in your task description, like "use sunswap skill", "use tronscan-skill". +The AI switches to testnet automatically. **We strongly recommend testing every new operation on testnet first** — testnet tokens are free, so there's nothing to lose. -If explicit invocation also doesn't work, check if the skill directory exists, npm install is complete, and environment variables are set correctly. +### Why is there a difference between the quoted and actual price? -### How do I switch between testnet and mainnet? +Because the blockchain doesn't pause while you're reading the quote. Between seeing the quote and confirming the transaction, a few seconds to a few minutes may pass, and the price can shift. -Use the `--network` parameter to specify. **Strongly recommend testing every new operation on testnet first**: +The AI handles this with a two-step approach: it shows you a quote first, then right before submitting, it fetches the latest price and uses slippage protection to ensure you don't get a drastically worse deal. -```bash -# Testnet (default, try this first) -node scripts/swap.js TRX USDT 100 --network nile +If extreme volatility causes a transaction to fail, try increasing the tolerance: "Swap 100 TRX for USDT with 1% slippage." -# Mainnet (only after confirming everything works) -node scripts/swap.js TRX USDT 100 --network mainnet --execute -``` +--- -You can also tell the AI directly in conversation: +## Configuration -``` -Help me swap 100 TRX for USDT on the Nile testnet. -``` +### How do I configure credentials? + +**The simplest and safest method (strongly recommended): use [Agent Wallet](../../Agent-Wallet/QuickStart.md).** Think of it as a password-protected vault with a simple visual interface — just follow the prompts to enter your keys. Set it up once, and you'll never have to wrestle with config files again. + +
+Backup method for power users: environment variables -### Why does the AI require confirmation before executing? +If you're comfortable with the command line, you can store credentials in your shell config file. -This is a safety mechanism by design — all write operations (operations involving on-chain transactions) must be explicitly confirmed by the user before execution. +**Mac:** -The AI will show in the confirmation prompt: operation type, tokens and amounts involved, target network, estimated Gas, and slippage. This gives you a chance to verify the operation matches expectations before your funds are actually used. **Don't skip this step, and never enable automatic execution of write operations.** +1. Open Terminal (press `Command + Space`, search for `Terminal`) +2. Type `nano ~/.zshrc` and press Enter — you'll see a basic text editor +3. Use arrow keys to scroll to the bottom, paste the lines you need from below (important: do NOT delete the double quotes `"` around each value, and make sure they're straight quotes, not curly quotes) +4. Press `Ctrl + X`, then `Y`, then Enter to save +5. Close the terminal, reopen it, and restart your AI tool -### What does dry-run (simulation) mean? +**Windows:** We don't recommend Windows beginners manually configure system environment variables. Please use the Agent Wallet method above. If you're using WSL, the steps are the same as Mac (but edit `~/.bashrc` instead). -Scripts in sunswap and other Skills support running without the `--execute` flag — this is dry-run mode. It simulates the execution flow, checks balance and approval status, and gets quotes, but doesn't broadcast any on-chain transactions. +Add the variables for the skills you need: ```bash -# Dry-run: simulate check, no execution -node scripts/swap.js TRX USDT 100 +# SunSwap trading (needed for swap operations) +export TRON_PRIVATE_KEY="your_private_key" +export TRONGRID_API_KEY="your_TronGrid_API_key" -# Real execution -node scripts/swap.js TRX USDT 100 --execute -``` +# SunPerp perpetual contracts +export SUNPERP_ACCESS_KEY="your_SunPerp_Access_Key" +export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" -Running dry-run first is a good habit when unsure. +# TronScan data queries +export TRONSCAN_API_KEY="your_TronScan_API_Key" -### Why is there a difference between the quoted price and the actual execution price? +# BANK OF AI account +export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" +``` -Because there's a time difference between getting the quote and actual execution, during which the price may change. The sunswap script uses a two-step quoting strategy to handle this: the first quote is shown to you for confirmation; after you confirm, it fetches the latest quote right before submitting the actual transaction, then uses the latest quote to calculate the `amountOutMin` as slippage protection. +
-If extreme market volatility causes transaction failure, increasing the slippage tolerance (`--slippage 1.0`) usually fixes it. +### Which AI tools support Skills? ---- +Currently: **OpenClaw** (most seamless), **Claude Code**, **Cursor**, and any AI assistant that can read local files. -## Security and Advanced +--- -### Can I modify a skill? +## Customization -Yes. Edit `SKILL.md` or scripts in `scripts/` directly, and the AI will read the latest version on the next call. You can change operation steps, add custom rules, adjust safety parameters, or add new examples. +### Can I modify a skill's rules? -Modifying `sunperp-skill/resources/sunperp_config.json` lets you adjust leverage limits and stop-loss defaults: +Absolutely. Skills are just regular folders on your computer. Edit anything you want. -```json -{ - "safety": { - "max_leverage": 20, - "stop_loss": { - "required": true, - "default_percent": 5, - "max_percent": 25 - } - } -} -``` +For example, if you think 20x leverage is still too risky for perpetual trading, open `~/.openclaw/skills/sunperp-skill/resources/sunperp_config.json` and lower the number. Your AI, your rules. -### How is skill versioning managed? +### How do I uninstall or update? -Skill versions are marked by the `version` field in the YAML frontmatter of `SKILL.md`. When using OpenClaw Extension, you can specify a specific version via the `GITHUB_BRANCH` environment variable: +**Uninstall:** Delete the folder. ```bash -GITHUB_BRANCH=v1.4.10 ./install.sh # Install specific version -GITHUB_BRANCH=main ./install.sh # Use latest main branch +rm -rf ~/.openclaw/skills/sunswap ``` -The default uses the `v1.4.12` tag version. +**Update:** Re-run the installer. It will ask if you want to overwrite existing skills. -### What if my private key is compromised? +```bash +cd openclaw-extension +./install.sh +``` -**Act immediately, don't hesitate:** +--- -1. Stop using the current AI tool -2. Create a new TRON/EVM wallet address -3. Transfer all assets to the new address (check for pending transactions in the current account first) -4. Update all environment variables to point to the new private key -5. Revoke token approvals on all protocols using the old wallet -6. Review the transaction history of the old wallet to confirm whether any unauthorized operations have occurred +## Concepts (for the Curious) -[Agent Wallet](../../Agent-Wallet/Intro) (encrypted storage) is safer than plaintext private keys — even if environment variables are compromised, attackers still need additional encryption keys to access funds. If you manage significant capital, consider switching to Agent Wallet mode. +### What's the relationship between "skills" and the "toolbox"? -### How do I uninstall or update a skill? +In one sentence: **The toolbox gives the AI abilities. Skills teach it how to use them.** -**Uninstall:** +The toolbox (MCP Server) provides individual capabilities — "check balance," "send transfer." A skill teaches the AI how to string these capabilities together into a complete workflow — "swap tokens" requires checking balance, getting a quote, confirming price, then executing. The skill defines that sequence. -```bash -rm -rf ~/.openclaw/skills/sunswap # Delete specific skill -``` +Analogy: Toolbox = knives, pots, and a stove. Skill = the recipe. -**Update (reinstall the latest version):** +### Will installing lots of skills slow things down? -```bash -cd openclaw-extension -./install.sh # If a skill with the same name exists, the installer will ask if you want to overwrite -``` +No. The AI only loads a "table of contents" at startup (like glancing at shelf labels). It reads the full skill content only when you actually use it. Hundreds of skills? Still lightning fast. diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index c9e0c2dc..4a9fcc0a 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -1,143 +1,102 @@ -# What Are Skills? +# Introduction -You may have already used MCP Server to let an AI assistant check balances, send transfers, and invoke contracts. But you'll notice that some tasks aren't "call a tool once and done" — for example, swapping tokens on a DEX requires checking your balance first, getting a quote, approving the transaction, then executing the swap. Each step involves decision-making and parameter handling. - -**Skills exist precisely for this kind of multi-step task.** - -A Skill is a "task handbook" — it's not a tool itself, but rather instructions that tell the AI how to combine a series of tools in the correct order with the correct parameters to complete a full business workflow. +Welcome to BANK OF AI Skills! In a nutshell, this is a set of **"AI skill packs"** built specifically for the TRON ecosystem. Whether you want to check market prices, execute trades, or track on-chain data, you no longer need to juggle a dozen websites and apps — just tell your AI what to do in plain language, and it handles the heavy lifting. --- -## The Difference Between Skills and MCP Server +## Why Does Your AI Only Talk the Talk? -Many people ask this question when first encountering Skills: what's the difference from MCP Server? +You might already be using an AI chat tool. You ask it "help me swap 100 USDT for TRX on SunSwap," and it gives you a nice list of steps — then does absolutely nothing. It can tell you how to trade, but it can't actually do it for you. -| | MCP Server | Skill | -| :--- | :--- | :--- | -| **Essence** | Tool service | Task handbook + script collection | -| **Purpose** | Provide AI with **atomic capabilities to get things done** | Teach AI **how to combine capabilities to complete a task** | -| **Example** | `mcp-server-tron` provides the `send_trx` tool | `sunswap` tells AI how to use multiple tools to execute a DEX swap | -| **Analogy** | Kitchen knives, pots, and stoves | A recipe | +Why? -Simply put: **MCP Server is a toolbox, Skill is an instruction manual.** A Skill tells the AI which drawer to open, which tool to grab, and what steps to follow to complete the task. +Because until now, your AI was an "armchair expert" — lots of theory, no hands. It knows what a swap is, but it can't check your balance, submit a transaction, or click confirm. --- -## What Does a Skill Look Like? +## Give Your AI a Toolbox and a Playbook -A Skill is a folder with a very simple structure: +Now things are different. We gave the AI two things: -| File/Directory | Purpose | Required? | -| :--- | :--- | :--- | -| `SKILL.md` | Core instruction document — where AI learns how to execute the task | **Yes** | -| `scripts/` | Executable scripts — AI calls these to perform specific operations | Optional | -| `resources/` | Reference data — contract addresses, token lists, config files, etc. | Optional | -| `package.json` | npm dependency declaration (required if the Skill has scripts) | Optional | +**A toolbox (MCP Server)** — the actual ability to look up data and send transactions (like giving it hands). -The top of `SKILL.md` contains YAML Frontmatter that declares basic information about the Skill: +**A playbook (Skill)** — step-by-step instructions for how to complete specific tasks (like giving it a brain for getting work done). -```yaml ---- -name: SunSwap DEX Trading -description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. -version: 2.0.0 -dependencies: - - node >= 18.0.0 - - tronweb -tags: - - defi - - dex - - swap - - tron ---- - -# SunSwap DEX Trading Skill - -## 🚀 Quick Start -...(specific operation instructions) -``` +| | Toolbox (MCP Server) | Playbook (Skill) | +| :--- | :--- | :--- | +| **What it does** | Gives the AI individual abilities | Teaches the AI how to combine abilities into complete workflows | +| **Example** | Provides "check balance" and "send transfer" as individual tools | Defines the full swap flow: check balance → get quote → confirm price → execute trade | +| **Analogy** | Knives, pots, and a stove | The recipe | -The `name` and `description` fields are key for AI to identify and match skills — the more accurate they are, the more easily the AI can find them at the right moment. The main content is the specific operation instructions with no format restrictions — it can be text explanations, code examples, parameter tables, or anything that helps the AI understand. +With a playbook, your AI goes from "an armchair expert who only talks" to "a hands-on trader who actually gets things done." --- -## Why Not Just Give All Instructions Directly to the AI? +## Trusting AI with Your Money? Three Reassurances -The key question for understanding Skills design: if we just tell the AI how to operate, why not just say it in the conversation? +The three questions you're most worried about — we've already thought of them: -This approach has two fundamental problems: +**"Will the AI secretly transfer my money?"** +No. Every operation that involves spending money will pause first and show you the full details — how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** Think of it as a diligent assistant who needs your signature on every expense report. -**Context window is limited and expensive.** If we stuff the complete content of all Skills into every conversation, the instructions alone would consume huge amounts of tokens, making the AI slower and dramatically increasing costs per conversation. +**"Will a ton of skills make the AI slow or confused?"** +No. When the AI starts up, it only loads a "table of contents" (like glancing at labels on a bookshelf). It only reads the full skill content when you actually use it. Hundreds of skills? Still lightning fast. -**Scattered attention.** When the AI faces detailed explanations for dozens of Skills, it struggles to focus on the current task and easily confuses rules and parameters across different skills, leading to errors. - -Skills solve this with **three-tier progressive loading** — only loading what's needed when it's needed. +**"Is my private key safe?"** +We recommend **Agent Wallet** — think of it as opening a dedicated "payment account" for your AI. You don't hand over your bank password (private key) directly. Instead, you give it an encrypted password. Even if someone peeks at your environment variables, they still need the encryption password to unlock anything — the odds of both locks being broken are extremely low. --- -## Three-Tier Progressive Loading - -Think of Skills as a library's retrieval system: - -**Tier 1: Shelf Index (ultra-lightweight)** +## What Can It Do for You? -When starting up, the system only exposes to the AI the `name` and `description` of all Skills — like labels on shelves. These "index cards" are tiny, so loading even hundreds of Skills at once creates no burden. Through this tier, the AI decides "which skill do I need for this task?" +Five core skills covering the most common scenarios in the TRON ecosystem. Each one comes with a ready-to-use sample prompt — copy it into your AI chat and hit enter to try it out. -**Tier 2: Operation Manual (loaded on demand)** +### 💱 Your Personal DEX Trader -Only when the AI confirms it needs a particular Skill does it read the complete `SKILL.md` content. This step triggers only when a skill is matched, providing the AI with specific execution steps, parameter requirements, edge conditions, and common error handling. +Check prices, compare rates, even swap tokens in one go. Like having a personal trader on call. -**Tier 3: Tool Execution (real-time invocation)** +> 🗣️ "How much TRX can I get for 100 USDT on SunSwap right now?" -Only when the task execution reaches a point requiring actual operations (like querying on-chain balance, executing a swap), the AI calls the corresponding script or MCP tool to do the substantive work, then returns the result to the conversation. +### 📈 Perpetual Contract Safety Officer -This design lets the system manage large numbers of Skills while maintaining low latency and high accuracy. - ---- +View market data, open and close positions on SunPerp. Built-in safety lock: max 20x leverage, mandatory stop-loss on every position — keeps you from blowing up your account. -## How Does the AI Find and Use a Skill? +> 🗣️ "What's BTC's funding rate right now? Open a 5x long position with a 5% stop-loss." -The AI selects and executes a Skill in four steps: +### 🕵️ On-Chain Data Detective -**Step 1: Intent Recognition** +Look up accounts, transactions, and check if a new token is legit. Pure read-only, completely safe, costs nothing. -You send a request (e.g., "Help me swap 100 USDT for TRX on SunSwap"), the AI parses the intent, scans the descriptions of all mounted Skills, and finds the best match. +> 🗣️ "Check the holder distribution for that new token — is it controlled by a whale?" -**Step 2: Rule Internalization** +### ☕ Auto-Pay Runner -The AI reads the Skill's `SKILL.md`, understanding the execution steps, parameter formats, network selection, and security constraints. +When the AI encounters a premium service (like a paid data API), it can automatically pay the small service fee for you — no need to switch apps or scan QR codes. -**Step 3: Tool Execution** +### 🏦 Account Manager -Following the manual's guidance, the AI proceeds step by step — calling scripts to check balance, get quotes, verify approvals, execute the swap — waiting for your confirmation at critical points. +Check your BANK OF AI balance and top up with a single sentence. -**Step 4: Result Feedback** - -After completion, the AI presents results in an easy-to-read format. When information is missing or execution fails, it asks proactively. +> 🗣️ "How much balance do I have? Go ahead and recharge 5 USDT." --- -## Two Ways to Invoke Skills - -You can trigger a Skill in two ways: +## Is This Right for Me? -**Explicit Invocation** — directly tell the AI which Skill to read, suitable for scenarios requiring deterministic behavior: +**I'm a total beginner:** Perfect! You no longer need to learn how to read candlestick charts, set slippage, or calculate gas fees. Just tell the AI what you want in plain language — it does the hard work and gives you the results in simple terms. -``` -Read the sunswap skill and help me check how much TRX I can get for 100 USDT on SunSwap. -``` +**I'm an experienced trader:** Tired of staring at screens all day? Let the AI monitor data, calculate yields, and execute routine operations. You focus on strategy, it handles execution. -**Implicit Triggering** — describe the task and let the AI auto-match, suitable for everyday conversation: +**I just want to explore:** Absolutely fine! The "On-Chain Data Detective" skill is 100% free and read-only. No wallet connection needed, zero risk, tinker all you want. -``` -Check how much TRX I can get for 100 USDT on SunSwap right now. -``` +--- -The difference lies in control: explicit invocation ensures the AI uses the Skill you specified; implicit triggering is more natural but if the description isn't clear enough, the AI might match the wrong Skill. When execution doesn't meet expectations, switching to explicit invocation usually solves the problem. +
---- +**Ready? Just 2 steps, less than 1 minute.** -## Next Steps + +Go to Quick Start + -- Want to know what Skills BANK OF AI provides? → [BANK OF AI Skills](./BANKOFAISkill.md) -- Have questions? → [FAQ](./Faq.md) +
diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md new file mode 100644 index 00000000..d57515e6 --- /dev/null +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -0,0 +1,151 @@ +# Quick Start + +Get your AI up and running with BANK OF AI Skills in **2 steps** and less than **1 minute**. No private keys, no configuration — just install and start talking. + +--- + +## Step 1: Install the Skills + +**If you are using OpenClaw (our top recommended AI client), just use the easiest, foolproof installation method below: Install via OpenClaw Extension** + +Open the "Terminal" on your computer (the black window where you type commands). + +:::tip Can't find Terminal? No worries +**Mac:** Press `Command + Space`, type `Terminal` in the search box, hit Enter. The black window appears. +**Windows:** Press `Win + R`, type `cmd` in the popup, hit Enter. +::: + +**Copy this entire line**, paste it into the black window, and press Enter: + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +``` + +A bunch of text will scroll across the screen — **you can ignore it**. Just wait for it to stop. The installer will ask you which components to install; follow the prompts and confirm. + +When it's done, verify by typing this into the terminal: + +```bash +ls ~/.openclaw/skills +``` + +If you see directory names like `sunswap`, `tronscan-skill`, etc. — congratulations, installation is complete! + +
+Not using OpenClaw? Click here for other installation methods + +**Claude Code:** + +```bash +git clone https://github.com/BofAI/skills.git /tmp/bofai-skills +mkdir -p ~/.config/claude-code/skills +cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ +``` + +**Cursor:** + +```bash +git clone https://github.com/BofAI/skills.git .cursor/skills +``` + +In Cursor Chat, use `@` to reference specific `SKILL.md` files. + +**Any AI tool (universal method):** + +```bash +git clone https://github.com/BofAI/skills.git ~/bofai-skills +``` + +Then tell the AI directly: `Please read ~/bofai-skills/sunswap/SKILL.md and check the current price of TRX for me.` + +
+ +--- + +## Step 2: Talk to Your AI + +Open your AI chat and copy-paste any of these: + +> Give me a TRON network overview: current TPS, number of Super Representatives, total accounts. + +In seconds, the AI calls the tronscan-skill and returns a complete on-chain data report. + +**This is completely safe — it's only "looking" at data. It doesn't touch your wallet or spend a single coin.** + +Try a few more: + +> How much TRX can I get for 100 USDT on SunSwap? + +> Show me the top 10 TRC20 tokens by market cap. + +> What's the current price, 24h change, and funding rate for BTC-USDT perpetual contract? + +If the AI responds with real data — congratulations, your AI is up and running! + +--- + +## 💰 Want the AI to Trade for You? + +Everything above is "look but don't touch" — the AI can look up data and compare prices, but it doesn't have permission to spend a single coin of yours. That's by design: you stay in full control. + +When you're ready to let the AI execute swaps, open positions, or manage liquidity, you need to give it a "wallet key." + +We've prepared two ways to hand over the key — pick whichever suits you: + +### Option 1: Open a Dedicated "Payment Account" for the AI (Strongly Recommended, Safest) + +We recommend using **Agent Wallet**. Think of it as opening a dedicated payment account for your AI. You don't expose your bank password (plaintext private key) in a file on your computer — instead, you set an encryption password. Every time it wants to spend money, it shows you the full bill first and only proceeds after you say "yes." + +👉 Head over to [Agent Wallet Quick Start](../../Agent-Wallet/QuickStart.md) to set it up (visual interface, about 2 minutes). + +### Option 2: Paste Your Private Key Directly (For Power Users or Quick Testing) + +If you don't want to install another tool and just want to start trading right away, you can paste your private key into a simple config file on your computer — like editing a notepad: + +**🍎 Mac Users:** + +1. In Terminal (the black window), type `open -e ~/.zshrc` and press Enter. +2. A text editor window will pop up. Scroll to the very bottom, start a new line, and paste your TRON private key: + ```bash + export TRON_PRIVATE_KEY="your_real_or_testnet_private_key" + ``` + ⚠️ Important: Don't forget the double quotes on both sides! +3. Press `Command + S` to save, then close the editor. + +**🪟 Windows (WSL) Users:** + +1. In the WSL terminal, type `notepad.exe ~/.bashrc` and press Enter. +2. At the very bottom of the notepad that opens, paste the same line: + ```bash + export TRON_PRIVATE_KEY="your_real_or_testnet_private_key" + ``` +3. Press `Ctrl + S` to save, then close the notepad. + +:::danger Critical Step +No matter which option you chose, you must **completely close and reopen your AI tool** for it to pick up the new key! +::: + +--- + +## 🎮 Key Is Set — How Do I Start Trading? + +Once you've configured your key and restarted your AI, you can start giving it trading commands right away! + +:::caution Golden Rule for Beginners: Practice with Play Money First +Before running any real transaction, **always test on the Nile testnet first**. Testnet tokens have zero real-world value — you can experiment freely without risking anything. +::: + +Open your AI chat and say your first trading command: + +> Swap 100 TRX for USDT on the Nile testnet. + +The AI will quickly calculate the price, estimate fees, then pause and ask: "Ready to execute?" Just reply "yes," and the on-chain transaction completes automatically! + +Once you've practiced on testnet and confirmed the AI behaves exactly as expected, simply drop the words "Nile testnet" from your commands — and it will trade with real funds on mainnet. + +--- + +## Next Steps + +- See what each skill can do → [Skill Catalog](./BANKOFAISkill.md) +- Something not working? → [FAQ](./Faq.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md index 6ce0f812..43aba1c6 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md @@ -1,11 +1,11 @@ # 简介 -BANK OF AI 通过 **MCP Server** 与 **Skills** 构建了一套完整的 AI Agent 能力体系：前者负责提供标准化的区块链交互能力，后者负责将这些能力组织为可执行的任务流程，从而支持 AI Agents 在链上环境中完成复杂操作。 +BANK OF AI 通过 **MCP Server** 与 **Skills** 构建了一套完整的 AI Agent 能力体系：前者是"锅碗瓢盆"——提供标准化的区块链交互工具；后者是"米其林菜谱"——将这些工具编排为可执行的任务流程，让 AI 在链上环境中像老手一样完成复杂操作。 -* **MCP Server** 旨在为大型语言模型 (LLM) 与外部工具和数据源之间的交互提供一个标准化的框架。其核心在于一个清晰定义的客户端-服务器架构和分层通信机制，确保了 AI 应用能够安全、高效地访问和利用外部信息。 -* **Skills** 是用于将多个工具按流程编排起来，帮助 AI 完成复杂任务的能力封装。 +* **MCP Server** 为大型语言模型 (LLM) 与外部工具和数据源之间的交互提供标准化框架。其核心是清晰定义的客户端-服务器架构和分层通信机制，确保 AI 应用能安全、高效地访问和利用外部信息。 +* **Skills** 是用于将多个工具按流程编排起来的"任务操作手册"，帮助 AI 完成复杂的多步骤任务——从 DEX 交易、永续合约到链上数据分析。 ## 快速导航 - **了解 MCP Server**：前往 [MCP Server 简介](./MCP/Intro.md)，了解协议架构与通信机制。 -- **了解 Skills**：前往 [Skills 简介](./SKILLS/Intro.md)，了解技能包的设计理念与使用方式。 +- **了解 Skills**：前往 [Skills 简介](./SKILLS/Intro.md)，了解技能包的设计理念、一键安装和使用方式。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 96dd9d33..7d4c8ae2 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,228 +1,191 @@ -# BANK OF AI Skills +# 技能大全 -BANK OF AI Skills 是一组为 AI 智能体设计的现成技能包，覆盖 TRON 生态的各种场景——DEX 交易、永续合约、链上数据查询、支付协议。每个技能封装了完整的业务工作流：从如何调用 API、按什么顺序执行步骤，到如何处理授权、怎样保护用户资产，全部内置在 `SKILL.md` 和配套脚本中。 +你不需要写代码，不需要懂技术。只要把下面的"参考话术"复制到 AI 对话框里，回车，AI 就会自动帮你干活。 -你无需编写代码，只需用自然语言告诉 AI 你想做什么，AI 会自动找到对应的技能并执行。 +:::warning 三条铁律 +BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤回"按钮，没有客服回滚。 -:::warning 使用任何 Skill 之前，请先阅读 -BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤销"按钮，没有客服回滚，转错地址的资金无法追回。使用前请牢记三条规则： - -1. **私钥永远不要出现在聊天窗口或配置文件中。** 只通过环境变量传递（如 `TRON_PRIVATE_KEY`）。私钥一旦泄露，请立即将资产转移到新钱包。 -2. **先测试网，后主网。** 每一个新操作都必须先在 Nile 或 Shasta 测试网上验证，再切换到主网执行。 -3. **写操作必须人工确认。** AI 在执行任何链上交易前，应向你展示完整的操作详情并等待你的明确确认。 +1. **永远不要把私钥粘贴到聊天窗口里。** 请使用 [Agent Wallet](../../Agent-Wallet/Intro.md)（相当于给 AI 开了一个专用"支付宝"，你不需要把银行卡密码直接给它）。 +2. **先用假钱练手。** 每个新操作都先在 Nile 测试网上试——测试网用的是免费"游戏币"，怎么折腾都不亏。 +3. **仔细看确认弹窗。** 任何花钱操作执行前，AI 都会把账单摊开给你看，你不点头它绝不动手。 ::: --- -## 可用技能一览 +## 技能一览表 -| Skill | 版本 | 功能概述 | 可选凭证 | -| :--- | :--- | :--- | :--- | -| **sunswap** | v2.0.0 | SunSwap DEX 交易——余额、报价、兑换、V2/V3 流动性 | `TRON_PRIVATE_KEY` | -| **sunperp-skill** | v1.0.0 | SunPerp 永续合约——行情、下单、仓位、提现 | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | -| **tronscan-skill** | v1.0.0 | TronScan 链上数据查询——账户、交易、代币、区块 | `TRONSCAN_API_KEY` | -| **x402-payment** | v1.4.0 | x402 协议支付——调用付费 API 和付费智能体 | `TRON_PRIVATE_KEY` 或 `EVM_PRIVATE_KEY` | -| **recharge-skill** | v1.1.1 | BANK OF AI 余额查询、订单记录、通过 MCP 充值 | `BANKOFAI_API_KEY` | +| 技能 | 能干什么 | 需要什么钥匙/密码？ | +| :--- | :--- | :--- | +| **sunswap** | 查价、报价、换币、管理流动性池 | 查询不需要；交易需要钱包凭证 | +| **sunperp-skill** | 看行情、开仓、平仓、提现 | 看行情不需要；交易需要 SunPerp 密钥 | +| **tronscan-skill** | 查账户、交易、代币、区块、全网数据 | 建议配置 TronScan API 密钥（不配可能卡顿） | +| **x402-payment** | 自动帮你支付收费 API 的"跑腿费" | 需要钱包凭证 | +| **recharge-skill** | 查余额、看订单、充值 | 需要 BANK OF AI 密钥 | ---- +### 🔑 这些"钥匙"去哪领？怎么配？ + +如果你只想让 AI 帮你查查公开数据（比如币价、区块高度），你可以什么都不配，直接去玩。 -## 安装 +但如果你想解锁高级功能或交易，请根据需要去领取对应的"钥匙"： -最简单的安装方式是使用 **OpenClaw Extension**——一键安装所有组件，自动配置技能目录，AI 开箱即用： +**1. 钱包凭证（用来花钱、交易的密码）** -```bash -# 方式一：直接运行（适合信任来源） -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +- **去哪领：** 你不需要去别的地方申请，这就是你的波场钱包私钥。 +- **怎么配：** 我们在[《快速开始》](./QuickStart.md#-想让-ai-帮你交易)里准备了两种方案任你挑： + - **方案一（推荐）：** 用 [Agent Wallet](../../Agent-Wallet/QuickStart.md)，可视化界面，两分钟搞定，私钥加密存储不外露。 + - **方案二：** 直接把私钥贴进系统配置文件（记事本大法），适合老手或快速测试。 -# 方式二：先检查脚本再运行（推荐） -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +**2. TronScan API 密钥（查数据的 VIP 通行证）** -安装完成后，技能会被放置到 `~/.openclaw/skills/` 目录，OpenClaw 自动发现并加载。 +不填这个也能查数据，但查快了容易被系统拉黑限速。填了就能走 VIP 高速通道。 -安装后验证技能是否就绪： +- **去哪领（完全免费）：** 去 [TronScan 官网](https://tronscan.org/) 注册个账号，点击生成即可。 +- **怎么配：** 请参考[《快速开始》里的"想让 AI 帮你交易？"](./QuickStart.md#-想让-ai-帮你交易)，用同样的记事本大法把 `TRONSCAN_API_KEY` 贴进去就行。 -```bash -ls ~/.openclaw/skills -``` +**3. SunPerp 密钥（专门用来玩永续合约）** -你应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 +- **去哪领：** 前往 [SunPerp 官网](https://sunperp.com/)，连接你的钱包后，在账户设置里生成 API Key 和 Secret。 +- **怎么配：** 同样使用记事本大法，把 `SUNPERP_ACCESS_KEY` 和 `SUNPERP_SECRET_KEY` 贴到系统配置文件里。 -### 其他平台安装 +**4. BANK OF AI 密钥（用来给账户充值或查余额）** -如果你使用 Claude Code、Cursor 或其他支持 Skills 的 AI 工具，也可以手动安装： +- **去哪领：** 前往 [chat.bankofai.io/key](https://chat.bankofai.io/key)，登录后即可获取。 +- **怎么配：** 使用记事本大法，贴入 `BANKOFAI_API_KEY`。 -**Claude Code：** +--- -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ -``` +## 还没安装？ -Claude Code 启动时会自动加载这些技能。 +去 **[快速开始](./QuickStart.md)** 花 1 分钟装一下，装完再回来挑你想用的技能。 -**Cursor：** +--- -```bash -# 克隆到项目根目录 -git clone https://github.com/BofAI/skills.git .cursor/skills -``` +## sunswap — 换币、查价、管理池子 -在 Cursor Chat 中，使用 `@` 符号引用特定 `SKILL.md` 文件提供上下文，或将技能路径添加到 `.cursorrules`。 +想在 SunSwap 上换币、查行情、管理流动性？对 AI 说下面的话就行。 -**通用方式（任何 AI 工具）：** +**绝对安全，只看不花钱：** -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` +> TRX 现在值多少钱？ -然后在对话中显式告诉 AI 读取某个技能文件： +> 100 USDT 在 SunSwap 上能换多少 TRX？ -``` -请阅读 ~/bofai-skills/sunswap/SKILL.md，帮我查询 TRX 当前价格。 -``` +> 帮我查看 SunSwap 上收益最高的 10 个池子。 ---- +> 帮我查看我当前所有的 SunSwap V3 流动性仓位。 -## 验证安装结果 +**需要你确认才会执行（AI 会先把账单给你看）：** -安装完成后，从只读操作开始是最好的起点——不需要私钥，零风险，适合熟悉技能的工作方式。 +> 在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 -在客户端输入： +> 在 SunSwap V2 的 TRX/USDT 池中添加 100 TRX 和 15 USDT 的流动性。 -``` -100 USDT 在 SunSwap 上能换多少 TRX？ -``` +> 帮我收取 V3 仓位 #12345 的手续费奖励。 -``` -帮我查一下 BTC-USDT 永续合约的当前行情。 -``` +**实战场景：** + +> 想搬砖？ "帮我算算 100 U 在 SunSwap 换成 TRX 划不划算？" + +> 想挖矿？ "SunSwap 上哪个 V3 池子年化收益最高？帮我分析一下。" + +> 想抄底？ "TRX 的价格现在处于什么位置？帮我查一下最近 7 天的走势。" --- -## 各技能使用示例 +## sunperp-skill — 永续合约交易 -每个示例标注了操作类型： -- 🟢 **只读** — 不产生链上交易，不需要私钥 -- ⚠️ **写操作** — 会发起链上交易，执行前需要用户确认 +想做合约？这个技能帮你看行情、开仓、平仓、设止损。内置安全锁：最高 20 倍杠杆，开仓必须设止损——默认帮你守住底线，亏损超过 5% AI 会自动帮你跑路，防止爆仓。 -### sunswap +**绝对安全，只看不花钱：** -``` -# 🟢 查询余额 -帮我查看我的 TRX 和 USDT 余额。 +> BTC-USDT 永续合约现在什么价格？24h 涨跌和资金费率呢？ -# 🟢 查询价格 -TRX 现在的价格是多少？ +> 我的 SunPerp 账户余额和可用保证金是多少？ -# 🟢 兑换报价 -100 USDT 在 SunSwap 上能兑换多少 TRX？ +> 我当前有哪些未平仓位？显示开仓均价、未实现盈亏和强平价。 -# ⚠️ 执行兑换 -在 SunSwap Nile 测试网上把 100 TRX 兑换成 USDT。 +**需要你确认才会执行：** -# ⚠️ 添加流动性 -在 SunSwap V2 的 TRX/USDT 池中添加 100 TRX 和 15 USDT 的流动性。 +> 以市价在 SunPerp 开 1 张 BTC-USDT 多单，10 倍杠杆，设置 5% 止损。 -# 🟢 查看 V3 仓位 -帮我查看我当前所有的 SunSwap V3 流动性仓位。 +> 平掉我所有的 BTC-USDT 仓位。 -# ⚠️ 收取手续费 -帮我收取 V3 仓位 #12345 的手续费奖励。 -``` +> 从 SunPerp 提现 10 USDT 到我的链上地址。 -### sunperp-skill +**实战场景：** -``` -# 🟢 查看行情 -BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ +> 被套牢了？ "帮我看看 BTC 现在的资金费率，建议做多还是做空？" -# 🟢 查看账户 -我的 SunPerp 账户余额和可用保证金是多少？ +> 想控制风险？ "帮我把 BTC-USDT 的杠杆降到 5 倍，止损调到 3%。" -# 🟢 查看持仓 -我当前有哪些未平仓位？显示开仓均价、未实现盈亏和强平价。 +> 想了解全局？ "帮我列出所有可交易的永续合约，按 24h 成交量排序。" -# ⚠️ 开仓 -以市价在 SunPerp 开 1 张 BTC-USDT 多单，10 倍杠杆，设置 5% 止损。 +--- -# ⚠️ 平仓 -平掉我所有的 BTC-USDT 仓位。 +## tronscan-skill — 链上数据侦探 -# ⚠️ 提现 -从 SunPerp 提现 10 USDT 到我的链上地址。 -``` +想查链上发生了什么？这个技能帮你查账户、交易、代币、区块和全网统计。**纯查询，绝对安全，不花一分钱，不需要任何密码。** 非常适合作为你的第一个技能来上手。 -### tronscan-skill +> 帮我查询地址 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf 的完整账户信息和持仓。 -``` -# 🟢 账户查询 -帮我查询地址 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf 的完整账户信息和持仓。 +> 查询这笔交易的详情：abc123... -# 🟢 交易查询 -查询这笔交易哈希的详情：abc123... +> 显示市值排名前 10 的 TRC20 代币。 -# 🟢 代币信息 -显示市值排名前 10 的 TRC20 代币。 +> 给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 -# 🟢 全网概览 -给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 +> 查询地址 TXX... 最近 20 笔 USDT 转账记录。 -# 🟢 转账记录 -查询地址 TXX... 最近 20 笔 USDT 转账记录。 -``` +**实战场景：** -### x402-payment +> 发现了一个新币，想看靠不靠谱？ "帮我查一下代币 TXX... 的持仓分布和合约验证状态。" -``` -# ⚠️ 调用付费端点 -使用 x402 协议调用这个付费智能体端点：https://api.example.com -``` +> 追踪鲸鱼动向？ "查一下地址 TXX... 最近 24 小时内超过 10 万 USDT 的所有交易。" -### recharge-skill +> 核实一笔转账？ "帮我查一下这笔交易到底成功了没有：abc123..." -``` -# 🟢 查询余额 -我的 BANK OF AI 账户还有多少余额？ +--- -# 🟢 查询订单 -显示我最近的 BANK OF AI 订单记录。 +## x402-payment — 自动打赏功能 -# ⚠️ 充值 -给 BANK OF AI 充值 1 USDT。 +有些高级 API 和 AI 智能体是收费的——需要你先付一小笔"跑腿费"才能使用。这个技能让 AI 帮你自动完成支付流程：AI 发现对方要收费，自动帮你付款，拿到结果后汇报给你。每次付款前同样会先问你确认。 -# ⚠️ 充值（英文） -Recharge 1 USDT to my BANK OF AI account. -``` +**需要你确认才会执行：** + +> 使用 x402 协议调用这个付费智能体端点：https://api.example.com （请替换为你实际要调用的付费端点地址） --- -## 推荐学习路径 +## recharge-skill — BANK OF AI 账户管理 + +查余额、看订单、给 BANK OF AI 账户充值。 + +**绝对安全，只看不花钱：** + +> 我的 BANK OF AI 账户还有多少余额？ -如果你刚开始使用 BANK OF AI Skills，按这个顺序来会更顺畅： +> 显示我最近的 BANK OF AI 订单记录。 -第一步：只读查询 - → 先用 tronscan-skill 查账户、看交易，熟悉技能的交互方式 - → 用 sunswap 查价格和报价，不执行真实交易 +**需要你确认才会执行：** + +> 给 BANK OF AI 充值 1 USDT。 + +--- + +## 推荐学习路径 -第二步：测试网写操作 - → 在 Nile 测试网执行 swap、添加流动性、开合约 - → 确认 AI 的行为符合预期，确认参数传递正确 +**从这里开始——零风险，零配置：** 用 tronscan-skill 查账户、看交易，用 sunswap 查价格和报价。纯查询，不花钱，不需要密码。 -第三步：主网小额操作 - → 用少量资金验证完整流程 +**接下来——用假钱练手：** 配置好钱包（见 [Agent Wallet 快速开始](../../Agent-Wallet/QuickStart.md)），然后在 Nile 测试网上试试换币和流动性操作。确认 AI 的表现完全符合预期。 -第四步：主网正式使用 - → 日常操作，根据需要调整参数和技能组合 +**然后——主网小额试水：** 用少量真实资金跑一遍完整流程，确保没有意外。 +**最后——放心使用：** 日常操作，根据需要调整参数和技能组合。 --- ## 下一步 -- 想深入了解 Skill 的工作原理？ → [Skills 是什么？](./Intro.md) -- 遇到问题？ → [常见问题](./Faq.md) -- 使用 OpenClaw Extension 安装？ → [OpenClaw Extension 文档](../../Openclaw-extension/Intro.md) +- 想了解技能背后的工作原理？ → [什么是 Skills？](./Intro.md) +- 遇到问题了？ → [常见问题](./Faq.md) +- 在用 OpenClaw Extension？ → [OpenClaw Extension 文档](../../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index 98ab0668..a261c90c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -1,204 +1,191 @@ -# 常见问题与排查 +# 常见问题 -以下问题按你最可能遇到的顺序排列。 +问题按你最可能遇到的顺序排列——出了问题的排最前面，概念解释放最后。 --- -## 基础概念 +## 出了问题怎么办 -### Skill 和 MCP Server 有什么区别？ +### AI 说"找不到技能"，或者回答牛头不对马嘴 -这是最常见的问题。一句话解释：**MCP Server 是工具箱，Skill 是操作手册。** +直接告诉 AI 去哪里读取技能文件： -MCP Server 提供原子级工具——比如"查余额"、"发起转账"、"调用合约"。Skill 则告诉 AI 如何把这些工具组合起来完成一个完整任务——比如"在 DEX 上兑换代币"需要依次执行查余额、获取报价、检查授权、执行兑换四个步骤，Skill 负责定义这个流程。 +``` +请阅读 ~/.openclaw/skills/sunswap/SKILL.md，帮我查一下 TRX 当前的价格。 +``` -### Skill 需要单独安装吗？ +如果这样能正常工作，说明之前只是 AI 自动匹配没命中。下次在指令里加个提示词就行，比如"使用 sunswap 技能"。 -不需要额外安装应用程序。Skill 就是一个文件夹——你只需把它放在 AI 工具能读取的目录里，AI 就能自动发现和使用它。 +如果这样也不管用，按顺序排查： -但如果技能包含 `scripts/` 目录（sunswap、sunperp-skill、tronscan-skill 都有），需要在该目录下运行一次 `npm install` 安装脚本依赖。使用 OpenClaw Extension 安装时这步是自动的。 +1. 技能目录存在吗？在终端（黑框框）运行 `ls ~/.openclaw/skills`，看看有没有对应的文件夹。 +2. 依赖装了吗？进到技能目录运行 `npm install`（比如 `cd ~/.openclaw/skills/tronscan-skill && npm install`）。 +3. 密码配了吗？参考下方 [怎么配置密码和密钥？](#怎么配置密码和密钥)。 -### Skills 支持哪些 AI 工具？ +### 安装失败了 -目前支持：**OpenClaw**（最完整的集成体验）、**Claude Code**、**Cursor**，以及任何支持读取本地文件的 AI 助手（通过显式调用方式）。 +安装技能需要你的电脑上装有一个叫"Node.js"的基础运行环境（类似 Java 运行环境）。如果安装报错，大概率是缺了它或版本太低。 ---- +**最简单的解决办法：** 去 [Node.js 官网](https://nodejs.org/) 下载最新的 LTS 版本（就像安装普通软件一样，一路点"下一步"），装完后重新试一次。 + +:::tip 已经装了 Node.js 但还是报错？ +在终端运行 `node --version` 查看版本号。技能需要 **v20 或更高版本**。如果版本太低，去官网重新下载最新版覆盖安装即可。 +::: -## 安装与配置 +### 怎么确认技能安装成功了？ -### 怎么知道技能安装成功了？ +在终端运行： ```bash ls ~/.openclaw/skills ``` -应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 +能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录名就说明装好了。 -然后在 OpenClaw 中验证： +然后在 AI 对话中验证： ``` -阅读 sunswap 技能，告诉我这个技能能做什么。 +读一下 sunswap 技能，告诉我它能做什么。 ``` -如果 AI 能准确描述技能内容，说明安装成功。 +AI 能准确描述功能 = 安装成功。 -### npm install 报错怎么办？ +--- -先确认 Node.js 版本： +## 我的钱安全吗 -```bash -node --version # 需要 >= 18 -``` +### AI 会偷偷把我的钱转走吗？ -如果版本过低，用 nvm 升级： +**不会。** 所有涉及花钱的操作，AI 都会先暂停，把完整的"账单"摊开给你看——要花多少、转到哪里、走哪条链、预估手续费是多少。**你不亲口说"好"，它绝不动手。** -```bash -nvm install 18 -nvm use 18 -``` +另外建议：用一个专门的钱包，只放你打算交易的资金。别把全部身家放进去——就像你不会带着所有积蓄去菜市场一样。 -然后重新在技能目录执行 `npm install`。 +### 私钥泄露了怎么办？ -### 凭证（私钥/API Key）怎么配置？ +**先别慌，看看你用的是什么网络：** -通过环境变量配置。根据你使用的技能，在 `~/.zshrc` 或 `~/.bashrc` 中添加对应变量： +如果你一直在用 **Nile 测试网**（我们强烈推荐新手这样做），那恭喜你——测试网里的"钱"是免费的游戏币，丢了就丢了，重新申请一个钱包就行，零损失。 -```bash -# TRON 钱包（sunswap、sun-mcp-server、x402-payment 需要） -export TRON_PRIVATE_KEY="你的私钥" -export TRONGRID_API_KEY="你的 TronGrid API Key" +如果是**主网**私钥泄露了，需要立即行动： -# SunPerp 合约交易（sunperp-skill 需要） -export SUNPERP_ACCESS_KEY="你的 SunPerp Access Key" -export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" - -# TronScan 数据查询（tronscan-skill 需要） -export TRONSCAN_API_KEY="你的 TronScan API Key" +1. 停止使用当前 AI 工具。 +2. 创建一个新钱包。 +3. 把旧钱包里的所有资产转到新钱包。 +4. 更新你的配置，指向新的密钥。 +5. 去各个协议（SunSwap、SunPerp 等）撤销旧钱包的授权。 -# BANK OF AI（recharge-skill 需要） -export BANKOFAI_API_KEY="你的 BANK OF AI API Key" -``` +:::tip 预防胜于补救 +从一开始就使用 [Agent Wallet](../../Agent-Wallet/Intro.md) 替代明文私钥。Agent Wallet 把你的密钥锁在本地加密保险箱里——就算有人偷看到你的环境变量，没有加密密码也打不开保险箱。两把锁同时被破的概率极低。 +::: -添加后执行 `source ~/.zshrc` 生效，然后重启 AI 工具。 +### 为什么每笔交易 AI 都要问我确认？ ---- +这是故意设计的安全机制。AI 每次要花你的钱之前，都会把所有细节列出来让你检查：要做什么操作、涉及哪些代币和金额、走哪条链、预估要花多少手续费。 -## 使用问题 +**这是你在真金白银动之前的最后一道安全门。别跳过它。** -### AI 说"找不到技能"或行为不符合预期怎么办？ +### 怎么切换测试网和主网？ -首先换成**显式调用**——直接告诉 AI 技能文件在哪里： +直接告诉 AI： ``` -请阅读 ~/.openclaw/skills/sunswap/SKILL.md，帮我查 TRX 当前价格。 +在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 ``` -如果显式调用正常，说明是隐式触发的匹配问题。可以在任务描述中加入更明确的关键词，比如"使用 sunswap 技能"、"通过 tronscan-skill"。 +AI 会自动切换到测试网操作。**强烈建议每次新操作都先在测试网跑一遍**——测试网用的是免费游戏币，怎么折腾都不亏。 -如果显式调用也不工作，检查技能目录是否存在、npm install 是否完成、环境变量是否正确设置。 +### 报价和实际成交价为什么有差异？ -### 如何在测试网和主网之间切换？ +因为区块链不会在你看报价的时候暂停。从看到报价到点确认执行，可能过了几秒到几十秒，这段时间内价格可能发生变化。 -通过 `--network` 参数指定。**强烈建议每次新操作都先在测试网验证**： +AI 的应对策略是：先给你看报价，你确认后在实际提交前会重新获取最新价格，并用"滑点保护"确保你不会拿到一个差得离谱的价格。 -```bash -# 测试网（默认，推荐先用这个） -node scripts/swap.js TRX USDT 100 --network nile +如果市场剧烈波动导致交易失败，可以适当放宽容忍度："帮我兑换 100 TRX 为 USDT，滑点设 1%。" -# 主网（确认一切正常后再用） -node scripts/swap.js TRX USDT 100 --network mainnet --execute -``` +--- -也可以在对话中直接告诉 AI： +## 配置相关 -``` -在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 -``` +### 怎么配置密码和密钥？ + +**最简单、最安全的方法（强烈推荐）：使用 [Agent Wallet](../../Agent-Wallet/QuickStart.md)。** 它就像一个带密码的保险箱，有简单的可视化界面，按提示填入密钥即可。设置一次，以后再也不用跟复杂的代码打交道。 + +
+极客/老手备用方法：通过环境变量配置 -### 为什么 AI 在执行前要让我确认？ +如果你熟悉命令行，可以将密码贴在系统的"隐形便签"（shell 配置文件）里。 -这是设计如此的安全机制——所有写操作（涉及链上交易的操作）都必须经过用户明确确认才能执行。 +**苹果电脑：** -AI 会在确认提示中展示：操作类型、涉及的代币和金额、目标网络、预估 Gas 和滑点。这是为了让你在资金真正动用之前，有机会核查操作是否符合预期。**不要跳过这个步骤，更不要开启自动执行写操作。** +1. 打开终端（按 `Command + 空格`，搜索 `Terminal`） +2. 输入 `nano ~/.zshrc`，按回车——你会看到一个简陋的文本编辑器 +3. 用方向键移到最下面，把下面需要的内容粘贴进去（注意：每行两边的英文双引号 `"` 千万别删掉，也别替换成中文引号） +4. 按 `Ctrl + X`，再按 `Y`，再按回车——保存完毕 +5. 关掉终端，重新打开，然后重启你的 AI 工具 -### dry-run（模拟执行）是什么意思？ +**Windows 电脑：** 不建议 Windows 新手折腾系统环境变量，请直接使用上面的 Agent Wallet 方法。如果你使用的是 WSL 环境，配置方式同苹果电脑（文件路径改为 `~/.bashrc`）。 -sunswap 等 Skill 的脚本支持不带 `--execute` 标志运行——这就是 dry-run 模式。它会模拟执行流程、检查余额和授权状态、获取报价，但不会广播任何链上交易。 +根据你需要的技能，把对应的内容粘贴进去： ```bash -# Dry-run：模拟检查，不执行 -node scripts/swap.js TRX USDT 100 +# SunSwap 换币（交易时需要） +export TRON_PRIVATE_KEY="你的私钥" +export TRONGRID_API_KEY="你的 TronGrid API Key" -# 真实执行 -node scripts/swap.js TRX USDT 100 --execute -``` +# SunPerp 永续合约 +export SUNPERP_ACCESS_KEY="你的 SunPerp Access Key" +export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" -遇到不确定的情况时，先跑 dry-run 是个好习惯。 +# TronScan 数据查询 +export TRONSCAN_API_KEY="你的 TronScan API Key" -### 为什么报价和实际成交有差异？ +# BANK OF AI 账户 +export BANKOFAI_API_KEY="你的 BANK OF AI API Key" +``` -因为从获取报价到实际执行之间有时间差，这段时间内价格可能发生变化。sunswap 的 `swap.js` 采用两步报价策略来处理这个问题：第一次报价展示给用户确认，用户确认后在实际提交交易前会重新获取最新报价，然后以最新报价计算的 `amountOutMin` 作为滑点保护。 +
-如果市场波动剧烈导致交易失败，适当增大滑点容忍度（`--slippage 1.0`）通常能解决。 +### 哪些 AI 工具能用这些技能？ ---- +目前支持：**OpenClaw**（最省心）、**Claude Code**、**Cursor**，以及任何能读取本地文件的 AI 助手。 -## 安全与进阶 +--- -### 我可以修改技能吗？ +## 自定义和管理 -可以。直接编辑 `SKILL.md` 或 `scripts/` 中的脚本，AI 下次调用时会读取最新版本。你可以修改操作步骤、添加自定义规则、调整安全参数，或者添加新的示例。 +### 我能修改技能的规则吗？ -修改 `sunperp-skill/resources/sunperp_config.json` 可以调整杠杆上限和止损默认值： +当然可以。技能就是你电脑上的普通文件夹，随便改。 -```json -{ - "safety": { - "max_leverage": 20, - "stop_loss": { - "required": true, - "default_percent": 5, - "max_percent": 25 - } - } -} -``` +比如你觉得 AI 做合约时 20 倍杠杆还是太高了，打开 `~/.openclaw/skills/sunperp-skill/resources/sunperp_config.json`，把数字改小就行——你的 AI，规矩由你定。 -### 技能的版本怎么管理？ +### 怎么卸载或更新？ -技能版本由 `SKILL.md` 的 YAML frontmatter 中的 `version` 字段标记。使用 OpenClaw Extension 时，可以通过 `GITHUB_BRANCH` 环境变量指定安装特定版本： +**卸载：** 删掉文件夹就行。 ```bash -GITHUB_BRANCH=v1.4.10 ./install.sh # 安装指定版本 -GITHUB_BRANCH=main ./install.sh # 使用最新主分支 +rm -rf ~/.openclaw/skills/sunswap ``` -默认使用 `v1.4.12` 标签版本。 +**更新：** 重新运行安装器，它会问你要不要覆盖旧版本。 -### 私钥泄露了怎么办？ +```bash +cd openclaw-extension +./install.sh +``` -**立即行动，不要犹豫：** +--- -1. 停止使用当前 AI 工具 -2. 创建一个新的 TRON/EVM 钱包地址 -3. 将所有资产转移到新地址（注意检查当前账户是否有待处理交易） -4. 更新所有环境变量，指向新的私钥 -5. 撤销旧钱包在所有协议上的代币授权 -6. 查看旧钱包的交易记录，确认是否已有未授权的操作 +## 概念解释（给好奇的你） -[Agent Wallet](../../Agent-Wallet/Intro)（加密存储）比明文私钥更安全——即使环境变量泄露，攻击者还需要额外的加密密钥才能访问资金。如果你管理较多资金，建议切换到 Agent Wallet 模式。 +### "技能"和"工具箱"到底什么关系？ -### 如何卸载或更新技能？ +一句话：**工具箱给 AI 干活的能力，技能教 AI 怎么干活。** -**卸载：** +工具箱（MCP Server）提供单个能力——比如"查余额"、"发转账"。技能（Skill）教 AI 怎么把这些能力串起来完成一个完整任务——比如"换币"需要先查余额、再看报价、确认价格、最后执行交易。技能定义了这个流程。 -```bash -rm -rf ~/.openclaw/skills/sunswap # 删除指定技能 -``` +打个比方：工具箱 = 菜刀、锅、灶台。技能 = 菜谱。 -**更新（重新安装最新版本）：** +### 装了一堆技能会不会变卡？ -```bash -cd openclaw-extension -./install.sh # 如果同名技能已存在，安装程序会询问是否覆盖 -``` +不会。AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个技能，照样飞快。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index 0b60ac1d..d0f0e0e0 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -1,143 +1,102 @@ -# Skills 是什么？ +# 简介 -你可能已经在用 MCP Server 让 AI 助手查余额、发转账、调用合约了。但你会发现，有些任务并不是"调一次工具就完事"——比如在 DEX 上兑换代币，需要先查余额、再获取报价、然后授权、最后执行兑换，每一步都有判断和参数要处理。 - -**Skills 就是为这类多步骤任务而生的。** - -一个 Skill 是一个"任务手册"——它不是工具，而是告诉 AI 怎样把一系列工具按正确的顺序、用正确的参数组合起来，完成一个完整的业务流程。 +欢迎来到 BANK OF AI Skills！简单来说，这是一套专为 TRON（波场）生态打造的**"AI 专属技能包"**。无论你是想查行情、做交易，还是追踪链上数据，现在都不用再打开一堆网页和 App 了——你只需要像聊天一样对 AI 发号施令，剩下的脏活累活，全交给它来搞定。 --- -## Skill 和 MCP Server 的区别 +## 你的 AI 为什么光说不练？ -很多人第一次接触 Skills 时会问：这和 MCP Server 有什么不一样？ +你可能已经用上了 AI 聊天工具，问它"帮我在 SunSwap 上把 100 USDT 换成 TRX"，它回你一堆操作步骤——然后就没有然后了。它只会嘴上说说，不会真正动手帮你操作。 -| | MCP Server | Skill | -| :--- | :--- | :--- | -| **本质** | 工具服务 | 任务手册 + 脚本集合 | -| **作用** | 提供 AI **做事的原子能力** | 教 AI **如何把能力组合起来完成一件事** | -| **例子** | `mcp-server-tron` 提供 `send_trx` 工具 | `sunswap` 告诉 AI 如何用多个工具完成一次 DEX 兑换 | -| **类比** | 厨房里的刀、锅、炉子 | 菜谱 | +为什么？ -简单说：**MCP Server 是工具箱，Skill 是操作手册。** Skill 告诉 AI 打开哪个抽屉、拿哪把工具、按什么步骤完成任务。 +因为以前的 AI 只是一个懂理论的"嘴强王者"。它知道怎么换币，但它没有手——不能查余额、不能发交易、不能帮你点确认。 --- -## 一个 Skill 长什么样？ +## 给 AI 配上"工具箱"和"操作手册" -Skill 是一个文件夹，结构非常简单： +现在不一样了。我们给 AI 配了两样东西： -| 文件/目录 | 作用 | 是否必须 | -| :--- | :--- | :--- | -| `SKILL.md` | 核心指令文档——AI 从这里学会如何执行任务 | **必须** | -| `scripts/` | 可执行脚本——AI 调用这些脚本完成具体操作 | 可选 | -| `resources/` | 参考数据——合约地址、代币列表、配置文件等 | 可选 | -| `package.json` | npm 依赖声明（有 scripts 的 Skill 需要先安装） | 可选 | +**工具箱（MCP Server）** — 让 AI 拥有查数据、发交易的实际能力（就像给它装上了手）。 -`SKILL.md` 的顶部是一段 YAML Frontmatter，声明技能的基本信息： +**操作手册（Skill）** — 告诉 AI 遇到具体任务时该怎么一步步操作（就像给它装上了干活的脑子）。 -```yaml ---- -name: SunSwap DEX Trading -description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. -version: 2.0.0 -dependencies: - - node >= 18.0.0 - - tronweb -tags: - - defi - - dex - - swap - - tron ---- - -# SunSwap DEX Trading Skill - -## 🚀 Quick Start -...（具体操作指令） -``` +| | 工具箱（MCP Server） | 操作手册（Skill） | +| :--- | :--- | :--- | +| **干什么的** | 给 AI 干活的能力 | 教 AI 怎么把能力组合起来完成任务 | +| **举个例子** | 提供"查余额"、"发转账"等单个能力 | 定义"换币"的完整流程：查余额 → 获取报价 → 确认价格 → 执行交易 | +| **打个比方** | 菜刀、锅、灶台 | 菜谱 | -`name` 和 `description` 是 AI 识别和匹配技能的关键字段——写得越准确，AI 越容易在合适的时机自动找到它。正文则是具体的操作指令，没有格式限制，可以是文字说明、代码示例、参数表格，或者任何有助于 AI 理解的内容。 +有了操作手册，你的 AI 就从"只会动嘴皮子的理论家"变成了"真正能帮你干活的交易员"。 --- -## 为什么不把所有指令直接给 AI？ +## 把钱交给 AI？先吃下这三颗定心丸 -理解 Skills 设计的关键问题：如果只是告诉 AI 怎么操作，直接在对话里说不就行了？ +把钱交给 AI 操作，你最担心的三个问题我们都想到了： -这样做有两个根本问题： +**"AI 会偷偷把我的钱转走吗？"** +不会。每次涉及花钱的操作，AI 都会先暂停，把所有细节摊开给你看（要花多少、转到哪里、走哪条链），**只有你亲口说"好"，它才会动手**。就像一个尽职的助理，每笔报销单都要你签字才能走流程。 -**上下文窗口有限且昂贵。** 如果把所有 Skill 的完整内容都塞进每次对话，光是这些指令就会占据大量 token，让 AI 反应变慢，也让每次对话的成本大幅增加。 +**"装了一堆技能，AI 会不会变卡、变笨？"** +不会。AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个技能，照样飞快。 -**注意力分散。** 当 AI 面对几十个 Skill 的详细说明时，它很难专注于当前任务，容易混淆不同技能的规则和参数，产生错误。 - -Skills 的解法是**三层渐进式加载**——只在需要的时候才加载需要的内容。 +**"我的密码安全吗？"** +我们推荐使用 **Agent Wallet** — 你可以把它理解成给 AI 专门开了一个"支付宝"。你不需要把银行卡密码（私钥）直接给它，而是给它一个支付密码。每次它要花钱，都得拿这个密码来找你核对。就算支付密码泄露了，对方还需要拿到你的电脑才能解锁——两把锁同时被破的概率极低。 --- -## 三层渐进式加载 - -把 Skills 想象成图书馆的检索系统： - -**第一层：书架索引（极轻量）** +## 目前能帮你干什么？ -AI 启动时，系统只向它暴露所有 Skill 的 `name` 和 `description`——就像书架上的标签。这些"索引卡片"非常小，即使同时加载几百个 Skill 也不会造成负担。AI 通过这一层决定"这次任务需要用到哪个技能"。 +五大核心技能，覆盖 TRON 生态最常用的场景。每个技能都配了一句"参考话术"——复制到 AI 对话框里回车就能体验。 -**第二层：操作手册（按需加载）** +### 💱 DEX 交易专属向导 -当 AI 确认需要某个 Skill，才去读取对应的 `SKILL.md` 完整内容。这一步只在匹配到技能时触发，为 AI 提供具体的执行步骤、参数要求、边界条件和常见错误处理。 +就像你的私人交易员。查价格、比报价、甚至一键换币。 -**第三层：工具执行（实时调用）** +> 🗣️ "帮我算算现在 100 USDT 在 SunSwap 上能换多少 TRX？" -当任务执行到需要具体操作的环节（比如查询链上余额、执行兑换交易），AI 才调用对应的脚本或 MCP 工具，完成实质性工作，然后把结果返回给对话。 +### 📈 永续合约安全员 -这种设计让系统在管理大量 Skill 的同时，保持低延迟和高准确性。 - ---- +在 SunPerp 看行情、开平仓。内置安全锁，最高只允许 20 倍杠杆，且开仓强制设止损——帮你管住手，防爆仓。 -## AI 如何找到并使用一个 Skill？ +> 🗣️ "现在 BTC 资金费率是多少？帮我开一张 5 倍杠杆的多单，亏损 5% 自动止损。" -AI 选择并执行一个 Skill 经历四个步骤： +### 🕵️ 链上数据侦探 -**步骤 1：意图识别** +查账户、查交易、查新币靠不靠谱。纯查询，绝对安全，不花一分钱。 -你发出一条请求（比如"帮我在 SunSwap 上把 100 USDT 兑换成 TRX"），AI 解析意图，扫描所有已挂载 Skill 的描述，找到最匹配的那个。 +> 🗣️ "帮我查一下昨天那个土狗币现在的持仓分布，有没有被庄家控盘？" -**步骤 2：规则内化** +### ☕ 自动打赏跑腿 -AI 读取该 Skill 的 `SKILL.md`，理解执行步骤、参数格式、网络选择、安全限制等具体规则。 +当 AI 遇到一些需要花钱的高级服务（比如付费数据接口）时，它能自动帮你付个几毛钱的跑腿费，不用你来回扫码支付。 -**步骤 3：工具执行** +### 🏦 账户大管家 -按照手册的指引，AI 逐步执行——调用脚本查余额、获取报价、检查授权、执行兑换——在关键节点等待你的确认。 +查看你的 BANK OF AI 余额，一句话完成充值。 -**步骤 4：结果反馈** - -任务完成后，AI 将结果整理成易读的格式汇报给你。遇到缺少信息或执行异常时，主动询问。 +> 🗣️ "帮我看看我的账户还有多少余额，顺便再充 5 个 U 进去。" --- -## 两种调用方式 - -你可以通过两种方式触发 Skill： +## 这套技能包适合我吗？ -**显式调用** — 直接告诉 AI 要读哪个 Skill，适合需要确定性行为的场景： +**我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么填滑点和 Gas 费了。直接用大白话跟 AI 提要求，它会把嚼碎的结果喂给你。 -``` -阅读 sunswap 技能，帮我查 100 USDT 在 SunSwap 上能兑换多少 TRX。 -``` +**我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下你大把的时间和精力。你可以专注于策略，把执行交给 AI。 -**隐式触发** — 描述任务，让 AI 自动匹配，适合日常对话： +**我只是想玩玩：** 完全没问题！"链上数据侦探"技能 100% 免费且只读，不用连钱包也能玩得很开心。零风险，随便折腾。 -``` -帮我查一下现在 100 USDT 在 SunSwap 能换多少 TRX。 -``` +--- -两种方式的区别在于控制权：显式调用确保 AI 使用你指定的 Skill；隐式触发更自然，但如果描述不够清晰，AI 可能匹配到错误的 Skill。遇到执行不符合预期时，换成显式调用通常能解决问题。 +
---- +**准备好了吗？只需 2 步，不到 1 分钟。** -## 下一步 + +前往快速开始 + -- 想了解 BANK OF AI 提供了哪些现成的 Skill？ → [BANK OF AI Skills](./BANKOFAISkill.md) -- 有疑问？ → [常见问题](./Faq.md) +
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md new file mode 100644 index 00000000..9aaa2727 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -0,0 +1,151 @@ +# 快速开始 + +只需 **2 步**，不到 **1 分钟**，你的 AI 就能开始帮你查链上数据、看行情报价。不需要密码，不需要配置任何东西——装完就能用。 + +--- + +## 第 1 步：安装技能库 + +**如果你正在使用 OpenClaw（我们最推荐的 AI 客户端），请直接使用下面这种最简单的傻瓜式安装：通过 OpenClaw Extension 安装** + +打开你电脑上的"终端"（就是那个黑框框）。 + +:::tip 找不到终端？别慌 +**苹果电脑：** 按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车，黑框框就出来了。 +**Windows 电脑：** 按 `Win + R`，在弹出的小窗口里输入 `cmd`，按回车。 +::: + +把下面这串长长的代码**整行复制**，粘贴到黑框框里，按回车： + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +``` + +屏幕上会跳出一堆英文字母——**不用管它们**，等它停下来就行。安装器会一步步问你要装哪些组件，跟着提示按回车确认即可。 + +装完后，黑框框里输入这行来验证： + +```bash +ls ~/.openclaw/skills +``` + +如果看到 `sunswap`、`tronscan-skill` 等目录名出现——恭喜，安装成功！ + +
+用的不是 OpenClaw？点这里看其他安装方式 + +**Claude Code：** + +```bash +git clone https://github.com/BofAI/skills.git /tmp/bofai-skills +mkdir -p ~/.config/claude-code/skills +cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ +``` + +**Cursor：** + +```bash +git clone https://github.com/BofAI/skills.git .cursor/skills +``` + +在 Cursor Chat 中用 `@` 引用具体的 `SKILL.md` 文件即可。 + +**任何 AI 工具（通用方式）：** + +```bash +git clone https://github.com/BofAI/skills.git ~/bofai-skills +``` + +然后在对话中直接告诉 AI：`请读取 ~/bofai-skills/sunswap/SKILL.md，帮我查一下 TRX 当前的价格。` + +
+ +--- + +## 第 2 步：对 AI 说出你的第一句话 + +打开你的 AI 对话框，把下面这句话复制进去，回车： + +> 给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 + +几秒后，AI 会自动调用 tronscan-skill，为你呈现一份完整的链上数据报告。 + +**这个操作绝对安全——它只是帮你"看"数据，不碰你的钱包，不花一分钱。** + +再试几句： + +> 100 USDT 在 SunSwap 上能换多少 TRX？ + +> 显示市值排名前 10 的 TRC20 代币。 + +> BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ + +如果 AI 返回了真实数据——恭喜，你的 AI 已经"开窍"了！ + +--- + +## 💰 想让 AI 帮你交易？ + +上面所有的操作都是"只看不动"的——AI 能帮你查数据、比价格，但它现在还没有权限动你的一分钱。这是故意的：控制权始终在你手里。 + +当你准备好让 AI 帮你换币、开仓、管理流动性时，你需要给它配一把"钱包钥匙"。 + +我们为你准备了两种给钥匙的方法，任选其一即可： + +### 方案一：给 AI 开个专用"支付宝"（强烈推荐，最安全） + +我们推荐使用 **Agent Wallet**。你可以把它理解成给 AI 开了一个专属的支付账户。你不需要把银行卡密码（明文私钥）直接暴露在电脑文件里，而是给它设置一个支付密码。每次花钱前，它都会把账单摊开给你看，你说"好"它才会操作。 + +👉 前往 [Agent Wallet 快速开始](../../Agent-Wallet/QuickStart.md) 设置（有可视化界面，大约 2 分钟搞定）。 + +### 方案二：直接把私钥贴给 AI（适合老手或快速测试） + +如果你嫌麻烦，不想装新工具，只想马上体验交易，你也可以像改普通记事本一样，直接把你的私钥贴在电脑的"隐形便签"里： + +**🍎 苹果电脑 (Mac) 用户：** + +1. 在终端（黑框框）输入 `open -e ~/.zshrc` 并按回车。 +2. 电脑会弹出一个记事本窗口。滑到最底下，新起一行，把你的波场私钥粘贴进去： + ```bash + export TRON_PRIVATE_KEY="你的真实或测试网私钥" + ``` + ⚠️ 注意：两边的英文双引号千万别漏掉！ +3. 按 `Command + S` 保存，关掉记事本。 + +**🪟 Windows 电脑 (WSL) 用户：** + +1. 在 WSL 终端输入 `notepad.exe ~/.bashrc` 并按回车。 +2. 在弹出的记事本最底下，粘贴同样的代码： + ```bash + export TRON_PRIVATE_KEY="你的真实或测试网私钥" + ``` +3. 按 `Ctrl + S` 保存，关掉记事本。 + +:::danger 极其重要的一步 +无论你用哪种方案配好了钥匙，都必须**彻底关闭并重新打开你的 AI 软件**，它才能拿到这把新钥匙！ +::: + +--- + +## 🎮 钥匙配好了，怎么让它去交易？ + +配好钥匙并重启 AI 后，你就可以直接对它下达交易指令了！ + +:::caution 新手铁律：先用假钱练手 +在执行任何真实交易之前，**务必先在 Nile 测试网上跑一遍**。测试网用的是没有真实价值的"游戏币"，怎么折腾都不会亏钱。 +::: + +打开对话框，对 AI 喊出你的第一句交易指令： + +> 在 Nile 测试网上，帮我把 100 TRX 兑换成 USDT。 + +此时，AI 会迅速帮你计算价格、预估手续费，然后停下来问你："确定要执行吗？" 你只需要回复"确定"，这笔链上交易就自动完成了！ + +等你在测试网上玩熟了，确认 AI 的表现完全符合预期，以后只要把指令里的"测试网"三个字去掉，它就会帮你操作主网的真金白银了。 + +--- + +## 下一步 + +- 看看每个技能都能帮你干什么 → [技能大全](./BANKOFAISkill.md) +- 遇到问题了？ → [常见问题](./Faq.md) diff --git a/sidebars.js b/sidebars.js index f1ea72cf..96a41ef4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -138,6 +138,7 @@ const sidebars = { collapsed: false, items: [ 'McpServer-Skills/SKILLS/Intro', + 'McpServer-Skills/SKILLS/QuickStart', 'McpServer-Skills/SKILLS/BANKOFAISkill', 'McpServer-Skills/SKILLS/Faq', ], From 5ecdb8c5acfa7fc8e738f458cb5911bbfe7c83ec Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 15:42:57 +0800 Subject: [PATCH 30/44] update agent wallet --- docs/Agent-Wallet/Developer/CLI-Reference.md | 4 +- docs/Agent-Wallet/Developer/SDK-Cookbook.md | 2 +- docs/Agent-Wallet/Developer/SDK-Guide.md | 16 ++--- docs/Agent-Wallet/FAQ.md | 2 +- docs/Agent-Wallet/Intro.md | 57 ++++++++++----- docs/Agent-Wallet/QuickStart.md | 32 +++------ .../Agent-Wallet/Developer/CLI-Reference.md | 4 +- .../Agent-Wallet/Developer/SDK-Cookbook.md | 2 +- .../Agent-Wallet/Developer/SDK-Guide.md | 12 ++-- .../current/Agent-Wallet/FAQ.md | 20 +++--- .../current/Agent-Wallet/Intro.md | 69 ++++++++++++------- .../current/Agent-Wallet/QuickStart.md | 38 ++++------ 12 files changed, 138 insertions(+), 120 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index db46e9c2..5cbd431a 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -201,7 +201,7 @@ When using `-p` to pass the password inline, the plaintext password is permanent ### Custom Storage Directory -All commands support the `--dir` flag to specify a custom encrypted safe storage path (default: `~/.agent-wallet`). For example, you can build your safe directly on an encrypted USB drive — plug and play, unplug and go: +All commands support the `--dir` flag to specify a custom Agent-wallet storage path (default: `~/.agent-wallet`). For example, you can store your Agent-wallet directly on an encrypted USB drive — plug and play, unplug and go: ```bash agent-wallet start --dir /Volumes/MyUSB/agent-wallet @@ -252,7 +252,7 @@ if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then exit 1 fi -echo "Calling local encrypted safe for signing..." +echo "Calling local Agent-wallet for signing..." # 2. Core operation: execute signing, capture the hash output into the SIGNATURE variable SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md index b15231f3..601753ef 100644 --- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md @@ -24,7 +24,7 @@ Before running any example below, make sure you have: 3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode — strongly recommended) :::danger Avoid static mode (`AGENT_WALLET_PRIVATE_KEY`) for real funds -Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local encrypted safe. +Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local Agent-wallet. ::: --- diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md index 92588604..2423e119 100644 --- a/docs/Agent-Wallet/Developer/SDK-Guide.md +++ b/docs/Agent-Wallet/Developer/SDK-Guide.md @@ -8,7 +8,7 @@ You've tried the CLI and can sign from the command line. Now you want signing in This page shows you how. By the end, you'll be able to initialize a wallet provider, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data — all in a few lines of TypeScript or Python. :::tip New here? -If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md) first (Steps 1–3 take under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. +If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md) first (takes under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice. ::: Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch. @@ -61,7 +61,7 @@ npm install @bankofai/agent-wallet **Check Your Python Version** -Requires Python ≥ 3.11 (the SDK uses `StrEnum` and other 3.11+ features). Check your current version: +Requires Python ≥ 3.11 (the SDK uses 3.11+ features): ```bash python3 --version @@ -143,7 +143,7 @@ Don't be intimidated by the concepts — `resolveWalletProvider()` is extremely It supports two modes: -### 🛡️ Core Usage: Local Vault Mode (Strongly Recommended) +### 🛡️ Core Usage: Local Agent-wallet Mode (Strongly Recommended) If you've already followed the [Quick Start](../QuickStart.md), your private key is already safely locked inside a hidden file on your machine. @@ -169,7 +169,7 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ### ⚠️ Fallback: Static Injection Mode (Test Environments Only) -If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local vault and feed the private key directly to the SDK. +If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local Agent-wallet and feed the private key directly to the SDK. ```bash export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex' @@ -178,19 +178,19 @@ export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' ``` :::danger Extremely Dangerous: Violates Core Security Principles! -Static mode reads your private key in plaintext, which means you forfeit Agent-wallet's encryption protection and fall back to the "single point of failure" approach described in the introduction. Only use this mode in fully isolated test environments or one-off CI/CD scripts! For mainnet operations with real funds, always use local vault mode. +Static mode reads your private key in plaintext, which means you forfeit Agent-wallet's encryption protection and fall back to the "single point of failure" approach described in the introduction. Only use this mode in fully isolated test environments or one-off CI/CD scripts! For mainnet operations with real funds, always use local Agent-wallet mode. ::: :::tip What if environment variables conflict? -If both a password and a private key exist in your environment variables, the SDK prioritizes security: it forces `AGENT_WALLET_PASSWORD` to enter local vault mode and ignores the plaintext private key. +If both a password and a private key exist in your environment variables, the SDK prioritizes security: it forces `AGENT_WALLET_PASSWORD` to enter local Agent-wallet mode and ignores the plaintext private key. ::: ### Environment Variable Reference | Variable | Purpose | Mode | Required | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | Master password, unlocks the local hidden file | 🛡️ Local Vault | Core required | -| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | 🛡️ Local Vault | Optional | +| `AGENT_WALLET_PASSWORD` | Master password, unlocks the local hidden file | 🛡️ Local Agent-wallet | Core required | +| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | 🛡️ Local Agent-wallet | Optional | | `AGENT_WALLET_PRIVATE_KEY` | Plaintext private key (hex) | ⚠️ Static Injection | Choose one (with mnemonic) | | `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | ⚠️ Static Injection | Choose one (with private key) | | `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 derivation index (default `0`) | ⚠️ Static Injection | Optional | diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index c71c8bf6..4b3f822b 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -136,7 +136,7 @@ Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), th ### What operating systems are supported? -macOS, Linux, and Windows (via WSL) are all supported. As long as you can run Node.js >= 18 or Python >= 3.11, you're good to go. +macOS and Linux. As long as you can run Node.js >= 18 or Python >= 3.11, you're good to go. Windows is not currently supported. ### `npm install -g` gives a permission error? diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 7385f22c..417a3a22 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -1,16 +1,16 @@ # Introduction -## Profit from AI Agents Without the Private Key Risk +## Enjoy the Convenience of AI Agents Without the Private Key Risk ### Your Private Key Is One File Read Away from Being Stolen You want your AI agent to handle on-chain work automatically — airdrop farming, token swaps, paying gas fees, scheduled transfers. To do any of that, the agent needs a "key" (your private key) to sign transactions on your behalf. -So you put your private key into your environment variables. +So you save your private key as plaintext in a configuration file on your computer — anyone who can read that file has your key. **That's like writing your bank card number and PIN on a sticky note and walking into a room full of strangers.** -That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read your environment variables. Your private key has no password protection, no encryption, no access control — it's just plaintext, one read away from being gone. +That room is your computer. Those strangers are everything else running on your machine — MCP servers, browser extensions, AI coding assistants, automation scripts. Every single one of them can read that file. Your private key has no password protection, no encryption, no access control — it's just plaintext, one app away from being gone. --- @@ -18,21 +18,19 @@ That room is your computer. Those strangers are everything else running on your - **Dependency chain poisoning.** You install a useful MCP server. Three months later, one of its 200 npm dependencies gets a malicious update — quietly scanning all files for anything that looks like a private key, then sending it out. You never see it happen. By the time you notice, your wallet is empty. -- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your environment variable file is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. +- **The "helpful" agent that leaks too much.** Your AI assistant reads your project directory to understand context. Your configuration file is in there. The assistant sends file contents to a remote API for analysis. Your private key is now sitting quietly in someone else's server logs — not stolen, just "accidentally" uploaded. - **Git's perfect memory.** You hardcoded a key during development and deleted it later. But you committed it once, three weeks ago. It's still in `git log -p`. If that repo ever touched GitHub, even for 30 seconds, automated scrapers already found it. -- **Cloud wallets: trading one exposure for another.** "Just use a cloud wallet service" — your key is off your machine, but now it's on someone else's server. Their breach is your breach. Their downtime is your agent's downtime. You've just moved the risk from one hand to the other. - -The common thread: **your private key is always exposed somewhere** — on disk, in logs, in git history, or on someone else's infrastructure. +The common thread: **your private key is always exposed somewhere** — on disk, in logs, or in git history. --- -## The Breakthrough: Agent-Wallet — The Web3 Wallet Designed Exclusively for AI +## The Breakthrough: Agent-wallet — The Web3 Wallet Designed Exclusively for AI -When you use a Web3 wallet like MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf. +When you use a Web3 wallet like TronLink/MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf. -**Agent-wallet is a local MetaMask purpose-built for AI agents.** +**Agent-wallet is a local TronLink/MetaMask purpose-built for AI agents.** It minimizes your risk through a **"physical + password separation"** dual-lock mechanism: @@ -53,7 +51,7 @@ If a hacker steals only your password through a malicious plugin, they can't do ## How It Compares -| | :x: Traditional (plaintext key in environment variables) | :white_check_mark: Agent-wallet Local Encrypted Safe | +| | :x: Traditional (plaintext key in configuration files) | :white_check_mark: Agent-wallet | | :--- | :--- | :--- | | **How it works** | :x: Hand your card and PIN directly to the AI | :white_check_mark: **Give AI the password, file stays locked locally** | | **Log / env variable leak** | :rotating_light: **Total loss** | :shield: **Only the password leaks — no file, hacker gets nothing** | @@ -66,23 +64,23 @@ If a hacker steals only your password through a malicious plugin, they can't do No need to understand everything first — get it running, then explore: -**Step 1 — Install:** +**Step 1 — Install Agent-wallet:** ```bash npm install -g @bankofai/agent-wallet ``` -**Step 2 — Create your encrypted safe:** +**Step 2 — Create your Agent-wallet wallet:** ```bash agent-wallet start ``` -The wizard will initialize your Agent-wallet encrypted safe and generate a **master password**. This is the only key to all your assets — if you lose it, there's no recovery. Save it in a password manager now. +The wizard will initialize your Agent-wallet wallet and generate a **master password**. This password is your only "unlock key": every time your AI agent needs to sign, it uses this password to unlock the wallet. **Save it immediately in a password manager (e.g. 1Password, Bitwarden)** — it won't be shown again, and if lost, there's no way to recover it or access your assets. **Step 3 — Your first signature:** ```bash agent-wallet sign msg "Hello from my AI agent" -n tron ``` -When a hash string appears on screen — congratulations, your encrypted safe is live. +When a hash string appears on screen — congratulations, your Agent-wallet is live. > Want the full step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. @@ -90,19 +88,40 @@ When a hash string appears on screen — congratulations, your encrypted safe is ## Next: Connect Your AI Agent -Your safe is set up and signing works. Now the question is: **how do I get my AI agent to actually use this wallet?** +Agent-wallet is set up and signing works. Now the question is: **how do I get my AI agent to actually use this wallet?** Pick the path that fits you: ### 🎮 I'm a casual user — using existing tools -No code required. We **strongly recommend our [OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. All you need to do is one thing — tell the tool your master password: +No code required. You can directly use our companion tools: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. + +#### 🤝 How do they work together? + +Think of your AI tools as a small company that manages your Web3 assets. The division of labor inside is crystal clear: + +- 🧠 **The Business Team (OpenClaw + Skills + MCP):** They do the legwork — checking market prices, calculating slippage, executing swaps. They're resourceful and capable, but here's the key: they have no direct access to your funds. +- 🏦 **The CFO (Agent Wallet):** The ultimate gatekeeper. Your private key (think: bank card PIN) is locked tight inside their local safe, invisible to any external tool. + +**Here's how the secure workflow plays out**: + +1. You give the AI agent an order: "Buy 100 USDT worth of TRX." +2. The Business Team springs into action — finds the best price and drafts a "transaction request form." +3. They hand the form to the internal **CFO (Agent Wallet)**. +4. The CFO verifies everything and never takes the private key out of the safe — instead, they stamp the form right there inside (this is what's technically called "signing"), then pass only the stamped form back out. +5. The Business Team takes the stamped form and submits the final transaction to the blockchain. + +✨ **The key takeaway:** Throughout the entire process, the AI tools that do the legwork only ever receive the "signature result" — never the key itself! This ensures your AI agent has powerful on-chain capabilities while keeping your assets secure. + +#### ⚙️ How do I connect them? + +Just one step — give the "Business Team" an internal passphrase to wake up the CFO. Tell the tools the master password you generated when creating your Agent Wallet: ```bash export AGENT_WALLET_PASSWORD='your-master-password' ``` -Once set, your tools automatically call your Agent-wallet encrypted safe to sign. Your private key stays encrypted throughout — the tool only ever receives the signature result, never the key itself. +Once this single passphrase is set, the entire system works seamlessly and automatically. The tools will call your Agent-wallet to sign on your behalf, transforming your AI agent into a top-tier Web3 personal assistant that's both brilliantly capable and secure! > Want the step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. @@ -138,7 +157,7 @@ Same key file, same data, same signature — across both languages. | Chain Type | Networks | | :--- | :--- | -| **EVM** | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain | +| **EVM** | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain (mainnet & testnet supported) | | **TRON** | TRON Mainnet, Nile Testnet, Shasta Testnet | Both chain types share the same interface — learn it once, use it everywhere. diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index fbb280bb..988d9dbd 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -3,7 +3,7 @@ import TabItem from '@theme/TabItem'; # Quick Start -Three steps, from zero to invoking your encrypted safe in the OpenClaw chat box. No coding required, no gas fees — just copy and paste. +Three steps, from zero to invoking your Agent-wallet in the OpenClaw chat box. No coding required, no gas fees — just copy and paste. :::tip Want CLI command details? This page only walks you through the shortest path. For password-free configuration, managing multiple wallets, signature types, and other advanced topics, see the [CLI Reference](./Developer/CLI-Reference.md). @@ -17,7 +17,7 @@ This page only walks you through the shortest path. For password-free configurat Agent-wallet requires Node.js (a runtime environment, version >= 18) on your computer. -Open a terminal (Mac users press `Command + Space` and search for "Terminal"; Windows users search for "cmd" or "PowerShell"), then type: +Open a terminal (Mac users press `Command + Space` and search for "Terminal"), then type: ```bash node -v @@ -55,14 +55,14 @@ agent-wallet --help If you see the help output, you're good to go. -### 1.3 Create Your Encrypted Safe +### 1.3 Create Your Agent-wallet Wallet Run: ```bash agent-wallet start ``` -The system will guide you through initializing your **Agent-wallet encrypted safe**. The process is interactive — just follow the prompts: +The system will guide you through initializing your **Agent-wallet wallet**. The process is interactive — just follow the prompts: ``` ? Quick start type: local_secure — Encrypted key stored locally (recommended) @@ -127,7 +127,7 @@ While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets reco ::: - + **Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password): @@ -147,16 +147,6 @@ export AGENT_WALLET_PASSWORD='your-master-password' source ~/.bashrc ``` -:::info Windows without WSL? -If you're on native Windows (no WSL), set the environment variable via PowerShell or System Properties: - -```powershell -# PowerShell — set permanently for your user -[Environment]::SetEnvironmentVariable("AGENT_WALLET_PASSWORD", "your-master-password", "User") -``` - -Or open **System Properties → Advanced → Environment Variables** and add `AGENT_WALLET_PASSWORD` manually. Restart your terminal after setting it. -::: @@ -187,9 +177,9 @@ Whether or not you currently have the OpenClaw backend service running, make sur --- -## Step 3: Wake Up Your Encrypted Safe in OpenClaw +## Step 3: Wake Up Your Agent-wallet in OpenClaw -Your safe is ready, the password is configured. Now open **OpenClaw** and test whether it can successfully invoke your local encrypted safe — just like chatting with a real person. +Your Agent-wallet is ready, the password is configured. Now open **OpenClaw** and test whether it can successfully invoke your local Agent-wallet — just like chatting with a real person. :::info Haven't installed OpenClaw Extension yet? Head to [OpenClaw Extension Quick Start](../Openclaw-extension/QuickStart.md) first, then come back here. @@ -201,7 +191,7 @@ Type in the chat box: > Show me the wallet address currently bound to my local wallet (TRON network). -The AI will automatically read your encrypted safe and report back the wallet address you just created. **This proves the password configuration is working correctly!** +The AI will automatically read your Agent-wallet and report back the wallet address you just created. **This proves the password configuration is working correctly!** ### Zero-Risk Test 2: Let AI Sign for You @@ -219,8 +209,8 @@ The AI will complete the signing locally and offline, returning a hash string. | I want to… | Go here | | :--- | :--- | -| Use CLI for advanced operations | [CLI Reference](./Developer/CLI-Reference.md) | -| Build my own agent with code | [SDK Guide](./Developer/SDK-Guide.md) | -| Find ready-made code examples | [SDK Cookbook](./Developer/SDK-Cookbook.md) | +| Prefer the command line? | [CLI Reference](./Developer/CLI-Reference.md) | +| Building your own agent? | [SDK Guide](./Developer/SDK-Guide.md) | +| Looking for ready-made code? | [SDK Cookbook](./Developer/SDK-Cookbook.md) | | Understand the security design | [Introduction](./Intro.md) | | Check common questions | [FAQ](./FAQ.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 9e571adf..75ce0900 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -201,7 +201,7 @@ agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' ### 自定义存储目录 -所有命令都支持 `--dir` 参数来指定加密保险箱的存储路径（默认在 `~/.agent-wallet`）。比如，你可以把保险箱直接建在加密 U 盘里，即插即用，拔下即走： +所有命令都支持 `--dir` 参数来指定 Agent-wallet 的存储路径（默认在 `~/.agent-wallet`）。比如，你可以把 Agent-wallet 直接建在加密 U 盘里，即插即用，拔下即走： ```bash agent-wallet start --dir /Volumes/MyUSB/agent-wallet @@ -254,7 +254,7 @@ if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then exit 1 fi -echo "正在调用本地保险箱签名..." +echo "正在调用本地 Agent-wallet 签名..." # 2. 核心操作：执行签名，并将终端打印出的哈希结果直接存入 SIGNATURE 变量 SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md index 90c4cacd..1283f208 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md @@ -24,7 +24,7 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页 3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式——强烈推荐） :::danger 真金白银操作请勿使用静态模式（`AGENT_WALLET_PRIVATE_KEY`） -静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地加密保险箱。 +静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地 Agent-wallet。 ::: --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md index bdb6f202..1b1ac48c 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md @@ -143,7 +143,7 @@ python3 -c "import agent_wallet; print('Installation successful')" 它支持以下两种模式： -### 🛡️ 核心用法：本地加密保险箱模式（强烈推荐） +### 🛡️ 核心用法：本地 Agent-wallet 模式（强烈推荐） 如果你刚才已经跟着 [快速上手](../QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。 @@ -169,7 +169,7 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" ### ⚠️ 备用方案：静态注入模式（仅限测试环境） -如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地加密保险箱，直接把私钥喂给 SDK。 +如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地 Agent-wallet，直接把私钥喂给 SDK。 ```bash export AGENT_WALLET_PRIVATE_KEY='你的私钥十六进制' @@ -178,19 +178,19 @@ export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...' ``` :::danger 极度危险：违背核心安全原则！ -静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地加密保险箱模式。 +静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地 Agent-wallet 模式。 ::: :::tip 环境变量冲突怎么办？ -如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地加密保险箱模式，忽略明文私钥。 +如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地 Agent-wallet 模式，忽略明文私钥。 ::: ### 环境变量速查 | 变量名 | 用途 | 模式 | 是否必填 | | :--- | :--- | :--- | :--- | -| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地加密保险箱 | 核心必填 | -| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地加密保险箱 | 可选 | +| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地 Agent-wallet | 核心必填 | +| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地 Agent-wallet | 可选 | | `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（十六进制） | ⚠️ 静态注入 | 二选一（与助记词） | | `AGENT_WALLET_MNEMONIC` | 明文助记词短语 | ⚠️ 静态注入 | 二选一（与私钥） | | `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 派生索引（默认 `0`） | ⚠️ 静态注入 | 可选 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index b87ecb9c..b6d20c14 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -4,14 +4,14 @@ --- -## 💰 AI 会不会把我的钱全转走？ +## 💰 AI 代理会不会把我的钱全转走？ -这是最常被问到的问题，答案是：**就算 AI 被入侵了，你的核心资产也是安全的。** +这是最常被问到的问题，答案是：**就算 AI 代理被入侵了，你的核心资产也是安全的。** -我们强烈建议你给 AI 单独创建一个钱包，只充入它实际需要的小额资金（比如当 Gas 费的额度）。你的主钱包、大额资产永远不碰。这样就算最坏情况发生，损失也只是那个小额钱包里的余额。 +我们强烈建议你给 AI 代理单独创建一个钱包，只充入它实际需要的小额资金（比如当 Gas 费的额度）。你的主钱包、大额资产永远不碰。这样就算最坏情况发生，损失也只是那个小额钱包里的余额。 ```bash -# 给 AI 单独建一个小额钱包 +# 给 AI 代理单独建一个小额钱包 agent-wallet add ``` @@ -19,7 +19,7 @@ agent-wallet add --- -## 🔌 断网了，AI 还能签名吗？ +## 🔌 断网了，AI 代理还能签名吗？ 能。**Agent-wallet 所有签名操作 100% 在你本地机器上完成。** @@ -58,7 +58,7 @@ agent-wallet add ### Agent-wallet 和 MetaMask 有什么区别？ -MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要你手动点"确认"。Agent-wallet 是给 AI 代理用的命令行钱包，专门设计为非交互式——AI 可以在后台静默调用签名，不需要人盯着屏幕点按钮。两者的加密原理类似（都是 Keystore V3），但使用场景完全不同。 +MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要你手动点"确认"。Agent-wallet 是给 AI 代理用的命令行钱包，专门设计为非交互式——AI 代理可以在后台静默调用签名，不需要人盯着屏幕点按钮。两者的加密原理类似（都是 Keystore V3），但使用场景完全不同。 ### 一台电脑上可以创建多少个钱包？ @@ -136,7 +136,7 @@ Agent-wallet 使用 Keystore V3 标准加密（scrypt + AES-128-CTR），这和 ### 支持哪些操作系统？ -macOS、Linux、Windows（通过 WSL）均可。只要能跑 Node.js >= 18 或 Python >= 3.11，就能用。 +macOS 和 Linux。只要能跑 Node.js >= 18 或 Python >= 3.11，就能用。目前不支持 Windows。 ### `npm install -g` 报权限错误怎么办？ @@ -152,13 +152,13 @@ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc ``` -### 配了密码但 AI 说"找不到钱包"或"密码错误"？ +### 配了密码但 AI 代理说"找不到钱包"或"密码错误"？ 最常见的三个原因： -1. **密码没生效**：你在终端 A 配了 `export`，但 AI 在终端 B 运行。解决：重启 AI 后台服务（参考 [快速开始](./QuickStart.md) 第二步）。 +1. **密码没生效**：你在终端 A 配了 `export`，但 AI 代理在终端 B 运行。解决：重启 AI 代理后台服务（参考 [快速开始](./QuickStart.md) 第二步）。 2. **密码被 shell 吃了**：双引号包裹的密码里有 `$` 或 `!`，被 shell 展开了。解决：改用单引号。 -3. **存储目录不对**：你之前用 `--dir` 指定了自定义路径，但 AI 在默认路径找。解决：`export AGENT_WALLET_DIR="/你的自定义路径"`。 +3. **存储目录不对**：你之前用 `--dir` 指定了自定义路径，但 AI 代理在默认路径找。解决：`export AGENT_WALLET_DIR="/你的自定义路径"`。 ### `agent-wallet` 命令找不到（command not found）？ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index 8b5b1df1..d15128c1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -1,15 +1,15 @@ # 简介 -## 享受 AI Agent 红利，告别私钥泄露焦虑 +## 享受 AI Agent 便利，告别私钥泄露焦虑 ### 你的私钥，距离被盗可能只差一次文件读取 -你想让 AI 代理帮你自动完成链上操作——刷空投、做兑换、付 Gas 费、定时转账。要做这些事，AI 需要一把"钥匙"（私钥）来替你签名。 +你想让 AI 代理帮你自动完成链上操作——刷空投、做兑换、付 Gas 费、定时转账。要做这些事，AI 代理需要一把"钥匙"（私钥）来替你签名。 -于是你把私钥放进了环境变量文件里。 +于是你把私钥以明文的方式保存在了电脑的一个配置文件里——谁能读到这个文件，谁就拿到了你的私钥。 **这就好比把银行卡和密码贴在脑门上，走进了一间挤满陌生人的办公室。** -那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读你的环境变量文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个进程拿走。 +那间办公室就是你的电脑。那些"陌生人"就是你机器上同时运行的一切——MCP Server、浏览器插件、AI 编程助手、自动化脚本。它们每一个，都能读到这个文件。你的私钥没有密码保护，没有加密，没有任何门槛——就是一段明文，随时可以被任何一个 APP 拿走。 --- @@ -17,28 +17,26 @@ - **依赖链投毒。** 你装了一个好用的 MCP Server。三个月后，它 200 个 npm 依赖中的某一个被注入了恶意代码——悄悄扫描所有文件，找到长得像私钥的字符串就发走。你完全不知道发生了什么，等你发现的时候，钱包已经空了。 -- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。环境变量在目录里。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 +- **"好心"代理的意外泄露。** AI 助手为了理解你的项目，读了整个工作目录。你的配置文件也在里面。助手把文件内容发给远端 API 做分析。你的私钥现在安静地躺在别人的服务器日志里——不是被偷的，是被"顺便"上传的。 - **Git 的"完美记忆"。** 你在开发时把私钥写进了代码，后来删了。但三周前你 commit 过一次。`git log -p` 里还有。仓库只要上过一次 GitHub，哪怕就 30 秒，自动化爬虫已经找到了。 -- **云钱包：换了个地方暴露。** "用云钱包服务不就安全了吗？" ——你的密钥确实不在本地了，但现在在别人的服务器上。他们被黑 = 你被黑，他们宕机 = 你的代理停摆。你只是把风险从左手换到了右手。 - -这些方式的共同点：**你的私钥总是在某个地方裸奔**——磁盘上、日志里、git 历史里、或者别人的基础设施上。 +这些方式的共同点：**你的私钥总是在某个地方裸奔**——磁盘上、日志里、git 历史里。 --- -## 破局之道：Agent-Wallet —— 专为 AI 打造的 Web3 钱包 +## 破局之道：Agent-wallet —— 专为 AI 代理打造的 Web3 钱包 -你平时用 Web3 钱包（比如 MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。 +你平时用 Web3 钱包（比如 TronLink/MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。 -**Agent-wallet 就是专为 AI 代理打造的本地 MetaMask。** +**Agent-wallet 就是专为 AI 代理打造的本地 TronLink/MetaMask。** 它通过**"物理与密码分离"**的双重机制，把你的风险降到了最低： 1. **第一重锁（物理文件）：** 你的私钥会被行业顶级的算法加密，锁死在电脑深处的隐藏文件夹里（`~/.agent-wallet`）。 -2. **第二重锁（授权密码）：** AI 只需要知道"开箱密码"（你可以配在环境变量里）就能干活。 +2. **第二重锁（授权密码）：** AI 代理只需要知道"开箱密码"（你可以配在环境变量里）就能干活。 -**你可能会问："如果 AI 把我的开箱密码也泄露了怎么办？"** +**你可能会问："如果 AI 代理把我的开箱密码也泄露了怎么办？"** 这就是 Agent-wallet 最精妙的地方：**密码泄露 ≠ 资产被盗。** @@ -52,9 +50,9 @@ ## 和"老办法"对比一下 -| | :x: 传统方式 (明文私钥放环境变量文件) | :white_check_mark: Agent-wallet 本地加密保险箱 | +| | :x: 传统方式（明文私钥放在配置文件里） | :white_check_mark: Agent-wallet | | :--- | :--- | :--- | -| **工作原理** | :x: 把银行卡和密码直接交给 AI | :white_check_mark: **给 AI 密码，文件锁在本地** | +| **工作原理** | :x: 把银行卡和密码直接交给 AI 代理 | :white_check_mark: **给 AI 代理密码，文件锁在本地** | | **遭遇日志/环境变量泄露** | :rotating_light: **直接倾家荡产** | :shield: **只丢了密码，没有文件，黑客偷不走钱** | | **遭遇加密文件被窃取** | :x: 明文私钥，直接被盗 | :shield: **没有密码，黑客打不开文件** | | **断网能签名吗** | :warning: 看情况 | :white_check_mark: **100% 离线签名** | @@ -65,43 +63,64 @@ 不需要先搞懂所有东西，先跑通再说： -**第一步 — 安装：** +**第一步 — 安装 Agent-wallet：** ```bash npm install -g @bankofai/agent-wallet ``` -**第二步 — 创建你的加密保险箱：** +**第二步 — 创建你的 Agent-wallet 钱包：** ```bash agent-wallet start ``` -系统会引导你初始化 Agent-wallet 加密保险箱，并生成一个**主密码**。这是解开所有资产的唯一凭证——忘了神仙难救，请用密码管理器保存。 +运行后，系统会引导你初始化 Agent-wallet 钱包，并生成一个**主密码**。这个密码是你唯一的"开箱钥匙"：每次 AI 代理需要签名时，都要用它来解锁钱包。**请立刻用密码管理器（如 1Password、Bitwarden）保存这个密码**——它不会再次显示，丢了就无法找回，资产也将无法操作。 **第三步 — 第一次签名：** ```bash agent-wallet sign msg "Hello from my AI agent" -n tron ``` -当屏幕上吐出一串哈希字符时——恭喜，你的加密保险箱配置成功了。 +当屏幕上吐出一串哈希字符时——恭喜，你的 Agent-wallet 配置成功了。 > 想看每一步的详细说明？去 **[快速开始](./QuickStart.md)**。 --- -## 接下来，让 AI 真正跑起来 +## 接下来，让 AI 代理真正跑起来 -保险箱建好了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** +Agent-wallet 建好了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？** 根据你的角色，走不同的路： ### 🎮 我是普通玩家——用现成的工具 -你不需要写代码。推荐使用我们的 **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。你只需要做一件事——把主密码告诉工具： +你不需要写代码。你可以直接使用我们配套的 **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。 + +#### 🤝 它们是怎么配合干活的？ + +如果你把你的 AI 工具看作是一家帮你管理 Web3 资产的"小公司"，那它们的内部分工是极其明确的： + +- 🧠 **业务团队（OpenClaw + Skills + MCP）：** 负责跑腿干活。它们脑子活、工具多，知道怎么查行情、怎么计算滑点、怎么去换币。但请注意：它们没有直接动用你资金的权限。 +- 🏦 **财务总监（Agent Wallet）：** 负责绝对的安全把关。你的私钥（银行卡密码）被死死锁在它的本地保险柜里，任何外部工具都看不见。 + +**完美的安全工作流是这样的**： + +1. 你对 AI 代理发号施令："帮我买 100 U 的 TRX"。 +2. 业务团队马上动起来，查好最优价格，并写好一张"交易申请单"。 +3. 它们把这张单子递给内部的 **财务总监（Agent Wallet）**。 +4. 财务总监核对无误后，绝不把私钥拿出保险柜，而是直接在内部盖个"同意印章"（也就是技术上说的签名），然后只把盖好章的单子递出去。 +5. 业务团队拿着盖好章的单子，去区块链上完成最终的交易。 + +✨ **核心亮点：** 整个过程中，跑腿的 AI 工具自始至终只拿到了"签名结果"，不是密钥本身！既保证了 AI 代理能拥有极其强大的链上操作能力，又保证了你的资产安全。 + +#### ⚙️ 我该怎么把它们连起来？ + +你只需要做一件事——给"业务团队"一把唤醒财务总监的内部口令。把你创建 Agent Wallet 时生成的主密码告诉工具： ```bash export AGENT_WALLET_PASSWORD='你的主密码' ``` -设置好后，工具就能自动调用你的 Agent-wallet 加密保险箱来签名了。你的私钥全程加密，工具拿到的只是签名结果，不是密钥本身。 +设置好这一个口令后，整个系统就能全自动无缝配合了。工具会自动调用你的 Agent-wallet 来签名，你的 AI 代理将彻底蜕变为一个既聪明能干，又绝对安全的 Web3 顶级私人管家！ > 跟着做一遍？去 **[快速开始](./QuickStart.md)**。 @@ -137,7 +156,7 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); | 链类型 | 网络 | | :--- | :--- | -| **EVM** | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链 | +| **EVM** | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链（主网和测试网均支持） | | **TRON** | TRON 主网、Nile 测试网、Shasta 测试网 | 两类链共用同一套接口——学一次，到处用。 @@ -148,7 +167,7 @@ const sig = await wallet.signMessage(new TextEncoder().encode("Hello!")); | 我在想… | 去这里 | | :--- | :--- | -| AI 会不会把我的钱全转走？ | [FAQ](./FAQ.md) — 我们有专门的风险隔离方案 | +| AI 代理会不会把我的钱全转走？ | [FAQ](./FAQ.md) — 我们有专门的风险隔离方案 | | 没写过代码？ | [快速开始](./QuickStart.md) | | 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) | | 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 7f85ef09..809936c4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -3,7 +3,7 @@ import TabItem from '@theme/TabItem'; # 快速开始 -三步，从零到在 OpenClaw 聊天框里唤醒你的加密保险箱。不用写代码，不花一分钱 Gas 费——复制粘贴就行。 +三步，从零到在 OpenClaw 聊天框里唤醒你的 Agent-wallet。不用写代码，不花一分钱 Gas 费——复制粘贴就行。 :::tip 想看 CLI 命令细节？ 本页只带你跑通最短路径。免密配置、管理多个钱包、签名类型等进阶内容，请看 [CLI 命令行手册](./Developer/CLI-Reference.md)。 @@ -17,7 +17,7 @@ import TabItem from '@theme/TabItem'; Agent-wallet 需要你的电脑里有 Node.js（这是一个运行环境，版本需 >= 18）。 -打开终端（Mac 用户按 `Command + 空格` 搜索"终端"；Windows 用户搜"cmd"或"PowerShell"），输入： +打开终端（Mac 用户按 `Command + 空格` 搜索"终端"），输入： ```bash node -v @@ -55,14 +55,14 @@ agent-wallet --help 看到帮助信息就说明安装好了。 -### 1.3 创建你的加密保险箱 +### 1.3 创建你的 Agent-wallet 钱包 运行： ```bash agent-wallet start ``` -系统会引导你初始化 **Agent-wallet 加密保险箱**。整个过程是交互式的——跟着提示走就行： +系统会引导你初始化 **Agent-wallet 钱包**。整个过程是交互式的——跟着提示走就行： ``` ? Quick start type: local_secure — Encrypted key stored locally (recommended) @@ -95,7 +95,7 @@ Active wallet: default --- -## 第二步：把密码"喂"给 AI（极其重要！） +## 第二步：把密码"喂"给 AI 代理（极其重要！） 为了让 OpenClaw 能自动使用你的钱包，你必须把密码配置到它的运行环境中。请根据你的电脑系统，选择对应的标签页，**无脑复制执行**即可。 @@ -127,7 +127,7 @@ source ~/.zshrc ::: - + **第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）： @@ -147,16 +147,6 @@ export AGENT_WALLET_PASSWORD='你的主密码' source ~/.bashrc ``` -:::info 没有 WSL 的 Windows 用户？ -如果你使用的是原生 Windows（未安装 WSL），可以通过 PowerShell 或系统属性设置环境变量： - -```powershell -# PowerShell — 为当前用户永久设置 -[Environment]::SetEnvironmentVariable("AGENT_WALLET_PASSWORD", "你的主密码", "User") -``` - -或者打开 **系统属性 → 高级 → 环境变量**，手动添加 `AGENT_WALLET_PASSWORD`。设置后请重启终端。 -::: @@ -177,9 +167,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" ``` ::: -### 2.2 重启你的 AI 后台服务 +### 2.2 重启你的 AI 代理后台服务 -:::danger 这一步很多人忘了，结果 AI 死活读不到密码！ +:::danger 这一步很多人忘了，结果 AI 代理死活读不到密码！ 因为你刚才新存了密码，而正在后台运行的 AI 助手还没刷新——它还是个"瞎子"！只有关掉它重新启动，它才能"看"到你的新密码。 ::: @@ -187,9 +177,9 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" --- -## 第三步：在 OpenClaw 里唤醒你的加密保险箱 +## 第三步：在 OpenClaw 里唤醒你的 Agent-wallet -保险箱建好了，密码也配好了。现在打开 **OpenClaw**，就像和真人聊天一样，测试一下它能不能成功调用你的本地加密保险箱。 +Agent-wallet 建好了，密码也配好了。现在打开 **OpenClaw**，就像和真人聊天一样，测试一下它能不能成功调用你的本地 Agent-wallet。 :::info 还没装 OpenClaw Extension？ 先去 [OpenClaw Extension 快速开始](../Openclaw-extension/QuickStart.md) 安装好，再回来继续。 @@ -201,17 +191,17 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" > 帮我查一下我当前绑定的本地钱包地址（TRON 网络）。 -AI 会自动读取你的加密保险箱，并准确报出你刚才创建的钱包地址。**这证明密码配置完全正确！** +AI 代理会自动读取你的 Agent-wallet，并准确报出你刚才创建的钱包地址。**这证明密码配置完全正确！** -### 零风险测试 2：让 AI 替你签名 +### 零风险测试 2：让 AI 代理替你签名 接着对它说： > 用我的钱包签名这段话："Hello Agent-wallet!" -AI 会在本地离线完成签名，并返回一串哈希字符。 +AI 代理会在本地离线完成签名，并返回一串哈希字符。 -**恭喜！** 全程没花一分钱 Gas 费，你也完全没接触私钥，但你已经成功让 AI 拥有了安全的密码学签名能力。 +**恭喜！** 全程没花一分钱 Gas 费，你也完全没接触私钥，但你已经成功让 AI 代理拥有了安全的密码学签名能力。 --- From 11c00b5819572ceaa52a51bf02ac0d7b54f6c04a Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 16:46:47 +0800 Subject: [PATCH 31/44] update skills --- docs/Agent-Wallet/Intro.md | 32 ++++++----- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 2 +- docs/McpServer-Skills/SKILLS/Intro.md | 56 +++++++++++-------- docs/McpServer-Skills/SKILLS/QuickStart.md | 2 +- .../current/Agent-Wallet/Intro.md | 32 ++++++----- .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 2 +- .../current/McpServer-Skills/SKILLS/Intro.md | 55 ++++++++++-------- 7 files changed, 104 insertions(+), 77 deletions(-) diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md index 417a3a22..691c6abb 100644 --- a/docs/Agent-Wallet/Intro.md +++ b/docs/Agent-Wallet/Intro.md @@ -94,36 +94,38 @@ Pick the path that fits you: ### 🎮 I'm a casual user — using existing tools -No code required. You can directly use our companion tools: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. +You don't need to know any code! You can directly use our ready-made "all-in-one" suite: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. #### 🤝 How do they work together? -Think of your AI tools as a small company that manages your Web3 assets. The division of labor inside is crystal clear: +To give you total peace of mind, we designed your AI assistant as a well-organized little "company" with clear division of labor: -- 🧠 **The Business Team (OpenClaw + Skills + MCP):** They do the legwork — checking market prices, calculating slippage, executing swaps. They're resourceful and capable, but here's the key: they have no direct access to your funds. -- 🏦 **The CFO (Agent Wallet):** The ultimate gatekeeper. Your private key (think: bank card PIN) is locked tight inside their local safe, invisible to any external tool. +- 🧠 **The Business Team (OpenClaw + Skills + MCP):** They do the legwork out in the field — quick-thinking and well-equipped, they know how to check prices, calculate slippage, and find the best quotes. But most importantly: they have zero authority to touch your funds. +- 🏦 **The CFO (Agent Wallet):** The one guarding the vault. Your private key (think: bank card PIN) is locked tight inside their local safe, completely invisible to the Business Team outside. -**Here's how the secure workflow plays out**: +Here's how a perfect secure pipeline works: -1. You give the AI agent an order: "Buy 100 USDT worth of TRX." -2. The Business Team springs into action — finds the best price and drafts a "transaction request form." -3. They hand the form to the internal **CFO (Agent Wallet)**. -4. The CFO verifies everything and never takes the private key out of the safe — instead, they stamp the form right there inside (this is what's technically called "signing"), then pass only the stamped form back out. -5. The Business Team takes the stamped form and submits the final transaction to the blockchain. +1. You sit back in the boss's chair and say: "Buy 100 USDT worth of TRX." +2. The Business Team rushes off to check prices, calculate fees, and dutifully drafts a "transaction request form." +3. They hand the form to the **CFO (Agent Wallet)**, who sits right next to the safe. +4. The CFO verifies everything and never takes the private key out of the safe — instead, they stamp the form right there with an "approved" seal (technically called "signing"), then pass only the stamped form back out. +5. The Business Team takes the stamped form and gets it done on the blockchain. -✨ **The key takeaway:** Throughout the entire process, the AI tools that do the legwork only ever receive the "signature result" — never the key itself! This ensures your AI agent has powerful on-chain capabilities while keeping your assets secure. +✨ **The key takeaway:** Throughout the entire process, the AI tools doing the legwork only ever receive the "stamped paper" — they never even catch a glimpse of the private key! This ensures AI agent can handle extremely complex tasks for you while keeping your assets absolutely secure. -#### ⚙️ How do I connect them? +#### ⚙️ Sounds great — how do I connect them? -Just one step — give the "Business Team" an internal passphrase to wake up the CFO. Tell the tools the master password you generated when creating your Agent Wallet: +Dead simple! No complex programming needed — just one thing: give the Business Team an internal passphrase to wake up the CFO. + +Just tell the tools the "master password" you generated when creating your Agent Wallet, like this: ```bash export AGENT_WALLET_PASSWORD='your-master-password' ``` -Once this single passphrase is set, the entire system works seamlessly and automatically. The tools will call your Agent-wallet to sign on your behalf, transforming your AI agent into a top-tier Web3 personal assistant that's both brilliantly capable and secure! +That's it — one line of config! Once the passphrase is set, the entire system works seamlessly and automatically. Your AI agent will transform into a top-tier Web3 personal assistant that's both brilliantly capable and absolutely secure! -> Want the step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**. +> Can't wait to try it? Head to 👉 **[Quick Start](./QuickStart.md)** and follow along. ### ⌨️ I'm an advanced user — managing wallets via CLI diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 1eca2864..a6c0b7b4 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -3,7 +3,7 @@ You don't need to write code or understand the technical details. Just copy the sample prompts below into your AI chat, hit enter, and the AI takes care of the rest. :::warning Three Golden Rules -BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactions are **irreversible** — there's no undo button, no customer service rollback. +BANK OF AI SKILLS can operate on **real on-chain assets**. Blockchain transactions are **irreversible** — there's no undo button, no customer service rollback. 1. **Never paste your private key into a chat window.** Use [Agent Wallet](../../Agent-Wallet/Intro.md) instead (think of it as opening a dedicated "payment account" for your AI — you don't hand over your bank password directly). 2. **Practice with play money first.** Every new operation should be tested on the Nile testnet — it uses free test tokens, so there's nothing to lose. diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 4a9fcc0a..5e5faaa4 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -1,34 +1,48 @@ # Introduction -Welcome to BANK OF AI Skills! In a nutshell, this is a set of **"AI skill packs"** built specifically for the TRON ecosystem. Whether you want to check market prices, execute trades, or track on-chain data, you no longer need to juggle a dozen websites and apps — just tell your AI what to do in plain language, and it handles the heavy lifting. +Welcome to BANK OF AI SKILLS! + +In the past, exploring Web3 was a grind full of barriers: watching charts, calculating slippage, switching wallets, checking contracts... one wrong step and you'd hit an error. We decided to put an end to that hassle. + +In a nutshell, BANK OF AI SKILLS is a set of **"AI skill packs"** purpose-built for the TRON ecosystem. It upgrades traditional "manual operations" into an **intent-driven, conversational experience**. Just talk to the AI like you would a personal trader, and it handles all the dirty work, heavy lifting, and technical details for you. --- -## Why Does Your AI Only Talk the Talk? +## 🌟 Why a "Toolbox" Alone Isn't Enough — You Need Skills -You might already be using an AI chat tool. You ask it "help me swap 100 USDT for TRX on SunSwap," and it gives you a nice list of steps — then does absolutely nothing. It can tell you how to trade, but it can't actually do it for you. +Some AI products on the market claim they can trade, but they typically just plug the AI into raw tool interfaces (i.e., MCP). If you've tried them, you'll know the result: give AI nothing but tools and it becomes a "kitchen maniac swinging a knife with no recipe." -Why? +In the high-stakes reality of Web3 trading, an AI needs more than "the ability to call tools" — it must "understand the business workflow." The core edge of BANK OF AI SKILLS is that we upgraded a bare toolbox into a **standardized pipeline with built-in error prevention and risk control guardrails**. -Because until now, your AI was an "armchair expert" — lots of theory, no hands. It knows what a swap is, but it can't check your balance, submit a transaction, or click confirm. +With Skills, your AI gains three decisive advantages: ---- +| Real Trading Pain Point | 🛠️ Basic Toolbox Only (raw MCP) | 🦸‍♂️ With BANK OF AI SKILLS (full skill pack) | +| :--- | :--- | :--- | +| **Complex trade execution** (error prevention & SOP) | Gets lost easily, errors everywhere. For example, it might try to swap tokens without even approving the contract first — instant failure. | Built-in "veteran driver navigation." Enforces the perfect sequence: check balance → verify approval → get quote → confirm → execute. Never misses a step. | +| **Fund safety & risk control** (blow-up prevention) | Blindly obedient, no guardrails. It just executes — if you casually say "open 100x leverage," it actually does it. | Built-in "business-level safety locks." Hard-coded risk limits (e.g., max 20x leverage, mandatory stop-loss), dangerous commands get blocked on the spot. | +| **Daily communication barrier** (understands plain language) | Tedious, like filling out forms. You need to precisely input contract addresses, slippage percentages, and other complex parameters — one typo and it all falls apart. | Powerful "intent translation." Just say "swap all my USDT for TRX" and it looks up addresses, calculates slippage, and fetches quotes on its own — never bothers you. | -## Give Your AI a Toolbox and a Playbook +**In one sentence:** A regular AI toolbox just hands you a wrench — you still have to figure out how to turn it. BANK OF AI SKILLS is like having a Michelin chef who comes with the recipe book, never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. -Now things are different. We gave the AI two things: +### 🎬 Real Scenario: You Want to "Buy Some TRX with 50 USDT" -**A toolbox (MCP Server)** — the actual ability to look up data and send transactions (like giving it hands). +Let's say you give the AI the simplest possible command: "Buy some TRX with 50 USDT." -**A playbook (Skill)** — step-by-step instructions for how to complete specific tasks (like giving it a brain for getting work done). +**❌ With a regular AI toolbox (raw MCP):** -| | Toolbox (MCP Server) | Playbook (Skill) | -| :--- | :--- | :--- | -| **What it does** | Gives the AI individual abilities | Teaches the AI how to combine abilities into complete workflows | -| **Example** | Provides "check balance" and "send transfer" as individual tools | Defines the full swap flow: check balance → get quote → confirm price → execute trade | -| **Analogy** | Knives, pots, and a stove | The recipe | +It hears the command, grabs the "trade tool," and goes straight to the blockchain to execute the purchase. Result: **BOOM — transaction failed.** The AI throws a wall of incomprehensible error code at you (something like `transfer amount exceeds allowance`). + +Why? Because in the Web3 world, you must **"Approve"** a token before spending it. A regular AI has the tools but zero domain knowledge — it skips the prerequisite step, crashes, and leaves you staring at a screen full of gibberish. -With a playbook, your AI goes from "an armchair expert who only talks" to "a hands-on trader who actually gets things done." +**✅ With BANK OF AI SKILLS installed:** + +After receiving your command, it doesn't just execute — it automatically runs through a standard operating procedure behind the scenes. Here's what your experience looks like: + +1. **Auto balance check:** "Boss, I checked — you have 100 USDT in your wallet. Plenty of funds." +2. **Preemptive troubleshooting:** "I noticed you haven't approved USDT for SunSwap yet. I've prepared the Approve request — please confirm." +3. **Precise quote:** "Approval successful! At the latest price, 50 USDT gets you roughly 350 TRX. I've automatically set 1% slippage protection. Ready to buy?" + +In this scenario, you said one sentence, and the Skill quietly handled 5 high-barrier steps behind the scenes: check balance → detect missing approval → submit approval → calculate slippage → fetch quote. That's the difference between a bare tool and a "pro butler with a brain." --- @@ -81,13 +95,11 @@ Check your BANK OF AI balance and top up with a single sentence. --- -## Is This Right for Me? - -**I'm a total beginner:** Perfect! You no longer need to learn how to read candlestick charts, set slippage, or calculate gas fees. Just tell the AI what you want in plain language — it does the hard work and gives you the results in simple terms. - -**I'm an experienced trader:** Tired of staring at screens all day? Let the AI monitor data, calculate yields, and execute routine operations. You focus on strategy, it handles execution. +## 🎯 Is This Right for Me? -**I just want to explore:** Absolutely fine! The "On-Chain Data Detective" skill is 100% free and read-only. No wallet connection needed, zero risk, tinker all you want. +- **👶 I'm a total beginner:** Perfect! No more wrestling with candlestick charts, slippage settings, or gas fee calculations. Just tell the AI what you want in plain language — it does the hard work and feeds you the results. +- **🕴️ I'm an experienced trader:** Tired of staring at screens all day? Let the AI batch-monitor data and calculate yields, freeing up your time and energy. You focus on strategy — let the AI handle the tedious execution. +- **🍉 I just want to explore:** Absolutely fine! Read-only skills like "On-Chain Data Detective" are 100% free — no wallet needed, zero risk, full access to the Web3 magic. --- diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index d57515e6..2690c74a 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -1,6 +1,6 @@ # Quick Start -Get your AI up and running with BANK OF AI Skills in **2 steps** and less than **1 minute**. No private keys, no configuration — just install and start talking. +Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than **1 minute**. No private keys, no configuration — just install and start talking. --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md index d15128c1..9dffa6e2 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md @@ -93,36 +93,38 @@ Agent-wallet 建好了。现在的问题是：**怎么让我的 AI 代理用上 ### 🎮 我是普通玩家——用现成的工具 -你不需要写代码。你可以直接使用我们配套的 **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。 +你完全不需要懂代码！你可以直接使用我们配套好的"全家桶"：**[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。 #### 🤝 它们是怎么配合干活的？ -如果你把你的 AI 工具看作是一家帮你管理 Web3 资产的"小公司"，那它们的内部分工是极其明确的： +为了让你用得绝对放心，我们把你的 AI 助理设计成了一家分工明确的"小公司"： -- 🧠 **业务团队（OpenClaw + Skills + MCP）：** 负责跑腿干活。它们脑子活、工具多，知道怎么查行情、怎么计算滑点、怎么去换币。但请注意：它们没有直接动用你资金的权限。 -- 🏦 **财务总监（Agent Wallet）：** 负责绝对的安全把关。你的私钥（银行卡密码）被死死锁在它的本地保险柜里，任何外部工具都看不见。 +- 🧠 **业务团队（OpenClaw + Skills + MCP）：** 负责在外头跑腿。它们脑子转得快、工具多，知道怎么查行情、算滑点、找最优报价。但最重要的是：它们没有任何动用你资金的权限。 +- 🏦 **财务总监（Agent Wallet）：** 负责死守钱袋子。你的私钥（银行卡密码）被死死锁在它的本地保险柜里，外面的业务团队根本看不见。 -**完美的安全工作流是这样的**： +一条完美的安全流水线是这样的： -1. 你对 AI 代理发号施令："帮我买 100 U 的 TRX"。 -2. 业务团队马上动起来，查好最优价格，并写好一张"交易申请单"。 -3. 它们把这张单子递给内部的 **财务总监（Agent Wallet）**。 -4. 财务总监核对无误后，绝不把私钥拿出保险柜，而是直接在内部盖个"同意印章"（也就是技术上说的签名），然后只把盖好章的单子递出去。 -5. 业务团队拿着盖好章的单子，去区块链上完成最终的交易。 +1. 你坐在老板椅上发话："帮我买 100 U 的 TRX"。 +2. 业务团队马上跑去查价格、算手续费，并老老实实写好一张"交易申请单"。 +3. 它们把单子递给坐在保险柜旁的 **财务总监（Agent Wallet）**。 +4. 财务总监核对无误后，绝不把私钥拿出保险柜，而是直接在申请单上盖个"同意印章"（技术上叫签名），然后再把盖好章的单子递出去。 +5. 业务团队拿着盖好章的单子，去区块链上把事办妥。 -✨ **核心亮点：** 整个过程中，跑腿的 AI 工具自始至终只拿到了"签名结果"，不是密钥本身！既保证了 AI 代理能拥有极其强大的链上操作能力，又保证了你的资产安全。 +✨ **核心亮点：** 在整个过程中，跑腿的 AI 工具自始至终只拿到了"盖好章的纸"，连私钥的影子都没见着！既保证了 AI 代理能帮你干极其复杂的活儿，又保证了你的资产绝对安全。 -#### ⚙️ 我该怎么把它们连起来？ +#### ⚙️ 听起来很棒，我该怎么把它们连起来？ -你只需要做一件事——给"业务团队"一把唤醒财务总监的内部口令。把你创建 Agent Wallet 时生成的主密码告诉工具： +极其简单！你不需要写复杂的程序，只需要做一件事：给业务团队一把唤醒财务总监的内部口令。 + +把你创建 Agent Wallet 时生成的"主密码"像下面这样告诉工具即可： ```bash export AGENT_WALLET_PASSWORD='你的主密码' ``` -设置好这一个口令后，整个系统就能全自动无缝配合了。工具会自动调用你的 Agent-wallet 来签名，你的 AI 代理将彻底蜕变为一个既聪明能干，又绝对安全的 Web3 顶级私人管家！ +就这一行配置！设置好口令后，整个系统就能全自动无缝配合了。你的 AI 代理将彻底蜕变为一个既聪明能干，又绝对安全的 Web3 顶级私人管家！ -> 跟着做一遍？去 **[快速开始](./QuickStart.md)**。 +> 迫不及待想试试？去 👉 **[快速开始](./QuickStart.md)** 跟着做一遍。 ### ⌨️ 我是进阶用户——想用 CLI 管理钱包 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 7d4c8ae2..3079d951 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -3,7 +3,7 @@ 你不需要写代码，不需要懂技术。只要把下面的"参考话术"复制到 AI 对话框里，回车，AI 就会自动帮你干活。 :::warning 三条铁律 -BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤回"按钮，没有客服回滚。 +BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤回"按钮，没有客服回滚。 1. **永远不要把私钥粘贴到聊天窗口里。** 请使用 [Agent Wallet](../../Agent-Wallet/Intro.md)（相当于给 AI 开了一个专用"支付宝"，你不需要把银行卡密码直接给它）。 2. **先用假钱练手。** 每个新操作都先在 Nile 测试网上试——测试网用的是免费"游戏币"，怎么折腾都不亏。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index d0f0e0e0..68f6b223 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -1,34 +1,47 @@ # 简介 -欢迎来到 BANK OF AI Skills！简单来说，这是一套专为 TRON（波场）生态打造的**"AI 专属技能包"**。无论你是想查行情、做交易，还是追踪链上数据，现在都不用再打开一堆网页和 App 了——你只需要像聊天一样对 AI 发号施令，剩下的脏活累活，全交给它来搞定。 +欢迎来到 BANK OF AI SKILLS！ + +在过去，探索 Web3 是一件充满门槛的苦差事：盯盘、算滑点、切钱包、查合约……稍有不慎还会踩坑报错。现在，我们决定终结这种繁琐。 + +简单来说，BANK OF AI SKILLS 是一套专为 TRON（波场）生态深度定制的**"AI 专属技能包"**。它将传统的"手动操作"彻底升级为"意图驱动"的对话式体验。你只需要像和私人交易员聊天一样发号施令，剩下的所有脏活、累活、技术活，全交给 AI 来搞定。 --- -## 你的 AI 为什么光说不练？ +## 🌟 为什么光有"工具箱"不够，必须配上 Skill（技能包）？ -你可能已经用上了 AI 聊天工具，问它"帮我在 SunSwap 上把 100 USDT 换成 TRX"，它回你一堆操作步骤——然后就没有然后了。它只会嘴上说说，不会真正动手帮你操作。 +现在市面上也有一些号称能交易的 AI，它们通常只是简单地给 AI 接入了底层工具接口（即 MCP）。但如果你用过就会发现，只给 AI 工具，它往往会变成一个"拿着菜刀乱挥的厨房杀手"。 -为什么？ +在 Web3 真实的高风险交易中，AI 需要的不仅仅是"能调用工具"，而是必须"懂业务流程"。BANK OF AI SKILLS 的核心竞争力，就在于我们将单纯的"工具箱"，升级成了自带防错机制和风控底线的"标准化流水线"。 -因为以前的 AI 只是一个懂理论的"嘴强王者"。它知道怎么换币，但它没有手——不能查余额、不能发交易、不能帮你点确认。 +有了 Skills，你的 AI 将拥有以下三大断层优势： ---- +| 真实交易痛点 | 🛠️ 只有基础工具箱（纯 MCP） | 🦸‍♂️ 搭载 BANK OF AI SKILLS（专属技能包） | +| :--- | :--- | :--- | +| **执行复杂交易**（防错与 SOP） | 容易迷路、疯狂报错。比如你想换币，它可能连授权（Approve）都没做就强行交易，直接卡死。 | 自带"老司机导航"。强制执行完美步骤：查余额 → 检查授权 → 报价 → 确认 → 交易，一步都不乱。 | +| **资金安全与风控**（防爆仓） | 盲目听话，没有底线。工具只管执行，你如果随口说"开 100 倍杠杆"，它真敢帮你开。 | 内置"业务级安全锁"。底层锁死风控红线（如：最高 20 倍杠杆、强制带止损），直接拦截危险指令。 | -## 给 AI 配上"工具箱"和"操作手册" +**一句话总结：** 普通的 AI 工具箱只是给你递了一把扳手，怎么拧还得看你；而 BANK OF AI SKILLS 就像是给你配了一个自带说明书、绝不犯低级错误、还会主动帮你避坑的米其林大厨。你只管用大白话点菜，剩下的它全包。 -现在不一样了。我们给 AI 配了两样东西： +### 🎬 真实场景还原：当你想"花 50 U 买点 TRX" -**工具箱（MCP Server）** — 让 AI 拥有查数据、发交易的实际能力（就像给它装上了手）。 +假设你现在对 AI 下达了一句最简单的指令："帮我用 50 USDT 买点 TRX。" -**操作手册（Skill）** — 告诉 AI 遇到具体任务时该怎么一步步操作（就像给它装上了干活的脑子）。 +**❌ 如果是普通的 AI 工具箱（纯 MCP）：** -| | 工具箱（MCP Server） | 操作手册（Skill） | -| :--- | :--- | :--- | -| **干什么的** | 给 AI 干活的能力 | 教 AI 怎么把能力组合起来完成任务 | -| **举个例子** | 提供"查余额"、"发转账"等单个能力 | 定义"换币"的完整流程：查余额 → 获取报价 → 确认价格 → 执行交易 | -| **打个比方** | 菜刀、锅、灶台 | 菜谱 | +它听到指令，拿起"交易工具"就直接去链上执行购买。结果**"砰"的一声，交易失败**。AI 给你弹出一长串看不懂的代码报错（比如 `transfer amount exceeds allowance`）。 + +为什么？因为在 Web3 的世界里，花 USDT 之前必须先进行**"授权（Approve）"**。普通 AI 只有工具但没有行业常识，漏掉前置步骤直接宕机，留下你一脸懵。 -有了操作手册，你的 AI 就从"只会动嘴皮子的理论家"变成了"真正能帮你干活的交易员"。 +**✅ 如果是搭载了 BANK OF AI SKILLS 的专属 AI：** + +它接到指令后，不仅会执行，还会自动在后台跑一遍"标准作业流程"。你的体验会是这样的： + +1. **自动查账：** "老板，看过了，您的钱包里有 100 USDT，余额充足。" +2. **前置排雷：** "发现您还没对 SunSwap 授权过 USDT，我已经帮您把授权（Approve）申请准备好了，请先确认。" +3. **精准报价：** "授权成功！按最新价格，50 USDT 约可兑换 350 TRX，我已经自动帮您设置好 1% 的防夹滑点。是否现在买入？" + +在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"查余额 → 发现缺授权 → 补授权 → 算滑点 → 拉报价"这整整 5 个高门槛步骤。这就是纯工具和"带脑子的专业管家"之间最直观的降维打击。 --- @@ -81,13 +94,11 @@ --- -## 这套技能包适合我吗？ - -**我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么填滑点和 Gas 费了。直接用大白话跟 AI 提要求，它会把嚼碎的结果喂给你。 - -**我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下你大把的时间和精力。你可以专注于策略，把执行交给 AI。 +## 🎯 这套技能包适合我吗？ -**我只是想玩玩：** 完全没问题！"链上数据侦探"技能 100% 免费且只读，不用连钱包也能玩得很开心。零风险，随便折腾。 +- **👶 我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么算滑点和 Gas 费了。直接用大白话提要求，AI 把处理好的结果直接喂给你。 +- **🕴️ 我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下大把精力。你只需专注策略，把枯燥的执行全扔给 AI。 +- **🍉 我只是想吃瓜玩玩：** 完全没问题！"链上数据侦探"等纯读取技能 100% 免费，不用连钱包也能畅通无阻，零风险体验 Web3 魔法。 --- From 6295071721460b69998bb49f5476b09b09e70c61 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 17:32:41 +0800 Subject: [PATCH 32/44] update skill intro --- docs/McpServer-Skills/SKILLS/Intro.md | 27 +++++++++---------- .../current/McpServer-Skills/SKILLS/Intro.md | 24 ++++++++--------- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 5e5faaa4..65fbb7e1 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -8,31 +8,30 @@ In a nutshell, BANK OF AI SKILLS is a set of **"AI skill packs"** purpose-built --- -## 🌟 Why a "Toolbox" Alone Isn't Enough — You Need Skills +## 🌟 Why You Need Professional Skills -Some AI products on the market claim they can trade, but they typically just plug the AI into raw tool interfaces (i.e., MCP). If you've tried them, you'll know the result: give AI nothing but tools and it becomes a "kitchen maniac swinging a knife with no recipe." +Today's AI chatbots are smart — if you push them to write a transfer script or hook them up to an API to try their luck on-chain, they can pull it off. But if you actually let them loose on your real money without guardrails, it often turns into a disaster. -In the high-stakes reality of Web3 trading, an AI needs more than "the ability to call tools" — it must "understand the business workflow." The core edge of BANK OF AI SKILLS is that we upgraded a bare toolbox into a **standardized pipeline with built-in error prevention and risk control guardrails**. +In the high-stakes reality of Web3 trading, an AI needs more than "smart and capable" — it must "know the business" and be "absolutely reliable." The core edge of BANK OF AI SKILLS is that we took a regular copy-paste AI and upgraded it into a **Web3 personal assistant** with built-in error prevention, deep business workflow expertise, and strict risk control guardrails. -With Skills, your AI gains three decisive advantages: +With Skills, your AI gains decisive advantages: -| Real Trading Pain Point | 🛠️ Basic Toolbox Only (raw MCP) | 🦸‍♂️ With BANK OF AI SKILLS (full skill pack) | +| Real Trading Pain Point | ❌ Regular AI Chatbot | 🦸‍♂️ With BANK OF AI SKILLS (personal assistant) | | :--- | :--- | :--- | -| **Complex trade execution** (error prevention & SOP) | Gets lost easily, errors everywhere. For example, it might try to swap tokens without even approving the contract first — instant failure. | Built-in "veteran driver navigation." Enforces the perfect sequence: check balance → verify approval → get quote → confirm → execute. Never misses a step. | -| **Fund safety & risk control** (blow-up prevention) | Blindly obedient, no guardrails. It just executes — if you casually say "open 100x leverage," it actually does it. | Built-in "business-level safety locks." Hard-coded risk limits (e.g., max 20x leverage, mandatory stop-loss), dangerous commands get blocked on the spot. | -| **Daily communication barrier** (understands plain language) | Tedious, like filling out forms. You need to precisely input contract addresses, slippage percentages, and other complex parameters — one typo and it all falls apart. | Powerful "intent translation." Just say "swap all my USDT for TRX" and it looks up addresses, calculates slippage, and fetches quotes on its own — never bothers you. | +| **Complex trade execution** (error prevention & SOP) | Guesses its way through, easily gets stuck. It can handle single-step commands, but for complex swaps, it often doesn't know you need to Approve first — leading to blind operations and error crashes. | Built-in "veteran driver navigation." Enforces the perfect sequence: check balance → verify approval → get quote → confirm → execute. Never misses a step. | +| **Fund safety & risk control** (blow-up prevention) | Blindly obedient, no guardrails. It doesn't understand financial common sense — if you casually say "open 100x leverage," it will generate that dangerous command without hesitation. | Built-in "business-level safety locks." Hard-coded risk limits (e.g., max 20x leverage, mandatory stop-loss) — dangerous operations get blocked on the spot. | -**In one sentence:** A regular AI toolbox just hands you a wrench — you still have to figure out how to turn it. BANK OF AI SKILLS is like having a Michelin chef who comes with the recipe book, never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. +**In one sentence:** A regular AI is a straight-A "top student" on paper, but full of holes the moment it hits real operations. An AI with BANK OF AI SKILLS is like a Michelin chef with real battlefield experience — never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. ### 🎬 Real Scenario: You Want to "Buy Some TRX with 50 USDT" Let's say you give the AI the simplest possible command: "Buy some TRX with 50 USDT." -**❌ With a regular AI toolbox (raw MCP):** +**❌ With a regular AI:** -It hears the command, grabs the "trade tool," and goes straight to the blockchain to execute the purchase. Result: **BOOM — transaction failed.** The AI throws a wall of incomprehensible error code at you (something like `transfer amount exceeds allowance`). +It hears the command and might generate a chunk of buggy code, or blindly try its luck on-chain. The result is usually **BOOM — transaction failed.** Then it throws a wall of incomprehensible error messages at you (something like `transfer amount exceeds allowance`). -Why? Because in the Web3 world, you must **"Approve"** a token before spending it. A regular AI has the tools but zero domain knowledge — it skips the prerequisite step, crashes, and leaves you staring at a screen full of gibberish. +Why? Because in the Web3 world, you must **"Approve"** a token before spending it. A regular AI has plenty of IQ but zero "industry common sense" — it skips the prerequisite step, crashes, and leaves you staring at gibberish. **✅ With BANK OF AI SKILLS installed:** @@ -42,7 +41,7 @@ After receiving your command, it doesn't just execute — it automatically runs 2. **Preemptive troubleshooting:** "I noticed you haven't approved USDT for SunSwap yet. I've prepared the Approve request — please confirm." 3. **Precise quote:** "Approval successful! At the latest price, 50 USDT gets you roughly 350 TRX. I've automatically set 1% slippage protection. Ready to buy?" -In this scenario, you said one sentence, and the Skill quietly handled 5 high-barrier steps behind the scenes: check balance → detect missing approval → submit approval → calculate slippage → fetch quote. That's the difference between a bare tool and a "pro butler with a brain." +In this scenario, you said one sentence, and the Skill quietly handled 5 high-barrier steps behind the scenes: check balance → detect missing approval → submit approval → calculate slippage → fetch quote. That's the difference between a **"regular chatbot AI"** and a **"professional Web3 butler."** --- @@ -107,7 +106,7 @@ Check your BANK OF AI balance and top up with a single sentence. **Ready? Just 2 steps, less than 1 minute.** - + Go to Quick Start diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index 68f6b223..cba87e56 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -8,30 +8,30 @@ --- -## 🌟 为什么光有"工具箱"不够，必须配上 Skill（技能包）？ +## 🌟 为什么你需要一套专业的 Skill（技能包）？ -现在市面上也有一些号称能交易的 AI，它们通常只是简单地给 AI 接入了底层工具接口（即 MCP）。但如果你用过就会发现，只给 AI 工具，它往往会变成一个"拿着菜刀乱挥的厨房杀手"。 +现在的普通 AI 都很聪明，如果你硬让它去写一段转账代码，或者给它接上接口去链上碰碰运气，它也能做到。但如果你真让它毫无防备地去操作你的真金白银，往往会变成一场灾难。 -在 Web3 真实的高风险交易中，AI 需要的不仅仅是"能调用工具"，而是必须"懂业务流程"。BANK OF AI SKILLS 的核心竞争力，就在于我们将单纯的"工具箱"，升级成了自带防错机制和风控底线的"标准化流水线"。 +在 Web3 真实的高风险交易中，AI 需要的不仅仅是"聪明能干"，而是必须"懂行"且"绝对靠谱"。BANK OF AI SKILLS 的核心竞争力，就在于把一个只会生搬硬套的普通 AI，升级成了一个自带防错机制、精通业务流程、且严格守住风控底线的"Web3 专属私人助理"。 -有了 Skills，你的 AI 将拥有以下三大断层优势： +有了 Skills，你的 AI 将拥有以下断层优势： -| 真实交易痛点 | 🛠️ 只有基础工具箱（纯 MCP） | 🦸‍♂️ 搭载 BANK OF AI SKILLS（专属技能包） | +| 真实交易痛点 | ❌ 普通的 AI 聊天机器人 | 🦸‍♂️ 搭载 BANK OF AI SKILLS（专属助理） | | :--- | :--- | :--- | -| **执行复杂交易**（防错与 SOP） | 容易迷路、疯狂报错。比如你想换币，它可能连授权（Approve）都没做就强行交易，直接卡死。 | 自带"老司机导航"。强制执行完美步骤：查余额 → 检查授权 → 报价 → 确认 → 交易，一步都不乱。 | -| **资金安全与风控**（防爆仓） | 盲目听话，没有底线。工具只管执行，你如果随口说"开 100 倍杠杆"，它真敢帮你开。 | 内置"业务级安全锁"。底层锁死风控红线（如：最高 20 倍杠杆、强制带止损），直接拦截危险指令。 | +| **执行复杂交易**（防错与 SOP） | 靠猜行事，容易卡壳。它能执行单步指令，但遇到复杂的换币，它往往不知道前提是要先授权（Approve），导致盲目操作、报错卡死。 | 自带"老司机导航"。强制执行完美步骤：查余额 → 检查授权 → 报价 → 确认 → 交易，一步都不乱。 | +| **资金安全与风控**（防爆仓） | 盲目听话，没有底线。它不懂金融常识，你如果随口说"开 100 倍杠杆"，它真敢毫无顾忌地帮你生成危险指令。 | 内置"业务级安全锁"。底层锁死风控红线（如：最高 20 倍杠杆、强制带止损），直接拦截危险操作。 | -**一句话总结：** 普通的 AI 工具箱只是给你递了一把扳手，怎么拧还得看你；而 BANK OF AI SKILLS 就像是给你配了一个自带说明书、绝不犯低级错误、还会主动帮你避坑的米其林大厨。你只管用大白话点菜，剩下的它全包。 +**一句话总结：** 普通的 AI 只是一个理论满分的"高材生"，一上实操就容易漏洞百出；而搭载了 BANK OF AI SKILLS 的 AI，就像是给你配了一个自带实战经验、绝不犯低级错误、还会主动帮你避坑的米其林大厨。你只管用大白话点菜，剩下的它全包。 ### 🎬 真实场景还原：当你想"花 50 U 买点 TRX" 假设你现在对 AI 下达了一句最简单的指令："帮我用 50 USDT 买点 TRX。" -**❌ 如果是普通的 AI 工具箱（纯 MCP）：** +**❌ 如果是普通的 AI：** -它听到指令，拿起"交易工具"就直接去链上执行购买。结果**"砰"的一声，交易失败**。AI 给你弹出一长串看不懂的代码报错（比如 `transfer amount exceeds allowance`）。 +它听到指令，可能直接给你生成一段漏洞百出的代码，或者盲目去链上碰运气。结果往往是**"砰"的一声，交易失败**。然后给你弹出一长串看不懂的英文报错（比如 `transfer amount exceeds allowance`）。 -为什么？因为在 Web3 的世界里，花 USDT 之前必须先进行**"授权（Approve）"**。普通 AI 只有工具但没有行业常识，漏掉前置步骤直接宕机，留下你一脸懵。 +为什么？因为在 Web3 的世界里，花 USDT 之前必须先进行**"授权（Approve）"**。普通的 AI 空有智商却没有"行业常识"，漏掉前置步骤直接宕机，留下你一脸懵。 **✅ 如果是搭载了 BANK OF AI SKILLS 的专属 AI：** @@ -41,7 +41,7 @@ 2. **前置排雷：** "发现您还没对 SunSwap 授权过 USDT，我已经帮您把授权（Approve）申请准备好了，请先确认。" 3. **精准报价：** "授权成功！按最新价格，50 USDT 约可兑换 350 TRX，我已经自动帮您设置好 1% 的防夹滑点。是否现在买入？" -在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"查余额 → 发现缺授权 → 补授权 → 算滑点 → 拉报价"这整整 5 个高门槛步骤。这就是纯工具和"带脑子的专业管家"之间最直观的降维打击。 +在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"查余额 → 发现缺授权 → 补授权 → 算滑点 → 拉报价"这整整 5 个高门槛步骤。这就是**"普通聊天 AI"和"专业 Web3 管家"**之间最直观的降维打击。 --- From 22486985ae5a72e0d82570261bc569bed327845f Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 18:32:20 +0800 Subject: [PATCH 33/44] update skill intro --- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 6 +-- docs/McpServer-Skills/SKILLS/Faq.md | 7 ++- docs/McpServer-Skills/SKILLS/Intro.md | 29 ++++++------- docs/McpServer-Skills/SKILLS/QuickStart.md | 41 +++--------------- .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 6 +-- .../current/McpServer-Skills/SKILLS/Faq.md | 7 ++- .../current/McpServer-Skills/SKILLS/Intro.md | 29 ++++++------- .../McpServer-Skills/SKILLS/QuickStart.md | 43 +++---------------- 8 files changed, 49 insertions(+), 119 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index a6c0b7b4..8d7642d5 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -19,7 +19,7 @@ BANK OF AI SKILLS can operate on **real on-chain assets**. Blockchain transactio | **sunswap** | Check prices, get quotes, swap tokens, manage liquidity pools | Read-only: none. Trading: wallet credentials | | **sunperp-skill** | Market data, open/close positions, withdrawals | Market data: none. Trading: SunPerp API keys | | **tronscan-skill** | Look up accounts, transactions, tokens, blocks, network stats | Recommended: TronScan API key (may throttle without one) | -| **x402-payment** | Auto-pay for premium APIs and agents | Wallet credentials | +| **x402-payment** | On-chain "pay-first" auto-settlement | Wallet credentials | | **recharge-skill** | Balance, order history, account top-up | BANK OF AI API key | ### 🔑 Where Do I Get These Keys? How Do I Set Them Up? @@ -146,9 +146,9 @@ Want to know what's happening on-chain? This skill looks up accounts, transactio --- -## x402-payment — Auto-Pay for Premium Services +## x402-payment — On-Chain "Pay-First" Auto-Settlement -Some APIs and AI agents charge a small fee to use. This skill handles the payment flow automatically — the AI detects the charge, pays it, gets the result, and reports back. It always asks for your confirmation before paying. +Some APIs and AI agents require on-chain payment before use. This skill uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — the AI detects the charge, completes the on-chain payment, gets the result, and reports back. It always asks for your confirmation before paying. **Requires your confirmation:** diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index 59650803..c4778527 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -147,7 +147,7 @@ export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" ### Which AI tools support Skills? -Currently: **OpenClaw** (most seamless), **Claude Code**, **Cursor**, and any AI assistant that can read local files. +Currently: **OpenClaw** (most seamless), and any AI assistant that can read local files. --- @@ -167,11 +167,10 @@ For example, if you think 20x leverage is still too risky for perpetual trading, rm -rf ~/.openclaw/skills/sunswap ``` -**Update:** Re-run the installer. It will ask if you want to overwrite existing skills. +**Update:** Re-run the install command. It will update all skills to the latest version. ```bash -cd openclaw-extension -./install.sh +npx skills add https://github.com/BofAI/skills ``` --- diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 65fbb7e1..7e71638f 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -4,7 +4,7 @@ Welcome to BANK OF AI SKILLS! In the past, exploring Web3 was a grind full of barriers: watching charts, calculating slippage, switching wallets, checking contracts... one wrong step and you'd hit an error. We decided to put an end to that hassle. -In a nutshell, BANK OF AI SKILLS is a set of **"AI skill packs"** purpose-built for the TRON ecosystem. It upgrades traditional "manual operations" into an **intent-driven, conversational experience**. Just talk to the AI like you would a personal trader, and it handles all the dirty work, heavy lifting, and technical details for you. +In a nutshell, BANK OF AI SKILLS is a set of **"AI skill packs"** purpose-built for the TRON ecosystem. Ordinary AI tends to fumble complex Web3 trades — blindly copying steps and riddled with errors. Our Skills provide the AI Agent with a set of **"standardized workflows"** — like having a personal trader who already comes with hands-on experience in DEX trading, contract lookup, and perpetual swaps. Just chat naturally, and from pre-flight checks and parameter calculations to transaction bundling — all the error-prone grunt work — Skills automatically orchestrate everything flawlessly behind the scenes. --- @@ -21,7 +21,7 @@ With Skills, your AI gains decisive advantages: | **Complex trade execution** (error prevention & SOP) | Guesses its way through, easily gets stuck. It can handle single-step commands, but for complex swaps, it often doesn't know you need to Approve first — leading to blind operations and error crashes. | Built-in "veteran driver navigation." Enforces the perfect sequence: check balance → verify approval → get quote → confirm → execute. Never misses a step. | | **Fund safety & risk control** (blow-up prevention) | Blindly obedient, no guardrails. It doesn't understand financial common sense — if you casually say "open 100x leverage," it will generate that dangerous command without hesitation. | Built-in "business-level safety locks." Hard-coded risk limits (e.g., max 20x leverage, mandatory stop-loss) — dangerous operations get blocked on the spot. | -**In one sentence:** A regular AI is a straight-A "top student" on paper, but full of holes the moment it hits real operations. An AI with BANK OF AI SKILLS is like a Michelin chef with real battlefield experience — never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. +**In one sentence:** A regular AI is a straight-A "top student" on paper, but full of holes the moment it hits real operations. An AI with BANK OF AI SKILLS is like a seasoned pro who already comes with DEX trading, contract lookup, and perpetual swap skills — never makes rookie mistakes, and proactively steers you away from pitfalls. You just order in plain language, and it handles everything. ### 🎬 Real Scenario: You Want to "Buy Some TRX with 50 USDT" @@ -45,22 +45,17 @@ In this scenario, you said one sentence, and the Skill quietly handled 5 high-ba --- -## Trusting AI with Your Money? Three Reassurances +## 🛡️ Your Assets Are Absolutely Safe with Skills -The three questions you're most worried about — we've already thought of them: +**"Can Skills spend my money without permission?"** +No. Every operation that involves spending money has a built-in **intercept-confirm mechanism** — the AI pauses first and shows you the full "bill": how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** Think of it as a diligent assistant who needs your signature on every expense report. -**"Will the AI secretly transfer my money?"** -No. Every operation that involves spending money will pause first and show you the full details — how much, where to, which chain, estimated fees. **Nothing happens until you explicitly say "yes."** Think of it as a diligent assistant who needs your signature on every expense report. - -**"Will a ton of skills make the AI slow or confused?"** -No. When the AI starts up, it only loads a "table of contents" (like glancing at labels on a bookshelf). It only reads the full skill content when you actually use it. Hundreds of skills? Still lightning fast. - -**"Is my private key safe?"** -We recommend **Agent Wallet** — think of it as opening a dedicated "payment account" for your AI. You don't hand over your bank password (private key) directly. Instead, you give it an encrypted password. Even if someone peeks at your environment variables, they still need the encryption password to unlock anything — the odds of both locks being broken are extremely low. +**"Will installing lots of Skills slow things down?"** +No. Skills use an **on-demand, lightweight architecture** — the AI only loads a "table of contents" at startup (like glancing at labels on a bookshelf). It reads the full skill content only when you actually use it. Hundreds of Skills? Still lightning fast. --- -## What Can It Do for You? +## What Can Skills Do for You? Five core skills covering the most common scenarios in the TRON ecosystem. Each one comes with a ready-to-use sample prompt — copy it into your AI chat and hit enter to try it out. @@ -82,9 +77,11 @@ Look up accounts, transactions, and check if a new token is legit. Pure read-onl > 🗣️ "Check the holder distribution for that new token — is it controlled by a whale?" -### ☕ Auto-Pay Runner +### ☕ On-Chain "Pay-First" Auto-Settlement + +When the AI needs to call a paid on-chain service or data API, it uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — no manual QR scanning or wallet switching needed. -When the AI encounters a premium service (like a paid data API), it can automatically pay the small service fee for you — no need to switch apps or scan QR codes. +> 🗣️ "Use the x402 protocol to call this paid agent endpoint: https://api.example.com" (replace with the actual paid endpoint URL you want to call) ### 🏦 Account Manager @@ -94,7 +91,7 @@ Check your BANK OF AI balance and top up with a single sentence. --- -## 🎯 Is This Right for Me? +## 🎯 Are These Skills Right for Me? - **👶 I'm a total beginner:** Perfect! No more wrestling with candlestick charts, slippage settings, or gas fee calculations. Just tell the AI what you want in plain language — it does the hard work and feeds you the results. - **🕴️ I'm an experienced trader:** Tired of staring at screens all day? Let the AI batch-monitor data and calculate yields, freeing up your time and energy. You focus on strategy — let the AI handle the tedious execution. diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 2690c74a..0de13224 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -6,8 +6,6 @@ Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than * ## Step 1: Install the Skills -**If you are using OpenClaw (our top recommended AI client), just use the easiest, foolproof installation method below: Install via OpenClaw Extension** - Open the "Terminal" on your computer (the black window where you type commands). :::tip Can't find Terminal? No worries @@ -18,47 +16,18 @@ Open the "Terminal" on your computer (the black window where you type commands). **Copy this entire line**, paste it into the black window, and press Enter: ```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +npx skills add https://github.com/BofAI/skills ``` -A bunch of text will scroll across the screen — **you can ignore it**. Just wait for it to stop. The installer will ask you which components to install; follow the prompts and confirm. +A bunch of text will scroll across the screen — **you can ignore it**. Just wait for it to stop. This command will install all BANK OF AI skills at once. -When it's done, verify by typing this into the terminal: +When it's done, verify the installation was successful by asking your AI: -```bash -ls ~/.openclaw/skills ``` - -If you see directory names like `sunswap`, `tronscan-skill`, etc. — congratulations, installation is complete! - -
-Not using OpenClaw? Click here for other installation methods - -**Claude Code:** - -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ +Read the sunswap skill and tell me what it can do. ``` -**Cursor:** - -```bash -git clone https://github.com/BofAI/skills.git .cursor/skills -``` - -In Cursor Chat, use `@` to reference specific `SKILL.md` files. - -**Any AI tool (universal method):** - -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` - -Then tell the AI directly: `Please read ~/bofai-skills/sunswap/SKILL.md and check the current price of TRX for me.` - -
+If the AI accurately describes the skill's capabilities — congratulations, installation is complete! --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 3079d951..2a8c5ffe 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -19,7 +19,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 | **sunswap** | 查价、报价、换币、管理流动性池 | 查询不需要；交易需要钱包凭证 | | **sunperp-skill** | 看行情、开仓、平仓、提现 | 看行情不需要；交易需要 SunPerp 密钥 | | **tronscan-skill** | 查账户、交易、代币、区块、全网数据 | 建议配置 TronScan API 密钥（不配可能卡顿） | -| **x402-payment** | 自动帮你支付收费 API 的"跑腿费" | 需要钱包凭证 | +| **x402-payment** | 链上"先付后用"自动结算 | 需要钱包凭证 | | **recharge-skill** | 查余额、看订单、充值 | 需要 BANK OF AI 密钥 | ### 🔑 这些"钥匙"去哪领？怎么配？ @@ -146,9 +146,9 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## x402-payment — 自动打赏功能 +## x402-payment — 链上"先付后用"自动结算 -有些高级 API 和 AI 智能体是收费的——需要你先付一小笔"跑腿费"才能使用。这个技能让 AI 帮你自动完成支付流程：AI 发现对方要收费，自动帮你付款，拿到结果后汇报给你。每次付款前同样会先问你确认。 +有些高级 API 和 AI 智能体是收费的——需要你先完成链上付费才能使用。这个技能通过 x402 协议帮你自动完成"先付费、再获取"的链上结算流程：AI 发现对方要收费，自动帮你完成链上支付，拿到结果后汇报给你。每次付款前同样会先问你确认。 **需要你确认才会执行：** diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index a261c90c..f412fb68 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -147,7 +147,7 @@ export BANKOFAI_API_KEY="你的 BANK OF AI API Key" ### 哪些 AI 工具能用这些技能？ -目前支持：**OpenClaw**（最省心）、**Claude Code**、**Cursor**，以及任何能读取本地文件的 AI 助手。 +目前支持：**OpenClaw**（最省心），以及任何能读取本地文件的 AI 助手。 --- @@ -167,11 +167,10 @@ export BANKOFAI_API_KEY="你的 BANK OF AI API Key" rm -rf ~/.openclaw/skills/sunswap ``` -**更新：** 重新运行安装器，它会问你要不要覆盖旧版本。 +**更新：** 重新运行安装命令，会自动更新所有技能到最新版本。 ```bash -cd openclaw-extension -./install.sh +npx skills add https://github.com/BofAI/skills ``` --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index cba87e56..ff72ff89 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -4,7 +4,7 @@ 在过去，探索 Web3 是一件充满门槛的苦差事：盯盘、算滑点、切钱包、查合约……稍有不慎还会踩坑报错。现在，我们决定终结这种繁琐。 -简单来说，BANK OF AI SKILLS 是一套专为 TRON（波场）生态深度定制的**"AI 专属技能包"**。它将传统的"手动操作"彻底升级为"意图驱动"的对话式体验。你只需要像和私人交易员聊天一样发号施令，剩下的所有脏活、累活、技术活，全交给 AI 来搞定。 +简单来说，BANK OF AI SKILLS 是一套专为 TRON（波场）生态深度定制的**"AI 专属技能包"**。普通的 AI 面对复杂的 Web3 交易往往只会生搬硬套、漏洞百出，而我们的 Skills 给 AI 提供一套"标准化流程"——就像是给你配了一个自带 DEX 交易、合约查询、永续合约实战经验的私人交易员。你只需要像聊天一样发号施令，从前置排雷、参数计算到交易打包，这些极其容易出错的脏活累活，Skills 都会在底层自动为你完美编排。 --- @@ -21,7 +21,7 @@ | **执行复杂交易**（防错与 SOP） | 靠猜行事，容易卡壳。它能执行单步指令，但遇到复杂的换币，它往往不知道前提是要先授权（Approve），导致盲目操作、报错卡死。 | 自带"老司机导航"。强制执行完美步骤：查余额 → 检查授权 → 报价 → 确认 → 交易，一步都不乱。 | | **资金安全与风控**（防爆仓） | 盲目听话，没有底线。它不懂金融常识，你如果随口说"开 100 倍杠杆"，它真敢毫无顾忌地帮你生成危险指令。 | 内置"业务级安全锁"。底层锁死风控红线（如：最高 20 倍杠杆、强制带止损），直接拦截危险操作。 | -**一句话总结：** 普通的 AI 只是一个理论满分的"高材生"，一上实操就容易漏洞百出；而搭载了 BANK OF AI SKILLS 的 AI，就像是给你配了一个自带实战经验、绝不犯低级错误、还会主动帮你避坑的米其林大厨。你只管用大白话点菜，剩下的它全包。 +**一句话总结：** 普通的 AI 只是一个理论满分的"高材生"，一上实操就容易漏洞百出；而搭载了 BANK OF AI SKILLS 的 AI，就像是给你配了一个自带 DEX 交易、合约查询、永续合约技能的实战老手——绝不犯低级错误、还会主动帮你避坑。你只管用大白话点菜，剩下的它全包。 ### 🎬 真实场景还原：当你想"花 50 U 买点 TRX" @@ -45,22 +45,17 @@ --- -## 把钱交给 AI？先吃下这三颗定心丸 +## 🛡️ 使用 Skills 交易，你的资产绝对安全 -把钱交给 AI 操作，你最担心的三个问题我们都想到了： +**"Skills 会越权动用我的资金吗？"** +不会。所有涉及花钱的操作都内置了**拦截确认机制**——AI 会先暂停，把完整的"账单"摊开给你看（要花多少、转到哪里、走哪条链、预估手续费），**你不亲口说"好"，它绝不动手**。就像一个尽职的助理，每笔报销单都要你签字才能走流程。 -**"AI 会偷偷把我的钱转走吗？"** -不会。每次涉及花钱的操作，AI 都会先暂停，把所有细节摊开给你看（要花多少、转到哪里、走哪条链），**只有你亲口说"好"，它才会动手**。就像一个尽职的助理，每笔报销单都要你签字才能走流程。 - -**"装了一堆技能，AI 会不会变卡、变笨？"** -不会。AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个技能，照样飞快。 - -**"我的密码安全吗？"** -我们推荐使用 **Agent Wallet** — 你可以把它理解成给 AI 专门开了一个"支付宝"。你不需要把银行卡密码（私钥）直接给它，而是给它一个支付密码。每次它要花钱，都得拿这个密码来找你核对。就算支付密码泄露了，对方还需要拿到你的电脑才能解锁——两把锁同时被破的概率极低。 +**"装了一堆 Skills，系统响应会不会变慢？"** +不会。Skills 采用**按需唤醒的轻量级架构**——AI 启动时只加载技能的"目录"（就像翻了一下书架上的标签），只有你真正用到某个技能时才会读取完整内容。装几百个 Skills，照样飞快。 --- -## 目前能帮你干什么？ +## 目前 Skills 能帮你干什么？ 五大核心技能，覆盖 TRON 生态最常用的场景。每个技能都配了一句"参考话术"——复制到 AI 对话框里回车就能体验。 @@ -82,9 +77,11 @@ > 🗣️ "帮我查一下昨天那个土狗币现在的持仓分布，有没有被庄家控盘？" -### ☕ 自动打赏跑腿 +### ☕ 链上"先付后用"自动结算 + +当 AI 需要调用付费的链上服务或数据接口时，会通过 x402 协议自动完成"先付费、再获取"的链上结算，无需你手动扫码或切换钱包。 -当 AI 遇到一些需要花钱的高级服务（比如付费数据接口）时，它能自动帮你付个几毛钱的跑腿费，不用你来回扫码支付。 +> 🗣️ "使用 x402 协议调用这个付费智能体端点：https://api.example.com"（请替换为你实际要调用的付费端点地址） ### 🏦 账户大管家 @@ -94,7 +91,7 @@ --- -## 🎯 这套技能包适合我吗？ +## 🎯 这套 Skills 适合我吗？ - **👶 我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么算滑点和 Gas 费了。直接用大白话提要求，AI 把处理好的结果直接喂给你。 - **🕴️ 我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下大把精力。你只需专注策略，把枯燥的执行全扔给 AI。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md index 9aaa2727..7614d016 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -6,8 +6,6 @@ ## 第 1 步：安装技能库 -**如果你正在使用 OpenClaw（我们最推荐的 AI 客户端），请直接使用下面这种最简单的傻瓜式安装：通过 OpenClaw Extension 安装** - 打开你电脑上的"终端"（就是那个黑框框）。 :::tip 找不到终端？别慌 @@ -15,50 +13,21 @@ **Windows 电脑：** 按 `Win + R`，在弹出的小窗口里输入 `cmd`，按回车。 ::: -把下面这串长长的代码**整行复制**，粘贴到黑框框里，按回车： +把下面这行代码**整行复制**，粘贴到黑框框里，按回车： ```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +npx skills add https://github.com/BofAI/skills ``` -屏幕上会跳出一堆英文字母——**不用管它们**，等它停下来就行。安装器会一步步问你要装哪些组件，跟着提示按回车确认即可。 +屏幕上会跳出一堆英文字母——**不用管它们**，等它停下来就行。这条命令会一次性安装所有 BANK OF AI 技能。 -装完后，黑框框里输入这行来验证： +装完后，在 AI 对话中验证： -```bash -ls ~/.openclaw/skills ``` - -如果看到 `sunswap`、`tronscan-skill` 等目录名出现——恭喜，安装成功！ - -
-用的不是 OpenClaw？点这里看其他安装方式 - -**Claude Code：** - -```bash -git clone https://github.com/BofAI/skills.git /tmp/bofai-skills -mkdir -p ~/.config/claude-code/skills -cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ +读一下 sunswap 技能，告诉我它能做什么。 ``` -**Cursor：** - -```bash -git clone https://github.com/BofAI/skills.git .cursor/skills -``` - -在 Cursor Chat 中用 `@` 引用具体的 `SKILL.md` 文件即可。 - -**任何 AI 工具（通用方式）：** - -```bash -git clone https://github.com/BofAI/skills.git ~/bofai-skills -``` - -然后在对话中直接告诉 AI：`请读取 ~/bofai-skills/sunswap/SKILL.md，帮我查一下 TRX 当前的价格。` - -
+AI 能准确描述功能——恭喜，安装成功！ --- From 590e69e08fc5c22486764723d789e77e7113f93f Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 18:39:24 +0800 Subject: [PATCH 34/44] update skills --- docs/McpServer-Skills/SKILLS/Intro.md | 2 +- .../current/McpServer-Skills/SKILLS/Intro.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 7e71638f..89de4e95 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -83,7 +83,7 @@ When the AI needs to call a paid on-chain service or data API, it uses the x402 > 🗣️ "Use the x402 protocol to call this paid agent endpoint: https://api.example.com" (replace with the actual paid endpoint URL you want to call) -### 🏦 Account Manager +### 🏦 BANK OF AI Account Manager Check your BANK OF AI balance and top up with a single sentence. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index ff72ff89..fc8b736e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -83,7 +83,7 @@ > 🗣️ "使用 x402 协议调用这个付费智能体端点：https://api.example.com"（请替换为你实际要调用的付费端点地址） -### 🏦 账户大管家 +### 🏦 BANK OF AI 账户大管家 查看你的 BANK OF AI 余额，一句话完成充值。 From b6621a6b71ae5b2312162c44bdf53a0576261769 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 19:59:56 +0800 Subject: [PATCH 35/44] update skill and setup way --- docs/McpServer-Skills/MCP/Intro.md | 2 +- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 14 +- .../SUNMCPServer/LocalPrivatizedDeployment.md | 172 ++++---------- .../MCP/SUNMCPServer/OfficialServerAccess.md | 69 ------ .../MCP/SUNMCPServer/QuickStart.md | 61 +---- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 32 +-- .../MCP/TRONMCPServer/Intro.md | 4 +- .../LocalPrivatizedDeployment.md | 146 +----------- .../MCP/TRONMCPServer/OfficialServerAccess.md | 110 ++------- .../MCP/TRONMCPServer/QuickStart.md | 53 +---- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 10 +- docs/McpServer-Skills/SKILLS/Intro.md | 22 +- docs/Openclaw-extension/FAQ.md | 214 ++++------------- docs/Openclaw-extension/Intro.md | 68 +++--- docs/Openclaw-extension/QuickStart.md | 174 +++++++------- .../current/McpServer-Skills/MCP/Intro.md | 2 +- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 14 +- .../SUNMCPServer/LocalPrivatizedDeployment.md | 162 ++----------- .../MCP/SUNMCPServer/OfficialServerAccess.md | 69 ------ .../MCP/SUNMCPServer/QuickStart.md | 61 +---- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 32 +-- .../MCP/TRONMCPServer/Intro.md | 6 +- .../LocalPrivatizedDeployment.md | 146 +----------- .../MCP/TRONMCPServer/OfficialServerAccess.md | 110 ++------- .../MCP/TRONMCPServer/QuickStart.md | 55 +---- .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 10 +- .../current/McpServer-Skills/SKILLS/Intro.md | 22 +- .../current/Openclaw-extension/FAQ.md | 216 ++++-------------- .../current/Openclaw-extension/Intro.md | 68 +++--- .../current/Openclaw-extension/QuickStart.md | 173 +++++++------- 30 files changed, 536 insertions(+), 1761 deletions(-) diff --git a/docs/McpServer-Skills/MCP/Intro.md b/docs/McpServer-Skills/MCP/Intro.md index 1bd3b19d..76da6657 100644 --- a/docs/McpServer-Skills/MCP/Intro.md +++ b/docs/McpServer-Skills/MCP/Intro.md @@ -6,7 +6,7 @@ The MCP Server is designed to provide a standardized framework for interaction b MCP follows a **client-server** architecture, primarily comprising the following three core participants: -* **MCP Host**: Typically the AI application itself (e.g., Claude Code or Claude Desktop). It is responsible for coordinating and managing one or more MCP Clients. +* **MCP Host**: Typically the AI application itself. It is responsible for coordinating and managing one or more MCP Clients. * **MCP Client**: Instantiated by the MCP Host for each MCP Server. Each client maintains a dedicated connection with its corresponding MCP Server and obtains context information from the MCP Server for the host to use. * **MCP Server**: A program responsible for providing context data to MCP Clients. Servers can run locally (e.g., a filesystem server) or remotely (e.g., a TRON MCP/SUN MCP server). diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 4cdd62ba..833497c5 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -9,9 +9,9 @@ This page collects frequently asked questions when using SUN MCP Server and thei ## Connection Issues -### Claude Desktop "Cannot Connect to MCP Server" +### MCP client "Cannot Connect to MCP Server" -**Symptom:** Claude Desktop shows server unresponsive or connection refused. +**Symptom:** MCP client shows server unresponsive or connection refused. **Resolution Steps:** @@ -31,12 +31,12 @@ This page collects frequently asked questions when using SUN MCP Server and thei ``` 3. **Check JSON Format** - - Verify JSON format of `stdio.json` in Claude Desktop configuration + - Verify JSON format of `stdio.json` in MCP client configuration - Common errors: trailing commas, unmatched brackets -4. **Restart Claude Desktop** +4. **Restart MCP client** - Completely close application - - Clear cache: delete temporary files in `~/.claude` directory + - Clear client cache (method depends on your specific MCP client) - Restart application 5. **Check Server Logs** @@ -97,7 +97,7 @@ This page collects frequently asked questions when using SUN MCP Server and thei export TRON_MNEMONIC="word1 word2 ... word12" ``` -4. **Restart server** and reconnect Claude Desktop +4. **Restart server** and reconnect MCP client Verify successful configuration by checking [Full Capability List](ToolList.md) for Full Capability List. @@ -396,7 +396,7 @@ Check transaction hash details on https://tronscan.org for error message **Yes.** For example, can run official mainnet server and local Nile instance simultaneously. -**Configuration Example (Claude Desktop):** +**Configuration Example (MCP client):** ```json { diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index a61b249c..d93472e7 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Local Privatized Deployment ## What is Local Privatized Deployment? @@ -166,121 +163,60 @@ sun-mcp-server --- -### Step 3: Client Configuration - -After configuration is complete, you need to add the connection definition of SUN MCP Server in your AI client. - -#### Find Configuration File - -Depending on your AI client, the configuration file location is as follows: +### Step 3: Server Running Methods -| Client | Configuration File Path | -|--------|-------------| -| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | -| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | -| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` or via environment variable | +After wallet configuration is complete, you can run the server using one of the following methods: -#### Add Server Definition +### Option A: Run directly with npx (Recommended) -Choose the tab corresponding to your deployment method: - - - - -**Claude Desktop Configuration:** +The simplest and quickest method, no installation or cloning needed. -Add to `~/.claude/resources/mcp/servers.json`: +**Command:** -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_NETWORK": "nile" - } - } - } -} +```bash +npx -y @bankofai/sun-mcp-server ``` -**Claude Code** +**Description:** +- `npx` automatically downloads the latest version of `@bankofai/sun-mcp-server` +- `-y` flag automatically confirms prompts +- First run may take a few seconds to download -```bash -# Basic -claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server +**Run with environment variables:** -# With environment variables -claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server +```bash +TRON_NETWORK=nile npx -y @bankofai/sun-mcp-server ``` -**Cursor Configuration:** - -Add to `~/.cursor/extensions/mcp/servers.json`: - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` +### Option B: Clone from Source - +Suitable for development and custom modifications. - +**Steps:** -For running from source code. +```bash +# 1. Clone repository +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server -**Claude Desktop Configuration:** +# 2. Install dependencies +npm install -Add to `~/.claude/resources/mcp/servers.json`: +# 3. Build project +npm run build -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_NETWORK": "nile" - } - } - } -} +# 4. Run server +npx tsx src/index.ts ``` -**Cursor Configuration:** - -Add to `~/.cursor/extensions/mcp/servers.json`: - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` +**Or install globally:** - +```bash +npm install -g @bankofai/sun-mcp-server +sun-mcp-server +``` - +### Option C: HTTP Mode Run SUN MCP Server in HTTP server mode, allowing remote connections. @@ -290,39 +226,12 @@ Run SUN MCP Server in HTTP server mode, allowing remote connections. sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -**Claude Desktop Configuration:** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - -**Cursor Configuration:** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - :::warning HTTP mode is suitable for local development and testing. For remote deployment, use HTTPS and appropriate authentication. ::: - - - :::tip About Environment Variables -- **npx Run**: Environment variables are set in the `"env"` field of the configuration file, or exported directly in the terminal before running. +- **npx Run**: Export environment variables directly in the terminal before running the command. - **HTTP Mode**: When starting the HTTP server, environment variables should be exported before the startup command: ```bash @@ -330,12 +239,21 @@ export TRON_NETWORK=nile sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -- **Restart Required**: After modifying configuration, you need to restart the AI client for changes to take effect. +- **Server Configuration**: Once the server is running, configure your MCP client to connect to it. ::: --- -### Step 4: Verify Connection +### Step 4: Client Configuration + +After the server is running, you need to configure your MCP client to connect to it. Refer to your MCP client's documentation for configuration instructions. The server will be accessible at one of the following: + +- **npx/Local Build**: Typically runs as a subprocess managed by your client +- **HTTP Mode**: `http://127.0.0.1:8080/mcp` (or the host/port you specified) + +--- + +### Step 5: Verify Connection After starting the AI client, you should be able to see the tool list of SUN MCP Server. Perform the following tests to confirm the configuration is correct: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 4aa271a2..3ff3e4e3 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Official Cloud Service Access ## What is the Official Cloud Service? @@ -41,69 +38,6 @@ Add the following MCP service endpoint to your AI client configuration: ## Client Configuration - - - -Configuration file path: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -**Basic Config**: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - -**Add via command line**: - -```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp -``` - -**Or add `.mcp.json` to your project root**: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "type": "http", - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -Add `.cursor/mcp.json` to your project root: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - If you want to integrate SUN MCP Server into your own application, you can call it via standard HTTP requests. **Step 1: Initialize Connection** @@ -167,9 +101,6 @@ curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session ::: - - - --- ## Verify Connection diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index ba07ff4e..3b07cca9 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Quick Start The goal of this page is simple: **get you integrated and make your first DeFi query in just 1 minute.** @@ -14,69 +11,19 @@ We'll use the [official cloud service](./OfficialServerAccess.md) for this quick Before you get started, make sure you have: 1. **Node.js** >= 20.0.0 ([download link](https://nodejs.org/)) -2. **MCP Client**: Any AI client that supports MCP. For example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). +2. **MCP Client**: Any AI client that supports MCP. --- -## Add Configuration - -Choose the configuration method that matches the tool you're using: - - - - -1. Open the Claude Desktop configuration file: - - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -2. Add the following configuration in the `mcpServers` section: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. Save the file and restart Claude Desktop. - - - - +## Install Run the following command in the terminal to add SUN MCP Server: ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp -``` - - - - - -1. Open the Cursor configuration file: `.cursor/mcp.json` - -2. Add the following in the configuration: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} +npx add-mcp @bankofai/sun-mcp-server ``` -3. Save the file and restart Cursor. - - - +After the command completes, restart your MCP client. --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 689eed9d..27c662e0 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -8,7 +8,7 @@ When you encounter problems, check here first. Organized by the order you're mos Connection issues usually occur during the initial configuration phase. If your AI client can't recognize the TRON tools, this is likely where the problem is. -### "Failed to connect to MCP server" in Claude Desktop +### "Failed to connect to MCP server" in your MCP client This is the most common issue. Troubleshoot in the following order: @@ -20,15 +20,11 @@ This is the most common issue. Troubleshoot in the following order: 2. **Check that npx is available**. Run `npx --version` in your terminal. If the command is not found, your Node.js installation is incomplete — reinstall it. -3. **Verify config file format**. `claude_desktop_config.json` must be valid JSON. Common mistakes include trailing commas, missing quotes, or mismatched brackets. Quickly validate with: - ```bash - cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool - ``` - If formatted JSON is printed, the format is fine. If there's an error, fix it according to the message. +3. **Verify config file format**. Your MCP client configuration file must be valid JSON. Common mistakes include trailing commas, missing quotes, or mismatched brackets. Validate your configuration file using a JSON validator. -4. **Fully quit and restart**. Closing the window is not the same as quitting — you need to fully exit Claude Desktop from the menu bar/system tray, then reopen it. On macOS, right-click the Dock icon and choose "Quit". +4. **Fully quit and restart**. Closing the window is not the same as quitting — you need to fully exit your MCP client, then reopen it. -5. **Check logs**. If none of the above resolves the issue, check Claude Desktop's log files. On macOS they're in `~/Library/Logs/Claude/` — search for entries containing "mcp" or "tron". +5. **Check logs**. If none of the above resolves the issue, check your MCP client's log files for entries containing "mcp" or "tron". ### "Connection refused" in HTTP mode @@ -191,25 +187,7 @@ Always develop and test on Nile first, then execute on Mainnet after confirming ### Can I use multiple TRON MCP Servers simultaneously? -Yes. Define multiple MCP Server entries in your config — for example, one connecting to the mainnet cloud service (read-only) and another connecting to a local testnet deployment (with wallet). Just use different names: - -```json -{ - "mcpServers": { - "tron-mainnet": { - "command": "npx", - "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] - }, - "tron-local": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "your-password" - } - } - } -} -``` +Yes. Define multiple MCP Server entries in your MCP client configuration — for example, one connecting to the mainnet cloud service (read-only) and another connecting to a local testnet deployment (with wallet). Configure both servers with different names in your client's MCP configuration. ### How do I update to the latest version? diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md index 054efd9c..f79c1f28 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -8,7 +8,7 @@ For example: just tell Claude "Check how much USDT this address has", and the AI This means different things to different people: -- If you are an **AI application user**, it lets you operate blockchain directly in Claude Desktop, Cursor, and other tools — as easy as everyday chat. +- If you are an **AI application user**, it lets you operate blockchain directly in MCP-compatible AI tools — as easy as everyday chat. - If you are a **Web3 developer**, it's your rapid on-chain prototyping tool — debug contracts and query state in natural language, saving vast amounts of boilerplate code. - If you are an **AI Agent builder**, it provides 95 standardized on-chain tools that can be orchestrated directly into your automation workflows. - If you are a **data analyst**, it turns on-chain data queries into conversation — no more writing scripts to scrape and parse. @@ -82,7 +82,7 @@ Specify the target network via the `network` parameter when calling tools, e.g., :::warning Before getting started, keep these security principles in mind — especially for operations involving real assets: -- **Never hardcode private keys**: Do not write private keys or mnemonic phrases directly in configuration files (such as `claude_desktop_config.json`). Use system environment variables or an encrypted wallet instead. +- **Never hardcode private keys**: Do not write private keys or mnemonic phrases directly in configuration files. Use system environment variables or an encrypted wallet instead. - **Test on testnet first**: Always run through and verify on Nile or Shasta testnets before performing any operation on Mainnet. - **Minimum funds principle**: The wallet configured for AI agents should only hold the minimum funds required for the task. - **Pay attention to authorization risks**: Be especially cautious with token approval (`approve`) operations — avoid granting unlimited authorization. diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index a411d406..215e0a51 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Local Private Deployment ## What is Local Private Deployment? @@ -46,7 +43,7 @@ node --version # Should output v20.x.x or higher Before configuring your wallet, make sure to understand the following security principles: :::danger Security Warning -**Never** save private keys or mnemonic phrases directly in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`). These files are often unencrypted and could be accidentally shared or committed to Git. Always use system environment variables or encrypted wallets. +**Never** save private keys or mnemonic phrases directly in MCP configuration files. These files are often unencrypted and could be accidentally shared or committed to Git. Always use system environment variables or encrypted wallets. ::: --- @@ -158,149 +155,28 @@ npm install npm run build ``` ---- - -### Step 4: Client Configuration - -With environment variables set and installation done, now point your AI client to the local server. - -#### Find Your Configuration File - -| Application | Operating System | Configuration Path | -| :--- | :--- | :--- | -| **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Cursor** | All | Project root: `.cursor/mcp.json` | -| **Google Antigravity** | All | `~/.config/antigravity/mcp.json` | -| **Opencode** | All | `~/.config/opencode/mcp.json` | - -#### Add Server Definition +#### Option C: Run in HTTP Mode - - - -Run the latest version directly from npm. No need to clone any repository. - -**Claude Desktop** (`claude_desktop_config.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - -**Claude Code**: +Start the server in HTTP mode, then connect your MCP client via the HTTP endpoint: ```bash -# Basic -claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron - -# With environment variables -claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron +npm run start:http ``` -**Cursor** (`.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` +This will start a local HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. - - - -For developers running from a cloned repository. - -**Claude Desktop** (`claude_desktop_config.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - -Replace the path with your actual cloned repository path. - -**Cursor** (`.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - } - } - } -} -``` - - - +#### Configuration Notes -If you started the server in HTTP mode (`npm run start:http`), connect via HTTP URL: +If you're configuring an MCP client to point to your local server: -**Claude Code**: - -```bash -claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp -``` +- **If running via npx or source**: Use the appropriate command in your MCP client's configuration (e.g., `command: npx` with `args: ["-y", "@bankofai/mcp-server-tron"]`) +- **If running in HTTP mode**: Point your client to `http://localhost:3001/mcp` via the HTTP URL configuration option -**Cursor** (`.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "http://localhost:3001/mcp" - } - } -} -``` - - - - -:::tip About the `env` Section in Configuration -If you have already set environment variables in your system (via `~/.zshrc` or `~/.bashrc`), you can omit the `env` section from the configuration entirely — the server will automatically read system environment variables. - -If your MCP client does not inherit system environment variables, you'll need to set them in the `env` section. In that case, **make sure the configuration file is never shared or committed to version control**. -::: +If your MCP client does not inherit system environment variables, you'll need to configure them explicitly in the client settings. **Make sure any configuration file storing credentials is never shared or committed to version control**. --- -### Step 5: Verify Connection +### Step 4: Verify Connection After completing configuration, **fully exit and restart** your AI client, then try: diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index f560cab3..67f8ae12 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Official Cloud Service Access ## What is the Official Cloud Service? @@ -96,90 +93,7 @@ After configuring the API Key, your requests will go through TronGrid's authenti ## Client Configuration - - - -Configuration file path: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -**Basic Config (No API Key)**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - -**Config with TronGrid API Key**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} -``` - -Replace `` with your actual TronGrid API Key. - - - - -**Command line:** - -```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp -``` - -**Or add `.mcp.json` to your project root**: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "type": "http", - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -Add the following to your project root `.cursor/mcp.json`: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -If you want to integrate TRON MCP Server into your own application, you can call it via standard HTTP requests. +You can connect to the official cloud service via HTTP requests. Here's how: **Step 1: Initialize Connection** @@ -221,6 +135,25 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` +To use a TronGrid API Key with the cloud service, add the header: + +```bash +curl -X POST https://tron-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -H "TRONGRID-API-KEY:your-api-key" \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "get_chain_info", + "arguments": {"network": "mainnet"} + }, + "id": 2 + }' +``` + **Step 3: Discover Available Tools** ```bash @@ -242,9 +175,6 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session ::: - - - --- ## Verify Connection diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index 1aeda6bb..9d4141d7 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Quick Start The goal of this page is simple: **get you connected in 1 minute and make your first blockchain query.** @@ -13,7 +10,7 @@ We'll use the [official cloud service](./OfficialServerAccess.md) for this quick Before you begin, make sure you have the following installed: -- Any AI client that supports MCP: for example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). +- Any AI client that supports MCP - **Node.js v20.0.0 or higher** (needed for `npx` command execution) ([Node.js Download](https://nodejs.org/)) Verify your Node.js version: @@ -26,57 +23,13 @@ node --version # should output v20.x.x or higher ## Add Configuration -Choose your AI client and copy in the corresponding configuration: - - - - -Open your configuration file: -- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - -Add the following content: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - Run the following command in your terminal: ```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp -``` - - - - -Add the following to your project root `.cursor/mcp.json`: - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} +npx add-mcp @bankofai/mcp-server-tron ``` - - +After the command completes, restart your MCP client. --- diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 8d7642d5..f23b9622 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -60,7 +60,7 @@ Head over to **[Quick Start](./QuickStart.md)** — it takes about 1 minute. Com --- -## sunswap — Swap Tokens, Check Prices, Manage Pools +## sunswap — Swap Tokens, Check Prices, Manage Pools {#sunswap} Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. @@ -92,7 +92,7 @@ Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the --- -## sunperp-skill — Perpetual Contract Trading +## sunperp-skill — Perpetual Contract Trading {#sunperp-skill} Want to trade contracts? This skill handles market data, opening/closing positions, stop-loss, and withdrawals. Built-in safety: max 20x leverage, mandatory stop-loss — if losses exceed 5%, the AI automatically closes your position to prevent liquidation. @@ -122,7 +122,7 @@ Want to trade contracts? This skill handles market data, opening/closing positio --- -## tronscan-skill — On-Chain Data Detective +## tronscan-skill — On-Chain Data Detective {#tronscan-skill} Want to know what's happening on-chain? This skill looks up accounts, transactions, tokens, blocks, and network stats. **Pure read-only, completely safe, costs nothing, needs no credentials.** The perfect first skill to get started. @@ -146,7 +146,7 @@ Want to know what's happening on-chain? This skill looks up accounts, transactio --- -## x402-payment — On-Chain "Pay-First" Auto-Settlement +## x402-payment — On-Chain "Pay-First" Auto-Settlement {#x402-payment} Some APIs and AI agents require on-chain payment before use. This skill uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — the AI detects the charge, completes the on-chain payment, gets the result, and reports back. It always asks for your confirmation before paying. @@ -156,7 +156,7 @@ Some APIs and AI agents require on-chain payment before use. This skill uses the --- -## recharge-skill — BANK OF AI Account Management +## recharge-skill — BANK OF AI Account Management {#recharge-skill} Check your balance, view order history, or top up your account. diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 89de4e95..eef6b17f 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -59,36 +59,46 @@ No. Skills use an **on-demand, lightweight architecture** — the AI only loads Five core skills covering the most common scenarios in the TRON ecosystem. Each one comes with a ready-to-use sample prompt — copy it into your AI chat and hit enter to try it out. -### 💱 Your Personal DEX Trader +### 💱 Execute DEX Trades -Check prices, compare rates, even swap tokens in one go. Like having a personal trader on call. +Check prices, compare rates, even swap tokens in one go. > 🗣️ "How much TRX can I get for 100 USDT on SunSwap right now?" -### 📈 Perpetual Contract Safety Officer +💡 For more advanced features, see: [**sunswap** (DEX Trading Guide)](./BANKOFAISkill.md#sunswap) + +### 📈 Trade Perpetual Contracts View market data, open and close positions on SunPerp. Built-in safety lock: max 20x leverage, mandatory stop-loss on every position — keeps you from blowing up your account. > 🗣️ "What's BTC's funding rate right now? Open a 5x long position with a 5% stop-loss." -### 🕵️ On-Chain Data Detective +💡 For more parameter settings, see: [**sunperp-skill** (Perpetual Contract Safety Officer)](./BANKOFAISkill.md#sunperp-skill) + +### 🕵️ Query On-Chain Data Look up accounts, transactions, and check if a new token is legit. Pure read-only, completely safe, costs nothing. > 🗣️ "Check the holder distribution for that new token — is it controlled by a whale?" -### ☕ On-Chain "Pay-First" Auto-Settlement +💡 For more query dimensions, see: [**tronscan-skill** (On-Chain Data Detective)](./BANKOFAISkill.md#tronscan-skill) + +### ☕ Auto-Settle On-Chain Paid Services When the AI needs to call a paid on-chain service or data API, it uses the x402 protocol to automatically complete "pay first, then receive" on-chain settlement — no manual QR scanning or wallet switching needed. > 🗣️ "Use the x402 protocol to call this paid agent endpoint: https://api.example.com" (replace with the actual paid endpoint URL you want to call) -### 🏦 BANK OF AI Account Manager +💡 For payment and authorization details, see: [**x402-payment** (On-Chain Auto-Settlement)](./BANKOFAISkill.md#x402-payment) + +### 🏦 Manage BANK OF AI Account Check your BANK OF AI balance and top up with a single sentence. > 🗣️ "How much balance do I have? Go ahead and recharge 5 USDT." +💡 For top-up and withdrawal rules, see: [**recharge-skill** (Account Manager)](./BANKOFAISkill.md#recharge-skill) + --- ## 🎯 Are These Skills Right for Me? diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md index 9666845f..b1a5ea6e 100644 --- a/docs/Openclaw-extension/FAQ.md +++ b/docs/Openclaw-extension/FAQ.md @@ -1,219 +1,93 @@ -# FAQ & Troubleshooting +# FAQ -When you encounter problems, check here first. Organized by the most likely issues you'll encounter: installation problems, connection issues, credential problems, runtime problems, and finally some general questions. +Don't panic when you see an error — it's usually just a small setting that's not configured properly. We've listed the most common issues in order of frequency: --- -## Installation Problems +## Errors During Installation -### Installer reports error "command not found: node" +### Error Says "command not found: node" or "npm install Failed" -The installer requires Node.js v18.0.0 or higher. Check if it's installed: +**Plain English**: Your computer doesn't have Node.js installed, or the version is too old. -```bash -node --version -``` +**How to fix**: Go to the [Node.js official website](https://nodejs.org/) and download the latest stable version (LTS, v20 or higher recommended). Install it like any regular software by clicking "Next" all the way through. Then close the terminal window and run the installation command again. -If not installed or version is too old, download and install the latest LTS version from [nodejs.org](https://nodejs.org/). After installing Node.js, the `npx` command will also be available. +### Error Says "command not found: python3" -### Installer reports error "command not found: python3" +**Plain English**: Your computer is missing a basic runtime environment called Python. -The installer uses Python to process JSON configuration files. macOS typically comes with Python 3; on Linux, install via package manager: +**How to fix**: Go to the [Python official website](https://www.python.org/downloads/) and download and install it. -```bash -# Ubuntu/Debian -sudo apt install python3 +### AgentWallet (AI Vault) Installation Failed -# macOS (via Homebrew) -brew install python3 -``` +**How to fix**: -### Installer warning "OpenClaw not found" - -The installer detected that `~/.openclaw` directory doesn't exist. This means OpenClaw might not be installed or was installed in a non-standard location. - -The installer will ask if you want to continue — you can choose to proceed (MCP Servers and Skills will still be configured), but OpenClaw may not auto-load them on startup. Recommend first completing installation from the [OpenClaw official repository](https://github.com/openclaw). - -### Skills clone failed - -If `git clone` fails, common causes include: - -- **Network issues**: Check if you can access GitHub. Try `git clone https://github.com/BofAI/skills.git` to test manually. -- **Git not installed**: Run `git --version` to confirm. -- **Specified branch/tag doesn't exist**: If you set the `GITHUB_BRANCH` environment variable, confirm the branch or tag actually exists. - -Skills clone failure won't interrupt the entire installation — MCP Server configuration remains intact. You can install Skills manually later. - -### npm install failed - -When installing Skills, some Skills (like sunswap, x402-payment) need to run `npm install` to install dependencies. If it fails: - -- Check network connectivity (npm needs to access registry.npmjs.org) -- Confirm Node.js version >= 18 -- Try running manually: - ```bash - cd ~/.openclaw/skills/sunswap # or other Skill directory - npm install - ``` - -npm install failure won't interrupt the installer — it will issue a warning but continue. That Skill's functionality may be limited until dependencies are successfully installed. - ---- - -## Connection Issues - -### Can't see blockchain tools in OpenClaw after startup - -**Most common cause**: OpenClaw wasn't restarted. After modifying mcporter.json, you must completely exit and restart OpenClaw. - -If you still can't see them after restarting: - -1. **Check mcporter.json format**: - ```bash - python3 -m json.tool ~/.mcporter/mcporter.json - ``` - If there's a JSON syntax error, fix the format issues and restart. - -2. **Check mcporter.json contents**: Confirm there are Server entries under `mcpServers` for what you installed. - -3. **Manually test MCP Server**: - ```bash - npx -y @bankofai/mcp-server-tron - ``` - If this command starts normally (shows logging output), the MCP Server itself is fine; the issue is in OpenClaw's configuration reading. - -### Only query tools available, no write tools like transfers - -This is by design. Write tools only appear after wallet credentials are configured. Check if any of these are set: - -- Environment variable `TRON_PRIVATE_KEY` (mcp-server-tron) -- Environment variable `PRIVATE_KEY` (bnbchain-mcp) -- `env.TRON_PRIVATE_KEY` or `env.PRIVATE_KEY` for corresponding Server in mcporter.json - - -### MCP Server startup timeout - -If OpenClaw times out starting an MCP Server, it may be that npx is downloading packages too slowly. The first run downloads packages from npm, which can take tens of seconds. - -Speed this up by pre-downloading: - -```bash -npx -y @bankofai/mcp-server-tron --help -npx -y @bnb-chain/mcp@latest --help -``` - -After downloading completes, subsequent startups will use cache and be much faster. +1. Double-check that your Node.js version is new enough. +2. Sometimes it's simply a network timeout — wait a couple of minutes and run the installation command again. +3. If it keeps getting stuck, try manually deleting the `~/.agent-wallet` folder and starting over from scratch. --- -## Credential Issues - -### "Invalid private key" error - -**TRON private key** should be a 64-character hexadecimal string, with or without `0x` prefix. +## Installation Finished, But AI Acts Clueless -**EVM private key** should have `0x` prefix. The installer automatically adds `0x` to private keys without it, but if you manually edit config files, ensure the format is correct. +### AI Says "I Don't Have Blockchain Tools" or "I Don't Know What SunSwap Is" -Common mistakes: -- Extra spaces, newlines, or quote nesting -- Invisible characters when copying from elsewhere +**Most likely cause**: You were too eager after installation and **didn't restart the OpenClaw software**. -Validation: Import the private key into the appropriate wallet (TronLink or MetaMask) to confirm validity. +**How to fix**: Completely quit OpenClaw (on Mac press `Command+Q`), then reopen it so the AI can reload its new brain. -### TronGrid API Key not working +### AI Can Fetch Data, But Answers Are Messy and Often Wrong? -1. **Is variable name correct?**: Must be `TRONGRID_API_KEY` (not `TRON_API_KEY`) -2. **Is Key still valid?**: Log in to [trongrid.io](https://www.trongrid.io/) to check status -3. **Is it properly loaded?**: If set in environment variables, confirm you ran `source ~/.zshrc` +**Most likely cause**: The underlying AI model version you're using is too weak. It's like asking a grade-schooler to do high school math — it's not that they're not trying, they just don't have the capacity. +**How to fix**: Open OpenClaw settings and upgrade to a more powerful model version. The stronger the model, the more accurately AI understands your commands and the fewer mistakes it makes when calling tools. -### BANK OF AI API Key invalid +### Why Can Others Send Transfers While My AI Can Only Read Data? -Check contents of `~/.mcporter/bankofai-config.json` (or `~/.bankofai/config.json`): +**Reason**: Your AI is currently in ultra-safe "read-only mode." This is because you skipped the AgentWallet configuration during installation and didn't provide it with wallet keys. -```bash -cat ~/.mcporter/bankofai-config.json -``` - -Confirm the `api_key` field contains a valid Key. Note that recharge-skill has a credential priority order (CLI arguments > environment variables > `bankofai-config.json` in working directory > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`); if you set different values in multiple places, you might read the unexpected one. +**How to fix**: Run the installation script again. At the AgentWallet setup level, follow the prompts carefully to properly configure your wallet. After configuring and restarting, transfer and trading functions will be activated. --- -## Runtime Problems - -### Rate limiting (429 errors) - -Mainnet's public RPC has strict rate limits. Solutions: - -- **Configure TronGrid API Key**: After free registration, set `TRONGRID_API_KEY`, significantly increasing quota -- **Use testnet**: Nile and Shasta testnets have fewer restrictions -- **Reduce concurrent queries**: In prompts, avoid having the AI execute large numbers of queries simultaneously - -### Skill execution failed +## Passwords and Security Concerns -If a Skill errors, troubleshoot in this order: +### Private Key Was Entered Wrong or Error Says "Invalid Private Key" -1. **Check if dependencies are installed**: - ```bash - cd ~/.openclaw/skills/ - npm install # if there's package.json - ``` +**Reason**: The current installer uses AgentWallet to manage wallets, so you generally don't need to manually enter private keys anymore. However, if you're using the BNB Chain toolbox (bnbchain-mcp) and manually configuring a private key, you might have accidentally copied an extra space or line break. -2. **Check Node.js version**: Some Skills require >= 18.0.0. +**How to fix**: Carefully copy it again. EVM (BNB/Ethereum) private keys should start with `0x` — if you're manually editing the file, make sure you don't miss that prefix. -### Transaction failed +### AI Reports "Rate Limited" or "429 Error" -Common reasons for on-chain transaction failures: +**Plain English**: You're making AI query data too fast, and the free network channel thinks you're a bot and temporarily blocked you. -- **Insufficient balance**: TRX balance doesn't cover gas fees (bandwidth/energy) -- **Insufficient energy**: Smart contract calls (including TRC20 transfers) consume energy -- **Account not activated**: New TRON addresses need to receive one TRX first to activate -- **Insufficient approval**: TRC20 token transfers may require prior approval +**How to fix**: -Use mcp-server-tron's `get_transaction_info` tool to see the specific reason for transaction failure. +1. **Quick fix**: Wait a few minutes before asking again. +2. **Permanent fix**: Go to [TronGrid](https://www.trongrid.io/) and apply for a free dedicated API Key. Enter this key during installation, and AI will be able to use the VIP express lane. --- -## General Questions - -### Can I install only some components? - -Yes. The installer lets you selectively install at each stage. For example, you can install only mcp-server-tron without other MCP Servers, or only sunswap Skill while skipping others. - -### Can I run the installer multiple times? - -Yes. The installer uses deep merge strategy for mcporter.json and won't overwrite existing configurations. For Skills, if a Skill with the same name already exists at the target location, it will ask if you want to overwrite. - -### How do I completely uninstall? +## Tinkering Freely (Uninstall & Reinstall) -OpenClaw Extension has no automatic uninstaller. Manual uninstall steps: +### Can I Install Just One Skill Without the Others? -1. **Remove MCP Server configuration**: Edit `~/.mcporter/mcporter.json`, remove corresponding Server entries -2. **Delete Skills**: Delete Skill folders in installation directory (default `~/.openclaw/skills/`) -3. **Delete credential files**: - ```bash - rm -f ~/.x402-config.json - rm -f ~/.mcporter/bankofai-config.json - rm -f ~/.bankofai/config.json - rm -f ~/.clawdbot/wallets/.deployer_pk - ``` -4. **Clean environment variables**: Remove related export statements from `~/.zshrc` or `~/.bashrc` +Absolutely! When the installation wizard reaches Level 4, it will list all skills. Just use the Space key to check only the ones you want, leave the rest unchecked, and press Enter to confirm. -### Which operating systems are supported? +### I'm Done With It — How Do I Uninstall? -The installer is a Bash script supporting: -- **macOS** (Intel and Apple Silicon) -- **Linux** (Ubuntu, Debian, CentOS, etc.) -- **Windows**: Requires WSL (Windows Subsystem for Linux) to run +The simplest brute-force method: Open your file manager, find the `~/.openclaw/skills/` directory, delete the skill folder(s) you no longer want, then restart the AI software — they'll be completely gone. -### What's the difference from TRON MCP Server's official cloud service? +### I Messed Everything Up — Can I Reinstall? -The [official cloud service](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md) is a remote-hosted read-only MCP Server, requiring no local installation. OpenClaw Extension runs the MCP Server locally, and with private keys configured, unlocks full read-write capabilities. +Reinstall anytime! Don't worry about breaking your computer. -If you only need to query on-chain data, cloud service is simpler. If you need transfers, contract writes, or want to use Skills (like SunSwap trading), you need OpenClaw Extension. +- **Option 1 (Normal installation)**: Run the script again and it will automatically patch whatever's missing. +- **Option 2 (Clean install)**: If you want to start completely from scratch, choose this one. It will wipe all your old toolboxes, skills, and configurations clean, giving you a fresh new environment. To prevent accidental triggers, it will ask you to manually type `CLEAN` to confirm. --- -## Next Steps +## Still Can't Figure It Out? -- Start fresh → [Quick Start](./QuickStart.md) +👉 Go back to **[Quick Start](./QuickStart.md)** and follow along from step one again — that usually solves 99% of the problems. diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index d4814867..b0756b3e 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -1,62 +1,60 @@ # Introduction -## What is OpenClaw Extension? +Make your AI understand blockchain with one click. -OpenClaw Extension is a toolkit developed by **BANK OF AI** that equips [OpenClaw](https://github.com/openclaw) (an open-source AI assistant) with **blockchain interaction capabilities**. Once installed, your AI assistant can directly manage on-chain assets — check balances, initiate transfers, invoke smart contracts, and swap tokens on DEXs — all through natural language conversation. +Have you ever wished that checking on-chain data, swapping tokens, or viewing balances didn't require opening dozens of web pages or staring at complex apps? -Traditionally, enabling an AI to interact with blockchain requires you to manually set up MCP Servers, manage configuration files, and install various tools individually. OpenClaw Extension packages all of this into an interactive installer — run one command, follow the prompts to select the components you need, and within minutes your AI assistant will have multi-chain operation capabilities. +All you need to do is send a simple message — just like chatting with a friend — and let your AI assistant handle all the heavy lifting. + +**OpenClaw Extension is the "one-click installer" that makes this magic happen.** --- -## Core Vision +## How Does the Magic Work? -OpenClaw Extension aims to build a financial infrastructure for the AI agent economy — enabling every AI agent with independent financial capabilities: +Previously, AI was just a "know-it-all" that could only talk the talk. To make it actually do things for you, our installer equips it with two core weapons: -- **Earn Revenue**: Receive payments for tasks and services through standard interfaces like the x402 protocol -- **Autonomous Spending**: Independently pay for compute, data, and storage resources -- **Agent Interconnection**: Facilitate direct financial transactions and settlements between agents (A2A) -- **DeFi Interaction**: Seamlessly interact with decentralized finance protocols and smart contracts +### 🛠️ 1. Toolbox (MCP Server) — Giving AI "Hands" ---- +This is the cable that connects AI to the blockchain. Once installed, AI gains the ability to directly read from and write to the blockchain. -## What Does It Include? +Currently supported: -OpenClaw Extension consists of two main categories of components: **MCP Servers** and **Skills**. You can choose which components to enable at installation time. +- **TRON Toolbox**: Check balances, send transfers, and interact with the TRON ecosystem. +- **BNB Chain Toolbox**: Supports multi-chain operations on BSC, Ethereum, and more. +- **Top-up Assistant**: Helps you remotely top up your BANK OF AI account. -### MCP Server — On-Chain Operation Capabilities +### 🧠 2. Skill Packs (Skills) — Giving AI a "Brain" -MCP Servers are bridges between your AI assistant and the blockchain, providing on-chain operation capabilities through the [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) standard interface. Currently supports MCP Servers for two blockchain chains plus one remote recharge service: +Having hands isn't enough — AI needs to know how to handle tasks step by step. Skill packs are the pre-written "recipes" we've prepared. -| MCP Server | Target | Core Capabilities | -| :--- | :--- | :--- | -| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | -| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | -| **bankofai-recharge** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | +For example, the **"sunswap" skill** teaches AI: "When the user wants to swap tokens, first check the price, then calculate the fees, and finally send the bill to the user for confirmation — never spend money recklessly." -### Skills — Pre-built Workflows +--- -Skills are encapsulated business process templates. Unlike individual tools provided by MCP Servers, a single Skill can chain multiple operations together to complete complex tasks — for example, "swap tokens on SunSwap" involves checking prices, verifying balances, executing the swap, and confirming results, all handled by one Skill. +## 🌟 How Great Is the Experience After Installation? -| Skill | Functionality | -| :--- | :--- | -| **sunswap** | SunSwap DEX trading including balance queries, quotes, swaps, and liquidity management | -| **sunperp-skill** | SunPerp perpetual futures trading — market data, orders, positions, leverage, withdrawals | -| **tronscan-skill** | Query on-chain data via TronScan API (accounts, transactions, tokens, blocks, network statistics) | -| **x402-payment** | x402 payment skill for calling paid agents and APIs | -| **recharge-skill** | BANK OF AI balance and order queries, plus TRC20 recharge via MCP | +Once installed, your AI instantly transforms into an incredibly professional personal Web3 assistant. Try giving it commands like these: +> **"Check if TRON energy fees are expensive right now."** +> +> **"How much TRX can I get for 100 USDT on SunSwap? Is it worth it after fees?"** +> +> **"How much balance is left in my wallet? Also check my holdings of that meme coin from yesterday."** + +It will chew through all the boring code and data and serve it up to you in plain language. --- -## Who Should Use This? +## Is This for Me? -- **OpenClaw Users**: Want your AI assistant to interact directly with blockchain without manually setting up MCP Servers -- **Web3 Developers**: Need a quick on-chain development environment to debug contracts and query data using natural language -- **AI Agent Builders**: Need to equip automation agents with multi-chain operation capabilities -- **DeFi Users**: Want to use your AI assistant to trade on SunSwap or manage liquidity +- **I'm a beginner**: Perfect! If you don't want to deal with code and just want to use plain language to have AI help you check data and make trades, this was tailor-made for you. +- **I'm a Web3 veteran**: Tired of opening web pages and connecting wallets every day? Want a personal trading assistant on call 24/7? It can save you tons of time watching charts. --- -## Next Steps +## Can't Wait? + +Don't hesitate — the entire installation process is as simple as microwaving a meal, taking just a few minutes. -- Want to get started immediately? → [Quick Start](./QuickStart.md) +👉 **[Go to Quick Start and upgrade your AI!](./QuickStart.md)** diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md index 291c504b..722dcc1f 100644 --- a/docs/Openclaw-extension/QuickStart.md +++ b/docs/Openclaw-extension/QuickStart.md @@ -1,146 +1,146 @@ # Quick Start -The goal of this page is: **Get you up and running with a complete installation and your first blockchain query in just a few minutes.** - -The installer is interactive, guiding you to select which MCP Servers and Skills to install, then automatically completing all configuration. You just need to follow the prompts. +Our goal: **Spend a few minutes following the wizard, clicking a few buttons, and get your AI to successfully fetch its first piece of on-chain data.** --- -## Prerequisites +## 🕹️ Prerequisites -Before running the installer, ensure the following tools are ready: +Before you begin, make sure the following basic software is installed on your computer (if not, download and install them from their official websites just like any regular software): -| Requirement | Description | Verification Command | Download | -| :--- | :--- | :--- | :--- | -| **OpenClaw** | Your open-source AI assistant | Check if `~/.openclaw` directory exists | [OpenClaw official repository](https://github.com/openclaw) | -| **Node.js v18+** | Required to run MCP Servers | `node --version` | [Node.js official site](https://nodejs.org/) | -| **Python 3** | Used by installer to handle JSON configuration | `python3 --version` | [Python official site](https://www.python.org/downloads/) | -| **Git** | Clone Skills repository | `git --version` | [Git official site](https://git-scm.com/) | +1. **OpenClaw**: Your AI assistant software. +2. **Node.js** (must be v20 or above): The runtime environment for skill packs. *(Extremely important — older versions will definitely cause errors!)* +3. **Git**: A small tool used to download skill packs. +4. **Python 3**: A helper used by the installation wizard to process configuration files. --- -## Running the Installer +## 🚀 Step 1: One-Click Installation + +Open the "Terminal" on your computer (that black window). -### Method 1: One-Click Install (Recommended) +- **Mac:** Press `Command + Space`, type `Terminal` in the search box, and hit Enter. +- **Windows:** You'll need to install WSL (Windows Subsystem for Linux) first, then open the WSL terminal. + +**Copy the entire line below**, paste it into the terminal, and press Enter: ```bash curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash ``` -### Method 2: Install from Source +🚑 **First Aid: Got an error right after pressing Enter?** If the screen says `command not found: node` or `python3`, it means your computer is missing the prerequisites mentioned above. 👉 [Click here to see how to fix it](./FAQ.md#error-says-command-not-found-node-or-npm-install-failed) -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +If there are no errors, an English wizard will appear on screen. Think of it as a text-based mini-game with 4 levels: -Once started, the installer automatically checks environment dependencies (Node.js, npx, Git, Python). If any are missing, it will alert you immediately. +### 🟢 Level 1: Choose Installation Mode ---- +The screen will ask you which mode to use. Type `1` (normal installation) on your keyboard, then press Enter. This is the most hassle-free option and preserves your previous settings. -## Installation Process Details +### 🟢 Level 2: Configure "AI's Personal Vault" (AgentWallet) -The installer consists of two main phases, each with interactive selection at every step. +The wizard will automatically install a tool called AgentWallet, which securely stores your AI's wallet keys. -### Phase 1: Select and Configure MCP Servers +If you're a beginner, just close your eyes and press Enter all the way through — the default values are perfectly fine. -The installer displays all available MCP Servers and asks which ones you want to install: +(🚑 Got stuck with an error? 👉 [Click here to see how to fix AgentWallet installation failures](./FAQ.md#agentwallet-ai-vault-installation-failed)) -``` -📦 Available MCP Servers: - 1) mcp-server-tron - TRON blockchain interaction - 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) bankofai-recharge - Remote BANK OF AI recharge MCP +### 🟢 Level 3: Pick Your Toolbox (Give AI "Hands") -Select servers to install (e.g., 1,2,3 or 'all'): -``` +The screen will list options like TRON (mcp-server-tron). Use the `↑` `↓` arrow keys to move, press **Space** to check, and press **Enter** to confirm. -> **Note on bankofai-recharge**: This is a remote MCP that connects directly to `https://recharge.bankofai.io/mcp`. No local credentials are needed — the installer configures the endpoint automatically. +⚠️ **Heads up**: The wizard might suddenly ask you for an API Key! -For each selected server, the installer continues by asking how you want to store credentials: +- **What's that?** It's a VIP pass — having one means data queries won't be throttled. +- **I don't have one right now?** Just press Enter to skip! Leaving it blank is totally fine and won't affect your installation at all. -- **Option 1: Save to Configuration File** — Keys stored in plaintext in `~/.mcporter/mcporter.json`. Convenient but lower security. -- **Option 2: Use Environment Variables (Recommended)** — Keys read from system environment variables, not written to any files. +### 🟢 Level 4: Pick Your Skill Packs (Give AI a "Brain") -If you choose to save to a configuration file, the installer will ask for specific key values (private keys, API Keys, etc.). If you choose environment variables, the installer will tell you which variables need to be set. +The screen will list skills like sunswap (token swapping), tronscan (data lookup), etc. Use **Space** to check and **Enter** to confirm. -> **Tip**: If you just want to quickly experience the features, you can skip key configuration for now (just press Enter to leave it empty). Without a private key, the MCP Server will run in read-only mode, and you can still query on-chain data. +If you see any prompts asking for keys that you don't understand, just press Enter to skip them all. -### Phase 2: Select and Install Skills +When `Installation Complete!` lights up at the bottom of the screen — congratulations, you've passed all levels! -The installer clones the [Skills repository](https://github.com/BofAI/skills) from GitHub, automatically discovers all available Skills, and asks you to select: +--- + +## 🎉 Step 2: Restart and Witness the Magic + +After installation, there's one step you absolutely cannot skip: **Completely close your OpenClaw software, then reopen it.** + +🚑 **First Aid: AI acting clueless?** If it says "I don't know what SunSwap is," 99% of the time it's because you didn't restart. 👉 [Click here to see how to properly restart](./FAQ.md#ai-says-i-dont-have-blockchain-tools-or-i-dont-know-what-sunswap-is) + +Open the chat window and send your AI its first command: ``` -🔧 Available Skills: - 1) recharge-skill - BANK OF AI account query and recharge - 2) sunperp-skill - SunPerp perpetual futures trading (TRON) - 3) sunswap - SunSwap DEX trading skill - 4) tronscan-skill - TRON blockchain data lookup - 5) x402-payment - Agent payment protocol (x402) - -Select skills to install (e.g., 1,2,3 or 'all'): +Check the current block height on the TRON mainnet. ``` -Then choose the installation location: +If it thinks for a few seconds and then reports back a number — awesome! Your AI has successfully connected to the blockchain! -| Option | Path | Use Case | -| :--- | :--- | :--- | -| **User-level (Recommended)** | `~/.openclaw/skills/` | Shared across all projects | -| **Workspace-level** | `.openclaw/skills/` | Used only by current project | -| **Custom Path** | Directory you specify | Special requirements | +Try another one: + +``` +How much TRX can I get for 100 USDT on SunSwap right now? +``` -Some Skills have additional credential requirements, which the installer will prompt you for during installation: +--- -- **recharge-skill** — Requires BANK OF AI API Key (`BANKOFAI_API_KEY`) -- **sunperp-skill** — Requires SunPerp API keys (`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`) -- **tronscan-skill** — Prompts you to set `TRONSCAN_API_KEY` environment variable in your shell -- **sunswap** — Prompts to configure TRON private key (if not configured earlier) +*(That covers the beginner essentials. If you've got the hang of it, keep reading below 👇)* --- -## Verifying the Installation +## 🛠️ How to Add API Keys (VIP Pass) After Installation? -After installation completes, **restart OpenClaw**, then in your conversation, enter: +Totally get it! You were just browsing during installation and pressed Enter to skip everything. Now that you're comfortable, here's how to fill in your API Keys for the "VIP express lane": -``` -Check the current block height on TRON mainnet -``` +### Step 1: Figure Out Which "Key" You Need -If you receive a normal response showing the current block height, it means mcp-server-tron has been successfully connected. +| Key Name | What's It For? | Where to Get It for Free? | +| :--- | :--- | :--- | +| `TRONGRID_API_KEY` | Express lane for the TRON toolbox — without it you'll be throttled | Register for free at [trongrid.io](https://www.trongrid.io/) | +| `TRONSCAN_API_KEY` | Required for the TronScan data lookup skill | Apply for free at [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) | +| `BANKOFAI_API_KEY` | Used for topping up or checking balance on BANK OF AI | Get it after logging in at [chat.bankofai.io/key](https://chat.bankofai.io/key) | -You can also try: +### Step 2: Enter Your Keys into the System -``` -Check the TRX balance of TRON address TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -``` +Once you have the corresponding key, choose the simple method below based on its type. **Don't forget to restart OpenClaw after filling it in!** -``` -What are the current energy and bandwidth prices on TRON mainnet? -``` +#### 🔧 Type A Keys: Add to "Hidden Notepad" (For TRONGRID and TRONSCAN) -If all these queries return results normally, you're all set. +**🍎 Mac Users:** -:::info About Read-Only Mode -If you didn't configure a private key during installation, the MCP Server will run in read-only mode — all query operations (check balance, check transactions, check contract state, etc.) work normally, but transfer and contract write operations are unavailable. To unlock write capabilities, see [Configuration Reference](./Configuration.md). -::: +1. Type `open -e ~/.zshrc` in the terminal and press Enter. +2. At the bottom of the text editor that opens, paste these lines (keep the double quotes `""`): + ``` + export TRONGRID_API_KEY="paste_your_TronGrid_Key_here" + export TRONSCAN_API_KEY="paste_your_TronScan_Key_here" + ``` +3. Press `Command + S` to save and close, then reopen the terminal or restart OpenClaw for changes to take effect. ---- +**🪟 Windows (WSL) Users:** -## Having Problems? +1. Type `notepad.exe ~/.bashrc` in the terminal and press Enter. +2. At the bottom of the text editor that opens, paste the same lines: + ``` + export TRONGRID_API_KEY="paste_your_TronGrid_Key_here" + export TRONSCAN_API_KEY="paste_your_TronScan_Key_here" + ``` +3. Press `Ctrl + S` to save and close, then reopen the terminal or restart OpenClaw for changes to take effect. -If your AI assistant can't recognize blockchain tools after installation, common causes include: +#### 🔧 Type B Keys: One-Click Config File (For BANK OF AI) -- **OpenClaw not restarted** — Configuration changes require a full restart -- **Node.js version too old** — Ensure v18.0.0 or higher -- **mcporter.json format error** — You can check with `python3 -m json.tool ~/.mcporter/mcporter.json` +If you have this key, simply copy and run the following command in the terminal (remember to replace the placeholder with your actual key): -For more troubleshooting, see [FAQ & Troubleshooting](./FAQ.md). +**Configure BANK OF AI:** + +```bash +mkdir -p ~/.mcporter && echo '{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://api.bankofai.io/v1/"}' > ~/.mcporter/bankofai-config.json +``` --- -## Next Steps +## Still Stuck Somewhere? + +That's totally normal! Everyone's computer environment is different. -- Want to understand the detailed features of each MCP Server and Skill? → [Component Details](./Components.md) -- Want to configure private keys, API Keys, or security options? → [Configuration Reference](./Configuration.md) -- Having issues? → [FAQ & Troubleshooting](./FAQ.md) +Check out 👉 **[FAQ (Troubleshooting Guide)](./FAQ.md)** — we've already encountered and documented solutions for 99% of the weird issues out there. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md index a8f2f872..86978c0b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/Intro.md @@ -6,7 +6,7 @@ MCP Server 旨在为大型语言模型 (LLM) 与外部工具和数据源之间 MCP 遵循**客户端-服务器**架构，主要包含以下三个核心参与者： -* **MCP 主机**：通常是 AI 应用程序本身（例如 Claude Code 或 Claude Desktop）。它负责协调和管理一个或多个 MCP 客户端。 +* **MCP 主机**：通常是 AI 应用程序本身。它负责协调和管理一个或多个 MCP 客户端。 * **MCP 客户端**：由 MCP 主机为每个 MCP 服务器实例化。每个客户端维护与对应 MCP 服务器的专用连接，并从服务器获取上下文信息供主机使用。 * **MCP 服务器**：一个程序，负责向 MCP 客户端提供上下文数据。服务器可以是本地运行的（例如文件系统服务器），也可以是远程运行的（例如 TRON MCP/SUN MCP 服务器）。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 36d87241..4a820dd4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -9,9 +9,9 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi ## 连接问题 -### Claude Desktop "无法连接到 MCP 服务器" +### MCP 客户端 "无法连接到 MCP 服务器" -**症状：** Claude Desktop 显示服务器未响应或连接被拒绝。 +**症状：** MCP 客户端 显示服务器未响应或连接被拒绝。 **解决步骤：** @@ -31,12 +31,12 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi ``` 3. **检查 JSON 格式** - - 在 Claude Desktop 配置中验证 `stdio.json` 的 JSON 格式 + - 在 MCP 客户端 配置中验证 `stdio.json` 的 JSON 格式 - 常见错误：末尾多余逗号、未匹配的括号 -4. **重启 Claude Desktop** +4. **重启 MCP 客户端** - 完全关闭应用程序 - - 清除缓存：删除 `~/.claude` 目录中的临时文件 + - 清除缓存（方法取决于你使用的特定 MCP 客户端） - 重新启动应用程序 5. **检查服务器日志** @@ -97,7 +97,7 @@ description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi export TRON_MNEMONIC="word1 word2 ... word12" ``` -4. **重新启动服务器**并重新连接 Claude Desktop +4. **重新启动服务器**并重新连接 MCP 客户端 验证配置成功的方式：查看 [完整能力清单](ToolList.md) 中的完整能力清单。 @@ -396,7 +396,7 @@ sun-mcp-server **是的。** 例如，可以同时运行官方主网服务器和本地 Nile 实例。 -**配置示例（Claude Desktop）：** +**配置示例（MCP 客户端）：** ```json { diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 9447b5bf..9a3062d2 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 本地私有化部署 ## 什么是本地私有化部署？ @@ -162,123 +159,8 @@ npm install -g @bankofai/sun-mcp-server sun-mcp-server ``` ---- - -### 第三步：客户端配置 - -配置完成后，需要在 AI 客户端中添加 SUN MCP Server 的连接定义。 - -#### 找到配置文件 - -根据您使用的 AI 客户端，配置文件位置如下： - -| 客户端 | 配置文件路径 | -|--------|-------------| -| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | -| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | -| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` 或通过环境变量 | - -#### 添加服务器定义 - -选择与您的部署方式对应的选项卡： - - - - -**Claude Desktop 配置：** - -在 `~/.claude/resources/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_NETWORK": "nile" - } - } - } -} -``` - -**Claude Code** - -```bash -# 基础配置 -claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server - -# 携带环境变量 -claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server -``` - -**Cursor 配置：** - -在 `~/.cursor/extensions/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["-y", "@bankofai/sun-mcp-server"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` - - - - -适用于从源码运行的情况。 - -**Claude Desktop 配置：** - -在 `~/.claude/resources/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_NETWORK": "nile" - } - } - } -} -``` - -**Cursor 配置：** - -在 `~/.cursor/extensions/mcp/servers.json` 中添加： - -```json -{ - "mcpServers": { - "sun": { - "command": "npx", - "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], - "env": { - "TRON_NETWORK": "nile" - } - } - } -} -``` - - - - +#### 方式 C：HTTP 模式 以 HTTP 服务器模式运行 SUN MCP Server，允许远程连接。 @@ -288,39 +170,12 @@ claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/s sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -**Claude Desktop 配置：** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - -**Cursor 配置：** - -```json -{ - "mcpServers": { - "sun": { - "url": "http://127.0.0.1:8080/mcp" - } - } -} -``` - :::warning HTTP 模式适用于本地开发和测试。对于远程部署，请使用 HTTPS 和适当的身份验证。 ::: - - - -:::tip 关于环境变量部分 -- **npx 运行**：环境变量在配置文件的 `"env"` 字段中设置，或直接在终端导出后运行。 +:::tip 关于环境变量 +- **npx 运行**：在运行命令前直接在终端导出环境变量。 - **HTTP 模式**：启动 HTTP 服务器时，环境变量应在启动命令前导出： ```bash @@ -328,11 +183,20 @@ export TRON_NETWORK=nile sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` -- **重启生效**：修改配置后，需重启 AI 客户端使更改生效。 +- **客户端配置**：服务器运行后，配置你的 MCP 客户端以连接到它。 ::: --- +### 第三步：客户端配置 + +服务器运行后，需要配置你的 MCP 客户端与其连接。请参考你的 MCP 客户端文档获取配置说明。服务器可通过以下方式访问： + +- **npx/本地构建**：通常作为客户端管理的子进程运行 +- **HTTP 模式**：`http://127.0.0.1:8080/mcp`（或你指定的主机/端口） + +--- + ### 第四步：验证接入是否成功 启动 AI 客户端后，应该能看到 SUN MCP Server 的工具列表。进行以下测试以确认配置正确： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 17dd6efe..714ffa2d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 官方云服务接入 ## 什么是官方云服务？ @@ -49,69 +46,6 @@ import TabItem from '@theme/TabItem'; ## 客户端配置 - - - -配置文件路径： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -**基础配置**： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - -**命令行添加**： - -```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp -``` - -**或在项目根目录添加 `.mcp.json`**： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "type": "http", - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -在项目根目录添加 `.cursor/mcp.json`： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "url": "https://sun-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - 如果你想将 SUN MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 **第一步：初始化连接** @@ -175,9 +109,6 @@ curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session ::: - - - --- ## 验证接入是否成功 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 0d20a5e0..2df3434e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 快速开始 这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次 DeFi 查询。** @@ -14,69 +11,19 @@ import TabItem from '@theme/TabItem'; 在开始之前，请确保你已经有： 1. **Node.js** >= 20.0.0（[下载链接](https://nodejs.org/)） -2. **MCP 客户端**：所有支持 MCP 的 AI 客户端。例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 +2. **MCP 客户端**：所有支持 MCP 的 AI 客户端。 --- -## 添加配置 - -根据你使用的工具选择对应的配置方式： - - - - -1. 打开 Claude Desktop 的配置文件： - - **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -2. 在 `mcpServers` 部分添加以下配置： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} -``` - -3. 保存文件并重启 Claude Desktop。 - - - - +## 安装 在终端中运行以下命令添加 SUN MCP Server： ```bash -claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp -``` - - - - - -1. 打开 Cursor 的配置文件：`.cursor/mcp.json` - -2. 在配置中添加： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] - } - } -} +npx add-mcp @bankofai/sun-mcp-server ``` -3. 保存文件并重启 Cursor。 - - - +命令完成后，重启你的 MCP 客户端。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index da701021..b755dd7d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -8,7 +8,7 @@ 连接问题通常发生在首次配置阶段。如果 AI 客户端无法识别 TRON 工具，多半是这里出了问题。 -### Claude Desktop 提示"无法连接到 MCP 服务器" +### 你的 MCP 客户端提示"无法连接到 MCP 服务器" 这是最常见的问题。按以下顺序逐一排查： @@ -20,15 +20,11 @@ 2. **检查 npx 是否可用**。在终端运行 `npx --version`。如果找不到命令，说明 Node.js 安装不完整，需要重新安装。 -3. **验证配置文件格式**。`claude_desktop_config.json` 必须是合法的 JSON。常见错误包括多余的逗号、缺少引号或括号不匹配。可以用这个命令快速验证： - ```bash - cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool - ``` - 如果输出了格式化的 JSON，说明格式没问题。如果报错，按照错误提示修复。 +3. **验证配置文件格式**。你的 MCP 客户端配置文件必须是合法的 JSON。常见错误包括多余的逗号、缺少引号或括号不匹配。使用 JSON 校验工具验证你的配置文件。 -4. **完全重启**。关闭窗口不等于退出——你需要从菜单栏/系统托盘彻底退出 Claude Desktop，然后重新打开。macOS 上可以在 Dock 图标上右键选择"退出"。 +4. **完全重启**。关闭窗口不等于退出——你需要彻底退出你的 MCP 客户端，然后重新打开。 -5. **查看日志**。如果以上都没解决问题，查看 Claude Desktop 的日志文件。macOS 上在 `~/Library/Logs/Claude/` 目录下，搜索包含 "mcp" 或 "tron" 的条目。 +5. **查看日志**。如果以上都没解决问题，查看你的 MCP 客户端的日志文件，搜索包含 "mcp" 或 "tron" 的条目。 ### HTTP 模式下"连接被拒绝" @@ -191,25 +187,7 @@ AI 可能将 TRON MCP Server 的能力与其他区块链工具混淆。如果它 ### 能否同时使用多个 TRON MCP Server 实例？ -可以。在配置中定义多个 MCP Server 条目即可——比如一个连接主网云服务（只读），另一个连接本地测试网部署（带钱包）。只需使用不同的名称： - -```json -{ - "mcpServers": { - "tron-mainnet": { - "command": "npx", - "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] - }, - "tron-local": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "your-password" - } - } - } -} -``` +可以。在 MCP 客户端配置中定义多个 MCP Server 条目即可——比如一个连接主网云服务（只读），另一个连接本地测试网部署（带钱包）。在客户端的 MCP 配置中使用不同的名称配置这两个服务。 ### 如何更新到最新版本？ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md index 0e7421f1..08f964a1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -8,7 +8,7 @@ TRON MCP Server 是连接 AI 助手与 TRON 区块链的桥梁。它基于 [Mode 这对不同的人意味着不同的事情： -- 如果你是 **AI 应用用户**，它让你在 Claude Desktop、Cursor 等工具中直接操作区块链，和日常聊天一样简单。 +- 如果你是 **AI 应用用户**，它让你在支持 MCP 的 AI 工具中直接操作区块链，和日常聊天一样简单。 - 如果你是 **Web3 开发者**，它是你的链上快速原型工具——用自然语言调试合约、查询状态，省去大量样板代码。 - 如果你是 **AI Agent 构建者**，它提供了 95 个标准化的链上工具，可以直接编排进你的自动化流程。 - 如果你是 **数据分析师**，它让链上数据查询变成了对话，不再需要写脚本抓取和解析。 @@ -78,10 +78,10 @@ TRON MCP Server 覆盖了 TRON 区块链上几乎所有常见操作，从只读 --- ## 安全注意事项 -:::warning +:::warning 在开始使用之前，有几条安全原则值得牢记——尤其是在涉及真实资产的操作中： -- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件（如 `claude_desktop_config.json`），应通过系统环境变量或加密钱包管理。 +- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件，应通过系统环境变量或加密钱包管理。 - **先在测试网验证**：任何链上操作在主网执行前，先在 Nile 或 Shasta 测试网上跑通。 - **最小资金原则**：为 AI Agent 配置的钱包只存放执行任务所需的最低金额。 - **注意授权风险**：代币授权（`approve`）操作要格外谨慎，避免授予无限额度。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 6d7c8b8a..f07ad8dd 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 本地私有化部署 ## 什么是本地私有化部署？ @@ -46,7 +43,7 @@ node --version # 应输出 v20.x.x 或更高 在配置钱包之前，请务必理解以下安全原则： :::danger 安全警告 -**切勿**将私钥或助记词直接保存在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中。这些文件通常未加密，可能被意外分享或提交到 Git。请务必使用系统环境变量或加密钱包。 +**切勿**将私钥或助记词直接保存在 MCP 配置文件中。这些文件通常未加密，可能被意外分享或提交到 Git。请务必使用系统环境变量或加密钱包。 ::: --- @@ -167,149 +164,28 @@ npm install npm run build ``` ---- - -### 第四步：客户端配置 - -环境变量和安装都准备好了，现在把 AI 客户端指向本地服务器。 - -#### 找到配置文件 - -| 应用程序 | 操作系统 | 配置路径 | -| :--- | :--- | :--- | -| **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | -| | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | -| **Cursor** | 所有 | 项目根目录：`.cursor/mcp.json` | -| **Google Antigravity** | 所有 | `~/.config/antigravity/mcp.json` | -| **Opencode** | 所有 | `~/.config/opencode/mcp.json` | - -#### 添加服务器定义 +#### 方式 C：以 HTTP 模式运行 - - - -直接从 npm 运行最新版本，无需克隆仓库。 - -**Claude Desktop**（`claude_desktop_config.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - -**Claude Code**： +启动服务器的 HTTP 模式，然后通过 HTTP 端点连接你的 MCP 客户端： ```bash -# 基础配置 -claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron - -# 携带环境变量 -claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron +npm run start:http ``` -**Cursor**（`.cursor/mcp.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["-y", "@bankofai/mcp-server-tron"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` +这会启动一个本地 HTTP 服务器（默认：`http://localhost:3001/mcp`），你的 MCP 客户端可以连接到它。 - - - -适用于从克隆仓库运行的开发者。 - -**Claude Desktop**（`claude_desktop_config.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - -将路径替换为你实际克隆的仓库路径。 - -**Cursor**（`.cursor/mcp.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], - "env": { - "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", - "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" - } - } - } -} -``` - - - +#### 配置说明 -如果你以 HTTP 模式启动了服务器（`npm run start:http`），通过 HTTP URL 连接： +如果你要配置 MCP 客户端指向本地服务器： -**Claude Code**： - -```bash -claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp -``` +- **如果通过 npx 或源码运行**：在 MCP 客户端配置中使用相应的命令（例如 `command: npx` 加上 `args: ["-y", "@bankofai/mcp-server-tron"]`） +- **如果以 HTTP 模式运行**：通过 HTTP URL 配置选项将客户端指向 `http://localhost:3001/mcp` -**Cursor**（`.cursor/mcp.json`）： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "http://localhost:3001/mcp" - } - } -} -``` - - - - -:::tip 关于配置中的 `env` 部分 -如果你已经在系统中设置了环境变量（通过 `~/.zshrc` 或 `~/.bashrc`），可以完全省略配置中的 `env` 部分，服务器会自动读取系统环境变量。 - -如果你的 MCP 客户端不继承系统环境变量，则需要在 `env` 部分中设置。此时**请确保该配置文件不会被分享或提交到版本控制系统**。 -::: +如果你的 MCP 客户端不继承系统环境变量，则需要在客户端设置中显式配置它们。**请确保任何存储凭证的配置文件不会被分享或提交到版本控制系统**。 --- -### 第五步：验证接入是否成功 +### 第四步：验证接入是否成功 完成配置后，**完全退出并重启** AI 客户端，然后尝试： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index c964fdd5..7c920ef4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 官方云服务接入 ## 什么是官方云服务？ @@ -97,90 +94,7 @@ import TabItem from '@theme/TabItem'; ## 客户端配置 - - - -配置文件路径： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -**基础配置（不含 API Key）**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - -**含 TronGrid API Key 的配置**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} -``` - -将 `` 替换为你的实际 TronGrid API Key。 - - - - -**命令行添加**： - -```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp -``` - -**或在项目根目录添加 `.mcp.json`**： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "type": "http", - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -在项目根目录添加 `.cursor/mcp.json`： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} -``` - - - - -如果你想将 TRON MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 +你可以通过 HTTP 请求连接到官方云服务。下面是具体步骤： **第一步：初始化连接** @@ -222,6 +136,25 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` +要使用 TronGrid API Key，在请求头中添加： + +```bash +curl -X POST https://tron-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -H "TRONGRID-API-KEY:your-api-key" \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/call", + "params": { + "name": "get_chain_info", + "arguments": {"network": "mainnet"} + }, + "id": 2 + }' +``` + **第三步：查看可用工具列表** ```bash @@ -243,9 +176,6 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session ::: - - - --- ## 验证接入是否成功 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index d3cde4b3..ca32d318 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # 快速开始 这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次区块链查询。** @@ -13,7 +10,7 @@ import TabItem from '@theme/TabItem'; 在开始之前，确保你已经安装了以下工具： -- 所有支持 MCP 的 AI 客户端：例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 +- 所有支持 MCP 的 AI 客户端 - **Node.js v20.0.0 或更高版本**（用于执行 `npx` 命令）（[Node.js 下载](https://nodejs.org/)） 验证 Node.js 版本： @@ -26,57 +23,13 @@ node --version # 应输出 v20.x.x 或更高 ## 添加配置 -选择你使用的 AI 客户端，把对应的配置复制进去： - - - - -打开配置文件： -- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` - -添加以下内容： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "command": "npx", - "args": [ - "mcp-remote", - "https://tron-mcp-server.bankofai.io/mcp" - ] - } - } -} -``` - - - - -在终端执行： +在终端执行以下命令： ```bash -claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp -``` - - - - -在项目根目录添加 `.cursor/mcp.json`： - -```json -{ - "mcpServers": { - "mcp-server-tron": { - "url": "https://tron-mcp-server.bankofai.io/mcp" - } - } -} +npx add-mcp @bankofai/mcp-server-tron ``` - - +命令完成后，重启你的 MCP 客户端。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 2a8c5ffe..aec15986 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -60,7 +60,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## sunswap — 换币、查价、管理池子 +## sunswap — 换币、查价、管理池子 {#sunswap} 想在 SunSwap 上换币、查行情、管理流动性？对 AI 说下面的话就行。 @@ -92,7 +92,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## sunperp-skill — 永续合约交易 +## sunperp-skill — 永续合约交易 {#sunperp-skill} 想做合约？这个技能帮你看行情、开仓、平仓、设止损。内置安全锁：最高 20 倍杠杆，开仓必须设止损——默认帮你守住底线，亏损超过 5% AI 会自动帮你跑路，防止爆仓。 @@ -122,7 +122,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## tronscan-skill — 链上数据侦探 +## tronscan-skill — 链上数据侦探 {#tronscan-skill} 想查链上发生了什么？这个技能帮你查账户、交易、代币、区块和全网统计。**纯查询，绝对安全，不花一分钱，不需要任何密码。** 非常适合作为你的第一个技能来上手。 @@ -146,7 +146,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## x402-payment — 链上"先付后用"自动结算 +## x402-payment — 链上"先付后用"自动结算 {#x402-payment} 有些高级 API 和 AI 智能体是收费的——需要你先完成链上付费才能使用。这个技能通过 x402 协议帮你自动完成"先付费、再获取"的链上结算流程：AI 发现对方要收费，自动帮你完成链上支付，拿到结果后汇报给你。每次付款前同样会先问你确认。 @@ -156,7 +156,7 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦 --- -## recharge-skill — BANK OF AI 账户管理 +## recharge-skill — BANK OF AI 账户管理 {#recharge-skill} 查余额、看订单、给 BANK OF AI 账户充值。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index fc8b736e..4c46a964 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -59,36 +59,46 @@ 五大核心技能，覆盖 TRON 生态最常用的场景。每个技能都配了一句"参考话术"——复制到 AI 对话框里回车就能体验。 -### 💱 DEX 交易专属向导 +### 💱 执行 DEX 交易 -就像你的私人交易员。查价格、比报价、甚至一键换币。 +查价格、比报价、甚至一键换币。 > 🗣️ "帮我算算现在 100 USDT 在 SunSwap 上能换多少 TRX？" -### 📈 永续合约安全员 +💡 如需了解更多进阶玩法，请查看：[**sunswap**（DEX 交易向导）](./BANKOFAISkill.md#sunswap) + +### 📈 进行永续合约交易 在 SunPerp 看行情、开平仓。内置安全锁，最高只允许 20 倍杠杆，且开仓强制设止损——帮你管住手，防爆仓。 > 🗣️ "现在 BTC 资金费率是多少？帮我开一张 5 倍杠杆的多单，亏损 5% 自动止损。" -### 🕵️ 链上数据侦探 +💡 如需了解更多参数设置，请查看：[**sunperp-skill**（永续合约安全员）](./BANKOFAISkill.md#sunperp-skill) + +### 🕵️ 查询链上数据 查账户、查交易、查新币靠不靠谱。纯查询，绝对安全，不花一分钱。 > 🗣️ "帮我查一下昨天那个土狗币现在的持仓分布，有没有被庄家控盘？" -### ☕ 链上"先付后用"自动结算 +💡 如需了解更多查询维度，请查看：[**tronscan-skill**（链上数据侦探）](./BANKOFAISkill.md#tronscan-skill) + +### ☕ 自动结算链上付费服务 当 AI 需要调用付费的链上服务或数据接口时，会通过 x402 协议自动完成"先付费、再获取"的链上结算，无需你手动扫码或切换钱包。 > 🗣️ "使用 x402 协议调用这个付费智能体端点：https://api.example.com"（请替换为你实际要调用的付费端点地址） -### 🏦 BANK OF AI 账户大管家 +💡 如需了解支付与授权细节，请查看：[**x402-payment**（链上自动结算）](./BANKOFAISkill.md#x402-payment) + +### 🏦 管理 BANK OF AI 账户 查看你的 BANK OF AI 余额，一句话完成充值。 > 🗣️ "帮我看看我的账户还有多少余额，顺便再充 5 个 U 进去。" +💡 如需了解充值与提现规则，请查看：[**recharge-skill**（账户大管家）](./BANKOFAISkill.md#recharge-skill) + --- ## 🎯 这套 Skills 适合我吗？ diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md index 0eb63d56..d0646bcc 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md @@ -1,221 +1,93 @@ -# 常见问题与排查 +# 常见问题 -遇到问题时，先来这里找找答案。按照你最可能遇到的顺序组织：安装问题、连接问题、凭证问题、运行时问题，最后是一些通用问题。 +遇到报错别慌，通常都是一些小设置没配好。我们按最容易碰到的问题排了个序： --- -## 安装问题 +## 安装时报错了 -### 安装程序报错"command not found: node" +### 报错里写着 "command not found: node" 或 "npm install 失败" -安装程序需要 Node.js v18.0.0 或更高版本。检查是否已安装： +**人话翻译**：你的电脑上没装 Node.js，或者版本太老了。 -```bash -node --version -``` +**怎么解决**：去 [Node.js 官网](https://nodejs.org/) 下载最新的稳定版（LTS，建议 v20 或更高版本），像装普通软件一样一路点"下一步"装好。然后关掉终端里的黑框框，重新运行一次安装口令。 -如果未安装或版本太低，请到 [nodejs.org](https://nodejs.org/) 下载安装最新 LTS 版本。安装 Node.js 后，`npx` 命令会同时可用。 +### 报错里写着 "command not found: python3" -### 安装程序报错"command not found: python3" +**人话翻译**：你的电脑缺少一个叫 Python 的基础运行环境。 -安装程序使用 Python 处理 JSON 配置文件。macOS 通常自带 Python 3，Linux 可以通过包管理器安装： +**怎么解决**：去 [Python 官网](https://www.python.org/downloads/) 下载安装。 -```bash -# Ubuntu/Debian -sudo apt install python3 +### AgentWallet（AI 保险柜）安装失败了 -# macOS (通过 Homebrew) -brew install python3 -``` +**怎么解决**： -### 安装程序警告"OpenClaw not found" - -安装程序检测到 `~/.openclaw` 目录不存在。这意味着 OpenClaw 可能未安装，或者安装在了非标准路径。 - -安装程序会询问你是否继续——你可以选择继续安装（MCP Server 和 Skills 仍然会被配置），但 OpenClaw 启动后可能无法自动加载它们。建议先到 [OpenClaw 官方仓库](https://github.com/openclaw) 完成安装。 - -### Skills 克隆失败 - -如果 `git clone` 失败，常见原因包括： - -- **网络问题**：检查是否能访问 GitHub。可以尝试 `git clone https://github.com/BofAI/skills.git` 手动测试。 -- **Git 未安装**：运行 `git --version` 确认。 -- **指定的分支/标签不存在**：如果你设置了 `GITHUB_BRANCH` 环境变量，确认对应的分支或标签确实存在。 - -Skills 克隆失败不会中断整个安装——MCP Server 的配置仍然完好。你可以之后手动安装 Skills。 - -### npm install 失败 - -安装 Skills 时，部分 Skill（如 sunswap、x402-payment）需要运行 `npm install` 安装依赖。如果失败： - -- 检查网络连接（npm 需要访问 registry.npmjs.org） -- 确认 Node.js 版本 >= 18 -- 尝试手动运行： - ```bash - cd ~/.openclaw/skills/sunswap # 或其他 Skill 目录 - npm install - ``` - -npm install 失败不会中断安装程序——它会发出警告但继续。该 Skill 的部分功能可能受限，直到依赖安装成功。 +1. 再次确认你的 Node.js 版本是否足够新。 +2. 有时候纯粹是网络太卡下载超时了，喝口水等两分钟重新运行一次安装代码即可。 +3. 如果一直卡住，可以试着手动把旧的 `~/.agent-wallet` 文件夹删掉，从头再来。 --- -## 连接问题 - -### OpenClaw 启动后看不到区块链工具 +## 安装完了，但 AI 像个傻子 -**最常见的原因**：没有重启 OpenClaw。修改 mcporter.json 后，必须完全退出并重新启动 OpenClaw。 +### AI 委屈地说："我没有查区块链的工具" 或 "我不知道什么是 SunSwap" -如果重启后仍然看不到： +**最可能的原因**：你装完之后太心急，**没有重启 OpenClaw 软件**。 -1. **检查 mcporter.json 格式**： - ```bash - python3 -m json.tool ~/.mcporter/mcporter.json - ``` - 如果报 JSON 语法错误，修复格式问题后重启。 +**怎么解决**：把 OpenClaw 彻底退出（苹果电脑按 `Command+Q`），重新打开，让 AI 重新读取一下它的新脑子。 -2. **检查 mcporter.json 内容**：确认 `mcpServers` 下有你安装的 Server 条目。 +### AI 能查到数据，但回答乱七八糟、经常出错？ -3. **手动测试 MCP Server**： - ```bash - npx -y @bankofai/mcp-server-tron - ``` - 如果这条命令能正常启动（显示日志输出），说明 MCP Server 本身没问题，问题在 OpenClaw 的配置读取。 +**最可能的原因**：你用的 AI 底层模型版本太低了。就好比你让一个小学生去做高中数学题，它不是不努力，是真的能力不够。 -### 只有查询工具可用，没有转账等写入工具 +**怎么解决**：打开 OpenClaw 的设置，把模型升级到更强的版本。模型越强，AI 理解你的指令就越准确，调用工具也越不容易出错。 -这是设计如此。写入工具只在配置了钱包凭证后才会出现。检查以下之一是否已配置： +### 凭什么别人能转账，我的 AI 只能查数据？ -- 环境变量 `TRON_PRIVATE_KEY`（mcp-server-tron） -- 环境变量 `PRIVATE_KEY`（bnbchain-mcp） -- mcporter.json 中对应 Server 的 `env.TRON_PRIVATE_KEY` 或 `env.PRIVATE_KEY` +**原因**：你现在的 AI 是极度安全的"只读模式"。因为你在安装时跳过了 AgentWallet 配置，没有给它留钱包钥匙。 -配置凭证后重启 OpenClaw。详细说明请参阅 [配置参考](./Configuration.md)。 - -### MCP Server 启动超时 - -如果 OpenClaw 在启动 MCP Server 时超时，可能是 npx 下载包太慢。首次运行时需要从 npm 下载包，可能需要几十秒。 - -可以提前手动下载来加速： - -```bash -npx -y @bankofai/mcp-server-tron --help -npx -y @bnb-chain/mcp@latest --help -``` - -下载完成后，后续启动会使用缓存，速度会快很多。 +**怎么解决**：重新跑一次安装脚本，在 AgentWallet 设置那一关跟着提示认真把钱包配好。配好并重启后，转账和交易功能就会被激活。 --- -## 凭证问题 - -### "私钥无效"错误 - -**TRON 私钥**应为 64 个字符的十六进制字符串，可以带或不带 `0x` 前缀。 - -**EVM 私钥**应带 `0x` 前缀。安装程序会自动为不带前缀的私钥添加 `0x`，但如果你手动编辑配置文件，请确保格式正确。 - -常见错误： -- 多余的空格、换行或引号嵌套 -- 从其他地方复制时带入了不可见字符 - -验证方法：将私钥导入对应的钱包（TronLink 或 MetaMask）确认有效。 +## 密码和安全焦虑 -### TronGrid API Key 不生效 +### 私钥填错了或者报错说 "私钥无效" -1. **变量名是否正确**：必须是 `TRONGRID_API_KEY`（不是 `TRON_API_KEY`） -2. **Key 是否仍然有效**：登录 [trongrid.io](https://www.trongrid.io/) 确认状态 -3. **是否正确加载**：如果在环境变量中设置，确认已运行 `source ~/.zshrc` +**原因**：现在的安装包用 AgentWallet 管理钱包，一般不需要你手动填私钥了。但如果你使用了币安链工具箱 (bnbchain-mcp)，手动配私钥时可能不小心多复制了一个空格或回车。 +**怎么解决**：重新仔细复制一遍。EVM（币安/以太坊）私钥要带 `0x` 开头，如果你是手动改文件，千万注意别漏了。 -### BANK OF AI API Key 无效 +### AI 报错 "请求限速" 或 "429 错误" -检查 `~/.bankofai/config.json` 或 `~/.mcporter/bankofai-config.json` 的内容： +**人话翻译**：你让 AI 查数据的速度太快了，免费的网络通道觉得你像个机器人，把你拉黑了一小会儿。 -```bash -cat ~/.bankofai/config.json -``` +**怎么解决**： -确认 `api_key` 字段包含有效的 Key。注意 recharge-skill 的凭证读取有优先级顺序（CLI 参数 > 环境变量 > 工作目录 `bankofai-config.json` > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`），如果你在多个地方设置了不同的值，可能会读到意外的那个。 +1. **治标**：歇几分钟再问。 +2. **治本**：去 [TronGrid](https://www.trongrid.io/) 免费申请一个专属的 API Key。安装时把这个 Key 填进去，AI 就能跑 VIP 高速通道了。 --- -## 运行时问题 - -### 请求限速（429 错误） - -主网的公共 RPC 有严格的频率限制。解决方法： - -- **配置 TronGrid API Key**：免费申请后设置 `TRONGRID_API_KEY`，显著提升限额 -- **使用测试网**：Nile 和 Shasta 测试网受限更少 -- **减少并发查询**：在提示词中避免让 AI 同时执行大量查询 - -### Skill 执行失败 - -如果某个 Skill 报错，按以下顺序排查： - -1. **检查依赖是否安装**： - ```bash - cd ~/.openclaw/skills/ - npm install # 如果有 package.json - ``` - - -2. **检查 Node.js 版本**：部分 Skill 需要 >= 18.0.0。 - -### 交易失败 - -链上交易失败的常见原因： - -- **余额不足**：TRX 余额不够支付 Gas 费（带宽/能量） -- **能量不足**：智能合约调用（包括 TRC20 转账）需要消耗能量 -- **账户未激活**：新的 TRON 地址需要先收到一笔 TRX 才能激活 -- **授权额度不足**：TRC20 代币转账前可能需要先 approve - -使用 mcp-server-tron 的 `get_transaction_info` 工具查看交易失败的具体原因。 - ---- - -## 通用问题 - -### 能否只安装部分组件？ - -可以。安装程序在每个阶段都允许你选择性安装。比如你可以只安装 mcp-server-tron 而不装其他 MCP Server，或者只安装 sunswap Skill 而跳过其他 Skill。 - -### 能否多次运行安装程序？ - -可以。安装程序对 mcporter.json 采用深度合并策略，不会覆盖已有配置。对于 Skills，如果目标位置已存在同名 Skill，会提示你是否覆盖。 - -### 如何完全卸载？ +## 随心所欲地折腾（卸载与重装） -OpenClaw Extension 没有自动卸载程序。手动卸载步骤： +### 我能不能只装某一个技能，不装别的？ -1. **删除 MCP Server 配置**：编辑 `~/.mcporter/mcporter.json`，移除对应的 Server 条目 -2. **删除 Skills**：删除安装目录下的 Skill 文件夹（默认 `~/.openclaw/skills/`） -3. **删除凭证文件**： - ```bash - rm -f ~/.x402-config.json - rm -f ~/.bankofai/config.json - rm -f ~/.mcporter/bankofai-config.json - rm -f ~/.clawdbot/wallets/.deployer_pk - ``` -4. **清理环境变量**：从 `~/.zshrc` 或 `~/.bashrc` 中移除相关 export 语句 +完全可以！安装向导走到第 4 关时，会列出所有技能。你用空格键只勾选你想要的，别的空着，按回车确认就行。 -### 支持哪些操作系统？ +### 玩腻了，怎么卸载它们？ -安装程序是 Bash 脚本，支持： -- **macOS**（Intel 和 Apple Silicon） -- **Linux**（Ubuntu、Debian、CentOS 等） -- **Windows**：需要通过 WSL（Windows Subsystem for Linux）运行 +最简单粗暴的方法：打开电脑的文件夹，找到 `~/.openclaw/skills/` 目录，把你不想用的技能文件夹直接删掉，然后重启 AI 软件，它就彻底消失了。 -### 和 TRON MCP Server 的官方云服务有什么区别？ +### 我瞎填了一通装坏了，能重新装吗？ -[官方云服务](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md)是远程托管的只读 MCP Server，不需要本地安装。OpenClaw Extension 则在你本地运行 MCP Server，配合私钥可以解锁完整的读写能力。 +随便装！不用怕搞坏电脑。 -如果你只需要查询链上数据，云服务更简单。如果你需要转账、合约写入等操作，或者需要使用 Skills（如 SunSwap 交易），就需要 OpenClaw Extension。 +- **选 1（普通安装）**：重新跑一次脚本，它会自动修补你缺的东西。 +- **选 2（全新安装 - Clean install）**：如果你想彻底从头来过，选这个。它会把你旧的工具箱、技能、配置全部格式化清空，给你一个干干净净的新环境。为了防止你误触，它还会要求你手动输入 `CLEAN` 这几个字母来确认。 --- -## 下一步 +## 还是搞不定？ -- 从头开始 → [快速开始](./QuickStart.md) +👉 回到 **[快速开始](./QuickStart.md)** 从第一步跟着再走一遍，通常 99% 的问题都能迎刃而解。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index cec7b4e9..3ae6f759 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -1,62 +1,60 @@ # 简介 -## OpenClaw Extension 是什么？ +一键让你的 AI 懂区块链。 -OpenClaw Extension 是由 **BANK OF AI** 开发的一套扩展工具包，为 [OpenClaw](https://github.com/openclaw)（开源 AI 助手）赋予**区块链交互能力**。安装后，你的 AI 助手就能直接操作链上资产——查余额、发起转账、调用智能合约、在 DEX 上兑换代币——而这一切只需要用自然语言对话完成。 +你有没有想过，有一天查链上数据、换币、看余额，再也不用打开十几个网页，也不用盯着复杂的各种 App？ -传统方式下，让 AI 操作区块链需要自己搭建 MCP Server、手动管理配置文件、逐个安装各种工具。OpenClaw Extension 把这些工作打包成了一个交互式安装程序——运行一条命令，按提示选择你需要的组件，几分钟内就能让 AI 助手具备多链操作能力。 +你只需要像跟朋友微信聊天一样，发一句大白话，剩下的脏活累活，全由你的 AI 助理搞定。 + +**OpenClaw Extension，就是帮你实现这个魔法的"一键安装包"。** --- -## 核心愿景 +## 它是怎么施展魔法的？ -OpenClaw Extension 的目标是为 AI 代理经济构建一套金融基础设施——让每个 AI 代理都具备独立的金融能力： +以前的 AI 只是个懂理论的"嘴强王者"。为了让它能帮你干实事，我们的安装包会给它装上两样核心武器： -- **赚取收益**：通过 x402 协议等标准接口接受任务和服务的付款 -- **自主消费**：独立支付计算、数据、存储等资源费用 -- **代理互联**：促进代理之间（A2A）的直接金融活动和结算 -- **DeFi 交互**：无缝地与去中心化金融协议和智能合约交互 +### 🛠️ 1. 工具箱 (MCP Server) —— 给 AI 装上"手" ---- +这就是 AI 接入区块链的网线。装上它，AI 就拥有了直接读写区块链的能力。 -## 它包含什么？ +目前我们支持： -OpenClaw Extension 由两大类组件构成：**MCP Server** 和 **Skills**。你可以在安装时按需选择要启用哪些组件。 +- **波场 (TRON) 工具箱**：能查余额、发转账、玩转波场生态。 +- **币安 (BNB Chain) 工具箱**：支持 BSC、以太坊等多链操作。 +- **充值小助手**：帮你远程给 BANK OF AI 账户充值。 -### MCP Server — 链上操作能力 +### 🧠 2. 技能包 (Skills) —— 给 AI 装上"脑子" -MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) 标准接口提供链上操作能力。目前支持两条链的 MCP Server 和一个远程充值服务： +光有手还不行，AI 得知道遇到事情该怎么按步骤处理。技能包就是我们提前写好的"菜谱"。 -| MCP Server | 目标 | 核心能力 | -| :--- | :--- | :--- | -| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | -| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | -| **bankofai-recharge** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | +比如 **"sunswap" 技能**，就是教 AI："当主人说想换币时，你要先去查价格，再算好手续费，最后把账单发给主人确认，绝对不能乱花钱。" -### Skills — 预构建工作流 +--- -Skills 是封装好的业务流程模板。与 MCP Server 提供的单个工具不同，一个 Skill 可以串联多个操作完成完整的任务——比如"在 SunSwap 上兑换代币"涉及查价格、检查余额、执行兑换、确认结果等步骤，一个 Skill 就能搞定。 +## 🌟 装上之后，体验有多爽？ -| Skill | 功能 | -| :--- | :--- | -| **sunswap** | SunSwap DEX 交易——余额查询、报价、兑换、V2/V3 流动性管理 | -| **sunperp-skill** | SunPerp 永续合约交易——行情、下单、仓位管理、杠杆设置、提现 | -| **tronscan-skill** | 通过 TronScan API 查询链上数据（账户、交易、代币、区块、全网统计） | -| **x402-payment** | x402 支付技能，调用付费智能体和付费 API | -| **recharge-skill** | BANK OF AI 余额和订单查询，以及通过 MCP 充值 | +安装完成后，你的 AI 会立刻化身为极其专业的私人 Web3 助理。试试像这样使唤它： +> **"帮我查一下现在 TRON 链上能量费贵不贵？"** +> +> **"100 USDT 在 SunSwap 上能换多少 TRX？算上手续费划算吗？"** +> +> **"我的钱包里还有多少余额？顺便帮我查一下昨天那个土狗币的持仓情况。"** + +它会把枯燥的代码和数据嚼碎了，变成大白话喂给你。 --- -## 适合谁使用？ +## 这适合我吗？ -- **OpenClaw 用户**：想让 AI 助手直接操作区块链，而不想自己手动搭建 MCP Server -- **Web3 开发者**：需要一个快速搭建的链上开发环境，用自然语言调试合约和查询数据 -- **AI Agent 构建者**：需要为自动化代理配备多链操作能力 -- **DeFi 用户**：想通过 AI 助手在 SunSwap 上交易或管理流动性 +- **我是小白玩家**：太棒了！不想折腾代码，只想用大白话让 AI 帮忙查数据、做交易，这就是为你量身定制的。 +- **我是 Web3 老手**：懒得天天开网页连钱包，想拥有一个随叫随到的私人交易助理，它能帮你省下大把盯盘时间。 --- -## 下一步 +## 迫不及待了？ + +别犹豫了，整个安装过程就像用微波炉热个便当一样简单，只需要几分钟。 -- 想立刻体验？ → [快速开始](./QuickStart.md) +👉 **[去快速开始，给你的 AI 升级吧！](./QuickStart.md)** diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md index 8a63a4fa..bdd487d5 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -1,145 +1,146 @@ # 快速开始 -这个页面的目标是：**让你在几分钟内完成安装，并发起第一次区块链查询。** - -安装程序是交互式的，会引导你选择要安装哪些 MCP Server 和 Skills，然后自动完成所有配置。你只需要按提示操作即可。 +我们的目标是：**花几分钟跟着向导点几下，让你的 AI 成功查到第一笔链上数据。** --- -## 准备工作 - -在运行安装程序之前，确保以下工具已就绪： +## 🕹️ 准备工作 -| 要求 | 说明 | 验证命令 | 下载安装 | -| :--- | :--- | :--- | :--- | -| **OpenClaw** | 你的开源 AI 助手 | 检查 `~/.openclaw` 目录是否存在 |[OpenClaw 官方仓库](https://github.com/openclaw) | -| **Node.js v18+** | 运行 MCP Server 所需 | `node --version` | [Node.js 官方网站](https://nodejs.org/) | -| **Python 3** | 安装程序用于处理 JSON 配置 | `python3 --version` | [Python 官方网站](https://www.python.org/downloads/)| -| **Git** | 克隆 Skills 仓库 | `git --version` | [Git 官方网站](https://git-scm.com/) | +在开始之前，请确保你的电脑上已经装好了这几样基础软件（如果没有，请像装普通软件一样去官网下载安装）： +1. **OpenClaw**：你的 AI 助手软件。 +2. **Node.js**（请务必安装 v20 或以上版本）：这是技能包运行的基础环境。*（极其重要，版本太低一定会报错！）* +3. **Git**：用来下载技能包的小工具。 +4. **Python 3**：安装向导用来处理配置文件的小帮手。 --- -## 运行安装程序 +## 🚀 第一步：一键通关安装 + +打开你电脑上的"终端"（也就是那个黑框框）。 + +- **苹果电脑：** 按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车。 +- **Windows 电脑：** 需要先装 WSL（Windows 子系统），然后打开 WSL 终端。 -### 方式一：一键安装（推荐） +把下面这行神奇的代码**完整复制**，粘贴进去，按回车： ```bash curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash ``` -### 方式二：从源码安装 +🚑 **急救包：敲完回车就报错了？** 如果屏幕提示 `command not found: node` 或 `python3`，说明你的电脑缺少上面说的基础环境。👉 [点这里看怎么解决](./FAQ.md#报错里写着-command-not-found-node-或-npm-install-失败) -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` +如果没有报错，屏幕上会跳出英文向导。请把它当成一个文字小游戏，整个流程分 4 关： -安装程序启动后，会自动检查环境依赖（Node.js、npx、Git、Python），如果发现缺失会立即提示。 +### 🟢 第 1 关：选安装模式 -如无依赖缺失，进入安装过程，安装过程分为两个主要阶段，每一步都会让你交互式选择。 +屏幕会问你选哪种方式。键盘输入 `1`（普通安装），然后按回车。 这种方式最省心，能保留你以前的设置。 ---- +### 🟢 第 2 关：配置"AI 的专属保险柜"（AgentWallet） -## 安装过程详解 +向导会自动给你装一个叫 AgentWallet 的工具，用来安全存放 AI 的钱包钥匙。 -### 第一阶段：选择并配置 MCP Server +如果你是新手，面对屏幕上的问题，闭着眼睛一路按回车，用默认值就足够了。 -安装程序会列出所有可用的 MCP Server，让你选择要安装哪些： +（🚑 报错卡住了？👉 [点这里看 AgentWallet 安装失败怎么救](./FAQ.md#agentwallet-ai-保险柜安装失败了)） -``` -📦 Available MCP Servers: - 1) mcp-server-tron - TRON blockchain interaction - 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) bankofai-recharge - Remote BANK OF AI recharge MCP +### 🟢 第 3 关：挑选工具箱（给 AI 装"手"） -Select servers to install (e.g., 1,2,3 or 'all'): -``` +屏幕会列出波场 (mcp-server-tron) 等选项。按键盘 `↑` `↓` 方向键移动，按**空格键**打勾，选完后按**回车**确认。 + +⚠️ **前方高能**：向导可能会突然问你要 API Key！ + +- **这是啥？** 它是 VIP 通行证，有了它查数据就不卡。 +- **我现在没有怎么办？** 直接按回车跳过！留空完全没关系！ 绝不影响你现在的安装。 + +### 🟢 第 4 关：挑选技能包（给 AI 装"脑子"） -> **关于 bankofai-recharge**：这是一个远程 MCP，直接连接到 `https://recharge.bankofai.io/mcp`，无需配置本地凭证——安装程序会自动配置好远程端点。 +屏幕会列出 sunswap（换币）、tronscan（查数据）等技能。同样按**空格键**打勾，按**回车**确认。 -对于每个选中的服务器，安装程序会继续询问凭证存储方式： +遇到看不懂的密钥索要提示，统统直接按回车跳过。 -- **选项 1：保存到配置文件** — 密钥以明文存储在 `~/.mcporter/mcporter.json` 中。方便但安全性较低。 -- **选项 2：使用环境变量（推荐）** — 密钥从系统环境变量读取，不写入任何文件。 +当屏幕底部亮起 `Installation Complete!` 时——恭喜，通关成功！ -如果你选择保存到配置文件，安装程序会接着询问具体的密钥值（私钥、API Key 等）。如果选择环境变量，安装程序会告诉你需要设置哪些变量。 +--- + +## 🎉 第二步：重启并见证奇迹 -> **建议**：如果你只是想快速体验，可以先跳过密钥配置（直接回车留空）。没有私钥时 MCP Server 会以只读模式运行，你仍然可以查询链上数据。 +安装完成后，有一步绝对不能漏：**彻底关掉你的 OpenClaw 软件，然后重新打开它。** -### 第二阶段：选择并安装 Skills +🚑 **急救包：AI 像个傻子？** 如果它回答"我不知道什么是 SunSwap"，99% 是因为你刚才没重启。👉 [点这里看怎么彻底重启](./FAQ.md#ai-委屈地说我没有查区块链的工具-或-我不知道什么是-sunswap) -安装程序会从 GitHub 克隆 [Skills 仓库](https://github.com/BofAI/skills)，自动发现所有可用的 Skill，并让你选择： +打开对话框，对你的 AI 发出第一个指令： ``` -🔧 Available Skills: - 1) recharge-skill - BANK OF AI account query and recharge - 2) sunperp-skill - SunPerp perpetual futures trading (TRON) - 3) sunswap - SunSwap DEX trading skill - 4) tronscan-skill - TRON blockchain data lookup - 5) x402-payment - Agent payment protocol (x402) - -Select skills to install (e.g., 1,2,3 or 'all'): +查一下 TRON 主网当前的区块高度。 ``` -然后选择安装位置： +如果它思考了几秒钟，然后乖乖给你报出了一串数字——太棒了！你的 AI 已经成功连上了区块链！ -| 选项 | 路径 | 适用场景 | -| :--- | :--- | :--- | -| **用户级别**（推荐） | `~/.openclaw/skills/` | 所有项目共享 | -| **工作区级别** | `.openclaw/skills/` | 仅当前项目使用 | -| **自定义路径** | 你指定的目录 | 特殊需求 | +再试一句： -部分 Skill 有额外的凭证需求，安装程序会在安装时逐一提示： +``` +100 USDT 在 SunSwap 上现在能换多少 TRX？ +``` + +--- -- **recharge-skill** — 需要 BANK OF AI API Key（`BANKOFAI_API_KEY`） -- **sunperp-skill** — 需要 SunPerp API 密钥（`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`） -- **tronscan-skill** — 提示你在 shell 中设置 `TRONSCAN_API_KEY` 环境变量 -- **sunswap** — 提示配置 TRON 私钥（如果前面没有配置） +*（以上是新手必修课。如果你已经玩转了，可以继续往下看👇）* --- -## 验证安装是否成功 +## 🛠️ 事后怎么补填 API Key（VIP 通行证）？ -安装完成后，**重启 OpenClaw**，然后在对话中输入： +太懂你了！一开始安装只想随便看看，全都按回车跳过了。现在玩熟练了，想填入 API Key 享受"VIP 不限速通道"该怎么做？ -``` -查一下 TRON 主网当前的区块高度 -``` +### 第一步：弄清楚你需要哪把"钥匙" -如果收到正常响应（显示当前区块高度），说明 mcp-server-tron 已成功接入。 +| Key 名称 | 它是干嘛的？ | 去哪免费领？ | +| :--- | :--- | :--- | +| `TRONGRID_API_KEY` | 波场工具箱的高速通道，不填会被限速 | [trongrid.io](https://www.trongrid.io/) 免费注册获取 | +| `TRONSCAN_API_KEY` | TronScan 查数据技能必须用到 | [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) 免费申请 | +| `BANKOFAI_API_KEY` | 给 BANK OF AI 充值或查余额用 | [chat.bankofai.io/key](https://chat.bankofai.io/key) 登录后获取 | -你还可以试试： +### 第二步：把钥匙填进系统里 -``` -查一下 TRON 地址 TXyz... 的 TRX 余额 -``` +拿到对应的 Key 后，根据它的类型，选择下面简单的方法填进去。**填完后千万记得重启 OpenClaw！** -``` -TRON 主网当前的能量和带宽价格是多少？ -``` +#### 🔧 A 类钥匙：填入"隐形便签"（适用于 TRONGRID 和 TRONSCAN） -如果这些查询都能正常返回结果，说明一切就绪。 +**🍎 苹果电脑 (Mac) 用户：** -:::info 关于只读模式 -如果你在安装时没有配置私钥，MCP Server 会以只读模式运行——所有查询类操作（查余额、查交易、查合约状态等）都可以正常使用，但转账、合约写入等操作不可用。要解锁写入能力，请参阅 [配置参考](./Configuration.md)。 -::: +1. 在终端输入 `open -e ~/.zshrc` 并回车。 +2. 在弹出的记事本最下方，粘贴这行代码（注意保留双引号 `""`）： + ``` + export TRONGRID_API_KEY="你的TronGrid_Key填在这里" + export TRONSCAN_API_KEY="你的TronScan_Key填在这里" + ``` +3. 按 `Command + S` 保存关闭，然后重新打开终端或重启 OpenClaw 即可生效。 ---- +**🪟 Windows 电脑 (WSL) 用户：** -## 遇到问题？ +1. 在终端输入 `notepad.exe ~/.bashrc` 并回车。 +2. 在弹出的记事本最下方，粘贴同样的代码： + ``` + export TRONGRID_API_KEY="你的TronGrid_Key填在这里" + export TRONSCAN_API_KEY="你的TronScan_Key填在这里" + ``` +3. 按 `Ctrl + S` 保存关闭，然后重新打开终端或重启 OpenClaw 即可生效。 -如果安装后 AI 助手无法识别区块链工具，常见原因包括： +#### 🔧 B 类钥匙：一键生成配置文件（适用于 BANK OF AI） -- **没有重启 OpenClaw** — 修改配置后必须完全重启 -- **Node.js 版本太低** — 确保 v18.0.0 或更高 -- **mcporter.json 格式错误** — 可以用 `python3 -m json.tool ~/.mcporter/mcporter.json` 检查 +如果你拿到了这把钥匙，直接在终端（黑框框）里复制并运行下面的整段代码即可（记得把中文部分替换成你的真实 Key）： -更多排查方法请参阅 [常见问题](./FAQ.md)。 +**配置 BANK OF AI：** + +```bash +mkdir -p ~/.mcporter && echo '{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://api.bankofai.io/v1/"}' > ~/.mcporter/bankofai-config.json +``` --- -## 下一步 +## 还有其他卡壳的地方？ + +这很正常！每个人的电脑环境都不一样。 -- 遇到问题？ → [常见问题](./FAQ.md) +去看看 👉 **[常见问题（救火指南）](./FAQ.md)**，99% 的奇葩坑我们都已经帮你踩过，并写好解法了。 From 7fedc2eb52a4bbbfb36a232c9741f5f670b4ea85 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 21:21:48 +0800 Subject: [PATCH 36/44] delete permanently --- docs/Agent-Wallet/Developer/CLI-Reference.md | 8 ++--- docs/Agent-Wallet/FAQ.md | 2 +- docs/Agent-Wallet/QuickStart.md | 30 +------------------ docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 2 +- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- docs/McpServer-Skills/SKILLS/Faq.md | 4 +-- docs/McpServer-Skills/SKILLS/QuickStart.md | 14 +-------- docs/Openclaw-extension/QuickStart.md | 13 -------- .../Agent-Wallet/Developer/CLI-Reference.md | 6 ++-- .../current/Agent-Wallet/FAQ.md | 2 +- .../current/Agent-Wallet/QuickStart.md | 30 +------------------ .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 2 +- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 2 +- .../current/McpServer-Skills/SKILLS/Faq.md | 4 +-- .../McpServer-Skills/SKILLS/QuickStart.md | 14 +-------- .../current/Openclaw-extension/QuickStart.md | 13 -------- 16 files changed, 19 insertions(+), 129 deletions(-) diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md index 5cbd431a..bc7a2ff7 100644 --- a/docs/Agent-Wallet/Developer/CLI-Reference.md +++ b/docs/Agent-Wallet/Developer/CLI-Reference.md @@ -165,7 +165,7 @@ jobs: ### Method B: Local Password Cache (Convenience vs. Security Trade-off) -After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: +After running a command once with the `--save-runtime-secrets` flag, the password is cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables: ```bash agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets @@ -196,7 +196,7 @@ agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' ``` :::danger Security Warning -When using `-p` to pass the password inline, the plaintext password is permanently recorded in your terminal's `history`. Only use this method in fully isolated test environments! +When using `-p` to pass the password inline, the plaintext password is recorded in your terminal's `history`. Only use this method in fully isolated test environments! ::: ### Custom Storage Directory @@ -225,7 +225,7 @@ agent-wallet change-password ### `agent-wallet reset` (Reset All Data) -Deletes everything under `~/.agent-wallet/`. **This is a nuclear option — once executed, all wallets, keys, and configuration are permanently gone, with no recovery.** The system will ask for confirmation. +Deletes everything under `~/.agent-wallet/`. **This is a nuclear option — once executed, all wallets, keys, and configuration are gone, with no recovery.** The system will ask for confirmation. ```bash agent-wallet reset @@ -245,7 +245,7 @@ This minimal example demonstrates how to perform a non-interactive signing opera set -e # 1. Password should already be set in the environment before running this script. -# e.g. via ~/.zshrc / ~/.bashrc — see "Permanently Save and Activate the Password" in QuickStart. +# e.g. via ~/.zshrc / ~/.bashrc — see "Save and Activate the Password" in QuickStart. # NEVER hardcode a real password in a script file (it will end up in git history). if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then echo "Error: AGENT_WALLET_PASSWORD not set" >&2 diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md index 4b3f822b..44306967 100644 --- a/docs/Agent-Wallet/FAQ.md +++ b/docs/Agent-Wallet/FAQ.md @@ -37,7 +37,7 @@ The master password is the only credential for decrypting all private keys. Ther If you forget your password: - Have another backup of your private key or mnemonic? Run `agent-wallet reset`, reinitialize, and reimport. -- No backup at all? Access to that wallet is permanently lost. +- No backup at all? Access to that wallet is lost. **So do this right now**: open your password manager and store the master password. Seriously. diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md index 988d9dbd..8227db33 100644 --- a/docs/Agent-Wallet/QuickStart.md +++ b/docs/Agent-Wallet/QuickStart.md @@ -99,7 +99,7 @@ Do this right now: For OpenClaw to automatically use your wallet, you must configure the password in its runtime environment. Select the tab matching your operating system and **just copy-paste**: -### 2.1 Permanently Save and Activate the Password +### 2.1 Save and Activate the Password @@ -177,34 +177,6 @@ Whether or not you currently have the OpenClaw backend service running, make sur --- -## Step 3: Wake Up Your Agent-wallet in OpenClaw - -Your Agent-wallet is ready, the password is configured. Now open **OpenClaw** and test whether it can successfully invoke your local Agent-wallet — just like chatting with a real person. - -:::info Haven't installed OpenClaw Extension yet? -Head to [OpenClaw Extension Quick Start](../Openclaw-extension/QuickStart.md) first, then come back here. -::: - -### Zero-Risk Test 1: Check Your Address - -Type in the chat box: - -> Show me the wallet address currently bound to my local wallet (TRON network). - -The AI will automatically read your Agent-wallet and report back the wallet address you just created. **This proves the password configuration is working correctly!** - -### Zero-Risk Test 2: Let AI Sign for You - -Then say: - -> Sign this message with my wallet: "Hello Agent-wallet!" - -The AI will complete the signing locally and offline, returning a hash string. - -**Congratulations!** You didn't spend a single cent on gas fees, you never touched your private key, but you've successfully given your AI secure cryptographic signing capability. - ---- - ## You've Completed the Full Flow | I want to… | Go here | diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 833497c5..42d75768 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **Verify password is set**: Run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` to confirm the variable is set without revealing the value. 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. -3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. +3. **If password is lost**: You'll need to re-initialize the wallet. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. Passwords with special characters are supported — use single quotes when setting the environment variable. ### "Conflicting Wallet Modes" diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index 27c662e0..e628182e 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -89,7 +89,7 @@ If the server reports an invalid private key at startup, it's usually a format i `AGENT_WALLET_PASSWORD` must exactly match the master password generated when you ran `agent-wallet start`. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory. -If the password is lost, you'll need to re-initialize. **Warning: this permanently wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. +If the password is lost, you'll need to re-initialize. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details. ### TronGrid API Key not working diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index c4778527..d6e933c3 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -123,8 +123,6 @@ If you're comfortable with the command line, you can store credentials in your s 4. Press `Ctrl + X`, then `Y`, then Enter to save 5. Close the terminal, reopen it, and restart your AI tool -**Windows:** We don't recommend Windows beginners manually configure system environment variables. Please use the Agent Wallet method above. If you're using WSL, the steps are the same as Mac (but edit `~/.bashrc` instead). - Add the variables for the skills you need: ```bash @@ -147,7 +145,7 @@ export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" ### Which AI tools support Skills? -Currently: **OpenClaw** (most seamless), and any AI assistant that can read local files. +Currently: **OpenClaw** (most seamless), and any AI assistant that can read local skill files. --- diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 0de13224..6d975a30 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -9,8 +9,7 @@ Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than * Open the "Terminal" on your computer (the black window where you type commands). :::tip Can't find Terminal? No worries -**Mac:** Press `Command + Space`, type `Terminal` in the search box, hit Enter. The black window appears. -**Windows:** Press `Win + R`, type `cmd` in the popup, hit Enter. +Press `Command + Space`, type `Terminal` in the search box, hit Enter. The black window appears. ::: **Copy this entire line**, paste it into the black window, and press Enter: @@ -71,8 +70,6 @@ We recommend using **Agent Wallet**. Think of it as opening a dedicated payment If you don't want to install another tool and just want to start trading right away, you can paste your private key into a simple config file on your computer — like editing a notepad: -**🍎 Mac Users:** - 1. In Terminal (the black window), type `open -e ~/.zshrc` and press Enter. 2. A text editor window will pop up. Scroll to the very bottom, start a new line, and paste your TRON private key: ```bash @@ -81,15 +78,6 @@ If you don't want to install another tool and just want to start trading right a ⚠️ Important: Don't forget the double quotes on both sides! 3. Press `Command + S` to save, then close the editor. -**🪟 Windows (WSL) Users:** - -1. In the WSL terminal, type `notepad.exe ~/.bashrc` and press Enter. -2. At the very bottom of the notepad that opens, paste the same line: - ```bash - export TRON_PRIVATE_KEY="your_real_or_testnet_private_key" - ``` -3. Press `Ctrl + S` to save, then close the notepad. - :::danger Critical Step No matter which option you chose, you must **completely close and reopen your AI tool** for it to pick up the new key! ::: diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md index 722dcc1f..4f2d2a6a 100644 --- a/docs/Openclaw-extension/QuickStart.md +++ b/docs/Openclaw-extension/QuickStart.md @@ -20,7 +20,6 @@ Before you begin, make sure the following basic software is installed on your co Open the "Terminal" on your computer (that black window). - **Mac:** Press `Command + Space`, type `Terminal` in the search box, and hit Enter. -- **Windows:** You'll need to install WSL (Windows Subsystem for Linux) first, then open the WSL terminal. **Copy the entire line below**, paste it into the terminal, and press Enter: @@ -107,8 +106,6 @@ Once you have the corresponding key, choose the simple method below based on its #### 🔧 Type A Keys: Add to "Hidden Notepad" (For TRONGRID and TRONSCAN) -**🍎 Mac Users:** - 1. Type `open -e ~/.zshrc` in the terminal and press Enter. 2. At the bottom of the text editor that opens, paste these lines (keep the double quotes `""`): ``` @@ -117,16 +114,6 @@ Once you have the corresponding key, choose the simple method below based on its ``` 3. Press `Command + S` to save and close, then reopen the terminal or restart OpenClaw for changes to take effect. -**🪟 Windows (WSL) Users:** - -1. Type `notepad.exe ~/.bashrc` in the terminal and press Enter. -2. At the bottom of the text editor that opens, paste the same lines: - ``` - export TRONGRID_API_KEY="paste_your_TronGrid_Key_here" - export TRONSCAN_API_KEY="paste_your_TronScan_Key_here" - ``` -3. Press `Ctrl + S` to save and close, then reopen the terminal or restart OpenClaw for changes to take effect. - #### 🔧 Type B Keys: One-Click Config File (For BANK OF AI) If you have this key, simply copy and run the following command in the terminal (remember to replace the placeholder with your actual key): diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md index 75ce0900..291f80ce 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md @@ -165,7 +165,7 @@ jobs: ### 方式 B：密码本地缓存（便利性与安全性的取舍） -执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： +执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量： ```bash agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets @@ -196,7 +196,7 @@ agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' ``` :::danger 安全提示 -直接用 `-p` 传递密码时，明文密码会被永久留在你电脑的终端 `history`（历史记录）中。强烈建议仅在完全隔离的测试环境中使用此方法！ +直接用 `-p` 传递密码时，明文密码会被留在你电脑的终端 `history`（历史记录）中。强烈建议仅在完全隔离的测试环境中使用此方法！ ::: ### 自定义存储目录 @@ -247,7 +247,7 @@ CLI 不只是拿来手敲的——它可以完美嵌入你的自动化脚本。 set -e # 1. 密码应在运行此脚本之前已在环境中设置好。 -# 例如通过 ~/.zshrc / ~/.bashrc — 详见快速开始中的"永久保存并使密码生效"。 +# 例如通过 ~/.zshrc / ~/.bashrc — 详见快速开始中的"保存并使密码生效"。 # 切勿在脚本文件中硬编码真实密码（密码会随脚本进入 git 历史记录）。 if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then echo "错误：AGENT_WALLET_PASSWORD 未设置" >&2 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md index b6d20c14..59452cac 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md @@ -37,7 +37,7 @@ agent-wallet add 如果你忘了密码： - 有私钥或助记词的其他备份？运行 `agent-wallet reset`，重新初始化，重新导入 -- 什么备份都没有？那个钱包的访问权限就永久丢失了 +- 什么备份都没有？那个钱包的访问权限就丢失了 **所以请现在就做这件事**：打开密码管理器，把主密码存进去。认真的。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md index 809936c4..5fb74d6e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md @@ -99,7 +99,7 @@ Active wallet: default 为了让 OpenClaw 能自动使用你的钱包，你必须把密码配置到它的运行环境中。请根据你的电脑系统，选择对应的标签页，**无脑复制执行**即可。 -### 2.1 永久保存并使密码生效 +### 2.1 保存并使密码生效 @@ -177,34 +177,6 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!" # 实际值变为 "P@ss!" --- -## 第三步：在 OpenClaw 里唤醒你的 Agent-wallet - -Agent-wallet 建好了，密码也配好了。现在打开 **OpenClaw**，就像和真人聊天一样，测试一下它能不能成功调用你的本地 Agent-wallet。 - -:::info 还没装 OpenClaw Extension？ -先去 [OpenClaw Extension 快速开始](../Openclaw-extension/QuickStart.md) 安装好，再回来继续。 -::: - -### 零风险测试 1：查地址 - -在聊天框里输入： - -> 帮我查一下我当前绑定的本地钱包地址（TRON 网络）。 - -AI 代理会自动读取你的 Agent-wallet，并准确报出你刚才创建的钱包地址。**这证明密码配置完全正确！** - -### 零风险测试 2：让 AI 代理替你签名 - -接着对它说： - -> 用我的钱包签名这段话："Hello Agent-wallet!" - -AI 代理会在本地离线完成签名，并返回一串哈希字符。 - -**恭喜！** 全程没花一分钱 Gas 费，你也完全没接触私钥，但你已经成功让 AI 代理拥有了安全的密码学签名能力。 - ---- - ## 你已经跑通了全流程 | 我想… | 去这里 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 4a820dd4..dd2f8ff1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' 1. **验证密码已设置**：运行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 确认变量已设置（不会泄露密码明文）。 2. **检查钱包目录**：确认 `~/.agent-wallet/` 存在并包含钱包文件。如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -3. **密码丢失**：需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 +3. **密码丢失**：需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。含有特殊字符的密码是受支持的——设置环境变量时请使用单引号。 ### "Conflicting wallet modes" diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index b755dd7d..c41cf206 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -89,7 +89,7 @@ `AGENT_WALLET_PASSWORD` 必须与运行 `agent-wallet start` 时生成的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 -如果密码丢失，需要重新初始化钱包。**警告：此操作会永久清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 +如果密码丢失，需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ)。 ### TronGrid API Key 不生效 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index f412fb68..2874304a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -123,8 +123,6 @@ AI 的应对策略是：先给你看报价，你确认后在实际提交前会 4. 按 `Ctrl + X`，再按 `Y`，再按回车——保存完毕 5. 关掉终端，重新打开，然后重启你的 AI 工具 -**Windows 电脑：** 不建议 Windows 新手折腾系统环境变量，请直接使用上面的 Agent Wallet 方法。如果你使用的是 WSL 环境，配置方式同苹果电脑（文件路径改为 `~/.bashrc`）。 - 根据你需要的技能，把对应的内容粘贴进去： ```bash @@ -147,7 +145,7 @@ export BANKOFAI_API_KEY="你的 BANK OF AI API Key" ### 哪些 AI 工具能用这些技能？ -目前支持：**OpenClaw**（最省心），以及任何能读取本地文件的 AI 助手。 +目前支持：**OpenClaw**（最省心），以及任何能读取本地技能文件的 AI 助手。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md index 7614d016..1be4c285 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -9,8 +9,7 @@ 打开你电脑上的"终端"（就是那个黑框框）。 :::tip 找不到终端？别慌 -**苹果电脑：** 按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车，黑框框就出来了。 -**Windows 电脑：** 按 `Win + R`，在弹出的小窗口里输入 `cmd`，按回车。 +按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车，黑框框就出来了。 ::: 把下面这行代码**整行复制**，粘贴到黑框框里，按回车： @@ -71,8 +70,6 @@ AI 能准确描述功能——恭喜，安装成功！ 如果你嫌麻烦，不想装新工具，只想马上体验交易，你也可以像改普通记事本一样，直接把你的私钥贴在电脑的"隐形便签"里： -**🍎 苹果电脑 (Mac) 用户：** - 1. 在终端（黑框框）输入 `open -e ~/.zshrc` 并按回车。 2. 电脑会弹出一个记事本窗口。滑到最底下，新起一行，把你的波场私钥粘贴进去： ```bash @@ -81,15 +78,6 @@ AI 能准确描述功能——恭喜，安装成功！ ⚠️ 注意：两边的英文双引号千万别漏掉！ 3. 按 `Command + S` 保存，关掉记事本。 -**🪟 Windows 电脑 (WSL) 用户：** - -1. 在 WSL 终端输入 `notepad.exe ~/.bashrc` 并按回车。 -2. 在弹出的记事本最底下，粘贴同样的代码： - ```bash - export TRON_PRIVATE_KEY="你的真实或测试网私钥" - ``` -3. 按 `Ctrl + S` 保存，关掉记事本。 - :::danger 极其重要的一步 无论你用哪种方案配好了钥匙，都必须**彻底关闭并重新打开你的 AI 软件**，它才能拿到这把新钥匙！ ::: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md index bdd487d5..73590b1d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -20,7 +20,6 @@ 打开你电脑上的"终端"（也就是那个黑框框）。 - **苹果电脑：** 按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车。 -- **Windows 电脑：** 需要先装 WSL（Windows 子系统），然后打开 WSL 终端。 把下面这行神奇的代码**完整复制**，粘贴进去，按回车： @@ -107,8 +106,6 @@ curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads #### 🔧 A 类钥匙：填入"隐形便签"（适用于 TRONGRID 和 TRONSCAN） -**🍎 苹果电脑 (Mac) 用户：** - 1. 在终端输入 `open -e ~/.zshrc` 并回车。 2. 在弹出的记事本最下方，粘贴这行代码（注意保留双引号 `""`）： ``` @@ -117,16 +114,6 @@ curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads ``` 3. 按 `Command + S` 保存关闭，然后重新打开终端或重启 OpenClaw 即可生效。 -**🪟 Windows 电脑 (WSL) 用户：** - -1. 在终端输入 `notepad.exe ~/.bashrc` 并回车。 -2. 在弹出的记事本最下方，粘贴同样的代码： - ``` - export TRONGRID_API_KEY="你的TronGrid_Key填在这里" - export TRONSCAN_API_KEY="你的TronScan_Key填在这里" - ``` -3. 按 `Ctrl + S` 保存关闭，然后重新打开终端或重启 OpenClaw 即可生效。 - #### 🔧 B 类钥匙：一键生成配置文件（适用于 BANK OF AI） 如果你拿到了这把钥匙，直接在终端（黑框框）里复制并运行下面的整段代码即可（记得把中文部分替换成你的真实 Key）： From 249c43be0eff64a96f451fecc97a4d0fce58695d Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Mon, 23 Mar 2026 23:49:02 +0800 Subject: [PATCH 37/44] Update Official Cloud Service MCP Usage Steps --- .../MCP/SUNMCPServer/OfficialServerAccess.md | 83 ++------------ .../MCP/TRONMCPServer/OfficialServerAccess.md | 108 ++---------------- .../MCP/SUNMCPServer/OfficialServerAccess.md | 85 ++------------ .../MCP/TRONMCPServer/OfficialServerAccess.md | 107 ++--------------- 4 files changed, 37 insertions(+), 346 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 3ff3e4e3..da1e4019 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -4,19 +4,17 @@ The official cloud service is a SUN MCP Server instance hosted by **BANK OF AI**, providing AI clients with **read-only query capabilities for SunSwap on-chain data**. -If you want your AI assistant to query token prices, pool APYs, or protocol trading volume on SunSwap, or analyze a specific address's liquidity positions — these are all read-only operations that can be completed via the official cloud service, with no local installation required and no wallet credentials needed. +If you want your AI assistant to query token prices, pool APYs, or protocol trading volume on SunSwap, or analyze a specific address's liquidity positions — these are all read-only operations that can be completed via the official cloud service, with no wallet credentials needed. **The core purpose of the official cloud service is to handle all infrastructure for you.** You only need to add a single service URL to your AI client's configuration to start interacting with SunSwap. ### Key Advantages -**1. No local installation required** — No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready in under 2 minutes. +**1. No private key exposure risk** — Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This eliminates key leakage risks and makes team sharing straightforward. -**2. No private key exposure risk** — Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This eliminates key leakage risks and makes team sharing straightforward. +**2. Official maintenance and continuous updates** — The service always runs the latest stable version, including SunSwap protocol updates and SUN.IO API synchronization. No manual rebuilds needed. -**3. Official maintenance and continuous updates** — The service always runs the latest stable version, including SunSwap protocol updates and SUN.IO API synchronization. No manual rebuilds needed. - -**4. Covers a large number of practical use cases** — Querying token prices and swap quotes, analyzing pool data and APYs, getting protocol statistics and historical metrics, viewing user liquidity positions — all the most commonly used DeFi data queries are fully supported. Only when you need to actually execute swaps or manage liquidity do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). +**3. Covers a large number of practical use cases** — Querying token prices and swap quotes, analyzing pool data and APYs, getting protocol statistics and historical metrics, viewing user liquidity positions — all the most commonly used DeFi data queries are fully supported. Only when you need to actually execute swaps or manage liquidity do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). > In short: **The official cloud service acts as a "read-only data gateway" for SunSwap** — AI clients only need the service URL to query all public data on SunSwap. @@ -28,84 +26,19 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect -Add the following MCP service endpoint to your AI client configuration: - -**`https://sun-mcp-server.bankofai.io/mcp`** - -> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. - ---- - -## Client Configuration - -If you want to integrate SUN MCP Server into your own application, you can call it via standard HTTP requests. - -**Step 1: Initialize Connection** +Simply tell your AI Agent to execute the following command: ```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -The response will include an `mcp-session-id` header — you will need it for subsequent requests. - -**Step 2: Call a Tool** - -Use the `mcp-session-id` from Step 1: - -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "getPrice", - "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} - }, - "id": 2 - }' -``` - -**Step 3: Discover Available Tools** - -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` - -:::info Session Management -- Each `initialize` creates a new session -- Sessions automatically expire after 30 minutes of inactivity -- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session -::: +Once the command completes, the MCP Server is ready to use — your AI Agent can immediately start interacting with SunSwap. --- ## Verify Connection -After configuration, **fully quit and restart** your AI client, then enter the following test query: +Once connected, you can test by asking your AI Agent the following question: ``` Check the current prices of USDT and TRX on SunSwap diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 67f8ae12..ba31e767 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -17,15 +17,11 @@ This is far too much overhead for users who simply want to check a balance. ### Key Advantages -**1. No local installation required** - -No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready to use. The entire process usually takes no more than 2 minutes. - -**2. No private key exposure risk** +**1. No private key exposure risk** Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This fundamentally eliminates risks like key leakage and config files accidentally committed to Git. It's especially convenient for team collaboration — any member can connect directly without key distribution or management concerns. -**3. Official maintenance and continuous updates** +**2. Official maintenance and continuous updates** The cloud service is maintained by the official team and always runs the latest stable version of TRON MCP Server. This includes: @@ -35,7 +31,7 @@ The cloud service is maintained by the official team and always runs the latest You don't need to worry about version numbers or manually run `npm install` or rebuild. -**4. Covers the vast majority of real-world use cases** +**3. Covers the vast majority of real-world use cases** The most common daily operations — checking address balances, analyzing transaction details, reading contract state, viewing the Super Representative list, monitoring on-chain events — are all read-only queries, fully supported through the cloud service. Only when you need to actually move assets (transfers, staking, contract writes) do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). @@ -49,9 +45,13 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect -To connect to the official cloud service, simply add the official **MCP service URL** to your AI client configuration: [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) +Simply tell your AI Agent to execute the following command: + +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp +``` -> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. +Once the command completes, the MCP Server is ready to use — your AI Agent can immediately start interacting with the TRON blockchain. The official cloud service supports **two usage modes**: @@ -85,101 +85,15 @@ For frequent mainnet queries, apply for a free TronGrid API Key to get a higher 1. Visit [trongrid.io](https://www.trongrid.io/) 2. Register an account and create a project 3. Copy the generated API Key -4. Add the API Key header in your configuration (see client configuration examples below) +4. Add the API Key header in your requests After configuring the API Key, your requests will go through TronGrid's authenticated channel, with more stable performance and higher throughput. --- -## Client Configuration - -You can connect to the official cloud service via HTTP requests. Here's how: - -**Step 1: Initialize Connection** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' -``` - -The response will include a `mcp-session-id` header — you'll need it for subsequent requests. - -**Step 2: Call a Tool** - -Use the `mcp-session-id` from Step 1: - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' -``` - -To use a TronGrid API Key with the cloud service, add the header: - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -H "TRONGRID-API-KEY:your-api-key" \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' -``` - -**Step 3: Discover Available Tools** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` - -:::info Session Management -- Each `initialize` creates a new session -- Sessions automatically expire after 30 minutes of inactivity -- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session -::: - ---- - ## Verify Connection -After completing configuration, **fully exit and restart** your AI client, then enter the following test prompt: +Once connected, you can test by asking your AI Agent the following question: ``` Query the current block height of TRON mainnet diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 714ffa2d..cf147768 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -4,25 +4,21 @@ 官方云服务是由 **BANK OF AI** 托管的 SUN MCP Server 实例，用于为 AI 客户端提供 **SunSwap 链上数据的只读查询能力**。 -如果你想让 AI 助手查询 SunSwap 上的代币价格、池子 APY、协议交易量，或者分析某个地址的流动性持仓——这些都是只读操作，通过官方云服务即可完成，不需要在本地安装任何东西，也不需要提供任何钱包凭证。 +如果你想让 AI 助手查询 SunSwap 上的代币价格、池子 APY、协议交易量，或者分析某个地址的流动性持仓——这些都是只读操作，通过官方云服务即可完成，不需要提供任何钱包凭证。 **官方云服务的核心作用，就是将基础设施工作全部托管。** 你只需要在 AI 客户端的配置中添加一行服务地址，即可开始与 SunSwap 对话。 ### 使用官方云服务的主要优点 -**1. 无需任何本地安装** - -不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 - -**2. 无私钥暴露风险** +**1. 无私钥暴露风险** 由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露的风险。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 -**3. 官方维护与持续升级** +**2. 官方维护与持续升级** 云服务始终运行最新稳定版本，包括 SunSwap 协议更新的适配和 SUN.IO API 的同步。你无需关心版本号，也不需要手动重新构建。 -**4. 覆盖大量实用场景** +**3. 覆盖大量实用场景** 查询代币价格和兑换报价、分析池子数据和 APY、获取协议统计和历史指标、查看用户流动性持仓——这些日常最常用的 DeFi 数据查询，通过云服务全部可以完成。只有当你需要实际执行兑换或管理流动性时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 @@ -36,84 +32,19 @@ ## 如何接入官方云服务？ -要接入官方云服务，只需在 AI 客户端配置中添加以下 MCP 服务地址： - -**`https://sun-mcp-server.bankofai.io/mcp`** - -> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 - ---- - -## 客户端配置 - -如果你想将 SUN MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 - -**第一步：初始化连接** - -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' -``` - -响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 - -**第二步：调用工具** - -使用第一步获得的 `mcp-session-id`： +只需告诉你的 AI Agent 执行以下命令： ```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "getPrice", - "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} - }, - "id": 2 - }' +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -**第三步：查看可用工具列表** - -```bash -curl -X POST https://sun-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` - -:::info Session 管理 -- 每次 `initialize` 会创建一个新 Session -- Session 在 30 分钟无活动后自动过期 -- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session -::: +执行完成后，即可使用相关 MCP Server，你的 AI Agent 可以立即开始与 SunSwap 交互。 --- ## 验证接入是否成功 -配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： +接入完成后，你可以直接向 AI Agent 提出以下问题来测试： ``` 查一下 SunSwap 上 USDT 和 TRX 的当前价格 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 7c920ef4..038e8e0d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -17,15 +17,11 @@ ### 使用官方云服务的主要优点 -**1. 无需任何本地安装** - -不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 - -**2. 无私钥暴露风险** +**1. 无私钥暴露风险** 由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露、配置文件被误提交到 Git 等安全隐患。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 -**3. 官方维护与持续升级** +**2. 官方维护与持续升级** 云服务由官方统一维护，始终运行最新稳定版本的 TRON MCP Server。包括： @@ -35,7 +31,7 @@ 你无需关心版本号，也不需要手动执行 `npm install` 或重新构建。 -**4. 覆盖绝大部分真实场景** +**3. 覆盖绝大部分真实场景** 日常中最常用的操作——查地址余额、分析交易详情、读取合约状态、查看超级代表列表、监控链上事件——全部属于只读查询，通过云服务就能完整覆盖。只有当你需要实际转移资产（转账、质押、合约写入等）时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 @@ -49,10 +45,13 @@ ## 如何接入官方云服务？ -要接入官方云服务，只需要在 AI 客户端配置中添加官方提供的 **MCP 服务地址**：[https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) +只需告诉你的 AI Agent 执行以下命令： +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp +``` -> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 +执行完成后，即可使用相关 MCP Server，你的 AI Agent 可以立即开始与 TRON 区块链交互。 官方云服务支持 **两种使用模式**： @@ -86,101 +85,15 @@ 1. 访问 [trongrid.io](https://www.trongrid.io/) 2. 注册账号并创建项目 3. 复制生成的 API Key -4. 在配置中添加 API Key 请求头（见下方客户端配置示例） +4. 在请求中添加 API Key 请求头 配置 API Key 后，你的请求会通过 TronGrid 的认证通道，享受更稳定的性能和更高的吞吐量。 --- -## 客户端配置 - -你可以通过 HTTP 请求连接到官方云服务。下面是具体步骤： - -**第一步：初始化连接** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -d '{ - "jsonrpc": "2.0", - "method": "initialize", - "params": { - "protocolVersion": "2025-03-26", - "capabilities": {}, - "clientInfo": {"name": "my-client", "version": "1.0"} - }, - "id": 1 - }' -``` - -响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 - -**第二步：调用工具** - -使用第一步获得的 `mcp-session-id`： - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' -``` - -要使用 TronGrid API Key，在请求头中添加： - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -H "TRONGRID-API-KEY:your-api-key" \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "get_chain_info", - "arguments": {"network": "mainnet"} - }, - "id": 2 - }' -``` - -**第三步：查看可用工具列表** - -```bash -curl -X POST https://tron-mcp-server.bankofai.io/mcp \ - -H "Content-Type: application/json" \ - -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ - -d '{ - "jsonrpc": "2.0", - "method": "tools/list", - "params": {}, - "id": 3 - }' -``` - -:::info Session 管理 -- 每次 `initialize` 会创建一个新 Session -- Session 在 30 分钟无活动后自动过期 -- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session -::: - ---- - ## 验证接入是否成功 -配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： +接入完成后，你可以直接向 AI Agent 提出以下问题来测试： ``` 查询 TRON 主网当前的区块高度 From 6b6423b8c54a2be9aaa241d0ac2f194bdb12490b Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 00:07:01 +0800 Subject: [PATCH 38/44] delete tron mcp server trongrid --- .../MCP/TRONMCPServer/OfficialServerAccess.md | 36 ------------------- .../MCP/TRONMCPServer/OfficialServerAccess.md | 36 ------------------- 2 files changed, 72 deletions(-) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index ba31e767..b2501c8c 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -53,42 +53,6 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp Once the command completes, the MCP Server is ready to use — your AI Agent can immediately start interacting with the TRON blockchain. -The official cloud service supports **two usage modes**: - -| Mode | Rate Limit | Description | -| :--- | :--- | :--- | -| **Without TronGrid API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | -| **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | - -Both modes use the same connection method — the only difference is the request rate limit. - ---- - -### Without TronGrid API Key Mode (Default) - -No API Key configuration needed to get started. Best for: - -- First-time experience with TRON MCP Server -- Occasional on-chain data queries -- Teaching, demos, and feature verification - -In this mode, all tools are available, but mainnet queries under high-frequency usage may trigger TronGrid's public RPC rate limits. - ---- - -### With TronGrid API Key Mode (Recommended) - -For frequent mainnet queries, apply for a free TronGrid API Key to get a higher request rate limit. - -**How to apply:** - -1. Visit [trongrid.io](https://www.trongrid.io/) -2. Register an account and create a project -3. Copy the generated API Key -4. Add the API Key header in your requests - -After configuring the API Key, your requests will go through TronGrid's authenticated channel, with more stable performance and higher throughput. - --- ## Verify Connection diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 038e8e0d..15c74c67 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -53,42 +53,6 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp 执行完成后，即可使用相关 MCP Server，你的 AI Agent 可以立即开始与 TRON 区块链交互。 -官方云服务支持 **两种使用模式**： - -| 模式 | 限速 | 说明 | -| :--- |--- |:--- | -| **无 TronGrid API Key（默认）** | 100,000 Requests / Day |即开即用，适合入门体验和低频查询 | -| **带 TronGrid API Key** | 500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | - -两种模式的接入方式完全相同，区别仅在于请求频率限制。 - ---- - -### 无 TronGrid API Key 模式（默认） - -不配置任何 API Key 即可直接使用。适用于： - -- 首次体验 TRON MCP Server -- 偶尔查询链上数据 -- 教学演示和功能验证 - -在这种模式下，所有工具均可正常调用，但主网查询在高频场景下可能触发 TronGrid 公共 RPC 的速率限制。 - ---- - -### 带 TronGrid API Key 模式（推荐） - -如果你需要频繁查询主网数据，建议申请一个免费的 TronGrid API Key 以获得更高的请求频率上限。 - -**申请步骤：** - -1. 访问 [trongrid.io](https://www.trongrid.io/) -2. 注册账号并创建项目 -3. 复制生成的 API Key -4. 在请求中添加 API Key 请求头 - -配置 API Key 后，你的请求会通过 TronGrid 的认证通道，享受更稳定的性能和更高的吞吐量。 - --- ## 验证接入是否成功 From 65940fedd8432d3b70320c64a72ecd0ca7450776 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 00:11:14 +0800 Subject: [PATCH 39/44] add restart ai agnet --- docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md | 2 +- docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md | 2 +- .../McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md | 2 +- .../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index da1e4019..992cc312 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -32,7 +32,7 @@ Simply tell your AI Agent to execute the following command: npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -Once the command completes, the MCP Server is ready to use — your AI Agent can immediately start interacting with SunSwap. +Once the command completes, restart your AI Agent, and the MCP Server is ready to use — you can start interacting with SunSwap. --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index b2501c8c..bf3136f7 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -51,7 +51,7 @@ Simply tell your AI Agent to execute the following command: npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` -Once the command completes, the MCP Server is ready to use — your AI Agent can immediately start interacting with the TRON blockchain. +Once the command completes, restart your AI Agent, and the MCP Server is ready to use — you can start interacting with the TRON blockchain. --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index cf147768..d36c69e4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -38,7 +38,7 @@ npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -执行完成后，即可使用相关 MCP Server，你的 AI Agent 可以立即开始与 SunSwap 交互。 +执行完成后，重启 AI Agent，即可使用相关 MCP Server，开始与 SunSwap 交互。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 15c74c67..4c045fc3 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -51,7 +51,7 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` -执行完成后，即可使用相关 MCP Server，你的 AI Agent 可以立即开始与 TRON 区块链交互。 +执行完成后，重启 AI Agent，即可使用相关 MCP Server，开始与 TRON 区块链交互。 --- From 4c3b71b801f22690525298548017ce4f5d633fb7 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 00:17:00 +0800 Subject: [PATCH 40/44] fix --- .../current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 1 + 1 file changed, 1 insertion(+) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md index c41cf206..84f200bc 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -209,3 +209,4 @@ npm run build ### 支持哪个 MCP 协议版本？ TRON MCP Server 支持 MCP 协议版本 **2025-11-25**，使用 `@modelcontextprotocol/sdk` 1.22.0 或更高版本。 + From b9fb0ccc4ac7c2270783f70fd401c95cbd6fa041 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 15:25:53 +0800 Subject: [PATCH 41/44] update setup process --- .../MCP/SUNMCPServer/OfficialServerAccess.md | 65 ++++++++++- .../MCP/SUNMCPServer/QuickStart.md | 4 +- .../MCP/TRONMCPServer/OfficialServerAccess.md | 65 ++++++++++- .../MCP/TRONMCPServer/QuickStart.md | 4 +- docs/McpServer-Skills/SKILLS/QuickStart.md | 109 ++++++++++++++++-- .../MCP/SUNMCPServer/OfficialServerAccess.md | 65 ++++++++++- .../MCP/SUNMCPServer/QuickStart.md | 4 +- .../MCP/TRONMCPServer/OfficialServerAccess.md | 65 ++++++++++- .../MCP/TRONMCPServer/QuickStart.md | 4 +- .../McpServer-Skills/SKILLS/QuickStart.md | 109 ++++++++++++++++-- 10 files changed, 466 insertions(+), 28 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 992cc312..d9df0a09 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -32,7 +32,70 @@ Simply tell your AI Agent to execute the following command: npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -Once the command completes, restart your AI Agent, and the MCP Server is ready to use — you can start interacting with SunSwap. +:::tip +This guide demonstrates the installation process using terminal commands as an example. +::: + +### Installation Walkthrough + +The installer will guide you through a few steps — just follow along: + +**1️⃣ Identify the service source** + +The installer automatically detects the remote MCP service URL and generates a server name: + +``` +◇ Source: https://sun-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: sun-mcp-server +``` + +**2️⃣ Choose which AI tools to install to** + +The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor, Cline, etc.). Use Space to select the ones you want: + +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code +``` + +**3️⃣ Confirm installation details** + +The installer displays an installation summary. Review it and select `Yes` to proceed: + +``` +◇ Installation Summary ───╮ +│ │ +│ Server: sun-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├──────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes +``` + +**4️⃣ Installation complete!** + +When you see output like this, SUN MCP Server has been successfully installed to your selected AI tools: + +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` + +Once installation is complete, restart your AI Agent, and you can start interacting with SunSwap via SUN MCP Server. --- diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 3b07cca9..89c957d2 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -17,10 +17,10 @@ Before you get started, make sure you have: ## Install -Run the following command in the terminal to add SUN MCP Server: +Simply tell your AI Agent to execute the following command: ```bash -npx add-mcp @bankofai/sun-mcp-server +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` After the command completes, restart your MCP client. diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index bf3136f7..754d0627 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -51,7 +51,70 @@ Simply tell your AI Agent to execute the following command: npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` -Once the command completes, restart your AI Agent, and the MCP Server is ready to use — you can start interacting with the TRON blockchain. +:::tip +This guide demonstrates the installation process using terminal commands as an example. +::: + +### Installation Walkthrough + +The installer will guide you through a few steps — just follow along: + +**1️⃣ Identify the service source** + +The installer automatically detects the remote MCP service URL and generates a server name: + +``` +◇ Source: https://tron-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: tron-mcp-server +``` + +**2️⃣ Choose which AI tools to install to** + +The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor, Cline, etc.). Use Space to select the ones you want: + +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code +``` + +**3️⃣ Confirm installation details** + +The installer displays an installation summary. Review it and select `Yes` to proceed: + +``` +◇ Installation Summary ────╮ +│ │ +│ Server: tron-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├───────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes +``` + +**4️⃣ Installation complete!** + +When you see output like this, TRON MCP Server has been successfully installed to your selected AI tools: + +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` + +Once installation is complete, restart your AI Agent, and you can start interacting with the TRON blockchain via TRON MCP Server. --- diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index 9d4141d7..a308b3cb 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -23,10 +23,10 @@ node --version # should output v20.x.x or higher ## Add Configuration -Run the following command in your terminal: +Simply tell your AI Agent to execute the following command: ```bash -npx add-mcp @bankofai/mcp-server-tron +npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` After the command completes, restart your MCP client. diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 6d975a30..94cc08e9 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -6,21 +6,114 @@ Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than * ## Step 1: Install the Skills -Open the "Terminal" on your computer (the black window where you type commands). +Simply tell your AI Agent to execute the following command: -:::tip Can't find Terminal? No worries -Press `Command + Space`, type `Terminal` in the search box, hit Enter. The black window appears. +```bash +npx skills add https://github.com/BofAI/skills +``` + +:::tip +This guide demonstrates the installation process using terminal commands as an example. If you prefer to install manually, open the Terminal on your computer (press `Command + Space`, type `Terminal`, hit Enter), paste the command above, and press Enter. ::: -**Copy this entire line**, paste it into the black window, and press Enter: +### Installation Walkthrough -```bash -npx skills add https://github.com/BofAI/skills +The installer will guide you through a few steps — just follow along: + +**1️⃣ Confirm tool installation** + +Terminal will ask you to install the `skills` package. Type `y` and press Enter: + +``` +Need to install the following packages: + skills@1.4.6 +Ok to proceed? (y) y ``` -A bunch of text will scroll across the screen — **you can ignore it**. Just wait for it to stop. This command will install all BANK OF AI skills at once. +**2️⃣ Select which Skills to install** + +The installer automatically fetches all available Skills from the repo and lists them for selection. Press **Space** to toggle each one — we recommend selecting all: + +``` +◇ Found 6 skills +│ +◇ Select skills to install (space to toggle) +│ Multi-Sig & Account Permissions, recharge-skill, +│ SunPerp Perpetual Futures Trading, SunSwap DEX Trading, +│ TronScan Data Lookup, x402-payment +``` + +:::tip Select all +Unless you're sure you only need specific skills, install them all. Skills use an on-demand architecture — unused skills consume zero resources. +::: + +**3️⃣ Choose which AI tools to install to** + +The installer auto-detects AI tools on your computer (e.g., Cursor, Claude Code, Cline, etc.). Use Space to select the ones you want: + +``` +◇ 43 agents +◇ Which agents do you want to install to? +│ Amp, Antigravity, Cline, Codex, Cursor, Deep Agents, +│ Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp +``` + +**4️⃣ Choose installation scope** + +Select `Project` (current project only) or `User` (globally available across all projects): + +``` +◇ Installation scope +│ Project +``` + +**5️⃣ Review security assessment & confirm** + +The installer runs a security scan on each Skill and shows the results. Review them and select `Yes` to proceed: + +``` +◇ Security Risk Assessments ──────────────────────────────╮ +│ │ +│ Gen Socket Snyk │ +│ Multi-Sig & Account Permissions -- -- -- │ +│ recharge-skill -- -- -- │ +│ SunPerp Perpetual Futures Trading -- -- -- │ +│ SunSwap DEX Trading -- -- -- │ +│ TronScan Data Lookup -- -- -- │ +│ x402-payment Med 1 alert Med │ +│ │ +├──────────────────────────────────────────────────────────╯ + +◇ Proceed with installation? +│ Yes +``` + +**6️⃣ Installation complete!** + +When you see output like this, all Skills have been successfully installed to your selected AI tools: + +``` +◇ Installed 6 skills ────────────────────────╮ +│ │ +│ ✓ Multi-Sig & Account Permissions (copied) │ +│ ✓ recharge-skill (copied) │ +│ ✓ SunPerp Perpetual Futures Trading (copied)│ +│ ✓ SunSwap DEX Trading (copied) │ +│ ✓ TronScan Data Lookup (copied) │ +│ ✓ x402-payment (copied) │ +│ │ +├─────────────────────────────────────────────╯ + +└ Done! +``` + +:::tip Optional: Install find-skills +After installation, you may be prompted to install `find-skills` — a helper that lets your AI automatically discover and suggest new skills. We recommend selecting `Yes`. +::: + +### Verify Installation -When it's done, verify the installation was successful by asking your AI: +Open your AI chat and type: ``` Read the sunswap skill and tell me what it can do. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index d36c69e4..ccff04b1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -38,7 +38,70 @@ npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` -执行完成后，重启 AI Agent，即可使用相关 MCP Server，开始与 SunSwap 交互。 +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。 +::: + +### 安装过程详解 + +安装器会引导你完成以下几步，照着做就行： + +**1️⃣ 识别服务来源** + +安装器会自动识别远程 MCP 服务地址，并为其生成服务名称： + +``` +◇ Source: https://sun-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: sun-mcp-server +``` + +**2️⃣ 选择要安装到哪些 AI 工具** + +安装器会自动检测你电脑上装了哪些 AI 工具（如 Claude Code、Cursor、Cline 等），用空格键勾选你要用的： + +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code +``` + +**3️⃣ 确认安装信息** + +安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装： + +``` +◇ Installation Summary ───╮ +│ │ +│ Server: sun-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├──────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes +``` + +**4️⃣ 安装完成！** + +看到类似以下输出，说明 SUN MCP Server 已经成功安装到你选择的 AI 工具中： + +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` + +安装完成后，重启 AI Agent，即可使用 SUN MCP Server 开始与 SunSwap 交互。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 2df3434e..84043575 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -17,10 +17,10 @@ ## 安装 -在终端中运行以下命令添加 SUN MCP Server： +只需告诉你的 AI Agent 执行以下命令： ```bash -npx add-mcp @bankofai/sun-mcp-server +npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` 命令完成后，重启你的 MCP 客户端。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 4c045fc3..ada8e5f4 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -51,7 +51,70 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` -执行完成后，重启 AI Agent，即可使用相关 MCP Server，开始与 TRON 区块链交互。 +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。 +::: + +### 安装过程详解 + +安装器会引导你完成以下几步，照着做就行： + +**1️⃣ 识别服务来源** + +安装器会自动识别远程 MCP 服务地址，并为其生成服务名称： + +``` +◇ Source: https://tron-mcp-server.bankofai.io/mcp (remote) +│ +● Server name: tron-mcp-server +``` + +**2️⃣ 选择要安装到哪些 AI 工具** + +安装器会自动检测你电脑上装了哪些 AI 工具（如 Claude Code、Cursor、Cline 等），用空格键勾选你要用的： + +``` +◇ Detected 1 agent +│ +◇ Select agents to install to +│ Claude Code +``` + +**3️⃣ 确认安装信息** + +安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装： + +``` +◇ Installation Summary ────╮ +│ │ +│ Server: tron-mcp-server │ +│ Type: remote │ +│ Scope: Project │ +│ Agents: Claude Code │ +│ │ +├───────────────────────────╯ +│ +◇ Proceed with installation? +│ Yes +``` + +**4️⃣ 安装完成！** + +看到类似以下输出，说明 TRON MCP Server 已经成功安装到你选择的 AI 工具中： + +``` +◇ Installation complete +│ +◇ Installed to 1 agent ───────╮ +│ │ +│ ✓ Claude Code: ~/.mcp.json │ +│ │ +├──────────────────────────────╯ +│ +└ Done! +``` + +安装完成后，重启 AI Agent，即可使用 TRON MCP Server 开始与 TRON 区块链交互。 --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index ca32d318..5d99c27a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -23,10 +23,10 @@ node --version # 应输出 v20.x.x 或更高 ## 添加配置 -在终端执行以下命令： +只需告诉你的 AI Agent 执行以下命令： ```bash -npx add-mcp @bankofai/mcp-server-tron +npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` 命令完成后，重启你的 MCP 客户端。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md index 1be4c285..617d3f28 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -6,21 +6,114 @@ ## 第 1 步：安装技能库 -打开你电脑上的"终端"（就是那个黑框框）。 +只需告诉你的 AI Agent 执行以下命令： -:::tip 找不到终端？别慌 -按 `Command + 空格`，在弹出的搜索框里输入 `Terminal`，按回车，黑框框就出来了。 +```bash +npx skills add https://github.com/BofAI/skills +``` + +:::tip 提示 +本文档以在终端中运行命令为例展示安装过程。如果你想在终端中手动安装，打开你电脑上的"终端"（按 `Command + 空格`，输入 `Terminal`，按回车），将上面的命令粘贴进去并回车即可。 ::: -把下面这行代码**整行复制**，粘贴到黑框框里，按回车： +### 安装过程详解 -```bash -npx skills add https://github.com/BofAI/skills +安装器会引导你完成以下几步，照着做就行： + +**1️⃣ 确认安装工具** + +终端会提示你需要安装 `skills` 工具包，输入 `y` 并回车即可： + +``` +Need to install the following packages: + skills@1.4.6 +Ok to proceed? (y) y ``` -屏幕上会跳出一堆英文字母——**不用管它们**，等它停下来就行。这条命令会一次性安装所有 BANK OF AI 技能。 +**2️⃣ 选择要安装的 Skills** + +安装器会自动从仓库拉取所有可用的 Skills，然后列出清单让你勾选。按**空格键**切换选中/取消，默认全选即可： + +``` +◇ Found 6 skills +│ +◇ Select skills to install (space to toggle) +│ Multi-Sig & Account Permissions, recharge-skill, +│ SunPerp Perpetual Futures Trading, SunSwap DEX Trading, +│ TronScan Data Lookup, x402-payment +``` + +:::tip 建议全选 +除非你很明确只需要某几个技能，否则建议全部安装。Skills 采用按需唤醒架构，不用的技能不会占用任何资源。 +::: + +**3️⃣ 选择要安装到哪些 AI 工具** + +安装器会自动检测你电脑上装了哪些 AI 工具（如 Cursor、Claude Code、Cline 等），用空格键勾选你要用的： + +``` +◇ 43 agents +◇ Which agents do you want to install to? +│ Amp, Antigravity, Cline, Codex, Cursor, Deep Agents, +│ Gemini CLI, GitHub Copilot, Kimi Code CLI, OpenCode, Warp +``` + +**4️⃣ 选择安装范围** + +选择 `Project`（当前项目）或 `User`（所有项目全局可用），按需选择即可： + +``` +◇ Installation scope +│ Project +``` + +**5️⃣ 查看安全评估 & 确认安装** + +安装器会对每个 Skill 进行安全风险扫描，并展示评估结果。确认无误后选择 `Yes` 开始安装： + +``` +◇ Security Risk Assessments ──────────────────────────────╮ +│ │ +│ Gen Socket Snyk │ +│ Multi-Sig & Account Permissions -- -- -- │ +│ recharge-skill -- -- -- │ +│ SunPerp Perpetual Futures Trading -- -- -- │ +│ SunSwap DEX Trading -- -- -- │ +│ TronScan Data Lookup -- -- -- │ +│ x402-payment Med 1 alert Med │ +│ │ +├──────────────────────────────────────────────────────────╯ + +◇ Proceed with installation? +│ Yes +``` + +**6️⃣ 安装完成！** + +看到类似以下输出，说明所有 Skills 已经成功安装到你选择的 AI 工具中： + +``` +◇ Installed 6 skills ────────────────────────╮ +│ │ +│ ✓ Multi-Sig & Account Permissions (copied) │ +│ ✓ recharge-skill (copied) │ +│ ✓ SunPerp Perpetual Futures Trading (copied)│ +│ ✓ SunSwap DEX Trading (copied) │ +│ ✓ TronScan Data Lookup (copied) │ +│ ✓ x402-payment (copied) │ +│ │ +├─────────────────────────────────────────────╯ + +└ Done! +``` + +:::tip 可选：安装 find-skills +安装完成后，工具可能会提示你是否安装 `find-skills`——这是一个帮 AI 自动发现和推荐新技能的辅助工具，建议选 `Yes`。 +::: + +### 验证安装 -装完后，在 AI 对话中验证： +打开你的 AI 对话框，输入： ``` 读一下 sunswap 技能，告诉我它能做什么。 From 533abedac7895e90abce1137691072167b5d58f7 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 16:18:16 +0800 Subject: [PATCH 42/44] skills quickstart Double Quotes to Single Quotes --- docs/McpServer-Skills/SKILLS/QuickStart.md | 2 +- .../current/McpServer-Skills/SKILLS/QuickStart.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 94cc08e9..1aec9227 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -166,7 +166,7 @@ If you don't want to install another tool and just want to start trading right a 1. In Terminal (the black window), type `open -e ~/.zshrc` and press Enter. 2. A text editor window will pop up. Scroll to the very bottom, start a new line, and paste your TRON private key: ```bash - export TRON_PRIVATE_KEY="your_real_or_testnet_private_key" + export TRON_PRIVATE_KEY='your_real_or_testnet_private_key' ``` ⚠️ Important: Don't forget the double quotes on both sides! 3. Press `Command + S` to save, then close the editor. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md index 617d3f28..3a3a4b4b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -166,7 +166,7 @@ AI 能准确描述功能——恭喜，安装成功！ 1. 在终端（黑框框）输入 `open -e ~/.zshrc` 并按回车。 2. 电脑会弹出一个记事本窗口。滑到最底下，新起一行，把你的波场私钥粘贴进去： ```bash - export TRON_PRIVATE_KEY="你的真实或测试网私钥" + export TRON_PRIVATE_KEY='你的真实或测试网私钥' ``` ⚠️ 注意：两边的英文双引号千万别漏掉！ 3. 按 `Command + S` 保存，关掉记事本。 From 88515e5132bec6c679d5e52f11f24c7c8f31e456 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 18:07:32 +0800 Subject: [PATCH 43/44] add setup mode --- .../MCP/SUNMCPServer/OfficialServerAccess.md | 16 +++++++++++++++- .../MCP/SUNMCPServer/QuickStart.md | 8 +++++++- .../MCP/TRONMCPServer/OfficialServerAccess.md | 16 +++++++++++++++- .../MCP/TRONMCPServer/QuickStart.md | 8 +++++++- docs/McpServer-Skills/SKILLS/QuickStart.md | 16 ++++++++++++++-- .../MCP/SUNMCPServer/OfficialServerAccess.md | 16 +++++++++++++++- .../MCP/SUNMCPServer/QuickStart.md | 8 +++++++- .../MCP/TRONMCPServer/OfficialServerAccess.md | 16 +++++++++++++++- .../MCP/TRONMCPServer/QuickStart.md | 8 +++++++- .../McpServer-Skills/SKILLS/QuickStart.md | 16 ++++++++++++++-- 10 files changed, 116 insertions(+), 12 deletions(-) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index d9df0a09..d0fa20a0 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -26,8 +26,22 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect +### Quick Auto-Install + Simply tell your AI Agent to execute the following command: +```bash +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y +``` + +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. + +Once installation is complete, restart your AI Agent, and you can start interacting with SunSwap via SUN MCP Server. + +### Interactive Installation + +If you want to choose which AI tools to install to, remove the `-y` flag: + ```bash npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` @@ -36,7 +50,7 @@ npx add-mcp https://sun-mcp-server.bankofai.io/mcp This guide demonstrates the installation process using terminal commands as an example. ::: -### Installation Walkthrough +#### Installation Walkthrough The installer will guide you through a few steps — just follow along: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 89c957d2..3bdb6064 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -20,11 +20,17 @@ Before you get started, make sure you have: Simply tell your AI Agent to execute the following command: ```bash -npx add-mcp https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y ``` +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. + After the command completes, restart your MCP client. +:::tip Want to choose which AI tools to install to? +Remove the `-y` flag to enter interactive installation mode. See [Official Cloud Service Access](./OfficialServerAccess.md) for details. +::: + --- ## Restart and Test diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 754d0627..ae00d6d4 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -45,8 +45,22 @@ The official cloud service only provides **read-only access**. It does **not sup ## How to Connect +### Quick Auto-Install + Simply tell your AI Agent to execute the following command: +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y +``` + +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. + +Once installation is complete, restart your AI Agent, and you can start interacting with the TRON blockchain via TRON MCP Server. + +### Interactive Installation + +If you want to choose which AI tools to install to, remove the `-y` flag: + ```bash npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` @@ -55,7 +69,7 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp This guide demonstrates the installation process using terminal commands as an example. ::: -### Installation Walkthrough +#### Installation Walkthrough The installer will guide you through a few steps — just follow along: diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index a308b3cb..e44c3643 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -26,11 +26,17 @@ node --version # should output v20.x.x or higher Simply tell your AI Agent to execute the following command: ```bash -npx add-mcp https://tron-mcp-server.bankofai.io/mcp +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y ``` +The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to. + After the command completes, restart your MCP client. +:::tip Want to choose which AI tools to install to? +Remove the `-y` flag to enter interactive installation mode. See [Official Cloud Service Access](./OfficialServerAccess.md) for details. +::: + --- ## Restart and Test diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md index 1aec9227..9163ca32 100644 --- a/docs/McpServer-Skills/SKILLS/QuickStart.md +++ b/docs/McpServer-Skills/SKILLS/QuickStart.md @@ -6,17 +6,29 @@ Get your AI up and running with BANK OF AI SKILLS in **2 steps** and less than * ## Step 1: Install the Skills +### Quick Auto-Install + Simply tell your AI Agent to execute the following command: +```bash +npx skills add https://github.com/BofAI/skills -y -g +``` + +The `-y` flag skips all interactive prompts and installs all available Skills by default. The `-g` flag enables global installation (available across all projects). Once complete, it will show ✅ Global installation complete! along with the full list of installed Skills. + +### Interactive Installation + +If you want to choose which Skills to install and the installation scope, remove the `-y -g` flags: + ```bash npx skills add https://github.com/BofAI/skills ``` :::tip -This guide demonstrates the installation process using terminal commands as an example. If you prefer to install manually, open the Terminal on your computer (press `Command + Space`, type `Terminal`, hit Enter), paste the command above, and press Enter. +This guide demonstrates the installation process using terminal commands as an example. ::: -### Installation Walkthrough +#### Installation Walkthrough The installer will guide you through a few steps — just follow along: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index ccff04b1..1aa5514b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -32,8 +32,22 @@ ## 如何接入官方云服务？ +### 一键自动安装 + 只需告诉你的 AI Agent 执行以下命令： +```bash +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y +``` + +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 + +安装完成后，重启 AI Agent，即可使用 SUN MCP Server 开始与 SunSwap 交互。 + +### 交互式安装 + +如果你想手动选择安装到哪些 AI 工具，去掉 `-y` 参数即可： + ```bash npx add-mcp https://sun-mcp-server.bankofai.io/mcp ``` @@ -42,7 +56,7 @@ npx add-mcp https://sun-mcp-server.bankofai.io/mcp 本文档以在终端中运行命令为例展示安装过程。 ::: -### 安装过程详解 +#### 安装过程详解 安装器会引导你完成以下几步，照着做就行： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md index 84043575..f79aed61 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -20,11 +20,17 @@ 只需告诉你的 AI Agent 执行以下命令： ```bash -npx add-mcp https://sun-mcp-server.bankofai.io/mcp +npx add-mcp https://sun-mcp-server.bankofai.io/mcp -y ``` +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 + 命令完成后，重启你的 MCP 客户端。 +:::tip 想手动选择安装到哪些 AI 工具？ +去掉 `-y` 参数即可进入交互式安装，详见[官方云服务接入](./OfficialServerAccess.md)。 +::: + --- ## 重启并测试 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index ada8e5f4..a1647e14 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -45,8 +45,22 @@ ## 如何接入官方云服务？ +### 一键自动安装 + 只需告诉你的 AI Agent 执行以下命令： +```bash +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y +``` + +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 + +安装完成后，重启 AI Agent，即可使用 TRON MCP Server 开始与 TRON 区块链交互。 + +### 交互式安装 + +如果你想手动选择安装到哪些 AI 工具，去掉 `-y` 参数即可： + ```bash npx add-mcp https://tron-mcp-server.bankofai.io/mcp ``` @@ -55,7 +69,7 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp 本文档以在终端中运行命令为例展示安装过程。 ::: -### 安装过程详解 +#### 安装过程详解 安装器会引导你完成以下几步，照着做就行： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index 5d99c27a..f8940266 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -26,11 +26,17 @@ node --version # 应输出 v20.x.x 或更高 只需告诉你的 AI Agent 执行以下命令： ```bash -npx add-mcp https://tron-mcp-server.bankofai.io/mcp +npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y ``` +`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。 + 命令完成后，重启你的 MCP 客户端。 +:::tip 想手动选择安装到哪些 AI 工具？ +去掉 `-y` 参数即可进入交互式安装，详见[官方云服务接入](./OfficialServerAccess.md)。 +::: + --- ## 重启并测试 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md index 3a3a4b4b..1f4f769b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md @@ -6,17 +6,29 @@ ## 第 1 步：安装技能库 +### 一键自动安装 + 只需告诉你的 AI Agent 执行以下命令： +```bash +npx skills add https://github.com/BofAI/skills -y -g +``` + +`-y` 参数会跳过所有交互选择，默认安装所有 Skills；`-g` 参数表示全局安装（所有项目都可使用）。安装完成后会显示 ✅ 全局安装完成！以及安装的所有 Skills 列表。 + +### 交互式安装 + +如果你想手动选择安装哪些 Skills 以及安装范围，去掉 `-y -g` 参数即可： + ```bash npx skills add https://github.com/BofAI/skills ``` :::tip 提示 -本文档以在终端中运行命令为例展示安装过程。如果你想在终端中手动安装，打开你电脑上的"终端"（按 `Command + 空格`，输入 `Terminal`，按回车），将上面的命令粘贴进去并回车即可。 +本文档以在终端中运行命令为例展示安装过程。 ::: -### 安装过程详解 +#### 安装过程详解 安装器会引导你完成以下几步，照着做就行： From 684fd9d4067048c6d113ba1214026fc2d36418fb Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 24 Mar 2026 18:54:15 +0800 Subject: [PATCH 44/44] config to install --- docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md | 2 +- .../current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index e44c3643..75702bfe 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -21,7 +21,7 @@ node --version # should output v20.x.x or higher --- -## Add Configuration +## Install Simply tell your AI Agent to execute the following command: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md index f8940266..4f7fe27f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -21,7 +21,7 @@ node --version # 应输出 v20.x.x 或更高 --- -## 添加配置 +## 安装 只需告诉你的 AI Agent 执行以下命令：