ZL-ClawPay

Use when users need to query sub-wallet binding status, bind sub-wallet, generate QR code, check payment status, query balance or transaction history. Trigge...

Security Scan

The skill is broadly consistent with a payment/wallet integration (it legitimately needs crypto keys and networking), but there are multiple internal inconsistencies and persistence behaviors that don't match its documentation and manifest — you should review endpoints, shipped .env, and state handling before installing.

Purpose & Capability

The name/description (wallet/payment operations) aligns with the code: many modules implement SM2/SM4 (GM) crypto, HMAC signing, secure client, wallet/payment services and HTTP/local interfaces. Requesting an app id and client private key + server public key is reasonable for a payment SDK. However, registry summary at the top of the report said "Required env vars: none" while the skill's SKILL.md and _meta.json clearly require ZLPAY_APP_ID and GM key material — this metadata mismatch is an incoherence to be aware of.

Instruction Scope

SKILL.md instructs the LLM to call the local CLI wrapper (scripts/skill.py) and to consult local reference docs; that is consistent with included CLI code. But SKILL.md also claims a "stateless design" (each call spawns a new process) while the code contains a StateStore, SessionManager and Memory classes and has state retention and cleanup logic — the skill appears to persist wallet IDs/state to disk. The doc mandates never showing credentials, yet the code logs request/response info (with masking filters). The existence of log files, a configurable log directory and a state file means sensitive data could be persisted if masking or configuration is misused.

Install Mechanism

There is no remote 'download-and-extract' installer; an included setup.sh creates a venv and pip-installs pinned packages in requirements.txt. Packages are standard PyPI libraries (requests, gmssl, cryptography, qrcode, etc.) — this is expected for crypto and QR functionality. The install script itself does not fetch code from arbitrary hosts, but it will install many third-party packages (moderate-risk: supply-chain considerations).

Credentials

The required environment variables declared in SKILL.md and _meta.json (ZLPAY_APP_ID, ZLPAY_GM_CLIENT_PRIVATE_KEY or path, ZLPAY_GM_SERVER_PUBLIC_KEY or path) are appropriate for a crypto-based payment skill. However: (1) the top-level registry metadata in this report incorrectly shows no required env vars — a mismatch; (2) the package includes a config/.env file in the bundle (config/.env), which may contain secrets or default keys shipped with the skill — shipping credential files packaged with a skill is a security concern and not justified by normal usage. The skill also uses optional ZLPAY_API_KEY and other envs; ensure only necessary secrets are provided and that any shipped .env is inspected/removed.

Persistence & Privilege

SKILL.md's 'stateless' claim conflicts with code that instantiates StateStore/SessionManager and a Memory component and has log retention and state retention configuration. The skill will write logs and state files (log_dir, state_file_path) locally; it is not marked always:true, but it does persist data on disk. If you expect no local persistence, this is an inconsistency to address. Also, while logging uses a filter to mask secrets, masked data may still be partially recorded and retention/rotation must be reviewed.

What to consider before installing

What to check before installing/using this skill: 1) Metadata mismatch: The report header shows no required env vars but SKILL.md/_meta.json require ZLPAY_APP_ID and GM key material — assume the skill needs those secrets. Do not pass keys until you audit the code. 2) Inspect config/.env: The package includes config/.env. Open it before installation; if it contains real keys or default credentials, remove or replace them. Never use credentials found inside a shipped .env without rotation. 3) Review Config for endpoints: Find scripts/zlpay_skill/config/config.py (or where SecureClient sets base URL). Confirm the backend host(s) the skill will contact. If endpoints point to unknown or external servers you don't control, treat it as high risk. 4) Local persistence: The code contains StateStore/Memory and logging with retention. If you need ephemeral operation, either run this skill in an isolated environment (container/VM) or modify the code/config to disable state/log retention or redirect to a secure path. 5) Confirm payment flow enforcement: SKILL.md requires explicit yes/no confirmation before payments. Verify the business methods actually enforce this (i.e., the CLI/library will not auto-execute payments when invoked by an agent). If the LLM can invoke the skill autonomously, ensure policy or operator approval is in place. 6) Secrets handling: The skill expects the client private key (sensitive). Prefer providing keys via secure secret manager or mounted files (paths) rather than embedding in environment on a shared machine. If you must put keys on disk, set strict filesystem permissions and consider hardware-backed keys. 7) Dependency review: The setup installs many third-party packages (cryptography, gmssl, sm-crypto). Verify you trust these package versions and consider using a vetted internal mirror or doing an SBOM/audit of dependencies. 8) Run in sandbox first: Execute the skill in an isolated environment, exercising non-sensitive operations (query binding, listing interfaces) and monitor network traffic to confirm it contacts only expected hosts and that no unexpected outbound data (e.g., entire .env contents) is transmitted. If you want, provide the contents of scripts/zlpay_skill/config/config.py and core/secure_client.py (or the base URL and where public keys are fetched) and I can do a more precise review of network endpoints and any code paths that may exfiltrate data.

