luckee-skill（幸运技能）

Luckee Skill

What is Luckee AI

Luckee AI is a cross-border e-commerce intelligent assistant built for Amazon sellers. It combines Amazon advertising optimization with general business intelligence analysis, powered by advanced AI technology.

Core capabilities

Amazon Advertising

• Ad Diagnosis — Campaign health checks, keyword performance analysis, ad placement efficiency (TOS/ROS/PP), ACOS/ROAS breakdown, campaign structure diagnosis, and diagnostic validation.
• Keyword Research — ASIN/category-based keyword collection, search term report analysis, keyword classification and tagging, CVR estimation, negative keyword suggestions, and word-root clustering.
• Ad Strategy — Bid recommendations, budget allocation analysis, campaign strategy generation, portfolio analysis, new product launch ad strategies, and period-over-period comparison.
• Competitor Analysis — Competitor basic info (price, rating, reviews, BSR), competitor keyword analysis, multi-ASIN comparison, listing analysis, review sentiment extraction, and category landscape mapping.
• Data & Reports — Store data retrieval via API, product/ASIN details, campaign/keyword data pulls, structured diagnostic reports, weekly/monthly summaries, and data visualization.

General Research & Analysis

• Link & Web Analysis — Amazon listing parsing, analysis of any webpage (1688, AliExpress, standalone sites), and web search for industry trends.
• File & Data Analysis — Excel/CSV analysis (sales, inventory, financials), PDF document interpretation (supplier quotes, contracts, manuals), and image recognition (screenshots, product images, design drafts).
• Content Generation — Listing optimization (title, bullet points, description), copywriting (A+ content, ad copy, emails), and multi-language translation & localization.

Pre-flight

Before doing anything, check whether the plugin is already installed:

openclaw plugins list

If luckee-tool appears and shows as enabled, skip straight to Usage. Otherwise, follow Install below.

Install

Before installing, ask the user for confirmation: explain that the plugin will be cloned from its GitHub repository and registered with OpenClaw.

Note: openclaw plugins install does not accept GitHub URLs directly — only npm specs, local directories, or archives are supported. You must clone the repo first, then install from the local path.

1. Clone or update the plugin repository

If the plugin has not been cloned yet:

git clone https://github.com/motse-ai/luckee-openclaw-plugin.git /tmp/luckee-openclaw-plugin

If the plugin directory already exists, pull the latest changes:

cd /tmp/luckee-openclaw-plugin && git checkout main && git pull --ff-only origin main && cd -

2. Install the plugin from the local directory

openclaw plugins install /tmp/luckee-openclaw-plugin

This registers the plugin with OpenClaw and installs its dependencies.

3. Verify and configure the luckee CLI binary path

After install, luckee-cli (the Python package) may have been placed in a directory that is not on the gateway process's PATH (e.g. ~/.local/bin). The plugin should use the luckee binary by default, so you must locate the actual binary and set binaryPath explicitly if needed:

# Find where the binary was installed
which luckee 2>/dev/null || which luckee-cli 2>/dev/null || python3 -c "import sysconfig; print(sysconfig.get_path('scripts', sysconfig.get_preferred_scheme('user')))" 2>/dev/null

Check the discovered directory (e.g. /home/node/.local/bin/) for a file named luckee or luckee-cli. Then set the full path:

openclaw config set plugins.entries.luckee-tool.config.binaryPath "/full/path/to/luckee"

Why: pip often installs scripts into ~/.local/bin/ which many environments (containers, systemd services, SSH sessions) do not include in PATH. Setting binaryPath makes the plugin find the binary regardless of PATH.

4. Authenticate with Luckee

Run:

luckee login

This command opens a browser auth page. Ask the user to complete authorization in the web page, then continue in terminal once login finishes. Running regular luckee commands also checks login status and will prompt the same web authorization flow if the user is not logged in.