ZL Claw Pay Skill

ZL Pay Skill provides sub-wallet management, payment collection, and Token payment functions, building a dual-track payment system of "Fiat + Token".

Key Protocols

1. Never expose credentials: Do not display API Key, Wallet ID or any sensitive information in chat responses.
2. Explicit confirmation: Must ask for "yes/no" confirmation before executing payments. Format: "I am about to send [amount] sat to [recipient/note]. Continue? (y/n)"
3. Check balance first: Verify balance before payment to prevent errors.
4. Always include QR code: When generating QR code: (a) display QR image, (b) output MEDIA: + qr_file path on same line. Never skip.

Execution Mode: LLM Driven

This Skill uses LLM-driven mode. The agent interacts with backend via command-line calls to skill.py.

Core Principles

• Stateless design: Each call starts a new process, exits immediately after execution
• Agent manages context: Session memory managed by agent, not dependent on local state
• Command-line driven: Execute all operations via skill.py commands
• Dual command support: call for HTTP APIs and local interfaces

Command Format

# Unified calling method
python {baseDir}/scripts/skill.py call -interfaceId=<INTERFACE_ID> [--param1=value1] ...

Command Design Principles:

• Unified command: call for all interface calls (HTTP and local)
• Parameter passthrough: Control params via -key=value, data params via --key=value
• Auto authentication: Python code handles GM SM2/SM4 encryption and signing automatically
• Interface code: All calls must pass -interfaceId parameter

Interface Types

Type	Code	Command	Description
HTTP API	C prefix	call	Requires network request to backend
Local Interface	L prefix	call	Direct local storage operation

Documentation Guide

When processing user requests, consult documents in this order:

1. Consult references\api-spec.md: Get interface codes, trigger keywords, guidance phrases, request/response parameters
2. Consult assets\request-examples.md: Get command-line calling examples
3. Execute command: Construct and execute commands according to documentation

CLI Command Examples

Local Interface (Query Binding Status):

python {baseDir}/scripts/skill.py call -interfaceId=L00001

HTTP API (Generate QR Code):

python {baseDir}/scripts/skill.py call -interfaceId=C00004 --amount=100

More examples in assets\request-examples.md.

---

Trigger Conditions

Activate when users need to handle payment-related business:

• Query binding status: User asks "Have I bound my wallet", "Query sub-wallet"
• Bind sub-wallet: User says "Bind wallet", "Open account", "Create wallet"
• Collect payment: User says "Generate QR code", "Collect money", "Receive payment"
• Query payment status: User asks "Payment successful", "Check order status"
• Query balance: User says "Check balance", "How much money left"
• Query transactions: User says "Transaction records", "Bill", "Collection details"

Not applicable for: non-payment scenarios, batch operations, historical data export.

---

Execution Steps

1. Consult interface documentation: Based on user intent, consult references\api-spec.md for interface codes and parameters
2. Consult calling examples: Get command format from assets\request-examples.md
3. Construct command: Use call command:
   • Local interface (L prefix): call -interfaceId=L00001
   • HTTP interface (C prefix): call -interfaceId=C00003
4. Execute command: Run the constructed command
5. Parse response: Process JSON response, extract success, data, _seq_id fields
6. Generate reply: Create user-friendly response based on result

---

Output Format

Success Response:

 [Operation success description]
[Related business data display]

Failure Response:

 [Error description]
[Suggested action]

QR Code Response (Must include):

Please scan the QR code to complete [amount] collection:

MEDIA:[QR code file path]

---

Security Protocols

1. Never expose credentials: Do not display API Key, Wallet ID or sensitive info
2. Explicit confirmation: Must ask "yes/no" confirmation before payment
3. Pre-payment confirmation format: "I am about to [operation description]. Continue? (y/n)"
4. Sensitive info management: All sensitive info managed by OpenClaw Memory system

Detailed security specs in "Sensitive Information Management" section of references\api-spec.md.

---

Business Scenarios and Interface Mapping

Scenario	Interface Code	Reference Document
Query binding status	L00001	references\api-spec.md
Bind sub-wallet	C00003	references\api-spec.md
Generate QR code	C00004	references\api-spec.md
Query payment status	C00005	references\api-spec.md
Query balance	C00006	references\api-spec.md

---

Document Index

Document	Content
references\api-spec.md	Interface list, trigger keywords, guidance phrases, request/response parameters
assets\request-examples.md	Command-line calling examples

---

Account System

Account Types

• ** Host Wallet**: Payment account, supports deposit, withdrawal, trading, settlement
• ** Sub-wallet**: Collection account, funds aggregated to host wallet
• ** Token Account**: Lobster ecosystem account for in-ecosystem transactions

Usage Scenarios

• Full form: Sub-wallet + Token account, supports full-featured payments
• Traditional e-commerce: Sub-wallet only, fiat collection and settlement
• Pure AI compute: Token account only, in-ecosystem consumption and settlement

---

Security Notes

Transport Security

• Mandatory HTTPS/TLS 1.3 encryption
• GM SM2/SM4: Request body encrypted with SM4, key encrypted with SM2
• SM2 digital signature: Request and response use SM2 signature verification
• Anti-replay: Timestamp + Nonce
• Response verification: Verify server SM2 signature

Credential Management

API Key

• Source: Multiple input methods (in priority order):
  1. Command line argument: -api-key=xxx
  2. Request body parameter: api_key (e.g., bind_sub_wallet)
  3. Environment variable: ZLPAY_API_KEY
  4. Memory storage: saved after successful bind_sub_wallet
• Storage: Optionally saved to memory after bind_sub_wallet, not written to config files
• Display: Never show full API Key in conversation, only show first 8 and last 4 digits
• Security: Use IronClaw Data Guard to check output, prevent credential leakage

Wallet ID

• Source: Provided by user during chat interaction
• Storage: Saved to local state file (~/.zlpay/state.json)
• Usage: Auto-retrieved from state file on subsequent API calls
• Display: Never show full wallet ID in chat (mask as wallet_****5678)

Configuration Parameters (GM Keys, App ID, API URL, Encryption)

• Source: Configured in config/.env file
• Required: ZLPAY_APP_ID, ZLPAY_GM_CLIENT_PRIVATE_KEY, ZLPAY_GM_SERVER_PUBLIC_KEY, ZLPAY_API_URL
• Optional: ZLPAY_GM_ENABLE_ENCRYPTION (default: true)
• Alternative: Can use file paths (*_PATH variants) for key files with 600 permissions
• Security: Keys are only used for request signing/verification, never transmitted over network

Data Masking

Sensitive info in responses is automatically masked:

• Phone: 138****8000
• ID Number: 110101********1234

---

Configuration

All settings are stored in config/.env:

• Required: ZLPAY_APP_ID, ZLPAY_GM_CLIENT_PRIVATE_KEY, ZLPAY_GM_SERVER_PUBLIC_KEY
• Optional: ZLPAY_API_URL, ZLPAY_LOG_LEVEL

API Key: User provides during chat (stored in OpenClaw Memory, not in config file)

Local Files: Creates ~/.zlpay/ directory for state storage and logs (user-only permissions).