No browser access (remote machine, headless server, SSH session, etc.): If the environment cannot open a browser — for example, a remote server, a container, or an SSH session — the luckee login command will still print an authorization URL to stdout. You must copy the full URL from the terminal output and present it to the user so they can open it in their own browser. Do not attempt to launch a browser in these environments.

5. Restart and verify

openclaw gateway restart
openclaw plugins info luckee-tool
openclaw health

Confirm the plugin shows as loaded and the gateway is healthy. Do not ask the user for API URL or User ID details.

Usage

Skill command

/luckee <query>

Example: /luckee 查一下 asin B0DPJMTH4N 的信息 用skills

Stop a running query

/luckee stop

Set a token

/luckee token <token>

Set a token and run a query in one go:

/luckee token sk_xxx 查一下 asin B0DPJMTH4N 的信息

AI tool invocation

Call the luckee_query tool with:

{
  "query": "查一下 asin B0DPJMTH4N 的信息 用skills",
  "token": "sk_optional_override",
  "language": "CN",
  "timeout": 90
}

Only query is required. For /luckee token ..., first call luckee_set_token, then call luckee_query if a query was included. Auth context is handled by CLI/session state or the auto-login prompt triggered by luckee_query.

Token Management

• Tokens are managed securely by OpenClaw and persisted across gateway restarts.
• Set a per-user token via /luckee token <token> (overrides the default for that sender).
• Set a default token via config: openclaw config set plugins.entries.luckee-tool.config.defaultToken "<token>".
• See reference.md for advanced token store details.

Troubleshooting

Binary not found

This is the most common issue. Even when luckee-cli is installed, the gateway process may not find it because pip installs scripts to a directory not in PATH (e.g. ~/.local/bin/).

Step 1 — Locate the binary:

which luckee 2>/dev/null || which luckee-cli 2>/dev/null

If that returns nothing, check common pip script directories:

ls ~/.local/bin/luckee* 2>/dev/null
python3 -c "import sysconfig; print(sysconfig.get_path('scripts', sysconfig.get_preferred_scheme('user')))" 2>/dev/null

Step 2 — If not installed, install it:

python -m pip install --upgrade 'luckee-cli>=0.1.0'

Then re-run Step 1 to find where it was placed.

Step 3 — Set the path explicitly and restart:

openclaw config set plugins.entries.luckee-tool.config.binaryPath "/full/path/to/luckee"
openclaw gateway restart

Important: Always set binaryPath after installing luckee-cli. Do not rely on PATH resolution alone, as the gateway process environment often differs from the interactive shell.

Not logged in / auth expired

If queries fail with auth/login errors:

Option 1 — Direct terminal login (preferred when you have terminal access):

luckee login

Complete authorization in the browser, then retry the query. If running on a remote machine or headless environment where a browser cannot be opened, copy the full authorization URL printed in the terminal output and present it to the user to open manually.

Option 2 — Set token via chat (when OAuth can't work, e.g. running inside gateway):

/luckee token <your_token>

Option 3 — Set token via config:

openclaw config set plugins.entries.luckee-tool.config.defaultToken "<your_token>"

Note: /luckee <query> is available as a native plugin slash command. If the command is not available on a given surface, the agent can still fall back to luckee_query. If auth is missing, the plugin will surface login or token instructions automatically.

Timeout

Increase the default timeout (seconds):

openclaw config set plugins.entries.luckee-tool.config.defaultTimeout 180

Plugin ID mismatch warning

If you see "plugin id mismatch (manifest uses luckee-tool, entry hints luckee-openclaw-plugin)":

openclaw config unset plugins.entries.luckee-openclaw-plugin
openclaw gateway restart

Safety Rules

• Never log or display full tokens. Always redact to sk_x***xx format.
• All install/config operations are idempotent — safe to re-run.
• Do not overwrite unrelated config keys when setting luckee-tool config.
• Never request API URL or User ID from users during normal setup/query flows.

Reference

For detailed config schema, channel list, token store format, and error catalog, see reference.md.